Overkiz API and Somfy API

Want to help test the local API?

There are still many things that need to be polished for the local API, however it would be good to already run some user tests. Best way to deliver feedback is on our Discord.

If you have developer experience, you can try to check out and run Add local API support to Overkiz integration (Somfy TaHoma Developer Mode) by iMicknl · Pull Request #71644 · home-assistant/core (github.com).

Otherwise, you can follow the next steps:

  1. Follow the installation steps for this custom component:
    alandtse/pr_custom_component: Create a custom component from a Home Assistant Integration Pull Request. Use this when you want to test a pull request that changes a built in integration. (github.com)

  2. When you are done, provide the following URL https://github.com/home-assistant/core/pull/71644 and follow the steps of the documentation above.

Now you should have our alpha version to test. Please don’t test it on your production instance, since there can be still bugs / breaking changes.


I will test the alpha version this week on my Tahoma Switch.

I just needs some parts for my test RaspBerry Pi 4 and then I will share my results.

I have the connectivity kit with RTS covers. However, I’m unable to move them to ‘my position’. After reading through this thread, I’m a little bit unsure, if this is actually supported by the overkiz API or not!?

got it installed, but how can we tell this is using the local API?

and another thing… I’m using this on a test instance, doesnt it interfere with the production system running the core integration (over Cloud)?

