I don't use this version anymore but a version build in ESP Home: https://github.com/hencou/esphome_components With the ESP Home approach, it is possible to create the logic between (wall)switches and lights in ESP Home, without scripting.

This is a fork of Sidoh's Milight Hub: https://github.com/sidoh/esp8266_milight_hub/ Instead of using a central hub this project aims to be used behind every wall switch.

• RGB_CCT Lights can be controlled with MQTT, HTTP, MiLight remote or a wall push switch.
• Wall switches will remains working even without WIFI.
• Status updates will be send to MQTT.
• WallSwitch commands are also forwarded to the MQTT command topic to extend the range.
• ESP8266MQTTMesh is used for the Wifi connection. When the Wifi is out of range, it creates a mesh network automaticaly with an gateway to the MQTT server.

UDP functionality is removed to save space, besides using it to know which deviceId to control. The first configured (UDP) deviceId from the settings is used for the wall switches. MQTT commands are only send to light bulbs when the corresponding deviceId is configured as (UDP) deviceId.

Button press functions:

• Short press: light off
• Long press: fade light in to max brightness
• 10 seconds long press: restart ESP
• 1 short and long press: change temperature from cold to warm and vice versa
• 2 short presses: night mode
• 3 short presses: white mode
• 4 short presses: pair bulb
• 5 short presses: unpair bulb

Below the original text of Sidoh's Milight Hub with slight modifications:

esp8266_milight_hub/switch

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 project is a replacement for the wifi gateway.

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.
5. This project is capable of passively listening for Milight packets sent from other devices (like remotes). It can publish data from intercepted packets to MQTT. This could, for example, allow the use of Milight remotes while keeping your home automation platform's state in sync. See the MQTT section for more detail.

Supported remotes

The following remotes can be emulated:

Support has been added for the following bulb types:

Model #	Name	Compatible Bulbs
FUT096	RGB/W	FUT014 FUT016 FUT103
FUT005 FUT006 FUT007	CCT	FUT011 FUT017 FUT019
FUT098	RGB	Most RGB LED Strip Controlers
FUT020	RGB	Some other RGB LED strip controllers
FUT092	RGB/CCT	FUT012 FUT013 FUT014 FUT015 FUT103 FUT104 FUT105 Many RGB/CCT LED Strip Controllers
FUT091	CCT v2	Most newer dual white bulbs and controllers
FUT089	8-zone RGB/CCT	Most newer rgb + dual white bulbs and controllers

Other remotes or bulbs, but have not been tested.

What you'll need

1. An ESP8266. I used a Wemos D1 Mini.
2. A NRF24L01+ module (~$3 on ebay). Alternatively, you can use a LT8900.
3. Some way to connect the two (7 female/female dupont cables is probably easiest).
4. 10 uF capacitor between power supply and NRF24L01+
5. HLK-PM03 3V3 Power supply, or HLK-PM01 5V to support RCWL-0516 radar sensor (optional)

Installing

Connecting GPIO

I used a Wemos D1 mini because it's very small to fit behind a wall switch.

• GPIO D1-D3 as input from wall switch to control groups 1-3. LOW is active state. Use a push switch or touch sensor like TTP223, solder jumper A on TTP223 to achieve active LOW output.
• Use GPIO D4 as input for a DS18B20 temperature sensor
• Use GPIO A0 as input for a LDR or RCWL-0516 radar sensor

Connect the NRF24L01+ / LT8900

This project is compatible with both NRF24L01 and LT8900 radios. LT8900 is the same model used in the official MiLight devices. NRF24s are a very common 2.4 GHz radio device, but require software emulation of the LT8900's packet structure. As such, the LT8900 is more performant.

Both modules are SPI devices and should be connected to the standard SPI pins on the ESP8266.

NRF24L01+

This guide details how to connect an NRF24 to an ESP8266. By default GPIO 16 for CE and GPIO 15 for CSN are used, but these can be configured late in the Web GUI under Settings -> Setup.

On a Wemos D1 mini:

Wemos GPIO	NRF24	Color
GND	GND	Black
3V3	VCC	Red
D0 GPIO16	CE	Orange
D5 GPIO14	SCK	Green
D6 GPIO12	MISO	Violet
D7 GPIO13	MOSI	Blue
D8 GPIO15	CSN	Yellow

• CE pin is on D0 instead of D2
• Do not mount the NRF24 and ESP12 antennas against each other. This will cause bad performance and crashes

Image source: MySensors.org

LT8900

Connect SPI pins (CE, SCK, MOSI, MISO) to appropriate SPI pins on the ESP8266. With default settings, connect RST to GPIO 0, PKT to GPIO 16, CE to GPIO 4, and CSN to GPIO 15. Make sure to properly configure these if using non-default pinouts.

Setting up the ESP

The goal here is to flash your ESP with the firmware. It's really easy to do this with PlatformIO:

export ESP_BOARD=d1_mini
platformio run -e $ESP_BOARD --target upload

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

Configure WiFi

Configure the Wifi settings in the header of main.cpp and in /src/credentials.h, see /src/credentials.h.example

