Topology

The circuitpython_homie module holds the Homie implementations for a device, node, and property. See the circuitpython_homie.recipes module for specialized properties that implement certain datatypes defined by the Homie Specifications.

This library’s data structures follows the Homie specification’s topology. Because this implementation is written in pure python, the attributes of a Homie device/node/property are instance attributes of the respective objects.

g device Device attributes nodes node1 Node1 attributes properties device:f2->node1:f0 node2 Node2 attributes properties device:f2->node2:f0 property1 Property1 attributes node1:f2->property1:f0 property2 Property2 attributes node1:f2->property2:f0 property3 Property3 attributes node2:f2->property3:f0 property4 Property4 attributes node2:f2->property4:f0

Simple Example

Let’s say you have a board equipped with an ESP32-Sx chip, and you want to broadcast temperature and humidity data from a DHT sensor to your MQTT broker for use in OpenHAB. Just for fun, we’ll let OpenHAB control your on-board RGB LED too. Structurally, this would be organized like so:

g Homie Device esp32-device attributes nodes DHT node dht-node attributes properties Homie Device:f2->DHT node:f0 LED node led-node attributes properties Homie Device:f2->LED node:f0 Temperature property temperature attributes DHT node:f2->Temperature property:f0 Humidity property humidity attributes DHT node:f2->Humidity property:f0 Color property color attributes LED node:f2->Color property:f0
from circuitpython_homie import HomieDevice, HomieNode
from circuitpython_homie.recipes import PropertyFloat, PropertyRGB

# declare device
# let mqtt_client be the instantiated adafruit_minimqtt.MQTT object
my_device = HomieDevice(mqtt_client, "esp32-device", "esp32-device-id")

# declare nodes
dht_node = HomieNode("dht-node", "sensor")
led_node = HomieNode("led-node", "LED")

# declare properties
temperature_property = PropertyFloat("temperature")
humidity_property = PropertyFloat("humidity")
led_color_property = PropertyRGB("color", settable=True)

# append the nodes to the device
my_device.nodes.extend([dht_node, led_node])

# append the properties to the appropriate nodes
dht_node.properties.extend([temperature_property, humidity_property])
led_node.properties.append(led_color_property)
Legend
  • homie denotes the default base topic for all Homie implementations. This can be changed via the HomieDevice.base_topic attribute.

  • topic denotes a base topic for a device, node, or property.

  • topic denotes a base topic for attributes that belong to a device, node, or property.

  • value denotes a topic’s message (or value). Notice that nodes’ base topic do not have a corresponding message.

  • homie

    • esp32-device-id

      • homie = 4.0.0

      • name = esp32-device

      • state = ready

      • extensions = null.dummy:none[3.x;4.x]

      • nodes = dht-node,led-node

      • dht-node

        • name = dht-node

        • type = sensor

        • properties = temperature,humidity

        • temperature = 0.0

          • name = temperature

          • datatype = float

        • humidity = 0.0

          • name = humidity

          • datatype = float

      • led-node

        • name = led-node

        • type = LED

        • properties = color

        • color = 0,0,0

          • name = color

          • datatype = color

          • settable = true