Skip to content

Home

Jump to bottom
zifnab69 edited this page May 9, 2026 · 29 revisions

🇫🇷 French below — Version française plus bas

MESHTASTIC CONFIG MANAGER v1.1 User and Technical Documentation — Wiki

PRESENTATION

Meshtastic Config Manager is a Python graphical tool (Tkinter) that allows you to back up, restore, and deploy the complete configuration of Meshtastic devices via a USB/serial connection.

It is intended for administrators of Meshtastic node fleets who want to manage their configurations in a reproducible, secure way without needing to use the command line.

Author : zinfab69_fr@yahoo.fr Version : 1.2 Language : Python 3.10+ Interface: Tkinter (native Windows/Linux/macOS GUI) Format : Standalone EXE (PyInstaller) or direct Python script

I’m not a software developer by training. This tool was built with the help of an AI and a lot of work on my side to design, test, and refine it. If you’re a developer and would like to contribute, any help to keep this project alive and evolving is greatly appreciated.

alt

PREREQUISITES

Required software:

  • Python 3.10 or higher
  • meshtastic (pip install meshtastic)
  • pyserial (pip install pyserial)
  • protobuf (pip install protobuf)

Hardware:

  • Meshtastic device with firmware 2.x minimum
  • USB data cable (not a charge‑only cable)
  • Available COM port (COM1 is automatically excluded — Windows system port)

Installation from source: pip install meshtastic pyserial protobuf python meshtastic_config_manager_v1.1.py

Installation from EXE: Run meshtastic_config_manager_v1.1.exe directly No Python installation required. USER INTERFACE

The interface is organized in two main tabs:

  • “Main” tab: all management operations
  • “Help” tab: built‑in usage guide

alt

COM port selection

  • The list of COM ports is detected automatically at startup
  • COM1 is systematically excluded (Windows system port, never a USB device)
  • The first available port is pre‑selected
  • Click “Detect ports” to refresh the list
  • Leaving the field empty = automatic scan of all ports

alt

Working directory

  • Default: application folder
  • “Choose folder” button to change the location
  • “Open folder” button to open Windows Explorer

File list

alt

Displays all JSON files in the working directory with:

  • File name
  • Export date
  • Source device (long_name)
  • Type (full backup or fleet profile)
  • LoRa region
  • Modem preset[^1]

Buttons available for the selected file:

  • Refresh : reload the list
  • View content : display formatted JSON
  • Edit key fields : modify essential fields (region, modem, owner)
  • Copy file : copy the JSON file to another folder
  • Delete : delete the file
  • Choose another file : browse folders to select a JSON

EXPORT (READING FROM DEVICE)

Full config export

  1. Plug in the device and select the COM port
  2. Click “EXPORT FULL CONFIG → JSON”
  3. The device is read first
  4. A save dialog opens with an automatically suggested name File name format: meshtastic_NAME_XXXX_YYYYMMDD_HHMMSS.json where NAME = device short_name, XXXX = last 4 hex of MAC address Example: meshtastic_JMC_5F7B_20260509_095500.json
  5. The JSON file is saved in the working directory

Multi‑node export (sequential)

Lets you export several devices one after another without restarting the tool.

  1. Click “Multi‑node export (sequential)”
  2. A dialog opens for each node:
    • Select the device’s COM port (COM1 automatically excluded)
    • “Detect” button to refresh the port list
    • Click “Export this node”
  3. The device is read, then a save dialog opens with an automatically suggested file name (short_name + hex MAC)
  4. Click “Skip” to skip a node
  5. Click “Finish” to end the session

CONTENT OF THE EXPORTED JSON FILE

The JSON file contains the following sections:

_export_date : export date/time _app_version : software version _schema_version : JSON schema version

owner : device information long_name : long name (e.g. “Jean‑Marc”) short_name : short name + hex MAC (e.g. “JMC_5F7B”) hw_model : hardware model (e.g. “TLORA_V2_1_1P6”)

local_config : full local configuration lora : radio parameters (region, modem preset, frequency, etc.) bluetooth : BT enabled/disabled, PIN, mode network : WiFi SSID/PSK, NTP, Ethernet display : brightness, sleep, rotation position : GPS, smart position, broadcast power : power, sleep, charging device : device mode, role, debug security : public key, private key, admin_key, flags

module_config : software modules mqtt, serial, range_test, telemetry, cannedmessage, audio, remotehardware, neighborinfo, ambientlighting, detectionsensor, paxcounter[^1]

channels : communication channels (0 to 7) index : channel number (0 = primary) settings.name : channel name settings.psk : AES‑256 encryption key (32‑byte hex) or “01” (default) settings.module_settings.position_precision : shared GPS precision role : 1=PRIMARY, 2=SECONDARY, 0=DISABLED

known_nodes : list of known mesh nodes

my_info : raw local node information metadata : firmware metadata

FLEET PROFILE

The fleet profile is a stripped‑down version of a configuration, deployable on any node in the fleet.

Elements removed from the fleet profile:

  • owner (long_name, short_name, hw_model)
  • security.public_key and security.private_key (each node must keep its own unique key pair)
  • network.wifi_ssid and network.wifi_psk
  • my_info, metadata, known_nodes
  • Internal version counters

Elements kept:

  • security.admin_key (shared across the fleet)
  • All LoRa configuration (region, preset, frequency, etc.)
  • All channels with their PSK keys
  • Modules, display, BT, position, power, device

Generation:

  1. Select a backup file in the list
  2. Click “GENERATE FLEET PROFILE”
  3. The file is saved with the _fleet.json suffix

RESTORE (WRITING TO DEVICE)

Single restore

  1. Select the JSON file in the list
  2. Plug in the device and check the COM port
  3. Click “RESTORE selected file → Device”
  4. A confirmation appears showing: file name, type, date, source device
  5. Restore runs section by section
  6. A detailed log is displayed at the end
  7. Restart the device to apply changes

Multi‑node import (serial deployment)

Deploys the same JSON file to several devices in succession. Uses the file selected in the list (same as single restore).

  1. Select the JSON file in the list
  2. Click “Multi‑node import”
  3. For each device:
    • Plug in the device
    • Select its COM port (COM1 automatically excluded)
    • Click “Restore this node”
  4. Click “Skip” to skip a node
  5. Click “Finish” when all nodes are processed
  6. Restart each device to apply changes

Fleet profile note: private_key and public_key are not restored (they are absent from the profile), each node keeps its own keys. The shared admin_key is restored on all nodes.

INTEGRITY CHECK

Before any restore, the file is automatically checked:

  • Presence of sections local_config and local_config.lora
  • Presence of the channels section
  • Consistency of the LoRa config (region, modem_preset)

If a problem is detected, a warning is displayed. The user can cancel or force the restore despite the warning.

CHANNEL RESTORE

Channels are restored in this order:

  1. Secondary channels (role=2) first
  2. Primary channel (role=1) last

This order matters: writing the primary channel last prevents the firmware from resetting its configuration when writing subsequent channels.

For each channel, the following are restored:

  • Channel name
  • Role (PRIMARY / SECONDARY / DISABLED)
  • PSK key (AES‑256, 32 bytes) — guaranteed full restore
  • module_settings (position_precision, is_muted)

The PSK is stored in hexadecimal in the JSON and converted to bytes during restore. The value “01” corresponds to the Meshtastic default key (unencrypted channel with a known public key).

SECURITY KEY RESTORE

public_key : restored from a full backup private_key : restored from a full backup (absent from fleet profiles — each node has its own pair) admin_key : always restored (backup AND fleet profile)

The keys allow remote administration of the device. A full backup allows a complete restore including remote administration capability.

EDITING KEY FIELDS

The “Edit key fields” button (between “View content” and “Copy file”) lets you modify essential fields of a JSON file without an external editor:

  • Long name (long_name)
  • Short name (short_name)
  • LoRa region
  • Modem preset
  • Channels (names)

Changes are saved directly into the selected JSON file.

FILE NAMING

Exported files follow this automatic format: meshtastic_[short_name][YYYYMMDD][HHMMSS].json

Example: meshtastic_JMC_5F7B_20260509_095500.json

