🏠 Somfy Tahoma/Connexoon Plugin for Domoticz

Original script by Nonolk.
Special thanks to Jan-Jaap for supporting the conversion of plugin to local access.

Domoticz plugin written in Python to support Somfy Tahoma/Connexoon devices.
Supports both Web (cloud) and Local API access. Local API is recommended for reliability.

The plugin currently supports the following device types: roller shutters, blinds (with slat/orientation control), interior/exterior screens, awnings, pergolas, garage doors, windows, luminance sensors, and RTS devices (Open/Close only, no state feedback due to RTS limitations). Supported devices:

• Roller shutters
• Screens (interior/exterior)
• Awning
• Pergolas
• Garage door
• Sliding Gate
• Windows
• Venetian blinds (positions + slats control)
• Exterior Venetian blinds
• Luminance sensor
• RTS devices (Open/Close only, no state feedback)

⚠️ Important Notes

Version 3.x

When upgrading to version 3.x, it is required to first remove all devices attached to the Somfy hardware. This has to do with the upgrade to the Domoticz Extended Framework, which enabled the slats/orientation control for the blinds. The plugin will not upgrade when there are still devices attached to the Somfy hardware.

version 4.x

As of version 4.x the plugin supports local access to the Somfy box for both Tahoma and Connexoon. Additional installation steps mentioned below.

Version 5.x

The latest plugin version 5.3.2 introduces:

• Extended device support

  • Full venetian blinds: separate units for up/down and orientation.
  • Exterior venetian blinds supported.
  • Awning devices handled correctly (no inverted percentages).
  • Luminance sensors supported.

• Day/Night polling

  • Separate intervals for day and night, configurable via config.txt (DAY_INTERVAL / NIGHT_INTERVAL).
  • Temporary fast polling after commands for faster status updates, configurable via config.txt (TEMP_DELAY / TEMP_TIME).

• Sunrise/Sunset awareness

  • Sunrise/sunset delays configurable via config.txt (SUNRISE_DELAY / SUNSET_DELAY).
  • Polling interval automatically adjusts based on daylight hours.

• Local API & token management

  • Automatic token generation & storage for Local API.
  • Web API still available but deprecated.

• Configuration via config.txt

  • Domoticz host/port, refresh intervals, sunrise/sunset delays, TEMP_DELAY/TIME.
  • Can reload without restarting Domoticz.

• Connection Status device

  • Automatically created in Domoticz to show connection state, gateway type, firmware version, and token info.
  • Displays errors when the box is unreachable.

• Improved logging & error handling

  • Debug logging toggled via the Debug logging field in the hardware settings.
  • Only logs meaningful changes.
  • Better handling of API and command errors.

---

⚠ Somfy currently discourages the use of the Web API
The connection to Somfy Web may not work properly in the plugin.
It is therefore recommended to use Local API mode. Refer to Somfy instructions to put your box in Developer Mode.

---

🔑 Somfy Login

Before installation, register your Somfy products and add them to your Tahoma or Connexoon box:

• Create Somfy account
• Tahoma login

💻 Installation

Prerequisites

1. A recent Domoticz installation with Python plugin support / Extended Plugin Framework enabled.
2. Python 3 with the matching Python development package for your system.
3. Follow the Domoticz guide on Using Python Plugins
4. Install required libraries:

sudo apt-get update
sudo apt-get install python3 python3-dev python3-requests python3-urllib3

Or install the Python dependencies with pip:

python3 -m pip install -r requirements.txt

DomoticzEx is provided by Domoticz and is not a pip dependency.

🖧 Setup Local API Access (Recommended)

1. First you need to enable developer mode on your box:

• connect to the Somfy website and navigate to the My Account menu.
• Find the different available options for your TaHoma box and activate Developer Mode.
• Follow instructions as provided by Somfy

Activating this mode will enable a local API on your TaHoma and Connexoon box. Be aware that Somfy will not be able to provide support for usage of this API.

2. Your Somfy box needs to be reachable in your network.

Option A – Direct IP (no DNS needed):
Select Local IP in the Connection field, fill in the Gateway PIN in the Gateway PIN field, and fill in the IP address of your Somfy box in the Local IP Address field, for example 192.168.1.100.
The plugin will automatically generate and store a token on first start using the PIN and the Somfy web API.

Option B – PIN with DNS / hosts entry:
Select Local PIN in the Connection field. Enter the Gateway PIN in the Gateway PIN field.
You also need to link your Somfy Box PIN to the Somfy Box IP address in your network:

