← Calibrage des capteurs | Sommaire | Suivant : Intégration Home Assistant →

11. Guide d'intégration MQTT

Version: 1.2.0
Date: 2025-12-24

Guide complet pour la connectivité MQTT de l'ACRouter, incluant la structure des topics et l'intégration Home Assistant.

Table des matières

• Vue d'ensemble
• Fonctionnalités
• Démarrage rapide
• Structure des topics
• Commandes console
• Configuration
• Test des topics
• Dépannage

Vue d'ensemble

ACRouter prend en charge le protocole MQTT pour :

• Surveillance en temps réel — Métriques de puissance, tension, courants, état du routeur
• Contrôle à distance — Changement de mode, contrôle du variateur, arrêt d'urgence
• Configuration — Ajustement des paramètres à distance
• Intégration Home Assistant — Découverte automatique pour une intégration domotique transparente

The MQTT client is based on ESP-IDF's esp-mqtt library with automatic reconnection, Last Will & Testament (LWT), and QoS support.

Fonctionnalités

Démarrage rapide

1. Activer MQTT via la console série

# Set broker URL (replace with your broker IP)
mqtt-broker mqtt://192.168.1.10:1883

# Enable MQTT
mqtt-enable

# Check status
mqtt-status

2. Vérifier la connexion

======================================================
  MQTT Status
======================================================
State:         Connected
Enabled:       Yes
Broker:        mqtt://192.168.1.10:1883
Device ID:     039C7C
Device Name:   (default)
HA Discovery:  Enabled
Pub Interval:  5000 ms
------------------------------------------------------
Uptime:        125 sec
Published:     250 messages
Received:      3 messages
======================================================

3. S'abonner aux topics

Utilisation des outils client Mosquitto à titre d'exemple :

# Subscribe to all ACRouter topics
mosquitto_sub -h 192.168.1.10 -t "acrouter/#" -v

Structure des topics

Tous les topics suivent le schéma : acrouter/{device_id}/category/name

Le {device_id} est généré automatiquement à partir des 6 derniers caractères de l'adresse MAC (par ex. 039C7C) ou peut être défini manuellement.

Topics de statut (retenus)

Topics de métriques (non retenus)

Publication toutes les 5 secondes (configurable).

Topics de configuration (retenus)

Topics de commande (écriture seule)

Envoyez des commandes en publiant sur ces topics :

Topics système (retenus)

Topics JSON agrégés

Pour plus d'efficacité, les métriques sont également publiées en JSON agrégé :

Topic : json/metrics

{
  "voltage": 230.5,
  "power_grid": -150.2,
  "power_solar": 1250.0,
  "power_load": 1100.0,
  "current_grid": 0.65,
  "current_solar": 5.43,
  "current_load": 4.78,
  "direction": "supplying"
}

Commandes console

Gestion de la connexion

Configuration

Exemples

# Configure broker with authentication
mqtt-broker mqtt://192.168.1.10:1883
mqtt-user myuser
mqtt-pass mypassword
mqtt-enable

# Set custom device name for Home Assistant
mqtt-device-name "Solar Router Kitchen"

# Reduce publish frequency to 10 seconds
mqtt-interval 10000

# Disable Home Assistant auto-discovery
mqtt-ha-discovery 0

Configuration

Clés de stockage NVS

Tous les paramètres MQTT sont conservés dans le NVS (Non-Volatile Storage) :

Valeurs par défaut

Test des topics

Vous pouvez utiliser n'importe quel client MQTT pour tester les topics. Les exemples ci-dessous utilisent les outils client Mosquitto (mosquitto_sub / mosquitto_pub).

S'abonner à tous les topics

mosquitto_sub -h 192.168.1.10 -t "acrouter/#" -v

S'abonner à des topics spécifiques

# Status only
mosquitto_sub -h 192.168.1.10 -t "acrouter/039C7C/status/#" -v

# Metrics only
mosquitto_sub -h 192.168.1.10 -t "acrouter/039C7C/metrics/#" -v

# JSON aggregated
mosquitto_sub -h 192.168.1.10 -t "acrouter/039C7C/json/#" -v

Envoyer des commandes

# Change mode to AUTO
mosquitto_pub -h 192.168.1.10 -t "acrouter/039C7C/command/mode" -m "auto"

# Set dimmer to 50% (in MANUAL mode)
mosquitto_pub -h 192.168.1.10 -t "acrouter/039C7C/command/dimmer" -m "50"

# Emergency stop
mosquitto_pub -h 192.168.1.10 -t "acrouter/039C7C/command/emergency_stop" -m "1"

# Reboot device
mosquitto_pub -h 192.168.1.10 -t "acrouter/039C7C/command/reboot" -m "1"

# Force refresh all data
mosquitto_pub -h 192.168.1.10 -t "acrouter/039C7C/command/refresh" -m "1"

Mettre à jour la configuration via MQTT

# Set control gain
mosquitto_pub -h 192.168.1.10 -t "acrouter/039C7C/config/control_gain/set" -m "200"

# Set balance threshold
mosquitto_pub -h 192.168.1.10 -t "acrouter/039C7C/config/balance_threshold/set" -m "25"

Dépannage

Problèmes de connexion

Symptôme : esp-tls: select() timeout

Solutions :

1. Vérifiez que le broker est en cours d'exécution et accessible
2. Vérifiez que le pare-feu autorise le port 1883
3. Vérifiez le format de l'URL du broker : mqtt://IP:PORT
4. Testez la connectivité du broker depuis un autre client

"Client has started" Error

Symptôme : Erreurs répétées mqtt_client: Client has started

Solution : Il s'agissait d'un bug dans les versions précédentes. Mettez à jour vers le dernier firmware où esp_mqtt_client_start() n'est appelé qu'une seule fois.

WiFi non connecté

Symptom: MQTT doesn't connect on boot

Explication : MQTT attend désormais la connexion WiFi avant de tenter de se connecter. Vérifiez d'abord le statut WiFi :

wifi-status

Messages non reçus

Symptôme : Les commandes sont envoyées mais non traitées

Solutions :

1. Vérifiez l'orthographe des topics (sensible à la casse)
2. Vérifiez que l'identifiant de l'appareil correspond : mqtt-status
3. Vérifiez que le message est reçu : le journal de l'appareil affiche MQTT: Command: mode = auto

Home Assistant ne détecte pas l'appareil

Symptom: Device doesn't appear in Home Assistant

Solutions :

1. Vérifiez que HA Discovery est activé : mqtt-ha-discovery 1
2. Vérifiez que l'intégration MQTT de HA est configurée
3. Forcez la republication : mqtt-publish ou redémarrez l'appareil
4. Consultez les journaux de HA pour les messages de découverte

Voir aussi

• 12_HOME_ASSISTANT.md — Détails de l'intégration Home Assistant
• 07_COMMANDS_EN.md — Référence complète des commandes
• 05_API_REFERENCE_EN.md — Documentation de l'API REST

Dernière mise à jour : 2025-12-24

← Calibrage des capteurs | Sommaire | Suivant : Intégration Home Assistant →