LoRaWAN GPS Tracker - Heltec Wireless Tracker

Tracker GPS LoRaWAN basé sur la carte Heltec Wireless Tracker (ESP32-S3 + SX1262 + GPS).

Ce projet permet de tracker en temps réel la position GPS d'un dispositif et de transmettre les coordonnées via le réseau LoRaWAN (The Things Network) avec affichage sur un écran TFT intégré.

Fonctionnalités

• Join LoRaWAN OTAA avec gestion de session persistante (nonces sauvegardés en flash)
• Transmission GPS : Latitude, Longitude, Altitude via CayenneLPP
• Affichage TFT : Heure locale (Paris), Position GPS, Satellites, Statut LoRa
• Réception Downlink : Affichage de la distance depuis la gateway
• Persistance : Sauvegarde des nonces pour éviter les re-joins inutiles
• Région EU868 configurée avec SF12 (portée maximale)
• Optimisé pour faible consommation avec possibilité de deep sleep

Matériel requis

• Heltec Wireless Tracker (ESP32-S3 + SX1262 + GPS + écran TFT)
• Antenne LoRa 868MHz
• Antenne GPS
• Câble USB-C pour programmation

Installation

Prérequis

• PlatformIO (CLI ou extension VS Code)
• Compte sur le réseau LoRaWAN de La Cyber Fabrique ou autre provider LoRaWAN comme The Things Network

1. Cloner le projet

git clone https://github.com/lacyberfabrique/heltec-wireless-tracker
cd heltec-wireless-tracker

2. Installer les dépendances

PlatformIO installera automatiquement les dépendances lors de la première compilation :

pio pkg install

3. Configurer les identifiants LoRaWAN

⚠️ IMPORTANT - SÉCURITÉ : Ne jamais commiter vos vraies clés LoRaWAN dans un repository public !

Méthode recommandée (les clés restent en local et ne sont jamais commitées) :

1. Copier le fichier exemple :

cp src/config_local.h.example src/config_local.h

2. Éditer src/config_local.h et décommenter/remplacer vos vraies clés :

// DevEUI - votre Device EUI depuis votre provider LoRaWAN
#define RADIOLIB_LORAWAN_DEV_EUI   0x70B3D57ED0012345  // VOS VRAIES VALEURS ICI

// AppKey - votre Application Key (16 octets)
#define RADIOLIB_LORAWAN_APP_KEY   0x01, 0x23, 0x45, 0x67, 0x89, 0xAB, 0xCD, 0xEF, 0xFE, 0xDC, 0xBA, 0x98, 0x76, 0x54, 0x32, 0x10  // VOS VRAIES VALEURS ICI

// NwkKey - identique à AppKey pour LoRaWAN 1.0.x (16 octets)
#define RADIOLIB_LORAWAN_NWK_KEY   0x01, 0x23, 0x45, 0x67, 0x89, 0xAB, 0xCD, 0xEF, 0xFE, 0xDC, 0xBA, 0x98, 0x76, 0x54, 0x32, 0x10  // VOS VRAIES VALEURS ICI

Le fichier src/config_local.h est automatiquement ignoré par Git (déjà dans .gitignore)

Où trouver ces identifiants ?

Sur The Things Network (TTN) :

1. Créer une application
2. Ajouter un device (End Device)
3. Choisir "Over the air activation (OTAA)"
4. Copier le DevEUI, AppKey et NwkKey

Sur ChirpStack (La Cyber Fabrique) :

1. Aller dans votre application
2. Cliquer sur Add device
3. Sélectionner un Device Profile de type OTAA
4. Entrer le DevEUI (Device EUI)
5. Une fois créé, aller dans l'onglet Keys (OTAA)
6. Définir l'Application Key (AppKey)
7. Pour LoRaWAN 1.1, définir aussi la Network Key (NwkKey)

Plus d'infos : ChirpStack Device Documentation

Format des clés :

• DevEUI : format hexadécimal 64 bits (ex: 0x70B3D57ED0012345)
• AppKey / NwkKey : 16 octets séparés par des virgules

⚠️ Note importante : Sur ChirpStack, si un JoinEUI / AppEUI est requis, vous pouvez le laisser à 0000000000000000 (sauf si vous utilisez un serveur de join externe)

4. Compiler et uploader

# Compiler le projet
pio run

# Compiler et uploader sur la carte
pio run --target upload

# Ouvrir le moniteur série (115200 bauds)
pio device monitor

Ou via l'extension PlatformIO dans VS Code :

• Cliquer sur l'icône ✓ pour compiler
• Cliquer sur l'icône → pour uploader
• Cliquer sur l'icône 🔌 pour le moniteur série

Configuration avancée

Modifier l'intervalle d'envoi

