WiserHeatAPIv2 1.1.2

WiserHeatAPIv2

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

Version 1.1.2 corrects Fahrenheit model readings and commands. See temperature units for conversions, limits and control values, and release notes for the patch details.

A .NET client library for the Drayton Wiser Heating local REST API, enabling discovery, monitoring, scheduling, and control of Wiser hubs, rooms, devices, hot water, smart plugs, lights, shutters, and related entities.

Drayton, Wiser, and Schneider Electric are trademarks of Schneider Electric SE, its subsidiaries, or affiliated companies. This project is an independent, unofficial .NET library and is not affiliated with or endorsed by Schneider Electric.

Release History

See the changelog for version history and fixes, and GitHub releases for release notes and packages.

Supported Platforms

Overview

WiserHeatAPIv2 provides a strongly typed .NET wrapper around the local Wiser hub API. It supports:

• Direct connection to a Wiser hub by IP address and secret
• Local network discovery of Wiser hubs
• Reading and refreshing hub state
• Access to rooms, devices, schedules, hot water, system information, and capabilities
• Control operations for supported device types
• YAML and structured schedule import helpers

This .NET library is an adaptation of the original Python project wiserHeatAPIv2 by Mark Parker.

Installation

dotnet add package WiserHeatAPIv2

The official NuGet package is built with all optional feature areas enabled.

Conditional Features

The source project contains several feature areas controlled by compilation symbols:

• SHUTTER — shutter-related types and functionality
• LIGHT — lighting-related types and functionality
• HEATACTUATOR — heating actuator support
• OPENTHERM — OpenTherm-related support

The published NuGet package includes all of these optional capabilities.

Some direct dependencies currently resolve to prerelease package versions. These were introduced through vulnerability remediation recommended by Visual Studio and have been retained to avoid reintroducing the original security or compatibility issues without further validation.

Quick Start

Obtaining the Wiser secret

The Wiser hub secret is required to authenticate with the local API.

Reference: https://it.knightnet.org.uk/kb/nr-qa/drayton-wiser-heating-control/#controlling-the-system

To obtain it:

1. Press the setup button on the HeatHub so that the light starts flashing.
2. Look for the Wi-Fi network (SSID) called WiserHeatXXXXXX, where XXXXXX is the last 6 digits of the MAC address.
3. Connect to that network from a Windows, Linux, macOS, Android, or iPhone device.
4. Open a browser and navigate to http://192.168.8.1/secret.
5. The hub will return a string containing your system secret. Store this somewhere safe. If you are using the console test utility, place this value together with the hub IP address in wiserkeys.params.
6. Press the setup button on the HeatHub again to return it to normal operation.
7. Copy the secret and save it somewhere safe.

If you already know the hub IP address, you can connect directly. Otherwise, use the discovery helper shown below to find the hub first.

Connect to a hub

using WiserHeatApiV2;

var api = new WiserAPI("192.168.1.50", "your-wiser-secret");
await api.InitializeAsync();

Console.WriteLine($"System version: {api.System?.ActiveSystemVersion}");
Console.WriteLine($"Room count: {api.Rooms.All.Count}");

Discover hubs on the local network

using WiserHeatApiV2;

List<WiserDiscoveredHub> hubs = await WiserDiscovery.DiscoverHubAsync(60, 2);
foreach (var hub in hubs)
{
    Console.WriteLine(hub.Url);
}

Inspect rooms and devices

using WiserHeatApiV2;

var api = new WiserAPI("192.168.1.50", "your-wiser-secret");
await api.InitializeAsync();

foreach (var room in api.Rooms.All)
{
    Console.WriteLine($"{room.Name}: {room.CurrentTemperature}°C -> {room.CurrentTargetTemperature}°C");
}

foreach (var device in api.Devices.All)
{
    Console.WriteLine($"{device.ProductType} #{device.Id}");
}

Refresh hub data

await api.ReadHubDataAsync();

Check schedule command results

Always check the Boolean returned by schedule operations, including JSON import and SetScheduleFromWsDataAsync. A rejected request or connection failure must not be treated as a successful update. A successful command response does not independently confirm that the requested schedule is now applied; refresh the hub state when that confirmation is required. After a connection failure, read the current state before deciding whether another write is appropriate.

Automated Tests

WiserHeatAPIv2.Tests contains an offline NUnit 4 suite, an opt-in read-only live fixture, and opt-in room control tests included in the main Visual Studio solution. It targets .NET Framework 4.7.2 and .NET 10, uses LangVersion=latest, and runs through Visual Studio Test Explorer with the NUnit adapter.

On Windows, with the .NET 10 SDK and .NET Framework 4.7.2 targeting pack installed:

dotnet test WiserHeatAPIv2.Tests/WiserHeatAPIv2.Tests.csproj --configuration Release --filter "TestCategory!=Live"

To run only one target, add --framework net472 or --framework net10.0. In Visual Studio, build the solution, open Test > Test Explorer, and run WiserHeatAPIv2.Tests.

The offline suite covers HTTP verbs, authentication, redirects, retry limits and response disposal, cancellation versus timeouts, JSON response handling, temperature and telemetry models, room and device commands, heating schedule export and assignment, initialization, refresh, and disposal. Synthetic hub responses are supplied through an in-memory HTTP handler; no hub, network access, secret, or local settings file is required. The tests do not operate physical devices.

GitHub CI excludes the Live category and runs the offline suite on both framework targets and uploads test results before packing the library. The test project is not packable and is not published to NuGet. The offline suite verifies client behavior against simulated responses; it does not validate discovery, real firmware behavior, or every device family.

