Skip to content

About

LORA spying tools

Resources

Stars

1 star

Watchers

0 watching

Forks

Latest commit

 

History

2 Commits

Folders and files

Repository files navigation

Meshtastic Passive Sniffer

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.

1. Concepts

Le protocole Meshtastic

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.

Ce qui est chiffré, ce qui ne l'est pas

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.

Écoute passive vs participation active

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).

Deux approches de capture

  • 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.

Considérations légales / éthiques

É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.


2. Fichiers du repo

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).

Schéma de la base

  • 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 par build_db.sh) — état des nœuds avec ancienneté de dernière observation en secondes.

3. Installation

pip install meshtastic folium networkx matplotlib --break-system-packages

4. Utilisation

Construire la base (optionnel — le sniffer le fait automatiquement)

./build_db.sh                    # crée meshtastic_sniffer.db
./build_db.sh --reset            # repart de zéro
./build_db.sh /chemin/custom.db  # chemin custom

Lancer la capture

python3 meshtastic_sniffer.py --port /dev/ttyACM0   # série
python3 meshtastic_sniffer.py --ble                  # BLE
python3 meshtastic_sniffer.py --host 192.168.1.50    # TCP/WiFi

Avant 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).

Visualiser les résultats

python3 visualize.py --db meshtastic_sniffer.db --out-dir ./viz

Gé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 RSSI
  • viz/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.


5. Limites connues

  • 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.

6. Pistes d'évolution

  • 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

About

LORA spying tools

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages