Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/agners/micropython-ha-mqtt-device
MicroPython module which allows to create Entites for HomeAssistant using MQTT Discovery
https://github.com/agners/micropython-ha-mqtt-device
Last synced: 16 days ago
JSON representation
MicroPython module which allows to create Entites for HomeAssistant using MQTT Discovery
- Host: GitHub
- URL: https://github.com/agners/micropython-ha-mqtt-device
- Owner: agners
- License: mit
- Created: 2020-05-08T00:20:37.000Z (over 4 years ago)
- Default Branch: master
- Last Pushed: 2020-05-08T00:20:59.000Z (over 4 years ago)
- Last Synced: 2024-05-02T00:34:43.296Z (6 months ago)
- Language: Python
- Size: 3.91 KB
- Stars: 8
- Watchers: 2
- Forks: 2
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-micropython - micropython-ha-mqtt-device - MicroPython module which allows creating Entites for HomeAssistant using MQTT Discovery. (Libraries / Communications)
README
# MicroPython library to create sensors for HomeAssistant using MQTT Discovery
This is a simple MicroPython library which allows to create sensors and group of
sensors for HomeAssistant. The library makes use of the HomeAssistant [MQTT
Discovery](https://www.home-assistant.io/docs/mqtt/discovery/) method by
announcing the devices through a configuration topic.## Getting Started
### Prerequisites
* MicroPython board capable of sending MQTT messages
* HomeAssistant with MQTT Broker running
* Some kind of sensor (not mandatory, but useful ;-))### Usage
#### MQTT Client
First a MQTT Client needs to be created. The module
[umqtt.simple](https://github.com/micropython/micropython-lib/tree/master/umqtt.simple)
provides a simple MQTT client. The module can be installed using upip. Make
sure you are connected to the internet, e.g. using WiFi:```
import network
wl = network.WLAN(network.STA_IF)
wl.active(True)
wl.connect(, )
wl.config(dhcp_hostname="Testboard")
```Install the `umqtt.simple` module and create a MQTTClient object:
```
upip.install("micropython-umqtt.simple")
from umqtt.simple import MQTTClient
mqttc = MQTTClient(b"umqtt-testboard", , keepalive=10)
mqttc.connect()
```#### Basic sensor
This example creates a single sensor and announces values. The second argument
to the `Sensor` constructor is the name argument and will be the entity name in
HomeAssistant. The argument `extra_config` allows to pass additional
configuration values as specified by the [MQTT Sensor
Component](https://www.home-assistant.io/integrations/sensor.mqtt/). In this
case the device class and unit of measurement of the sensor is specified.With the creation of the Sensor object a persistent MQTT message is sent to the
discovery topic. The configuration will be picked up by HomeAssistant and a
sensor is created. The topic for the entites states update is handled by the
class.The `publish_state()` function will send the MQTT message to the state topic
which will update the state of the particular entity in HomeAssistant.```
# Temperature sensor...
import time
temp_config = { "unit_of_measurement": "°C", "device_class": "temperature" }
temp = Sensor(mqttc, b"temperature_sensor", b"sensorid", extra_conf=temp_config)
for i in range(10, 30):
temp.publish_state(str(i))
time.sleep(1)# This deletes the sensor from HomeAssistant as well!
temp.remove_entity()
```#### Multiple sensors
Multiple entities can share the same MQTT state topic. This allows to send a
single (JSON formatted) MQTT message to update multiple entites in
HomeAssistant. For this each entity needs to have a `value_template` specified
so each entity know which value it needs to parse.```
group = EntityGroup(mqttc, b"testboard")
sensor1_config = { "unit_of_measurement": "°C", "device_class": "temperature",
"value_template": "{{ value_json.temperature }}" }
sensor1 = group.create_sensor(b"test1", b"test1id", extra_conf=sensor1_config)sensor2_config = { "unit_of_measurement": "%", "device_class": "humidity",
"value_template": "{{ value_json.humidity }}" }
sensor2 = group.create_sensor(b"test2", b"test2id", extra_conf=sensor2_config)
```To update the group the `publish_state()` function on the group object needs to
be used:
```
for i in range(10, 30):
group.publish_state({ "temperature": str(i), "humidity": str(10 + i) })
time.sleep(1)
```To delete all entities of this group:
```
group.remove_group()
```#### Multiple sensors with Device registry
HomeAssistant allows to group entites into devices via the [Device
Registry](https://developers.home-assistant.io/docs/device_registry_index/)
concept. MQTT entities allow to use the [device
registry](https://www.home-assistant.io/integrations/sensor.mqtt/#device) to
group individual entities to a device as well.For this to work a `device` dictionary needs to be added to the configuration
variable. A `unique_id` property with a unique ID for each entity is required
too.```
device_conf = { "identifiers": [ "common_identifier" ], "name": "Testboard",
"manufacturer": "MicroPython", "model": "TinyPico", "sw_version": "0.1" }
common_conf = { "device": device_conf }
group = EntityGroup(mqttc, b"testboarder", extra_conf=common_conf)sensor1_config = { "unit_of_measurement": "°C", "device_class":
"temperature", "value_template": "{{ value_json.temperature }}"),
"unique_id": mqtt_status + "sensor1"}
sensor1 = group.create_sensor(b"test1", b"test1id", extra_conf=sensor1_config)sensor2_config = { "unit_of_measurement": "%", "device_class":
"humidity", "value_template": "{{ value_json.humidity }}",
"unique_id": mqtt_status + "sensor2"}
sensor2 = group.create_sensor(b"test2", b"test2id", extra_conf=sensor2_config)
```Publishing state and removing the group stays the same as regular entity
groups.#### Using availability topic
MQTT allows to specify a last will message which is sent to the specified topic
when a device does not connect for a certain period. The last will message is
transmitted when connecting, hence this needs to be configured before
connecting. Also choose a keep alive timeout which is higher than your expected
sensor update time. E.g. if you plan to update the sensor value every minute,
a value higher than 60 seconds make sense. The same topic then needs to be
specified when creating the sensor:```
mqtt_availability_topic = b"testboard/status"
mqttc = MQTTClient(b"umqtt-testboard", , keepalive=70)
mqttc.set_last_will(mqtt_status, b"offline", True)
mqttc.connect()
mqttc.publish(mqtt_status, b"online", retain=True)temp_config = { "availability_topic": mqtt_availability_topic }
temp = Sensor(mqttc, b"temperature_sensor", b"sensorid", extra_conf=temp_config)
```## License
This project is licensed under the MIT License - see the
[LICENSE](LICENSE) file for details