ha-mqtt-device

A thin Python library for creating and maintaining Home Assistant devices that are discoverable via MQTT device discovery. Individual entities associated with a device can be added, updated, and removed through the same API.

Features

• Device discovery: publish the discovery payload Home Assistant needs to automatically pick up your device over MQTT.
• Entity management: add and maintain multiple entities (sensors, switches, lights, binary sensors, dates, datetimes, humidifiers, cameras, device trackers, infrared emitters/receivers, etc.) that belong to a device.
• Event subscriptions: entities can subscribe to MQTT topics and deliver updates — for example switch commands from Home Assistant or infrared emitter signals — to your async callbacks as Event objects.
• Thin and focused: no heavy framework — just the abstractions needed to model a device and its entities.

Requirements

• Python 3.14+
• uv for development and dependency management
• aiomqtt for the MQTT provider (pip install "ha-mqtt-device[mqtt]")

Usage

Runnable examples — for the MQTT provider, device discovery, and every entity (supported and planned) — can be found in EXAMPLES.md.

Development

This project is managed with uv. Common commands:

Project layout

src/ha_mqtt_device/   # library source
tests/                # test suite
examples/             # runnable entity examples
pyproject.toml        # project metadata and tool configuration

License

MIT