CrestronHomeDriver.Overkiz.Shades 2.3.3

OverkizCrestronDriver

A Crestron Home platform driver that integrates Overkiz-compatible smart-home gateways (Somfy TaHoma, Atlantic Cozytouch, Hitachi Hi Kumo, and others) as managed shade/blind devices, supporting both cloud and local LAN connections.

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 the Overkiz API, discovers all shades/blinds on the gateway, and registers each as a managed child sub-controller under a single Crestron Home device entry. Optionally, shades can be grouped into room aggregate entities that provide a combined room-level UI tile alongside the individual shade sub-controllers.

The driver is implemented using the Crestron Home SDK V2 Entity Model — it derives directly from ReflectedAttributeDriverEntity and declares all properties, commands, and events via SDK attributes, with no dependency on any RAD base type (ABaseDriver, ABasicVideoDisplay, etc.) or command/state controller infrastructure (StateController, PollingDeviceStateBase, etc.).

Features

• Cloud connection via Somfy OAuth 2.0 (and other Overkiz-based cloud servers)
• Local LAN connection using a Somfy developer-mode bearer token
• Local mode takes precedence when either local field is supplied, and requires both Gateway IP and Local API Token
• Automatically discovers all shades/blinds on the gateway and exposes each as a managed child device
• Per-shade UI with position control (two-way devices), open/stop/close buttons, and optional My position button
• Optional room aggregate entities grouping multiple shades with per-slot labels, room-level open/close/stop/my commands, and room-wide position control
• Display name overrides for individual shades via ShadeDisplayNames config
• Dynamic rename, add, and delete detection via Overkiz event streaming
• RTS (one-way radio) shade support with motion state inferred from command execution lifecycle

Compatibility note: the driver is intended for Overkiz-compatible gateways, but the current implementation has only been validated by the author with a Somfy TaHoma gateway. Other Overkiz-compatible gateways may work but have not yet been directly tested with this Crestron Home driver.

Prerequisites

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 Shade_Overkiz_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.Overkiz.Shades NuGet package. This NuGet package conforms to the Crestron Home Driver NuGet Publishing Standard v1. It is a distribution wrapper for the final Shade_Overkiz_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 Shade_Overkiz_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 Configure application, add a new device and select the Tahoma Gateway driver.
4. Fill in the connection configuration:

If either local-mode field is supplied, the driver treats the configuration as local mode and requires both local values. Otherwise it requires the cloud username and password.

The local API token is not generated by this driver. It must be obtained from the gateway vendor's cloud/account system for the specific Overkiz ecosystem you use. The exact process varies by brand, server region, and account type, and some ecosystems may not expose local or developer API access at all. For Somfy-based systems, use Somfy's developer/local API process. For other Overkiz-based systems, consult that vendor's developer or local API documentation.

Current limitation: install and configure this driver using the Crestron Home Setup application. The beta Configure Pro workflow is not currently recommended for this driver.

Configuration

Room Groups

Groups shades into room aggregate entities. Format:

RoomKey:Display Title=ApiLabel1:Slot1 Name,ApiLabel2:Slot2 Name

Multiple rooms are separated by semicolons. Example:

Lounge:Lounge Blinds=Lounge Left Blind:Left,Lounge Center Blind:Centre,Lounge Right Blind:Right; Bedroom=Bedroom Blind

• RoomKey — a unique room key used internally for matching (case-insensitive)
• Display Title — the visible label for the room tile
• ApiLabel — the exact name of the shade as it appears in the Overkiz app
• Slot Name — the subheading shown under each slot in the room tile

Room tiles support up to 10 configured slots. Extra configured slots beyond that UI limit are not shown.

Shade Display Names

Overrides the visible label for individual shade sub-controllers. Format:

ApiLabel:Display Name; ApiLabel2:Display Name2

Example:

Master Blind:Master Bedroom; En-suite:Ensuite Blind

The ApiLabel is the raw Overkiz API name used for all room-matching logic. The display name is shown in the Crestron Home UI only.

Building from Source

Dependencies

• OverkizClient NuGet package (restored automatically)
• Crestron.DeviceDrivers.DevKit NuGet package
• C# 13 language features compiled for a .NET Framework 4.7.2 target, with compatibility shim assemblies merged into the driver package as needed
• ILRepack (via ILRepackMerge.ps1) to merge dependencies into a self-contained driver DLL
• PatchMergedAssembly.ps1 to rewrite merged System.* helper types that Crestron Home's Mono sandbox rejects during reflection
• ManifestUtil.exe from the Crestron Driver SDK to produce the final .pkg

Build

dotnet build -c Release

The build pipeline:

1. Compiles the driver targeting net472
   • The project uses LangVersion=latest (currently C# 13) while targeting the Crestron-required .NET Framework 4.7.2 runtime.
   • Required compatibility shim assemblies are merged into the driver and then patched for Crestron Home's runtime constraints.
2. Bumps DriverVersion and VersionDate in Shade_Overkiz_IP_V2.json
   • Every deployable build increments the 4th component.
   • Start a new public release line by running StartReleaseCycle.ps1, which increments the 3rd component and resets the 4th to 0000.
3. ILRepacks runtime dependencies into a single Shade_Overkiz_IP_V2.dll
4. Runs PatchMergedAssembly.ps1 against the merged assembly
5. Packages everything into Shade_Overkiz_IP_V2.pkg using Crestron's ManifestUtil

GitHub Release Asset

GitHub does not receive anything from bin/ automatically, but the repository now includes a working GitHub Actions workflow that builds and attaches the .pkg when a GitHub Release is published.

The release-package.yml workflow runs on windows-latest, installs Crestron.DeviceDrivers.ManifestUtil from NuGet, builds the solution in Release, locates the generated Shade_Overkiz_IP_V2.pkg, and uploads it as the release asset automatically.

The same release workflow also publishes the OverkizCrestronDriver NuGet package, which wraps the final Shade_Overkiz_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.

License

MIT + Commons Clause © 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 work (e.g. a Crestron installer commissioning a customer system) is explicitly permitted, even where a fee is charged for that service.

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.