TapHome

Somfy TaHoma – io and RTS Blinds (Local API)

Packet Parser → HTTP
Submitted by
Last updated: 11. 2026

Requires external gateway

Somfy TaHoma with Developer Mode (local API, HTTPS port 8443) — product page

This device supports mDNS

Instead of using an IP address, you can reach the device at:

gateway-{pin}.local.local

Replace {MAC} with your device's MAC address (uppercase, no colons).

TapHome supports mDNS — using a hostname is more reliable than a static IP.

Somfy TaHoma – io and RTS Blinds (Local API)

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.

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, and import it as a new module.

Template · TapHome portal Community Beta · unverified
Somfy TaHoma — io and RTS shading motors (Developer Mode, local API)
By Martin Keller
HTTP View in TapHome portal

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. 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:

1

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.

ProtocolFormatExample
io-homecontrolio://{gateway-pin}/{device-id}io://1234-5678-9012/4820485
RTSrts://{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 parameterDescriptionPlaceholder
GatewayAddressIP address or host name of the TaHoma gateway, for example gateway-1234-5678-9012.local192.168.1.100
BearerTokenToken from Developer Mode(empty)
SlideDeviceUrldeviceURL of the io roller shutter or awningio://1234-5678-9012/12345678
BlindDeviceUrldeviceURL of the io venetian blindio://1234-5678-9012/12345678
RtsDeviceUrldeviceURL of the RTS motorrts://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.

ValueCommandAction
OpenopenMove up / fully open
MymyGo to the favourite position stored in the motor
StopstopStop the movement
ClosecloseMove 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 VersionVersion of the local API the gateway reports
Gateway IDPIN of the gateway (for example 1234-5678-9012), the same PIN that is part of every device address
Connectivity StatusConnectivity 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 <token>'
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.

Somfy TaHoma Gateway

Read (module)
VAR r := SENDHTTPREQUEST("/enduser-mobile-web/1/enduserAPI/apiVersion");
IF r.IsSuccess
    ApiVersion := r.Content;
END

r := SENDHTTPREQUEST("/enduser-mobile-web/1/enduserAPI/setup/gateways", "GET", "", "Authorization: Bearer " + BearerToken);
IF r.StatusCode = 401
    ADDERROR(0, "Check Bearer token in TaHoma By Somfy app → Developer Mode");
ELSEIF r.IsSuccess
    GatewayData := r.Content;
END
Service Attributes
Protocol Version
PARSEJSON(ApiVersion, "$.protocolVersion", true)
Gateway ID
PARSEJSON(GatewayData, "[0].gatewayId", true)
Connectivity Status
PARSEJSON(GatewayData, "[0].connectivity.status", true)
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 Roller Shutter / Awning

Read (module)
VAR encodedUrl := REPLACE(REPLACE(DeviceUrl, ":", "%3A"), "/", "%2F");
VAR r := SENDHTTPREQUEST("/enduser-mobile-web/1/enduserAPI/setup/devices/" + encodedUrl + "/states/core%3AClosureState", "GET", "", "Authorization: Bearer " + BearerToken);
IF r.StatusCode = 401
    ADDERROR(0, "Check Bearer token in TaHoma By Somfy app → Developer Mode");
ELSEIF r.IsSuccess
    StatesJson := r.Content;
ELSE
    ADDERROR(1, "Device unavailable (HTTP " + r.StatusCode + ")");
END
Read blind level
VAR closure := PARSEJSON(StatesJson, "$.value", true);
IF ISNULL(closure)
    ADDERROR(0, "Closure state not available");
    RETURN(NaN);
END
RETURN(closure / 100);
Write blind level
VAR pos := ROUND(Bl * 100);
VAR body := "{\"label\":\"Set roller shutter\",\"actions\":[{\"deviceURL\":\"" + DeviceUrl + "\",\"commands\":[{\"name\":\"setClosure\",\"parameters\":[" + pos + "]}]}]}";
SENDHTTPREQUEST("/enduser-mobile-web/1/enduserAPI/exec/apply", "POST", body, "Authorization: Bearer " + BearerToken, "Content-Type: application/json");
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

