Recipes¶

The circuitpython_homie.recipes module holds any suggested recipes for easily implementing common node properties.

Important

Callback methods are not templated for these properties. Users are advised to write their own callback methods and set them to the desired property’s callback attribute.

Colors¶

class circuitpython_homie.recipes.PropertyRGB(name: str, property_id: str = None, **extra_attributes)[source]¶

A property that can be used to represent node’s color in RGB format.

The parameters here follow the HomieProperty constructor signature, but with a few exceptions:

settable attribute is set to True (can be overridden with a keyword argument)
init_value is set to black "0,0,0" (can be overridden with a keyword argument)
datatype attribute is set to "color" (shall not be overridden)
format attribute is set to "rgb" (shall not be overridden)

validate(color: str | Sequence[int]) → list[int][source]¶

Translate a color string into a valid 3-tuple of integers.

Parameters¶

color: str | Sequence[int]¶: The color as a string in which the elements are delimited by commas (,).

Throws¶

An AssertionError is raised when the given color string is malformed or the color’s components are out of bounds.

Returns¶

A 3 tuple consisting of the color’s 3 components.

class circuitpython_homie.recipes.PropertyHSV(name: str, property_id: str = None, **extra_attributes)[source]¶

A property that can be used to represent node’s color in HSV format.

The parameters here follow the HomieProperty constructor signature, but with a few exceptions:

init_value is set to black "0,0,0" (can be overridden with a keyword argument)
datatype attribute is set to "color" (shall not be overridden)
format attribute is set to "hsv" (shall not be overridden)

validate(color: str | Sequence[int]) → list[int][source]¶

Translate a color string into a valid 3-tuple of integers.

Parameters¶

color: str | Sequence[int]¶: The color as a string in which the elements are delimited by commas (,).

Throws¶

An AssertionError is raised when the given color string is malformed or the color’s components are out of bounds.

Returns¶

A 3 tuple consisting of the color’s 3 components.

Boolean¶

class circuitpython_homie.recipes.PropertyBool(name: str, property_id: str = None, init_value=False, **extra_attributes)[source]¶

Bases: HomieProperty

A property to represent boolean data.

The parameters here follow the HomieProperty constructor signature, but with a few exceptions:

datatype attribute is set to "boolean" (shall not be overridden)
init_value is set to False (can be overridden with a keyword argument)

static validate(value: str | bool) → bool[source]¶

Validates a str that describes a boolean.

Parameters¶

value: str | bool¶

The boolean’s description. According to the Homie specifications, this string value can only be "true or "false" (case-sensitive).

This function will convert the given str to lowercase form. If a bool is passed, then this function simply returns it.

Returns¶

A bool object.

Throws¶

An AssertionError is raised if the given string value is not in compliance with Homie specifications.

Numbers¶

class circuitpython_homie.recipes.PropertyPercent(name: str, datatype: str = 'float', property_id: str = None, init_value=0, **extra_attributes)[source]¶

A property that represents a percentage.

The parameters here follow the HomieProperty constructor signature, but with a few exceptions:

unit attribute is set to "%" (shall not be overridden)
datatype attribute is constrained to "integer" or its default "float" values (can be overridden with a keyword argument)
format attribute is set to "0:100", which describes an inclusive range from 0 to 100, but it is not have to be this range (can be overridden with a keyword argument)
init_value defaults to 0 because percentage type payloads cannot be empty rings (can be overridden with a keyword argument)

validate(value: str | int | float) → int | float¶

Make assertions that a given value is in the format range.

Parameters¶

value: str | int | float¶: The value to validate. If this value is a str, then it is converted to an int or float according to the datatype attribute.

Throws¶

An AssertionError is raised when the given value is malformed.

Returns¶

The validated value (as specified by the value parameter).

class circuitpython_homie.recipes.PropertyInt(name: str, property_id: str = None, init_value=0, **extra_attributes)[source]¶

A property to represent an integer.

The parameters here follow the HomieProperty constructor signature, but with a few exceptions:

datatype attribute is set to "integer" (shall not be overridden)
init_value is set to 0 (can be overridden with a keyword argument)
format attribute can optionally be used to define the constraining range. By default, the format attribute is unspecified (can be overridden with a keyword argument).

