CrestronHomeDriver.Wiser.WiserHeat 1.3.16

WiserHeatCrestronDriver

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

See the changelog for release history and the release notes for the current driver update. Driver releases are made for runtime fixes or dependency changes; adding tests alone does not require a driver release.

A Crestron Home platform driver that integrates a Drayton Wiser Heating (UK and Ireland) hub and exposes discovered rooms as managed child thermostat devices.

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

Crestron and Crestron Home are trademarks or registered trademarks of Crestron Electronics, Inc. This project is not affiliated with, endorsed by, or sponsored by Crestron Electronics, Inc.

Driver Architecture

This driver is a platform driver. It connects to a local Wiser hub, discovers rooms, and registers each room as a managed child thermostat entity under a single Crestron Home device entry.

The driver is implemented using the Crestron Home SDK V2 Entity Model. It derives from ReflectedAttributeDriverEntity and uses SDK attributes for commands and properties, while packaging the deliverable as a standard Crestron Home .pkg driver.

Features

• Connects directly to a local Wiser hub using hub IP/hostname and secret
• Discovers Wiser rooms and exposes them as managed thermostat child devices
• Heat-only thermostat UI for each room
• Current temperature display and target temperature adjustment
• Room boost control
• Schedule enable/disable control
• Schedule assignment and schedule selection UI
• Shared schedule day editing from the Crestron Home UI
• Dynamic room tile icons reflecting heating, scheduled, or regular state
• Optional whole-house hot water control on the platform options page
• Optional global Away Mode control on the platform options page

Prerequisites

Wiser Hub Compatibility

This driver targets the Drayton Wiser Heating system, covered by Schneider Electric's UK and Ireland system guide.

Current live testing of the driver and its underlying library has been performed with a Drayton Wiser 2nd Generation HubR, 3 channel (CCTFR6313G2D, v2). Earlier versions of the underlying library operated with a Wiser v1 hub, but the interface and library have since changed. The current driver and library have not been revalidated on v1 hardware, so v1 compatibility is unverified and is not guaranteed.

Here, v1 and v2 identify the Wiser hub hardware generation.

Other regional systems and product families sold under the Wiser name have not been validated with this driver. In particular, local API compatibility with continental European Wiser Home hubs has not been established. A shared brand or app does not establish compatibility.

Installation

The best way to download and install this driver on a Crestron Home system is to use the Crestron Home Driver Feed Installer repository and application.

If you prefer to install manually, use the attached Thermostat_WiserHeat_IP_V2.pkg asset from the relevant GitHub Release. The automatic GitHub Source code (zip) and Source code (tar.gz) assets are repository snapshots, not installable Crestron driver packages.

NuGet package availability: this driver is also published as the CrestronHomeDriver.Wiser.WiserHeat NuGet package. This NuGet package conforms to the Crestron Home Driver NuGet Publishing Standard v1. It is a distribution wrapper for the final Thermostat_WiserHeat_IP_V2.pkg artifact, includes the required crestron-driver-package.json manifest, and is not intended as a direct DLL reference package.

Crestron Home Driver NuGet Publishing Standard v1 is not an official Crestron product or specification. It is an open source packaging standard created to facilitate community distribution and discovery of Crestron Home drivers through NuGet.

1. Download Thermostat_WiserHeat_IP_V2.pkg from the GitHub Release assets, or build it yourself using the instructions in Building from Source.
2. Upload the .pkg to your Crestron Home processor manually, for example via SFTP to /user/ThirdPartyDrivers/Import.
3. In the Crestron Home setup workflow, add the Wiser platform driver.
4. Enter the required configuration values:

When either platform option is enabled, the root platform tile opens a Wiser Heat Options page. The verified behavior is:

• Whole-house hot water and Away Mode both work from the platform options page.
• Away Mode is a global system mode, but individual room and hot water settings can still be overridden afterward.
• State-changing controls reject repeat presses while a command is already in flight to avoid double-push races.

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

Typical process:

1. Press the setup button on the HeatHub so the indicator starts flashing.
2. Connect to the temporary Wi-Fi network exposed by the hub.
3. Open http://192.168.8.1/secret in a browser.
4. Save the returned secret securely.
5. Return the hub to normal operation.

Building from Source

Dependencies

• WiserHeatAPIv2 NuGet package
• Crestron.DeviceDrivers.DevKit NuGet package
• .NET Framework 4.7.2
• ManifestUtil.exe from the Crestron Driver SDK
• ILRepackMerge.ps1 and PatchMergedAssembly.ps1 in this repository for dependency merge and patching

Build

dotnet build WiserHeatCrestronDriver/WiserHeatCrestronDriver.csproj -c Release

The build pipeline:

1. Compiles the driver targeting net472
2. Reads the manifest version; Debug builds increment its fourth component, while local Release builds preserve it and release CI verifies the selected tag
3. Merges runtime dependencies into the driver assembly
4. Patches the merged assembly for Crestron runtime compatibility
5. Packages everything into Thermostat_WiserHeat_IP_V2.pkg

GitHub Release Asset

This repository includes a GitHub Actions workflow that builds and attaches the .pkg when a GitHub Release is published.

The same release workflow also publishes the CrestronHomeDriver.Wiser.WiserHeat NuGet package, which wraps the final Thermostat_WiserHeat_IP_V2.pkg artifact.

Typical release flow:

1. Push the release commit and tag.
2. Publish a GitHub Release for that tag.
3. Let the workflow build and attach the .pkg asset.

When publishing a release, include release notes mentioning the verified platform options behavior, specifically that whole-house hot water and Away Mode both work and that Away Mode does not prevent later individual overrides.

Notes

When changing entity shape, UI definitions, or child-device property surfaces, Crestron Home may retain stale child metadata on an existing processor. If runtime UI behavior does not match the current build after such a change, remove and re-add the child device before assuming the driver logic is wrong.

License

MIT + Commons Clause. Copyright (c) 2026 Neil Colvin - see LICENSE.

Free to use and modify. You may not sell the Software as a standalone product or sublicense it. Commercial system integration and commissioning work is permitted, provided the Software itself is not sold as a standalone product.

Note: This project references Crestron.DeviceDrivers.DevKit, which is subject to Crestron's SDK license agreement. That license governs the SDK libraries only; the source code in this repository is licensed independently under the terms above.

Automated tests

The opt-in Android UI project compares the real Hot Water and Away controls with fresh processor state, inspects the schedule/day/time choices of explicitly bound room thermostats, and restores the Home screen. It uses TestAdapter 1.12.1 and DevTools 1.13.1, and runs only when selected by a private processor workflow. Room bindings belong in the private UI settings file; the tests never choose a thermostat automatically or save an edited schedule. A separate private AllowNameBinding option temporarily renames the gateway to associate its app tile with the installed instance, then restores the name. Heating and Away commands are never sent.

The separately selected Android control project adds an Auto/Manual/Auto room-mode cycle, editor Cancel checks and an explicitly configured Save Day/Save All case. Existing manual and scheduled targets may differ; both are captured and restored. These controls can briefly change heating demand and require private room bindings. The mode cycle and Cancel case have passed development hardware validation; see the development history for the recorded scope. Both Android projects skip during ordinary desktop runs without an active processor workflow.

The read-only endurance producer is a separate .NET 10 executable for a monitoring worker. It verifies pinned active package files, processor boot, driver lifetime and fresh state against independent hub readings. Its offline tests are part of the solution and CI; running ordinary tests never starts live monitoring. Short real-function and deliberate same-version restart-rejection checks have passed development validation. Configure monitoring separately from ordinary test execution; retain the exact package identity with each observation.

