Somfy TaHoma (Local API)

The Somfy TaHoma (Local API) driver controls Somfy TaHoma and Connexoon gateways directly over your local network — no Somfy cloud account round-trip during normal operation. GEM talks to the gateway's on-LAN Local Developer API using a long-lived bearer token you mint once from the Somfy site. One gateway becomes one GEM device, and each motorized covering paired to that gateway — roller shades, blinds, awnings — becomes its own GEM zone.

Because it runs on the LAN, response is fast and the integration keeps working when the internet is down, provided GEM and the gateway are on the same network. (Somfy also ships a separate cloud-based TaHoma integration; that is a different driver. This page covers the local-API path only, which is the preferred choice for a commissioned install.)

What's controlled

Each Somfy covering you create a zone for gets the four motorized-covering actions:

• Open — fully open / raise the covering.
• Close — fully close / lower the covering.
• Stop — halt a covering that's in motion.
• My (favorite) — send the covering to its Somfy "my" preset position.

This driver does not drive coverings to an arbitrary percentage — there is no position (0–100 %) command, even though some Somfy coverings support it. Control is open / close / stop / favorite only. See Known limitations.

Prerequisites

• A Somfy TaHoma or Connexoon gateway on the same LAN as GEM, reachable by IP. Give it a DHCP reservation so its address never moves — a moved address means GEM can no longer reach the gateway.
• Pair your coverings in the Somfy (TaHoma) app first. GEM only controls devices the gateway already knows about; it does not pair new io-homecontrol or RTS motors.
• Developer Mode enabled on the gateway and a local API token generated for it. You activate Developer Mode and mint the token from Somfy's developer dashboard (developer.somfy.com) for that specific gateway. The token is what GEM authenticates with — keep it; you'll paste it into the device.

note

The Local Developer API is only available on compatible io-homecontrol TaHoma / Connexoon gateways with Developer Mode turned on. If the gateway doesn't offer Developer Mode, the local token path isn't available for it.

Setup — adding the gateway

1. Open Devices, add a device, and choose the Somfy TaHoma (Local API) driver.
2. Set TaHoma IP Address to the gateway's LAN IP.
3. Paste the token you generated into Local API Token. It is stored encrypted.
4. Leave HTTPS Port at 8443 unless you've remapped it. The driver connects over HTTPS and accepts the gateway's self-signed certificate, so no certificate setup is required.
5. Save and enable the device. On connect, GEM reads the gateway's device list to confirm the token works; the device shows connected once that succeeds.

If the device won't connect, the most common causes are a wrong or expired token, a changed gateway IP, or Developer Mode having been switched off on the gateway — see Troubleshooting.

Finding each covering's address

Every Somfy device on the gateway is identified by a deviceURL — for an io-homecontrol roller shade it looks like io://0000-0000-0000/12345678. You need that string to create the zone.

1. With the device connected, open its Commands tab and run get_devices (it takes no arguments).
2. GEM returns the gateway's full device list. Each entry has a deviceURL and a label (the name you gave the covering in the Somfy app). Match the label to the covering you want and copy its deviceURL.

You'll paste that deviceURL into the zone's Address field in the next step.

Mapping coverings to zones

Zones are not created automatically — you add one zone per covering by hand:

1. Open Zones and add a zone.
2. Set its Subsystem to Shades. GEM does not pre-select this for you, so choose it explicitly. (Awnings and exterior screens also belong here unless you keep a dedicated subsystem for them.)
3. Set the zone's controlling Device to the TaHoma gateway you just added.
4. Paste the covering's deviceURL (from get_devices) into the Address field.
5. For the UI control widget, pick the manual shade control (Open / Stop / Close). Because this driver exposes no position command, the built-in shade control automatically presents Open / Stop / Close buttons rather than a position slider — those buttons send the open, stop, and close commands. The control highlights Open when the zone reports open and Close when it reports closed.
6. Save. Repeat for each covering.

Keeping state current

GEM polls each shade zone's state on a loop. For every zone it reads the gateway's closure reading and writes the zone's state attribute: a zero reading reports closed, and any non-zero reading reports open. The poll walks the zones one at a time with about a one-second gap between them, then waits the Status Poll Interval before starting the next sweep (default 3000 ms / 3 seconds). With many coverings the time to refresh them all grows with the count, since they're read sequentially.

