pyziggy.parameters¶

Contains the parameter classes that your code can interact with in order to query and modify the device states observable through MQTT.

You are not expected to directly instantiate any of these classes. The main feature of pyziggy is its code generator. The generator will query device information from the MQTT broker and generate the pyziggy_autogenerate.available_devices.AvailableDevices class in your home automation project directory. The public members of this class are all the devices that your MQTT broker knows of. The public members of each device are parameter objects, which are instances of the classes in this module.

You are expected to only instantiate an AvailableDevices object, and access the autogenerated parameters of its autogenerated devices.

Zigbee2MQTT has access flags for each parameter. A parameter may be either queryable or not, and it may either be read-only or writeable as well. Accordingly, each autogenerated parameter object will have the parameter type determined by the access flags.

Example:

Your automation code should access the autogenerated parameters under the devices:

from pyziggy_autogenerate.available_devices import AvailableDevices

devices = AvailableDevices()

devices.kitchen_light.brightness.set(100)

You can add listeners to be notified of parameter changes:

kitchen_brightness = devices.kitchen_light.brightness
kitchen_brightness.add_listener(lambda: print(f"Brightness: {kitchen_brightness.get()}"))

Classes

`BinaryParameter`(property)	A two state parameter that can have a valid value of 0 or 1.
`CompositeParameter`(property)	Base class for Z2M parameters with a type property of composite.
`EnumParameter`(property, enum_values)	Base class for parameters that have a corresponding Z2M parameter with a type of enum.
`NumericParameter`(property, min_value, max_value)	A parameter stored as a single floating point number, and limited to between a minimum and maximum value.
`ParameterBase`(property)	A base class for all other parameter types.
`QueryableBinaryParameter`(property)	A BinaryParameter representing a Z2M parameter with a flags property that is queryable
`QueryableNumericParameter`(property, ...)	A parameter representing a Z2M numeric parameter with a flags property that is queryable.
`QueryableToggleParameter`(property)	A parameter representing a Z2M toggle parameter with a flags property that is queryable.
`SettableAndQueryableBinaryParameter`(property)	A parameter representing a Z2M binary parameter with a flags property that is settable and queryable.
`SettableAndQueryableNumericParameter`(...)	A parameter representing a Z2M numeric parameter with a flags property that is settable and queryable.
`SettableAndQueryableToggleParameter`(property)	A parameter representing a Z2M toggle parameter with a flags property that is settable and queryable.
`SettableBinaryParameter`(property)	A parameter representing a Z2M binary parameter with a flags property that is settable.
`SettableEnumParameter`(property, enum_values)	A parameter representing a Z2M enum parameter with a flags property that is settable.
`SettableNumericParameter`(property, ...)	A parameter representing a Z2M numeric parameter with a flags property that is settable.
`SettableToggleParameter`(property)	A parameter representing a Z2M toggle parameter with a flags property that is settable.
`ToggleParameter`(property)	A two state parameter that can have a valid value of 0 or 1.

class pyziggy.parameters.BinaryParameter(property: str)¶

Bases: NumericParameter

A two state parameter that can have a valid value of 0 or 1.

Represents MQTT parameters whose definition.features.type property is binary.

class pyziggy.parameters.CompositeParameter(property: str)¶

Bases: ParameterBase

Base class for Z2M parameters with a type property of composite.

Such parameters are made up of multiple simple parameters. These will be added by the pyziggy autogenerator as public members to a derived CompositeParameter class.

Example:

composite_param = devices.color_bulb.color_hs
composite_param.hue.set(120)
composite_param.saturation.set(50)

final mark_as_stale()¶

Use this function to mark the parameter as stale, if for whatever reason, we can’t assume that the parameter’s value correctly reflects the physical device’s state.

This will override the default logic where the SettableNumericParameter.set() and SettableNumericParameter.set_normalized() functions only emit MQTT messages if the parameter’s stored state is different from the new one.

This way you can practically force emitting an MQTT message that requires the device parameter to be set to the required value. The first :SettableNumericParameter.set() or SettableNumericParameter.set_normalized() call clears the stale state, returning the parameter logic to follow the default behavior.

class pyziggy.parameters.EnumParameter(property: str, enum_values: List[str])¶

Bases: NumericParameter

Base class for parameters that have a corresponding Z2M parameter with a type of enum.

The pyziggy autogenerator generates derived classes that return and take concrete enum types also autogenerated based on Z2M parameter information. These derived classes will all have a public enum_type member to provide type safety and code completion.

Example:

