Passerelle MQTT

La passerelle MQTT permet de relier des nœuds LoRa de pair à pair à l’internet et vice versa. La présente documentation vous guidera pas à pas dans cette démarche. L’application de la passerelle est complète et ne nécessite aucune programmation pour son fonctionnement. Cependant, le code source complet de la passerelle LoRa est disponible et peut être personnalisé si nécessaire.

Ce guide commencera par la configuration de base et ajoutera d’autres fonctionnalités plus bas, notamment la réception de messages de la LoRa sur un téléphone portable

Si vous suivez les instructions de ce guide, vous devriez être en mesure de tout faire fonctionner en 20 minutes environ.

Caractéristiques de la passerelle MQTT

  • Prise en charge du protocole pair à pair RadioShuttle LoRa
  • Transmission de messages MQTT à des nœuds spécifiques de LoRa
  • Transmission des messages LoRa à un serveur MQTT (également appelé MQTT Broker)
  • Rapport d’état détaillé sur l’écran OLED (enregistrement supplémentaire sur le moniteur série)
  • Connexion/reconnexion automatique à un réseau WiFi (et/ou à un autre réseau WiFi)
  • Connexion/reconnexion automatique à un serveur MQTT (et/ou à un autre serveur MQTT)
  • Mise à jour automatique de l’horloge via NTP (au démarrage et une fois par semaine)
  • Surveillance des opérations par un watchdog et redémarrage s’il n’est pas réactif
  • Prise en charge du cryptage SSL pour les communications MQTT (mqtts)
  • Prise en charge du cryptage AES pour les messages LoRa
  • Soutien à 1 000 nœuds LoRa

Préparation

  • Assurez-vous d’avoir un nœud LoRa à portée de main, par exemple une carte ECO Power ou Turtle, ou une deuxième carte Eagle.
  • Assurez-vous que l’IDE Arduino est installé et fonctionne. Pour plus de détails, voir la page Mise en Service.
  • Assurez-vous que vous avez un compte MQTT avec un nom d’utilisateur, un mot de passe, un nom d’hôte, un port et un Topic disponibles.
  • Assurez-vous d’avoir votre SSID et votre mot de passe WiFi à portée de main.

Configurer les paramètres de la passerelle MQTT

  • Activez l’application « PropertyEditor » à partir des exemples Arduino inclus en appuyant une fois sur le bouton « Reset » puis en maintenant le bouton « User » enfoncé pendant environ 5 secondes (jusqu’à ce que l’application « PropertyEditor » démarre dans la fenêtre « Serial Monitor »).
  • Définissez les propriétés WiFi suivantes : WIFI_SSID, WIFI_PASSWORD (une autre configuration WiFi est prise en charge au cas où le WiFi principal n’est pas disponible). En option, configurez une propriété HOSTNAME pour donner un nom à la passerelle MQTT, par exemple « mygateway1 ».
  • Définissez la propriété MQTT_SERVER :
    mqtt://user:password@hostname:port
    ou utilisant le SSL :
    mqtts://user:password@hostname:port
  • Définissez la propriété MQTT_TOPIC_GATEWAY qui est utilisée pour les échanges de messages avec le serveur MQTT (le topic doit également être configuré/autorisé sur le serveur MQTT). Une autre configuration du serveur MQTT (MQTT_SERVER_ALT) est prise en charge au cas où le serveur MQTT principal n’est pas disponible. En option, définissez le mot de passe AES via la propriété LORA_APP_PWD (lorsque vous utilisez un mot de passe d’application LoRa, celui-ci doit être défini et identique sur tous les nœuds LoRa). Pour envoyer un message de test à un autre nœud LoRa, vous devez également spécifier le LORA_REMOTE_ID de la carte distante.

Remarque :
Les comptes MQTT anonymes (sans nom d’utilisateur et mot de passe) ne sont pas pris en charge car cela introduirait des limitations lorsqu’ils sont utilisés avec l’application « MQTT Push Client » qui nécessite un nom d’utilisateur.

Installer le logiciel de passerelle MQTT sur la carte Eagle

  • Chargez l’application « ESP32RadioShuttleMQTTGateway » à partir des exemples Arduino inclus. Elle se trouve dans le menu Arduino : Fichier -> Exemples -> Arduino-mbed-API Library.
  • Sélectionnez la carte : « Heltec WiFi LoRa 32(V2) » dans le menu Outils -> Type de carte -> ESP32 Arduino

Lorsque l’application est démarré, elle doit se connecter au réseau WiFi puis établir une connexion avec le serveur MQTT. L’écran OLED sur le tableau indique l’état du WiFi et du MQTT.