validate(value: str | int | float) → int | float¶

Make assertions that a given value is in the format range.

Parameters¶

value: str | int | float¶: The value to validate. If this value is a str, then it is converted to an int or float according to the datatype attribute.

Throws¶

An AssertionError is raised when the given value is malformed.

Returns¶

The validated value (as specified by the value parameter).

class circuitpython_homie.recipes.PropertyFloat(name: str, property_id: str = None, init_value=0.0, **extra_attributes)[source]¶

A property to represent an float.

The parameters here follow the HomieProperty constructor signature, but with a few exceptions:

datatype attribute is set to "float" (shall not be overridden)
init_value is set to 0.0 (can be overridden with a keyword argument)
format attribute can optionally be used to define the constraining range. By default, the format attribute is unspecified (can be overridden with a keyword argument).

validate(value: str | int | float) → int | float¶

Make assertions that a given value is in the format range.

Parameters¶

value: str | int | float¶: The value to validate. If this value is a str, then it is converted to an int or float according to the datatype attribute.

Throws¶

An AssertionError is raised when the given value is malformed.

Returns¶

The validated value (as specified by the value parameter).

Time¶

class circuitpython_homie.recipes.PropertyDateTime(name: str, property_id: str = None, init_value='2000-01-01T00:00:00', **extra_attributes)[source]¶

Bases: HomieProperty

A property that represents a data and time in ISO 8601 format.

The parameters here follow the HomieProperty constructor signature, but with a few exceptions:

datatype attribute is set to "datetime" (shall not be overridden)
init_value is set to "2000-01-01T00:00:00" (can be overridden with a keyword argument)

Hint

Validation of the payload format can be done using the datetime library or the adafruit_datetime library.

static convert(value: struct_time) → str[source]¶

Takes a struct_time object and returns a str in compliance with ISO 8601 standards.

Parameters¶

value: struct_time¶: The named tuple to translate.

Returns¶

A ISO 8601 compliant formatted string in the form YYYY-MM-DDTHH:MM:SS.

class circuitpython_homie.recipes.PropertyDuration(name: str, property_id: str = None, init_value='PT0S', **extra_attributes)[source]¶

Bases: HomieProperty

A property that represents a duration of time in ISO 8601 Duration format.

The parameters here follow the HomieProperty constructor signature, but with a few exceptions:

datatype attribute is set to "duration" (shall not be overridden)
init_value is set to "PT0S" (can be overridden with a keyword argument)

Hint

Validation of the payload format can be done using the datetime library or the adafruit_datetime library.

static convert(value: int | float) → str[source]¶

Takes a a number of seconds and returns a str in compliance with ISO 8601 Duration standards.

Note

For minimality, this function will only convert a number of seconds into units of hours, minutes, and seconds.

Parameters¶

value: int | float¶: The number of seconds that describe a duration. If a float object is passed, then the fractional seconds are truncated.

Returns¶

A ISO 8601 Duration compliant formatted string in the form PTnHnMnS.

Only units with a non-zero value are represented. For instance, a value of 59 will return "PT59S" (representing 59 seconds), and a value of 3609 will return "PT1H9S" (representing 1 hour and 9 seconds).

Helpers¶

These module attributes help validation of certain values.

circuitpython_homie.validate_id(_id: str) → str[source]¶

Conform and validate a given ID to Homie specifications.

Parameters¶

_id: str¶

The given ID.

Note

This function strips - characters from the beginning and ending of the ID. A leading $ is also removed since that character is reserved for Homie attributes.

Throws¶

If the given ID contains anything other than lowercase letters (a-z), numbers (0-9), or hyphens (-), then this function will raise a ValueError exception.

Returns¶

A valid ID from the value passed to the _id parameter.

circuitpython_homie.DEVICE_STATES = ['init', 'ready', 'disconnected', 'sleeping', 'alert', 'lost']¶: A list of valid device states according to the Homie specification’s Life Cycle.

circuitpython_homie.PAYLOAD_TYPES = ['integer', 'float', 'boolean', 'string', 'enum', 'color', 'datetime', 'duration']¶

A valid payload type (per Homie specifications) is one of these defined types: