Homie Device

class circuitpython_homie.HomieDevice(client: MQTT, name: str, device_id: str)[source]

A class to represent an instantiated Homie device.

client: MQTT

An instance of an MQTT client object that the device will use to communicate with a MQTT broker.

name: str

The device’s human friendly name.

device_id: str

A unique identifying string for the device. This should adhere to the Homie ID specifications. Meaning only lowercase letters (a-z) or numbers or hyphens (-) are allowed. This ID is prohibited from starting with a $ and cannot begin or end with a -, thus these characters are stripped from the given input.

base_topic = 'homie'

The base topic used for all HomieDevice instances (class attribute).


Register this Homie device with the MQTT broker.


All keyword arguments are used as parameters that get passed to connect().


The MQTT client object.


A flag to control interaction with Homie’s broadcast topic.


The supported Homie extensions (not implemented by this library).


The Homie firmware name and version in a dict.

implementation = 'CircuitPython on Linux'

The implementation attribute used for all HomieDevice instances (class attribute). The platform specified by default is taken from sysname.


The device’s name attribute.

nodes : list[HomieNode]

The list of nodes for this device.

set_property(prop: HomieProperty, value, multi_node: bool = False)[source]

Change a specified property’s value and publish it to the MQTT broker.

prop: HomieProperty

the instance object representing the device node’s property.


The new value for the property. The data type passed here will depend on the type of HomieProperty (specified by the prop parameter) for which it is being applied.

See also

The Recipes have derivatives of the HomieProperty class with validators implemented accordingly.

multi_node: bool = False

Set this to True if the property is associated with multiple device nodes. By default, only the first node found in association is updated on the MQTT broker.


If the property is not associated with one of the device’s nodes, then a ValueError exception is raised.

set_state(state: str)[source]

Set the device’s state attribute on the MQTT broker.

state: str

The new desired state of the device.


If the specified state value is not a member of DEVICE_STATES, then a ValueError exception is raised.