Both mDNS and SSDP are supported.

• OS X - you should be able to navigate to http://milight-hub.local.
• Windows - you should see a device called "ESP8266 MiLight Gateway" show up in your network explorer.
• Linux users can install avahi (sudo apt-get install avahi-daemon on Ubuntu), and should then be able to navigate to http://milight-hub.local.

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>, or http://milight-hub.local if your client supports mDNS. The UI should look like this:

If it does not work as expected see Troubleshooting.

Pair Bulbs

If you need to pair some bulbs, how to do this is described in the wiki.

Device Aliases

You can configure aliases or labels for a given (Device Type, Device ID, Group ID) tuple. For example, you might want to call the RGB+CCT remote with the ID 0x1111 and the Group ID 1 to be called living_room. Aliases are useful in a couple of different ways:

• In the UI: the aliases dropdown shows all previously set aliases. When one is selected, the corresponding Device ID, Device Type, and Group ID are selected. This allows you to not need to memorize the ID parameters for each lighting device if you're controlling them through the UI.
• In the REST API: standard CRUD verbs (GET, PUT, and DELETE) allow you to interact with aliases via the /gateways/:device_alias route.
• MQTT: you can configure topics to listen for commands and publish updates/state using aliases rather than IDs.

REST API

The REST API is specified using the OpenAPI v3 specification.

openapi.yaml contains the raw spec.

You can view generated documentation for the master branch here.

Docs for other branches can be found here

MQTT

To configure your ESP to integrate with MQTT, fill out the following settings:

1. mqtt_server- IP or hostname should work. Specify a port with standard syntax (e.g., "mymqttbroker.com:1884").
2. mqtt_topic_pattern - you can control arbitrary configurations of device ID, device type, and group ID with this. A good default choice is something like milight/:device_id/:device_type/:group_id. More detail is provided below.
3. (optionally) mqtt_username
4. (optionally) mqtt_password

More detail on mqtt_topic_pattern

mqtt_topic_pattern leverages single-level wildcards (documented here). For example, specifying milight/:device_id/:device_type/:group_id will cause the ESP to subscribe to the topic milight/+/+/+. It will then interpret the second, third, and fourth tokens in topics it receives messages on as :device_id, :device_type, and :group_id, respectively. The following tokens are available:

1. :device_id - Device ID. Can be hexadecimal (e.g. 0x1234) or decimal (e.g. 4660).
2. :device_type - Remote type. rgbw, fut089, etc.
3. :group_id - Group. 0-4 for most remotes. The "All" group is group 0.
4. :device_alias - Alias for the given device. Note that if an alias is not configured, a default token __unnamed_group will be substituted instead.

Messages should be JSON objects using exactly the same schema that the REST gateway uses for the /gateways/:device_id/:device_type/:group_id endpoint.

Example:

If mqtt_topic_pattern is set to milight/:device_id/:device_type/:group_id, you could send the following message to it (the below example uses a ruby MQTT client):

irb(main):001:0> require 'mqtt'
irb(main):002:0> client = MQTT::Client.new('10.133.8.11',1883)
irb(main):003:0> client.connect
irb(main):004:0> client.publish('milight/0x118D/rgb_cct/1', '{"status":"ON","color":{"r":255,"g":200,"b":255},"brightness":100}')

This will instruct the ESP to send messages to RGB+CCT bulbs with device ID 0x118D in group 1 to turn on, set color to RGB(255,200,255), and brightness to 100.

Updates

ESPMH is capable of providing two types of updates:

1. Delta: as packets are received, they are translated into the corresponding command (e.g., "set brightness to 50"). The translated command is sent as an update.
2. State: When an update is received, the corresponding command is applied to known group state, and the whole state for the group is transmitted.

Delta updates

To publish data from intercepted packets to an MQTT topic, configure MQTT server settings, and set the mqtt_update_topic_pattern to something of your choice. As with mqtt_topic_pattern, the tokens :device_id, :device_type, and :group_id will be substituted with the values from the relevant packet. :device_id will always be substituted with the hexadecimal value of the ID. You can also use :hex_device_id, or :dec_device_id if you prefer decimal.

The published message is a JSON blob containing the state that was changed.

As an example, if mqtt_update_topic_pattern is set to milight/updates/:hex_device_id/:device_type/:group_id, and the group 1 on button of a Milight remote is pressed, the following update will be dispatched:

irb(main):005:0> client.subscribe('milight/updates/+/+/+')
=> 27
irb(main):006:0> puts client.get.inspect
["lights/updates/0x1C8E/rgb_cct/1", "{\"status\":\"on\"}"]

Full state updates

For this mode, mqtt_state_topic_pattern should be set to something like milight/states/:hex_device_id/:device_type/:group_id. As an example:

