Somfy TaHoma (Cloud)

The Somfy TaHoma (Cloud) driver controls Somfy shades, blinds, awnings, and gates through the Overkiz cloud — the same service behind the TaHoma, Connexoon, and Cozytouch apps. GEM signs in with your Somfy account email and password, reads the list of devices paired to your hub, and sends open / close / stop / favorite commands over the internet. One Somfy account becomes one GEM device, and each motorized covering paired to the hub becomes its own GEM zone.

Because control travels through the Somfy cloud, this path needs a working internet connection and adds a second or two of round-trip lag; it keeps functioning even when GEM and the hub are on different networks. Somfy also ships a LAN-only integration that talks to the hub directly — that is a different driver, Somfy TaHoma (Local API), which is the preferred choice for a commissioned install when the hub supports Developer Mode. This page covers the cloud path only.

Prefer the local driver where you can

If the hub is on the same LAN as GEM and supports Developer Mode, use Somfy TaHoma (Local API) instead — it is faster, survives internet outages, and reports each covering's open/closed state back to GEM. Use this cloud driver when the hub isn't reachable on the LAN, doesn't offer Developer Mode, or you can't mint a local token.

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 working Somfy cloud account. Confirm the same email and password sign in to the Somfy (TaHoma / Connexoon) mobile app before entering them in GEM.
Pair your coverings in the Somfy app first. GEM only controls devices the hub already knows about; it does not pair new io-homecontrol or RTS motors.
Internet access from the GEM controller to the Overkiz cloud. There is no local API in this driver — if the site's internet is down, the shades won't respond.
Know your region's Overkiz server. North American accounts use the default host; European accounts often need a different one (see Setup).

Setup — adding the account

Open Devices, add a device, and choose the Somfy TaHoma (Cloud) driver.
Set Somfy Account Email to the email you use to sign in to the Somfy app.
Set Somfy Account Password to that account's password. It is stored encrypted.
If your account is not on the North American server, set Overkiz Host to your region's Overkiz API host. The default is ha401-1.overkiz.com (North America); European accounts commonly need ha101-1.overkiz.com. Leave it blank to use the default.
Save and enable the device. On connect, GEM signs in to the Overkiz cloud and reads your account's device list to confirm the credentials work; the device shows connected once that succeeds.

Account-wide credentials

The email and password are your whole Somfy account — the same login the mobile app uses. GEM stores the password encrypted, but treat it like any shared account credential. Changing the Somfy account password later means you must update Somfy Account Password here too, or the device stops connecting.

Finding each covering's address

In the cloud driver a covering is identified by its name — the label you gave it in the Somfy app (for example Living Room Shade). You need that exact name to create the zone.

With the device connected, open its Commands tab and run get_devices (it takes no arguments).
GEM returns the account's device list, keyed by each device's name. Find the covering you want and copy its name exactly as shown.

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

Name, not deviceURL

This is the one place the cloud driver differs from the local driver: the local driver addresses coverings by their deviceURL (e.g. io://0000-0000-0000/12345678), while this cloud driver addresses them by name. Use the name from get_devices here.

Mapping coverings to zones

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

Open Zones and add a zone.
Set its Subsystem to Shades. GEM does not pre-select this for you, so choose it explicitly. (Awnings, exterior screens, and gates driven from Somfy also live here unless you keep a dedicated subsystem for them.)
Set the zone's controlling Device to the Somfy account device you just added.
Paste the covering's name (from get_devices) into the Address field, matching it exactly — including capitalization and spaces.
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 presents Open / Stop / Close buttons rather than a position slider — those buttons send the open, stop, and close commands.
Save. Repeat for each covering.

Cloud connection and polling

GEM holds a live session to the Overkiz cloud for the account. Two device attributes tune how often it refreshes from the cloud:

Polling Interval (ms) (polling_interval, default 2000, minimum 500) — how often the driver refreshes device state from Overkiz when polling is active.
Always Poll (always_poll, default off) — when on, the driver polls continuously; when off, it only refreshes around the commands it sends.

Cloud control is open-loop

Unlike the local driver, this cloud driver sends commands but does not write a live open/closed reading back onto the zone. It has no state attribute, so the shade tile shows the Open / Stop / Close buttons but does not light up an "active" state based on the covering's real position, and you can't drive an attribute trigger from a cloud shade's position. If you need GEM to react to a covering's open/closed state, use the local driver, which reports it. Commands you send still take effect on the covering itself — GEM simply doesn't track the resulting position over the cloud.

Attributes

Device — required

Attribute	Type	Description
`username`	string	The email used to sign in to the Somfy TaHoma / Connexoon app. Shown as Somfy Account Email.
`password`	string	That account's password. Shown as Somfy Account Password. Stored encrypted.

Device — optional

Attribute	Type	Default	Description
`overkiz_host`	string	`ha401-1.overkiz.com`	Regional Overkiz API host. Shown as Overkiz Host. The default is the North American server; European accounts commonly need `ha101-1.overkiz.com`.
`polling_interval`	int	2000	How often (ms) the driver refreshes device state from Overkiz when polling is active. Shown as Polling Interval (ms). Minimum 500.
`always_poll`	bool	false	When on, poll the cloud continuously; when off, only refresh around commands. Shown as Always Poll.

Zone

Attribute	Type	Description
`address`	string	Required. The Somfy device name for this covering, copied exactly from `get_devices`.

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 device name) from the zone you pick, so you don't type it in normal use; from the Commands screen you'd provide the name 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 account, keyed by name. A device-level diagnostic — it needs no zone and works as soon as the account 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

Cloud dependency. All control travels through the Somfy/Overkiz cloud. If the site's internet or the Overkiz service is down, the shades won't respond. Where the hub supports it, the local driver avoids this.
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.
No position feedback. The cloud driver does not report a covering's open/closed state back to GEM, so the shade tile won't reflect live position and cloud shades can't drive state-based attribute triggers (see Cloud connection and polling).
Account credentials, not a scoped token. Sign-in uses the full Somfy account email and password. Changing that account's password requires updating it here as well.

Troubleshooting

Symptom	Check
Device won't connect	Verify Somfy Account Email and Somfy Account Password sign in to the Somfy mobile app. If your account isn't on the North American server, set Overkiz Host to your region's host (European accounts often need `ha101-1.overkiz.com`).
`get_devices` returns an empty list	Make sure at least one covering is paired with the hub in the Somfy app and is visible there. GEM only sees devices the account already controls.
A covering doesn't respond to Open/Close/Stop	Confirm the zone's Address matches the covering's name from `get_devices` exactly — capitalization and spaces included — and that the zone's controlling device is the Somfy account device.
Shades respond, but slowly	Cloud round-trips add a second or two of lag; this is expected. For LAN-speed response, use the local driver where the hub supports it.
Stopped working after a password change	The Somfy account password changed. Update Somfy Account Password on the device to the new value.

What's controlled​

Prerequisites​

Setup — adding the account​

Finding each covering's address​

Mapping coverings to zones​

Cloud connection and polling​

Attributes​

Device — required​

Device — optional​

Zone​

Commands​

Known limitations​

Troubleshooting​

See also​