DuckTyping.Ikea.Dirigera 1.2.0

IKEA DIRIGERA Hub client library

An unofficial client library for the IKEA DIRIGERA smart home hub.
Connects to the API via the local network, handles OAuth2 PKCE pairing, allows for controlling lights, and streams real-time device readings over WebSocket.

Installation

Install via the terminal or the "Manage NuGet Packages" in your IDE of choice.

dotnet add package DuckTyping.Ikea.Dirigera

First-time pairing

The hub uses an OAuth2 PKCE flow that requires a one-time physical button press on the DIRIGERA hub. When you start the application for the first time (or after a token expires) you will see:

Press the Action button on the DIRIGERA hub (short press). Waiting 60s...

Press the small button on the bottom of the hub within 60 seconds. The token is then saved to disk and reused on all subsequent starts (no button press needed until the token expires).

The default token file location is ~/.dirigera-tokens.json. You can override this with StorePath in the settings (see below).

Setup with dependency injection

Register the client in your Program.cs or wherever you configure your IServiceCollection:

builder.Services.AddDirigeraClient(settings =>
{
    settings.Ip = "192.168.1.100"; // local IP address of your DIRIGERA hub
});

To find the hub IP, check your router's DHCP leases or look for a device named DIRIGERA on your network.

Optional settings

builder.Services.AddDirigeraClient(settings =>
{
    settings.Ip = "192.168.1.100";
    settings.StorePath = "/var/myapp/dirigera-tokens.json"; // custom token file location
});

Listening for sensor readings

Inject IDirigeraClient and call ListenAsync. It returns an IAsyncEnumerable<SensorReading> that you consume with await foreach. The connection and pairing happen automatically on the first call.

await foreach (var reading in client.ListenAsync(cancellationToken))
{
    switch (reading)
    {
        case EnvironmentReading env:
            Console.WriteLine($"{env.Name}  Temp={env.CurrentTemperature}°C  RH={env.CurrentRH}%  CO2={env.CurrentCO2}ppm");
            break;

        case DoorSensorReading door:
            Console.WriteLine($"{door.Name} is {(door.IsOpen ? "open" : "closed")}");
            break;

        case MotionSensorReading motion:
            Console.WriteLine($"{motion.Name}: {(motion.IsDetected ? "motion detected" : "clear")}");
            break;

        case WaterSensorReading water:
            Console.WriteLine($"{water.Name}: {(water.IsLeaking ? "LEAK DETECTED" : "dry")}");
            break;
    }
}

ListenAsync reconnects automatically with exponential backoff if the hub becomes unreachable, and stops cleanly when the CancellationToken is cancelled.

Reading types

All readings inherit from SensorReading which exposes:

Pattern match on the concrete type to access sensor-specific properties:

DoorSensorReading

MotionSensorReading

WaterSensorReading

EnvironmentReading

Controlling lights

Discover device IDs

Before controlling a light you need its device ID. Call GetDevicesAsync to list everything registered on the hub:

var devices = await client.GetDevicesAsync();
foreach (var device in devices)
    Console.WriteLine($"{device.Id}  {device.Name}  ({device.DeviceType})");

Copy the ID of the light you want to control (e.g. 2d3d4c0a-4624-45d1-bb3f-4f94b569ce48_11) and use it in the calls below.

On / Off / Toggle

await client.TurnOnAsync(lightId);
await client.TurnOffAsync(lightId);
await client.ToggleAsync(lightId);   // reads current state, then flips it

To turn a light on and set brightness in a single command, pass the brightness level as the second argument. Pass null to turn on without changing the current brightness:

await client.TurnOnAsync(lightId, brightness: 75);   // turn on at 75%
await client.TurnOnAsync(lightId, brightness: null);  // turn on, keep current brightness

Dimming

Brightness is a value from 1 (minimum) to 100 (maximum).

await client.DimAsync(lightId, brightness: 50);

Color temperature (white spectrum)

Color temperature is in Kelvin. Typical range for IKEA bulbs is 2200 K (warm white) to 4000 K (cool white).

await client.SetColorTemperatureAsync(lightId, kelvin: 2700);

