LOCODUINO

Cet article est le plus compliqué de la série. En effet, il vous faudra installer Mosquitto sur votre machine et le configurer et également installer et utiliser MQTT Explorer. Suivez donc bien les explications sans sauter d’étape.

MQTT est l’acronyme de Message Queuing Telemetry Transport. Il s’agit d’un protocole de communication basé sur le paradigme du publier / s’abonner et l’échange de messages. C’est le standard des applications de l’IoT. Pour mettre en place un système MQTT, il faut un serveur (appelé aussi Broker MQTT, terminologie que nous emploierons dans le reste de cet article) et des clients.

Un message est constitué d’un topic et d’un payload. Les deux sont des chaines de caractères. Le topic est l’identifiant du message. Par exemple, dans notre application d’éclairage de réseau, on pourrait avoir le topic Commande/intensite pour les messages à destination des ESP32 qui pilotent les rubans de LED avec comme payload une valeur de 0 à 65535 [1]. De même on aurait un topic Commande/allume pour demander d’allumer ou d’éteindre le ruban avec comme payload true ou false. Les ESP publieraient la valeur de PWM qu’ils appliquent sous le topic Eclairage/PWMx, où x est le numéro de l’ESP, avec pour payload un entier de 0 à 100.

Le Broker MQTT reçoit les demandes d’abonnement des clients et maintient la liste des clients abonnés à chaque topic et, à chaque réception message de publication d’un topic, il diffuse un message à chacun des abonnés du topic. C’est donc un système centralisé. La figure 1 montre cet exemple.

Figure 1 : Exemple de système MQTT

Chaque client peut publier des topics, soit à intervalles réguliers (messages périodiques), soit ponctuellement. Afin de (tenter de) garantir (dans une certaine mesure) qu’un message est bien délivré à l’ensemble des abonnés, MQTT définit 3 niveaux de qualité de service (QoS) :

• QoS 0 : Un message est reçu par un client 1 seule fois ou pas du tout. Le client n’envoi pas de réponse au Broker pour indiquer qu’il a reçu le message ;
• QoS 1 : Un message est reçu par un client au moins 1 fois. Le client doit envoyer une réponse au Broker pour indiquer qu’il a reçu le message. Si il ne le fait pas, le Broker envoie le message à nouveau ;
• QoS 2 : Un message est reçu exactement 1 fois par un client.

La QoS 2 n’est, à ma connaissance, pas disponible sur les clients MQTT qui fonctionnent sur ESP32. Si on conçoit un système où les messages sont envoyés périodiquement, la QoS 0 est suffisante et c’est ce que nous allons mettre en œuvre.

L’avantage manifeste de MQTT est de disposer, sur tablette ou téléphone, de clients permettant de construire des interfaces graphique avec des boutons ou des curseurs, entre autres, afin de publier des topic MQTT.

Le Broker MQTT

Avant toute chose il faut installer un Broker MQTT. Le Broker le plus répandu est Mosquitto et c’est celui que j’ai utilisé. Une installation permanente à la maison nécessite d’avoir une machine allumée 24h sur 24h et la meilleure solution est sans doute d’utiliser un petit ordinateur monocarte fonctionnant sous Linux comme un Raspberry Pi Zéro W (W pour WiFi) ou Raspberry Pi Zéro 2 W, plus puissant. Mais pour faire des essais, installer Mosquitto sur votre ordinateur est plus pratique.

Installation sur Mac OS X

Je suppose que vous avez un Mac OS raisonnablement récent, c’est à dire version 10.15 (Catalina) qui est sorti en 2019. Le plus facile pour installer Mosquitto est de le faire via Homebrew. Tout d’abord, et si ce n’est pas déjà fait, nous installons Homebrew via le terminal comme indiqué sur leur page d’accueil.

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Puis, demander à Homebrew d’installer Mosquitto

brew install mosquitto

Suite à quoi Mosquitto (version 2.0.14 au moment où j’écris ces lignes) est installé. Il n’est pas forcément nécessaire de faire fonctionner Mosquitto au démarrage de votre machine car cette installation ne sert que pour des essais.

Le fichier de configuration de Mosquitto

Cette section s’applique à toutes les plateformes : Mac OS X, Linux et Windows.

Avant de lancer Mosquitto il faut lui fournir un fichier de configuration minimum, mosquitto.conf, permettant à des clients de se connecter sur le réseau local :

