Le plugin de source de données MQTT Grafana permet à un tableau de bord de s'abonner aux topics d'un broker et d'afficher les valeurs dès leur publication, sans base de données intermédiaire. Dans ce tutoriel, vous allez installer le plugin, le connecter à broker.connectmq.com, construire des panneaux en direct à partir de payloads numériques et JSON, et savoir précisément quand ajouter plutôt une base de données de séries temporelles.
Comment fonctionne la source de données MQTT Grafana
La plupart des sources de données Grafana reposent sur des requêtes : un panneau demande une plage de temps à une base de données et dessine le résultat. La source de données MQTT est différente. C'est une source de données en streaming construite sur Grafana Live. À l'ouverture d'un panneau, le serveur Grafana s'abonne au topic indiqué, et chaque message est poussé vers le navigateur via un WebSocket, puis ajouté au graphique.
Cette conception a deux conséquences à comprendre avant de construire quoi que ce soit de sérieux :
- La latence est excellente. Une valeur publiée par un appareil apparaît presque immédiatement dans le panneau, ce qui est idéal pour la mise en service, les démonstrations en direct et les vues de type salle de contrôle.
- Il n'y a pas d'historique. Le plugin n'affiche que ce qui est arrivé pendant que le panneau était ouvert. Rechargez le tableau de bord et le graphique repart à vide. Impossible de dézoomer sur la journée d'hier, puisque hier n'a jamais été stocké.
Gardez ces deux points en tête. La source de données MQTT est une fenêtre sur le flux en direct, pas un enregistrement de celui-ci.
Installer le plugin
L'ID du plugin est grafana-mqtt-datasource. Sur une installation native de Grafana :
grafana cli plugins install grafana-mqtt-datasource
sudo systemctl restart grafana-server
Les anciennes versions de Grafana utilisent le binaire grafana-cli au lieu de grafana cli. Avec Docker, laissez le conteneur l'installer au démarrage :
services:
grafana:
image: grafana/grafana:11.3.0
ports:
- "3000:3000"
environment:
GF_INSTALL_PLUGINS: grafana-mqtt-datasource
volumes:
- grafana-data:/var/lib/grafana
volumes:
grafana-data:
Lancez docker compose up -d et ouvrez http://localhost:3000. L'identifiant par défaut est admin / admin, et Grafana vous demande de le changer.
Configurer la connexion
Dans Grafana, allez dans Connections, puis Data sources, puis Add data source, et recherchez MQTT. La page de paramètres demande une URI et des identifiants facultatifs.
| Paramètre | Serveur MQTT public gratuit (test) | Broker privé (production) |
|---|---|---|
| URI | tcp://broker.connectmq.com:1883 |
tls://broker.connectmq.com:8883 |
| Username | vide | YOUR_USERNAME |
| Password | vide | YOUR_PASSWORD |
| Options TLS | aucune | Laisser la CA vide ; le certificat Let's Encrypt est reconnu publiquement |
Cliquez sur Save and test. Une confirmation verte signifie que le serveur Grafana, et non votre navigateur, a atteint le broker. Cette distinction compte sur les réseaux verrouillés : le serveur a besoin d'un accès sortant au port 1883 ou 8883. Si votre version du plugin affiche un champ client ID et que vous vous connectez à un broker MQTT managé qui lie les client IDs aux identifiants, saisissez le client ID délivré avec votre nom d'utilisateur.
Publier des données de test
Choisissez un préfixe unique comme connectmq/demo/a1b2c3 afin que vos topics de test restent séparés sur le broker public. Cette boucle Bash publie une température numérique simple toutes les deux secondes :
ID=a1b2c3
while true; do
T=$(awk -v r=$RANDOM 'BEGIN { printf "%.2f", 20 + r / 32767 * 5 }')
mosquitto_pub -h broker.connectmq.com -p 1883 -i "pub-$ID" \
-t "connectmq/demo/$ID/room1/temperature" -m "$T"
sleep 2
done
Et celle-ci publie un objet JSON contenant plusieurs valeurs :
ID=a1b2c3
while true; do
T=$(awk -v r=$RANDOM 'BEGIN { printf "%.2f", 20 + r / 32767 * 5 }')
H=$(awk -v r=$RANDOM 'BEGIN { printf "%.1f", 40 + r / 32767 * 15 }')
mosquitto_pub -h broker.connectmq.com -p 1883 -i "pubjson-$ID" \
-t "connectmq/demo/$ID/room1/telemetry" \
-m "{\"temperature\": $T, \"humidity\": $H}"
sleep 2
done
Pour de nombreux appareils à la fois, lancez le simulateur d'appareils MQTT en Python et pointez les panneaux vers les topics de chaque appareil.
Construire un panneau en direct avec la source de données MQTT Grafana
- Créez un nouveau tableau de bord et ajoutez une visualisation.
- Sélectionnez la source de données MQTT.
- Dans l'éditeur de requête, saisissez le topic, par exemple
connectmq/demo/a1b2c3/room1/temperature. - Choisissez la visualisation Time series. Les valeurs commencent à apparaître en quelques secondes.
- Réglez la plage de temps du tableau de bord sur une durée courte, par exemple les 5 dernières minutes. Le rafraîchissement automatique est inutile, puisque le panneau est en streaming.
Pour le topic JSON, le plugin transforme chaque clé numérique de l'objet en un field distinct : temperature et humidity deviennent ainsi deux séries dans le même panneau. Utilisez les overrides de field pour placer l'humidité sur un axe à droite ou donner à chaque série sa propre unité. Les panneaux Stat et Gauge conviennent bien aux valeurs courantes uniques ; réglez leur calcul sur « Last » pour qu'ils affichent toujours la mesure la plus récente.
Les versions récentes du plugin acceptent les wildcards + et # dans le champ topic, ce qui est pratique pour surveiller un groupe de capteurs dans un seul panneau. Si votre version refuse les wildcards, ajoutez plutôt une requête par topic, car chaque panneau peut en contenir plusieurs.
Problèmes courants et corrections
| Symptôme | Cause | Correction |
|---|---|---|
| « Save and test » échoue | Le serveur Grafana ne peut pas joindre le broker | Tester depuis le serveur avec mosquitto_sub ; vérifier les pare-feux et le schéma de l'URI |
| Le panneau reste vide | Topic incorrect ou rien n'a encore été publié | Vérifier avec mosquitto_sub -t "connectmq/demo/a1b2c3/#" -v |
| Graphique vide après rechargement | Comportement attendu ; aucun historique n'est stocké | Ajouter une base de séries temporelles pour l'historique |
| Du texte au lieu de nombres | Le payload contient des unités, comme 21.5 C |
Publier des nombres bruts ou des nombres JSON |
| Le panneau se fige dans le navigateur | Débit de messages très élevé sur un topic | Publier moins souvent ou agréger avant de publier |
| Unauthorized sur un broker privé | Identifiants ou client ID erronés | Recopier les valeurs depuis le portail du broker |
Quand ajouter une base de données de séries temporelles
La source de données en streaming est le bon outil pour un ensemble restreint de tâches. Dès que vous avez besoin d'historique, d'agrégation ou d'alertes sur la durée, placez une base de données entre le broker et Grafana.
| Besoin | Source de données MQTT seule | Telegraf + InfluxDB + Grafana |
|---|---|---|
| Vue en direct infraseconde | Oui | Presque, limitée par l'intervalle d'écriture |
| Voir la semaine dernière | Non | Oui |
| Moyennes, min/max par heure | Non | Oui, dans la requête |
| Règles d'alerte sur des fenêtres de temps | Limité | Oui |
| Résiste au rechargement du tableau de bord | Non | Oui |
| Composants supplémentaires à exploiter | Aucun | Deux |
Un modèle courant combine les deux : un panneau adossé à une base pour la tendance et un panneau en streaming pour la valeur courante. Le tutoriel Telegraf MQTT consumer montre comment écrire les mêmes topics dans InfluxDB, et la stack TIG avec Docker Compose vous fournit la stack complète dans un seul fichier avec des tableaux de bord provisionnés. Une fois l'historique en place, les alertes Grafana sur les données de capteurs IoT deviennent possibles.
Remarques pour la production
Le broker public est lisible par tous : réservez-le aux données de test. Pour de vrais équipements, connectez Grafana à un broker privé protégé par TLS. Un broker MQTT managé ConnectMQ fournit TLS sur le port 8883 et des identifiants issus du portail, et Grafana s'y connecte comme n'importe quel autre client MQTT. N'oubliez pas que chaque connexion du serveur Grafana compte dans la limite de connexions de votre plan, qui est de 25 sur le plan Serverless (Free).
Pour des cas d'usage purement navigateur où vous ne voulez pas de serveur Grafana du tout, une petite page web utilisant MQTT sur WebSocket sur le port 8084 peut afficher directement les valeurs en direct. Pour choisir la bonne pile cliente pour cela ou pour le code des appareils, consultez le guide des bibliothèques clientes MQTT. La page de la source de données MQTT Grafana du plugin documente ses options actuelles.
Démarrez avec ConnectMQ
Pointez le plugin vers le serveur MQTT public gratuit broker.connectmq.com et vous aurez un panneau en direct en quelques minutes. Lorsque le tableau de bord doit afficher de vrais appareils, exécutez votre broker sur ConnectMQ, où vous disposez aussi d'un client MQTT dans le navigateur et d'un explorateur de topics en direct pour vérifier les topics avant de câbler les panneaux. Créez un broker Serverless gratuit sur app.connectmq.com, sans carte bancaire. Vous préparez un déploiement plus large ? Notre guide du broker MQTT cloud explique ce qui change à grande échelle.
Questions fréquentes
La source de données MQTT Grafana stocke-t-elle des données ?
Non. Elle diffuse les messages vers les panneaux ouverts via Grafana Live et ne conserve rien une fois le panneau fermé. Utilisez une base de séries temporelles comme InfluxDB lorsque vous avez besoin d'historique.
Puis-je utiliser des wildcards dans le champ topic ?
Les versions récentes du plugin prennent en charge + et #. Sur les versions plus anciennes, ajoutez une requête par topic.
Quels formats de payload fonctionnent avec le plugin ?
Les payloads numériques simples et les objets JSON à valeurs numériques fonctionnent le mieux. Chaque clé JSON numérique devient un field distinct dans le panneau.
Le navigateur se connecte-t-il directement au broker ?
Non. Le serveur Grafana maintient la connexion MQTT et transmet les données aux navigateurs via Grafana Live : seul le serveur a besoin d'un accès réseau au broker.
