MQTT Home Assistant

MQTT Home Assistant Integration

The router can publish telemetry and per-client statistics to an MQTT broker with Home Assistant auto-discovery. This lets HA automatically create entities for the router and its connected clients.

Requirements

• MQTT broker (e.g. Mosquitto) accessible from the router's network
• Home Assistant with MQTT integration configured
• Firmware built with CONFIG_MQTT_HOMEASSISTANT=y (enabled by default)

Build Configuration

Enable the integration in idf.py menuconfig under MQTT Home Assistant:

Option	Default	Description
Enable MQTT Home Assistant integration	Yes	Compile MQTT HA support into firmware
MQTT buffer size	1024 B	Send/receive buffer size
Default publish interval	30 s	How often telemetry is published (5-3600s)

Setup

1. Configure the MQTT broker

mqtt broker mqtt://192.168.1.100:1883

For brokers with authentication:

mqtt user myuser mypassword

2. Enable the integration

mqtt enable

The router connects to the broker and publishes HA discovery configs immediately.

3. Verify in Home Assistant

The router should appear automatically under Settings > Devices & Services > MQTT. No manual configuration needed.

Entities

Router Entities

Entity	Type	Description
Uplink Status	Binary Sensor	Whether the router is connected to the upstream AP
Connected Clients	Sensor	Number of devices connected to the AP
Bytes Sent	Sensor	Total bytes sent through the uplink (increasing)
Bytes Received	Sensor	Total bytes received through the uplink (increasing)
Uplink RSSI	Sensor	Signal strength of the uplink connection (dBm)
Uplink SSID	Sensor	Name of the upstream WiFi network
Free Heap	Sensor	Available heap memory (diagnostic)
Uptime	Sensor	Seconds since boot (diagnostic)
Restart	Button	Remotely restart the router
Web UI	Switch	Enable/disable the web interface (takes effect after reboot)
Remote Console	Switch	Enable/disable the remote console service
AP Interface	Switch	Enable/disable the WiFi hotspot immediately (persisted across reboots)

Per-Client Entities

Per-client tracking is available for devices with DHCP reservations. For each reserved client, the following entities are created:

Entity	Type	Description
Name Presence	Binary Sensor	Whether the client is currently connected
Name TX	Sensor	Bytes sent by the client (increasing)
Name RX	Sensor	Bytes received by the client (increasing)
Name RSSI	Sensor	Client's WiFi signal strength (dBm, 0 when disconnected)

To add a client for per-device tracking:

dhcp_reserve add AA:BB:CC:DD:EE:FF 192.168.4.100 -n MyPhone
mqtt rediscover

The mqtt rediscover command re-publishes discovery configs so HA picks up the new client entities.

CLI Commands

mqtt status                        # Show MQTT status, broker, and interval
mqtt enable                        # Enable and start MQTT publishing
mqtt disable                       # Disable and disconnect
mqtt broker <uri>                  # Set broker URI (e.g. mqtt://host:1883)
mqtt user <username> <password>    # Set broker credentials
mqtt interval <seconds>            # Set publish interval (5-3600)
mqtt rediscover                    # Re-publish HA discovery configs

MQTT Topics

Topic	Direction	Description
esp32_nat_router/state	Publish	Router telemetry JSON
esp32_nat_router/availability	Publish	online / offline
esp32_nat_router/command/restart	Subscribe	Send any payload to restart
esp32_nat_router/command/web_ui	Subscribe	Send ON/OFF to toggle web UI
esp32_nat_router/command/remote_console	Subscribe	Send ON/OFF to toggle remote console
esp32_nat_router/command/ap	Subscribe	Send ON/OFF to enable/disable the AP interface
esp32_nat_router/clients/<MAC>	Publish	Per-client stats JSON
homeassistant/…	Publish	Auto-discovery config (retained)

State Payload Example

{
  "uplink": "ON",
  "clients": 3,
  "bytes_tx": 1048576,
  "bytes_rx": 2097152,
  "free_heap": 120000,
  "uptime": 3600,
  "rssi": -52,
  "ssid": "MyNetwork",
  "web_ui": "ON",
  "remote_console": "OFF",
  "ap_enabled": "ON"
}

Client Payload Example

{
  "present": "ON",
  "tx": 524288,
  "rx": 1048576,
  "rssi": -45
}

Last Will and Testament

The router publishes online to esp32_nat_router/availability on connect and sets an MQTT last will of offline on the same topic. If the router goes offline unexpectedly, the broker automatically publishes the offline message so HA marks the device as unavailable.

Broker URI Formats

The broker URI follows the ESP-IDF MQTT client format:

Scheme	Description
mqtt://host:1883	Plain MQTT
mqtts://host:8883	MQTT over TLS
ws://host:8080	MQTT over WebSocket
wss://host:8081	MQTT over secure WebSocket

Troubleshooting

• Router not appearing in HA: Verify the broker URI is correct and the MQTT integration is configured in HA. Check with mosquitto_sub -t "homeassistant/#" -v to see if discovery messages arrive.
• Clients not appearing: Only devices with DHCP reservations get per-client entities. Add a reservation and run mqtt rediscover.
• Stale data after reboot: Counters (bytes, uptime) reset on reboot. HA handles this via total_increasing state class.
• Connection drops: Check mqtt status on the CLI. The client reconnects automatically.