Overkiz

The Overkiz (by Somfy) IoT platform is used by many different vendors, like Somfy, Hitachi, and Atlantic. This integration will allow users to integrate their devices into Home Assistant using the Overkiz API.

Supported vendors

• Atlantic Cozytouch
• Bouygues Flexom
• Hexaom HexaConnect
• Hitachi Hi Kumo
• Nexity Eugénie
• Rexel Energeasy Connect
• Sauter Cozytouch
• Simu LiveIn2
• Somfy TaHoma
• Thermor Cozytouch
• Ubiwizz

Over 6000 devices from 60 brands are compatible with the Overkiz platform. This integration will retrieve your devices and map them to the relevant Home Assistant platforms.

Local API support

Local API availability depends on your specific gateway. The following gateways support the local API:

• Somfy Connexoon IO
• Somfy Connexoon RTS
• Somfy TaHoma v2
• Somfy TaHoma Beecon
• Somfy TaHoma Switch
• Rexel Energeasy Connect Rail Din
• Rexel Energeasy Connect V2
• Rexel Energeasy Connect V3
• Rexel Energeasy Connect V3 Rail Din

Configuration

To add the Overkiz hub to your Home Assistant instance, use this My button:

Overkiz can be auto-discovered by Home Assistant. If an instance was found, it will be shown as Discovered. You can then set it up right away.

The Overkiz integration supports both the Overkiz cloud API and the local API (only supported by some gateways). With a compatible gateway, you can connect locally, allowing device control without an internet connection. Start by selecting the server or app that you use to control your devices.

Log in to Overkiz (Cloud API)

Log in to Rexel Energeasy Connect (Cloud API)

If you select Rexel Energeasy Connect as your server, you sign in through your browser instead of entering a username and password in Home Assistant.

1. After selecting Rexel Energeasy Connect, you are taken to the Rexel sign-in page.
2. Sign in with the account you use in the Energeasy Connect app, and authorize Home Assistant.
3. If your account has more than one gateway, select the gateway you want to add.

Log in to Overkiz (Local API)

To connect Home Assistant to your gateway using the local API, you need a compatible gateway and a token. How you generate this token depends on your gateway.

Scenarios and climate entities are not supported via the local API.

List of actions

The Overkiz integrationIntegrations connect and integrate Home Assistant with your devices, services, and more. [Learn more] provides the following actions. Each link below opens a dedicated page with examples, parameters, and a step-by-step UI walkthrough.

• Set cover position and tilt (overkiz.set_cover_position_and_tilt) Move a cover to a target position and tilt at the same time, keeping the motor running smoothly through the move.

For an overview of every action across all integrations, see the actions reference.

Data updates

How often this integration retrieves data depends on how you connect:

• When connected through the local API, it polls every 5 seconds.
• When connected through the cloud API, it polls every 30 seconds.
• When connected through the cloud API and you only have stateless devices (such as RTS), it polls every hour to reduce unnecessary load on the Overkiz API.

Known limitations

Unsupported hardware

Some devices that appear in your vendor app may not use the Overkiz platform and are not accessible through the Overkiz API. For example, Somfy Protect devices and some Atlantic Cozytouch devices are not supported by this integration.

If you have a Cozytouch device that is not supported by the Overkiz integration, you can explore custom components created by the community. These may provide support for additional Cozytouch devices.

Zigbee, Z-Wave, Hue, and Sonos devices are not supported

Even though most Overkiz gateways support adding Zigbee, Z-Wave, Hue, and Sonos devices, this isn’t supported in the Overkiz integration. All these platforms have native integrations in Home Assistant, which provide more frequent state updates and are more feature-rich.

Stateless RTS covers

RTS covers do not report their state back to the gateway, so Home Assistant cannot track their state after they are controlled. If you only control your RTS cover from Home Assistant, you can use the template cover to create a stateful cover entity. This will help you track the current state (open or closed) and use the cover in automations and scenes.

cover:
 - platform: template
 covers:
 stateful_rts_test_shutter: # unique ID
 friendly_name: "StatefulRTSTestShutter" # your name
 optimistic: true # default when no state is available
 open_cover:
 - action: cover.open_cover
 target:
 entity_id: cover.rts_test_shutter # change to your device id
 close_cover:
 - action: cover.close_cover
 target:
 entity_id: cover.rts_test_shutter # change to your device id
 stop_cover:
 - action: cover.stop_cover
 target:
 entity_id: cover.rts_test_shutter # change to your device id

Scenes and automations that set both position and tilt

If a scene or automation sets both the position and the tilt of a cover, Home Assistant sends these as two separate actions: Set cover position followed by Set cover tilt position. On Somfy venetian blinds and similar IO motors, the second command interrupts the first while it’s still moving, so the cover only makes a short stuttering move instead of reaching the target position and tilt.

To move a cover to a target position and tilt in one smooth motion, use the Set cover position and tilt action instead.

Troubleshooting connection issues with the local API

If your entities frequently become unavailable for short periods, this usually indicates connection problems between Home Assistant and your gateway. To improve reliability, try connecting to your gateway using its IP address instead of the gateway-xxxx-xxxx-xxx.local hostname.

Overkiz API limits

Device state changes are not broadcasted for all devices

Some Overkiz devices do not broadcast status changes. To update their status, the vendor’s app (for example, Somfy TaHoma) requests a status update when opened. The app then broadcasts the states via events that the Overkiz integration also listens to. The Overkiz integration cannot replicate this behavior, as it does not know when you access the Home Assistant dashboard or run automations.

As a result, the state of some Overkiz devices in Home Assistant may not always be up-to-date.

Server busy, please try again later. (Too many executions)

During peak hours, it could happen that the Overkiz platform is unable to execute your command. The integration will try to retry this command, however, this is not guaranteed to succeed.

Execution queue is full on gateway

The Overkiz API only supports 10 requests in its execution queue. If you try to command more devices at the same time, for example with a group, this will fail with EXEC_QUEUE_FULL. To work around this, you can create a scenario in the corresponding application and call that scenario instead after syncing it in the integration.

Device support via the local API

Various sensors, scenarios, and climate entities are not supported via the Somfy TaHoma Developer Mode due to limitations of the local API. If your device functions with the Cloud API but not with the Local API, this is an inherent limitation of the Local API and cannot be resolved.

Device support via HomeKit

If your gateway (e.g. Somfy Connectivity Kit) supports HomeKit, a sensor named HomeKit Setup Code will be added to Home Assistant. To configure the HomeKit Controller integration for local control, follow these steps:

1. Locate the HomeKit Setup Code sensor in Home Assistant.
2. Retrieve the setup code value from the sensor.
3. Use this setup code to configure the HomeKit Controller integration in Home Assistant.

Only a limited set of devices is supported via HomeKit.

Removing the integration

This integration follows standard integration removal. No extra steps are required.

To remove an integration instance from Home Assistant

1. Go to Settings > Devices & services and select the integration card.
2. From the list of devices, select the integration instance you want to remove.
3. Next to the entry, select the three dots menu. Then, select Delete.