OverkizClient 1.1.5

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.1.5

This patch adds 154 offline NUnit tests and fixes the authentication, JSON state handling, event mapping and error-handling problems they exposed. It retains the existing public API and targets .NET Framework 4.7.2 and .NET 10. No credentials or devices are required to run the automated tests.

See the changelog, release notes and test guide. Tagged releases run the suite on both frameworks before publishing to NuGet. The test project is not included in the NuGet 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();

Automated tests

OverKizApi.Tests contains 154 NUnit 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 suite exercises 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 identifiers, credentials, tokens and responses are synthetic. 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.

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.