OverkizClient 1.2.0

OverkizClient

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 1.2.0

This minor release adds dedicated internal response models and six opt-in local API live tests, and expands offline NUnit coverage to 233 cases on each target framework. The console and live tests share private local credentials through LiveTestSettings.json.

Public method signatures and existing public domain models remain unchanged. Response validation is stricter: blank required identifiers and incompatible known-field JSON types are rejected, and invalid OAuth responses are rejected before updating authentication state. Optional response fields and unknown fields remain supported. See the changelog, release notes and test guide for the exact behavior and live-test opt-in instructions.

Tagged releases run all offline cases on .NET Framework 4.7.2 and .NET 10 before publishing to NuGet. The test project, NUnit dependencies and private settings are not included in the library package.

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 retains its raw JSON result because the library does not define that payload's schema. FetchEventsRaw provides both typed events and the original JSON for diagnostics.

Automated tests

OverKizApi.Tests contains 233 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.