OSRAM Lightify is a smart home, connected lightning technology. Lights, switches and other paired devices are controlled using the Lightify gateway device. This gateway is an always-on, always-connected device which can be controlled using the official Lightify REST API on the Lightify Cloud. That, however, means that all commands need to be routed through the internet.

The official Lightify app, on the other hand, communicates directly with the gateway and uses a proprietary binary protocol which is not publicly specified.

This document is meant to create a public specification of the known facts about how to discover gateway devices, paired devices and zones/groups, as well as how to control those devices.

All information in this document are collected using reverse engineering practices or are available by other implementations / people on the internet. Certain information might be incorrect, outdated or unspecific. Any help completing this document is appreciated, please file pull requests.

Using and/or implementing information in this document might brick your device, render it unfunctional, change behavior of any connected device and/or may void your warranty. Any action taken upon information in this document is strictly at your own risk. The author(s) are not liable for any losses and damages in connection with the use of this document.

The author(s) are not affiliated to OSRAM Light AG in any way. Furthermore is this document not official publicated or approved by OSRAM Licht AG.

The OSRAM Lightify gateway protocol is a binary protocol with a specified header.

The underlying protocol is a persistent TCP connection which does not seem to support multiplexing, therefore multiple requests should be sent one after another. To support multithreading, multiple connections should be used.

The TCP protocol works over port 4000 and discovery can be implemented using mDNS (multicast DNS, aka Bonjour). Further information in Lightify Gateway Discovery.

Multibyte values encoded using little-endian encoding and considered unsigned values.

String values are encoded using UTF-8 encoding and of fixed length. Unused bytes are filled with 0x00 and should be trimmed out to get the real string.

Headers

Table 1. Packet Header

Byte(s)	Description	Data type
0-1	Length of the packet, excl header length	uint16_t
2	Packet type (flag)	uint8_t: enum { 0x00: Light Device 0x01: Device response? 0x02: Broadcast / Zone Command 0x03: Zone Response? }
3	Command Id	uint8_t: See Lightify Commands
4-7	Unique, increasing request id	uint32_t

Table 2. Response Header Status Code

Byte(s)	Description	Data type
8	Status code?	uint8_t: enum { 0x00: No error? 0x01: Wrong (number of) parameter(s)? 0x14: ? 0x15: Command is not a broadcast? 0x16: Resync required (gateway expects the next packet to be PACKET_LIST_PAIRED_DEVICES) 0xA7: ? 0x0B: ? 0xC2: ? 0xD1: ? 0xFF: Unknown command? }

Error Response

The OSRAM Lightify gateway uses the Zigbee Light Link communication protocol, however it is also able to communicate with certain other device types of the Lightify series, such as switches, motion sensors and power plugs / sockets.

A device type is sent with status updates to identify the type of the device as well as the capabilities of a specific device.

Each paired device has a unique address (MAC). Multiple paired devices can be controlled at once by adding them to zones / groups, which are addressed using the zone’s id.

An address always contains 8 byte, no matter it’s adressing a device or zone and is directly followed by the command’s specific data.

Device address

Table 5. Device Addressing

Byte(s)	Description	Data type
0-7	Device address	uint64_t

Zone address

Table 6. Zone Addressing

Byte	Data type
1	uint8_t: lower significant byte
2	uint8_t: higher significant byte
3-7	uint8_t[6]: 0x00

To discover the OSRAM Lightify gateway’s IP address, a mDNS (multicast DNS) request is used. mDNS is also known as Bonjour and is originally developed by Apple.

To find the gateway’s address a SSDP lookup request is sent to the UDP broadcast address 224.0.0.251 (IPv4) or FF02::FB (IPv6). The service type to search for is _http._tcp which will find a Lightify device named as Lightify-XXXXXXXX, where XXXXXXXX is a part of the gateway’s serial number (S/N: OSRXXXXXXXX-YY) which is also used in the gateway’s own SSID (last 6 numbers of the code).

Since more items, especially of other vendors, might be found, the instance name should be tested for starting with Lightify- to make sure only the Lightify gateway is discovered.