The short_name includes the last four hexadecimal characters of the device MAC address, which lets you uniquely identify each node even if two devices share the same user short_name.

If retrieving the name fails, the fallback format is: meshtastic_backup_[YYYYMMDD]_[HHMMSS].json

BEHAVIOR WHEN A JSON FIELD IS MISSING

If a key is missing from the JSON (for example adc_multiplier removed manually), the value present on the device remains unchanged during restore. This is the standard behavior of the protobuf protocol: missing fields are not reset to zero.

Warning: a field present with the default value of the type (0, false, “”) can in some cases be ignored by protobuf — deleting the line is safer to preserve an existing value.

BUILDING THE EXECUTABLE

pyinstaller --onefile --windowed meshtastic_config_manager_v1.1.py

The EXE generated in dist/ is standalone and does not require Python to be installed. Typical size: 30 to 60 MB depending on bundled dependencies.

TROUBLESHOOTING

No COM port detected → Check the USB cable (data cable, not charge‑only) → Check CH340/CP2102/FTDI drivers depending on model → Leave the port field empty for automatic scan

owner section empty in JSON → Wait 2–3 seconds after plugging in before exporting → Firmware may take a few seconds to initialize node info

A channel’s PSK is “01” after restore → Check that the JSON file actually contains a 32‑byte PSK (64 hex chars) → Write secondary channels before the primary one — handled automatically in v1.1

hw_model empty → Firmware too old (< 2.3) or model not recognized in protobuf enum → No functional impact

“Cannot import protobuf” error → pip install --upgrade protobuf meshtastic

CHANGELOG

v1.2 (May 2026)

  • Added “Help” tab in the interface
  • Export: device is read before selecting destination file
  • Automatic file naming with short_name + 4 hex MAC
  • Multi‑node export with per‑node port selection, COM1 excluded
  • Multi‑node import: uses the file selected in the UI
  • COM1 automatically excluded from all port lists
  • Automatic port detection at startup
  • Full restore of channel PSK keys (bug fixed)
  • Channel restore order: secondary first, primary last
  • Restore of module_settings (position_precision, is_muted)
  • Full restore of security keys (including private_key)
  • Fleet profile: public_key AND private_key removed (admin_key kept)
  • hw_model converted from protobuf enum to readable name
  • short_name completed with last 4 hex of MAC address
  • “Edit key fields” button moved into the file toolbar
  • “Multi‑node export” button activated (previously dead code)
  • owner section: 5 successive fallback methods for retrieval

v1.0 (initial)

  • Full configuration export/import
  • Fleet profile generation
  • Integrity validation
  • Key‑field editor
  • JSON file viewing and management

MESHTASTIC CONFIG MANAGER v1.2 Wiki — Documentation utilisateur et technique

PRÉSENTATION

Meshtastic Config Manager est un outil graphique Python (Tkinter) permettant de sauvegarder, restaurer et déployer la configuration complète d'appareils Meshtastic via liaison USB/série.

Il s'adresse aux administrateurs de flottes de nœuds Meshtastic souhaitant gérer leurs configurations de manière reproductible, sécurisée et sans nécessiter de ligne de commande.

Auteur : Zifnab69_fr@yahoo.fr Version : 1.2 Langage : Python 3.10+ Interface: Tkinter (GUI native Windows/Linux/macOS) Format : EXE autonome (PyInstaller) ou script Python direct

Je ne suis absolument pas développeur de formation. Ce logiciel a été conçu avec l’aide d’une IA et beaucoup d’efforts de ma part pour le penser, le tester et l’améliorer. Si vous êtes développeur et que vous souhaitez contribuer, toute aide sera la bienvenue pour faire vivre et progresser ce projet.

alt

PRÉREQUIS

Logiciels requis :

  • Python 3.10 ou supérieur
  • meshtastic (pip install meshtastic)
  • pyserial (pip install pyserial)
  • protobuf (pip install protobuf)

Matériel :

  • Appareil Meshtastic avec firmware 2.x minimum
  • Câble USB data (pas un câble charge seul)
  • Port COM disponible (COM1 est automatiquement exclu — port système Windows)

