| Name | hamqa JSON |
| Version |
0.5.0
JSON |
| download |
| home_page | https://github.com/hvalev/hamqa |
| Summary | Home Assistant MQTT autodiscovery sensor registration and publishing library |
| upload_time | 2024-11-27 14:22:21 |
| maintainer | None |
| docs_url | None |
| author | hvalev |
| requires_python | >=3.8 |
| license | MIT |
| keywords |
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# hamqa - Home Assistant MQTT autodiscovery sensor registration library
[](https://github.com/hvalev/hamqa/actions/workflows/build.yml)
[](https://pepy.tech/project/hamqa)
[](https://pepy.tech/project/hamqa)
[](https://pepy.tech/project/hamqa)
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.
```python
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})
```
```python
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:
```python
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`
Raw data
{
"_id": null,
"home_page": "https://github.com/hvalev/hamqa",
"name": "hamqa",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": null,
"author": "hvalev",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/0d/55/04f5b1621dcc52782b3abb0fcf1d3627b47c38d7700948fbae2df3d68295/hamqa-0.5.0.tar.gz",
"platform": null,
"description": "# hamqa - Home Assistant MQTT autodiscovery sensor registration library\n[](https://github.com/hvalev/hamqa/actions/workflows/build.yml)\n[](https://pepy.tech/project/hamqa)\n[](https://pepy.tech/project/hamqa)\n[](https://pepy.tech/project/hamqa)\n\nThe **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.\n\n## Features\n\n- Register and manage multiple sensors for a single device.\n- Automatically handle Home Assistant MQTT discovery.\n- Publish sensor values in both single-sensor and multi-sensor devices.\n- Flexible configuration of MQTT topic paths.\n- Easily remove devices from Home Assistant via MQTT.\n- Includes a micropython equivalent implementation\n\n## Installation\n\nInstall the dependencies required for this library:\n\n`pip install hamqa`\n\n## Example Usage\n\nBelow are examples for one or more sensors.\n\n```python\nimport paho.mqtt.client as mqtt\nfrom hamqa import HAMQTTDevice\n\nip_address = 'xxx.xxx.xxx.xxx'\nmqtt_client = mqtt.Client(mqtt.CallbackAPIVersion.VERSION2)\nmqtt_client.connect(ip_address, 1883, 60)\n\nsingle_sensor = HAMQTTDevice(client=mqtt_client, \n base_topic=\"home\",\n device_id=\"lx_device\")\n\nsingle_sensor.add_sensor(sensor_name=\"illumination\", \n kwargs={\"device_class\":\"illuminance\", \"unit_of_measurement\":\"lx\"})\n\nsingle_sensor.register_sensors()\nsingle_sensor.publish_value({'illumination': 300})\n```\n\n```python\nimport paho.mqtt.client as mqtt\nfrom hamqa import HAMQTTDevice\n\nip_address = 'xxx.xxx.xxx.xxx'\nmqtt_client = mqtt.Client(mqtt.CallbackAPIVersion.VERSION2)\nmqtt_client.connect(ip_address, 1883, 60)\n\nmulti_sensor = HAMQTTDevice(client=mqtt_client, \n base_topic=\"home\",\n device_id=\"temp_hum_device\")\n\nmulti_sensor.add_sensor(sensor_name=\"temperature\",\n kwargs={\"device_class\":\"temperature\", \"unit_of_measurement\":\"\u00b0C\"})\nmulti_sensor.add_sensor(sensor_name=\"humidity\",\n kwargs={\"device_class\":\"humidity\", \"unit_of_measurement\":\"%\"})\n\nmulti_sensor.register_sensors()\nsensor_values = {\"temperature\": 22, \"humidity\": 60}\nmulti_sensor.publish_value(sensor_values)\n```\n\n## Home Assistant Discovery Path Example\n\nFor a temperature sensor, the discovery topic will look like:\n\n`homeassistant/sensor/multi_sensor/temperature/config`\n\n\n## Sensor Value Topic Example\n\nFor the same temperature sensor, the sensor value topic will be:\n\n`home/multi_sensor/temperature/state`\n\n\n## Custom Path Patterns\n\nYou 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.\n\nExample:\n\n```python\ncustom_pattern = \"custom/{device_id}/{sensor_type}/{sensor_name}/config\" \nmulti_sensor.set_path_pattern(custom_pattern)\n```\n\nThis will change the discovery path to:\n\n`custom/multi_sensor/sensor/temperature/config`",
"bugtrack_url": null,
"license": "MIT",
"summary": "Home Assistant MQTT autodiscovery sensor registration and publishing library",
"version": "0.5.0",
"project_urls": {
"Homepage": "https://github.com/hvalev/hamqa"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "950fcd7dd3031cc605cb179726e5a13c748a31d3f068ee4223eb380c180aa136",
"md5": "d35f7cee25ff50e0d8e23032bbff93aa",
"sha256": "2a1ce2ebc20ce64a6dac845c76a29f2fec115bcb5ad24e2525f347a25c0b9368"
},
"downloads": -1,
"filename": "hamqa-0.5.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d35f7cee25ff50e0d8e23032bbff93aa",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 6375,
"upload_time": "2024-11-27T14:22:20",
"upload_time_iso_8601": "2024-11-27T14:22:20.053291Z",
"url": "https://files.pythonhosted.org/packages/95/0f/cd7dd3031cc605cb179726e5a13c748a31d3f068ee4223eb380c180aa136/hamqa-0.5.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "0d5504f5b1621dcc52782b3abb0fcf1d3627b47c38d7700948fbae2df3d68295",
"md5": "76e6578ccd37f89da854281b2c1b387c",
"sha256": "f682f47c5a345a6796a1ebae92a1c547955e29e13ea740d33bf75fd545c93792"
},
"downloads": -1,
"filename": "hamqa-0.5.0.tar.gz",
"has_sig": false,
"md5_digest": "76e6578ccd37f89da854281b2c1b387c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 4728,
"upload_time": "2024-11-27T14:22:21",
"upload_time_iso_8601": "2024-11-27T14:22:21.567609Z",
"url": "https://files.pythonhosted.org/packages/0d/55/04f5b1621dcc52782b3abb0fcf1d3627b47c38d7700948fbae2df3d68295/hamqa-0.5.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-27 14:22:21",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "hvalev",
"github_project": "hamqa",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "hamqa"
}
