Skip to main content

hamqa - Home Assistant MQTT autodiscovery sensor registration library

build Downloads Downloads Downloads

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)

Source distribution for hamqa 0.5.0
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)

Table of built distributions (wheels) for hamqa 0.5.0
File Interpreter ABI Platform Actions
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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page