Écoute Forge IoT : `forge iot:listen`¶

Statut : commande de développement / pédagogie.
Elle écoute le broker MQTT configuré et insère chaque mesure reçue dans la table iot_events.
Ce n'est pas un service de production (pas de daemon, pas de retry, pas de batch).

Objectif¶

Relier les briques Forge IoT en un flux local réellement utilisable :

Mosquitto
   ↓
forge iot:listen
   ↓
MqttSubscriber
   ↓
IotEventRepository.insert()
   ↓
iot_events

Jusqu'ici, forge iot:simulate publiait des mesures, mais Forge n'avait pas de commande simple pour écouter et stocker.
C'est ce que comble forge iot:listen.

Usage¶

forge iot:listen

Aucune option pour ce premier ticket.
Aide via :

forge iot:listen --help

La commande reste active jusqu'à Ctrl+C, puis s'arrête proprement.

Sortie exemple¶

Forge IoT listen

[INFO] Broker MQTT : localhost:1883
[INFO] Topic       : forge/+/+/telemetry
[INFO] Stockage    : table iot_events via IotEventRepository
[INFO] En écoute. Ctrl+C pour arrêter.

[OK] atelier/esp32-001 temperature=22.4 °C
[OK] atelier/esp32-001 humidity=55 %
^C
[INFO] Arrêt demandé.
[OK] Écoute MQTT arrêtée proprement.

Résumé :
  mesures reçues       : 2
  mesures stockées     : 2
  erreurs de contrat   : 0
  erreurs de stockage  : 0

Chaque ligne [OK] correspond à une mesure validée par le contrat MQTT et insérée dans iot_events.

Arrêt propre¶

Sur Ctrl+C, la commande affiche [INFO] Arrêt demandé. puis, une fois la connexion fermée, [OK] Écoute MQTT arrêtée proprement..
La déconnexion du broker (disconnect) est toujours effectuée, même si l'écoute s'est interrompue sur une erreur.

Résumé de session¶

À l'arrêt, un petit résumé récapitule la session, utile en classe et pour le debug :

Résumé :
  mesures reçues       : 3
  mesures stockées     : 3
  erreurs de contrat   : 0
  erreurs de stockage  : 0

mesures reçues : messages conformes au contrat MQTT ;
mesures stockées : insertions réussies dans iot_events ;
erreurs de contrat : messages MQTT ignorés (payload ou topic invalide) ;
erreurs de stockage : échecs d'insertion en base.

Message MQTT invalide¶

Un message qui ne respecte pas le contrat (topic mal formé, champ manquant, type incorrect…) est ignoré sans arrêter l'écoute :

[WARN] Message MQTT ignoré - PAYLOAD_FIELD_MISSING

Le code affiché (TOPIC_PATTERN, PAYLOAD_PARSE, PAYLOAD_FIELD_MISSING, PAYLOAD_FIELD_TYPE, PAYLOAD_VALUE_FORMAT) vient de la taxonomie du contrat MQTT.
Le compteur erreurs de contrat est incrémenté.
Contrairement à une erreur base, un message invalide ne fait pas tomber la commande : on continue d'écouter.

Parcours complet¶

forge iot:listen est le maillon central d'un flux qui réutilise toutes les commandes IoT déjà disponibles :

forge iot:doctor          # package, config, migration, API HTTP
forge iot:init            # copier la migration vers mvc/migrations/
forge migration:apply     # créer la table iot_events
forge iot:doctor --db     # confirmer que la table est lisible
forge iot:doctor --mqtt   # confirmer que le broker répond
forge iot:listen          # écouter et stocker (laisser tourner)

Dans un second terminal, publie des mesures :

forge iot:simulate --count 3 --interval 1

Les mesures apparaissent dans le terminal forge iot:listen ([OK] …), puis sont lisibles via l'API HTTP :

curl http://localhost:8000/api/iot/events

Gestion des erreurs¶

Configuration invalide¶

[ERREUR] Configuration IoT invalide : FORGE_IOT_MQTT_HOST ne peut pas être vide

Exit code 1.
Voir Configuration Forge IoT.

Broker inaccessible¶

[ERREUR] Connexion MQTT impossible : [Errno 111] Connection refused

Exit code 1.
Le broker n'est pas démarré ou l'hôte/port est faux ; diagnostique avec forge iot:doctor --mqtt.
Pour installer et lancer un broker local, voir Mosquitto local.

Erreurs base¶

La commande s'arrête au premier échec base (exit code 1), volontairement simple et pédagogique, et distingue trois cas, message sobre (jamais de stacktrace) :

Table iot_events absente :

[ERREUR] Table iot_events absente.
Conseil : lance forge iot:init puis forge migration:apply.

Crée la table (forge iot:init puis forge migration:apply) puis relance forge iot:listen.

Connexion base impossible (MariaDB arrêté, mauvais identifiants, base inconnue…) :

[ERREUR] Connexion base impossible.
Conseil : vérifie forge db:init et forge iot:doctor --db.

Autre erreur SQL (cas générique) :

[ERREUR] Stockage IoT impossible.

Connexion TLS¶

forge iot:listen bénéficie du TLS via le MqttSubscriber : si FORGE_IOT_MQTT_TLS_ENABLED=true, le subscriber appelle client.tls_set(...) avant de se connecter (ca_certs = FORGE_IOT_MQTT_TLS_CA_FILE si fourni, sinon les certificats système).
Pense à configurer aussi le port TLS du broker (généralement 8883) :

export FORGE_IOT_MQTT_HOST="mqtt.example.net"
export FORGE_IOT_MQTT_PORT="8883"
export FORGE_IOT_MQTT_TLS_ENABLED="true"
export FORGE_IOT_MQTT_TLS_CA_FILE="/etc/ssl/certs/mosquitto-ca.crt"

forge iot:listen

Sans TLS (défaut), la connexion reste en clair, adapté au Mosquitto local.
Détails : Configuration : TLS MQTT.

Limites¶

forge iot:listen est conçue pour le développement et la pédagogie, pas pour la production.
Sont hors périmètre :

pas de daemon systemd ni de mode service ;
pas de file d'attente, de retry/backoff, ni de batch insert ;
pas de stockage multi-thread ;
pas d'authentification avancée (mTLS, ACL côté broker) ;
ne lance pas le simulateur (voir forge iot:simulate) ;
ne modifie ni l'API HTTP ni le contrat MQTT.

Pour un déploiement réel, on brancherait MqttSubscriber dans un processus supervisé de l'application, ce qui dépasse ce ticket.

Écoute Forge IoT : forge iot:listen¶