Connect ESP-Claw to Your Smart Home with MQTT

MQTT is the backbone of IoT communication, and it’s one of ESP-Claw’s most powerful channels. This tutorial shows you how to connect your AI agent to your smart home using MQTT, enabling natural language control of lights, sensors, climate, and more.

What is MQTT?

MQTT (Message Queuing Telemetry Transport) is a lightweight messaging protocol designed for constrained devices. It uses a publish/subscribe model: devices publish messages to “topics,” and other devices subscribe to those topics to receive messages.

For ESP-Claw, MQTT serves two purposes:

Control channel: The AI agent publishes commands to control smart devices
Sensor channel: Smart devices publish sensor data that the AI can read

Setting Up an MQTT Broker

You need an MQTT broker — a server that routes messages between devices. You have two options:

Option A: Mosquitto (Self-Hosted, Free)

Mosquitto is the most popular open-source MQTT broker. Install it on any computer that’s always on — a Raspberry Pi, a NAS, or a spare laptop.

On Ubuntu or Raspberry Pi OS:

sudo apt update
sudo apt install mosquitto mosquitto-clients
sudo systemctl enable mosquitto
sudo systemctl start mosquitto

On macOS:

brew install mosquitto
brew services start mosquitto

By default, Mosquitto listens on port 1883 without authentication. For a home network, this is fine to start. For production use, add username/password authentication.

Option B: Cloud MQTT (HiveMQ, EMQX)

If you don’t want to run your own broker, several cloud services offer free tiers:

HiveMQ Cloud: Free tier with 100 connections
EMQX Cloud: Free tier with 1M messages/month
CloudMQTT: Free tier with 5 connections

Cloud brokers are easier to set up but add latency (messages travel to the cloud and back) and have privacy implications.

Connecting ESP-Claw to MQTT

In the ESP-Claw web configuration panel, configure the MQTT channel:

Setting	Value
Broker Address	Your broker’s IP (e.g., 192.168.1.100)
Port	1883 (or 8883 for TLS)
Username	(optional, leave blank for no auth)
Password	(optional)
Client ID	espclaw-living-room
Base Topic	espclaw/

After saving, ESP-Claw will connect to the broker and subscribe to espclaw/command for incoming messages.

Controlling Smart Lights

Let’s start with the most common use case: controlling smart lights.

Zigbee Lights via Home Assistant

If you use Home Assistant with Zigbee2MQTT, your lights are already publishing state to MQTT. The typical topic structure is:

zigbee2mqtt/living_room_light/set    → {"state": "ON", "brightness": 255}
zigbee2mqtt/bedroom_light/set        → {"state": "OFF"}
zigbee2mqtt/kitchen_light/set        → {"state": "ON", "color_temp": 350}

Add this to your SOUL.md so the AI knows about your lights:

## Smart Lights (via MQTT)

Available lights and their MQTT topics:
- Living room: zigbee2mqtt/living_room_light/set
  Supports: state (ON/OFF), brightness (0-255), color_temp (150-500)
- Bedroom: zigbee2mqtt/bedroom_light/set
  Supports: state (ON/OFF), brightness (0-255)
- Kitchen: zigbee2mqtt/kitchen_light/set
  Supports: state (ON/OFF), brightness (0-255), color_temp

When user asks to dim lights, set brightness to 50 (about 20%).
Default color temperature: 350 (warm white) for evening, 200 (daylight) for daytime.

Now you can say things like:

“Turn on the living room light” → publishes {"state": "ON"} to the light’s topic
“Dim the bedroom light to 30%” → publishes {"state": "ON", "brightness": 76}
“Make the kitchen light warmer” → publishes {"color_temp": 400}
“Turn everything off” → publishes OFF to all three topics

Tasmota Devices

Tasmota uses a slightly different topic structure:

cmnd/living_room_plug/POWER → ON
stat/living_room_plug/POWER → ON (response)

Add appropriate tool descriptions to your SOUL.md for Tasmota devices.

Reading Sensor Data via MQTT

Smart sensors often publish their readings to MQTT. For example, a Zigbee temperature sensor might publish to:

zigbee2mqtt/bedroom_sensor → {"temperature": 22.5, "humidity": 45, "battery": 87}

ESP-Claw can subscribe to these topics and make the data available to the AI. Configure subscriptions in the MQTT settings, and add context to SOUL.md:

## MQTT Sensors

I can read these sensors via MQTT:
- bedroom_sensor (zigbee2mqtt/bedroom_sensor): temperature, humidity, battery
- outdoor_sensor (zigbee2mqtt/outdoor_sensor): temperature, humidity
- power_meter (tele/power_meter/SENSOR): energy, power, voltage

When reporting sensor data, always include the room name.
If battery is below 20%, mention it needs replacement.

Building an MQTT-Connected Climate System

Here’s a complete example that combines multiple MQTT devices into a cohesive climate management system.

The Setup

ESP-Claw (living room, with DHT22 for local reading)
Zigbee temperature sensor (bedroom, via Zigbee2MQTT)
Smart IR blaster (controls AC, via MQTT)
Smart plug (controls a portable heater, via Tasmota)

SOUL.md Configuration

# Climate Manager

You manage the climate in a 2-bedroom apartment.

## Sensors
- Living room: local DHT22 (tool: dht_read)
- Bedroom: MQTT topic zigbee2mqtt/bedroom_sensor
- Outdoor: MQTT topic zigbee2mqtt/outdoor_sensor

## Controls
- AC: MQTT topic ir_bridge/ac/set
  Format: {"mode":"cool","temp":24,"fan":"auto"}
  Modes: cool, heat, dry, fan_only, off
- Heater: MQTT topic cmnd/bedroom_heater/POWER
  Values: ON, OFF (no temperature control, it's a simple heater)

## Climate Rules
- Ideal temperature: 22-25°C
- If any room exceeds 28°C and AC is off, suggest cooling
- If bedroom is below 18°C at night, suggest turning on heater
- Don't run AC and heater simultaneously
- Check outdoor temperature before suggesting opening windows
- Log temperature readings every hour to memory

With this configuration, you can have conversations like:

You: “Is it comfortable to sleep?” AI: [reads bedroom sensor: 19.2°C, 55%] “The bedroom is 19.2°C — a bit cool for sleeping. Want me to turn on the heater for 30 minutes to warm it up?”

You: “Yeah, do that” AI: [publishes ON to bedroom heater] [sets 30-minute timer] “Heater is on. I’ll turn it off in 30 minutes so it doesn’t overheat overnight.”

Security Considerations

MQTT without authentication is fine for initial testing but not for production. Here are the security steps you should take:

Enable authentication: Set up username/password in Mosquitto
Use TLS: Encrypt MQTT traffic, especially if using a cloud broker
Limit topics: Configure ACLs so ESP-Claw can only publish to specific topics
Firewall: Don’t expose your MQTT broker to the internet
Isolate IoT network: Consider a separate VLAN for IoT devices

Debugging MQTT

When things don’t work, use mosquitto_sub to monitor traffic:

# See all messages on all topics
mosquitto_sub -h localhost -t '#' -v

# See only ESP-Claw messages
mosquitto_sub -h localhost -t 'espclaw/#' -v

# See what the AI sends to lights
mosquitto_sub -h localhost -t 'zigbee2mqtt/+/set' -v

This is invaluable for understanding what commands the AI is sending and whether devices are responding.

Next Steps

Once you have MQTT working, consider adding event-driven automation with WireClaw firmware, which can trigger actions based on MQTT messages without waiting for AI inference. This gives you the best of both worlds: instant automation for common scenarios and AI-powered reasoning for complex situations.