hamqa - Home Assistant MQTT autodiscovery sensor registration library
The hamqa library provides an easy way to register and manage MQTT-based sensors for Home Assistant. It handles both devices producing a single or multiple values and allows to easily push updates from those devices to be consumed by Home Assistant.
Features
- Register and manage multiple sensors for a single device.
- Automatically handle Home Assistant MQTT discovery.
- Publish sensor values in both single-sensor and multi-sensor devices.
- Flexible configuration of MQTT topic paths.
- Easily remove devices from Home Assistant via MQTT.
- Includes a micropython equivalent implementation
Installation
Install the dependencies required for this library:
pip install hamqa
Example Usage
Below are examples for one or more sensors.
import paho.mqtt.client as mqtt
from hamqa import HAMQTTDevice
ip_address = 'xxx.xxx.xxx.xxx'
mqtt_client = mqtt.Client(mqtt.CallbackAPIVersion.VERSION2)
mqtt_client.connect(ip_address, 1883, 60)
single_sensor = HAMQTTDevice(client=mqtt_client,
base_topic="home",
device_id="lx_device")
single_sensor.add_sensor(sensor_name="illumination",
kwargs={"device_class":"illuminance", "unit_of_measurement":"lx"})
single_sensor.register_sensors()
single_sensor.publish_value({'illumination': 300})
import paho.mqtt.client as mqtt
from hamqa import HAMQTTDevice
ip_address = 'xxx.xxx.xxx.xxx'
mqtt_client = mqtt.Client(mqtt.CallbackAPIVersion.VERSION2)
mqtt_client.connect(ip_address, 1883, 60)
multi_sensor = HAMQTTDevice(client=mqtt_client,
base_topic="home",
device_id="temp_hum_device")
multi_sensor.add_sensor(sensor_name="temperature",
kwargs={"device_class":"temperature", "unit_of_measurement":"°C"})
multi_sensor.add_sensor(sensor_name="humidity",
kwargs={"device_class":"humidity", "unit_of_measurement":"%"})
multi_sensor.register_sensors()
sensor_values = {"temperature": 22, "humidity": 60}
multi_sensor.publish_value(sensor_values)
Home Assistant Discovery Path Example
For a temperature sensor, the discovery topic will look like:
homeassistant/sensor/multi_sensor/temperature/config
Sensor Value Topic Example
For the same temperature sensor, the sensor value topic will be:
home/multi_sensor/temperature/state
Custom Path Patterns
You can customize the MQTT path for Home Assistant discovery by providing a custom path_pattern. The placeholders {device_id}, {sensor_type}, and {sensor_name} will be replaced with the appropriate values.
Example:
custom_pattern = "custom/{device_id}/{sensor_type}/{sensor_name}/config"
multi_sensor.set_path_pattern(custom_pattern)
This will change the discovery path to:
custom/multi_sensor/sensor/temperature/config
Metadata
Release files for hamqa 0.5.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| hamqa-0.5.0.tar.gz | 4.7 kB | Without provenance | Details for hamqa-0.5.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| hamqa-0.5.0-py3-none-any.whl | Python 3 | none | any | Details for hamqa-0.5.0-py3-none-any.whl |
Total release size: 11.1 kB
Release files / hamqa-0.5.0.tar.gz
| Download URL | hamqa-0.5.0.tar.gz |
|---|---|
| Size | 4.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
f682f47c5a345a6796a1ebae92a1c547955e29e13ea740d33bf75fd545c93792
|
|
BLAKE2b-256 checksum How to use checksums |
0d5504f5b1621dcc52782b3abb0fcf1d3627b47c38d7700948fbae2df3d68295
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
poetry/1.8.4 CPython/3.12.1 Linux/6.5.0-1025-azure
|
Release files / hamqa-0.5.0-py3-none-any.whl
| Download URL | hamqa-0.5.0-py3-none-any.whl |
|---|---|
| Size | 6.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
2a1ce2ebc20ce64a6dac845c76a29f2fec115bcb5ad24e2525f347a25c0b9368
|
|
BLAKE2b-256 checksum How to use checksums |
950fcd7dd3031cc605cb179726e5a13c748a31d3f068ee4223eb380c180aa136
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
poetry/1.8.4 CPython/3.12.1 Linux/6.5.0-1025-azure
|
Security for hamqa 0.5.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.