Homie Property¶

class circuitpython_homie.HomieProperty(name: str, datatype: str = 'string', property_id: str = None, init_value='', **extra_attributes)[source]¶

A class to represent a single property of a Homie device’s node.

Parameters¶

name: str¶: The human friendly name of the node.
datatype: str = 'string'¶: The node’s datatype. Valid data types are defined in PAYLOAD_TYPES. Default is "string".
property_id: str = None¶: A unique identifying str to use in the generated MQTT topic. If this parameter is not specified, then the name parameter will be used (providing it conforms to Homie specifications - see validate_id()).
init_value=''¶: The property’s initial value.

Throws¶

A ValueError can indicate if the specified datatype or property_id is invalid. The exception’s message will indicate which value.

Warning

All attributes for this class should be considered read-only after calling HomieDevice.begin(). This is because the attributes published to the MQTT broker are not dynamically updated without calling HomieDevice.begin() after changing the attributes’ value.

property callback¶

This attribute shall hold a pointer to a callback function that is called when the property’s value changes via broker subscription.

Conventionally, this will require echoing the data back to the broker as confirmation.

See also

Use HomieDevice.set_property() to echo back a confirmation to the MQTT broker.

prop1 = HomieProperty("signage", settable=True)

def new_signage(client: MQTT, topic, :str, message: str):
    # let `my_device` be the instantiated HomieDevice object
    my_device.set_property(prop1, message)  # confirm with broker
    # Optionally do something with the new value
    print("received:", prop1.value)

prop1.callback = new_signage

Using a lambda

CircuitPython also supports lambda objects.

prop2 = HomieProperty("signage", settable=True)
prop2.callback = lambda *args: my_device.set_property(prop2, args[2])

This assumes that the property’s value will be used elsewhere.

datatype¶: The property’s datatype attribute.

is_retained() → bool[source]¶

By default, all properties are published as retained topics. This can be controlled by declaring a retained bool attribute.

>>> prop1 = HomieProperty("demo-1")
>>> prop1.is_retained()
True
>>> prop2 = HomieProperty("demo-2", retained=False)
>>> prop2.is_retained()
False

is_settable() → bool[source]¶

Can this property be manipulated from the broker? This is controlled by the declaring a settable bool attribute. By default, all properties are not settable.

>>> prop1 = HomieProperty("demo-1")
>>> prop1.is_settable()
False
>>> prop2 = HomieProperty("demo-2", settable=True)
>>> prop2.is_settable()
True

name¶: The property’s human friendly name attribute

property_id¶: The property’s ID as used in the generated MQTT topic.

property value¶

The current value of the property.

Read Only

This function will not update the value on the MQTT broker. Instead use HomieDevice.set_property() to do that.

Returns¶

A usable object as a result of validation. This class has no implemented validation method because it is meant to be a derivative’s base class. Therefore, this function simply returns the specified value.