Sommaire
Introduction
Après avoir présenté les principes et le fonctionnement des réseaux LoRa (LoRa: qu’est-ce que c’est ? à quoi ça sert ?), on va ici s'intéresser à la connexion d'un premier appareil LoRa à un réseau et à la récupération des informations dans Home-Assistant.
Pour rappel, LoRa vous permettra de connecter des capteurs distants et hors de portée de votre box domotique. Vous pourrez par exemple connecter une station météo dans votre maison de campagne, une boite aux lettres ou un portail tout au bout du chemin de votre immense propriété, ou encore un capteur de température dans une cabane au fond du jardin...
Comme exemples, nous allons nous concentrer sur un capteur de température/Humidité, un capteur d'ouverture de porte et une télécommande sans fil à boutons (voir plus loin).
Choix de réseau
Mais tout d'abord, il va falloir choisir un réseau pour y connecter nos appareils. Comme on l'a vu dans l'article cité précédemment, il existe 3 types de réseau.
Les réseaux privés ne nous concernent pas ici, mais le principe de connexion avec Home-Assistant présenté plus bas reste valable. Les réseaux commerciaux ne seront pas non plus considérés ici, car leurs conditions d'accès les réservent aux professionnels. Nous allons donc nous concentrer sur les réseaux partagés.
Les réseaux partagés ne sont pas très nombreux et je vais évoquer les trois plus connus et importants. Il en existe d'autres, mais très limités, alors que les trois cités ci-dessous ont une couverture à peu près mondiale maintenant.
- Hélium (Helium & LoRaWAN) : réseau américain relativement récent sur le marché et dont le réseau héberge également une blockchain. Il est possible d'acheter des bornes LoRa spécifiques pour le réseau Helium. Elles minent de la crypto-monnaie en même temps, et l'opérateur rétribue par ailleurs en crypto-monnaie ceux qui font tourner une borne LoRa Helium.
Helium permet une utilisation gratuite pour un usage personnel avec un maximum de 10 appareils ce qui est déjà pas mal pour un appartement ou une maison de taille classique ! Vous pouvez au choix utiliser la couverture existante si une ou plusieurs bornes couvrent votre zone (Helium Coverage) ou installer une borne LoRa connecté au réseau Helium. Le choix et l'installation d'une borne LoRa feront l'objet d'un article séparé prochainement disponible. - The Things Network (The Things Network) : réseau néerlandais, qui existe depuis une dizaine d'années maintenant. The Things Network (TTN) est le réseau communautaire fourni par The Things Industries, la maison mère, qui propose des services commerciaux aux entreprises concernant le LoRa. Une carte de couverture indicative est présente sur le site tiers TTN Mapper, mais il s'agit d'une carte participative donc il peut y avoir de la couverture même si le site indique le contraire.
- Loriot (Loriot) : réseau suisse qui de façon similaire à TTN propose un service communautaire (limité à 30 appareils par compte) et un service pour les professionnels avec serveur(s) dédié(s). Comme pour les deux précédents, vous pouvez les utiliser gratuitement si vous êtes dans une zone déjà couverte par le réseau concerné, ou installer une "gateway" que vous connecterez à ce même réseau.
Les appareils à connecter
Pour les appareils, on verra donc 3 exemples différents d'appareils :
- Une sonde de température/ambiance de Dragino: LHT65N :
- Une télécommande 4 boutons de RakWireless: Wisnode Button 4K :
- Un détecteur d'ouverture de porte/fenêtre de Dragino: LDS02.
On va dans un premier temps s'occuper de "connecter" notre appareil au réseau LoRa TTN. Une alternative avec Loriot est également présentée.
Nous verrons ensuite comment récupérer les informations de cet appareil dans Home-Assistant avec 2 méthodes : une intégration LoRa et MQTT.
Le principe restera le même quel que soit le type d'appareils LoRa si ce n'est qu'il aura plus ou moins de données transmises (par exemple : un tracker LoRa transmettra des coordonnées GPS latitude - longitude et une altitude).
Connexion au réseau LoRa
Identification d'un appareil LoRa
Dans un système LoRa, chaque appareil est identifié par un trio de "codes". Ils permettent l'appairage initial de l'appareil avec son réseau LoRa et la communication ensuite.
Ces 3 codes sont communiqués par le fabricant de l'appareil (en général sur un sticker À NE PAS PERDRE), et ils sont modifiables sur certains appareils en se connectant directement dessus (possible par exemple parmi nos appareils de test dans le capteur de température/humidité et dans la télécommande, mais pas dans le détecteur d'ouverture).
Voyons ce que sont ces 3 codes :
- DevEUI: cet identifiant (de la forme suivante : A0 B1 C2 D3 E4 F5 01 23) est l'équivalent de l'adresse MAC pour une carte réseau. Elle permet d'identifier de façon unique un appareil, il est donc préférable d'éviter de la modifier pour éviter tout conflit éventuel dans le réseau LoRa (le fabricant s'assure que cet identifiant est unique).
- JoinEUI (anciennement appelé AppEUI) : cet identifiant, du même format que le DevEUI, permet d'identifier le serveur qui va gérer la demande de pairage de l'appareil avec le réseau LoRa. Il est en général identique pour tous les appareils d'un même type, voire d'un même fabricant.
- AppKey: cet identifiant (de la forme : A0 B1 C2 D3 E4 F5 01 23 45 67 89 0A BC DE F1 23), souvent composé de la concaténation du DevEUI et du JoinEUI, va servir de clé d'encryption pour la communication avec le serveur Lora. C'est ce qui garantira la confidentialité de la communication radio et doit être gardé confidentiel.
Appairage
Une fois en possession d'un appareil LoRa, ses identifiants et en étant dans une zone couverte par le réseau LoRa choisi (soit par votre propre gateway connecté au dit réseau soit par la couverture existante de ce réseau), on va devoir "appairer" l'appareil avec le serveur LoRa (Join en anglais). On va donc se connecter à la console de l'opérateur LoRa pour ajouter l'appareil et que ce dernier puisse alors communiquer.
Nous mettrons en parallèle ici la configuration dans TTN (The Thing Network) et Loriot (le système suisse). A vous de choisir en fonction de votre couverture.
Pour TTN, la console est accessible sur ces pages :
- Console EU1 pour le serveur européen,
- Console NAM1 pour l'Amérique du Nord et Sud,
- Console AU1 pour l'Asie et l'Australie.
Pour Loriot, on y accédera par exemple à cette adresse pour leur serveur à Amsterdam : Console EU2.
Une fois connecté à la console, on va créer une Application. Cela permettra de classer les appareils de votre compte. Vous pouvez vous organiser comme vous voulez, cela n'a aucune conséquence technique.
Une fois choisi un id (en minuscule sans espace) et une éventuelle description, vous allez alors arriver sur l'interface permettant d'ajouter les appareils dans le réseau LoRa.
La console TTN vous guide tout le long du processus afin de rendre cela le plus simple possible. Une possibilité est proposée d'ajouter un appareil en scannant son code QR (mais je n'ai jamais rencontré d'appareils avec un QRCode compatible...).
Loriot dispose lui d'une interface plus technique où c'est à vous à définir la version de LoRa implémentée par votre appareil au lieu d'utiliser une liste d'appareils déjà connus comme TTN.
Pour TTN (à gauche ci-dessus) : il suffit de choisir la marque, le modèle et la région Radio parmi les choix proposés pour facilement rajouter un appareil.
La région Radio doit correspondre à la zone géographique où vous êtes (voir LoRa: qu’est-ce que c’est ? à quoi ça sert ? si besoin) et à la fréquence radio de votre appareil.
Pour Loriot (à droite ci-dessus) : il faudra choisir juste la version de Lora implémenté par l'appareil (se reporter à la documentation de l'appareil) et le "mode de Join/Enrollment".
Par défaut, on utilisera toujours le mode OTAA (seul mode accessible sur TTN/Loriot) qui est le mode le plus sécurisé pour le LoRa. Il existe un autre mode ABP qui est très peu utilisé et beaucoup moins sécurisé.
Il n'y a plus maintenant qu'à saisir chacun des 3 identifiants dans l'interface pour enregistrer l'appareil dans le réseau.
À partir de là, il va falloir provoquer, sur l'appareil ajouté, une commande de JOIN. C'est un message spécial qui permet un appairage unique entre l'appareil et le réseau LoRa : à partir des identifiants, un nouveau jeu de clé d'encryptage va être généré et stocké dans l'appareil, puis utilisé pour les messages suivants qu'il enverra.
- Pour notre capteur de température, il suffira d'appuyer quelques secondes sur l'unique bouton pour provoquer l'envoi de la commande JOIN.
- Pour la télécommande 4 boutons, il suffira d'appuyer quelques secondes sur le bouton 2 pour provoquer la commande JOIN.
- Pour le détecteur d'ouverture, il suffira de provoquer une action du capteur (balader l'aimant le long du capteur) et l'appareil va automatiquement JOIN le réseau LoRa.
Ci-dessous ce que vous verrez apparaitre dans la console TTN si le JOIN réussit.
En cas d'erreur, il faut vérifier que les 3 identifiants ont bien été saisis sans erreur, que vous êtes bien dans une zone couverte par TTN/Loriot, que votre appareil est bien alimenté et qu'il est bien dans la bonne fréquence pour votre région géographique.
Remarque : avec un réseau commercial (ici Swisscom à titre d'exemple), le principe reste très similaire. On donne un nom à l'appareil, on indique les DeEUI, JoinEUI et AppKey et le tour est joué.
Décodeur de messages
Il nous reste désormais un dernier point à configurer qui est le "payload decoder" ou décodeur de messages. En effet, comme on l'a vu précédemment, les messages LoRa sont cryptés et encodés. Il va donc falloir les décoder pour pouvoir les rendre exploitables. Pour le moment, si vous regardez dans la console les messages reçus, le payload est de la forme ci-dessous, ce qui n'est pas vraiment lisible.
"frm_payload": "AUcNABQEsAPoAAAAAAAAAE2W"
On va donc se rendre dans l'onglet "Payload Formatters" où il est possible de saisir un Javascript ou de se connecter avec un service externe pour le décodage.
Si vous avez choisi le bon appareil lors de l'ajout dans la console TTN, le bon "formatter" sera par défaut sélectionné. C'est le cas ici pour nos appareils RakWireless comme Dragino, ce qui simplifie les choses. Dans le cas contraire, il faudra récupérer le Javascript adéquat de la part du fabricant que vous copierez/collerez dans l'onglet Uplink (messages des appareils vers le serveur LoRa).
Et là miracle, le payload, qui était jusque-là illisible, devient soudainement beaucoup plus clair avec les différentes valeurs retournées par l'appareil.
Une fois la connexion établie entre TTN (ou Loriot) et Home-Assistant, on va donc maintenant pouvoir exploiter cela dans Home-Assistant.
Intégration Home Assistant
Deux solutions se présentent à nous :
- utiliser une intégration qui est une solution simple et rapide, mais avec des restrictions/contraintes et qui n'est possible au jour d'aujourd'hui qu'avec TTN,
- ou utiliser la solution MQTT un peu plus compliquée, mais permet beaucoup plus de choses et utilisable avec tous les serveurs LoRa.
Intégration HACS TTN
Nous n'allons pas utiliser l'intégration TTN officielle, car cette dernière a de nombreuses restrictions dues aux contraintes des intégrations officielles Home-Assistant. Nous allons utiliser la version non officielle, faite par le même développeur, et qui s'installe facilement via HACS :
https://github.com/angelnu/home_assistant_thethingsnetwork
Une fois installée via HACS, il suffira de l'ajouter comme une intégration officielle (Paramètres -> Intégration et chercher "The Things Network".
Il n'y aura plus qu'à saisir l'application ID précédemment crée dans la console TTN et la clé d'API, cette dernière doit être créée sur la page de l'application dans la console TTN (attention à sauvegarder la clé, car elle n'est plus consultable ensuite).
Il faudra également toujours sur la page de l'application dans la console TTN activer la Storage Integration (menu Intégrations -> Storage Integration et activer la coche, tout simplement).
Après quelques minutes, parfois immédiatement, vos appareils ajoutés dans TTN vont apparaitre dans l'intégration TTN:
Si l'on sélectionne notre appareil, on a alors le détail des capteurs et autres données que retourne l'appareil en question. On y voit alors le détail de toutes les informations retournées par l'appareil y compris son niveau de batterie (à gauche le capteur de température/humidité, et à droite le détecteur d'ouverture de porte).
Avantages/Limitations/Inconvénients de cette intégration:
- Facile et rapide à configurer.
- les appareils qui ne retournent pas de données comme la télécommande 4 boutons n'apparaissent pas et donc ne peuvent pas être utilisées via cette intégration.
- l'intégration utilise l'API de TTN pour communiquer et cette dernière tombe en panne de temps en temps ou a une grosse latence.
- Compatible uniquement avec le réseau LoRa TTN.
- l'intégration ne pouvant pas par elle-même détecter le type des données retournées par les appareils, il est souvent utile de passer par le menu Configurer de l'intégration et choisir "Fields" puis choisir le paramètre à modifier pour le configurer correctement.
Intégration via MQTT
Ici on va recourir à la bonne vieille solution du broker MQTT.
Pour ceux qui ne connaîtraient pas encore MQTT, il s'agit d'un dispositif logiciel pour distribuer des courts messages, typiquement pour l'IoT. Il s'agit d'un protocole très léger mais qui peut être sécurisé si besoin est et qui bien sûr est nativement géré par HA ! Pour ceux qui voudraient en savoir plus sur MQTT, le site officiel en donne une présentation détaillée. MQTT est un système normalisé désormais.
Première étape (probablement inutile pour la plupart d'entre vous): installer le module complémentaire/add-on MQTT Broker.
Une fois installé, s'assurer que les options suivantes sont activées dans le module (il faudra également créer le dossier mosquitto dans le dossier /share de HA):
active: true
folder: mosquitto
Une fois le module complémentaire installé, vous pouvez installer l'intégration officielle MQTT Broker. Elle va automatiquement se configurer pour communiquer avec le broker MQTT précédemment installé.
On va laisser de côté HA un instant pour continuer la configuration côté TTN. Il va falloir se rendre dans la console TTN, dans la rubrique Applications puis choisir l'Application dans laquelle se trouve l'appareil Lora dont on veut récupérer les informations.
On va alors choisir dans le menu de gauche : API puis "Add API key". On lui donne un nom (cela est juste pour nous comme repère), une éventuelle date d'expiration sinon on laisse vide.
Vous pouvez laisser par défaut tous les droits (dans l'absolu seuls Write Downlink application traffic, et Read Application Traffic sont nécessaires).
Il nous reste à récupérer l'ID de l'appareil LORA avec lequel on veut interagir : pour cela, on va aller dans le menu End Devices du menu de gauche et cliquer alors sur l'end-device qui nous intéresse. On pourra alors récupérer l'ID de l'appareil.
Désormais il ne nous reste plus qu'à faire un peu de configuration dans HA pour récupérer nos infos d'appareils LoRa.
Tout d'abord, on va relier ou "bridger" le broker MQTT de HA avec celui de TTN. Pour cela, on va devoir créer un fichier bridge.conf pour MQTT qui lui dira à MQTT comment faire la liaison. Ce fichier doit être placé dans votre dossier "share" da HAOS. Ce dossier n'est pas accessible par l'éditeur de fichier de HA, il faut y accéder par le partage de fichiers de HA.
Dans ce dossier share, vous créez s'il n'existe pas un dossier mosquitto et dans ce dossier, vous créez un fichier bridge.conf (un seul fichier suffit pour tous les bridges que vous créerez, il suffit de les lister à la suite les uns des autres !). Ce fichier contiendra les éléments suivants :
connection lenomquejeveux
address eu1.cloud.thethings.network
bridge_protocol_version mqttv311
remote_username iddemondevice@ttn start_type
automatic notifications false
try_private false
remote_password NNSXS.xxxxxxxxxxxxxxxxxxxxxxxx
bridge_insecure true
topic # in 0
cleansession true- lenomquejeveux vous permet de nommer le bridge (c'est purement pour vous et doit être unique pour chaque bridge déclaré dans le fichier bridge.conf)
- eu1... doit être remplacé par le serveur TTN que vous utilisez selon la région du monde où vous vous trouvez
- iddemondevice est à remplacer par l'ID du device précédemment récupéré dans la console TTN
- et pour finir dans remote_password, vous y collez la clé d'API que vous avez précédemment générée.
Vous pouvez alors redémarrer le module complémentaire Mosquitto Broker dans HA, et si tout est bien configuré, vous devriez voir cela dans les logs du module complémentaire :
1684589377: Loading config file /share/mosquitto/bridge.conf
1684589377: Warning: Bridge lenomquejeveux using insecure mode.Si vous avez bien ça, c'est parfait, cela veut dire que le broker MQTT de HA communique bien avec celui de TTN et que l'on va automatiquement recevoir les données envoyées par nos appareils LORA.
Il ne nous reste plus qu'à extraire les données qui vous intéressent pour les exploiter dans HA. La structure du message reçu de TTN est en JSON, cela va donc être assez simple à récupérer.
Voici un cas simple et concret avec notre capteur de température/humidité LHT-52. En examinant les messages envoyés par la console TTN, voici ce qui apparaît en dehors des entêtes et autres informations qui ne nous intéressent pas :
On va alors pouvoir ajouter un capteur MQTT dans HA qui extraira automatiquement la valeur qui nous intéresse de la façon suivante :
"sonde-ambiance" doit être remplacé par l'ID de votre application dans la console TTN.
Pour réduire le risque d'erreur et pour ceux qui sont sous Android (il doit probablement exister l'équivalent sous IOS mais je n'ai pas d'appareil IOS), il existe une application très pratique qui s'appelle MQTT Snooper qui vous permet de voir tous les messages MQTT sur un broker.
Une fois installé l'application, vous ajoutez un nouveau host (vous indiquez comme serveur le serveur de TTN, en username l'id de l'application TTN suivi de @ttn et en mot de passe la clé d'API).
Une fois connecté, vous verrez automatiquement passer les messages MQTT émis par TTN et facilement reconnaître les champs que vous souhaitez extraire.
Limitations/Inconvénients de l'intégration MQTT :
- Compatible avec tous les appareils LoRa et permet également d'envoyer des Downlinks pour paramétrer des appareils LoRa.
- Compatible avec la grande majorité des serveurs Lora (TTN, Helium, Chirpstack), pas compatible directement avec Loriot.
- Nécessite un peu plus de manipulations pour être configuré et utilisable avec Home-Assistant.
- Communication instantanée avec les appareils LoRa car le MQTT est implémenté directement dans le serveur LoRa, contrairement à des API qui parfois peuvent souffrir de latence/panne.
Conclusion
Voilà, vous avez (je l'espère) réussi à connecter un premier appareil via LoRa et à le faire communiquer avec Home-Assistant.
Vous avez désormais accès à un outil très pratique pour des capteurs déportés ou détecteurs sans le problème de la portée Wifi, ou avoir à passer un câble.
Cet article est également publié sur mon blog:
Vincèn PUJOL