listener 1883
allow_anonymous true
log_timestamp_format %Y-%m-%d T %H:%M:%S

La première directive dit à Mosquitto d’accueillir les clients MQTT sur le port 1883, la deuxième permet les connexions anonymes [2] et la troisième spécifie le format de la date sur le journal d’activité. Ce fichier est utilisable tel quel sur Linux ou Windows et peut être téléchargé ci-dessous.

Ensuite on lance Mosquitto dans le Terminal et en fixant le répertoire courant à l’emplacement où se trouve votre fichier de configuration :

/opt/homebrew/opt/mosquitto/sbin/mosquitto -c mosquitto.conf

Mais l’emplacement où Homebrew installe les logiciels peut changer en fonction des versions de Mac OS X. La ligne de commande ci-dessus est valable pour Mac OS X 11 mais, par exemple, pour la version 10.13 la commande est :

/usr/local/opt/mosquitto/sbin/mosquitto -c mosquitto.conf

La commande suivante permet de savoir où Homebrew installe Mosquitto :

brew --prefix mosquitto

Il suffira de compléter par /sbin/mosquitto -c mosquitto.conf.

Les lignes présentées à la figure 2 devraient s’afficher :

Figure 2 : Journal de Mosquitto au lancement.

Ne fermez pas le terminal ! Cela bloquerait le fonctionnement de Mosquitto !

Installation sur Linux

Le déroulé des opérations devrait être aussi direct que sur Mac OS X mais, au moment où j’écris ces lignes, la version de Mosquitto sur la plus populaire des distributions, à savoir Ubuntu, est la 2.0.11. Malheureusement j’ai eu quelques soucis de connexion avec cette version à partir des ESP et je ne la recommande pas. En attendant que la mise à jour arrive dans les dépôts Ubuntu ou Raspbian (Debian sur Raspberry Pi), il faut compiler Mosquitto 2.0.14 à partir des sources. Il faut donc télécharger les sources à partir du site de Mosquitto. Mosquitto est simple à compiler mais il faudra installer gcc (sudo apt-get install gcc) ainsi que les bibliothèques nécessaires (voir la procédure sur le GitHub de Mosquitto).

Un fois l’archive déballée, vous obtenez un répertoire mosquitto-2.0.14. Il suffit de se rendre dans ce répertoire avec le Terminal et de taper make. La compilation peut prendre un certain temps sur Raspberry Pi Zéro W.

Une fois obtenu l’exécutable, il se trouve dans le sous répertoire src, la procédure est la même qu’avec Mac OS X mais évidemment le chemin est différent. Par exemple sur mon Raspberry Pi le chemin est /home/pi/Documents/Mosquitto/mosquitto-2.0.14/src/mosquitto.

Installation sur Windows

Pour installer MQTT sur Windows, il faut se rendre sur la page de téléchargement de Mosquitto et choisir le paquet qui convient à votre machine. Il s’agit normalement du paquet pour Windows 64 bits si vous avez un PC raisonnablement récent. Après avoir exécuté ce programme d’installation, Mosquitto est installé dans C:\Program Files (x86)\mosquitto. Dans ce répertoire vous trouverez également mosquitto.conf. renommez le en Mosquitto-origine.conf pour le conserver et copier dans ce répertoire le mosquitto.conf que vous avez téléchargé (voir la note dans la section consacrée à l’installation sur Mac OS X).

Il faut ensuite démarrer Mosquitto. Tout d’abord, lancez l’invite de commandes en mode administrateur comme montré à la figure 3.

Figure 3 : Lancement de l’invite de commande en mode administrateur

Tapez ensuite la commande net start mosquitto. Un message indiquant que le Broker est démarré devrait s’afficher. Quand vous aurez fini les tests, il est raisonnable d’arrêter Mosquitto avec un net stop mosquitto.

Figure 4 : Démarrage de Mosquitto

Le pare-feu de Windows

Pour que MQTT Explorer et l’ESP puissent se connecter au Broker Mosquitto, il faut autoriser cette accès dans le pare feu de Windows. Je ne vais pas ici expliquer la manière d’autoriser une application, Mosquitto en l’occurrence, car l’exposé prendrait autant de figures que le reste de l’article. Je vous renvoie à une page explicative. Toutefois, comme Mosquitto n’est pas dans la liste, il faut cliquer sur le bouton Autoriser une autre application... Puis sur le dialogue qui s’affiche, cliquer sur Parcourir... (figure 5).

