← Calibración de sensores | Contenido | Siguiente: Integración con Home Assistant →

11. Guía de integración MQTT

Version: 1.2.0
Date: 2025-12-24

Guía completa para la conectividad MQTT de ACRouter, incluyendo la estructura de topics y la integración con Home Assistant.

Tabla de contenido

• Descripción general
• Características
• Inicio rápido
• Estructura de topics
• Comandos de consola
• Configuración
• Prueba de topics
• Solución de problemas

Descripción general

ACRouter soporta el protocolo MQTT para:

• Monitoreo en tiempo real — Métricas de potencia, voltaje, corrientes, estado del router
• Control remoto — Cambio de modo, control del dimmer, parada de emergencia
• Configuración — Ajustar parámetros de forma remota
• Integración con Home Assistant — Descubrimiento automático para una integración domótica transparente

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

Características

Inicio rápido

1. Habilitar MQTT a través de la consola serie

# 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. Verificar la conexión

======================================================
  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. Suscribirse a topics

Usando las herramientas cliente de Mosquitto como ejemplo:

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

Estructura de topics

Todos los topics siguen el patrón: acrouter/{device_id}/category/name

El {device_id} se genera automáticamente a partir de los últimos 6 caracteres de la dirección MAC (por ej., 039C7C) o puede establecerse manualmente.

Topics de estado (retenidos)

Topics de métricas (no retenidos)

Publicación cada 5 segundos (configurable).

Topics de configuración (retenidos)

Topics de comando (solo escritura)

Envíe comandos publicando en estos topics:

Topics de sistema (retenidos)

Topics JSON agregados

Para mayor eficiencia, las métricas también se publican como JSON agregado:

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

Comandos de consola

Gestión de conexión

Configuración

Ejemplos

# 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

Configuración

Claves de almacenamiento NVS

Todos los ajustes MQTT se conservan en NVS (Non-Volatile Storage):

Valores por defecto

Prueba de topics

Puede usar cualquier cliente MQTT para probar los topics. Los ejemplos a continuación utilizan las herramientas cliente de Mosquitto (mosquitto_sub / mosquitto_pub).

Suscribirse a todos los topics

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

Suscribirse a topics específicos

# 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

Enviar comandos

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

Actualizar configuración vía 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"

Solución de problemas

Problemas de conexión

Síntoma: esp-tls: select() timeout

Soluciones:

1. Verifique que el broker esté en ejecución y sea accesible
2. Verifique que el firewall permita el puerto 1883
3. Compruebe el formato de la URL del broker: mqtt://IP:PORT
4. Pruebe la conectividad del broker desde otro cliente

"Client has started" Error

Síntoma: Errores repetidos mqtt_client: Client has started

Solución: Esto era un bug en versiones anteriores. Actualice al firmware más reciente donde esp_mqtt_client_start() se llama solo una vez.

WiFi no conectado

Symptom: MQTT doesn't connect on boot

Explicación: MQTT ahora espera la conexión WiFi antes de intentar conectarse. Verifique primero el estado de WiFi:

wifi-status

Mensajes no recibidos

Síntoma: Los comandos se envían pero no se procesan

Soluciones:

1. Verifique la ortografía del topic (distingue mayúsculas y minúsculas)
2. Verifique que el ID del dispositivo coincida: mqtt-status
3. Compruebe que el mensaje se reciba: el registro del dispositivo muestra MQTT: Command: mode = auto

Home Assistant no detecta el dispositivo

Symptom: Device doesn't appear in Home Assistant

Soluciones:

1. Verifique que HA Discovery esté habilitado: mqtt-ha-discovery 1
2. Compruebe que la integración MQTT de HA esté configurada
3. Fuerce la republicación: mqtt-publish o reinicie el dispositivo
4. Revise los registros de HA en busca de mensajes de descubrimiento

Ver también

• 12_HOME_ASSISTANT.md — Detalles de la integración con Home Assistant
• 07_COMMANDS_EN.md — Referencia completa de comandos
• 05_API_REFERENCE_EN.md — Documentación de la API REST

Última actualización: 2025-12-24

← Calibración de sensores | Contenido | Siguiente: Integración con Home Assistant →