Outillage pour observer passivement un mesh Meshtastic : capture des métadonnées de paquets (présence de nœuds, RSSI/SNR, routage, position si diffusée), stockage en SQLite, et visualisation (carte + graphe de routage).
Développé pour tourner avec un LilyGo T-Deck (ESP32-S3
- SX1262 LoRa) comme nœud d'écoute, mais fonctionne avec n'importe quel appareil Meshtastic connecté en série, BLE ou TCP.
Meshtastic est un protocole de mesh radio longue portée basé sur LoRa. Chaque
nœud relaie les paquets des autres (selon son rôle et le hop_limit du
paquet), formant un réseau maillé sans infrastructure centrale. Les paquets
transportent des types différents identifiés par un portnum :
TEXT_MESSAGE_APP (messages), POSITION_APP (GPS), NODEINFO_APP
(identité du nœud), TELEMETRY_APP (batterie, capteurs), etc.
Le payload des paquets est chiffré (AES-256-CTR). Sur le canal public par
défaut ("LongFast"), la clé est connue et publique (AQ==), donc les
messages y sont en pratique lisibles par quiconque écoute. Sur un canal
custom avec une clé propre, le payload reste opaque.
Les en-têtes de paquet (ID source, ID destination, hop limit, ID de paquet) circulent en clair, quel que soit le canal. C'est ce qui permet l'écoute passive même sans connaître la clé du canal : présence de nœuds, fréquence d'émission, routage, RSSI/SNR restent observables.
Par défaut, un nœud Meshtastic participe au routage : il relaie le trafic des
autres nœuds selon son rôle (CLIENT par défaut). Pour une écoute
vraiment passive, sans influencer le mesh observé, il faut configurer le
nœud d'écoute en rôle CLIENT_MUTE (silence radio en émission, écoute
uniquement).
- CLI/API officiel Meshtastic : on utilise la stack firmware standard, qui décode et filtre déjà les paquets avant de les exposer en série/BLE/TCP. Rapide à mettre en œuvre, mais on ne voit que ce que le firmware choisit de remonter.
- Firmware custom bare-metal (RadioLib) : on bypasse la stack Meshtastic pour dialoguer directement avec le driver radio SX1262, capturant tout signal LoRa sur la fréquence, y compris hors-protocole ou malformé. Plus de contrôle, plus de travail.
Ce repo implémente la première approche (CLI/API officiel + pipeline Python), suffisante pour cartographier un mesh Meshtastic existant.
Écouter un canal Meshtastic public non chiffré individuellement (clé connue) est comparable à l'écoute VHF aviation/marine : pas de violation du secret des correspondances sur un canal broadcast ouvert. Si l'usage prévu inclut la journalisation de positions GPS de nœuds tiers hors de son propre matériel, il est préférable de clarifier en amont s'il s'agit d'un exercice privé (matériel personnel) ou d'une étude de mesh public, et de documenter l'usage en conséquence.
| Fichier | Rôle |
|---|---|
build_db.sh |
Crée le schéma SQLite indépendamment du script de capture. Utile pour initialiser/reset la base ou l'inspecter en CLI sans lancer Python. |
meshtastic_sniffer.py |
Se connecte à un nœud Meshtastic (série/BLE/TCP) et logue chaque paquet reçu dans SQLite. Crée le schéma automatiquement s'il n'existe pas. |
visualize.py |
Lit la base SQLite et génère un résumé texte, une carte HTML (folium + heatmap RSSI) et un graphe de routage (networkx). |
observations— un enregistrement par paquet reçu (timestamp, from/to, RSSI, SNR, hop limit/start, portnum, texte si applicable, JSON brut).nodes— dernier état connu par nœud (nom, modèle, dernière position, dernier RSSI/SNR, niveau de batterie).nodes_status(vue, créée parbuild_db.sh) — état des nœuds avec ancienneté de dernière observation en secondes.
pip install meshtastic folium networkx matplotlib --break-system-packages./build_db.sh # crée meshtastic_sniffer.db
./build_db.sh --reset # repart de zéro
./build_db.sh /chemin/custom.db # chemin custompython3 meshtastic_sniffer.py --port /dev/ttyACM0 # série
python3 meshtastic_sniffer.py --ble # BLE
python3 meshtastic_sniffer.py --host 192.168.1.50 # TCP/WiFiAvant de lancer une capture longue durée, penser à passer le nœud d'écoute en
rôle CLIENT_MUTE via l'app Meshtastic si l'objectif est une écoute
strictement passive.
Arrêt propre avec Ctrl+C (ferme la connexion et la base).
python3 visualize.py --db meshtastic_sniffer.db --out-dir ./vizGénère :
- un résumé en console (nœuds vus, répartition par type de paquet, batteries)
viz/meshtastic_map.html— carte des nœuds avec position connue + heatmap RSSIviz/meshtastic_routing.png— graphe des échanges point-à-point observés
Note : peu de nœuds diffusent leur position publiquement par défaut (paramètre de confidentialité côté utilisateur), donc la carte peut rester clairsemée selon le mesh observé — c'est un comportement normal.
- Le CLI/API officiel ne remonte que ce que le firmware Meshtastic décide d'exposer : pas de capture de paquets malformés ou hors-protocole.
- Le graphe de routage est peu rempli si le trafic observé est
essentiellement en broadcast (
^all), ce qui est le cas par défaut sur la plupart des mesh. - Le déchiffrement automatique des messages texte ne fonctionne que sur le canal public par défaut (clé connue) ; un canal avec clé custom restera opaque au-delà des métadonnées d'en-tête.
- Firmware custom (RadioLib) pour une capture bas niveau complète
- Export continu vers une timeseries DB (InfluxDB/Timescale) pour du monitoring longue durée
- Triangulation approximative de position de nœuds via RSSI multi-points