C# helper library to talk to the Philips Hue bridge
C#
Failed to load latest commit information.
src Support for Remote API V2 #72 Jul 29, 2016
.gitignore Moved ColorConversion to separate assembly Jul 22, 2016
LICENSE.txt Added MIT license Jan 19, 2013
README.md Support for Remote API V2 #72 Jul 29, 2016

README.md

Q42.HueApi

Open source library for communication with the Philips Hue bridge. 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 Portable Library is compatible with: .Net45, Windows 8, Windows Phone 8, Windows 10 Universal Apps and the Xamarin Platform! Download directly from NuGet Q42.HueApi on NuGet.

How to use?

Some basic usage examples

Bridge

Before you can communicate with the Philips Hue Bridge, you need to find the bridge and register your application:

IBridgeLocator locator = new HttpBridgeLocator();

//For Windows 8 and .NET45 projects you can use the SSDPBridgeLocator which actually scans your network. 
//See the included BridgeDiscoveryTests and the specific .NET and .WinRT projects
IEnumerable<string> bridgeIPs = await locator.LocateBridgesAsync(TimeSpan.FromSeconds(5));

Register your application

ILocalHueClient client = new LocalHueClient("ip");
var appKey = await client.RegisterAsync("mypersonalappname", "mydevicename");
//Save the app key for later use

If you already registered an appname, you can initialize the HueClient with the app's key:

client.Initialize("mypersonalappkey");

Control the lights

Main usage of this library is to be able to control your lights. We use a LightCommand for that. A LightCommand can be send to one or more / multiple lights. A LightCommand can hold a color, effect, on/off etc.

var command = new LightCommand();
command.On = true;

There are some helpers to set a color on a command:

//Turn the light on and set a Hex color for the command (see the section about Color Converters)
command.TurnOn().SetColor(new RGBColor("FF00AA"))

LightCommands also support Effects and Alerts

//Blink once
command.Alert = Alerts.Once;

//Or start a colorloop
command.Effect = Effects.ColorLoop;

Once you have composed your command, send it to one or more lights

client.SendCommandAsync(command, new List<string> { "1" });

Or send it to all lights

client.SendCommandAsync(command);

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. Q42.HueApi has 3 different color converters out of the box. They are in a seperate package and it's easy to create your own color converter.

  • Original: The original converter based on a large XY array.
  • OriginalWithModel: Does not use the large XY array, but should produce the same result and uses the lamp model.
  • HSB: Converts based on Hue, Brightness and Saturation.

    How to use a color converter? Add one of the following usings:
    using Q42.HueApi.ColorConverters.Original
    using Q42.HueApi.ColorConverters.OriginalWithModel
    using Q42.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!

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.
You need an Access Token and a Bridge Id. Please refer to the Philips Hue API documentation on how to obtain them. NOTE Remote API support is untested. Testing and PRs are very much appreciated.

IRemoteHueClient remoteHueClient =  new RemoteHueClient("access token");
remoteHueClient.Initialize("bridge id", "whitelist_id");

After the setup, you can send normal commands to the remote API:

remoteHueClient.SendCommandAsync(command, new List<string> { "1" });

How To install?

Download the source from GitHub or get the compiled assembly from NuGet Q42.HueApi on NuGet.

Credits

This library is made possible by contributions from:

Open Source Project Credits

  • Newtonsoft.Json is used for object serialization

License

Q42.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.

Build status

Related Projects

Apps that use Q42.HueAPI

Are you using Q42.HueAPI? Get your app listed here! Edit this page and send a pull request.

Windows Phone

Windows

Windows Desktop

MONO