Oakrey.Hue.ApiV1
3.0.0
dotnet add package Oakrey.Hue.ApiV1 --version 3.0.0
NuGet\Install-Package Oakrey.Hue.ApiV1 -Version 3.0.0
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="Oakrey.Hue.ApiV1" Version="3.0.0" />
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="Oakrey.Hue.ApiV1" Version="3.0.0" />
<PackageReference Include="Oakrey.Hue.ApiV1" />
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add Oakrey.Hue.ApiV1 --version 3.0.0
The NuGet Team does not provide support for this client. Please contact its maintainers for support.
#r "nuget: Oakrey.Hue.ApiV1, 3.0.0"
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package Oakrey.Hue.ApiV1@3.0.0
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=Oakrey.Hue.ApiV1&version=3.0.0
#tool nuget:?package=Oakrey.Hue.ApiV1&version=3.0.0
The NuGet Team does not provide support for this client. Please contact its maintainers for support.
Oakrey.Hue.ApiV1
DTO and model library for the Philips Hue REST API v1.
Provides System.Text.Json-annotated C# types that map directly to the JSON responses
returned by a Hue bridge. No HTTP client or bridge discovery is included � compose
with HttpClient or any REST library of your choice.
Main features
- Full model graph for the Hue v1 light resource:
Light,State,Capabilities,Control,Config,Startup,Streaming,Swupdate,ColorTemperature ConnectionInfofor storing bridge address, port, and API username- All properties annotated with
[JsonPropertyName]matching Hue bridge field names exactly - No external dependencies � uses only
System.Text.Jsonfrom the .NET runtime - Targets .NET 11
Requirements
- .NET 11 or higher
- No additional NuGet packages required
Installation
.NET CLI
dotnet add package Oakrey.Hue.ApiV1
Package Manager Console
Install-Package Oakrey.Hue.ApiV1
NuGet Package Manager (Visual Studio)
Search for Oakrey.Hue.ApiV1 under Tools > NuGet Package Manager > Manage NuGet Packages for Solution and click Install.
Model graph
classDiagram
class Light {
+string Name
+string Type
+string ModelId
+string ProductName
+string ManufacturerName
+string UniqueId
+string SwVersion
+string SwConfigId
+string ProductId
+State State
+Capabilities Capabilities
+Config Config
+Swupdate SwUpdate
}
class State {
+bool On
+int Brightness
+int BrightnessIncrement
+int Hue
+int Saturation
+int SaturationIncrement
+int Ct
+string ColorMode
+string Alert
+string Effect
+string Mode
+bool Reachable
+int TransitionTime
+List~double~ Xy
}
class Capabilities {
+bool Certified
+Control Control
+Streaming Streaming
}
class Control {
+int MaxLumen
+int MinDimLevel
+string ColorGamutType
+double[][] ColorGamut
+ColorTemperature Ct
}
class ColorTemperature {
+int Min
+int Max
}
class Streaming {
+bool Proxy
+bool Renderer
}
class Config {
+string Archetype
+string Direction
+string Function
+Startup Startup
}
class Startup {
+bool Configured
+string Mode
}
class Swupdate {
+string State
+string LastInstall
}
class ConnectionInfo {
+string IpAddress
+string Username
+string Port
}
Light --> State
Light --> Capabilities
Light --> Config
Light --> Swupdate
Capabilities --> Control
Capabilities --> Streaming
Control --> ColorTemperature
Config --> Startup
Usage
Read all lights from a Hue bridge
using System.Net.Http.Json;
using System.Text.Json;
using Oakrey.Hue.ApiV1;
ConnectionInfo connection = new ConnectionInfo
{
IpAddress = "192.168.1.100",
Port = "80",
Username = "your-hue-api-username"
};
using HttpClient client = new HttpClient();
string url = $"http://{connection.IpAddress}:{connection.Port}/api/{connection.Username}/lights";
Dictionary<string, Light>? lights = await client.GetFromJsonAsync<Dictionary<string, Light>>(url);
foreach (KeyValuePair<string, Light> entry in lights ?? [])
{
Console.WriteLine($"{entry.Key}: {entry.Value.Name} � on={entry.Value.State.On}, bri={entry.Value.State.Brightness}");
}
Deserialize a single light from JSON
string json = await File.ReadAllTextAsync("light.json");
Light? light = JsonSerializer.Deserialize<Light>(json);
Console.WriteLine($"Color gamut type: {light?.Capabilities.Control.ColorGamutType}");
Console.WriteLine($"CT range: {light?.Capabilities.Control.Ct.Min} - {light?.Capabilities.Control.Ct.Max} mired");
Model reference
| Class | Hue API resource field | Purpose |
|---|---|---|
Light |
/api/{user}/lights/{id} |
Top-level light resource |
State |
state |
Runtime state (on, bri, hue, sat, ct, xy, �) |
Capabilities |
capabilities |
Static capability declaration |
Control |
capabilities.control |
Lumen range, color gamut, CT range |
ColorTemperature |
capabilities.control.ct |
Mirek min/max bounds |
Streaming |
capabilities.streaming |
Proxy and renderer flags |
Config |
config |
Archetype, direction, function, startup mode |
Startup |
config.startup |
Power-on behaviour |
Swupdate |
swupdate |
Firmware update state and timestamp |
ConnectionInfo |
n/a | Helper for storing bridge address and credentials |
Development notes
- This library covers the light resource only. Groups, scenes, sensors, schedules, and rules from the Hue v1 API are not included.
ConnectionInfois a plain data holder with no HTTP logic. Constructing the request URL and handling authentication headers is left to the consumer.- The Hue API v1 returns lights as a
Dictionary<string, Light>where the key is the numeric light ID as a string. - The Hue bridge uses self-signed TLS on port 443. When targeting HTTPS, configure
HttpClientHandlerto accept the bridge certificate or use port 80.
License
MIT � Copyright (c) Oakrey 2016-present
Project information
- Author: Oakrey
- Repository: https://dev.azure.com/oakrey/OpenPackages/_git/Protocols
- Project URL: http://www.oakrey.cz/opkg_protocols_hue
| Product | Versions Compatible and additional computed target framework versions. |
|---|---|
| .NET | net11.0 is compatible. |
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.
-
net11.0
- Oakrey.Network.Rest (>= 3.0.0)
NuGet packages
This package is not used by any NuGet packages.
GitHub repositories
This package is not used by any popular GitHub repositories.