Installation depuis le source : pip install meshtastic pyserial protobuf python meshtastic_config_manager_v1.1.py

Installation depuis l'EXE : Lancer directement meshtastic_config_manager_v1.1.exe Aucune installation Python requise.

INTERFACE UTILISATEUR

L'interface est organisée en deux onglets principaux :

  • Onglet "Principal" : toutes les opérations de gestion
  • Onglet "Aide" : guide d'utilisation intégré

alt

Sélection du port COM

  • La liste des ports COM est détectée automatiquement au démarrage
  • COM1 est systématiquement exclu (port système Windows, jamais un appareil USB)
  • Le premier port disponible est pré-sélectionné
  • Cliquer "Détecter ports" pour actualiser la liste
  • Laisser le champ vide = scan automatique de tous les ports

alt

Dossier de travail

  • Par défaut : dossier de l'application
  • Bouton "Choisir dossier" pour changer l'emplacement
  • Bouton "Ouvrir dossier" pour ouvrir l'explorateur Windows

Liste des fichiers

Affiche tous les fichiers JSON du dossier de travail avec : - Nom du fichier - Date d'export - Appareil source (long_name) - Type (backup complet ou profil flotte) - Région LoRa - Preset modem

alt

Boutons disponibles sur le fichier sélectionné : - Actualiser : recharger la liste - Voir contenu : afficher le JSON formaté - Éditer champs clés : modifier les champs essentiels (région, modem, owner) - Copier fichier : copier le fichier JSON dans un autre dossier - Supprimer : supprimer le fichier - Choisir un autre fichier : parcourir les dossiers pour sélectionner un JSON