Figure 5 : Ajout d’une nouvelle application autorisée dans le pare-feu

Dans le dialogue qui s’affiche, naviguez jusqu’au répertoire qui contient Mosquitto et cliquez Ouvrir (figure 6). Assurez vous ensuite que mosquitto est bien coché dans la liste des applications autorisées.

Figure 6 : Navigation jusqu’à mosquitto

Il est temps de tester

Testons maintenant que le Broker est fonctionnel. Téléchargez et installez MQTT Explorer. Pour Mac OS X, il est également disponible sur l’Apple AppStore. MQTT Explorer est un client MQTT permettant d’examiner les messages qui transitent. Par défaut, il s’abonne automatiquement à tous les topics, ce qui est très pratique pour débugger.

Au lancement, MQTT Explorer affiche une fenêtre de connexion (figure 7) invitant à spécifier comment se connecter au Broker.

Figure 7 : Connexion au Broker avec MQTT Explorer

En haut à gauche vous avez deux serveurs de test préconfigurés. Nous allons ajouter le notre :

1. Cliquez le + en haut à gauche ;
2. Entrez un nom pour cette nouvelle connexion, ici Local ;
3. Désactivez la validation de certificat, nous n’allons pas employer une connexion chiffrée ;
4. Entrez le nom localhost qui signifie « la machine où j’exécute MQTT Explorer » qui se trouve être celle où fonctionne Mosquitto ;
5. À gauche vous devriez voir le pédigrée de cette nouvelle connexion ;
6. Enfin, cliquez le bouton « Connect » en bas à droite.

Si tous les paramètres ont été correctement saisis, la fenêtre montrée figure 8 s’affiche.

Figure 8 : MQTT Explorer est connecté au Broker

Mosquitto publie une hiérarchie de topics informant sur son activité. Ces topics sont préfixés par $SYS/broker/. Par exemple, on voit ici pointé par la flèche rouge, le topic $SYS/broker/version donnant la version du Broker Mosquitto auquel MQTT Explorer est connecté.

Si vous avez un affichage conforme à ce qui est exposé ici, tout est opérationnel et nous pouvons passer à l’étape suivante.

L’ESP32 comme client MQTT

La bibliothèque MQTT pour Arduino la plus utilisée est PubSubClient. Vous la trouverez dans le gestionnaire de bibliothèques de l’IDE. Il faut donc tout d’abord installer cette bibliothèque pour pourvoir compiler notre sketch d’essai. En tapant PubSubClient dans le champ de recherche, plusieurs items sont proposés. La bonne est celle de Nick O’Leary (voir figure 9).

Figure 9 : Installation de la bibliothèque PubSubClient

Nous allons modifier notre classe Connection pour lui adjoindre ce qui manque pour établir et maintenir le connexion avec le Broker MQTT.

Pour mettre en place un client MQTT, nous avons besoin de deux objet. Le premier est une instance de WiFiClient qui permet d’établir la connexion bas niveau et le second est une instance de PubSubClient qui est le client MQTT. La méthode setCallback du client MQTT permet d’indiquer une fonction pour recevoir les messages envoyés par le Broker et la méthode subscribe permet de s’abonner à un Topic.

La bibliothèque est d’abord incluse :

#include <PubSubClient.h>

Ces deux objets sont ajoutés à notre classe Connection :

  static WiFiClient sNet;
  static PubSubClient sClient;

Nous avons également besoin du nom mDNS du Broker (sans le .local) et de son adresse IP :

  static char *sBrokerName;
  static IPAddress sBrokerIP;

Découvrir l’IP du Broker à partir de son nom utilise le Multicast DNS dont nous avons déjà parlé des « Éclairer le réseau (2) - Connexion au WiFi et Multi Cast DNS ». Connaître le nom du Broker, c’est à dire celui de votre machine, dépend de son système d’exploitation. Avec Mac OS X, il est indiqué dans les Préférences Système à la section Partages (voir figure 10).

Figure 10 : Localisation du nom Multicast DNS sous Mac OS X

Ou bien, une simple commande hostname tapée dans le terminal vous donnera ce nom. C’est aussi le cas avec Linux et avec Windows mais sans le .local.