L’écran s’assombrit après une courte période, une brève pression sur le bouton « User » permet de le rallumer.

État de la passerelle MQTT

Un état détaillé peut être vu dans le fichier journal « Serial Monitor » d’Arduino, qui enregistre de nombreux détails, y compris les mots de passe du WiFi et du MQTT à des fins de débogage. Si les mots de passe ne doivent pas être enregistrés, l’option de débogage doit être désactivée en changeant SetDebug(true) en SetDebug(false) dans la fonction setup() du programme de passerelle (« ESP32RadioShuttleMQTT.ino »).

Affichage en mode « MQTT Gateway »

Ligne 1

  • ID du dispositif RadioShuttle de la passerelle (pour des raisons d’espace, seuls les trois derniers chiffres sont affichés)
  • L’heure actuelle (au format hh:mm:ss)
    Au départ, l’heure d’installation du programme est affichée, après une courte période, l’affichage passe à l’heure correcte acquise auprès du serveur NTP (en supposant que le WiFi est disponible)

Ligne 2

  • SSID WiFi (nom) et RSSI WiFi (puissance)
    Après le démarrage de la passerelle, l’écran affiche le SSID WiFi. Une fois la connexion WiFi établie, l’écran affiche également la valeur du RSSI WiFI (par exemple « HELIOSOG (-62) »).
  • Un RSSI WiFi inférieur à -85 indique une faible puissance du signal WiFi
  • Le SSID WiFi n’est affiché que jusqu’à ce que le premier message LoRa soit reçu
  • Le dernier message LoRa reçu sera affiché (seulement quelques caractères). Si le message contient des données binaires, un vidage hexadécimal du dernier message est affiché

Ligne 3

  • Adresse et port du serveur MQTT

Ligne 4

  • Paquets LoRa reçus/transmis RX(xx) TX(xx)
  • Puissance du signal des derniers paquets reçus dBm(xxx)
    Parfois, la valeur est également appelée RSSI et se situe généralement entre -40 et -150 (-40 dBm étant proche et -150 dBm étant éloigné)

Ligne 5

  • État du WiFi: Offline ou Online
  • État du MQTT: Offline ou Online

Pour éviter que l’écran OLED ne s’enflamme, il sera automatiquement mis en veilleuse après une courte période. Une brève pression sur le bouton « User » le rallumera. L’écran s’allume également lorsqu’un message LoRa est reçu.

Mise en place d’un nœud LoRa

Toutes les cartes supportées par RadioShuttle peuvent être utilisées, actuellement ce sont LongRa, ECO Power, Turtle et Eagle.

Les cartes Arduino (ECO Power, Eagle, LongRa)

Dans cet exemple, nous utilisons une des cartes basées sur Arduino, ECO Power.

  • Installez le logiciel RadioShuttle sur la carte ECO Power (voir Mise en Service).
  • Activez l’application « PropertyEditor » en appuyant une fois sur le bouton « Reset », puis en maintenant le bouton « User » enfoncé pendant environ 5 secondes (jusqu’à ce que l’application « PropertyEditor » démarre dans la fenêtre « Serial Monitor »).
  • Définissez LORA_REMOTE_ID sur l’ID de la carte de la passerelle MQTT (Eagle). L’ID de la carte Eagle sera affiché au démarrage dans le moniteur serie d’Arduino.
  • Définissez LORA_RADIO_TYPE = 3 (noeud en ligne) ou 1 (noeud hors ligne). Voir aussi le tableau dans Installation d’un Croquis RadioShuttle pour ECO Power.

Après avoir démarré la carte ECO Power, le fait d’appuyer sur le bouton « User » enverra un exemple de message à la passerelle MQTT. Ce message peut être suivi sur l’écran de la passerelle. Le message est également transmis au serveur MQTT.

La Carte à base de Mbed (Turtle)

Dans cet exemple, nous utilisons notre carte à base de Mbed, Turtle.

  • Installez le logiciel RadioShuttle sur la planche Turtle (voir Mise en Service).
  • Une fois le logiciel installé avec succès, le programme du terminal est démarré. Dans les 10 secondes, tapez p et appuyez sur ENTER pour lancer l’application « PropertyEditor ».
  • Réglez LORA_REMOTE_ID sur l’ID de la carte de la passerelle MQTT (Eagle) :
    s12=<l'ID de la carte Eagle>
    L’ID de la carte Eagle sera affiché lors du démarrage dans le moniteur serie d’Arduino.
  • Définissez LORA_RADIO_TYPE = 3 (noeud en ligne) ou 1 (noeud hors ligne). Voir aussi le tableau dans Installation du Programme RadioShuttle pour Turtle.

