DOCSEARCHbyAlgolia
Submit Docs

HueApi

repository·master·Indexed 19 days ago

https://github.com/michielpost/q42.hueapi

An open-source .NET library for communicating with Philips Hue bridges. It supports local and remote APIs, including Clip V2 and Entertainment APIs. The library provides tools for bridge discovery via IBridgeLocator, application registration, and light control using a Fluent API. Additional extensions include HueApi.ColorConverters for RGB/HSB logic and HueApi.Entertainment for streaming and spatial effects using layers and LightSourceEffect.

Tokens
4.4K
Snippets
19
Records
19
Agent score
64%

What's inside HueApi

  1. Use Color Converters (RGB/HSB)

    master

    Hue lights use internal color properties (Brightness, Saturation, Hue, X, Y). To work with standard color systems like RGB or HEX, install HueApi.ColorConverters and add the appropriate using directive. This adds extension methods to Light, State, and LightCommand.

    Available converters:

    • HueApi.ColorConverters.Original: Based on a large XY array.
    • HueApi.ColorConverters.HSB: Based on Hue, Brightness, and Saturation.
    using HueApi.ColorConverters.RGBColor;
// or
using HueApi.ColorConverters.HSB;

// Example usage in a command:
var req = new UpdateLight().SetColor(new RGBColor("FF0000"));

  2. How layers work in Hue Entertainment

    master

    When auto-updating a StreamingGroup, you manipulate lights using Layers.

    There are two types of layers:

    • Base Layers: You should always have one base layer. This serves as the foundation for all light states.
    • Effect Layers: Used to run specific effects. If a light's brightness on an effect layer is 0, the effect layer is ignored and the light reverts to its state on the base layer.

    To create a new layer, use GetNewLayer(isBaseLayer: true) for a base layer or false for an effect layer.

    //Create new base layer
var entLayer = stream.GetNewLayer(isBaseLayer: true);

  3. Locate Hue Bridges on your network

    master

    Use an IBridgeLocator implementation to find available Hue bridges in your local network. Available implementations include:

    • HttpBridgeLocator
    • LocalNetworkScanBridgeLocator
    • MdnsBridgeLocator
    • MUdpBasedBridgeLocator
    IBridgeLocator locator = new HttpBridgeLocator();
var bridges = await locator.LocateBridgesAsync(TimeSpan.FromSeconds(5));

  4. Connect to an entertainment group and start streaming

    master

    To stream to a Hue entertainment group, follow these steps:

    1. Initialize a StreamingHueClient using the bridge IP, the generated client key, and the entertainment key.
    2. Retrieve available entertainment groups via client.LocalHueClient.EntertainmentConfiguration.GetAllAsync().
    3. Create a StreamingGroup using the locations from the selected group.
    4. Connect to the group using client.Connect(groupId).
    5. Start auto-updating the group using client.AutoUpdate(entGroup, intervalMs).

    Note: For a working demo, you can run the Q42.HueApi.Streaming.Sample project or the HueApi.Entertainment.ConsoleSample for the V2 API demo.

    //Initialize streaming client
StreamingHueClient client = new StreamingHueClient(ip, key, entertainmentKey);

//Get the (first) entertainment group
var all = await client.LocalHueClient.EntertainmentConfiguration.GetAllAsync();
var group = all.Data.FirstOrDefault();

//Create a streaming group
var entGroup = new StreamingGroup(group.Locations);

//Connect to the streaming group
await client.Connect(group.Id);

//Start auto updating this entertainment group
client.AutoUpdate(entGroup, 50);

  5. Register your application with a Hue Bridge

    master

    To register a new application, use LocalHueClient.RegisterAsync.

    Note: The user must physically press the button on the Hue Bridge before this call is made, otherwise it will throw a LinkButtonNotPressedException.

    // Register the app (requires physical button press on bridge)
var regResult = await LocalHueClient.RegisterAsync("BRIDGE_IP", "mypersonalappname", "mydevicename");