this is proof?

  "zeroconf": [
      "type": "_kizbox._tcp.local.",
      "name": "gateway*"
      "type": "_kizboxdev._tcp.local.",
      "name": "gateway*"

install went faultless and all devices show in a blink of an eye :wink:

operation just works…

core HA over Somfy Cloud:

and now via Local api:

How have you installed it? I have tried the PR Custom component but it didn’t work for me.

locap api somfy

1 Like

I dl the linked repo (so the whole HA fork by Imick) by clicking the Green Code button (select zip) and selected the Overkiz component in that. Copy that as complete folder into your custom_components folder. Then add a “version” key in the manifest file and restart HA.

  "domain": "overkiz",
  "name": "Overkiz (by Somfy)",
  "version": "0.0.1",
  "config_flow": true,
etc etc

It will show your newly added integrations in the discovery.

Now, first allow the developers api in your Somfy device, by logging in at Somfy on your device and click allow.

then configure the integration using the config flow, and be sure to scroll down all the way to:

(I did not do that correctly above, so that is still a cloud install :wink: You can see it in the Connected to: field., where it should list your local device id key )

Next screen wil bring you to your credentials I which your enter your own key replacing the xxx’s, user and pw.

and you’re set


Hey I have a Qbus installed with 3 somfy motors.
It looks like this

what I marked “3” in above picture is my cover.seitenmarkise below.
The state seems reversed. So in below screenshot it is actually NOT deployed which would be “closed” to me? At least the others ( 1 and 2 from above) do show CLOSED when NOT deployed.

However despite it seems inverted! The default UI card does correctly show me the arrows for down and up ! In this example it is again NOT deployed … so the arrow DOWN is just fine! But the state is despite that Closed / current position 100.

I can live with it but thought it might be interesting as it is not the same experience for the 3 different types.


From Somfy recommandation, we map open to deploy and close to undeploy for Awning devices. It’s the case for your Absenkmarkise and Hauptmarkise. But your Seitenmarkise is not reported as an Awning, it’s why you see a reverse state. FYI the same kind of motor can be used for a classic cover where this state is logic.

To solve your issue, you can create a Cover Template

  - platform: template
        friendly_name: "Seiten Markise
        value_template: "{{ states('cover.seitenmarkise') }}"
          service: cover.open_cover
          service: cover.close_cover

thank you for the explanation and I understand the logic of the non awning is coming from core then.

Template Covers are also problematic as the issue here is that value_template and position_template cannot been set concurrently in a template cover, so HA assumed the cover is open, when position is 100 and cover is closed when position is 0.

So I would need to use the orignal and template entity both to have a full working solution.

Edit: btw … I understand and support the Somfy logic. I think also for “other” covers many people would like to have 0 = closed = undeployed and 100 = open = deployed …
unfortunately core has no option to actually invert this.

demand is popular:


Both values can be set into the templates. There is only one warning:

If both a value_template and a position_template are specified, only opening and closing are set from the value_template .

If fact, even only position template should be enough in your case:

position_template: '{{ 100 - state_attr("cover.front", "current_position") }}'

Can you post your diagnostics information here? (or on GitHub gist and link it here). It would be interesting to see the device types, since we are revamping the cover entity.

sure I can.
also for other covers?
I have a different types for zwave covers on rollershutter and venetian blinds or just the somfy ones?

hey and when revamping the cover entity … maybe also consider that many actuators actually report 1-3 % off … means when they fully open or close the motor itself might stop the motor a moment earlier than the actuator was calibrated which result in something like this:

those are fully open - yet the actuator reports back 98 or 99% …
also here people create workarounds as it seems a more common issue - like here:

Just the Somfy ones, there is a download diagnostics button in Home Assistant.

Do you have this issue with the Somfy covers? We will only rewrite the Somfy cover implementation. And even there, I am not in favor of this change. If this is an issue with a certain vendor / platform, they either need to fix this or the Home Assistant integration needs to handle this margin / offset.


Since (i think) the last home assistant core update i have setting up entry error :

  • Logger: homeassistant.config_entries
    *Source: components/overkiz/init.py:61 *
    *First occurred: 13:46:36 (1 occurrences) *
    Last logged: 13:46:36

Error setting up entry [email protected] for overkiz
Traceback (most recent call last):

  • File “/usr/src/homeassistant/homeassistant/config_entries.py”, line 353, in async_setup*
  • result = await component.async_setup_entry(hass, self)*
  • File “/usr/src/homeassistant/homeassistant/components/overkiz/init.py”, line 61, in async_setup_entry*
  • setup, scenarios = await asyncio.gather(*
  • File “/usr/local/lib/python3.10/site-packages/backoff/_async.py”, line 133, in retry*
  • ret = await target(*args, *kwargs)
  • File “/usr/local/lib/python3.10/site-packages/pyoverkiz/client.py”, line 388, in get_setup*
  • setup = Setup(*humps.decamelize(response))
  • File “/usr/local/lib/python3.10/site-packages/pyoverkiz/models.py”, line 63, in init*
  • self.devices = [Device(*d) for d in devices]
  • File “/usr/local/lib/python3.10/site-packages/pyoverkiz/models.py”, line 63, in *
  • self.devices = [Device(*d) for d in devices]
    TypeError: Device.init() missing 1 required keyword-only argument: ‘device_url’

I have deleted/installed the overkiz integration and restarted ha but without success.

Thanks for your help.

## System Health

version | core-2022.7.3
-- | --
installation_type | Home Assistant OS
dev | false
hassio | true
docker | true
user | root
virtualenv | false
python_version | 3.10.5
os_name | Linux
os_version | 5.15.32-v8
arch | aarch64
timezone | Europe/Oslo
config_dir | /config

<details><summary>Home Assistant Community Store</summary>

GitHub API | ok
-- | --
GitHub Content | ok
GitHub Web | ok
GitHub API Calls Remaining | 4867
Installed Version | 1.26.0
Stage | running
Available Repositories | 1074
Downloaded Repositories | 11


<details><summary>Home Assistant Cloud</summary>

logged_in | false
-- | --
can_reach_cert_server | ok
can_reach_cloud_auth | ok
can_reach_cloud | ok


<details><summary>Home Assistant Supervisor</summary>

host_os | Home Assistant OS 8.2
-- | --
update_channel | stable
supervisor_version | supervisor-2022.07.0
agent_version | 1.2.1
docker_version | 20.10.14
disk_total | 57.8 GB
disk_used | 9.2 GB
healthy | true
supported | true
board | rpi3-64
supervisor_api | ok
version_api | ok
installed_addons | File editor (5.3.3), Samba share (10.0.0), Mosquitto broker (6.1.2), Duck DNS (1.15.0), Terminal & SSH (9.6.0), Network UPS Tools (0.11.0), SomfyProtect2MQTT-dev (0.2.1)



dashboards | 1
-- | --
resources | 5
views | 11
mode | storage



oldest_recorder_run | 2 juillet 2022 à 18:40
-- | --
current_recorder_run | 12 juillet 2022 à 13:44
estimated_db_size | 124.30 MiB
database_engine | sqlite
database_version | 3.38.5



version | 3.1.0 (3871c0b)
-- | --
cloud_online | 1 / 4
local_online | 0 / 0


@mcik33 do you have (or had) the custom component installed?

Similar issue to this one: Cannot import name ‘TooManyAttemptsBannedException’ from ‘pyoverkiz.exceptions’ · Issue #74636 · home-assistant/core (github.com).

@imick Thanks for your reply.

Yes, in tue past, i had the custom componement installed.

The issue giving by Ducatel don’t work for me (not in doker).

Had the same issue. Got it working by patching the api.py file from PR Custom Component: on line 330, there’s a call to timeout(). I just removed the loop=asyncio.get_event_loop() parameter (and the comma of course), so that it reads:

async with async_timeout.timeout(TIMEOUT):

I don’t know if this is really a proper fix, but (after a restart of HA) I was able to install this native Somfy API component - and it has been working like dream (for now): response is like instantaneous!

Works great, thanks! Response is immediate, and perfect if there is no internet. Local is the way to go…

Have it working with 21 roller shutters (10 Velux, the rest Somfy), 2 windows, 1 bioclimatic (motorized) pergola and light. All fine.