pyziggy.workarounds¶

Contains somewhat generally applicable modifications to the autogenerated parameter data and behavior.

The workaround functions are applied to the AvailableDevices before connecting to the MQTT broker.

These are modifications that I’ve found necessary to have unsurprising behavior when implementing common automations such as various smart switches controlling lights. The modifications are enabled by default, but it’s easy to turn them off. I’m not sure how generally applicable they are, and I suspect changes to Zigbee2MQTT behavior might affect the necessity of these changes, hence the name, workarounds.

For example one of the changes set the minimum and maximum values for hue and saturation sub-parameters in LightWithColor devices. These should ideally be reported by Zigbee2MQTT, but in my testing, they seem to be missing for all sub-parameters of composite parameters. After some experimentation, one can discover that the effective limits are [0, 360] for hue, and [0, 100] for saturation. I wouldn’t be surprised if Zigbee2MQTT eventually started reporting these limits, at which point they would automatically show up in the autogenerated LightWithColor devices.

You can disable these workarounds by accessing the pyziggy.workarounds.applied_workarounds singleton object in your automation script.

Example:

import pyziggy.workarounds
pyziggy.workarounds.fix_light_with_color_min_max_values.set_enabled(False)

Module Attributes

applied_workarounds

This is the object that contains the active workarounds that will be applied to the pyziggy.devices_client.DevicesClient object before starting the MQTT operations.

Classes

`Workaround`(callable, description)	Class that wraps a function that's called prior to starting MQTT communication.
`Workarounds`()	Class aggregating all `pyziggy.workarounds.Workaround` objects.

class pyziggy.workarounds.Workaround(callable: Callable[[DevicesClient], None], description: str)¶

Bases: object

Class that wraps a function that’s called prior to starting MQTT communication. This way the function has a chance to apply modifications to the DevicesClient.

set_enabled(enabled: bool) → None¶

Sets whether a workaround gets applied to your DevicesClient object.

The default setting is True.

class pyziggy.workarounds.Workarounds¶

Bases: object

Class aggregating all pyziggy.workarounds.Workaround objects. You can access the public members to change their enabled state.

fix_light_with_color_min_max_values¶: Modifies LightWithColor devices. Changes hue limits to [0, 360] and saturation limits to [0, 100].

make_action_enum_parameters_always_call_listeners¶: Modifies EnumParameters with the “action” property to call listeners on MQTT messages even if the action is unchanged.

make_action_enum_parameters_use_sync_callbacks¶: Modifies EnumParameters with the “action” property to use synchronous callbacks.

make_setting_color_invalidate_color¶: Modifies LightWithColor device behavior: setting hs, xy or color_temp will mark the other two parameters as stale.

make_setting_state_invalidate_color_temp¶

Modifies LightWithColorTemp device behaviour: marks all color related params as stale when the device is turned on.

If we send color parameter changes to a device that is turned off, it will likely ignore it. Z2M however will send the info to the device, and even in its internal state, Z2M will believe that the light has this new color value.

So it can happen that the device is turned on, has the wrong color, but both Z2M and pyziggy thinks it has the right color, hence it won’t even send a new parameter change with the same value.

Marking the parameters stale ensures, that whatever color we set after the device turns on, will be sent to it.

pyziggy.workarounds.applied_workarounds = <pyziggy.workarounds.Workarounds object>¶

This is the object that contains the active workarounds that will be applied to the pyziggy.devices_client.DevicesClient object before starting the MQTT operations.

The public members of this object are the “workarounds” that modify the default behaviour for certain parameters. You can import this object in your automation code, and call pyziggy.workarounds.Workaround.set_enabled() with a False parameter for a workaround that doesn’t play well with your own Zigbee devices.