C# API (.Net) to control Xiaomi Yeelight Color Bulbs
If you find this package useful, please make a gift on Paypal : https://www.paypal.me/roddone
- The console project uses C# 7.1 "Async Main Method" Feature, make sure your visual studio version is up to date !
- Enable the "developer mode" on your devices, otherwhise they will neither be discovered nor usable by this API
To install the latest release from NuGet package manager:
Install-Package YeelightAPI
The YeelightAPI.Device allows you to create a device. Just instanciate a new Device with an ip adress or a hostname: Device device = new Device("hos.tna.meo.rIP"); and initiate connection : device.Connect();.
Then you can use the device object to control the device :
- Power on / off :
device.SetPower(true); - Toggle State :
device.Toggle(); - Change brightness level :
device.SetBrightness(100); - Change color :
device.SetRGBColor(80, 244, 255); - ...
Some methods use an optional parameter named "smooth", it refers to the duration in milliseconds of the effect you want to apply. For a progressive brightness change, use device.SetBrightness(100, 3000);.
If you need a method that is not implemented, you can use the folowing methods :
ExecuteCommandWithResponse(METHODS method, int id = 0, List<object> parameters = null)(with response)ExecuteCommand(METHODS method, int id = 0, List<object> parameters = null)(without response).
These methods are generic and use the METHODS enumeration and a list of parameters, which allows you to call any known method with any parameter.
All the parameters are defined in the doc "Yeelight WiFi Light Inter-Operation Specification", section 4.1 : COMMAND Message.
If you need to control multiple devices at a time, you can use the YeelightAPI.DeviceGroup class.
This class simply ihnerits from native .net List<Device> and implements the IDeviceController interface, allowing you to control multiple devices the exact same way you control a single device.
DeviceGroup group = new DeviceGroup();
group.Add(device1);
group.Add(device2);
group.Connect();
group.Toggle();
...You can create a Color Flow to "program" your device with different state changes. Changes can be : RGB color, color temperature and brightness.
Just create a new ColorFlow(), add some new ColorFlowExpression() to it, and starts the color flow with your ColorFlow object.
ColorFlow flow = new ColorFlow(0, ColorFlowEndAction.Restore);
flow.Add(new ColorFlowRGBExpression(255, 0, 0, 1, 500)); // color : red / brightness : 1% / duration : 500
flow.Add(new ColorFlowRGBExpression(0, 255, 0, 100, 500)); // color : green / brightness : 100% / duration : 500
flow.Add(new ColorFlowRGBExpression(0, 0, 255, 50, 500)); // color : blue / brightness : 50% / duration : 500
flow.Add(new ColorFlowSleepExpression(2000)); // sleeps for 2 seconds
flow.Add(new ColorFlowTemperatureExpression(2700, 100, 500)); // color temperature : 2700k / brightness : 100 / duration : 500
flow.Add(new ColorFlowTemperatureExpression(5000, 1, 500)); // color temperature : 5000k / brightness : 100 / duration : 500
device.StartColorFlow(flow); // start
/* Do Some amazing stuff ... */
device.StopColorFlow(); // stop the color flowThe ColorFlow constructor has 2 parameters : the first one defines the number of repetitions (or 0 for infinite), the second one defines what to do when the flow is stopped. you can choose to restore to the previous state, keep the last state or turn off the device.
Another way to create color flow is to use the device.Flow() method. This method returns a FluentFLow object you can use to create a flow in a "Fluent-syntax" way.
example :
FluentFlow flow = await backgroundDevice.BackgroundFlow()
.RgbColor(255, 0, 0, 50, 1000)
.Sleep(2000)
.RgbColor(0, 255, 0, 50) //without timing
.During(1000) // set the timing of the previous instruction
.Sleep(2000)
.RgbColor(0, 0, 255, 50, 1000)
.Sleep(2000)
.Temperature(2700, 100, 1000)
.Sleep(2000)
.Temperature(6500, 100, 1000)
.Play(ColorFlowEndAction.Keep);
await flow.StopAfter(5000);
//use the same object to create a new flow
await flow.Reset()
.RgbColor(0, 255, 0, 50, 1000)
.Temperature(3000, 100, 1000)
.Play(ColorFlowEndAction.Keep);If you want to find all connected devices, you can use the static asynchronous API of the YeelightAPI.DeviceLocator:
private async Task GetDevicesAsync()
{
// Await the asynchronous call to the static API
IEnumerable<Device> discoveredDevices = await DeviceLocator.DiscoverAsync();
}If you don't want to wait until all devices are discovered, you can make use of the IProgress<T>, to receive intermediate results.
Create instance of Progress<Device> and pass it to the appropriate DiscoverAsync overload. The callback, taking a Device as parameter and is registered with the constructor will always execute on the caller's thread. Therefore the caller has not to worry about Dispatcher invokes.
Each time DeviceLocator.DiscoverAsync(IProgress<Device>) finds a device, the IProgress<T>.Report method is invoked with the discovered devcice, which will trigger a call to the registered callback.
Example :
// Define the callback for the progress reporter
private void OnDeviceFound(Device device)
{
// Do Something with the discovered device
}
private async Task GetDevicesAsync()
{
// Initialize the instance of Progress<T> with a callback to handle a discovered device
var progressReporter = new Progress<Device>(OnDeviceFound);
// Await the asynchronous call to the static API
await DeviceLocator.DiscoverAsync(progressReporter);
// Alternatively: although each device is handled as soon as it is discovered by the callback registered with the progress reporter,
// you still can await the result collection
IEnumerable<Device> discoveredDevices = await DeviceLocator.DiscoverAsync(progressReporter);
}Some parameters are available to help avoiding some issues during discovery
MaxRetryCountallows you to define a retry count. Use with caution, because it can slow down the discovery! Defaults to1.UseAllAvailableMulticastAddressesallows you to use all the available multicast addresses instead of just the default one : 239.255.255.250. Use with caution, because it can slow down the discovery! Defaults tofalse.DefaultMulticastIPAddressallows you to change the default multicast address used for the discovery. Defaults to 239.255.255.250
Almost every method is awaitable returning a Task or Task<T> to make them execute asynchronously. Simply await them non-blocking using await:
Example :
// with single device
await device.Connect();
await device.Toggle();
// with groups
await group.Connect();
await group.Toggle();
...When you call a method that changes the state of the device, it sends a notification to inform that its state really change. You can receive these notification using the "OnNotificationReceived" event. Example :
device.OnNotificationReceived += (object sender, NotificationReceivedEventArgs arg) =>
{
Console.WriteLine("Notification received !! value : " + JsonConvert.SerializeObject(arg.Result));
};When an unknown error occurs, a "OnError" event is fired. Example :
device.OnError += (object sender, UnhandledExceptionEventArgs e) =>
{
Console.WriteLine($"An error occurred : {e.ExceptionObject}");
};- correct bugs if needed
Nothing else planned, if you have any ideas feel free to create an issue or a pull request.
Apache Licence
This code is an implementation of the "Yeelight WiFi Light Inter-Operation Specification" as defined on January 1st, 2018
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent