Somfy TaHoma and Overkiz Gateway Setup

The Somfy TaHoma Switch runs on the Overkiz platform, like older Somfy hubs and several other vendors’ gateways. Home Assistant connects to the gateway through the built-in Overkiz integration, and the supported motors and sensors paired to the gateway appear in Home Assistant. Motors are never paired to Home Assistant directly.

Current Somfy hubs support a local API, which works without the cloud and updates every 5 seconds instead of every 30. Use it whenever the gateway supports it.

Step 1: Pair the Devices to the Gateway

Set up the hub and pair each motor, remote, and sensor in the TaHoma by Somfy app. Name the devices and assign rooms there, since Home Assistant picks up those names. Devices paired later appear in Home Assistant on their own.

The North American TaHoma Switch pairs RTS motors, such as the Altus 40 RTS, Sonesse 30 WireFree RTS, and Glydea Ultra 60 RTS, and Somfy Zigbee motors. RTS motors do not report their position: see RTS Motors Have No State . Choose Somfy Zigbee motors where a shade’s position has to be known.

In Europe

The European TaHoma Switch adds io-homecontrol, Somfy’s two-way radio, which is not sold in North America. io-homecontrol motors, such as the Sonesse 40 io and Oximo io, report their position. Rexel Energeasy Connect gateways, sold in France, run on Overkiz too and are set up in the Energeasy Connect app.

Step 2: Generate a Local API Token

The local API is available on the Somfy TaHoma Switch, TaHoma v2, TaHoma Beecon, Connexoon io, and Connexoon RTS, and on the Rexel Energeasy Connect V2, V3, Rail Din, and V3 Rail Din.

Somfy TaHoma and Connexoon:

1. In the TaHoma by Somfy app, go to Account > Configure the installation > Access the parameters of your TaHoma box.
2. Tap the gateway PIN (it looks like 1234-5678-9012) seven times to turn on Developer Mode.
3. Generate a token and copy it.

Rexel Energeasy Connect:

1. In the Energeasy Connect app, go to Settings > My home > Maintenance.
2. Select the gateway, then Local API, and generate a token.

Note the gateway PIN as well: it makes up the gateway’s hostname in the next step.

Step 3: Add the Gateway to Home Assistant

1. Go to Settings > Devices & Services. The gateway usually appears under Discovered as Overkiz. Select Add. If it is not there, select Add Integration and search for Overkiz.
2. Choose the server: Somfy or Rexel Energeasy Connect.
3. Choose Local API.
4. Enter the host and the token:
   • Host: gateway-<PIN>.local:8443, for example gateway-1234-5678-9012.local:8443, or the gateway’s IP address followed by :8443.
   • Token: the token from Step 2.
   • Verify SSL: leave it on with the hostname. Turn it off when you enter an IP address.
5. Assign each device to an area.

Reserve the gateway’s IP address in the router. If entities often become unavailable over the .local hostname, switch the host to the IP address: open the Overkiz entry, select Reconfigure from its menu (⋮), and change it.

Over the Cloud Instead

Choose Cloud API for a gateway without a local API, or for what the local API does not provide, including scenarios created in the vendor app, climate entities, and some sensors. Somfy and most vendors sign in with the app’s account. Rexel opens a browser sign-in instead.

Other Overkiz vendors, such as Atlantic, Sauter, and Thermor Cozytouch, Hitachi Hi Kumo, Simu LiveIn2, Nexity Eugénie, and Flexom, are cloud only: choose the vendor as the server and sign in with the app’s account.

RTS Motors Have No State

RTS is one-way. Home Assistant can send an RTS motor up, down, or to its favorite (my) position, but never learns where it stopped, and a move from a wall remote is not reported at all. RTS covers show an unknown state in Home Assistant.

When an automation needs a state for an RTS cover, wrap it in a template cover in optimistic mode, which assumes the cover is where it was last sent. On a new install, specify Somfy Zigbee motors instead, or io-homecontrol motors in Europe.

Scenes That Move Many Covers

• Position and tilt together: on a venetian blind, setting the position and then the tilt sends two commands, and the second stops the first. Use the overkiz.set_cover_position_and_tilt action to send both at once.
• Whole-house scenes: the gateway queues about 10 requests. Home Assistant groups commands sent close together into one request, but a scene that moves every cover at once can still fail with EXEC_QUEUE_FULL. Stagger large scenes, or create the scene in the vendor app and run it over the cloud API.

What the Gateway Does Not Pass to Home Assistant

Somfy’s own Zigbee motors and blinds come through, but other Zigbee devices, Z-Wave devices, Philips Hue, and Sonos paired to the gateway are not supported, even though the vendor app controls them. Pair them to Home Assistant’s own integrations instead.

Troubleshooting

1. The gateway is not discovered. Discovery uses mDNS, which does not cross VLANs on its own. Add the integration manually and enter the gateway’s IP address.
2. Setup fails with an invalid authentication error. On a Somfy gateway, check that Developer Mode is on (Step 2), then generate a new token and paste it again.
3. “Too many attempts with an invalid token”. The gateway temporarily blocks Home Assistant after repeated bad tokens. Wait, then retry with a newly generated token.
4. A motor does not respond. Check that it works from the vendor app first. If it does not, the problem is the radio range or the pairing, not Home Assistant.