io Venetian Blind

Read (module)
VAR encodedUrl := REPLACE(REPLACE(DeviceUrl, ":", "%3A"), "/", "%2F");
VAR r := SENDHTTPREQUEST("/enduser-mobile-web/1/enduserAPI/setup/devices/" + encodedUrl + "/states", "GET", "", "Authorization: Bearer " + BearerToken);
IF r.StatusCode = 401
    ADDERROR(0, "Check Bearer token in TaHoma By Somfy app → Developer Mode");
ELSEIF r.IsSuccess
    StatesJson := r.Content;
ELSE
    ADDERROR(1, "Device unavailable (HTTP " + r.StatusCode + ")");
END
Read blind level
VAR closure := PARSEJSON(StatesJson, "$[?(@.name=='core:ClosureState')].value", true);
IF ISNULL(closure)
    ADDERROR(0, "Closure state not available");
    RETURN(NaN);
END
RETURN(closure / 100);
Write blind level
VAR pos := ROUND(Bl * 100);
VAR ori := ROUND(Bs * 100);
VAR body := "{\"label\":\"Set venetian blind\",\"actions\":[{\"deviceURL\":\"" + DeviceUrl + "\",\"commands\":[{\"name\":\"setClosureAndOrientation\",\"parameters\":[" + pos + "," + ori + "]}]}]}";
VAR date := NOW();
IF body != LastBody OR date.UNIXTIME - LastSentAt > 3
    SENDHTTPREQUEST("/enduser-mobile-web/1/enduserAPI/exec/apply", "POST", body, "Authorization: Bearer " + BearerToken, "Content-Type: application/json");
    LastBody := body;
    LastSentAt := date.UNIXTIME;
END
Read blind slope
VAR orientation := PARSEJSON(StatesJson, "$[?(@.name=='core:SlateOrientationState')].value", true);
IF ISNULL(orientation)
    RETURN(NaN);
END
RETURN(orientation / 100);
Write blind slope
VAR pos := ROUND(Bl * 100);
VAR ori := ROUND(Bs * 100);
VAR body := "{\"label\":\"Set venetian blind\",\"actions\":[{\"deviceURL\":\"" + DeviceUrl + "\",\"commands\":[{\"name\":\"setClosureAndOrientation\",\"parameters\":[" + pos + "," + ori + "]}]}]}";
VAR date := NOW();
IF body != LastBody OR date.UNIXTIME - LastSentAt > 3
    SENDHTTPREQUEST("/enduser-mobile-web/1/enduserAPI/exec/apply", "POST", body, "Authorization: Bearer " + BearerToken, "Content-Type: application/json");
    LastBody := body;
    LastSentAt := date.UNIXTIME;
END
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

RTS Motor

Read switch state
RETURN(0);
Write switch state
VAR cmd := SWITCH(Mu, 1, "open", 2, "my", 3, "stop", 4, "close", "stop");
VAR body := "{\"label\":\"RTS command\",\"actions\":[{\"deviceURL\":\"" + DeviceUrl + "\",\"commands\":[{\"name\":\"" + cmd + "\",\"parameters\":[]}]}]}";
SENDHTTPREQUEST("/enduser-mobile-web/1/enduserAPI/exec/apply", "POST", body, "Authorization: Bearer " + BearerToken, "Content-Type: application/json");
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 2026-11-04
  • Somfy TaHoma local API — OpenAPI specification
    somfy-developer.github.io 2026-11-04

Found a problem with this device template?

Tell us what's wrong, what's missing, or how the template should behave. We rely on your feedback to keep the catalog accurate.

Community — unreviewed

Want to use this in your TapHome Core?

Open this template in the Customer Portal to apply it to one of your homes, or to draft a refinement and submit it back to the catalog.

Open in portal