d8ahazard/q42.hueapi

C# helper library to talk to the Philips Hue bridge

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 library targets .netstandard2.0, .net45, .net 5 and .net 6! Download directly from NuGet Q42.HueApi on NuGet.

• Support for Hue Entertainment API
• Support for the Hue Remote API
• Multiple Color Converters
• NEW: Support for Clip V2 API with the new HueApi package 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(); //Or: LocalNetworkScanBridgeLocator, MdnsBridgeLocator, MUdpBasedBridgeLocator
	var bridges  = await locator.LocateBridgesAsync(TimeSpan.FromSeconds(5));

	//Advanced Bridge Discovery options:
	bridges = await HueBridgeDiscovery.CompleteDiscoveryAsync(TimeSpan.FromSeconds(5), TimeSpan.FromSeconds(30));
	bridges	= await HueBridgeDiscovery.FastDiscoveryWithNetworkScanFallbackAsync(TimeSpan.FromSeconds(5), TimeSpan.FromSeconds(30));
	bridges = await HueBridgeDiscovery.CompleteDiscoveryAsync(TimeSpan.FromSeconds(5));

Register your application

	ILocalHueClient client = new LocalHueClient("ip");
	//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 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 = Alert.Once;
	
	//Or start a colorloop
	command.Effect = Effect.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);

Clip V2 API

Recently Hue releases a new Clip V2 API. This library has support for the new Clip V2 APIs. Not everything is implemented yet. Please create an issue or PR if you need something that is not supported yet.

Make sure to install the new packages:

• HueApi from NuGet
• HueApi.ColorConverters from NuGet
• HueApi.Entertainment from NuGet

Clip V2 Example

Use the LocalHueClLocalHueApiient:

var localHueApi = new LocalHueApi("BRIDGE_IP", "KEY");

For remote usage, use the new RemoteHueApi("KEY", "token")

Registration of your App and retreiving a key can be done using the original Q42.HueApi. There's no support yet in the new Clip V2 API.

Change the lights:

var lights = await localHueApi.GetLights();
var id = all.Data.Last().Id; //Pick a light

var req = new UpdateLight()
	.TurnOn()
	.SetColor(new ColorConverters.RGBColor("FF0000"));
var result = await localHueApi.UpdateLight(id, req);

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

Support for Hue Entertainment.

Check out the Q42.HueApi.Streaming 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/Q42/Q42.HueApi/blob/master/RemoteApi.md

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.

The Q42.HueApi.ColorConverters NuGet package contains:

• Original: The original converter based on a large XY array.
• Gamut: Uses the provided Gamut (type) provided by each light.
• 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.Gamut
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!

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:

• Michiel Post (@michielpostnl) - core contributor
• Q42 (@q42)
• @ermau
• @koenvanderlinden
• @Indigo744
• and others

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.

Related Projects

• Lists of hue libraries
• Official Philips hue API documentation

Apps that use Q42.HueAPI

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

Windows

• My Hue Light Switch
• DarkLights
• Huetro for Hue
• hueDynamic
• CastleOS
• PresenceLight

Windows Phone

• My Hue Light Switch
• iControlHue
• OnHue
• Huetro for Hue
• hueDynamic

WinForms

• Andriks.HueApiDemo

Xbox One

• hueDynamic

Android

• hueReact

Command Line Tools - Windows, Linux (x64 & ARM) and Windows 10 IOT (ARM)

• Command Line Tools -- Control your Hue from your command line
• C# Script Command Line Tool -- Use C# as your scripting language

Other

• Hue Light DJ