Groups and Locations

Using groups and Locations form the LIFX app in your third party development

The LIFX Application allows users to organize each bulb by giving it a group and location. Most users use groups to represent a room, and location to represent a building (such as a house or office) but this does not need to be the case. These groups and locations are stored on the devices themselves, and are designed so that they can be modified or renamed as long as one of the bulbs in the affected group is powered on.

Groups

Each group is stored in a bulb as three pieces of data, a 16 byte identifier, a 32 byte string and a 64-bit integer timestamp.

FieldType
groupbyte array, size: 16 bytes
labelstring, size: 32 bytes
updated_atunsigned 64-bit integer

When determining what groups are available given the data from all the devices your app can see, each unique ID should be considered a separate group. To determine the correct label to display to the user, you should search the list of all the devices with matching group IDs, and choose the label from the one with the highest timestamp. This allows the protocol to remain resilient even in situations where a group label is changed while one or more of the members of the group are offline.

📘

Groups spanning locations

At this current time groups should not have the same ID across multiple locations. That is to say all groups are subsets of a parent location. Groups that span multiple locations are undefined and may not behave correctly.

Locations

Locations are also stored as three pieces of data similarly to the way a group is stored.

FieldType
locationbyte array, size: 16 bytes
labelstring, size: 32 bytes
updated_atunsigned 64-bit integer

The same algorithm mentioned for groups applies to locations as they share the same semantics. A location is considered to contain the groups of the devices within it, so groups should not span multiple locations.

Control

To control a group of lights simultaneously, you must first determine which devices on your network are in the group or location you want to target, and then message each light individually.