OverkizClient 2.0.0

OverkizClient

For shipped changes, see the changelog. Test, CI and build history is recorded separately in development and validation history.

A .NET client library for the Overkiz cloud and local REST API, enabling control and monitoring of smart-home gateways and devices from Somfy, Atlantic Cozytouch, Hitachi Hi Kumo, and other Overkiz-compatible ecosystems.

Supported Platforms

Supported Gateways / Cloud Servers

Local API (LAN) is supported for Somfy TaHoma, Rexel Energeasy Connect, and compatible gateways when a local or developer-mode bearer token is available.

Compatibility note: this .NET library is intended to work across the broader family of Overkiz-compatible gateways, with gateway coverage informed by the behavior of the upstream python-overkiz-api project. The current .NET implementation has been validated by the author with a Somfy TaHoma gateway; other Overkiz-compatible gateways and cloud ecosystems are expected to work but have not yet been directly tested here. Recent compatibility updates include the modern Rexel backend flow, newer Hitachi Hi Kumo hlrrwifi:// device URL handling, and aligned gateway type/sub-type metadata for newer Energeasy Connect variants.

Installation

dotnet add package OverkizClient

Version 2.0.0

This major version moves JSON contracts onto model attributes, returns typed events and execution actions, makes local pairing completion-only, and represents variable device values using CLR primitives and collections. The unused log4net and Polly dependencies are removed; Newtonsoft.Json is not used. JSON packages and .NET Framework compatibility packages use stable 10.0.12 releases instead of preview packages.

Public API changes require recompiling consumers. See the 2.0 migration guide for replacements for FetchEventsRaw, pairing-result access, action dictionaries and JsonElement value casts. The test console has been updated.

The offline suite has 272 cases per target framework, including regression coverage for JWT errors, invalid enum tokens, default-option model serialization and flexible values. Six live tests remain separately opt-in.

Recent Upstream Parity Updates

• Synced recent upstream python-overkiz-api parity updates relevant to this .NET implementation.
• Added aligned gateway Type metadata and corrected gateway SubType numeric mappings.
• Improved Rexel compatibility by treating gateway subType: 0 as no specific subtype instead of an unknown subtype.
• Added cloud endpoints for local pairing and gateway developer-mode management.
• Marked Rexel as local-API capable in the supported server metadata.
• Expanded protocol and UI enum coverage to recognize newer upstream device integrations and widget types.
• Preserved support for the newer Rexel bearer-token-plus-gateway-selection flow and Hitachi Hi Kumo hlrrwifi:// device URL handling.

Quick Start

Cloud Connection (Somfy)

using OverKizApi;
using OverKizApi.Enums;

await using var client = new OverkizClient(
	username: "your@email.com",
	password: "your-password",
	server: OverkizConst.SupportedServers[Server.SomfyEurope]);

await client.Login();

var devices = await client.GetDevices();
foreach (var device in devices)
	Console.WriteLine($"{device.Label} — {device.DeviceUrl}");

Cloud Connection (Rexel)

Rexel now uses an externally managed bearer token plus explicit gateway selection. Supply the token to the constructor, log in, then discover and select the target gateway before making normal setup/device calls.

using OverKizApi;
using OverKizApi.Enums;

await using var client = new OverkizClient(
	username: string.Empty,
	password: string.Empty,
	server: OverkizConst.SupportedServers[Server.Rexel],
	token: "your-rexel-bearer-token");

await client.Login();

var gateways = await client.DiscoverRexelGateways();
client.SelectRexelGateway(gateways[0].GatewayId);

var devices = await client.GetDevices();

Local Connection (LAN)

using var httpClient = new HttpClient(OverkizConst.CreateLocalHttpClientHandler());

await using var client = new OverkizClient(
	username: string.Empty,
	password: string.Empty,
	server: OverkizConst.LocalServer("192.168.1.xxx"),
	token: "your-local-bearer-token",
	httpClient: httpClient);

await client.Login();

var devices = await client.GetDevices();

Sending a Command

string execId = await client.ExecuteDeviceAction(
	deviceUrl: "io://xxxx-xxxx-xxxx/12345678",
	commands: new[]
	{
		new Command { Name = "open" }
	});

Live Event Streaming

await client.RegisterEventListener();

while (true)
{
	var events = await client.FetchEvents();
	foreach (var ev in events)
		Console.WriteLine($"{ev.Name}: {ev.DeviceURL}");

	await Task.Delay(2000);
}

await client.UnregisterEventListener();

Response models

The client deserializes setup, devices, states, gateways, events and other domain data into public models. Internal response models describe login results, OAuth tokens, listener registration, execution and scheduling IDs, local-token generation/activation, API errors and wrapped device-state lists.