Pour terminer avec les données de cette classes, nous avons besoin d’un pointeur de fonction pour pointer sur la fonction de réception des messages MQTT de l’application et vers laquelle les messages seront relayés (je rappelle que cette classe Connection est indépendante de l’application) et d’un pointeur de fonction pour que l’application fasse ses souscriptions aux topics MQTT qui l’intéresse au moment décidé par la machine d’état de Connection.

  typedef void (*MessageHandlingFunction)(char *, byte *, unsigned int);
  static MessageHandlingFunction sMessageHandler; 

  typedef void (*SubscriptionFunction)();
  static SubscriptionFunction sDoSubscriptions;

Tout ceci est évidemment instancié et initialisé :

char *Connection::sBrokerName = NULL;
IPAddress Connection::sBrokerIP = {0, 0, 0, 0};
WiFiClient Connection::sNet;
PubSubClient Connection::sClient(Connection::sNet);
Connection::MessageHandlingFunction Connection::sMessageHandler = NULL; 
Connection::SubscriptionFunction Connection::sDoSubscriptions = NULL;

Nous définissons également quatre fonctions dans la classe Connection pour relayer la réception de message et permettre les abonnements. La première est incomingMessage :

  static void incomingMessage(char *inTopic, byte *inPayload, unsigned int inLength);

qui est implémentée de la manière suivante :

void Connection::incomingMessage(char *inTopic, byte *inPayload, unsigned int inLength)
{
  if (sMessageHandler != NULL) {
    sMessageHandler(inTopic, inPayload, inLength);
  }
}

La deuxième est subscribe

  static void subscribe(const char *inTopic);

Qui se contente de relayer la souscription au client MQTT :

void Connection::subscribe(const char *inTopic)
{
  sClient.subscribe(inTopic);
}

La troisième est une fonction privée appelée après que la connection au Broker MQTT soit établie de manière à ce que l’application effectue ses abonnements.

  static void performSubscriptions();

Elle implémentée comme suit :

void Connection::performSubscriptions()
{
  if (sDoSubscriptions != NULL) {
    sDoSubscriptions();
  }
}

Enfin la quatrième permet d’accrocher la fonction d’abonnement et de réception de messages de l’application :

  static void attach(SubscriptionFunction inSubFunction, MessageHandlingFunction inMessageHandler);

Elle consiste juste à recopier les arguments dans les données de la classe.

void Connection::attach(SubscriptionFunction inSubFunction, MessageHandlingFunction inMessageHandler)
{
  sDoSubscriptions = inSubFunction;
  sMessageHandler = inMessageHandler;
}

Nous devons également modifier Connection::setup pour lui passer le nom du Broker :

void Connection::setup(const char *inSsid,
                       const char *inPass,
                       const char *inName,
                       const char *inBrokerName,
                       const char *inOTAPass,
                       const uint32_t inPeriod)
{
  sPeriod = inPeriod;
  sSsid = (char *)inSsid;
  sPass = (char *)inPass;
  sName = (char *)inName;
  sBrokerName = (char *)inBrokerName;
  sOTAPass = (char *)inOTAPass;
}

Et enfin, dans Connection::loop(), nous ajoutons sClient.loop() afin que le client MQTT gère l’arrivée de messages.

L’enchainement des opérations pour établir une connexion avec le Broker consiste à :

1. Demander au système mDNS l’adresse IP du Broker avec l’appel sBrokerIP = MDNS.queryHost(sBrokerName); ;
2. Indiquer au client MQTT cette adresse IP et le port avec l’appel sClient.setServer(sBrokerIP, 1883); ;
3. Indiquer au client MQTT la fonction a appeler quand un message arrive avec l’appel sClient.setCallback(incomingMessage); ;
4. Et enfin se connecter via sClient.connect(sName).

On peut également changer les paramètres de keep alive. À intervalles régulier, le client informe le Broker qu’il est toujours vivant. Si le Broker n’a pas reçu ce signal du Client depuis la durée du keep alive, il ferme la connexion. J’ai constaté que PubSubClient a un keep alive par défaut de 15s alors que les autres client MQTT (téléphone, ordinateur) on un keep alive de 60s. Je pense qu’il est donc préférable de régler ce paramètre à 60s pour l’ESP32. La même remarque vaut pour un autre paramètre, le socket timeout qui fixe combien de temps le client attend la fin d’un message incomplet. Il s’agira donc d’appeler avant de se connecter les deux méthodes suivantes : sClient.setKeepAlive(60) et sClient.setSocketTimeout(60).

