La librairie Homie est devenue très populaire pour le développement rapide d’objets connectés à base d’ESP8266 qui communiquent par messages MQTT. Cette librairie (page GitHub) est développée et maintenue par Marvin Roger (page personnelle). Homie est une librairie qui prend en charge la connexion au réseau Wi-Fi, l’authentification à un serveur MQTT et même la mise à jour sans fil par MQTT (qu’il me reste à découvrir). La documentation (page officielle) est un modèle du genre. Elle n’est cependant disponible qu’en anglais (pour le moment ?) et s’adresse à un public qui maitrise déjà très bien la programmation. Nous allons aborder Homie dans ce tutoriel de façon très assez pratique étape par étape.

Installer la librairie Homie et ses dépendances sur l’IDE Arduino

Pour ce tutoriel, j’ai installé la version 2 de la librairie (voir le paragraphe suivant pour connaître les différences avec la v1.5). Elle n’est pas disponible depuis le gestionnaire de libraire de l’IDE Arduino. Téléchargez la version qui vous intéresse

• version 1.5
• version 2 (développement)

Ne décompressez pas l’archive. Allez au menu Croquis / Inclure une bibliothèque / Ajouter la bibliothèque .ZIP et sélectionnez le fichier ZIP de la librairie Homie que vous venez de télécharger

Il faut ensuite installer quatre librairies supplémentaires :

• Bounce2 : elle est disponible depuis le gestionnaire de librairies
• ArduinoJson : également disponible depuis le gestionnaire de librairies
• ESPAsyncTCP (version >= c8ed544) : à télécharger et à installer manuellement depuis le ZIP
• AsyncMqttClient : idem

C’est tout. Vous êtes prêt à développer avec la librairie Homie

Différences entre la version 1.5 et la version 2

Avant d’aller plus loin, voici les principales différences entre les deux version actuelles. La version stable est la v1.5. La version 2 est en cours de développement mais elle est utilisable. Les différences actuelles se situent surtout au niveau du formalisme de certaines fonctions qui a évolué (la liste complète ici) :

• Homie.setFirmware(name, version) devient Homie_setFirmware(name, version)
• Homie.setBrand(brand) devient Homie_setBrand(brand)
• Homie.registerNode() doit être supprimé. Le Nodes sont maintenant automatiquement (automagically) enregistrées
• Serial.begin() doit être maintenant explicitement démarré
• Supprimer HOMIE_OTA_MODE
• Homie.setNodeProperty() change complètement. La syntaxe Homie.setNodeProperty(node, “property”, “value”, true) est remplacée par Homie.setNodeProperty(node, “property”).setRetained(true).send(“value”).

Premier test

La librairie Homie intègre plusieurs exemple. Par le tutoriel, nous allons tester l’exemple DoorSensor. Ici, j’ai indiqué la broche D1 sur laquelle j’ai branché un micro switch. Par rapport au code initial, la commande pinMode utilise la résistance de PULLUP interne. Sinon vous pouvez ajouter une résistance de rappel à votre montage.

#include <Homie.h>

const int PIN_DOOR = D1;

Bounce debouncer = Bounce(); // Bounce is built into Homie, so you can use it without including it first
int lastDoorValue = -1;

HomieNode doorNode("door", "door");

void loopHandler() {
  int doorValue = debouncer.read();

  if (doorValue != lastDoorValue) {
     Homie.getLogger() << "Door is now " << (doorValue ? "open" : "close") << endl;

     doorNode.setProperty("open").send(doorValue ? "true" : "false");
     lastDoorValue = doorValue;
  }
}

void setup() {
  Serial.begin(115200);
  Serial << endl << endl;
  pinMode(PIN_DOOR, INPUT_PULLUP);
  //digitalWrite(PIN_DOOR, HIGH);
  debouncer.attach(PIN_DOOR);
  debouncer.interval(50);

  Homie_setFirmware("awesome-door", "1.0.1");
  Homie.setLoopFunction(loopHandler);

  doorNode.advertise("open");

  Homie.setup();
}

void loop() {
  Homie.loop();
  debouncer.update();
}

Comme vous pouvez le constater, il n’y a aucun paramètre dans le code. Tout se fait via un fichier de configuration au format JSON. Il y a plusieurs possibilités pour configurer Homie :

• Créer un dossier data dans le répertoire du projet et y inclure un fichier config.json. Il faudra ensuite téléverser le dossier data dans un 2ème temps dans la zone mémoire SPIFFS. Pour en savoir plus, vous pouvez lire cet article.
• Utiliser l’utilitaire de configuration. Il est disponible sous la forme d’un site internet à cette adresse ou utiliser l’application Android. Dans les deux cas, il faudra se connecter au point d’accès créé par Homie automatiquement au démarrage
• On pourra enfin envoyer une nouvelle configuration en HTTP à l’aide de la commande curl suivante par exemple

curl -X PUT http://192.168.123.1/config --header "Content-Type: application/json" -d @config.json

C’est très pratique, mais c’est aussi un peu déroutant lorsqu’on débute.

Configuration des paramètres

Ici, je vous propose d’utiliser la méthode similaire au framework ESP Easy et à la librairie WiFiManager. Nous allons nous connecter au point d’accès créé par Homie au démarrage. Homie créé un point d’accès jusqu’à ce que des paramètres ce connexion au réseau Wi-Fi existent.

