ha-mqtt-autodiscovery✓ Pass

SKILL.md Content

---
name: ha-mqtt-autodiscovery
description: |
  Configures and publishes MQTT auto-discovery messages to automatically register IoT devices and
  sensors with Home Assistant, defining discovery payloads with device classes, state classes, units,
  and device grouping for multi-sensor devices. Use when integrating custom IoT devices, creating
  MQTT sensors, building ESP32/ESP8266/Pi-based devices that auto-register with HA, or implementing
  resilient MQTT patterns with offline queuing and auto-reconnect.
---

Works with MQTT brokers (Mosquitto), paho-mqtt Python library, and Home Assistant MQTT integration.
# Home Assistant MQTT Auto-Discovery

Automatically register IoT devices and sensors with Home Assistant by publishing MQTT discovery configurations.

## Overview

MQTT auto-discovery allows devices to automatically appear in Home Assistant without manual YAML configuration. Publish a JSON config to the discovery topic and HA creates the entity automatically.

**Discovery Topic Pattern:**
```
homeassistant/{component}/{node_id}/{object_id}/config
```

**State Topic Pattern:**
```
{node_id}/{sensor_type}/state
```

## When to Use This Skill

Use this skill when you need to:
- Automatically register custom IoT devices with Home Assistant via MQTT
- Build ESP32/ESP8266/Raspberry Pi-based sensors that self-register
- Create multi-sensor devices grouped under a single device entry
- Implement resilient MQTT patterns with offline queuing and auto-reconnect
- Configure proper device classes and state classes for long-term statistics
- Avoid manual YAML configuration for frequently changing device deployments

Do NOT use when:
- You can use existing Home Assistant integrations (prefer official integrations)
- Building devices without MQTT broker infrastructure
- You need real-time control with minimal latency (consider direct API instead)

## Usage

Follow these steps to set up MQTT auto-discovery:

1. **Define sensor configurations** with device classes and units
2. **Publish discovery payloads** to discovery topics with retain=True
3. **Verify entities appear** in Home Assistant
4. **Publish sensor values** to state topics
5. **Implement resilient patterns** with auto-reconnect and offline queuing

## Quick Start

```python
import json
import paho.mqtt.client as mqtt

# Connect to MQTT broker
client = mqtt.Client(mqtt.CallbackAPIVersion.VERSION2)
client.connect("192.168.68.123", 1883, 60)

# Publish discovery config
discovery_topic = "homeassistant/sensor/enviroplus_temperature/config"
config = {
    "name": "Enviro+ Temperature",
    "unique_id": "enviroplus_temperature",
    "state_topic": "enviroplus/temperature/state",
    "device_class": "temperature",
    "unit_of_measurement": "°C",
    "state_class": "measurement",
    "device": {
        "identifiers": ["enviroplus"],
        "name": "Enviro+ Environmental Sensor",
        "manufacturer": "Pimoroni",
        "model": "Enviro+",
    },
}
client.publish(discovery_topic, json.dumps(config), qos=1, retain=True)

# Publish sensor value
client.publish("enviroplus/temperature/state", "23.5", qos=1)
```

After publishing, the sensor `sensor.enviro_temperature` appears in Home Assistant automatically.

## Discovery Payload Structure

### Required Fields

```python
{
    "name": "Friendly Name",           # Display name in HA
    "unique_id": "unique_identifier",  # Must be globally unique
    "state_topic": "device/sensor/state",  # Topic where values are published
}
```

### Recommended Fields

```python
{
    "device_class": "temperature",     # Semantic type (enables icons, units)
    "unit_of_measurement": "°C",       # Unit for display
    "state_class": "measurement",      # Enables long-term statistics
    "icon": "mdi:thermometer",         # Custom icon (optional)
}
```

### Device Information

Group sensors under a single device:

```python
{
    "device": {
        "identifiers": ["device_unique_id"],  # List of identifiers
        "name": "Device Name",
        "manufacturer": "Manufacturer",
        "model": "Model Name",
        "sw_version": "1.0.0",
    }
}
```

## Common Sensor Types

See [references/sensor_configs.md](references/sensor_configs.md) for complete sensor configuration templates.

### Environmental Sensors

```python
# Temperature
{
    "device_class": "temperature",
    "unit_of_measurement": "°C",
    "state_class": "measurement",
}

# Humidity
{
    "device_class": "humidity",
    "unit_of_measurement": "%",
    "state_class": "measurement",
}

# Pressure
{
    "device_class": "atmospheric_pressure",
    "unit_of_measurement": "hPa",
    "state_class": "measurement",
}

# Light
{
    "device_class": "illuminance",
    "unit_of_measurement": "lx",
    "state_class": "measurement",
}
```

### Air Quality Sensors

```python
# PM2.5
{
    "device_class": "pm25",
    "unit_of_measurement": "µg/m³",
    "state_class": "measurement",
}

# PM10
{
    "device_class": "pm10",
    "unit_of_measurement": "µg/m³",
    "state_class": "measurement",
}
```

### Energy Monitoring