Color (RGB)

Pass standard RGB values (0–255 per channel). The library converts them to the hue/saturation format the hub expects.

await client.SetColorAsync(lightId, r: 255, g: 120, b: 0);  // warm orange

To switch back to white after using color mode, call SetColorTemperatureAsync.

Reading light state

All light control methods return a LightStatus reflecting the target state of the command — not a live re-poll of the hub. The physical device may still be transitioning (e.g. dimming or changing color) when the method returns. To read the actual current state without issuing a command, use GetLightStatusAsync:

var status = await client.GetLightStatusAsync(lightId);
Console.WriteLine($"On={status.IsOn}  Brightness={status.Brightness}%  Mode={status.ColorMode}");

LightStatus properties

Exceptions

Controlling outlets

On / Off / Toggle

await client.TurnOutletOnAsync(outletId);
await client.TurnOutletOffAsync(outletId);
await client.ToggleOutletAsync(outletId);   // reads current state, then flips it

Reading outlet state

All outlet methods return an OutletStatus. You can also read it without making any change:

var status = await client.GetOutletStatusAsync(outletId);
Console.WriteLine($"On={status.IsOn}  Reachable={status.IsReachable}");

OutletStatus properties

Controlling blinds

Open / Close / Set position

await client.OpenBlindAsync(blindId);             // sets position to 0 (fully open)
await client.CloseBlindAsync(blindId);            // sets position to 100 (fully closed)
await client.SetBlindPositionAsync(blindId, 50);  // 0 = fully open, 100 = fully closed

Reading blind state

All blind methods return a BlindStatus. You can also read it without making any change:

var status = await client.GetBlindStatusAsync(blindId);
Console.WriteLine($"Current={status.CurrentLevel}  Target={status.TargetLevel}");

BlindStatus properties

Examples

Below are some examples of how to use the library.
Note; these are just example snippets and not full applications ready for production

Example: .NET Console application with lights control

A console application that lists all devices and exposes light control as CLI commands.

using DuckTyping.Ikea.Dirigera;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;

var host = Host.CreateDefaultBuilder(args)
    .ConfigureServices(services =>
    {
        services.AddDirigeraClient(settings =>
        {
            settings.Ip = "192.168.1.100";
        });
    })
    .Build();

var client = host.Services.GetRequiredService<IDirigeraClient>();

switch (args)
{
    case ["devices"]:
        var devices = await client.GetDevicesAsync();
        foreach (var d in devices)
            Console.WriteLine($"{d.Id}  {d.Name,-30}  {d.DeviceType}");
        break;

    case ["lights", "on", var id]:
        var on = await client.TurnOnAsync(id);
        Console.WriteLine($"{on.Name} is now on at {on.Brightness}%");
        break;

    case ["lights", "on", var id, var level] when int.TryParse(level, out var onBrightness):
        var onDimmed = await client.TurnOnAsync(id, onBrightness);
        Console.WriteLine($"{onDimmed.Name} is now on at {onDimmed.Brightness}%");
        break;

    case ["lights", "off", var id]:
        var off = await client.TurnOffAsync(id);
        Console.WriteLine($"{off.Name} is now off");
        break;

    case ["lights", "toggle", var id]:
        var toggled = await client.ToggleAsync(id);
        Console.WriteLine($"{toggled.Name} is now {(toggled.IsOn ? "on" : "off")}");
        break;

    case ["lights", "dim", var id, var level] when int.TryParse(level, out var brightness):
        var dimmed = await client.DimAsync(id, brightness);
        Console.WriteLine($"{dimmed.Name} brightness set to {dimmed.Brightness}%");
        break;

    case ["lights", "temp", var id, var kelvin] when int.TryParse(kelvin, out var k):
        var temp = await client.SetColorTemperatureAsync(id, k);
        Console.WriteLine($"{temp.Name} color temperature set to {temp.ColorTemperature}K");
        break;

    case ["lights", "color", var id, var r, var g, var b]
        when int.TryParse(r, out var rv) && int.TryParse(g, out var gv) && int.TryParse(b, out var bv):
        var colored = await client.SetColorAsync(id, rv, gv, bv);
        Console.WriteLine($"{colored.Name} color set  Hue={colored.Hue}  Sat={colored.Saturation}%");
        break;

    case ["lights", "status", var id]:
        var status = await client.GetLightStatusAsync(id);
        Console.WriteLine($"{status.Name}  On={status.IsOn}  Brightness={status.Brightness}%  Mode={status.ColorMode}");
        break;

    default:
        Console.WriteLine("""
            Usage:
              devices
              lights status  <id>
              lights on      <id>
              lights on      <id> <1-100>
              lights off     <id>
              lights toggle  <id>
              lights dim     <id> <1-100>
              lights temp    <id> <kelvin>
              lights color   <id> <r> <g> <b>
            """);
        break;
}

