ioBroker.tahoma

An ioBroker adapter for Somfy Tahoma. This project has no affiliation with Somfy. Initially based on the script taken from https://forum.iobroker.net/post/336001 and forked from https://github.com/StrathCole/ioBroker.tahoma.

The adapter connects to the Tahomalink end user API and controls the devices. set up through Tahoma Box (and most likely Connexoon).
The adapter is not feature-complete, yet, but it should support most actions for controlling blinds and shutters etc.

Please also read the FAQ in case of issues first.

Currently tested devices

Generally, this adapter should support all devices that can be accessed via tahomalink.com, but for the adapter developer it is difficult to guarantee this. Mainly, because the documention of the used Somfy-API is (at least publically) non-existant and the developer can only test Somfy-devices which he owns himself, or is able to test with support of willing participants.

Devices that can be controlled via tahomalink.com usually are also supported by this adapter. This includes: | Device | Support for Online API | Support for Local API | |-|-|-| | Tahoma box | ✓ | ✓ | | Connexoon | ✓ | ✓ (proof) | Tahoma Switch | ✓ | ✓ | | Connectivity Kit | ✓ (proof) | ✗ (proof)

The following Somfy devices were verified to work with this adapter:

• S&SO RS100 io
• Oximo io
• Sun sensor Sunis io
• Temperature sensor io
• Smoke Sensor io
• Adapter Plug io

Configuration

The following configuration parameters are supported by the adapter. | Parameter | (Default) value | Description | |---------------------------------------------------------|-----------------|-------------| | Username | <your Tahomalink user> | Required to authenticate your Tahoma account. | | Password | <Your Tahomalink password> | Required to authenticate your Tahoma account. | | Polling interval | 20000 | Time (in milliseconds) after which the adapter will try to get new data from Tahomalink. | | PIN of the Tahoma box | format similar to 1234-5678-9012 | ^{Only for LocalAPI} Unique PIN of your Tahoma box provided by Somfy. More infos on how to activate/use it here | | Local IP | | Optional. Use only, if you want to connect to the local api of your Tahoma box via the specified IP, instead of using the default DNS-Record gateway-<pin>, which will work fine for most installation. | Use MDNS | false | ^{Only for LocalAPI} If set to true will try to use mDNS to resolve local hostname of you Tahoma-Box. Might not be supported by all routers, hence it is deactivated by default. | | Login Attempts ¹ ² | 3 | Amount of attempts to login again after login failure. | | Delay between login attempts ¹ ² | 30 | Time (in seconds) to wait between login attempts. | | Delay after failed login ¹ ² | 120 | Time (in seconds) to wait, after all consecutive login attempts have failed. | | Delay before applyqueue retry ¹ ² | 1500 | Time (in milliseconds) to wait, before a second attempt is made to send changes from the internal apply queue to Tahoma, in case it got lost. |

¹ These configuration values are only visible and configurable in Admin 5 (new GUI), or later.

² All values are related to login to Tahomalink, which is mostly a blackbox from development point of view. If you configure the numbers too low here, experience has shown that there is a good chance Somfy will temporarily lock your account, so lower default values here with care!

States

tahoma.X.location

The state in this tree contain the personal information of the user like city, street address and longitude/latitude.

tahoma.X.devices.*.deviceURL

This state contains the device URL that is used by Tahoma to identify the device.

tahoma.X.devices.*.commands

These states contain button commands for controlling the devices. Most devices will support commands like close and open but also some more.
Some of the commands have a :slow at the end if supported by the device. Using those enables low speed or so-called silent mode.

tahoma.X.devices.*.states

These states contain current status of the devices as follows. Some of the states have a :slow at the end if supported by the device. Setting those enables low speed or so-called silent mode.

| Device state | Editable | Purpose/Description | |-------------------------------------------------------------|----------|---------------------| | tahoma.X.devices.*.states.core:DeploymentState | ✓ | Provides information about and controls the state of current deployment. 100 means fully deployed, 0 is undeployed. Not all devices have this value, some have ClosureState instead. | | tahoma.X.devices.*.states.core:TargetDeploymentState | ✓ | See tahoma.X.devices.*.states.core:DeploymentState. Use this to e.g. change blind position directly. | | tahoma.X.devices.*.states.coreClosureState | ✓ | Provides information about and controls the state of current closure. 100 means fully closed, 0 is open. Not all devices have this value, some have DeploymentState instead. | | tahoma.X.devices.*.states.core:TargetClosureState | ✓ | See tahoma.X.devices.*.states.core:ClosureState | | tahoma.X.devices.*.states.core:OrientationState | ✓ | Provides information about and ocntrols the orientation (e. g. for shutters) of slats. Not all devices offer this value | | tahoma.X.devices.*.states.core:TargetOrientationState | ✓ | See tahoma.X.devices.*.states.core:OrientationState |
| tahoma.X.devices.*.states.core:NameState | | Contains the current name of the device. | | tahoma.X.devices.*.states.core:OpenClosedState | | Contains closed if the device is 100% closed or 0% deployed and open otherwise. | | tahoma.X.devices.*.states.core:PriorityLockTimerState | | If a sensor has locked the device this is stated here, e. g. a wind sensor blocking an awning. | | tahoma.X.devices.*.states.core:RSSILevelState | | The current signal quality of the device. | | tahoma.X.devices.*.states.core:StatusState | | available if the device is currently available. | | tahoma.X.devices.*.states.io:PriorityLockLevelState | | See tahoma.X.devices.*.states.core:PriorityLockTimerState | | tahoma.X.devices.*.states.io:PriorityLockOriginatorState | | See tahoma.X.devices.*.states.core:PriorityLockTimerState | | tahoma.X.devices.*.states.moving | | States if the device is currently moving. 0 = stopped, 1 = up/undeploy, 2 = down/deploy, 3 = unknown direction <br/> Remark: <br/>This only works reliable if connected to the Tahoma (not Local) API, since the Local API does not provide enough action-event updates to compute this state correctly. core:MovingState should work in both cases though.

Changelog

See Changelog.

<!-- Placeholder for the next version (add instead of version-number-headline below): ## __WORK IN PROGRESS__ -->

0.11.0 (2025-04-15)

• Feature: Added option to specify IP address for access to local API (https://github.com/Excodibur/ioBroker.tahoma/issues/424)

0.10.4 (2024-04-28)

• Fixed: Warning resolved about invalid element in jsonConfig

0.10.3 (2024-01-29)

• Fixed: Some crashed caused by event-updates were fixed with a workaround.

0.10.2 (2023-03-25)

• Fixed: Improved core:MovingState. Should reflect moving blinds correctly now.

0.10.1 (2023-01-23)

• Fixed: Clear bearer token, if connection to local API fails, so new one can be fetched.

0.10.0 (2023-01-03)

• Fixed warnings about Failed getting execution state when using the local API.

License

The MIT License (MIT)

Copyright (c) 2020-2025 Marius Burkard & Excodibur

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The abo