HTTP APILAN Protocol

Representing Color with HSBK

Suggest Edits

There are many ways to represent color and we have chosen HSBK values for specifying color in LIFX Devices.

With all our products, whether they have one or many zones, each zone can be set to their own HSBK value using the LIFX binary protocol.

HSBK has four components to it, as represented by each letter of the acronym:

  • Hue: The section of the color spectrum that represents the color of your device. So for example red is 0, green is 120, etc
  • Saturation: How strong the color is. So a zero saturation is completely white, whilst full saturation is the full color
  • Brightness: How bright the color is. So zero brightness is the same as the device is off, while full brightness be just that.
  • Kelvin: The "temperature" when the device has zero saturation. So a higher value is a cooler white (more blue) whereas a lower value is a warmer white (more yellow)

You can find more information about the HSB and K parts of HSBK on wikipedia.

Usually hue is a value between 0 and 360 while saturation and brightness are values between 0 and 1. However we represent these three numbers as Uint16 values between 0 and 65535.

This means to convert a hue value to and from a Uint16 you need to do something like the following. Note that we use 0x10000 instead of 65535 and perform some rounding to provide consistent values when we go back and forth between these conversions.

# From a 0-360 value to a 0-65535 value
hue = 120
uint16_hue = int(round(0x10000 * hue) / 360)) % 0x10000

# from a 0-65535 value to a 0-360 value
hue = round(float(uint16_hue) * 360 / 0x10000, 2)

And converting a saturation or brightness value is a bit easier, and also we can round to more decimal places:

# From a 0-1 value to a 0-65535 value
saturation = 0.5
uint16_saturation = int(round(0xFFFF * saturation))

# from a 0-65535 value to a 0-1 value
saturation = round(float(uint16_saturation) / 0xFFFF, 4)

The kelvin is also represented as a Uint16 number but our devices only support a certain portion of the full 0 to 65535 range. For example some of products accept a range between 1500 and 9000 and you would set the value as just that. You can find the kelvin ranges supported by our different products on the Products page

Updated about 3 years ago