Dans src/config.h, modifier la valeur (en secondes) :

// Intervalle d'envoi uplink (60 secondes par défaut)
const uint32_t uplinkIntervalSeconds = 60;

⚠️ Attention : Respecter le Duty Cycle (1% en EU868) et la Fair Use Policy de TTN (30 secondes de time-on-air par jour max).

Modifier la région LoRaWAN

Par défaut : EU868. Pour changer :

// Choix régionaux : EU868, US915, AU915, AS923, etc.
const LoRaWANBand_t Region = EU868;  // Modifier ici

// Pour US915/AU915, choisir aussi la sous-bande
const uint8_t subBand = 0;  // US915: mettre 2, CN470: mettre 1

Modifier le Datarate (portée vs débit)

Dans src/main.cpp, fonction lwActivate() :

// DR0 = SF12/125kHz (portée maximale, débit minimal)
// DR5 = SF7/125kHz (portée minimale, débit maximal)
node.setDatarate(0);  // Modifier ici (0-5 pour EU868)

Données transmises

Format : CayenneLPP

Canal	Type	Données
1	GPS	Lat, Lon, Altitude

Taille de la payload : ~11 octets

Réception Downlink

Le tracker peut recevoir des messages downlink de la gateway :

• 2 octets : Distance en mètres (big-endian) → Affichée en m ou km
• 3 octets ASCII : Message texte brut
• Autre : Affiché en hexadécimal

Affichage TFT

L'écran affiche en temps réel :

• Heure locale Paris (CET/CEST automatique)
• Date
• Position GPS (latitude, longitude)
• Altitude
• Nombre de satellites
• Statut LoRaWAN (Joining, Joined, Sending, etc.)
• Nombre de trames envoyées (Tx)
• Distance depuis la gateway (si downlink reçu)

Debug

Activer les logs détaillés

Les logs sont déjà actifs via printf(). Pour voir les logs :

pio device monitor --baud 115200

LED de statut

• Clignotante : Recherche fix GPS en cours
• Éteinte : GPS synchronisé et système opérationnel

Codes d'erreur courants

Code	Description	Solution
ERR_CHIP_NOT_FOUND	Module radio non détecté	Vérifier connexions SPI
ERR_NO_JOIN_ACCEPT	Join refusé par le network	Vérifier les clés OTAA
ERR_RX_TIMEOUT	Timeout réception	Normal, pas de downlink

Structure du projet

heltec-wireless-tracker/
├── src/
│   ├── main.cpp              # Code principal de l'application
│   ├── config.h              # Déclarations : pins, constantes LoRaWAN
│   ├── config.cpp            # Définitions : variables globales LoRaWAN
│   ├── config_local.h        # Configuration locale des clés (non versionné)
│   ├── lorawan_helper.h      # Déclarations : fonctions utilitaires LoRaWAN
│   └── lorawan_helper.cpp    # Implémentations : gestion OTAA, nonces, erreurs
├── platformio.ini            # Configuration PlatformIO
└── README.md                 # Ce fichier

Bibliothèques utilisées

• RadioLib - Stack LoRaWAN
• TinyGPSPlus - Parser GPS
• CayenneLPP - Format payload
• Adafruit ST7735 - Driver écran TFT
• Adafruit GFX - Graphiques
• ArduinoJson - JSON (future extension)

Sécurité

⚠️ ATTENTION : Les clés LoRaWAN sont des secrets sensibles !

Bonnes pratiques :

1. Ne JAMAIS commiter les vraies clés dans un repo public
2. Utiliser des variables d'environnement ou fichiers de config locaux
3. Ajouter src/config.h au .gitignore si modifié avec de vraies clés
4. Utiliser des valeurs de test (zéros) dans le code partagé
5. Sur TTN et Chirpstack, activer "Frame Counter Checks" pour éviter les replay attacks

Dépannage

GPS ne trouve pas de fix

• Vérifier que l'antenne GPS est bien connectée
• Sortir en extérieur (vue dégagée du ciel)
• Attendre 2-5 minutes pour la première synchronisation

Join LoRaWAN échoue

• Vérifier les clés OTAA (DevEUI, AppKey, NwkKey)
• Vérifier la couverture LoRaWAN (https://ttnmapper.org)
• Sur TTN : activer "Resets Frame Counters" pendant les tests

Compilation échoue

• Vérifier la version de PlatformIO : pio upgrade
• Nettoyer le cache : pio run --target clean
• Réinstaller les libs : rm -rf .pio && pio run

Licence

Ce projet est fourni "tel quel" pour usage personnel et éducatif.

Contributions

Les contributions sont les bienvenues ! N'hésitez pas à ouvrir une issue ou une pull request.