A node module to control Milight LED bulbs and OEM equivalents auch as Rocket LED, Limitless LED Applamp, Easybulb, s`luce, iLight, iBulb, and Kreuzer
npm install node-milight-promiseluce, iLight, iBulb, and Kreuzer. This library uses Promises to automatically synchronize the command
sequences sent. Thus, there is no need for nesting commands using callbacks. Of course, each API call returns a promise
which can be used to wait for the call promise to be resolved or rejected. The module has been tested with
RGB WW/CW (full color), RGBWW and White bulbs using Milight protocol versions 4.0 and 6.0. RGB bulbs which are no
longer sold since January 2014 should also work using the rgb command set.
Earlier versions of Milight used a very primitive one-way communication protocol where each command must be sent in a
single UDP packet. It is just fire & forget similar to simple RF protocols for garage door openers and such. Recently,
a new generation of Milight products has been introduced which use a new v6.0 protocol to provide advanced features.
Contributions
Contributions to the project are welcome. You can simply fork the project and create a pull request with
your contribution to start with. If you like this plugin, please consider ★ starring
the project on github.
$3
Support for using the 8-zone controller with CCT bulbs has been added (thanks to @pauleec & @fghekman for testing).
The 8-zone controller is known to work with current makes of the iBox2 bridge. Presumably, it will also work
with newer makes of iBox1. It did not work with mine, however, which is a couple of months old. Note, it is not
possible to pair a CCT bulb with the 4-zone and the 8-zone controller at the same time. As some users reported the
control session becomes invalid with their iBox2 bridge after a few minutes the session timeout has been reduced
to 30 seconds and it is now configurable also.
$3
So far, synchronization of Milight commands had been performed for each Milight() instance, individually. This caused
problems with some applications, which create multiple Milight() instances, for example, to manage different zones.
In some cases, commands did not get sent in the expected order or commands event got dropped by Milight Controller.
The current version should solve these issues by synchronizing commands across all instances. This also lays the
ground for a higher layer command API I am planning to add in the future.
If the new synchronization feature causes unexpected behavior it can be switched off as part of the configuration
options for a milight instance (fullSync: false).
$3
This version includes support for the new WiFi Bridge protocol v6.0 (also referred to as "v6 bridge" by the
project). Applications using the legacy should not be impacted, however I had to remove some supporting functions
to reduce code duplication (see Breaking Changes below).
Support for the v6 bridge includes the following features:
* support for the new full color RGW WW/CW bulbs
* support for legacy bulbs WW/CW white bulbs, RGBWW bulbs and RGB(W) strip controllers
* optional support for the legacy Milight color wheel
* flow control with automatic retry
* control for multiple bridges
* bridge discovery
* support for unicast and broadcast communication
* link/unlink bulbs to/from a given zone
The old command interface should work as is with the following exception:
* the command function rgbToHsv() and hsvToMilightColor() have ben removed to reduce the amount of code duplication.
If you use this function in your code you can now find the code in helper.js which is also exported using the
helper property.
There are also some subtle, notable changes of the default behaviour:
* the default for commandRepeat has been changed to 1 to provide consistent operation for all modes (WW/CW bulbs
with legacy bridges in particular). Note, beyond, a higher value does not make much sense for the v6 bridge
as the flow control strategy will automatically resend messages as required (if no receipt received)
* the default for delayBetweenCommands has been changed to 100 ms to provide consistent operation for all modes.
According to my findings a more aggressive timing is possible with the legacy bridges depending on condition of the
LAN (quality of the wireless link and router physics).
Notable features for v6 Bridge
$3
The new bridge allows for the implementation of flow control as each command message received by the bridge is replied
with a receipt message. So far, I have implemented a very simple strategy which is to wait for the receipt
$3
To my surprise, the color model of the v6.0 bridge protocol is different to the color wheel supported by earlier
bridge versions for RGBW lights. If you look at the old color wheel the new color wheel runs counterclockwise
and it is shifted by about 22.5 degrees to the left. It still looks odd to me as it does not match with RGB
wheel or the HSV color circle. Another curiosity is the color wheel of the bridge light is different to the
one of the RGBW light as it is shifted by another 22.5 degrees (starting with red instead of violet).
Maybe this is a bug of the bridge firmware or it is a calibration issue?
To cut a long story short I have integrated an optional transformation feature to the hue command for bridge and rgbw
to optionally support the legacy color wheel. This might be useful for applications which provide controls
for the legacy color wheel like the plugin for pimatic does.
$3
According to my findings a bulb can only be linked to single zone of a v6.0 bridge. The link/unlink commands can be used
for pairing within a short time window of about five seconds after powering up the bulb. If a bulb has not been paired
yet, calling the on() command a few times after powering up the bulb will also link the bulb to the given zone.
The following visual feedback is provided when pairing full color RGB bulbs:
* Flashing red light: The unlink command has been received. Flashing will stop after five seconds.
* Flashing green light: The link command has been received and pairing is in progress. Pairing mode will stop
after 5 seconds and light will turn to red.
* Constant red light: The bulb is either not linked to a bridge or it has been linked to a zone, but no further command
has been received yet.
$3
Using the effect mode (1 to 9) will not turn on the device. Thus, make sure the device is on before setting the
effect mode. To disable the effect mode you can set the white mode or choose a color. Note, switching off will not
disable the effect mode.
Notable features for Legacy Bridges
$3
Generally, the delay between commands is required to reduce the chances of UDP packet loss on the network. A longer
delay may lower the risk of data loss, however, data loss is likely to occur occasionally on a wireless network. Keep
in mind, that apart from your Wifi network there is another lossy communications channel between the Milight
Controller and the bulbs. Another strategy against loss is to repeat each command. By default, each command
will only be sent once. If you wish to resend commands you set number of repeats using the `commandRepeat`
property. Keep in mind, however, this should not be used with white bulbs, as the brightnessUp/brightnessDown, and
warmer/cooler commands will perform multiple steps otherwise.
$3
I noticed the rgbw.brightness() command never reached the maximum brightness level of the bulb and it turned out to be
yet another bug in the commands file. I also found an article suggesting the RGBW bulbs support 22 brightness levels
instead of 20, however, the two additional levels did not change the brightness for me (tested with 6W bulbs). Maybe
this is different with 9W bulbs. For this reason, I have added rgbw.brightness2() which maps brightness 0-100 to
22 levels.
Another interesting observation is the RGBW bulbs keep brightness levels for color mode and white mode, individually.
Thus, you may notice a change in brightness if you switch to white mode, for example. So, if your application only
maintains a single brightness control you need to make sure to send the commands in the right order!
$3
For RGBW bulbs the command rgbw.rgb255 is provided to map RGB values to Milight. However, the
color space of Milight is limited, as it is not possible to control color saturation and there are only 20
brightness levels. Thus, the results may be disappointing when compared to other LED lightning technologies.
Effectively, Milight is unable to display different shades of grey.
$3
Recently, I found out that Milight bridge version 3 and higher can also handle 2-byte command sequences instead of
3-byte command sequence. Basically, the last byte of the 3-byte command sequence, call it stop byte, can be omitted.
It is said the 2-byte command sequences provide better performance. This may be true for the Milight RF protocol,
but I don't think it has an significant impact on the IP communication between the application and the bridge. To use
the 2-byte command sequences you can simply use commands2 instead of commands. Mixing 2-byte and 3-byte sequences
is also supported.
General Features
$3
The bridge discovery function can be used to discover the IP and MAC addresses of Milight Wifi bridges found
on the local network. By default, the discovery function will only discover legacy bridges using the V3/V4/V5 protocol.
By setting the "type" property to the value "v6" the new bridges can be discovered. Using value "all" all bridges can be
discovered.
The following options can be provided to the discovery function.
| Property | Default | Type | Description |
|:----------|:------------------|:--------|:--------------------------------------------|
| address | "255.255.255.255" | String | The broadcast address. See "Important Notes" below. |
| timeout | 3000 | Integer | The timeout in milliseconds for discovery |
| type | "legacy" | String | One of "legacy", "v6", or "all" to determine the types of bridges to discover |
An array of results is returned. Each result contains the following properties:
* ip: The IP address string
* mac: The MAC address string
* type: The type of bridge. One of "legacy" or "v6"
* name: The hostname of the bridge. This will be empty for legacy bridges.
Usage
Documentation is still something left to be desired and I am sorry for that. To bridge the gap I have written some
example applications which you can find in the examples directory of the project/package.
$3
`javascript
var Milight = require('node-milight-promise').MilightController;
var commands = require('node-milight-promise').commands2;
// Important Notes:
// Instead of providing the global broadcast address which is the default, you should provide the IP address
// of the Milight Controller for unicast mode. Don't use the global broadcast address on Windows as this may give
// unexpected results. On Windows, global broadcast packets will only be routed via the first network adapter. If
// you want to use a broadcast address though, use a network-specific address, e.g. for 192.168.0.1/24 use
// 192.168.0.255.
var light = new Milight({
ip: "255.255.255.255",
delayBetweenCommands: 75,
commandRepeat: 2
}),
zone = 1;
light.sendCommands(commands.rgbw.on(zone), commands.rgbw.whiteMode(zone), commands.rgbw.brightness(100));
light.pause(1000);
light.sendCommands(commands.rgbw.off(zone));
light.pause(1000);
// Setting Hue
light.sendCommands(commands.rgbw.on(zone));
for (var x = 0; x < 256; x += 5) {
light.sendCommands(commands.rgbw.hue(x));
if (x === 0) {
commands.rgbw.brightness(100)
}
light.pause(100);
}
light.pause(1000);
light.sendCommands(commands.rgbw.off(zone));
light.pause(1000);
// Back to white mode
light.sendCommands(commands.rgbw.on(zone), commands.rgbw.whiteMode(zone));
light.pause(1000);
// Setting Brightness
light.sendCommands(commands.rgbw.on(zone));
for (var x = 100; x >= 0; x -= 5) {
light.sendCommands(commands.rgbw.brightness(x));
light.pause(100);
}
light.pause(1000);
light.sendCommands(commands.rgbw.off(zone));
light.pause(1000);
light.close().then(function () {
console.log("All command have been executed - closing Milight");
});
console.log("Invocation of asynchronous Milight commands done");
`
$3
`javascript
var Milight = require('../src/index').MilightController;
var commands = require('../src/index').commandsV6;
// Important Notes:
// * Instead of providing the global broadcast address which is the default, you should provide the IP address
// of the Milight Controller for unicast mode. Don't use the global broadcast address on Windows as this may give
// unexpected results. On Windows, global broadcast packets will only be routed via the first network adapter. If
// you want to use a broadcast address though, use a network-specific address, e.g. for 192.168.0.1/24 use
// 192.168.0.255.
// * Note, for the v6 command set each command must be provided with a zone parameter as shown in the example below!
var light = new Milight({
ip: "255.255.255.255",
type: 'v6'
}),
zone = 1;
light.sendCommands(commands.rgbw.on(zone), commands.rgbw.whiteMode(zone), commands.rgbw.brightness(zone, 100));
light.pause(1000);
light.sendCommands(commands.rgbw.off(zone));
light.pause(1000);
// Setting Hue
light.sendCommands(commands.rgbw.on(zone));
light.pause(1000);
for (var x = 0; x < 256; x += 5) {
light.sendCommands(commands.rgbw.hue(zone, x));
if (x === 0) {
light.sendCommands(commands.rgbw.brightness(zone, 100))
}
}
light.pause(1000);
light.sendCommands(commands.rgbw.off(zone));
light.pause(1000);
// Back to white mode
light.sendCommands(commands.rgbw.on(zone), commands.rgbw.whiteMode(zone));
light.pause(1000);
// Setting Brightness
light.sendCommands(commands.rgbw.on(zone));
for (var x = 100; x >= 0; x -= 5) {
light.sendCommands(commands.rgbw.brightness(zone, x));
}
light.pause(1000);
light.sendCommands(commands.rgbw.off(zone));
light.pause(1000);
light.close().then(function () {
console.log("All command have been executed - closing Milight");
});
console.log("Invocation of asynchronous Milight commands done");
`
$3
`javascript
var discoverBridges = require('../src/index').discoverBridges;
discoverBridges().then(function (results) {
console.log(results);
});
`
$3
`javascript
var discoverBridges = require('../src/index').discoverBridges;
discoverBridges({
type: 'all'
}).then(function (results) {
console.log(results);
});
`
Important Notes
* Instead of providing the global broadcast address which is the default, you should provide the IP address
of the Milight Controller for unicast mode. Don't use the global broadcast address on Windows as this may give
unexpected results. On Windows, global broadcast packets will only be routed via the first network adapter. If
you want to use a broadcast address though, use a network-specific address, e.g. for 192.168.0.1/24 use
192.168.0.255.
* For White bulbs the property commandRepeat should be set to 1`, as the brightnessUp/brightnessDown, and