# MQTT Entity helper library for Home Assistant
[](https://github.com/kellerza/mqtt_entity/actions)
[](https://codecov.io/gh/kellerza/mqtt_entity)
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
- Manage entities per device
- Home Assistant Entities modelled as attrs classes:
- 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 attrs classes
- 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.
Alternatives 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 :dolphin: emoji as a prefix in the commit message. This will trigger a release on the master branch.
```bash
# Patch
git commit -m ":dolphin: Release 0.0.x"
# Minor
git commit -m ":rocket: Release 0.x.0"
```
### 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.
```bash
uv run pytest --mqtt
```
Raw data
{
"_id": null,
"home_page": null,
"name": "mqtt-entity",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.12",
"maintainer_email": null,
"keywords": "asyncio, discovery, home-assistant, library, mqtt",
"author": "Johann Kellerman",
"author_email": "Johann Kellerman <kellerza@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/28/f9/cbd67f10af9f51e65107da068dac94c1a04b2ee0d7b8a20ab1459de4eb8d/mqtt_entity-1.0.21.tar.gz",
"platform": null,
"description": "# MQTT Entity helper library for Home Assistant\n\n[](https://github.com/kellerza/mqtt_entity/actions)\n[](https://codecov.io/gh/kellerza/mqtt_entity)\n\nA Python helper library to manage Home Assistant entities over MQTT.\n\nUpdated for device based MQTT discovery.\n\nFeatures:\n\n- MQTT client based on paho-mqtt\n - Retrieve MQTT service info from the Home Assistant Supervisor\n- Manage MQTT discovery info (adding/removing entities)\n- MQTTDevice class to manage devices\n - Availability management\n - Manage entities per device\n- Home Assistant Entities modelled as attrs classes:\n - Read-only: Sensor, BinarySensor\n - Read & write: Select, Switch, Number, Text, Light\n - MQTT device events\n- Asyncio based\n- Helpers for Home Assistant add-ons (optional)\n - Add-on configuration modeled as attrs classes\n - Load from environment variables, HA's options.yaml or options.json\n - Load MQTT connection settings from the Supervisor\n - Enable add-on logging (incl colors & debug by config)\n\n## Why?\n\nThis 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.\n\nAlternatives options (not based on asyncio)\n\n- <https://pypi.org/project/ha-mqtt-discoverable/>\n- <https://pypi.org/project/homeassistant-mqtt-binding/>\n\n## Credits\n\n@Ivan-L contributed some of the writable entities to the Sunsynk addon project\n\n## Release\n\nSemantic versioning is used for release.\n\nTo create a new release, include a commit with a :dolphin: emoji as a prefix in the commit message. This will trigger a release on the master branch.\n\n```bash\n# Patch\ngit commit -m \":dolphin: Release 0.0.x\"\n\n# Minor\ngit commit -m \":rocket: Release 0.x.0\"\n```\n\n### Development\n\nTo run the tests, you need to have Python 3.12+ installed.\n\nThe `--mqtt` connects to a live Home Assistant instance using the MQTT broker.\n\n```bash\nuv run pytest --mqtt\n```\n",
"bugtrack_url": null,
"license": null,
"summary": "MQTT client supporting Home Assistant MQTT entity auto-discovery",
"version": "1.0.21",
"project_urls": {
"Homepage": "https://github.com/kellerza/mqtt_entity"
},
"split_keywords": [
"asyncio",
" discovery",
" home-assistant",
" library",
" mqtt"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "95d640e70634c3079185ac77c90a5a7e5ce7a73f97de5acc0892ad31efae3ae0",
"md5": "e3420b5065eb2d4c002ff842953f377c",
"sha256": "9b67064c968b76cff12385cc62c228702cb7bd1548316b626915f54c009af10f"
},
"downloads": -1,
"filename": "mqtt_entity-1.0.21-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e3420b5065eb2d4c002ff842953f377c",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.12",
"size": 19816,
"upload_time": "2025-10-29T20:27:59",
"upload_time_iso_8601": "2025-10-29T20:27:59.013109Z",
"url": "https://files.pythonhosted.org/packages/95/d6/40e70634c3079185ac77c90a5a7e5ce7a73f97de5acc0892ad31efae3ae0/mqtt_entity-1.0.21-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "28f9cbd67f10af9f51e65107da068dac94c1a04b2ee0d7b8a20ab1459de4eb8d",
"md5": "265ce5a30812772fd6cec9a51b7a2b94",
"sha256": "97715a6f356d30286c96ea4af773e5882cab25da1d46a1594117dd3a53f43f5f"
},
"downloads": -1,
"filename": "mqtt_entity-1.0.21.tar.gz",
"has_sig": false,
"md5_digest": "265ce5a30812772fd6cec9a51b7a2b94",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.12",
"size": 16876,
"upload_time": "2025-10-29T20:27:59",
"upload_time_iso_8601": "2025-10-29T20:27:59.804247Z",
"url": "https://files.pythonhosted.org/packages/28/f9/cbd67f10af9f51e65107da068dac94c1a04b2ee0d7b8a20ab1459de4eb8d/mqtt_entity-1.0.21.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-29 20:27:59",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "kellerza",
"github_project": "mqtt_entity",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "mqtt-entity"
}
JSON