Par défaut, une propriété PROG_CMDLINE vide fait que le logiciel démarre le programme « RadioTestNew ». Pour démarrer un autre programme, entrez le code de programme souhaité, par exemple s80=b pour le démarrage initial du programme « Blinky » (voir la figure 2 dans Installation du Programme RadioShuttle pour Turtle).

Après avoir démarré la carte Turtle, le fait d’appuyer sur le bouton « User » enverra un exemple de message à la passerelle MQTT. Ce message peut être suivi sur l’écran de la passerelle. Le message est également transmis au serveur MQTT.

Messages MQTT depuis / vers le serveur MQTT

Habituellement, plusieurs clients MQTT sont connectés au serveur MQTT. Il peut s’agir d’un PC, d’un smartphone ou même d’un client MQTT Arduino. Nous allons expliquer ce qui sera envoyé/reçu entre la passerelle MQTT et le serveur MQTT à l’aide des trois exemples suivants :

Message LoRa reçu par la passerelle MQTT et transmis au serveur MQTT

Lorsque la passerelle MQTT a reçu un message d’un nœud LoRa, elle le transmet au serveur MQTT. Le topic ressemble à :
loratest/HELIOS/myHost/LoRaRECV/11616/1/2
Le contenu du message MQTT est le contenu du message LoRa. Il est recommandé d’utiliser des messages très courts (par exemple quelques octets seulement) pour économiser l’énergie sur le nœud LoRa lors de l’envoi et pour maintenir une faible utilisation du réseau.

Un message se compose de :

  • Topic MQTT (loratest/HELIOS) comme spécifié dans la propriété de la passerelle MQTT_TOPIC_GATEWAY
  • Nom d’hôte comme spécifié dans la propriété de la passerelle HOSTNAME (myHost si vide)
  • Le clé (LoRaRECV) indique que la passerelle transmet un message LoRa reçu
  • Le numéro 11616 indique l’ID du nœud LoRa qui envoie le message
  • Le numéro 1 est l’ID de l’application du nœud LoRa qui envoie le message (l’ID 1 est utilisé par toutes les applications d’exemple)
  • Le dernier numéro indique l’état de réception du nœud. Les numéros d’état valides sont :
    2 = des données confirmées ont été reçues
    1 = les données ont été reçues (confirmation non demandée)

Message LoRa du serveur MQTT à la passerelle MQTT

Lorsque la passerelle reçoit un message du serveur MQTT, et que le topic configuré correspond, elle transmet le contenu du message au nœud LoRa distant. Le topic ressemble à :
loratest/HELIOS/myHost/LoRaSEND/11616/1/1

  • Topic MQTT (lorates/HELIOS) comme spécifié dans la propriété de la passerelle MQTT_TOPIC_GATEWAY
  • Nom d’hôte comme spécifié dans la propriété de la passerelle HOSTNAME (myHost si vide)
  • Le clé (LoRaSEND) indique que la passerelle doit envoyer un message à un nœud LoRa
  • Le numéro 11616 est l’ID du nœud LoRa cible pour ce message
  • Le numéro 1 est l’ID de l’application cible pour ce message
  • Le dernier numéro indique qu’un message doit être envoyé :
    1 = avec confirmation
    0 = sans confirmation au serveur MQTT
    Le deuxième bit (2) signifie que le message est soumis à un cryptage AES, par exemple
    2 Cryptage AES sans demande de confirmation
    3 Cryptage AES avec demande de confirmation

Message de confirmation de la passerelle MQTT vers le serveur MQTT

Après qu’un message a été transmis du serveur MQTT à un nœud LoRa, un message d’état sera envoyé au serveur MQTT pour l’informer de la réussite ou de l’échec de la transmission des messages au nœud LoRa. Un topic de statut ressemble à :
loratest/HELIOS/myHost/LoRaSTAT/11616/1/2
Le contenu du message est la chaîne de statut, par exemple MS_SentCompletedConfirmed

  • Topic MQTT (loratest/HELIOS) comme spécifié dans la propriété de la passerelle MQTT_TOPIC_GATEWAY
  • Une clé (LoRaSTAT) que la passerelle doit envoyer un message à un nœud LoRa
  • Le numéro 11616 est l’ID du nœud LoRa cible de ce message
  • Le numéro 1 est l’ID de l’application cible pour ce message
  • Le dernier numéro est l’état d’achèvement du message. Les numéros d’état valides sont :
    1 = le transfert de message a été effectué
    2 = le transfert du message a été effectué et confirmé par le nœud LoRa récepteur
    3 = le transfert de message a été interrompu après un délai d’attente (3 tentatives émises)
    4 = le nœud n’a pas accepté le message parce que l’autorisation a échoué