Pour la dernière fois, nous allons modifier notre machine à états qui gère la connexion. Nous allons ajouter un état MQTT_OK qui sera l’étape qui suit l’OTA. Avec le client MQTT il est possible de tester que la connexion avec le Broker est fonctionnelle via la méthode connected() de l’objet sClient. En cas de perte de connexion avec le Broker, la machine à état retournera dans l’état OTA_OK. La machine à états mise à jour est présentée à la figure 11.

Figure 11 : Machine à états définitive avec la gestion du MQTT

Testons avec une application simple

Il est temps de tester toute cette infrastructure que nous avons mis en place. Le but de cette petit application sur l’ESP est de s’abonner à un topic amplitude qui sera publié par MQTT Explorer et de publier une sinusoïde sin(t), où t est bien entendu le temps, et de l’amplitude spécifiée, sous le topic sinus.

Voyons voir tout d’abord du côté de l’ESP.

L’application sur l’ESP

Bien évidemment, nous n’allons pas pouvoir engendrer une sinusoïde à grande fréquence et une période de 10 secondes conviendra tout à fait pour le test. Le temps est récupéré avec la fonction millis() et nous voulons que 2 × 𝛑 fasse 10000 millisecondes. Nous allons donc calculer amplitude * sin ( 2 * PI * (float) millis() / 10000.0) et le publier toutes les 200ms. Cette publication prend donc place dans loop :

void loop() {
  static uint32_t dateDePublication = 0;

  uint32_t dateCourante = millis();
  if (dateCourante - dateDePublication > 200) {
    Connection::publish(
      "sinus",
      amplitude * sin ( 2 * PI * (float) dateCourante / 10000.0)
    );
    dateDePublication = dateCourante;
  }
  
  Connection::loop();  
}

Ensuite nous devons fournir une fonction pour spécifier les abonnement. Le topic pour fixer l’amplitude sera tout simplement amplitude.

void subscribe()
{
  Connection::subscribe("amplitude");
}

La fonction de réception des messages se charge de convertir la chaine de caractère en un nombre à virgule flottante.

void handleMessage(char *inTopic, byte *inPayload, unsigned int inLength)
{
  /* termine la chaine */
  inPayload[inLength] = '\0';
  amplitude = atof((char *)inPayload);
}

Dans setup(), nous configurons la connection, nous attachons nos fonctions d’abonnement et de réception de message.

void setup() {
  /* Pour le debug */
  DSB(115200);
  /* 
   * Connexion 
   * ssid = nom du réseau WiFi
   * pass = mot de passe du réseau WiFi
   * "Sinus" = nom de l'ESP sur le réseau (.local) et sur le Broker
   * broker = nom du Broker (.local)
   * OTAPass = mot de passe pour le téléversement du logiciel via l'OTA
   *
   * ssid, pass, broker et OTAPass sont définis dans Config.h
   */
  Connection::setup(ssid, pass, "Sinus", broker, OTAPass);
  Connection::attach(subscribe, handleMessage);
}

C’est tout pour l’ESP.

Le sketch complet peut être téléchargé ci-dessous.

Test de la communication

Avant tout, ouvrez le moniteur série à une vitesse de 115200 bauds. Le sketch affiche des informations concernant l’établissement de connexion au réseau WiFi, au mDNS et au Broker.

L’ESP étant démarré et connecté au Broker, il s’agit maintenant d’examiner son activité avec MQTT Explorer. Une petite vidéo vaut mieux, dans ce cas, qu’un long discours. Une petite précision : pour connaître la valeur d’un topic et l’afficher graphiquement, il faut le sélectionner dans l’arborescence à gauche.

Nous voici arrivés au bout de la partie traitant de la connectivité de l’ESP. Le prochain article présentera la carte d’éclairage. Cela peut vous paraitre compliqué pour simplement alimenter des rubans de LED, mais le but de cette série d’articles était aussi de vous montrer quelques techniques pour se connecter en WiFi, techniques qui se révèleront d’une grande utilité pour vos autres projets.