def light_switch_handler():
    action_enum = devices.light_switch.action.enum_type
    action = devices.light_switch.action.get_enum_value()

    if action == action_enum.brightness_move_up:
        kitchen_light.brightness.add_normalized(0.075)
    elif action == action_enum.brightness_move_down:
        kitchen_light.brightness.add_normalized(-0.075)

devices.light_switch.action.add_listener(light_switch_handler)

class pyziggy.parameters.NumericParameter(property: str, min_value: float, max_value: float)¶

Bases: ParameterBase

A parameter stored as a single floating point number, and limited to between a minimum and maximum value.

This value is used to represent Z2M parameters whether they have an integral or floating point representation and granularity.

The minimum and maximum values are determined by the pyziggy generator based on the parameter information shared by Z2M. Sometimes Z2M fails to report these values, specifically I’ve seen them missing for members of CompositeParameters. In this case the generator will choose a very large default range to avoid accidentally clamping the values exchanged with Z2M.

final get() → float¶

Returns:: The parameter’s raw value as it is known by Z2M.

get_maximum() → float¶

Returns:: The upper limit (inclusive) of this parameter’s permitted range.

get_minimum() → float¶

Returns:: The lower limit (inclusive) of this parameter’s permitted range.

final get_normalized() → float¶

Returns:: The parameter’s value mapped to the range [0.0, 1.0]. The range’s start and end represent the values returned by get_minimum() and get_maximum() and the mapping is linear.

set_always_call_listeners_on_report(value: bool) → None¶

Call this function with a True value to always call listeners whenever an update is received from Z2M for the parameter.

The default setting is False.

By default, listeners are only called if the update received from Z2M changes the value compared to the last time when the listeners were called.

The pyziggy framework has a workarounds module that tries to ensure that this value is set to True whenever it makes sense, so you generally shouldn’t need to call this function.

For example the True setting is useful for action parameters in general. Certain light switches for example will send a parameter update for the action parameter with a brightness_up value, whenever the brightness increase button is pressed.

set_call_listeners_synchronously(value: bool) → None¶

Sets whether the parameter’s listeners should be called synchronously when the value changes.

The default setting is False.

The pyziggy framework has a workarounds module that tries to ensure that this value is set to True whenever it makes sense, so you generally shouldn’t need to call this function.

Default parameter listener callback behavior:

Parameter callbacks are called asynchronously by default. A practical consequence of this, is that callback in the following example will only be called at most once after event_handler has run. It will only happen if the parameter value has changed since the last time the listeners were called.

Example:
def callback():
    print(f"Brightness changed to: {devices.light.brightness.get()}")

devices.light.brightness.add_listener(callback)

def event_handler():
    devices.light.brightness.set(20)
    devices.light.brightness.set(30)
    devices.light.brightness.set(40)
This also means that callback cannot observe the transient values during the execution of event_handler. This behavior is intentional and is meant to avoid cascading event callback storms in callback heavy projects.

Discussion:

Calling this function with True is useful for parameters where transient values are significant. For example, it’s possible that we receive multiple consecutive changes to a parameter’s value in a single sub-second message window, but we still need to to observe and serve them all. An action parameter of a rotary dial, or brightness increasing switch could be such a parameter.

As a counter example, if the brightness of a bulb changes in quick succession from 0 to 40 in 0.1 seconds, we probably don’t want to take action on all the intermediate values, but only on the final value at the end of the 0.1 second period.

class pyziggy.parameters.ParameterBase(property: str)¶

Bases: Broadcaster

A base class for all other parameter types.

This type inherits from pyziggy.broadcasters.Broadcaster, so you can call pyziggy.broadcasters.Broadcaster.add_listener() on all parameter objects to be notified when their value changes.

final get_property_name()¶

Used internally. You generally shouldn’t need to call this function, as the property name isn’t used anywhere on the pyziggy public APIs.

Returns:: The name of the parameter as it’s known by MQTT.

class pyziggy.parameters.QueryableBinaryParameter(property: str)¶

Bases: BinaryParameter, QueryableNumericParameter

A BinaryParameter representing a Z2M parameter with a flags property that is queryable

class pyziggy.parameters.QueryableNumericParameter(property: str, min_value: float, max_value: float)¶

Bases: NumericParameter

A parameter representing a Z2M numeric parameter with a flags property that is queryable.

query_device() → None¶

Instructs Z2M to query the device for the current value of this parameter.

This can typically be available for battery powered devices that don’t update their actual parameter values frequently.

