hue-zigbee-encoding 1.0.0

Binary encoding and decoding of Zigbee messages for Hue lights

hue-zigbee-encoding

hue-zigbee-encoding implements encoding and decoding of the binary format used by Philips Hue Zigbee devices.

The format was reverse-engineered by Christian Iversen and described at: https://github.com/chrivers/bifrost/blob/master/doc/hue-zigbee-format.md

Other related resources:

• https://kjagiello.github.io/hue-gradient-command-wizard/
• https://viereck.ch/hue-xy-rgb/

Installation

With pip: pip install hue-zigbee-encoding

With uv: uv add hue-zigbee-encoding

Documentation

HueLightUpdateMessage

The HueLightUpdateMessage class represents multiple attributes of a Hue light, combined into one object. It supports conversion to and from bytes:

from hue_zigbee_encoding import HueLightUpdateMessage

# Convert to bytes: returns b"\x03\x00\x01\x7f"
HueLightUpdateMessage(is_on=True, brightness=127).to_bytes()

# Convert from bytes: returns a HueLightUpdateMessage object
HueLightUpdateMessage.from_bytes(b"\x03\x00\x01\x7f")

Use hex and fromhex to convert to and from printable strings:

# Convert to a hex string: returns "0300017f"
HueLightUpdateMessage(is_on=True, brightness=127).to_bytes().hex()

# Convert from a hex string: returns a HueLightUpdateMessage object
HueLightUpdateMessage.from_bytes(bytes.fromhex("0300017f"))

HueLightUpdateMessage attributes

All attributes are optional (they accept a value of None). You can apply a subset of attributes to change only those settings of Hue lights.

Attribute	Type	Description
is_on	bool | None	Set to True to turn the light on, False to turn off.
brightness	int | None	0–255 (0xFF), although only values 1 (dimmest) through 254 (brightest) are valid.
color_temp	HueLightColorMired | None	Color temperature in mireds. You can also use HueLightColorMired.from_kelvin() to convert from Kelvin.
color_xy	HueLightColorXY | None	Color as XY values. See also: https://viereck.ch/hue-xy-rgb/
transition_time	int | None	0–65535 (0xFFFF). Use 0 for an instantaneous transition, higher numbers for a slower fade.
effect	HueLightEffect | None	Specify one of the light effects from the HueLightEffect enum.
effect_speed	int | None	Animation speed of the selected effect: 0 (slowest) to 255 (fastest).
gradient	HueLightGradient | None	Gradient colors and style (for light strips).
gradient_params	HueLightGradientParams | None	Gradient scale and offset parameters (for light strips).

HueLightColorXY

Color specified as XY coordinates in the range 0–1. See also: https://viereck.ch/hue-xy-rgb/

from hue_zigbee_encoding import HueLightColorXY

HueLightColorXY(x=0.424, y=0.285)

HueLightColorMired

Color temperature specified in mireds.

from hue_zigbee_encoding import HueLightColorMired

# Specify a color temperature in mireds:
HueLightColorMired(mired=40)

# Specify a color temperature in Kelvin:
HueLightColorMired.from_kelvin(25000)

HueLightEffect

This enum describes the predefined effects supported by Hue lights.

Name	Decimal value	Hex value
HueLightEffect.CANDLE	1	0x01
HueLightEffect.FIREPLACE	2	0x02
HueLightEffect.PRISM	3	0x03
HueLightEffect.SUNRISE	9	0x09
HueLightEffect.SPARKLE	10	0x0A
HueLightEffect.OPAL	11	0x0B
HueLightEffect.GLISTEN	12	0x0C
HueLightEffect.SUNSET	13	0x0D
HueLightEffect.UNDERWATER	14	0x0E
HueLightEffect.COSMOS	15	0x0F
HueLightEffect.SUNBEAM	16	0x10
HueLightEffect.ENCHANT	17	0x11

HueLightGradient

This class represents a custom gradient on a light strip.

from hue_zigbee_encoding import HueLightGradient

HueLightGradient(
    style=HueLightGradientStyle.SCATTERED,
    colors=[
        HueLightColorXY(x=0.424, y=0.285),
        HueLightColorXY(x=0.229, y=0.279),
    ],
)

Attribute	Type	Description
style	HueLightGradientStyle	The type of gradient effect. See below for options.
colors	list[HueLightColorXY]	List of colors in the gradient.

HueLightGradientStyle

This enum describes the different styles that can be used for custom gradients on light strips.

Name	Decimal value	Hex value
HueLightGradientStyle.LINEAR	0	0x00
HueLightGradientStyle.SCATTERED	2	0x02
HueLightGradientStyle.MIRRORED	4	0x04

HueLightGradientParams

Gradient scale and offset parameters (for light strips). Values can be between 0 and 31.875 in increments of 0.125 (1/8).

Attribute	Type	Description
scale	float	Number of colors that should fit on the light strip. Ignored in the "scattered" gradient style. A value of 0 is special, blending all the gradient colors smoothly across the whole light strip. Read more at: https://github.com/chrivers/bifrost/blob/master/doc/hue-zigbee-format.md#property-gradient_params-scale
offset	float	Number of lights to skip at the start of the light strip.