The Things Network (TTN)
The Things Network (TTN)
The Things Network (TTN) est un réseau LoRaWAN communautaire et gratuit pour démarrer. Il reçoit les messages relayés par les passerelles, vérifie et déchiffre ceux de vos appareils, puis vous les remet décodés. C'est le « serveur réseau » de la chaîne décrite dans Chaîne de données.
Site : https://www.thethingsnetwork.org — console de la région Europe : https://eu1.cloud.thethings.network
Les objets de la console
- Application : le regroupement de vos appareils. Elle porte les formateurs de charge utile, les webhooks et les clés d'accès MQTT.
- Appareil (end device) : un capteur. Il a trois identifiants :
<DEV_EUI>(propre à l'appareil),<JOIN_EUI>(souvent des zéros) et la clé<APP_KEY>(secrète). - Passerelle (gateway) : votre passerelle déclarée, pour que TTN accepte ses messages.
Rejoindre le réseau : OTAA
L'activation OTAA (over-the-air activation) est la méthode à utiliser. L'appareil envoie une demande de « join » signée avec sa clé, TTN répond par une acceptation, et les deux calculent les clés de session. Le « join » est refait automatiquement si besoin.
Étapes :
- créer l'application ;
- enregistrer l'appareil avec le plan de fréquences « Europe 863–870 MHz (SF9 for RX2 – recommended) » et la version LoRaWAN 1.0.x ;
- copier
<DEV_EUI>,<JOIN_EUI>,<APP_KEY>dans le micrologiciel ; - vérifier le « join » à l'établi, en regardant le port série, avant de partir sur le terrain.
Piège : l'ordre des octets. Dans le micrologiciel LMIC, le DevEUI et le JoinEUI se saisissent dans l'ordre inverse de la console (poids faible d'abord) ; l'AppKey, dans l'ordre affiché. Se tromper est la cause numéro un de « join » silencieux. Un petit script qui écrit les clés dans le croquis en inversant ce qu'il faut évite l'erreur.
Le formateur de charge utile
Le capteur envoie des octets ; le formateur (payload formatter) les transforme en valeurs lisibles (JSON). Il s'écrit en JavaScript dans la console, onglet Payload formatters (voir l'exemple b du Kit de démarrage).
Piège : un formateur d'application s'applique à TOUS les appareils de l'application. Chez nous, le formateur du capteur de sol traitait aussi un nœud de relevé de couverture : le compteur de paquets de 2 octets de ce dernier est ressorti comme « humidité du sol = 100 » et « température = compteur ÷ 10 ». 130 fausses mesures sont entrées en base en 40 minutes avant qu'on le voie. Parades, à cumuler :
- ne décoder qu'un port précis et un format reconnu (identifiant au début de la trame, longueur attendue), et renvoyer une erreur sinon ;
- définir le formateur sur l'appareil plutôt que sur l'application ;
- côté base de données, distinguer les capteurs des appareils de test (voir Chaîne de données).
Autre leçon : un décodeur peut être faux. Conservez toujours la trame brute pour pouvoir tout recalculer.
Sortir les données de TTN
Deux voies, qui peuvent coexister.
Webhook (TTN appelle votre API)
Dans Integrations → Webhooks, un custom webhook envoie chaque message montant à une adresse HTTPS, avec un en-tête d'authentification que vous choisissez. L'exemple c du Kit de démarrage est un récepteur complet. Points d'attention :
- répondez toujours 200 aux messages que vous ne comprenez pas ou déjà reçus : si votre serveur renvoie des erreurs, TTN réessaie puis finit par désactiver le webhook ;
- ne répondez une erreur (401) qu'en cas d'authentification invalide, et 500 en cas de vraie panne ;
- l'URL doit être joignable depuis Internet, en HTTPS.
Au début de nos essais, un webhook configuré ne livrait rien (cause non élucidée) ; nous sommes passés par MQTT ; les deux voies ont ensuite servi à alimenter l'API.
MQTT (vous allez chercher les messages)
TTN expose un broker MQTT par région : hôte eu1.cloud.thethings.network, utilisateur <APP_ID>@ttn, mot de passe = une clé d'API de l'application. Le sujet des messages montants est v3/<APP_ID>@ttn/devices/<DEVICE_ID>/up. Créez une clé d'API par usage, avec le droit minimal (par exemple read application traffic seulement), pour pouvoir la révoquer seule. Un pont MQTT local (un broker Mosquitto qui relaie ce sujet vers votre réseau) permet de brancher un système domotique sans ouvrir de port.
Limites d'usage équitable
TTN limite le temps d'antenne montant à environ 30 secondes par jour et par appareil et les messages descendants à 10 par jour. Un capteur de sol qui envoie 7 octets toutes les 10 minutes en SF7 (144 messages × 0,057 s ≈ 8 s) reste très en dessous.
Quand quitter TTN ?
Pour un réseau qui grandit ou des données sensibles, on peut héberger soi-même un serveur réseau (ChirpStack). La migration demande de ré-enregistrer les appareils. À petite échelle, TTN suffit.
Exemples de code
Formateur de charge utile et récepteur de webhook (voir aussi le Kit de démarrage).
// Formateur de charge utile TTN (montante) — exemple de démarrage (Alseno Tech, licence MIT).
// À coller dans : console TTN > Application > Payload formatters > Uplink > JavaScript.
//
// PIÈGE : un formateur défini au niveau de l'APPLICATION s'applique à TOUS les appareils
// de cette application (capteurs, mouchards de couverture, tests...). Un appareil qui n'a
// rien à voir recevrait des « mesures » inventées. Deux protections ci-dessous :
// 1. on ne décode que le port PORT_SOL ;
// 2. on exige l'octet d'identification 0xA1 et la bonne longueur ; sinon on répond par une erreur,
// jamais par des valeurs plausibles.
// Mieux encore : définissez le formateur sur l'appareil lui-même (onglet Payload formatters
// de l'appareil), il ne touche alors que celui-là.
var PORT_SOL = 10;
var ID_FORMAT = 0xA1;
var LONGUEUR = 7;
// Calibration de VOTRE sonde (voir la page « Capteur de sol ») : valeur brute dans l'air / dans l'eau.
var BRUT_SEC = 870; // sonde à l'air libre : 0 %
var BRUT_HUMIDE = 560; // sonde dans l'eau : 100 % (une sonde capacitive donne MOINS quand c'est plus humide)
function decodeUplink(input) {
var b = input.bytes;
if (input.fPort !== PORT_SOL) {
return { errors: ["port " + input.fPort + " non géré par ce formateur"] };
}
if (b.length !== LONGUEUR || b[0] !== ID_FORMAT) {
return { errors: ["trame inconnue (longueur " + b.length + ")"] };
}
var brut = (b[1] << 8) | b[2];
var tempBrute = (b[3] << 8) | b[4];
if (tempBrute & 0x8000) tempBrute -= 0x10000; // entier signé sur 16 bits
var vccMv = (b[5] << 8) | b[6];
// Conversion brut -> pourcentage, bornée entre 0 et 100.
var pct = 100 * (BRUT_SEC - brut) / (BRUT_SEC - BRUT_HUMIDE);
pct = Math.max(0, Math.min(100, Math.round(pct)));
var data = { sol_brut: brut, sol_pct: pct, batterie_mv: vccMv };
if (tempBrute !== -32768) data.temperature_c = tempBrute / 100; // 0x8000 = « pas de mesure »
return { data: data };
}
#!/usr/bin/env python3
"""Récepteur minimal de webhook TTN : stocke les mesures dans SQLite.
Exemple de démarrage (Alseno Tech, licence MIT). Une seule dépendance : Flask.
pip install flask
export CLE_INGESTION="<CLE_A_CHOISIR>" # longue chaîne aléatoire, à vous
python recepteur_webhook.py
Dans la console TTN : Integrations > Webhooks > Custom webhook
URL de base : https://<URL_API> chemin montant : /ttn
En-tête : X-Ingest-Key = <CLE_A_CHOISIR>
(Exposez le service derrière HTTPS : proxy inverse, tunnel...)
Choix de conception, tirés de l'expérience :
* on répond TOUJOURS 200 aux charges inattendues ou déjà vues : un webhook qui reçoit
des erreurs réessaie, puis TTN finit par le désactiver. Seules l'authentification
(401) et une vraie panne (500) échouent ;
* on garde la charge d'origine (colonne brut) : un décodeur peut être faux, et sans le
brut on ne peut rien rejouer ;
* un doublon (même appareil, même compteur de trame, même heure) est ignoré proprement.
"""
import hmac
import json
import os
import sqlite3
from flask import Flask, jsonify, request
BASE = os.environ.get("BASE_SQLITE", "mesures.db")
CLE = os.environ.get("CLE_INGESTION", "")
app = Flask(__name__)
def ouvrir_base():
"""Ouvre la base et crée les tables au premier appel (mode WAL : lecture pendant l'écriture)."""
cnx = sqlite3.connect(BASE)
cnx.execute("PRAGMA journal_mode=WAL")
cnx.executescript("""
CREATE TABLE IF NOT EXISTS receptions (
id INTEGER PRIMARY KEY,
appareil TEXT NOT NULL,
recu_le TEXT NOT NULL,
compteur INTEGER,
rssi REAL, snr REAL,
brut TEXT NOT NULL,
UNIQUE (appareil, compteur, recu_le)
);
CREATE TABLE IF NOT EXISTS mesures (
reception_id INTEGER NOT NULL REFERENCES receptions(id),
grandeur TEXT NOT NULL,
valeur REAL NOT NULL
);
CREATE INDEX IF NOT EXISTS idx_mesures ON mesures (grandeur, reception_id);
""")
return cnx
def cle_valide():
"""Compare la clé reçue à la clé attendue, en temps constant."""
recue = request.headers.get("X-Ingest-Key", "")
return bool(CLE) and hmac.compare_digest(recue, CLE)
@app.post("/ttn")
def recevoir():
if not cle_valide():
return jsonify(erreur="non autorise"), 401
msg = request.get_json(silent=True) or {}
montante = msg.get("uplink_message")
if not montante: # événement qui n'est pas une mesure (join, etc.)
return jsonify(ok=True, ignore="pas une mesure")
appareil = msg.get("end_device_ids", {}).get("device_id", "inconnu")
decode = montante.get("decoded_payload") or {}
# On ne retient que les valeurs numériques : un champ texte inattendu ne casse rien.
mesures = {k: float(v) for k, v in decode.items()
if isinstance(v, (int, float)) and not isinstance(v, bool)}
if not mesures:
return jsonify(ok=True, ignore="rien a stocker")
meta = (montante.get("rx_metadata") or [{}])[0] # première passerelle ayant entendu la trame
cnx = ouvrir_base()
try:
with cnx: # une transaction : tout ou rien
cur = cnx.execute(
"INSERT OR IGNORE INTO receptions (appareil, recu_le, compteur, rssi, snr, brut) "
"VALUES (?, ?, ?, ?, ?, ?)",
(appareil, msg.get("received_at", ""), montante.get("f_cnt"),
meta.get("rssi"), meta.get("snr"), json.dumps(msg)))
if cur.rowcount == 0: # doublon : déjà enregistré
return jsonify(ok=True, ignore="doublon")
cnx.executemany(
"INSERT INTO mesures (reception_id, grandeur, valeur) VALUES (?, ?, ?)",
[(cur.lastrowid, g, v) for g, v in mesures.items()])
finally:
cnx.close()
return jsonify(ok=True, stocke=len(mesures))
if __name__ == "__main__":
app.run(host="127.0.0.1", port=8600) # derrière un proxy HTTPS, jamais exposé tel quel
Sources
Documentation TTN (https://www.thethingsnetwork.org/docs) ; essais de terrain Alseno Tech (août 2026).