HueApi
Open source library for communication with the Philips Hue bridge.
Over 400k downloads on NuGet (Q42.Hue + HueApi)
This library covers all the Philips hue API calls! You can set the state of your lights, update the Bridge configuration, create groups, schedules etc.
This library targets .net 8, .net 9 and .net 10!
Download directly from NuGet:
New for v3
The new Fluent API allows for easy access to all resources through their respective methods. For example:
//Light resource
localHueApi.Light.GetAllAsync()
localHueApi.Light.UpdateAsync(id, ...)
//Room Resource
localHueApi.Room.GetAllAsync()
Features:
- Support for Hue Entertainment API
- Support for the Hue Remote API
- Support for the Hue Bridge Pro APIs
- Multiple Color Converters
Make sure to install the HueApi packages:
Do not use the Q42 prefixed packages anymore. They target old APIs which will be removed in the future.
How to use?
Some basic usage examples
Locate bridges in your network:
IBridgeLocator locator = new HttpBridgeLocator(); //Or: LocalNetworkScanBridgeLocator, MdnsBridgeLocator, MUdpBasedBridgeLocator
var bridges = await locator.LocateBridgesAsync(TimeSpan.FromSeconds(5));
Register your application
//Make sure the user has pressed the button on the bridge before calling RegisterAsync
//It will throw an LinkButtonNotPressedException if the user did not press the button
var regResult = await LocalHueClient.RegisterAsync("BRIDGE_IP", "mypersonalappname", "mydevicename");
//Save the app key for later use and use it to initialize LocalHueApi
var appKey = regResult.Username;
Use the LocalHueApi:
var localHueApi = new LocalHueApi("BRIDGE_IP", "KEY");
Change the lights:
var lights = await localHueApi.Light.GetAllAsync();
var id = all.Data.Last().Id; //Pick a light
var req = new UpdateLight()
.TurnOn()
.SetColor(new ColorConverters.RGBColor("FF0000"));
var result = await localHueApi.Light.UpdateAsync(id, req);
API Reference
Use the API reference provided by Hue to discover the capabilities of the API.
https://developers.meethue.com/develop/hue-api-v2/api-reference/
EventStream
Listen to the new EventStream to get notified by the Hue Bridge when new events occur.
localHueApi.OnEventStreamMessage += EventStreamMessage;
localHueApi.StartEventStream();
void EventStreamMessage(List<EventStreamResponse> events)
{
Console.WriteLine($"{events.Count} new events");
foreach(var hueEvent in events)
{
foreach(var data in hueEvent.Data)
{
Console.WriteLine($"Data: {data.Metadata?.Name} / {data.IdV1}");
}
}
}
//localHueApi.StopEventStream();
Sample usage can be found in the included Console Sample App: HueApi.ConsoleSample
Clip V2 API
Philips Hue has developed a new Clip V2 API. This library has support for the new Clip V2 APIs. Philips Hue is still developing these APIs and new functionality is added regularly. Please create an issue or PR if you need something that is not supported yet.
Support for Hue Entertainment.
Check out the HueApi.Entertainment documentation
Read about the Philips Entertainment API
Remote API
There is also a Philips Hue Remote API. It allows you to send commands to a bridge over the internet. You can request access here: http://www.developers.meethue.com/content/remote-api
Q42.HueApi is compatible with the remote API. There’s a sample app and documentation can be found here:
https://github.com/michielpost/Q42.HueApi/blob/master/RemoteApi.md
For remote usage with the new CLIP v2 API, use the new RemoteHueApi("KEY", "token")
Color Conversion
The Philips Hue lights work with Brightness, Saturation, Hue and X, Y properties. More info can be found in the Philips Hue Developer documentation: http://www.developers.meethue.com/documentation/core-concepts#color_gets_more_complicated
It’s not trivial to convert the light colors to a color system developers like to work with, like RGB or HEX. HueApi has 2 different color converters out of the box. They are in a seperate package and it’s easy to create your own color converter.
The HueApi.ColorConverters NuGet package contains:
- Original: The original converter based on a large XY array.
- HSB: Converts based on Hue, Brightness and Saturation.
How to use a color converter?
Add one of the following usings:
using HueApi.ColorConverters.Original
using HueApi.ColorConverters.HSB
This will add extension methods to Light, State and LightCommand. So you can set the color using new RGBColor() and convert the State back to RGBColor
Pull Requests with improvements to the color conversion are always welcome!
How To install?
Download the source from GitHub or get the compiled assembly from NuGet
Credits
This library is made possible by contributions from:
License
HueApi is licensed under MIT. Refer to license.txt for more information.
Contributions
Contributions are welcome. Fork this repository and send a pull request if you have something useful to add.
Apps that use Q42.HueAPI
Are you using Q42.HueAPI? Get your app listed here! Edit this page and send a pull request.
Open Source
Windows
Other
No longer available or maintained
评论