Validation on both frameworks: 138 offline tests passed, six read-only live tests passed with the optional OpenTherm test skipped, and both room control tests passed when explicitly selected. Live validation used a real hub; control tests were run sequentially and followed by a readback confirming restoration.

The live suites are available from the repository and are not included in the published library package. v1.1.0.6 updates the library dependencies to log4net 3.4.0 and YamlDotNet 18.1.0, with unchanged public API signatures. See the changelog for release details.

Read-only Live Tests

LiveHubTests is a separate fixture in the Live category. It reads hub information, rooms, device collections, telemetry, schedules, and optional OpenTherm data, and checks repeated refreshes. It sends no control commands. One authenticated snapshot is shared for the fixture; the refresh test performs two further reads. Missing rooms, devices, schedules, or optional OpenTherm data produce explicit skips where applicable.

Copy LiveTestSettings.example.json to %LOCALAPPDATA%\WiserHeatAPIv2\LiveTestSettings.json. Enter the hub hostname/IP and existing secret, then set enabled to true when you want local live testing. timeoutSeconds limits each initialization or refresh operation (1–120 seconds; default 60). Use a hostname when available to avoid depending on a fixed IP address.

dotnet test WiserHeatAPIv2.Tests/WiserHeatAPIv2.Tests.csproj -c Release -f net10.0 --filter "TestCategory=Live&TestCategory!=LiveControl"

Use -f net472 to test the .NET Framework target. In Visual Studio Test Explorer, select the LiveHubTests fixture after enabling the private settings. Merely selecting it does not bypass the settings flag. Ordinary test runs skip the live fixture unless enabled; use --filter "TestCategory!=Live" to guarantee offline execution even when your local flag is enabled.

The NUnit parameter TestDataDirectory overrides the settings directory, and EnableLiveTests=true overrides enabled:false for a selected live run. EnableLiveTests=false disables it before reading credentials. These parameters follow the runner convention used by other test suites; a processor test package has not yet been added.

Actual LiveTestSettings.json files are private runtime inputs, never NuGet content, and are not copied to build or publish output. Keep yours outside the checkout. This local checkout also excludes that filename through .git/info/exclude; exclusions are local and are not distributed to other clones. Only the empty example belongs in Git. The existing console continues to use its separate wiserkeys.params file; enter the same hub and secret in the live-test settings.

Room Control Tests

LiveRoomControlTests has the Live and LiveControl categories and follows the same settings-based opt-in as the other live fixtures. It requires live testing to be enabled and controlRoomName to identify exactly one room in private settings. It does not use NUnit's Explicit attribute. Once live testing is enabled, Run All can include these tests; use the read-only filter above to exclude device changes. To run only the control fixture, select it in Test Explorer or use:

dotnet test WiserHeatAPIv2.Tests/WiserHeatAPIv2.Tests.csproj -c Release -f net10.0 --filter "FullyQualifiedName~LiveRoomControlTests"

Run one framework or runner at a time against a room. The tests toggle and restore window detection, and apply a one-minute setpoint override 0.5°C below the current value before cancelling it and verifying schedule control has resumed. The temperature test requires Auto mode following a schedule with no existing override, boost, or timer; other initial states are skipped. It preserves the selected schedule and follows its current setpoint if the schedule changes during the test.

Each test reads its starting state from the hub and restores the setting in finally, using a separate cleanup timeout even if the command or assertion fails. Restoration is verified by reading back the hub state, and cleanup failures are reported alongside the original test failure. A terminated process or unreachable hub can prevent cleanup; the temperature override expires after one minute, but an interrupted window-detection test may need manual restoration. These tests do not change room mode, schedule assignments, room names, boosts, or hot-water settings.

Test Console

The solution includes WiserHeatAPIv2Test, a console application that exercises hub discovery, initialization, device listing, room inspection, and general API validation against a real Wiser installation.

The console and WPF application load wiserkeys.params when it is present. Each project includes a sample in GitHub:

Copy the sample inside the project folder to wiserkeys.params, then replace the placeholder values:

wiserkey=your_wiser_secret_here
wiserhubip=your_wiser_hub_hostname_or_ip

When the real file exists in the project folder, local builds copy it to the application's output directory. If you start the console from a terminal, run it with that output directory as the working directory. The console also accepts wiserhubip=discover to discover a hub; when multiple hubs are found, specify the intended host instead.

Before adding your real credentials, put this filename in your clone's .git/info/exclude:

wiserkeys.params

Only the sample is tracked. The real file remains local and is excluded from publishing and packaging. Local exclusions are not distributed with clones, so each clone needs that entry.

The NUnit live tests use a different file, LiveTestSettings.example.json, copied to the private location described above. They do not automatically read wiserkeys.params; use the same hub and secret in the JSON settings.

Documentation

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

Repository Contents

• WiserHeatAPIv2 — the main library project published to NuGet
• WiserHeatApp.Wpf — a WPF desktop application for interacting with and monitoring a Wiser system
• WiserHeatAPIv2.Tests — offline NUnit tests, opt-in hub reads, and opt-in room control tests for both supported frameworks
• WiserHeatAPIv2Test — a console-based test utility for exercising the API against a real hub

Acknowledgements

This is an independent .NET implementation, written from scratch. Behavioral and compatibility reference work in this project draws on the upstream Python wiserHeatAPIv2 project and its public documentation.

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.