Philips Hue

ZigBee

The Philips Hue wireless lighting system is based on ZigBee. ZigBee is based on the IEEE 802.15.4 standard for personal wireless networks. While using the same 2.4GHz radio frequency range as WiFi (IEEE 802.11), it's a completely different network protocol, like Bluetooth or DECT. This means that you need a ZigBee hardware adapter to participate in a ZigBee network. Devices lacking such hardware, like a computer or smartphone, need the help of a ZigBee gateway device, like a Hue bridge, to communicate with ZigBee lights, sensors or switches.

ZigBee defines three types of networked devices: a ZigBee coordinator, a ZigBee router, and a ZigBee end device. A coordinator controls a ZigBee network. A gateway is a coordinator that provides Internet (protocol) access to the devices on a ZigBee network. A Hue bridge is a ZigBee gateway/coordinator. A router extends the range of a ZigBee network, by relaying messages. Typically, a mains-powered ZigBee device, like a (friends of) Hue light, is a ZigBee router. The coordinator and routers form a mesh network. A battery-powered ZigBee device, like a Hue motion sensor or a Hue dimmer switch, is a ZigBee end devices. So is a Green Power device, like a Hue tap.

ZigBee network traffic is encrypted using a secret key created by the coordinator and shared by all devices on the network. When a device joins the network, it receives the encryption key from the coordinator. Once a device has joined a network, it only communicates with devices in the same network, until it is reset. When a Hue bridge searches for new devices, it only finds devices already on the bridge's network and devices that haven't yet joined a network.
It is possible to "steal" a device from its network, forcing it to join another network, using TouchLink. This only works if the device is at close proximity (10cm) to the coordinator.
When a Hue dimmer switch is paired directly with a light, the switch creates a ZigBee network by itself. A light can only join one ZigBee network at a time, so it is either controlled by the Hue dimmer switch or by the Hue bridge.

ZigBee Light Link (ZLL)

On top of IEEE 802.15.4, the ZigBee Alliance standardises protocols for interoperability between ZigBee devices from different vendors. ZigBee defines multiple protocols, much like Bluetooth defines multiple profiles. Typically these protocols are implemented in the firmware of the ZigBee hardware adapter.
For ZigBee devices to work together, they need to use the same protocol. Philips Hue uses the ZigBee Light Link (ZLL) protocol for (friends of) Hue lights and plug-in units, for Hue motion sensors, and for Hue dimmer switches; and the ZigBee Green Power (ZGP) protocol for Hue taps.

Most ZigBee lights and plug-in units from other vendors use ZLL as well, and those devices can be controlled from a Hue bridge. Known exceptions are the Ikea trådfri and the North American OSRAM Lightify devices, which use the ZigBee Home Automation (ZHA) protocol instead of ZLL. These lights can join the ZigBee network created by a Hue bridge, but they cannot be controlled from the Hue bridge, as it doesn't support ZHA.
The use of ZLL for sensors and switches seems less common, other vendors might use ZHA for these. A Hue bridge doesn't support ZHA, so it doesn't work with these sensors or switches. Gateways from other vendors, like the European OSRAM Lightify gateway or the innr bridge, typically support ZLL for lights, so a (friends of) Hue light or plug-in unit could be controlled from those gateways.

Hue Bridge

A Hue bridge is a small computer running Linux, with a ZigBee network adapter and an Ethernet adapter. It acts as a ZigBee gateway, between the ZigBee Light Link (ZLL) protocol and the Hue API. The v2 (square) bridge also contains HomeKit hardware and acts as a gateway between ZLL and the HomeKit Accessory Protocol (HAP).

The Hue API provides access to a Hue bridge and to the ZigBee lights, sensors, and switches connected to the bridge. This is a RESTful API, using HTTP GET, POST, PUT, and DELETE requests to read, create, update, or delete resources on the Hue bridge. The request body (for POST and PUT) and response body contain the resource attributes in JSON format.
Philips provide SDKs on top of the Hue API for Objective C (for macOS applications and iOS apps) and Java (for Android apps), but any command or library supporting HTTP and JSON can be used in conjunction with the Hue API. homebridge-hue uses the request package. To issue requests manually, you could even use curl or the web-based API debug tool provided by the Hue bridge, see Getting Started on the Hue developer portal.

After a Hue bridge finds a device, it creates the corresponding resource for it. When the Hue bridge resource is deleted, the Hue bridge sends a reset message to the corresponding device. The device forgets the network key so it can be found by another network controller. In case the communication between the bridge and device fails (because the device is disconnected from power or out of reach), the device remains part of the network and continues to react to broadcast messages, until it is reset or joins another network through TouchLink.
When a device is reset manually, the corresponding Hue bridge resource continues to exist, but the bridge won't be able to contact the device. When the device re-joins the network (e.g. by Touchlink), the bridge continues to use the existing configuration.

Hue Bridge Resources

A Hue bridge supports the following resource types:

Resource Type	URI	Comments
Daylight sensor	/sensors/1	Built-in.
ZLL sensor ZGP sensor	/sensors/#	Created by the Hue bridge, when a new sensor or switch is found.
CLIP sensor	/sensors/#	Created through the Hue API.
light	/lights/#	Created by the Hue bridge, when a new light is found.
all lights group	/groups/0	Built-in.
Luminaire group LightSourcegroup	/groups/#	Created by the Hue bridge, when a new multi-source luminaire is found.
LightGroup group Room group	/groups/#	Created through the Hue API.
schedule	/schedules/#	Created through the Hue API.
rule	/rules/#	Created through the Hue API.
resourcelink	/resourcelinks/id	Created through the Hue API.
config	/config	Built-in.
capabilities	/capabilities	Built-in.

Meethue portal