Verify the open/close indication during commissioning

The reported state is a coarse open-or-closed reading derived from the covering's closure value, not a measured position — so a partially-open covering reports as open. Watch the shade control while you Open and Close each covering and confirm the Open / Close highlight matches the physical shade. If the indication reads reversed on a particular covering, you can flip it for that zone in the Attribute editor by setting the zone's open_state attribute to closed and close_state to open; the command buttons are unaffected, only which state lights up as active.

Attributes

Device — required

Attribute	Type	Description
ip	string	The TaHoma / Connexoon gateway's LAN IP address. Shown as TaHoma IP Address.
token	string	The gateway's local API bearer token, generated from Somfy's developer dashboard. Shown as Local API Token. Stored encrypted.

Device — optional

Attribute	Type	Default	Description
port	int	8443	HTTPS port of the gateway's local API. Shown as HTTPS Port. Range 1–65535.
status_interval	int	3000	How often (ms) GEM starts a fresh sweep of all shade zones' state. Not shown on the form by default; add it as an attribute on the device if you want to slow the polling down.

Zone

Attribute	Type	Description
address	string	Required. The Somfy deviceURL for this covering (e.g. io://0000-0000-0000/12345678), copied from get_devices.
state	string	Read-back from the gateway: open or closed. GEM sets this on each poll — you don't enter it. It's cataloged, so it autocompletes in the Attribute editor and can drive attribute triggers (for example, run a macro when a shade's state becomes closed).

Commands

Driver-declared commands appear on the device's Commands tab and can be used in macros, triggers, and on UI buttons. The four covering commands act on a specific zone — GEM supplies the zone's address (the deviceURL) from the zone you pick, so you don't type it in normal use; from the Commands screen you'd provide the deviceURL as the address argument.

Command	Arg	Action
open	address	Fully open / raise the covering.
close	address	Fully close / lower the covering.
stop	address	Stop a covering that's moving.
my	address	Send the covering to its Somfy "my" favorite position.
get_devices	—	List every Somfy device on the gateway, with each one's deviceURL and label. A device-level diagnostic — it needs no zone and works as soon as the gateway is connected.

Using the "my" favorite position

The built-in shade control surfaces only Open, Stop, and Close, so there's no "favorite" button on the standard tile. To use a covering's Somfy my preset, send the my command from a macro, a scene, a custom UI button, or the device's Commands tab.

Known limitations

• No set-to-position control. This driver offers open / close / stop / favorite only. If a covering supports intermediate positions, GEM can reach them only through the my preset, not by commanding a specific percentage.
• State is open-or-closed, not a position. GEM reports a coarse open / closed value derived from the gateway's closure reading; a partially-open covering reads as open. Confirm the indication during commissioning (see the tip under Keeping state current).
• Local API and Developer Mode are prerequisites. If Developer Mode is turned off on the gateway, or the minted token is revoked or expires, GEM can no longer authenticate and the device disconnects until you supply a working token.

Troubleshooting

Symptom	Check
Device won't connect	Confirm TaHoma IP Address is correct and reachable on the LAN, the HTTPS Port is 8443 (or your remapped value), and the Local API Token is the one minted for this gateway. A reservation prevents the IP from drifting.
Connected, but get_devices returns nothing / an auth error	The token is wrong, revoked, or expired, or Developer Mode has been turned off on the gateway. Re-enable Developer Mode and mint a fresh token on Somfy's developer dashboard, then paste it into Local API Token.
A covering doesn't respond to Open/Close/Stop	Verify the zone's Address exactly matches the deviceURL from get_devices, and that the zone's controlling device is the TaHoma gateway. A covering not paired in the Somfy app won't appear in get_devices and can't be controlled.
Open/Close highlight looks reversed	The closure reading reads inverted for that covering. Flip it on the zone via the open_state / close_state attributes as described under Keeping state current.
State updates feel slow with many shades	Coverings are polled one at a time with a short gap between each, so a full refresh scales with the shade count. This is expected; commands you send still update that one covering's state right away.

See also

• Devices — adding and configuring devices.
• Zones — how zones map coverings to controls and subsystems.
• Subsystems — what the Shades subsystem is.
• Commands — running and scripting device commands.
• Macros and Triggers — automating shades and reacting to their state.