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 toTrue
(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)
-
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)
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 toFalse
(can be overridden with a keyword argument)
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 to0
because percentage type payloads cannot be empty rings (can be overridden with a keyword argument)
-
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 to0
(can be overridden with a keyword argument)format
attribute can optionally be used to define the constraining range. By default, theformat
attribute is unspecified (can be overridden with a keyword argument).
-
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 to0.0
(can be overridden with a keyword argument)format
attribute can optionally be used to define the constraining range. By default, theformat
attribute is unspecified (can be overridden with a keyword argument).
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 theadafruit_datetime
library.- static convert(value: struct_time) str [source]¶
Takes a
struct_time
object and returns astr
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 theadafruit_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¶
- 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 of3609
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¶
- Throws¶
If the given ID contains anything other than lowercase letters (a-z), numbers (0-9), or hyphens (
-
), then this function will raise aValueError
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.