Yeelight 3P Plugin - Beta
This is a basic plugin to control the Xiaomi Yeelight brand of WiFi light bulbs, they currently have a number of bulbs, strips and lamps available with the majority supporting control of WiFi. The plugin has few options and few dependencies, the bulbs support discovery by an SSDP like protocol and as such the plugin can discover the bulbs available on the network using multicast messages.
The plugin will;
- Send a multicast message out on 18.104.22.168:1982 (UPNP multicast address but a custom port)
- When the respective bulbs reply then it will determine the type and properties and then create the device in HomeSeer
- HomeSeer will then be able to control the device via devices and events, colour flows can be set via events
- Every 60 seconds the plugin will poll the network for new devices, if it finds a new device then it will add the device to HS and if not then it should update the devices (in case the device has been controlled from outside HS).
The plugin currently is not in the HomeSeer updater however is simple to install, it has a single EXE (HSPI_YEELIGHT3P.exe) and configuration file so can be dropped into the HS folder and it should then appear in your HS plugin interfaces page. Enabling it from here should start the plugin and start the discovery and inclusion process.
A set of devices will be created depending on the device type the plugin discovers, if no devices are created please check the HS log to determine whether or not the plugin has been able to locate devices on your network. If it does not create any devices and you are confident it should then please see the end of this document. When created the devices should appear as following;
You will see that the devices are relatively self explanatory, in summary;
- Root Device - Will display ‘Communications Issue’ if there is an issue sending data to the unit, I would suggest looking into the log to see if any errors are explained there, if not see the end of this document.
- Control Device - This is fairly easy to understand however there are some slightly subtle matters, ‘On Last Level’ will send the simple power on command to the LED. Depending on the state it was left in depends on what dim value you have set and colours etc. If you have controlled it from outside HS then the devices in HS may be out of date, you will need to wait for the periodic refresh for it to refresh the values. ‘On’ will turn the device on to 100% brightness, ‘Off’ will turn it off. The transition and fade duration devices are relevant here, if fade duration is set (as in this example) to two seconds then it will smoothly turn the device off. If the transition device is set to sudden then it will do it instantly.
- CT Colour - This is the colour temperature in degrees Kelvin for the bulb to set itself to, even the colour bulbs will accept a colour temperature so you can set this independently of the RGB device value.
- Fade Duration / Transition State - As detailed above, the fade duration will accept a decimal value if you wish to set sub second values (0.5 = 500 milliseconds)
- RGB Colour - This is the colour picker device to set the bulb to an RGB colour, if the device is off it will make an attempt to turn the device on first. This is fairly self explanatory.
The plugin supports some ability to set colour flows to your Yeelight device, the flows can be complex to understand and the HS3 events page (without extensive programming) is not best suited to programming these flows. The flows are a string of values that represent frames of the light states, in the Zip file I have included the Yeelight API documentation. If you look on page 14 of this document you will see the data structure. The HS events page has the ability to send a colour flow in the same format of the documentation, the event action looks like this;
The flow message box will accept data in the same format that the device is expecting in the parameters as detailed in the documentation. This is the example flow (on page 14) copied into the box - please remove any spaces/line breaks first if copying from a document. When you send this it should then send the flow to the bulb. The event action to stop the flow does exactly what it says. More options (such as loading from a text file) may be added in the future.
- It appears that on occasion the Yeelight bulb can get in a bad state where it cannot accept new instruction, in this case it appears that waiting a couple of seconds before sending a command helps. It could be a rogue character sitting in the buffer of the device (which may be flushed internally) however if you see this please be mindful and report any known issues (with a copy of the log) to the below thread.
- The UDP discovery method can be blocked by some firewalls, you need to ensure that you have allowed port 1982 through and allowed the plugin access to this. This could explain if you do not see any bulbs discovered by the plugin, I have also had issue with some application possibly redirecting the multicast packets, installing MS easy fix 20140 (https://support.microsoft.com/en-us/help/299357/how-to-reset-tcp-ip-by-using-the-netshell-utility) fixed this for me. In this zip file there is a file called ‘Yeelight_Control.exe’, this is a third party discovery tool that may be of use to run to see if this application discovers the bulbs on your network.
- There appears to be nothing in the API that determines whether a device that is colour temperature only (such as the desk lamp), as such that may be created in the plugin as a RGB device and give a colour picker that does not work.
- The ceiling light background functions at present are not implemented, I do not have a ceiling light to test with however if someone needs these functions then they can be added with some assistance.
- I only have a single RGB bulb and whilst I have made every effort to support all of the options this plugin is in beta state so multiple devices may need further work or the assistance of users.
- The plugin at present is completely untested on Linux
- IMPORTANT - it appears that by default the option to control these devices outside of the application (the LAN API) is turned off on each bulb. You need to enable the LAN control option in the Yeelight app before you will be able to discover and control your devices in the plugin.