192.168.1.1 1234-1234-1234.local

192.168.1.1 is the IP of your Somfy box
1234-1234-1234 is the PIN number of your Somfy box and don't forget to add .local to the PIN number

📦 Install the plugin

1. Go in your Domoticz directory using a command line and open the plugins directory: cd domoticz/plugins
2. clone the plugin: git clone https://github.com/MadPatrick/domoticz_somfy Somfy
3. Restart Domoticz: sudo systemctl restart domoticz

⚙️ Configure the Plugin

In the Domoticz UI, navigate to the Hardware page. In the hardware dropdown list there will be an entry called "Somfy Tahoma or Connexoon plugin". Add the hardware to your Domoticz system and fill in the required fields

👉 Somfy Tahoma or Connexoon plugin

Field	Input
Username	Somfy account login
Password	Somfy account password
Connection	Web – via Somfy web server; Local PIN – direct connection using Gateway PIN (DNS required); Local IP – direct connection using IP address (no DNS required)
Gateway PIN	Gateway PIN of your Somfy box (e.g. 1234-1234-1234). Used for all connection modes to generate/activate the local API token.
Local IP Address	Only for Local IP mode: IP address of your Somfy box (e.g. 192.168.1.100). Leave empty for Web or Local PIN mode.
Reset token	False by default; set True if token errors occur
Portnumber	Default 8443
Debug logging	Off by default; On for verbose logs

🔧 After saving the configuration, devices are automatically created in Devices.

💡 A Somfy Connection Status device is automatically created. It shows the connection type, gateway model, firmware version, and token info. When the box is unreachable it displays the error reason.

🧾 config.txt (Advanced configuration)

The plugin supports an optional config.txt file for advanced configuration.
This allows you to change settings without restarting Domoticz.

📁 Location:

domoticz/plugins/domoticz_somfy/config.txt

Remove the # for the setting you want to use in config.txt

🔄 Reloading config.txt

The plugin automatically reloads config.txt during runtime No Domoticz restart required. Invalid or missing values will fall back to default settings

📌 Values from config.txt will override UI settings when defined.

# ---- IP AND PORT OF DOMOTICZ. DON'T FORGET TO ENABLE ACCESS FOR LOCAL NETWORK ----
DOMOTICZ_HOST=127.0.0.1
DOMOTICZ_PORT=8080
# ---- POLLING INTERVALS (in seconds) ----
DAY_INTERVAL=30
NIGHT_INTERVAL=900
# ---- TEMP POLLING SETTINGS (in seconds) ----
TEMP_DELAY=10
TEMP_TIME=60
# ---- REFRESH PARAMETERS FOR SUNSET/REFRESH TIMES ----
SUN_REFRESH_TIME=02:15
# ---- SUNRISE/SUNSET DELAYS (in minutes) ----
SUNRISE_DELAY=30
SUNSET_DELAY=60

Key	Description	Default
DOMOTICZ_HOST	IP address of your Domoticz server	127.0.0.1
DOMOTICZ_PORT	Port of your Domoticz server	8080
DAY_INTERVAL	Polling interval during the day (in seconds)	30
NIGHT_INTERVAL	Polling interval during the night (in seconds)	900
TEMP_DELAY	Fast-polling interval (in seconds) applied directly after a command	10
TEMP_TIME	Duration (in seconds) the fast-polling stays active after a command	60
SUN_REFRESH_TIME	Time of day to refresh sunrise/sunset data (HH:MM)	02:15
SUNRISE_DELAY	Minutes before sunrise when day mode starts	30
SUNSET_DELAY	Minutes after sunset when night mode starts	60

---

🔄 Slider Status in Domoticz

If the slider positions do not match your preferences (Open = 0%, Close = 100%), you can reverse the slider for each device:

1. Edit the device in Domoticz
2. Check Reverse Position
3. Move the device a few times to calibrate (To set the position correctly move your devices a few time)

🔄 Update the plugin:

When there is an update of the plugin you can easily do an update by:

cd domoticz/plugins/domoticz_somfy
git pull

And then either restart Domoticz or update the plugin on the Hardware page.

📚 References:

• Web API description Tahoma: https://tahomalink.com/enduser-mobile-web/enduserAPI/doc
• local API description somfy box: https://github.com/Somfy-Developer/Somfy-TaHoma-Developer-Mode