Optional properties represent missing or null fields and gateway-specific alternatives. Device-state wrappers support states, deviceStates and values, using the first non-null collection in that order. Additional JSON fields are ignored. Required IDs and tokens are validated before use; properties with an incompatible JSON type are rejected rather than converted to arbitrary strings.

Existing public methods continue to return useful domain models or validated values. The small transport wrappers do not add public API surface. Open-ended state values and command parameters remain flexible, and OpenLocalPairing returns completion only because its response schema is not portable. FetchEvents returns typed events. Flexible values deserialize to CLR primitives, lists and dictionaries, without exposing JSON document types.

Automated tests

OverKizApi.Tests contains 272 offline NUnit tests and 6 opt-in live tests, targeting both net472 and net10.0, with the same latest C# language setting as the library. Open OverkizClient.slnx in Visual Studio and use Test Explorer, or run:

dotnet test OverKizApi.Tests/OverKizApi.Tests.csproj -c Release

The offline API tests exercise the public client through an injected HttpClient and a strict scripted HTTP handler. Every request is intercepted: it does not open sockets, access cloud accounts, use saved credentials or operate devices. All offline identifiers, credentials, tokens and responses are synthetic. Configuration tests use temporary files which they remove after each run. Tests validate request methods, escaped URLs, authorization headers and JSON/form payloads as well as returned models and exceptions.

Coverage includes standard, Somfy and CozyTouch login; token refresh; Rexel gateway discovery/selection; setup caching; device/state parsing; commands and scenarios; execution history; event registration/fetch/cleanup; local tokens and developer mode; HTTP error mapping; enum compatibility; serialization; and client resource ownership. NUnit3TestAdapter enables Visual Studio discovery, and the NUnit tests GitHub workflow runs both targets on pushes and pull requests without publishing packages.

The suite validates library behavior against synthetic protocol examples, not service availability or compatibility with every physical gateway. Nexity authentication is currently an explicit unsupported stub. Local label polling is checked for initial snapshots, throttling and best-effort errors; the timed rename-difference branch is not covered by this first suite. See the test guide for regression details and limitations.

Opt-in local API live tests

LiveLocalApiTests is a separate NUnit fixture in category Live. Its six tests use an existing local gateway token to check authentication, gateways, setup, devices, device states and event-listener lifecycle. They do not generate or revoke tokens, send device commands or change device settings. The event test creates its own listener and unregisters it during cleanup.

The console and tests share %LOCALAPPDATA%/OverkizClient/LiveTestSettings.json. Opening the console in local mode imports its previously saved local credentials if the shared file is missing; saving local credentials updates this same file while preserving its enable flag and timeout. Cloud-account credentials are not used by this fixture.

Live tests are disabled by default. Set enabled to true in the private JSON file, or explicitly pass the opt-in run settings:

dotnet test OverKizApi.Tests/OverKizApi.Tests.csproj -c Release -f net472 --filter "TestCategory=Live" --settings OverKizApi.Tests/LiveTests.runsettings.example

For Visual Studio, select a local copy of the run settings and run the Live category. Ordinary offline checks can always use --filter "TestCategory!=Live"; CI uses that filter explicitly.

An embedded runner can supply the same JSON file in its private test inputs, set NUnit's TestDataDirectory parameter to that input directory and set EnableLiveTests=true only for its separately selected Live suite. An explicit false overrides the saved enable flag. Supplying an input directory prevents fallback to desktop credentials. No credentials are copied into builds or packages. See the live test guide for details.

Test Console

The solution includes OverKizApi.TestConsole, an interactive command-line tool for testing API operations — device listing, command execution, live event watching, and Rexel gateway discovery/selection — against both cloud and local connections.

Documentation

Full API documentation is published at oznetmaster.github.io/OverkizClient.

Acknowledgements

Behavioral and compatibility reference work in this project draws on the upstream python-overkiz-api project and its public documentation. This is an independent C# implementation and does not include or derive from its source code.

License

MIT © 2026 Neil Colvin — see LICENSE.

Publishing when local hardware is unavailable

The publish/release workflows support an explicit manual override when the processor or local self-hosted GitHub Actions runner is unavailable. Select skip_hardware_checks and provide a single-line hardware_skip_reason. Use the workflow's normal source and version controls. The override applies only to that invocation and is recorded with the exact source revision in its warning and job summary; it does not create a passing hardware-test result.

GitHub-hosted validation remains mandatory for the checked-out source, and the normal build, tests and packaging steps still run. Wait for the configured hosted workflows to pass, or run them on the same source revision first. None of these hosted checks needs the local runner or processor. Automatic tag/release-triggered runs retain the normal hardware checks; use a manual invocation of the updated release workflow when an offline override is needed.