MQTT Entity helper library for Home Assistant

A Python helper library to manage Home Assistant entities over MQTT.

Updated for device based MQTT discovery.

Features:

• MQTT client based on paho-mqtt
  • Retrieve MQTT service info from the Home Assistant Supervisor
• Manage MQTT discovery info (adding/removing entities)
• MQTTDevice class to manage devices
  • Availability management (client-wide and optional per-device availability_topics)
  • Manage entities per device
• Home Assistant Entities modelled as dataclasses:
  • Read-only: Sensor, BinarySensor
  • Read & write: Select, Switch, Number, Text, Light
  • MQTT device events
• Asyncio based
• Helpers for Home Assistant add-ons (optional)
  • Add-on configuration modeled as dataclasses
    • Load from environment variables, HA's options.yaml or options.json
    • Load MQTT connection settings from the Supervisor
  • Enable add-on logging (incl colors & debug by config)

Why?

This MQTT code was included in several of my home Assistant addons (SMA-EM / Sunsynk). It is easier to update a single library & add new features, like discovery removal.

Alternative options (not based on asyncio)

• https://pypi.org/project/ha-mqtt-discoverable/
• https://pypi.org/project/homeassistant-mqtt-binding/

Credits

@Ivan-L contributed some of the writable entities to the Sunsynk addon project

Release

Semantic versioning is used for release.

To create a new release, include a commit with a 🐬 emoji as a prefix in the commit message. This will trigger a release on the master branch.

# Patch
git commit -m ":dolphin: Release 0.0.x"

# Minor - any commit

Development

To run the tests, you need to have Python 3.12+ installed.

The --mqtt connects to a live Home Assistant instance using the MQTT broker.

uv run pytest --mqtt