The solution includes WiserHeatCrestronDriver.Tests (NUnit 4 with the Visual Studio NUnit adapter) and WiserHeatCrestronDriver.ProcessorTests (a standalone Crestron Home Utility test package). Offline tests exercise driver logic without credentials or real device commands. Processor lifecycle cases are excluded on Windows in this project; the dedicated desktop SDK harness exercises the same fixture sources. CI compares discovered tests with executed results, so adding tests does not require updating a fixed total in this document.

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

Build the processor project in Debug in Visual Studio to build and deploy using private deployment settings. See processor test instructions for setup, suites, tile operation and UI separation. Processor packages are not published to NuGet. See CHANGELOG for changes.

Command state refresh

After a state-changing command completes, the driver reads fresh hub state before publishing the result. Hot-water and Away buttons therefore show the observed state before they become available again; boost, schedule and setpoint controls also refresh immediately. Background polling requests fresh hub data approximately every ten seconds. A failed bounded read marks the gateway and its thermostats offline; polling continues, and a successful fresh read restores availability automatically while preserving room controllers and saved settings.

The opt-in Android boundary fixture also exercises both directions at the temperature limits for each current row, including rows revealed by scrolling, then verifies Cancel and unchanged independent hub schedules. Its endpoint preparation is separate from the Android button inputs. See the control-test setup and scope.

SDK command regressions also verify schedule-editor temperature limits, non-finite input, half-degree rounding, Cancel restoration and continued hub refresh after an ignored command. The supported heating range is 5-30 C / 41-86 F. Fahrenheit controls use whole-degree input steps, while physical targets retain the hub's half-degree Celsius resolution; invalid or out-of-range values are rejected before starting an edit. See the release notes for validation scope.

Expanded driver behavior tests

The SDK and processor fixtures exercise every one of the eight schedule editor positions, verify slot-specific time/temperature notifications and Cancel restoration, and check clearing/restoration as the selected day changes its number of entries. These fixtures use simulated hub responses and send no commands to a physical room. Actual Android rendering and live save/conflict behavior remain separate checks.

Cover room discovery, stable child identity, renamed/removed rooms, cleared settings, overlapping connections and late refresh/login completion. Clearing or disposing the platform now removes its children and prevents old work from restoring them. The runtime dependency is WiserHeatAPIv2 1.1.3.

Saved schedules can be reopened and saved again; integer lists and arrays are copied independently before editing; the root entity can be created and disposed repeatedly.

The package contains offline tests, SDK entity/lifecycle tests and optional live hub tests. Discover the built package in the runner to see its current test inventory. The processor package remains net472 only, appears under Utility in Configure, and can run independently through its own tile or the Windows NUnit runner. The offline and lifecycle fixtures use synthetic data. The separate live suite authenticates with the selected hub, discovers rooms, refreshes telemetry and reconnects; it sends no room-control commands.

WiserHeatCrestronDriver.Lifecycle.Tests runs the entity checks against the real desktop SDK on .NET 10. It compiles the relevant driver sources and shares fixture sources with the net472 processor tests. Building this project does not deploy a driver. A locally supplied Newtonsoft.Json.Compact.dll is needed by the SDK's manifest reader; it is supplied by the processor at runtime and must not be added to source control or bundled with the processor test package.

dotnet test WiserHeatCrestronDriver.Tests/WiserHeatCrestronDriver.Tests.csproj --filter "TestCategory!=Processor"
dotnet test WiserHeatCrestronDriver.Lifecycle.Tests/WiserHeatCrestronDriver.Lifecycle.Tests.csproj

Set CompactJsonPath in the desktop test project's private DesktopTest.Local.props, excluded through .git/info/exclude, or pass it as an MSBuild property. Keep machine paths and credentials out of tracked files.

Desktop success does not establish Mono compatibility. Build the processor test project in Visual Studio, deploy it, and run both suites on the processor. The fixtures cover configuration, restoration, refresh/reconnect races and disposal using simulated responses. Installed-driver health remains a separate gate from these test-host fixtures.