```python
# Power
{
    "device_class": "power",
    "unit_of_measurement": "W",
    "state_class": "measurement",
}

# Energy (cumulative)
{
    "device_class": "energy",
    "unit_of_measurement": "kWh",
    "state_class": "total_increasing",
}
```

## State Classes

| State Class | Purpose | Resets? | Statistics? |
|-------------|---------|---------|-------------|
| `measurement` | Current value (temp, power) | No | Yes (mean, min, max) |
| `total` | Monotonically increasing (odometer) | No | Yes (rate of change) |
| `total_increasing` | Cumulative with resets (daily energy) | Yes | Yes (rate of change) |

## Complete Example: Multi-Sensor Device

```python
import json
import paho.mqtt.client as mqtt

DEVICE_ID = "enviroplus"
BROKER = "192.168.68.123"

# Sensor definitions
SENSORS = {
    "temperature": {
        "name": "Temperature",
        "device_class": "temperature",
        "unit_of_measurement": "°C",
        "state_class": "measurement",
    },
    "humidity": {
        "name": "Humidity",
        "device_class": "humidity",
        "unit_of_measurement": "%",
        "state_class": "measurement",
    },
    "pressure": {
        "name": "Pressure",
        "device_class": "atmospheric_pressure",
        "unit_of_measurement": "hPa",
        "state_class": "measurement",
    },
    "pm2_5": {
        "name": "PM2.5",
        "device_class": "pm25",
        "unit_of_measurement": "µg/m³",
        "state_class": "measurement",
    },
}

def publish_discovery(client):
    """Publish discovery configs for all sensors."""
    for sensor_key, config in SENSORS.items():
        unique_id = f"{DEVICE_ID}_{sensor_key}"
        discovery_topic = f"homeassistant/sensor/{unique_id}/config"

        payload = {
            "name": config["name"],
            "unique_id": unique_id,
            "state_topic": f"{DEVICE_ID}/{sensor_key}/state",
            "device_class": config["device_class"],
            "unit_of_measurement": config["unit_of_measurement"],
            "state_class": config["state_class"],
            "device": {
                "identifiers": [DEVICE_ID],
                "name": "Enviro+ Sensor",
                "manufacturer": "Pimoroni",
                "model": "Enviro+",
            },
        }

        client.publish(discovery_topic, json.dumps(payload), qos=1, retain=True)
        print(f"Published discovery for {config['name']}")

# Connect and publish
client = mqtt.Client(mqtt.CallbackAPIVersion.VERSION2)
client.connect(BROKER, 1883, 60)
publish_discovery(client)

# Publish sample values
client.publish(f"{DEVICE_ID}/temperature/state", "23.5", qos=1)
client.publish(f"{DEVICE_ID}/humidity/state", "65", qos=1)
client.publish(f"{DEVICE_ID}/pressure/state", "1013.25", qos=1)
client.publish(f"{DEVICE_ID}/pm2_5/state", "12.3", qos=1)

client.disconnect()
```

## Resilient MQTT Pattern

For production devices, use auto-reconnect and offline queuing:

```python
from collections import deque
import paho.mqtt.client as mqtt


class ResilientMQTT:
    """MQTT client with offline queuing and auto-reconnect."""

    def __init__(self, broker: str, port: int = 1883):
        self.broker = broker
        self.port = port
        self.connected = False
        self._message_queue = deque(maxlen=1000)
        self.client = mqtt.Client(mqtt.CallbackAPIVersion.VERSION2)
        self.client.on_connect = self._on_connect
        self.client.on_disconnect = self._on_disconnect

    def connect(self):
        """Connect with auto-reconnect enabled."""
        self.client.reconnect_delay_set(min_delay=1, max_delay=60)
        self.client.connect_async(self.broker, self.port, keepalive=60)
        self.client.loop_start()

    def _on_connect(self, client, userdata, flags, reason_code, properties):
        if reason_code == 0:
            self.connected = True
            self._publish_discovery()  # Re-publish on reconnect
            self._flush_queue()

    def _on_disconnect(self, client, userdata, flags, reason_code, properties):
        self.connected = False

    def publish(self, topic: str, payload: str, qos: int = 1):
        """Publish with offline queuing."""
        if self.connected:
            self.client.publish(topic, payload, qos=qos)
        else:
            self._message_queue.append({"topic": topic, "payload": payload})

    def _flush_queue(self):
        """Publish queued messages on reconnect."""
        while self._message_queue and self.connected:
            msg = self._message_queue.popleft()
            self.client.publish(msg["topic"], msg["payload"], qos=1)

    def _publish_discovery(self):
        """Re-publish discovery configs on reconnect."""
        # Implement your discovery publishing logic here
        pass
```

See `references/sensor_configs.md` for complete sensor configuration templates, best practices, testing commands, and entity removal procedures.

## Resources

- [references/sensor_configs.md](references/sensor_configs.md) - Complete sensor configuration templates
- [scripts/mqtt_discovery.py](scripts/mqtt_discovery.py) - Multi-sensor discovery publisher

License

Declared license: MIT

MIT License

Copyright (c) 2026 majiayu000

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

View the license in the source repository — the version published there is authoritative.