According to the search type and the mDNS response, there is supposed to be a HTTP service on port 80, which does not seem to exist. However, the gateway seems to communicate over QUIC to the OSRAM servers, so maybe the port 80 is also available using QUIC.

After discovering the gateway’s IP address, the communication port to use the described protocol is TCP/4000.

Lightify devices and zones will be discovered using the gateway binary protocol, using tge commands PACKET_LIST_PAIRED_DEVICES and PACKET_LIST_ZONES.

Lightify commands are either used for broadcasts, like device or zone discovery, or contain information to control a specfic device or zone.

The following table is most probably incomplete and more commands are available. Response packets often follow a very similar scheme, therefore it should be easy to find new packets and analyze their content.

Known command ids are put into the following list:

As visible from the list, a lot of command ids seem either unused or, what is more presumable, unknown at the current point in time.

Most commands carry additional information starting after the header (for broadcast packets) or after the addressing header (non-broadcast packets).

The following sections define the packet’s structure after either of both headers, according to the command type.

PACKET_LIST_PAIRED_DEVICES

Table 8. Request data

Byte(s)	Description	Data type
16	Unknown	uint8_t: always? 0x01

Table 9. Response data

Byte(s)	Description	Data type
9-10	Number of devices	uint16_t
…​50 bytes each device	Device status information	See following table

Table 10. Device status information

Byte(s)	Description	Data type
0-1	Device id?	uint16_t
2-9	Device address	uint64_t: See Device address
10	Device type?	uint8_t: See Device Types
11-14	Firmware version	uint8_t[5]: Translation into firmware version string → {%02d, uint8_t[0]}{%02d, uint8_t[1]}{%02d, uint8_t[2]}+uint8_t[3]
15	Reachable	uint8_t: 0x00 online, 0xFF offline
16-17	Zone Id	uint16_t
18	Power switch status	uint8_t: bool
19	Luminance value / Battery value (Motion Detector)	uint8_t
20-21	Temparature value (in Kelvin)	uint16_t: 2,000 >= x ⇐ 6,500
22	Red value / Enabled value (Motion Detector)	uint8_t
23	Green value / Triggered value (Motion Detector)	uint8_t
24	Blue value	uint8_t
25	Alpha value	uint8_t: always? 0xFF
26-41	Device name	uint8_t[16]: UTF-8 encoded, zero terminated string
42-45	Time since last seen by gateway	uint32_t
46-49	Joining?	uint32_t

PACKET_LIST_ZONES

Table 11. Request data

Byte(s)	Description	Data type
-	No additional information to send	-

Table 12. Response data

Byte(s)	Description	Data type
9-10	Number of zones	uint16_t
…​18 bytes each zone	Zone information	See following table

Table 13. Zone information

Byte(s)	Description	Data type
0-1	Zone id	uint16_t
2-17	Zone name	uint8_t[16]: UTF-8 encoded, zero terminated string

PACKET_LIST_SCENES

Table 14. Request data

Byte(s)	Description	Data type
-	No additional information to send	-

Table 15. Response data

Byte(s)	Description	Data type
0-1	Number of Scenes	uint16_t
…​20 bytes each scene	Scene information	See following table

Table 16. Scene information

Byte(s)	Description	Data type
0	Scene id	uint8_t
1	Unknown, seems to always be 0x64 (@-sign)	uint8_t
2-17	Scene name	uint8_t[16]: UTF-8 encoded, zero terminated string
18-19	Unknown	uint16_t
20	Next Scene id (chaining scenes?)	uint8_t

PACKET_GET_ZONE_INFO

Table 17. Request data

Byte(s)	Description	Data type
-	No additional information to send	-

Table 18. Response data

Byte(s)	Description	Data type
9-10	Zone id	uint32_t
11-27	Zone name	uint8_t[16]: UTF-8 encoded, zero terminated string
28	Number of assigned devices	uint8_t
…​8 bytes each device	Device addresses	See Device address

PACKET_SET_LUMINANCE

Table 19. Request data

Byte(s)	Description	Data type
16	Luminance value	uint8_t
17-18	Transition time in millis	uint16_t

Table 20. Response data

