---
title: "Somfy TaHoma – io and RTS Blinds (Local API)"
description: "Control Somfy io roller shutters, awnings and venetian blinds and RTS motors from TapHome over the local TaHoma Developer Mode API — no cloud needed."
url: "https://taphome.com/en/compatibility/somfy-tahoma-http/"
language: en
lastmod: 2026-11-04
generator: hugo
ai:
  topics: ["http","gateway","blinds","shutters","awnings","io-homecontrol","rts","rest-api","mdns"]
  questions: ["Is there a TapHome template for Somfy?","Can I integrate Somfy blinds into TapHome through the TaHoma gateway?","How to get the Bearer token of the Somfy TaHoma Developer Mode for TapHome?","How to find the deviceURL of a Somfy motor for the TapHome template?","Can TapHome control Somfy RTS motors?","Do wired Somfy motors without radio need a TaHoma gateway in TapHome?"]
---

# Somfy TaHoma – io and RTS Blinds (Local API)

Communication: Packet Parser → HTTP

- [Somfy Official Website](https://www.somfy.com)
- [Somfy TaHoma Switch Product Page](https://www.somfy.co.uk/products/1870600/tahoma-switch)

The Somfy TaHoma template connects TapHome to a Somfy TaHoma gateway (for example TaHoma Switch) over the official local API of the gateway, which Somfy calls Developer Mode. The motors are paired with the gateway in the TaHoma by Somfy app as usual; TapHome talks only to the gateway, over HTTPS on port 8443 in the local network, with no cloud connection.

The template controls io-homecontrol roller shutters and awnings by position, io-homecontrol exterior venetian blinds by position and slat angle, and sends the commands Open, My, Stop and Close to one-way RTS motors.

> [!WARNING]
> **Community template — not yet tested with TapHome.** The template was generated in the TapHome portal from the Somfy Developer Mode documentation, with the names of the device states and commands taken from community sources (Somfy does not list them). It was tested only against a simulated gateway on a local TapHome Core 2025.2, not on a real TaHoma gateway or real Somfy motors, and feedback from the field is welcome. Download the XML on this page, or get it from the TapHome portal: [Somfy TaHoma — community template](https://portal.taphome.com/portal/community/somfy-tahoma-http), and import it as a new module.

**[Somfy TaHoma — io and RTS shading motors (Developer Mode, local API)](https://portal.taphome.com/en/portal/community/somfy-tahoma-http)** — Somfy, HTTP. Somfy TaHoma gateway over its official local API (Developer Mode, HTTPS 8443, token): io roller shutters and awnings with position, io venetian blinds with slats, RTS motors as commands without feedback.

> [!NOTE]
> **Wired Somfy motors need no gateway.** A 230 V Somfy motor without a radio receiver (for example Somfy WT, four conductors — PE, N, up, down) is controlled by TapHome directly with relay modules, like any other blind motor — see [Requirements → Shading](https://taphome.com/en/docs/setup/requirements/#shading). This template is for motors with radio (io-homecontrol or RTS) that are paired with a TaHoma gateway.

## Supported gateways

According to Somfy, Developer Mode works on the large majority of TaHoma gateways. It is **not available** on:

- the TaHoma box or Somfy box of the 1st generation (square shape)
- the Connectivity Kit

## Hardware connection

No wiring is needed. The TaHoma gateway and the TapHome Core have to be in the same local network. The gateway uses a certificate signed by the self-signed Overkiz authority; the template connects with certificate errors ignored, so no certificate has to be installed.

## Configuration

### Turning on Developer Mode and creating a token

1. Open the **TaHoma by Somfy** app.
2. Go to **Configure the installation › Access the parameters** of your TaHoma box.
3. Tap the PIN of the gateway (for example 2001-1234-5678) **7 times** — Developer Mode turns on and the local API of the gateway starts.
4. In the **Developer Mode** menu, generate a token.

The token can be read and copied only when it is created — save it right away. More tokens can be generated; if a token is lost, generate a new one and enter it in TapHome.

### Finding the device addresses

Each motor paired with the gateway has an address, the `deviceURL`. To read the addresses, call the device list of the gateway with the token — for example from a computer in the same network:

```
curl -k -H "Authorization: Bearer <token>" https://<gateway-address>:8443/enduser-mobile-web/1/enduserAPI/setup/devices
```

Find the motor by its `label` (the name from the TaHoma app) and copy its `deviceURL` exactly as shown. The template encodes it for the request itself.

| Protocol | Format | Example |
|---|---|---|
| io-homecontrol | `io://{gateway-pin}/{device-id}` | `io://1234-5678-9012/4820485` |
| RTS | `rts://{gateway-pin}/{device-id}` | `rts://1234-5678-9012/987654321` |

The same answer shows what each motor supports: `definition.states` and `definition.commands`. The template expects the state `core:ClosureState` and the command `setClosure` on a roller shutter or awning, `core:ClosureState`, `core:SlateOrientationState` and `setClosureAndOrientation` on a venetian blind, and `open`, `my`, `stop` and `close` on an RTS motor. A motor whose definition lacks these names will not work with that device.

### Import parameters

| Import parameter | Description | Placeholder |
|---|---|---|
| `GatewayAddress` | IP address or host name of the TaHoma gateway, for example `gateway-1234-5678-9012.local` | `192.168.1.100` |
| `BearerToken` | Token from Developer Mode | (empty) |
| `SlideDeviceUrl` | `deviceURL` of the io roller shutter or awning | `io://1234-5678-9012/12345678` |
| `BlindDeviceUrl` | `deviceURL` of the io venetian blind | `io://1234-5678-9012/12345678` |
| `RtsDeviceUrl` | `deviceURL` of the RTS motor | `rts://1234-5678-9012/12345678` |

If you use the IP address, reserve it for the gateway in the router so that it does not change.

The template has one device of each kind. Delete the devices you do not need. For more motors, import the template again with the other addresses — each import adds a gateway module with its own devices — and delete the extra devices, or change the `DeviceUrl` variable of a device.

## Device capabilities

### Gateway

The module reads the gateway every 30 s and shows three service attributes: **Protocol Version** (the version of the local API), **Gateway ID** (the gateway PIN) and **Connectivity Status** (for example OK). When the token is wrong, the module shows the error "Check Bearer token in TaHoma By Somfy app → Developer Mode".

### io roller shutters and awnings

- **io Roller Shutter / Awning** — position of an io-homecontrol roller shutter or awning. The gateway reports 0 = fully open and 100 = fully closed; in TapHome 0 % is fully raised and 100 % fully lowered, the same direction. The device reads the position every 5 s and moves the motor with the command `setClosure`.

### io venetian blinds

- **io Venetian Blind** — position and slat angle of an io-homecontrol exterior venetian blind. Both are sent together in one command `setClosureAndOrientation`, so a change of position also sends the current slat angle and a change of the slats the current position. When TapHome changes position and slats at once, the identical command is sent only once.

### RTS motors

RTS (Radio Technology Somfy) motors are one-way radio: they receive commands but do not report their position.

| Value | Command | Action |
|---|---|---|
| Open | `open` | Move up / fully open |
| My | `my` | Go to the favourite position stored in the motor |
| Stop | `stop` | Stop the movement |
| Close | `close` | Move down / fully close |

- **RTS Motor** — after each command the switch shows **Ready**, so the same command can be sent again, for example Close after the motor was moved with its own remote. Choosing Ready sends Stop.

None of the devices moves a motor when the TapHome Core starts: they take their state from the gateway, not from the last value in TapHome.

### How the template talks to the gateway

All calls go to `https://<gateway-address>:8443/enduser-mobile-web/1/enduserAPI` with the header `Authorization: Bearer <token>`; only `GET /apiVersion` works without the token. Each io device reads its states from `/setup/devices/{deviceURL}/states` every 5 s, and all devices send commands with `POST /exec/apply`. Somfy sets no rate limit on the local API but warns that too frequent calls overload the gateway and delay the control of the motors — keep this in mind with many motors on one gateway.

## Troubleshooting

### Error "Check Bearer token in TaHoma By Somfy app → Developer Mode"

The gateway answered HTTP 401: the token is wrong or was not copied completely. Generate a new token in the TaHoma by Somfy app › Developer Mode and enter it in TapHome.

### Device error "Device unavailable (HTTP …)"

The gateway does not know the address. Check that the `deviceURL` is copied exactly from `GET /setup/devices` — not encoded, without spaces — and that it belongs to the right device type.

### Device error "Closure state not available"

The gateway answered, but without the state `core:ClosureState`. Check the `definition.states` of the motor. Some awnings report the state `core:DeploymentState` (0 = retracted, 100 = deployed) instead; the template does not read it.

### Device shown as unavailable in the gateway, but it works

Some TaHoma firmware reports io devices as unavailable (`available: false`) although they work normally — reported to Somfy in the Developer Mode repository. The template does not use this flag and shows no error because of it.

### RTS motor does not move

RTS commands are one-way radio signals without a delivery confirmation, so TapHome shows no error when the motor does not react. Check that the motor is in the radio range of the gateway and that it moves from the TaHoma by Somfy app.

### Gateway host name not reachable

If `gateway-{pin}.local` does not resolve, use the IP address of the gateway — it is in the router. Developer Mode has to stay on: it is what enables the local API of the gateway.

## Available devices

Somfy TaHoma Gateway Module

Service Attributes

|                     |                                                                                                    |
|---------------------|----------------------------------------------------------------------------------------------------|
| Protocol Version    | Version of the local API the gateway reports                                                       |
| Gateway ID          | PIN of the gateway (for example 1234-5678-9012), the same PIN that is part of every device address |
| Connectivity Status | Connectivity status the gateway reports, for example OK                                            |

Custom Variables

`BearerToken` (string) Token of the TaHoma local API, created in the TaHoma by Somfy app › Developer Mode; the module and every device send it as 'Authorization: Bearer &lt;token&gt;'

TaHoma by Somfy app → Configure the installation → Access the parameters of your TaHoma box → tap the gateway PIN 7 times → Developer Mode → generate a token. The token can be copied only when it is created; enter it as the import parameter Bearer token.

io Roller Shutter / Awning Slide

Position of an io-homecontrol roller shutter or awning — 0 % fully open, 100 % fully closed, the same direction as the gateway

numeric (0–100) Unit: % json\_path

Variable: `DeviceUrl` — Address of the motor in the TaHoma gateway (deviceURL from GET /setup/devices), for example io://1234-5678-9012/4820485

io Venetian Blind Blind

Position and slat angle of an io-homecontrol exterior venetian blind — both are sent together in one command

numeric (0–100) Unit: % json\_path

Variable: `DeviceUrl` — Address of the venetian blind in the TaHoma gateway (deviceURL), for example io://1234-5678-9012/5932104

RTS Motor Multi-value Switch

Commands for a one-way RTS motor — Open, My (favourite position), Stop or Close; RTS reports no position, so the switch shows Ready after each command

enum numeric

Values / States: Ready · Open · My · Stop · Close

Variable: `DeviceUrl` — Address of the RTS motor in the TaHoma gateway (deviceURL), for example rts://1234-5678-9012/987654321

**Connection:** Packet Parser → HTTP • Hostname: `gateway-{pin}.local.local`

Possible improvements (6)

- Event-driven state updates — Somfy recommends reading /setup at start and then fetching events at most once per second; the listener expires after 10 minutes without a fetch. The template polls the states of each device every 5 s instead.
- Automatic device discovery — The gateway lists every paired device with its deviceURL, label, controllableName and definition. The template does not create devices from it; the installer enters one deviceURL per device.
- Open / Close / Stop / My on io motors — io roller shutters and venetian blinds accept the same commands as RTS; the template drives them by position only (setClosure / setClosureAndOrientation).
- Awnings that report the deployment instead of the closure — Awnings of type io:HorizontalAwningIOComponent may report core:DeploymentState (0 = retracted, 100 = deployed) instead of core:ClosureState; the roller shutter device reads ClosureState only.
- Cancel running executions — Cancels all running commands launched from the local API.
- Availability of a motor — The device description carries available and the state core:StatusState; some gateway firmware reports io devices as unavailable although they work (reported in the Developer Mode repository), so the template does not use it.

## Sources

- Somfy TaHoma Developer Mode — README (activation, token, certificate, mDNS, supported gateways)
  
  [github.com](https://github.com/Somfy-Developer/Somfy-TaHoma-Developer-Mode) 2026-11-04
- Somfy TaHoma local API — OpenAPI specification
  
  [somfy-developer.github.io](https://somfy-developer.github.io/Somfy-TaHoma-Developer-Mode/) 2026-11-04

## Related Documentation

- [Packet Parser Integration](https://taphome.com/en/compatibility/packet-parser-guide/)
- [Packet Parser (HTTP, TCP, UDP, FTP, MQTT)](https://taphome.com/en/docs/integration/packet-parser/)
- [Packet parser functions](https://taphome.com/en/docs/script/packet-parser/)
- [Parsing functions](https://taphome.com/en/docs/script/parsing-functions/)