If the query procedure is successful Z2M will send a value update, which updates the parameter value and fires any added listeners.

class pyziggy.parameters.QueryableToggleParameter(property: str)¶

Bases: ToggleParameter, QueryableNumericParameter

A parameter representing a Z2M toggle parameter with a flags property that is queryable.

class pyziggy.parameters.SettableAndQueryableBinaryParameter(property: str)¶

Bases: BinaryParameter, SettableAndQueryableNumericParameter

A parameter representing a Z2M binary parameter with a flags property that is settable and queryable.

class pyziggy.parameters.SettableAndQueryableNumericParameter(property: str, min_value: float, max_value: float)¶

Bases: QueryableNumericParameter, SettableNumericParameter

A parameter representing a Z2M numeric parameter with a flags property that is settable and queryable.

class pyziggy.parameters.SettableAndQueryableToggleParameter(property: str)¶

Bases: ToggleParameter, SettableAndQueryableNumericParameter

A parameter representing a Z2M toggle parameter with a flags property that is settable and queryable.

class pyziggy.parameters.SettableBinaryParameter(property: str)¶

Bases: BinaryParameter, SettableNumericParameter

A parameter representing a Z2M binary parameter with a flags property that is settable.

class pyziggy.parameters.SettableEnumParameter(property: str, enum_values: List[str])¶

Bases: EnumParameter, SettableNumericParameter

A parameter representing a Z2M enum parameter with a flags property that is settable.

class pyziggy.parameters.SettableNumericParameter(property: str, min_value: float, max_value: float)¶

Bases: NumericParameter

A parameter representing a Z2M numeric parameter with a flags property that is settable.

add(value: float) → None¶

Equivalent to calling set(get() + value).

The resulting value will be clamped to the permitted range.

add_normalized(value: float) → None¶

Equivalent to calling set_normalized(get_normalized() + value).

The resulting value will be clamped to the permitted range.

mark_as_stale()¶

Use this function to mark the parameter as stale, if for whatever reason, we can’t assume that the parameter’s value correctly reflects the physical device’s state.

This will override the default logic where the set() and set_normalized() functions only emit MQTT messages if the parameter’s stored state is different from the new one.

This way you can practically force emitting an MQTT message that requires the device parameter to be set to the required value. The first set() or set_normalized() call clears the stale state, returning the parameter logic to follow the default behavior.

set(value: float) → None¶

Set the parameter’s desired value. This will instruct Z2M to change the corresponding device’s parameter to this value.

The provided value should be in the MQTT parameter’s original range e.g. a typical brightness parameter will have raw values between 0 and 254, and a color_temp parameter between 250 and 454.

The passed in value will be clamped to the permitted range.

MQTT communication behavior:

The pyziggy framework keeps track of parameter values sent and received and has logic to avoid unnecessarily sending MQTT messages. Calling set() with the same value that the parameter already has will not emit any MQTT messages, unless mark_as_stale() has been called on the parameter prior to set().

The logic that determines whether a parameter value changed runs asynchronously, and this is responsible for sending the MQTT messages as well. This means that it can only happen after the entire call stack has been unwound on which set() has been called. A practical consequence of this, is that the callback in the following example can emit at most a single MQTT message. It will do so if the final value of the parameter is different from what Z2M thinks it is.

Example:
def callback():
    devices.light_bulb.brightness.set(10)
    devices.light_bulb.brightness.set(20)
    devices.light_bulb.brightness.set(30)
    devices.light_bulb.brightness.set(40)

devices.light_switch.action.add_listener(callback)
This behavior is intentional and is meant to eliminate unnecessary MQTT communication in callback heavy projects.

set_normalized(value: float) → None¶

Set the parameter’s desired value by passing a number between 0.0 and 1.0.

This value will be automatically converted to the range of the MQTT parameter e.g. a typical brightness parameter will have raw values between 0 and 254, and a color_temp parameter between 250 and 454. Calling set_normalized(0.0) or set_normalized(1.0) will set both to their respective minimum or maximum values.

The passed in value will be clamped to the permitted range.

This function internally calls set(), consequently its MQTT communication behavior is the same.

class pyziggy.parameters.SettableToggleParameter(property: str)¶

Bases: ToggleParameter, SettableNumericParameter

A parameter representing a Z2M toggle parameter with a flags property that is settable.

class pyziggy.parameters.ToggleParameter(property: str)¶

Bases: NumericParameter

A two state parameter that can have a valid value of 0 or 1.

Represents MQTT parameters whose definition.features.type property is toggle.