11. MQTT Integration Guide

Version: 1.2.0
Date: 2025-12-24

Complete guide for ACRouter MQTT connectivity, including topic structure and Home Assistant integration.

Table of Contents

• Overview
• Features
• Quick Start
• Topic Structure
• Console Commands
• Configuration
• Testing Topics
• Troubleshooting

Overview

ACRouter supports MQTT protocol for:

• Real-time monitoring - Power metrics, voltage, currents, router status
• Remote control - Mode switching, dimmer control, emergency stop
• Configuration - Adjust parameters remotely
• Home Assistant integration - Auto-discovery for seamless smart home integration

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

Features

Quick Start

1. Enable MQTT via Serial Console

# 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. Verify Connection

======================================================
  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. Subscribe to Topics

Using Mosquitto client tools as an example:

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

Topic Structure

All topics follow the pattern: acrouter/{device_id}/category/name

The {device_id} is auto-generated from the last 6 characters of the MAC address (e.g., 039C7C) or can be set manually.

Status Topics (Retained)

Metrics Topics (Not Retained)

Published every 5 seconds (configurable).

Config Topics (Retained)

Command Topics (Write-Only)

Send commands by publishing to these topics:

System Topics (Retained)

JSON Aggregated Topics

For efficiency, metrics are also published as aggregated JSON:

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

Console Commands

Connection Management

Configuration

Examples

# 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

NVS Storage Keys

All MQTT settings are persisted in NVS (Non-Volatile Storage):

Default Values

Testing Topics

You can use any MQTT client to test topics. Examples below use Mosquitto client tools (mosquitto_sub / mosquitto_pub).

Subscribe to All Topics

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

Subscribe to Specific Topics

# 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

Send Commands

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

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

Troubleshooting

Connection Issues

Symptom: esp-tls: select() timeout

Solutions:

1. Check broker is running and accessible
2. Check firewall allows port 1883
3. Verify broker URL format: mqtt://IP:PORT
4. Test broker connectivity from another client

"Client has started" Error

Symptom: Repeated mqtt_client: Client has started errors

Solution: This was a bug in earlier versions. Update to latest firmware where esp_mqtt_client_start() is called only once.

WiFi Not Connected

Symptom: MQTT doesn't connect on boot

Explanation: MQTT now waits for WiFi connection before attempting to connect. Check WiFi status first:

wifi-status

Messages Not Received

Symptom: Commands sent but not processed

Solutions:

1. Check topic spelling (case-sensitive)
2. Verify device ID matches: mqtt-status
3. Check message is received: device log shows MQTT: Command: mode = auto

Home Assistant Not Discovering

Symptom: Device doesn't appear in Home Assistant

Solutions:

1. Verify HA Discovery is enabled: mqtt-ha-discovery 1
2. Check HA MQTT integration is configured
3. Force republish: mqtt-publish or restart device
4. Check HA logs for discovery messages

See Also

• 12_HOME_ASSISTANT.md - Home Assistant integration details
• 07_COMMANDS_EN.md - Complete command reference
• 05_API_REFERENCE_EN.md - REST API documentation

Last Updated: 2025-12-24