Somfy TaHoma Switch RTI Driver

Version 3.08

Overview

This driver gives RTI two-way control of Somfy motorised blinds, shades and awnings through the Somfy TaHoma Switch hub. It talks to the hub over the documented Developer Mode local API (HTTPS with a Bearer token) entirely on your LAN – no cloud relay and no Somfy account needed at runtime. It supports up to 20 individual shades and 10 groups, with live position feedback.

Two device families are supported:

- Zigbee shades report live position (0-100%) and accept Up / Down / Stop / My / Set Level.

- RTS radio motors accept Up / Down / Stop / My. RTS is one-way, so position is not reported.

What's New in Version 3 (major rewrite)

Version 3 is a ground-up rebuild of how the driver is set up and wired:

- One-click discovery inside Integration Designer. Right-click the driver and choose "Discover TaHoma Devices" – it reads your hub and fills in every shade and group automatically. No separate PC tool step required (the PC tool is still included as a backup).

- Two ways to wire a panel, both using simple static tags. Add each shade to a room as a source and use the standard Shade Up / Down / Stop / Level tags, OR type the per-number Shade 1 Up, Shade 2 Down ... tags on any button. See "Wiring a Panel" below.

- Live position feedback on both wiring styles, tracking the motor as it moves.

- Requires minimumApexVersion 11.4 (Integration Designer 11.4+), which the driver sets automatically.

Requirements

- Somfy TaHoma Switch hub (local-API model) with Developer Mode enabled.

- Somfy Zigbee or RTS blinds, shades or awnings already paired to the TaHoma Switch.

- RTI XP processor (runtime 24 or later) on the same LAN as the TaHoma Switch.

- RTI Integration Designer 11.4 or later.

Quick Start (end to end)

1. Enable Developer Mode in the TaHoma app and copy the 20-character Bearer token (see "Enabling Developer Mode").

2. In Integration Designer, add the Somfy TaHoma Switch driver to your project.

3. In Driver Properties, set the TaHoma IP Address and Bearer Token.

4. Right-click the driver and choose Discover TaHoma Devices. Every shade and group is filled in automatically with its name, URL and type.

5. (Optional) leave the Licence Key blank to run the 120-minute trial, or paste your purchased key.

6. Wire your panel (see "Wiring a Panel").

7. Send the project to the processor. The driver connects and feedback populates within a few seconds.

Enabling Developer Mode

1. Open the TaHoma app on your phone or tablet.

2. Go to Settings.

3. Tap "Advanced features".

4. Tap the version number 7 times to unlock Developer Mode.

5. Go back – a new "Developer Mode" entry appears.

6. Open it, activate the local API, and copy the 20-character Bearer token.

Note: the Bearer token is tied to that hub. If you factory-reset or replace the TaHoma Switch you must generate a new token and update the driver.

Discovering Your Devices

Recommended – in Integration Designer:

1. Set the TaHoma IP Address and Bearer Token in Driver Properties.

2. Right-click the Somfy TaHoma Switch driver and choose Discover TaHoma Devices.

3. The driver connects to the hub, lists what it found, and fills every shade and group slot (name, URL, type) automatically. Re-run it any time you add or rename devices on the hub.

Backup – PC tool: if you prefer, the included Get_TaHoma_Devices.bat (and a browser page, TaHoma_Device_Discovery.html) list every device's URL so you can paste them in by hand or import a generated configuration file.

Wiring a Panel

There are two ways to wire buttons, and they can be used together.

Option A – add each shade to a room (standard tags):

1. In Add Workspace Item, add a Shade source to the room and pick the shade you want.

2. On a UI layer whose Source is that shade, tag buttons with the standard tags Shade Up, Shade Down, Shade Stop, Shade My and Shade Level (slider). Integration Designer wires the command and the matching feedback for you.

Option B – per-number tags (type on any button):

Tag a button with Shade 1 Up, Shade 1 Down, Shade 1 Stop, Shade 1 My or Shade 1 Level (and Shade 2 ... through Shade 20 ...). Groups use Group 1 Up ... Group 10 Level. These work on any layer without a source assignment.

Friendly names on buttons: the tag string is fixed (Shade 1, Shade 2 ...), but the friendly name from the hub is available as a variable – bind a button's Text to the Shade N Name variable to show "Living Room", "Master Bedroom", etc.

Feedback: on either style, Shade Up = Is-Open, Shade Down = Is-Closed, Shade Level = Position (bind to a slider/gauge), Shade Status = text. Drop the Level tag and a slider together for a control that drives the blind and tracks its live movement.

Tag Reference: at startup the driver prints a full "which number is which room" table to the log, and a Print Tag Reference function repeats it on demand – handy when you have many shades.

Configuration Reference

Licensing

- Licence Key (cfgLicence): the key issued for this processor's MAC address. Leave blank for the 120-minute trial.