Envoyer des messages MQTT à un smartphone

Après avoir appris comment les messages sont transférés vers/depuis le serveur MQTT, nous allons un peu plus loin et montrons comment un message peut être envoyé directement à un smartphone. Le smartphone peut même envoyer un message au nœud LoRa, via la passerelle MQTT.

  • Installez l’application « MQTT Push Client » pour iOS ou Android.
  • Configurez le compte MQTT (utilisateur MQTT, mot de passe, hôte).
  • Configurez le topic MQTT dans l’application, par exemple « loratest/HELIOS », comme indiqué dans les paramètres de la passerelle :

C’est tout ! De nouveaux messages sur ce topic apparaîtront sur le smartphone après que le nœud LoRa aura envoyé un message.

Envoyer des messages à partir d’un smartphone

Ajoutez une action MQTT avec les paramètres suivants :

  • Nom: « Bonjour nœud LoRa 11609 »
  • Topic: loratest/HELIOS/LoRaSEND/phonename/11609/1/0
  • Nom du téléphone: tout nom, par exemple « iPhone-Yves »
  • Le numéro 11609: est l’ID du nœud LoRa cible pour ce message
  • Le numéro 1: est l’ID de l’application cible pour ce message
  • Le dernier numéro (flags pour l’envoi de messages) :
    0 = pas de confirmation
    1 = première bit marche => envoyer un message avec confirmatio
    Le deuxième bit (2) signifie que le message est soumis à un cryptage AES, par exemple
    2 Cryptage AES sans demande de confirmation
    3 Cryptage AES avec demande de confirmation

Dans la fenêtre « Dashboard » de l’application, l’action permet d’envoyer des données au nœud LoRa. Il peut s’agir d’un simple message de contrôle, par exemple l’allumage et l’extinction des lumières.

Résumé

La passerelle MQTT permet une transmission polyvalente des messages entre les nœuds pair-à-pair de RadioShuttle LoRa et le monde de l’IoT via MQTT. Il peut s’agir d’un simple rapport de température ou d’une gestion avancée des machines. La passerelle MQTT complète ne nécessite aucune programmation ; il suffit d’entrer les paramètres WiFi et MQTT via l’application « PropertyEditor » et elle fonctionnera. Il en va de même pour le nœud LoRa. Une douzaine d’exemples d’applications sont inclus, il suffit d’activer/charger l’application de capteur appropriée et la communication peut commencer.

Note pour l’utilisation avancée

Par défaut, tous les exemples d’applications RadioShuttle utilisent l’ID d’application « 1  dans le message. Un champ magique dans le message détermine si le message est traité ou ignoré. Pour les projets plus importants, des ID d’application personnalisés peuvent être utilisés lors de l’enregistrement via la fonction rs->RegisterApplication() à la fin de la fonction setup() dans le fichier « .ino » du programme d’exemple.
Lorsque des messages cryptés AES sont utilisés, le mot de passe doit être défini de manière identique sur tous les nœuds LoRa et la passerelle, en utilisant « PropertyEditor ». En cas d’utilisation de plusieurs ID d’application, le mot de passe doit être spécifié par ID d’application via la fonction rs->RegisterApplication().

Notes sur la performance

Les messages MQTT peuvent contenir tous types de données, par exemple des données binaires, des chaînes de caractères, des messages HTML ou même des messages codés en JSON. Pour les réseaux WiFi, la longueur des messages n’est pas importante, tandis que pour les réseaux LoRa, la longueur des messages doit être aussi courte que possible. Par exemple, l’exemple du capteur de température RadioShuttle n’utilise que 6 octets ou même moins pour transmettre l’humidité, la température et l’état de la batterie.

Il y a trois raisons principales pour garder le message aussi court que possible :

  1. Évite un réseau radio LoRa occupé (permet à plus d’appareils de communiquer, dépasse la limite de 1% par heure d’occupation)
  2. Économie d’énergie sur les nœuds LoRa alimentés par batterie
    (Par exemple, un message de 12 octets consomme deux fois plus d’énergie qu’un message de 6 octets)
  3. Accélère le délai de communication grâce à de petits messages. La modulation LoRa permet de grandes distances mais a un faible débit de données. Les petits messages permettent un délai d’exécution plusieurs fois plus court que les gros messages