Tutoriel : Débuter avec The Things Network

Synopsis

L’objectif de ce tutoriel est de prendre en main la pile réseau LoRaWAN open source nommée “The Things Stack v3” utilisée sur le réseau communautaire The Things Network pour mettre en œuvre une application IoT (Internet of Things) .

L’application IoT visée consiste simplement à échanger des données, via LoRaWAN, entre 1 nœud LoRa et un client MQTT. Celle-ci est représentée schématiquement ci-dessous :

On utilisera un émulateur de terminal série pour interagir avec le nœud LoRa à l’aide de commandes de type AT. Ces commandes permettront de le configurer , joindre la passerelle LoRa et lui envoyer des données arbitraires (→ payload LoRa) qui seront ensuite relayées au serveur réseau LoRaWAN de “The Things Stack v3”.

2 types de nœud seront utilisés de façon à illustrer 2 façons d’enregistrer un nœud LoRa dans une application “The Things Stack v3”.
Le serveur réseau LoRaWAN traitera ce payload LoRa — via un morceau de code Javascript appelé “payload formatter” — afin de le transcrire dans un message au format JSON
Ce message JSON sera ensuite délivré sur le client MQTT ayant souscrit aux publications de données provenant du nœud LoRa considéré
Le client MQTT sera utilisé dans un 2^ème temps pour renvoyer des données sur le serveur réseau LoRaWAN
Ces données seront décodées via un “payload formatter” dédié du serveur réseau LoRaWAN
Les données décodées seront enfin envoyées — sour forme d’un payload LoRa — sur le nœud LoRa en transitant par la passerelle

Résumé de la procédure à suivre

Les étapes à suivre pour parvenir à réaliser ce qui vient d’être décrit consistent à :

Créer un compte utilisateur sur The Things Network
Enregistrer la passerelle sur “The Things Stack v3”
Créer une application sur “The Things Stack v3”
Enregistrer le(s) nœud(s) Lora au niveau de l’application
Coder le programme de communication intégré au noeud LoRa
Souscrire aux publications (→ topics MQTT) des nœuds LoRa au niveau du client MQTT
Coder le payload formatter de l’application “The Things Stack v3” pour transcrire en JSON le payload LoRa envoyé par le nœud LoRa
Envoyer des données depuis le nœud LoRa et constater leur bonne réception sur le client MQTT
Coder le payload formatter de l’application “The Things Stack v3” pour transcrire en payload LoRa le message JSON envoyé par le client MQTT
Envoyer un message JSON depuis le client MQTT et constater sa bonne réception sur le nœud LoRa

Procédure détaillée

✓ Création de compte sur The Things Network

Se rendrehttps://account.thethingsnetwork.org/register[Create an account ^] et remplir le formulaire.

✓ [Optionnel] Enregistrement de la passerelle LoRa sur “The Things Stack v3”