Run it from the terminal:

dotnet run -- devices
dotnet run -- lights on    2d3d4c0a-4624-45d1-bb3f-4f94b569ce48_11
dotnet run -- lights on    2d3d4c0a-4624-45d1-bb3f-4f94b569ce48_11 75
dotnet run -- lights dim   2d3d4c0a-4624-45d1-bb3f-4f94b569ce48_11 40
dotnet run -- lights temp  2d3d4c0a-4624-45d1-bb3f-4f94b569ce48_11 2700
dotnet run -- lights color 2d3d4c0a-4624-45d1-bb3f-4f94b569ce48_11 255 120 0

Example: .NET Worker Service

Worker service that listens to events from the DIRIGERA Hub, the worker logs information based on the type of sensor reading that is received.

Program.cs

using DuckTyping.Ikea.Dirigera;

var builder = Host.CreateApplicationBuilder(args);

builder.Services.AddDirigeraClient(settings =>
{
    settings.Ip = builder.Configuration.GetRequiredSection("Dirigera:Ip").Value!;
});

builder.Services.AddHostedService<DirigeraWorker>();

var host = builder.Build();
host.Run();

appsettings.json

{
  "Dirigera": {
    "Ip": "192.168.1.100"
  }
}

DirigeraWorker.cs

public sealed class DirigeraWorker(IDirigeraClient client, ILogger<DirigeraWorker> logger) : BackgroundService
{
    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        logger.LogInformation("Connecting to DIRIGERA hub...");

        await foreach (var reading in client.ListenAsync(stoppingToken))
        {
            switch (reading)
            {
                case EnvironmentReading env:
                    logger.LogInformation(
                        "[Environment] {Name}  Temp={Temp}  RH={RH}%  CO2={CO2}ppm",
                        env.Name, env.CurrentTemperature, env.CurrentRH, env.CurrentCO2);
                    break;

                case DoorSensorReading door:
                    logger.LogInformation(
                        "[Door] {Name}  {State}  Bat={Battery}%",
                        door.Name, door.IsOpen ? "Open" : "Closed", door.Battery);
                    break;

                case MotionSensorReading motion:
                    logger.LogInformation(
                        "[Motion] {Name}  {State}  Bat={Battery}%",
                        motion.Name, motion.IsDetected ? "Motion" : "Clear", motion.Battery);
                    break;
            }
        }

        logger.LogInformation("Event loop stopped.");
    }
}

Example: Console application

A console application that listens to events from the DIRIGERA Hub and prints info to the console

using DuckTyping.Ikea.Dirigera;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;

var host = Host.CreateDefaultBuilder(args)
    .ConfigureServices(services =>
    {
        services.AddDirigeraClient(settings =>
        {
            settings.Ip = "192.168.1.100";
        });
    })
    .Build();

var client = host.Services.GetRequiredService<IDirigeraClient>();

using var cts = new CancellationTokenSource();
Console.CancelKeyPress += (_, e) =>
{
    e.Cancel = true;
    cts.Cancel();
};

await foreach (var reading in client.ListenAsync(cts.Token))
{
    Console.WriteLine($"{reading.Time:HH:mm:ss}  {reading.Name ?? reading.DeviceId}  {reading.GetType().Name}");
}

Notes

• The hub uses a self-signed TLS certificate on port 8443. The library accepts this certificate automatically. DO NOT expose this port to the internet.