← Calibrazione dei sensori | Indice | Avanti: Integrazione Home Assistant →

11. Guida all'integrazione MQTT

Version: 1.2.0
Date: 2025-12-24

Guida completa alla connettività MQTT di ACRouter, inclusa la struttura dei topic e l'integrazione con Home Assistant.

Indice

• Panoramica
• Funzionalità
• Avvio rapido
• Struttura dei topic
• Comandi console
• Configurazione
• Test dei topic
• Risoluzione dei problemi

Panoramica

ACRouter supporta il protocollo MQTT per:

• Monitoraggio in tempo reale — Metriche di potenza, tensione, correnti, stato del router
• Controllo remoto — Cambio modalità, controllo del dimmer, arresto di emergenza
• Configurazione — Regolazione dei parametri da remoto
• Integrazione con Home Assistant — Scoperta automatica per un'integrazione domotica trasparente

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

Funzionalità

Avvio rapido

1. Abilitare MQTT tramite la console seriale

# 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. Verificare la connessione

======================================================
  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. Sottoscrivere i topic

Utilizzo degli strumenti client Mosquitto come esempio:

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

Struttura dei topic

Tutti i topic seguono lo schema: acrouter/{device_id}/category/name

Il {device_id} viene generato automaticamente dagli ultimi 6 caratteri dell'indirizzo MAC (es. 039C7C) oppure può essere impostato manualmente.

Topic di stato (retained)

Topic delle metriche (non retained)

Pubblicazione ogni 5 secondi (configurabile).

Topic di configurazione (retained)

Topic dei comandi (sola scrittura)

Inviare comandi pubblicando su questi topic:

Topic di sistema (retained)

Topic JSON aggregati

Per maggiore efficienza, le metriche vengono pubblicate anche come JSON aggregato:

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"
}

Comandi console

Gestione della connessione

Configurazione

Esempi

# 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

Configurazione

Chiavi di archiviazione NVS

Tutte le impostazioni MQTT vengono salvate nel NVS (Non-Volatile Storage):

Valori predefiniti

Test dei topic

È possibile utilizzare qualsiasi client MQTT per testare i topic. Gli esempi seguenti utilizzano gli strumenti client Mosquitto (mosquitto_sub / mosquitto_pub).

Sottoscrivere tutti i topic

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

Sottoscrivere topic specifici

# 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

Inviare comandi

# 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"

Aggiornare la configurazione tramite 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"

Risoluzione dei problemi

Problemi di connessione

Sintomo: esp-tls: select() timeout

Soluzioni:

1. Verificare che il broker sia in esecuzione e raggiungibile
2. Verificare che il firewall consenta la porta 1883
3. Controllare il formato dell'URL del broker: mqtt://IP:PORT
4. Testare la connettività del broker da un altro client

"Client has started" Error

Sintomo: Errori ripetuti mqtt_client: Client has started

Soluzione: Si trattava di un bug nelle versioni precedenti. Aggiornare all'ultimo firmware dove esp_mqtt_client_start() viene chiamato una sola volta.

WiFi non connesso

Symptom: MQTT doesn't connect on boot

Spiegazione: MQTT ora attende la connessione WiFi prima di tentare la connessione. Verificare prima lo stato del WiFi:

wifi-status

Messaggi non ricevuti

Sintomo: I comandi vengono inviati ma non elaborati

Soluzioni:

1. Verificare l'ortografia del topic (sensibile alle maiuscole/minuscole)
2. Verificare che l'ID del dispositivo corrisponda: mqtt-status
3. Controllare che il messaggio sia stato ricevuto: il log del dispositivo mostra MQTT: Command: mode = auto

Home Assistant non rileva il dispositivo

Symptom: Device doesn't appear in Home Assistant

Soluzioni:

1. Verificare che HA Discovery sia abilitato: mqtt-ha-discovery 1
2. Controllare che l'integrazione MQTT di HA sia configurata
3. Forzare la ripubblicazione: mqtt-publish o riavviare il dispositivo
4. Controllare i log di HA per i messaggi di scoperta

Vedi anche

• 12_HOME_ASSISTANT.md — Dettagli sull'integrazione con Home Assistant
• 07_COMMANDS_EN.md — Riferimento completo dei comandi
• 05_API_REFERENCE_EN.md — Documentazione dell'API REST

Ultimo aggiornamento: 2025-12-24

← Calibrazione dei sensori | Indice | Avanti: Integrazione Home Assistant →