// Save the Username (app key) for future initialization
var appKey = regResult.Username;

  7. Install HueApi and its extensions

    master

    To use HueApi, install the core package and any required extensions via NuGet.

    Important: Do not use packages prefixed with Q42, as they target legacy APIs. Use the modern HueApi packages instead.

    Required packages:

    • HueApi: Core library for communication with the Philips Hue bridge.
    • HueApi.ColorConverters: Provides RGB and HSB color conversion logic.
    • HueApi.Entertainment: Provides support for the Hue Entertainment API.
    # Install core package
dotnet add package HueApi

# Install optional extensions
dotnet add package HueApi.ColorConverters
dotnet add package HueApi.Entertainment

  8. Locate a Philips Hue Bridge

    master

    To communicate with a Philips Hue Bridge, you must first locate it on your network using an IBridgeLocator implementation. You can use different discovery methods depending on your network environment:

    • HttpBridgeLocator: Standard HTTP discovery.
    • LocalNetworkScanBridgeLocator: Scans the local network.
    • MdnsBridgeLocator: Uses mDNS.
    • MUdpBasedBridgeLocator: Uses UDP-based discovery.

    You can also use HueBridgeDiscovery for advanced discovery patterns like complete discovery or fast discovery with network scan fallback.

    IBridgeLocator locator = new HttpBridgeLocator();
var bridges = await locator.LocateBridgesAsync(TimeSpan.FromSeconds(5));

// Advanced discovery options:
// Complete discovery
bridges = await HueBridgeDiscovery.CompleteDiscoveryAsync(TimeSpan.FromSeconds(5), TimeSpan.FromSeconds(30));

// Fast discovery with network scan fallback
bridges = await HueBridgeDiscovery.FastDiscoveryWithNetworkScanFallbackAsync(TimeSpan.FromSeconds(5), TimeSpan.FromSeconds(30));

  9. Register your app with the Hue Bridge for Entertainment API access

    master

    To use the Entertainment API, you must request access during the registration process by setting generateClientKey = true in the LocalHueClient.RegisterAsync method. This generates the necessary key required to initialize a StreamingHueClient.

    LocalHueClient.RegisterAsync("ipAddress", "applicationName", "deviceName", true);

  10. Access Hue via the Remote API

    master

    For controlling a bridge over the internet using the Philips Hue Remote API, use the RemoteHueApi class. For the new CLIP v2 API, initialize it with your key and token.

    // For remote usage with the new CLIP v2 API
var remoteApi = new RemoteHueApi("KEY", "token");

  11. Register your application with the Hue Bridge

    master

    Before sending commands, you must register your application to obtain an application key.

    Important: The user must physically press the button on the Philips Hue Bridge before you call RegisterAsync. If the button is not pressed, the method will throw a LinkButtonNotPressedException.

    1. Initialize a LocalHueClient with the Bridge IP.
    2. Call RegisterAsync with your application name and device name.
    3. Save the returned appKey for future sessions.
    ILocalHueClient client = new LocalHueClient("ip");
// Ensure the physical button on the bridge is pressed before this call
var appKey = await client.RegisterAsync("mypersonalappname", "mydevicename");
// Save appKey for later

  12. Initialize LocalHueApi and control lights

    master

    Once you have the Bridge IP and the application key (Username), initialize LocalHueApi. You can use the new Fluent API to access resources like Light, Room, etc., and perform operations like updating light states.

    // Initialize the API
var localHueApi = new LocalHueApi("BRIDGE_IP", "KEY");

// Get all lights
var lights = await localHueApi.Light.GetAllAsync();
var id = lights.Data.Last().Id; // Example: pick the last light

// Create an update request using the Fluent API
var req = new UpdateLight()
    .TurnOn()
    .SetColor(new HueApi.ColorConverters.RGBColor("FF0000"));
    
// Apply the update
var result = await localHueApi.Light.UpdateAsync(id, req);