Sélectionnez votre carte ESP8266, le port sur lequel elle est connectée puis téléversez le croquis. Ouvrez le Terminal pour récupérer l’identifiant attribué et vérifier au passage que tout fonctionne comme prévu.

Si vous tentez de vous connecter au point d’accès créé par Homie, vous allez obtenir cette page d’erreur (UI bundle not loaded…) qui vous indique qu’aucun fichier de configuration n’existe. Re-connectez-vous à votre réseau Wi-Fi.

Ouvrez cette page http://setup.homie-esp8266.marvinroger.fr/

Connectez vous au point d’accès

Enfin, faites un reset sur l’ESP8266. Dès qu’il sera de nouveau connecté au réseau Wi-Fi, la page va s’actualiser automatiquement. La première page affiche les principales informations :

• Identifiant (ID) du module ESP8266
• Version de la librairie Homie
• Nom du firmware : le nom donné au programme Arduino
• Version : la version que vous avez donné à votre programme Arduino
• La liste des Nodes : ici, il n’y en a qu’un : Door. C’est un détecteur d’ouverture de porte. Vous pouvez modifier son nom et attribuer un type qui sera publié dans le message $type.

Normalement vous n’avez rien à modifier ici puisque tout est contenu dans le programme Arduino. Allez à l’écran suivant avec Next. L’écran suivant permet de choisir le réseau Wi-Fi sur lequel se connecter et indiquer le mot de passe.

L’écran suivant permet de configurer les paramètres de connexion au serveur (broker MQTT) :

• Adresse IP ou URL si vous utiliser un broker en ligne (lisez cet article pour une sélection)
• Port : 1883 par défaut
• Préfixe du topic. Par défaut, tous les messages commencerons par /homie . N’indiquez par le nom du device ici, il faudra l’indiquer à l’écran suivant et il est automatiquement ajouté par Homie dans le Topic.
• Si vous avez mis en place un authentification par mot de passe, indiquez l’utilisateur et son mot de passe

Sur le dernier écran, vous pouvez indiquer le nom de l’objet. C’est fortement recommandé pour retrouver les messages correspondant sur un serveur domotique par exemple. C’est le champ Device ID qui sera utilisé par Homie pour construire le Topic.

Voilà, la configuration est terminée. Les paramètres sont sauvegardés dans la zone mémoire SPIFFS dans un fichier nommé config.json. Une fois que l’ESP8266 a redémarré, le point d’accès n’est plus accessible.

Récupérer vos premiers messages MQTT

Suivez ce tutoriel pour installer un broker Mosquitto sur votre machine.

Ouvrez un Terminal et exécutez la commande suivante

mosquitto_sub -h localhost -t "homie/#" -v

Si vous avez mis en place une authentification, exécutez cette commande après avoir modifié le nom d’utilisateur et le mot de passe.

mosquitto_sub -h localhost -t "homie/#" -v -u "UTILSATEUR" -P "MOT-DE-PASSE"

Signification des paramètres :

• -h : option pour indiquer l’adresse du serveur MQTT. Ici, il est sur la machine de test.
• -t : le topic sur lequel on démarre la souscription. Le jocker # permet d’indiquer que l’on souhaite souscrire à toute l’arborescence située après lui
• -v (verbose) : permet d’indiquer le chemin du topic. Sinon, il n’y a que les messages qui seront affiché. Pas toujours pratique si on doit repérer un topic en particulier pour l’utiliser par ailleurs
• -u : option permettant d’indiquer l’utilisateur
• -P : et son mot de passe d’authentification

Après quelques instants, voici les premiers messages qui arrivent en provenance du détecteur d’ouverture de porte. Ici, le programme utilise la librairie Bounce2 qui permet d’améliorer la détection d’appui sur un interrupteur. Cette librairie évite le problème de “rebond” en détectant le front montant / descendant durant un certain temps (ici 50ms) pour déterminer sur un interrupteur a été appuyé. Vous pouvez tester l’interrupteur (ou un micro switch). Dès qu’il est appuyé ou relâché, un message MQTT est envoyé par Homie.

Comme vous pouvez le constater, Homie est très bavard ! Il envoi de très nombreux Topics très régulièrement (en plus de vos propres événements). Cette page détaille tous les messages publiés par la librairie.

Il y a plusieurs autres exemples pour découvrir le fonctionnement d’Homie. Dans le prochain tutoriel, nous verrons comment inclure des objets Homie sur les principaux serveurs domotiques. Si vous devez développer des objets qui communiquent à l’aide de messages MQTT, Homie est réellement un librairie à envisager. A elle seule, elle remplace avantageusement les librairies WiFiManager et PubSubClient. Elle permet de s’affranchir de tout le travail de configuration Wi-Fi, re-connexion… donc moins de codage en perspective.

• Inclure un objet connecté ESP8266 + DHT22 + Homie MQTT dans Home Assistant (HASS)
• Premier projet Homie ESP8266, publier en MQTT des mesures d’une sonde DHT22
• Bien débuter avec la librairie Homie (MQTT) pour objets connectés à base d’ESP8266