irb(main):005:0> client.subscribe('milight/states/+/+/+')
=> 27
irb(main):006:0> puts client.get.inspect
["lights/states/0x1C8E/rgb_cct/1", "{\"state\":\"ON\",\"brightness\":255,\"color_temp\":370,\"bulb_mode\":\"white\"}"]
irb(main):007:0> puts client.get.inspect
["lights/states/0x1C8E/rgb_cct/1", "{\"state\":\"ON\",\"brightness\":100,\"color_temp\":370,\"bulb_mode\":\"white\"}"]

Make sure that mqtt_topic_pattern, mqtt_state_topic_pattern, and matt_update_topic_pattern are all different! If they are they same you can put your ESP in a loop where its own updates trigger an infinite command loop.

Customize fields

You can select which fields should be included in state updates by configuring the group_state_fields parameter. Available fields should be mostly self explanatory, but are all documented in the REST API spec under GroupStateField.

Client Status

To receive updates when the MQTT client connects or disconnects from the broker, confugre the mqtt_client_status_topic parameter. A message of the following form will be published:

{"status":"disconnected_unclean","firmware":"milight-hub","version":"1.9.0-rc3","ip_address":"192.168.1.111","reset_reason":"External System"}

If you wish to have the simple messages connected and disconnected instead of the above environmental data, configure simple_mqtt_client_status to true (or set Client Status Message Mode to "Simple" in the Web UI).

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.

Transitions

Transitions between two given states are supported. Depending on how transition commands are being issued, the duration and smoothness of the transition are both configurable. There are a few ways to use transitions:

RESTful /transitions routes

These routes are fully documented in the REST API documentation.

transition field when issuing commands

When you issue a command to a bulb either via REST or MQTT, you can include a transition field. The value of this field specifies the duration of the transition, in seconds (non-integer values are supported).

For example, the command:

{"brightness":255,"transition":60}

will transition from whatever the current brightness is to brightness=255 over 60 seconds.

Notes on transitions

• espMH's transitions should work seamlessly with HomeAssistant's transition functionality.
• You can issue commands specifying transitions between many fields at once. For example:

  {"brightness":255,"kelvin":0,"transition":10.5}

  will transition from current values for brightness and kelvin to the specified values -- 255 and 0 respectively -- over 10.5 seconds.
• Color transitions are supported. Under the hood, this is treated as a transition between current values for r, g, and b to the r, g, b values for the specified color. Because milight uses hue-sat colors, this might not behave exactly as you'd expect for all colors.
• You can transition to a given status or state. For example,

  {"status":"ON","transition":10}

  will turn the bulb on, immediately set the brightness to 0, and then transition to brightness=255 over 10 seconds. If you specify a brightness value, the transition will stop there instead of 255.

LED Status

Some ESP boards have a built-in LED, on pin #2. This LED will flash to indicate the current status of the hub:

• Wifi not configured: Fast flash (on/off once per second). See Configure Wifi to configure the hub.
• Wifi connected and ready: Occasional blips of light (a flicker of light every 1.5 seconds).
• Packets sending/receiving: Rapid blips of light for brief periods (three rapid flashes).
• Wifi failed to configure: Solid light.

In the setup UI, you can turn on "enable_solid_led" to change the LED behavior to:

• Wifi connected and ready: Solid LED light
• Wifi failed to configure: Light off

Note that you must restart the hub to affect the change in "enable_solid_led".

You can configure the LED pin from the web console. Note that pin means the GPIO number, not the D number ... for example, D1 is actually GPIO5 and therefore its pin 5. If you specify the pin as a negative number, it will invert the LED signal (the built-in LED on pin 2 (D4) is inverted, so the default is -2).

If you want to wire up your own LED you can connect it to D1/GPIO5. Put a wire from D1 to one side of a 220 ohm resistor. On the other side, connect it to the positive side (the longer wire) of a 3.3V LED. Then connect the negative side of the LED (the shorter wire) to ground. If you use a different voltage LED, or a high current LED, you will need to add a driver circuit.

Another option is to use an external LED parallel to the (inverted) internal one, this way it will mirror the internal LED without configuring a new LED pin in the UI. To do this connect the (short) GND pin of your LED to D4. The longer one to a 220 ohm resistor and finally the other side of the resistor to a 3V3 pin.

Development

This project is developed and built using PlatformIO.

Running tests

On-board unit tests are available using PlatformIO. Run unit tests with this command:

pio test -e d1_mini

substituting d1_mini for the environment of your choice.

Running integration tests

A remote integration test suite built using rspec is available under ./test/remote.

Ready-Made Hub

h4nc (h4nc.zigbee(a)gmail.com) created a PCB and 3D-printable case for espMH. He's offering ready-made versions. Please get in touch with him at the aforementioned email address for further information.

Find more information from the espmh_pcb repository.

Acknowledgements

• @WoodsterDK added support for LT8900 radios.
• @cmidgley contributed many substantial features to the 1.7 release.

Donating

If the project brings you happiness or utility, it's more than enough for me to hear those words.

If you're feeling especially generous, and are open to a charitable donation, that'd make me very happy. Here are some whose mission I support (in no particular order):

• Water.org
• Brain & Behavior Research Foundation
• Electronic Frontier Foundation
• Girls Who Code
• San Francisco Animal Care & Control