Connection Settings

- TaHoma IP Address (cfgIPAddress): the LAN IP of your TaHoma Switch. Give the hub a DHCP reservation so it never changes.

- Bearer Token (cfgToken): the 20-character token from Developer Mode.

- Poll Interval (cfgPollInterval): full status refresh interval in seconds (default 30). A fast 2-second event poll gives near-instant feedback, so the default is fine.

- Enable Debug Logging (cfgDebug): turn on only while troubleshooting.

Devices / Groups are filled by the Discover button. Each shade has a Name, URL and Type (Zigbee or RTS); each group has a Name and URL.

Commands / Functions

Every shade and group supports the same set, available as standard tags, per-number tags, and scripted functions:

- Up – fully open (Zigbee: position 0).

- Down – fully close (Zigbee: position 100).

- Stop – stop movement.

- My (Favourite) – move to the motor's saved favourite position.

- Set Level – move to a specific percentage. Bind to a slider.

All Shades: Up / Down / Stop / My / Set Level / Refresh apply to every configured shade at once.

Scripted (for advanced macros): DeviceOpen / DeviceClose / DeviceStop / DeviceMy / DeviceSetPosition take a shade number (and a position for Set); GroupOpen / GroupClose / GroupStop / GroupMy / GroupSetPosition do the same for groups.

System Variables

Per shade (N is the shade number)

- Shade N Name (DeviceNName) – the friendly name from the hub. Bind to a button's Text.

- Shade N Position (DeviceNPosition) – 0-100 (0 = open, 100 = closed). Bind to a slider/gauge.

- Shade N Status (DeviceNStatus) – text: Open, Closed, Moving or a percentage.

- Shade N Is Open / Is Closed (DeviceNIsOpen / DeviceNIsClosed) – booleans for layer visibility / button state.

(The per-number tags use a parallel set of variables that track the same state.)

Connection

- Connected, Connection Status, Last Update.

Licensing

- Licence Valid, Licence Status, Trial Active, Trial Expired, Trial Time Remaining, MAC For Key (this processor's MAC in the exact format needed to generate a key).

Events

- CONNECTED / DISCONNECTED / CONNECTION_ERROR – link state changes.

- DEVICE[N]_MOVING, DEVICE[N]_OPENED, DEVICE[N]_CLOSED – per-shade movement.

- GROUP[N]_COMMAND – fires when a group command is sent.

- TRIAL_WARNING / TRIAL_EXPIRED – trial lifecycle.

Licensing

This driver requires a licence key tied to your RTI processor's MAC address.

Free trial: a fully functional 120-minute trial runs with no key. When it expires, shade and group commands are blocked until a valid key is entered (feedback and configuration still work). The trial resets when the processor reboots.

Per processor: one key per RTI XP processor. The MAC For Key variable shows the exact MAC to use. Enter the key in the Licence Key field.

To purchase:

1. Go to https://smarthomeprogramming.com.au/store/

2. Add the Somfy TaHoma Switch driver to your cart.

3. Enter your RTI processor MAC address (from the MAC For Key variable) at checkout.

4. Complete payment and receive your licence key by email.

5. Paste the key into the Licence Key field and send the project.

Troubleshooting

Cannot connect / Discover fails

- Verify the TaHoma IP address and that the processor (and the PC running Discover) are on the same subnet as the hub.

- Confirm the Bearer Token is exactly 20 characters and Developer Mode is still enabled.

A button press does nothing after re-sending the driver

- Re-sending reloads the driver and briefly drops any connected panel. Let the panel reconnect (a few seconds) and try again.

Commands not working

- Check whether the trial has expired (Licence Status will say so) – enter a licence key.

- Confirm the shade works in the TaHoma app, and re-run Discover to refresh its URL.

No position feedback

- RTS devices are one-way; use a Zigbee device for position feedback.

Version History

v3.x - Major rewrite: in-Integration-Designer "Discover TaHoma Devices" button; standard Shade Up/Down/Stop/Level tags plus per-number Shade N tags; live feedback on both; Tag Reference printout.

v1.x - Local-API control, Zigbee/RTS support, 2-second event feedback, groups, licensing (120-minute trial + per-processor key), PC discovery tool.

Support

For technical support, bug reports or feature requests:

- Store / account: https://smarthomeprogramming.com.au/store/

- Email: david@smarthomeprogramming.com.au

Terms of Service

This driver is provided "as is" without warranty of any kind. You use it entirely at your own risk. A free trial is included so you can verify compatibility before purchasing – do not purchase a licence if you have not tested the driver on your hardware. For full terms including warranty disclaimer, limitation of liability and refund policy, visit https://smarthomeprogramming.com.au/store/terms.html

Copyright 2026 Smart Home Programming. All rights reserved.