EXPORT (LECTURE DEPUIS L'APPAREIL)

Export config complète

  1. Brancher l'appareil et sélectionner le port COM
  2. Cliquer "EXPORTER CONFIG COMPLÈTE → JSON"
  3. L'appareil est lu en premier
  4. Une boîte de sauvegarde s'ouvre avec un nom suggéré automatiquement Format du nom : meshtastic_NOM_XXXX_YYYYMMDD_HHMMSS.json où NOM = short_name de l'appareil, XXXX = 4 derniers hex de l'adresse MAC Exemple : meshtastic_JMC_5F7B_20260509_095500.json
  5. Le fichier JSON est sauvegardé dans le dossier de travail

Export multi-nœuds (séquentiel)

Permet d'exporter plusieurs appareils l'un après l'autre sans redémarrer l'outil.

  1. Cliquer "Export multi-nœuds (séquentiel)"
  2. Une boîte de dialogue s'ouvre pour chaque nœud :
    • Sélectionner le port COM de l'appareil (COM1 exclu automatiquement)
    • Bouton "Détecter" pour rafraîchir la liste des ports
    • Cliquer "Exporter ce nœud"
  3. L'appareil est lu, puis une boîte de sauvegarde s'ouvre avec le nom de fichier suggéré automatiquement (short_name + hex MAC)
  4. Cliquer "Passer" pour sauter un nœud
  5. Cliquer "Terminer" pour clore la session

CONTENU DU FICHIER JSON EXPORTÉ

alt Le fichier JSON contient les sections suivantes :

_export_date : date/heure de l'export _app_version : version du logiciel _schema_version : version du schéma JSON

owner : informations sur l'appareil long_name : nom long (ex: "Jean-Marc") short_name : nom court + hex MAC (ex: "JMC_5F7B") hw_model : modèle matériel (ex: "TLORA_V2_1_1P6")

local_config : configuration locale complète lora : paramètres radio (région, modem preset, fréquence...) bluetooth : BT activé/désactivé, PIN, mode network : WiFi SSID/PSK, NTP, Ethernet display : luminosité, veille, rotation position : GPS, smart position, broadcast power : alimentation, sleep, charge device : mode appareil, rôle, debug security : clé publique, clé privée, admin_key, flags

module_config : modules logiciels mqtt, serial, range_test, telemetry, cannedmessage, audio, remotehardware, neighborinfo, ambientlighting, detectionsensor, paxcounter

channels : canaux de communication (0 à 7) index : numéro du canal (0 = primaire) settings.name : nom du canal settings.psk : clé de chiffrement AES-256 (hex 32 octets) ou "01" (défaut) settings.module_settings.position_precision : précision GPS partagée role : 1=PRIMARY, 2=SECONDARY, 0=DISABLED

known_nodes : liste des nœuds connus du réseau mesh

my_info : informations brutes du nœud local metadata : métadonnées firmware

PROFIL FLOTTE

Le profil flotte est une version épurée d'une configuration, déployable sur n'importe quel nœud de la flotte.

Éléments supprimés du profil flotte :

  • owner (long_name, short_name, hw_model)
  • security.public_key et security.private_key (chaque nœud doit conserver ses propres clés uniques)
  • network.wifi_ssid et network.wifi_psk
  • my_info, metadata, known_nodes
  • Compteurs de version internes

Éléments conservés :

  • security.admin_key (commune à toute la flotte)
  • Toute la configuration LoRa (région, preset, fréquence...)
  • Tous les canaux avec leurs clés PSK
  • Modules, display, BT, position, power, device

Génération :

  1. Sélectionner un fichier backup dans la liste
  2. Cliquer "GÉNÉRER PROFIL FLOTTE"
  3. Le fichier est sauvegardé avec le suffixe _fleet.json

RESTAURATION (ÉCRITURE VERS L'APPAREIL)

Restauration unique

  1. Sélectionner le fichier JSON dans la liste
  2. Brancher l'appareil et vérifier le port COM
  3. Cliquer "RESTAURER le fichier sélectionné → Appareil"
  4. Une confirmation s'affiche avec : nom du fichier, type, date, appareil source
  5. La restauration s'effectue section par section
  6. Un log détaillé s'affiche à la fin
  7. Redémarrer l'appareil pour appliquer les changements

Import multi-nœuds (déploiement en série)

Déploie le même fichier JSON sur plusieurs appareils successivement. Utilise le fichier sélectionné dans la liste (identique à la restauration unique).

  1. Sélectionner le fichier JSON dans la liste
  2. Cliquer "Import multi-nœuds"
  3. Pour chaque appareil :
    • Brancher l'appareil
    • Sélectionner son port COM (COM1 exclu automatiquement)
    • Cliquer "Restaurer ce nœud"
  4. Cliquer "Passer" pour sauter un nœud
  5. Cliquer "Terminer" quand tous les nœuds sont traités
  6. Redémarrer chaque appareil pour appliquer

Note profil flotte : les clés private_key et public_key ne sont pas restaurées (absentes du profil), chaque nœud conserve ses propres clés. L'admin_key commune est bien restaurée sur tous les nœuds.

VÉRIFICATION D'INTÉGRITÉ

Avant toute restauration, le fichier est automatiquement vérifié :

  • Présence des sections local_config et local_config.lora
  • Présence de la section channels
  • Cohérence de la config LoRa (région, modem_preset)

En cas de problème détecté, un avertissement s'affiche. L'utilisateur peut annuler ou forcer la restauration malgré l'avertissement.

RESTAURATION DES CANAUX

Les canaux sont restaurés dans cet ordre :

  1. Canaux secondaires (role=2) en premier
  2. Canal primaire (role=1) en dernier

Cet ordre est important : écrire le canal primaire en dernier empêche le firmware de réinitialiser sa configuration lors de l'écriture des canaux suivants.

Pour chaque canal sont restaurés :

  • Nom du canal
  • Rôle (PRIMARY / SECONDARY / DISABLED)
  • Clé PSK (AES-256, 32 octets) — restauration complète garantie
  • module_settings (position_precision, is_muted)

La PSK est stockée en hexadécimal dans le JSON et convertie en bytes lors de la restauration. La valeur "01" correspond à la clé par défaut Meshtastic (canal non chiffré avec clé publique connue).

RESTAURATION DES CLÉS DE SÉCURITÉ

public_key : restaurée depuis un backup complet private_key : restaurée depuis un backup complet (absente des profils flotte — chaque nœud a sa propre paire) admin_key : restaurée dans tous les cas (backup ET profil flotte)

Les clés permettent d'administrer l'appareil à distance. Un backup complet permet une restauration totale y compris la capacité d'administration à distance.

ÉDITION DES CHAMPS CLÉS

Le bouton "Éditer champs clés" (entre "Voir contenu" et "Copier fichier") permet de modifier les champs essentiels d'un fichier JSON sans éditeur externe :

  • Nom long (long_name)
  • Nom court (short_name)
  • Région LoRa
  • Modem preset
  • Canaux (noms)

Les modifications sont sauvegardées directement dans le fichier JSON sélectionné.

NOMMAGE DES FICHIERS

Les fichiers exportés suivent ce format automatique : meshtastic_[short_name][YYYYMMDD][HHMMSS].json

Exemple : meshtastic_JMC_5F7B_20260509_095500.json

Le short_name inclut les 4 derniers caractères hexadécimaux de l'adresse MAC de l'appareil, ce qui permet d'identifier chaque nœud de manière unique, même si deux appareils ont le même short_name utilisateur.

En cas d'échec de récupération du nom, le format de repli est : meshtastic_backup_[YYYYMMDD]_[HHMMSS].json

COMPORTEMENT LORS D'UN CHAMP ABSENT DU JSON

Si une clé est absente du JSON (ex: adc_multiplier supprimé manuellement), la valeur présente dans l'appareil reste inchangée lors de la restauration. C'est le comportement standard du protocole protobuf : les champs absents ne sont pas remis à zéro.

Attention : une valeur présente avec la valeur par défaut du type (0, false, "") peut dans certains cas être ignorée par protobuf — supprimer la ligne est plus sûr pour préserver une valeur existante.

COMPILATION EN EXÉCUTABLE

pyinstaller --onefile --windowed meshtastic_config_manager_v1.1.py

L'EXE généré dans dist/ est autonome et ne nécessite pas Python installé. Taille typique : 30 à 60 Mo selon les dépendances embarquées.

DÉPANNAGE

Aucun port COM détecté → Vérifier le câble USB (cable data, pas charge seule) → Vérifier les pilotes CH340/CP2102/FTDI selon le modèle → Laisser le champ port vide pour un scan automatique

Section owner vide dans le JSON → Attendre 2-3 secondes après branchement avant d'exporter → Le firmware peut mettre quelques secondes à initialiser les infos nœud

La PSK d'un canal est "01" après restauration → Vérifier que le fichier JSON contient bien une PSK de 32 octets (64 hex chars) → Écrire les canaux secondaires avant le primaire — géré automatiquement en v1.1

hw_model vide → Firmware trop ancien (< 2.3) ou modèle non reconnu dans l'enum protobuf → Sans impact fonctionnel

Erreur "Cannot import protobuf" → pip install --upgrade protobuf meshtastic

CHANGELOG

v1.2 (mai 2026)

  • Ajout onglet "Aide" dans l'interface
  • Export : lecture de l'appareil avant sélection du fichier de destination
  • Nommage automatique des fichiers avec short_name + 4 hex MAC
  • Export multi-nœuds avec sélection de port par nœud, COM1 exclu
  • Import multi-nœuds : utilise le fichier sélectionné dans l'UI
  • COM1 automatiquement exclu de toutes les listes de ports
  • Détection automatique des ports au démarrage
  • Restauration complète des clés PSK des canaux (bug corrigé)
  • Ordre de restauration des canaux : secondaires d'abord, primaire en dernier
  • Restauration de module_settings (position_precision, is_muted)
  • Restauration complète des clés de sécurité (private_key incluse)
  • Profil flotte : suppression public_key ET private_key (admin_key conservée)
  • hw_model converti depuis enum protobuf en nom lisible
  • short_name complété avec les 4 derniers hex de l'adresse MAC
  • Bouton "Éditer champs clés" déplacé dans la barre fichiers
  • Activation du bouton "Export multi-nœuds" (précédemment code mort)
  • Section owner : 5 méthodes de fallback successives pour la récupération

v1.0 (initial)

  • Export/import configuration complète
  • Génération profil flotte
  • Validation d'intégrité
  • Éditeur de champs clés
  • Visualisation et gestion des fichiers JSON

Clone this wiki locally