Se rendre sur la console d’administration web de The Things Network accessible sur The Things Network Cluster Picker après avoir choisi la région “Europe 1” (ou directement sur https://eu1.cloud.thethings.network/console/ )

Il existe une version en ligne de commande locale de la console d’administration The Things Network.

Voir Command-line Interface pour plus de détails.
Sélectionner l’onglet “gateways” puis le bouton + Add gateway
Saisir les informations d’enregistrement de la passerelle.

Exemple
Une fois enregistrée, se rendre dans la rubrique de la passerelle et créer une clé d’API avec les droits “Link as Gateway to a Gateway Server for traffic exchange, i.e. write uplink and read downlink”

Copier la clé et la sauvegarder dans un endroit sûr comme recommandé dans la boîte de dialogue qui s’affiche suite à la création de la clé d’API

Pour mémoire, la valeur de la clé d’API générée pour enregistrer sur The Things Network la passerelle nommée “sn-lab-ttn-v3” est :

NNSXS.QXPXR2NKPC7BZAWZCE5RYDKUBAC4X25IMLQQQHQBINLVMMYVYYTA45J7SSQLI3VX266K5SFIK6ZSMUKJNVQRDSOHDIA

Pour mémoire, la clé d’API générée pour enregistrer sur The Things Network la passerelle nommée “ciel-lab-ttn-v3” est :

nom : link-api-key valeur : NNSXS.4XJKSV3C7O57T5TA3ESZS72SMUBU36KPFZS3BWQ.DUFFQM6JBGQGXQCRIU5O4PVJWIA5CDYG3FDA2CTB75S73YN6Q7EA

Celle pour la passerelle nommée “sicom-ceri-ttn” est :

NNSXS.RBCPB6IGCUZRQOP5TA7QTZML226WBNSLUXOB53I.4U5LGQOT76NM6LDKPEIBEIEHIORXXTGX2Y7436TZVARRPTBPTBHQ

Connecter la passerelle LoRa au réseau The Things Network

Faire un reset de la passerelle à l’aide du bouton situé sous le couvercle

Se connecter sur le point d’accès WiFi de la passerelle (→ SSID : “Things-Gateway-<adresse MAC interface WiFi>” / Clé WPA : “thethings”)

Le modèle de passerelle utilisée dans ce tutoriel est : “The Things Kickstarter Gateway” Model : TTN-001-868-1.0.

Les adresses MAC de ses interfaces réseau sont :

Interface WiFi : 00:1E:C0:40:2A:69 (→ Microchip Technology Inc.)
Interface filaire : 54:10:EC:10:E8:B9 (→ Microchip Technology Inc.)
Il est également possible d’utiliser une passerelle Multitech Conduit .

Cependant, il faudra d’abord la configurer — pour être reconnue par The Things Network — en suivant la procédure : Connect Multitech Conduit with UDP Packet Forwarder

Cette procédure est moins à jour que celle expliquée sur Connect Multitech Conduit with LoRa Basics™ Station mais est adaptée au firmware présent dans la passerelle en notre possession (→ MTCDT-246A Firmware 1.6.4)

Se rendre sur l’interface web de configuration de la passerelle (→ http://192.168.84.1 )
Saisir les informations requises pour permettre à la passerelle de se connecter au réseau The Things Network
Appliquer la configuration
Vérifier la réussite du test lancé automatiquement et qui consiste à joindre le réseau The Things Network pour envoyer — depuis la passerelle — un 1^er message

La signification de l’état des DELs de la passerelle est précisé sur Status LEDs

✓ Création de l’application “The Things Stack v3”

Créer une application The Things Network via le bouton + Add application] de l’onglet “Applications” de la console The Things Network

Il faut voir une application The Things Network comme le destinataire des messages envoyés par les nœuds LoRa.

✓ Enregistrement d’un nœud Lora au niveau de l’application “The Things Stack v3”

Toujours depuis la console The Things Network, enregistrer dans l’application créée le ou les nœuds Lora devant communiquer avec elle depuis le menu “Applications application ID End devices + Add end device”

Il faut alors renseigner — ou laisser générer automatiquement par The Things Network — l’identifiant du nœud (→ Dev EUI, un peu l’équivalent d’une adresse MAC mais sur 8 octets) et la clé d’application (→ App Key, sur 16 octets).

Le Dev EUI peut, selon le constructeur, être imposé (comme l’adresse MAC d’une carte réseau) mais il est bien souvent modifiable par programme.

✓ Codage du programme du noeud LoRa

Coder le programme de chacun des nœuds LoRa — en y intégrant les identifiants/clés générés à l’étape précédente — de façon à ce que ceux-ci émettent régulièrement (mais en veillant à respecter le duty cycle ) les informations à traiter par l’application utilisant The Things Network

✓ Souscription MQTT aux publications des nœuds LoRa

✓ Codage du payload formatter pour la communication “Uplink”

✓ Test du “Uplink”

✓ Codage du payload formatter pour la communication “Downlink”

✓ Test du “Downlink”

Paramétrage client MQTT

Broker Address : eu1.cloud.thethings.network
User Credentials
- User Name : <Application ID>@ttn (ex.: tuto-ttn@ttn)
- Password :
  1. Aller dans Applications tuto-ttn integrations MQTT puis cliquer sur “Generate API Key”
  2. Copier la clé générée (ex.: NNSXS.DFQH6E2B2FJ54OKLKNYSVB4CVPMLCVOYEFVWRQY.34J6KRWBSBQRIEK5SW5P2Y6LXRNW42CJUCBWUG2KI7LFJAPT6UJQ)
  3. Coller cette clé dans le champ password du client MQTT
Topic de souscription : v3/<Application ID>@ttn/devices/<Device ID>/up (ex. : v3/test-app-cdefrance@ttn/devices/multitech-mdot-01/up)

voir : MQTT Server

Topic de publication : v3/<Application ID>@ttn/devices/<Device ID>/down/push (ex. : v3/test-app-cdefrance@ttn/devices/multitech-mdot-01/down/push)

☠ Contenu ancien site pour version 2 de TTN à recycler ☠

Exploiter les informations récoltées par l’application The Things Network soit en récupérant les données avec un client MQTT (→ client MQTT.fx , programme Qt, utilitaire mosquitto_sub qui accompagne le broker Mosquitto ), soit, directement, depuis ce que The Things Network appelle une integration

Paramétrage MQTT

Host: <Region>.thethings.network, where <Region> is last part of the handler you registered your application to, e.g. eu.
Port: 1883, or 8883 for TLS
For TLS, the server uses a Let’s Encrypt certificate. If your server does not trust that yet, you might want to include the Let’s Encrypt Roots in your certificate chain. Alternatively you can use our PEM-encoded CA certificate, which includes those roots as well: mqtt-ca.pem
Username: Application ID
Password: Application Access Key
Uplink Messages Topic : <AppID>/devices/<DevID>/up
Downlink Messages Topic : <AppID>/devices/<DevID>/down

L'Application ID et l'Application Access Key sont à récupérer depuis la console d’administration dans les rubriques Application Overview et Access Keys

Pour plus de détails consulter l’article Réseau The Things Network link de M.Silanus.

=== Décoder le payload LoRa dans une application The Things Network

Lorsqu’on crée une application sur The Things Network, la plateforme met à notre disposition une fonction qui nous permet de décoder le tableau d’octets transmis dans la charge utile d’un message LoRa (→ payload) et le convertir en un objet JavaScript (ex. : JSON).

L’édition de cette fonction — appelée decoder — est réalisée,depuis la console The Things Network, dans l’onglet Payload Formats du panneau de configuration de l’application.

Cette fonction doit être codée en Javascript dans sa version ES5.1 (→ ECMAScript 5.1).

Le fait que The Things Network ne prenne en charge que la version ES5.1 de Javascript interdit d’utiliser les fonctionnalités de la version ES6 comme les TypedArray ou les Fonctions fléchées link .

🕮 Sources :

Exemple de décodage d’un nombre flottant codé en IEE754 simple précision (32 bits)

function Decoder(bytes, port) {
  var decoded = {};
  if (port === 1) {
    var bits = (bytes[0] << 24) | (bytes[1] << 16) | (bytes[2] << 8) | (bytes[3]);
    var sign = ((bits >>> 31) === 0) ? 1.0 : -1.0;
    var e = ((bits >>> 23) & 0xff);
    var m = (e === 0) ? (bits & 0x7fffff) << 1 : (bits & 0x7fffff) | 0x800000;
    var f = sign * m * Math.pow(2, e - 150);
    console.log(f);
    decoded.valeur_numerique = f;
    decoded.valeur_chaine = f.toString();
  }
  return decoded;
}

Ressources

Connect Multitech Conduit with UDP Packet Forwarder link

→ page qui explique comment se connecter à The Things Network depuis une passerelle Multitech Conduit

Cette procédure s’applique à une Multitech Conduit dont le firmaware est antérieur à la version 5.3. Ce qui est notre cas (→ firmware v.16.4).

La procédure recommandée pour la dernière version du firmware est décrite dans Connect Multitech Conduit with LoRa Basics™ Station link

Best practices to limit application payloads

→ Un billet qui explique les bonnes pratiques pour limiter la taille de la charge utile des messages LoRa
LoRaWAN airtime calculator

→ Un outil qui permet de calculer le temps nécessaire pour transmettre par LoRa la charge utile d’un message
Maximum Duty Cycle , Règles précises de duty cycle

→ Règlementation sur la portion de temps durant laquelle un end device LoRa peut émettre

🞄 🞄 🞄