Driver build and release versions

The driver's JSON manifest is the source of its four-component build version. Debug builds increment only the fourth component; for example, 2.0.001.0005 becomes 2.0.001.0006. MSBuild's Version and default PackageVersion are derived from that same manifest and refreshed after the increment; their numeric form is 2.0.1.6. Assembly binding versions remain separate. Test-only references and IDE design-time builds do not increment the production driver version.

GitHub tags and NuGet releases retain three components: v2.0.1 and 2.0.1. Prepare the manifest's first three components for the intended release before tagging. Release CI checks that the tag matches, resets the fourth component to zero, and verifies the generated .pkg version against the manifest and release version before publishing. It does not increment the selected patch again. Local Release builds preserve the manifest. A later Debug build can legitimately be newer than a published release; the processor test package has its own independent version.

Deployment validation compares the exact built .pkg against the imported catalogue entry and installed instance, numerically including all four components. Upload/import alone does not activate the new version. Keep the tested package and its hash: rebuilding creates a new artifact that must be validated again.

Run pwsh -File tools/Test-DriverVersioning.ps1 to check these rules with temporary manifests; this does not change the working driver manifest or deploy anything.

See versioning details for build, release and installed-instance verification rules.

Desktop SDK dependency in CI

The SDK's desktop manifest reader needs its Newtonsoft.Json.Compact.dll runtime dependency. Supply a local SDK/runtime copy through the CompactJsonPath MSBuild property (or private DesktopTest.Local.props). Maintainer CI restores the same verified copy from encrypted Actions secrets into its temporary directory; it is not committed, attached to release assets or included in processor packages. Fork pull requests do not receive these secrets and require a trusted maintainer validation run.

For automated local tests, processor tests and gated driver deployment, see the Crestron Home NUnit CI development guide. It covers private configuration, live-test gates, install/update waits, results and optional test-package removal.

Local build/deployment overrides can be created by copying WiserHeatCrestronDriver.Local.targets.example to WiserHeatCrestronDriver.Local.targets beside the project. Fill in your own paths privately and exclude the resulting local file with .git/info/exclude; it is not part of the published source.

Optional development probes are described in installed room controls and configuration-preserving rollback. Their hardware validation status and restrictions are recorded in those guides.

Optional live hub tests

Use LiveTestSettings.example.json as the public template. The driver tests share the library's private %LOCALAPPDATA%/WiserHeatAPIv2/LiveTestSettings.json file (enabled, hubHost, secret). Keep the real file outside the repository or in .git/info/exclude; it is never embedded in the processor package.

On Windows, run the Live category in the .NET 10 desktop SDK harness with private settings enabled, or pass NUnit parameter EnableLiveTests=true. Ordinary CI should filter TestCategory!=Live. On the processor, select Live Hub, supply the private JSON through the runner's Test inputs, and run that suite. Its explicit runner enablement applies only to that run. The library's optional room-control settings are ignored by these read-only driver tests. The complete initial-installation workflow has been validated on a development processor: local unit/lifecycle tests, processor tests and read-only live hub tests, then actual-driver installation/configuration and configured/online/ready checks. New installations use the planned Connection and HeatSettings wizard steps with explicit choices; see the NUnit CI guide for private initial-configuration files. This workflow is supported by the published NUnit tooling. No heating controls were operated.

Visual Studio processor workflow

The solution includes WiserHeatCrestronDriver.WorkflowTests, using the published Crestron Home Test Adapter. It exposes the complete gated workflow in Test Explorer while the ordinary NUnit fixtures remain available for local testing. Configure its private settings before execution; hosted CI verifies discovery without accessing hardware.

CI discovers test identities from the built source assembly and compares them with desktop results and the merged processor package. Each suite must be nonempty; missing or unexpected cases and unexpected skips fail validation. Test totals are reported, not maintained as build constants. Live cases are discovered but never executed by ordinary hosted CI.

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.