esp8266_milight_hub

This is a replacement for a Milight/LimitlessLED remote/gateway hosted on an ESP8266. Leverages Henryk Plötz's awesome reverse-engineering work.

Milight bulbs are cheap smart bulbs that are controllable with an undocumented 2.4 GHz protocol. In order to control them, you either need a remote ($13), which allows you to control them directly, or a WiFi gateway ($30), which allows you to control them with a mobile app or a UDP protocol.

This guide on my blog details setting one of these up.

Why this is useful

1. Both the remote and the WiFi gateway are limited to four groups. This means if you want to control more than four groups of bulbs, you need another remote or another gateway. This project allows you to control 262,144 groups (4*2^16, the limit imposed by the protocol).
2. This project exposes a nice REST API to control your bulbs.
3. You can secure the ESP8266 with a username/password, which is more than you can say for the Milight gateway! (The 2.4 GHz protocol is still totally insecure, so this doesn't accomplish much :).
4. Official hubs connect to remote servers to enable WAN access, and this behavior is not disableable.

What you'll need

1. An ESP8266. I used a NodeMCU.
2. A NRF24L01+ module (~$3 on ebay).
3. Some way to connect the two (7 female/female dupont cables is probably easiest).

Installing

Connect the NRF24L01+

This module is an SPI device. This guide details how to connect it. I used GPIO 16 for CE and GPIO 15 for CSN. These can be configured later.

Setting up the ESP

You'll need to flash the firmware and a SPIFFS image. It's really easy to do this with PlatformIO:

export ESP_BOARD=nodemcuv2
platformio run -e $ESP_BOARD --target upload
platformio run -e $ESP_BOARD --target uploadfs

Of course make sure to substitute nodemcuv2 with the board that you're using.

You can find pre-compiled firmware images on the releases.

Configure WiFi

This project uses WiFiManager to avoid the need to hardcode AP credentials in the firmware.

When the ESP powers on, you should be able to see a network named "ESPXXXXX", with XXXXX being an identifier for your ESP. Connect to this AP and a window should pop up prompting you to enter WiFi credentials.

Use it!

The HTTP endpoints (shown below) will be fully functional at this point. You should also be able to navigate to http://<ip_of_esp>. The UI should look like this:

REST endpoints

1. GET /. Opens web UI. You'll need to upload it first.
2. GET /about. Return information about current firmware version.
3. POST /system. Post commands in the form {"comamnd": <command>}. Currently supports the commands: restart.
4. POST /firmware. OTA firmware update.
5. POST /web. Update web UI.
6. GET /settings. Gets current settings as JSON.
7. PUT /settings. Patches settings (e.g., doesn't overwrite keys that aren't present). Accepts a JSON blob in the body.
8. GET /radio_configs. Get a list of supported radio configs (aka device_types).
9. GET /gateway_traffic/:device_type. Starts an HTTP long poll. Returns any Milight traffic it hears. Useful if you need to know what your Milight gateway/remote ID is. Since protocols for RGBW/CCT are different, specify one of rgbw, cct, or rgb_cct as `:device_type. Accepts a JSON blob.
10. PUT /gateways/:device_id/:device_type/:group_id. Controls or sends commands to :group_id from :device_id.
11. POST /raw_commands/:device_type. Sends a raw RF packet with radio configs associated with :device_type. Example body:

    {"packet": "01 02 03 04 05 06 07 08 09", "num_repeats": 10}
    

Bulb commands

Route (5) supports these commands. Note that each bulb type has support for a different subset of these commands:

1. status. Toggles on/off. Can be "on", "off", "true", or "false".
2. hue. Sets color. Should be in the range [0, 359].
3. level. Controls brightness. Should be in the range [0, 100].
4. temperature. Controls white temperature. Should be in the range [0, 100].
5. saturation. Controls saturation.
6. mode. Sets "disco mode" setting to the specified value. Note that not all bulbs that have modes support this command. Some will only allow you to cycle through next/previous modes using commands.
7. command. Sends a command to the group. Can be one of:
   • set_white. Turns off RGB and enters WW/CW mode.
   • pair. Emulates the pairing process. Send this command right as you connect an unpaired bulb and it will pair with the device ID being used.
   • unpair. Emulates the unpairing process. Send as you connect a paired bulb to have it disassociate with the device ID being used.
   • next_mode. Cycles to the next "disco mode".
   • previous_mode. Cycles to the previous disco mode.
   • mode_speed_up.
   • mode_speed_down.
   • level_down. Turns down the brightness. Not all dimmable bulbs support this command.
   • level_up. Turns down the brightness. Not all dimmable bulbs support this command.
   • temperature_down. Turns down the white temperature. Not all bulbs with adjustable white temperature support this command.
   • temperature_up. Turns up the white temperature. Not all bulbs with adjustable white temperature support this command.

If you'd like to control bulbs in all groups paired with a particular device ID, set :group_id to 0.

Examples

Turn on group 2 for device ID 0xCD86, set hue to 100, and brightness to 50%:

$ curl --data-binary '{"status":"on","hue":100,"level":50}' -X PUT http://esp8266/gateways/0xCD86/rgbw/2
true%

Set color to white (disable RGB):

$ curl --data-binary '{"command":"set_white"}' -X PUT http://esp8266/gateways/0xCD86/rgbw/2
true%

UDP Gateways

You can add an arbitrary number of UDP gateways through the REST API or through the web UI. Each gateway server listens on a port and responds to the standard set of commands supported by the Milight protocol. This should allow you to use one of these with standard Milight integrations (SmartThings, Home Assistant, OpenHAB, etc.).

You can select between versions 5 and 6 of the UDP protocol (documented here). Version 6 has support for the newer RGB+CCT bulbs and also includes response packets, which can theoretically improve reliability. Version 5 has much smaller packets and is probably lower latency.