Byte(s)	Description	Data type
9-10	Device or zone id	uint16_t
11-18	Device or zone address	uint64_t: See Device and Zone Addressing

PACKET_SET_SWITCH

Table 21. Request data

Byte(s)	Description	Data type
16	Power switch state	uint8_t: bool

Table 22. Response data

Byte(s)	Description	Data type
9-10	WRONG:Device or zone id??? Number of devices changed?	uint16_t
11-18	Device or zone address	uint64_t: See Device and Zone Addressing

PACKET_SET_TEMPERATURE

Table 23. Request data

Byte(s)	Description	Data type
16	White light temperature	uint16_t: 2,000 >= x ⇐ 6,500
17-18	Transition time in millis	uint16_t

Table 24. Response data

Byte(s)	Description	Data type
9-10	Device or zone id	uint16_t
11-18	Device or zone address	uint64_t: See Device and Zone Addressing

PACKET_SET_COLOR

Table 25. Request data

Byte(s)	Description	Data type
16	Red value	uint8_t
17	Green value	uint8_t
18	Blue value	uint8_t
19	Alpha value	uint8_t: always 0xFF?
20-21	Transition time in millis	uint16_t

Table 26. Response data

Byte(s)	Description	Data type
9-10	Device or zone id	uint16_t
11-18	Device or zone address	uint64_t: See Device and Zone Addressing

PACKET_ACTIVATE_SCENE

Table 27. Request data

Byte(s)	Description	Data type
16	Scene id	uint8_t: 0x00 to 0x0F for the different predefined scenes

Table 28. Response data

Byte(s)	Description	Data type
9-10	Device or zone id	uint16_t
11-18	Device or zone address	uint64_t: See Device and Zone Addressing

PACKET_GET_DEVICE_INFO

Table 29. Request data

Byte(s)	Description	Possible values
-	No additional information to send	-

Table 30. Response data

Byte(s)	Description	Data type
9-10	Device id?	uint16_t
11-18	Device address	uint64_t: See Device address
19	Reachable	uint8_t: 0x00 online, 0xFF offline
20	Unknown	uint8_t: ???
21	Power switch status	uint8_t: bool
22	Luminance value / Battery value (Motion Detector)	uint8_t
23-24	Temparature value (in Kelvin)	uint16_t: 2,000 >= x ⇐ 6,500
25	Red value / Enabled value (Motion Detector)	uint8_t
26	Green value / Triggered value (Motion Detector)	uint8_t
27	Blue value	uint8_t
28	Alpha value	uint8_t: always 0xFF?
29-31	Unknown	uint8_t[3]: ???

PACKET_GET_WIFI_CONFIGURATION

Table 31. Request data

Byte(s)	Description	Data type
16	Subcommand	uint8_t: enum { 0x00: Get wifi configuration 0x01: Set wifi configuration 0x03: Scan wifi configuration }

Table 32. Response data

Byte(s)	Description	Data type
9	Number of profiles	uint8_t
…​97 bytes each profile	Profile information	See following table

Table 33. Profile information

Byte(s)	Description	Data type
0-31	Profile Name	uint8_t[32]: UTF-8 encoded, zero terminated string
32-64	SSID	uint8_t[33]: UTF-8 encoded, zero terminated string
65-70	BSSID	uint8_t[6]: UTF-8 encoded, zero terminated string
71-74	Channel	uint32_t
75-76	Unknown	uint16_t: ???
77-80	IP Address	uint64_t: 4 bytes of IP address
81-84	Gateway	uint64_t: 4 bytes of IP address
85-88	Netmask	uint64_t: 4 bytes of IP address
89-92	DNS #1	uint64_t: 4 bytes of IP address
93-96	DNS #2	uint64_t: 4 bytes of IP address

PACKET_GET_GATEWAY_FIRMWARE_VERSION

Table 34. Request data

Byte(s)	Description	Data type
-	No additional information to send	-

Table 35. Response data

Byte(s)	Description	Data type
9-12	Firmware version	uint8_t[4]: Translation into firmware version string → {%02d, uint8_t[0]}{%02d, uint8_t[1]}{%02d, uint8_t[2]}+{%02d, uint8_t[3]}