Home Assistant controls, schedules, and a tablet-friendly dashboard for Somfy shades connected through Overkiz / TaHoma.

Русская версия

Important

Cloud mode is the reference connection path. Direct local connection to a TaHoma gateway by IP is experimental and untested in this project. Keep a working cloud configuration available until the local path has been validated on your own hardware and firmware.

Why ShadePilot?

Some Somfy motors can open, close, and stop, but do not report a trustworthy absolute position. ShadePilot turns those simple commands into predictable day-to-day modes:

• a clean tablet interface for individual shades and grouped actions;
• Home Assistant automations for scheduled modes;
• time-based positioning for motors without position feedback;
• a deliberate nightly end-stop run and morning reference cycle;
• a documented cloud path and an opt-in local-IP experiment;
• support for installations with two TaHoma gateways.

ShadePilot is configuration for Home Assistant, not replacement firmware for a TaHoma gateway or a Somfy motor.

How it works

flowchart LR
    U["Tablet / browser"] --> HA["Home Assistant"]
    HA --> A["Automations and scripts"]
    A --> O["Overkiz integration"]
    O --> C["Somfy cloud<br/>reference mode"]
    O -. "experimental" .-> L["Local API<br/>&lt;TAHOMA_IP&gt;:8443"]
    C --> G1["TaHoma gateway A"]
    C --> G2["TaHoma gateway B"]
    L -.-> G1
    L -.-> G2
    G1 --> M1["Somfy motors"]
    G2 --> M2["Somfy motors"]

Loading

The dashboard calls Home Assistant services. Automations and scripts translate those calls into open, close, and stop commands. The Overkiz integration then delivers the commands either through the Somfy cloud or, experimentally, to a compatible gateway on the local network.

See Architecture for the complete data flow.

Calibration strategy

Time-based position is an estimate, not sensor feedback. ShadePilot therefore uses two reference operations:

1. Night: issue a full close command for slightly longer than the measured travel time. The intentional margin lets a shade that stopped partway during the day reach its configured motor end-stop.
2. Morning: fully open the shade to establish a known starting point, then close it for a calibrated interval to reach the desired approximate mode.

The extra seconds are intentional. They are safe only when the motor's physical or electronic end limits are correctly commissioned. Timing must be measured for each installation and should never be copied blindly.

Read Calibration and recovery before changing any delay.

Connection modes

Mode	Status in this project	Internet required for shade commands	Credentials
Overkiz cloud	Reference / expected path	Yes	Somfy account, stored by Home Assistant
TaHoma local API	Experimental, untested	No after successful setup	One local Developer Mode token per gateway

Local mode may depend on gateway model, firmware, Developer Mode availability, network topology, and the Home Assistant / Overkiz versions in use. The experimental procedure is documented in Local API over IP.

Experimental local-IP utility

This repository includes a small standalone client for Somfy's published Developer Mode API. It does not modify Home Assistant configuration.

python -m pip install -e .

# Read-only reachability and API-version probe; no token is sent.
shadepilot-local --host 192.0.2.10:8443 --no-verify-ssl probe

# Authenticated but read-only device inventory.
TAHOMA_TOKEN=CHANGE_ME shadepilot-local \
  --host 192.0.2.10:8443 --no-verify-ssl list-devices

The client also contains opt-in open, close, and stop calls. They are disabled unless the explicit --i-understand-this-is-experimental flag is provided. Do not test movement unless the shades are visible and a normal stop control is immediately available.

Getting started

Prerequisites

• a supported Home Assistant installation;
• one or more Somfy shades already paired with TaHoma;
• the official Home Assistant Overkiz integration;
• correctly configured motor end limits;
• a tested emergency stop method before timing experiments.

1. Configure the connection

Start with the cloud connection in Home Assistant:

1. Open Settings → Devices & services.
2. Add the Overkiz integration and select the appropriate Somfy server.
3. Complete account authentication in the Home Assistant UI.
4. Confirm that each required shade can open, close, and stop.

Do not place an account password in YAML or commit it to Git.

2. Map placeholders

Repository examples intentionally use names such as:

cover:
  - cover.<ROOM_SHADE>
  - cover.<SECOND_ROOM_SHADE>

gateways:
  - <TAHOMA_A>
  - <TAHOMA_B>

Replace placeholders with entity IDs from your own Home Assistant entity registry. Keep installation-specific values in local configuration or a secrets.yaml file that is excluded from version control.

3. Measure and test

Measure complete travel in both directions, calibrate one shade at a time, and only then test a group. Use conservative margins and observe the entire first cycle. The procedure and acceptance checks are in Calibration and recovery.

4. Add the dashboard and schedule

Import the provided Home Assistant configuration according to the comments in the files, then map dashboard actions to your own script entities. Test manual actions before enabling schedules.

Two-gateway installations

Treat gateways as separate security and failure domains:

• give each gateway a clear non-secret label, such as <TAHOMA_A> and <TAHOMA_B>;
• keep a record of which shades belong to which gateway;
• use a separate local token for each gateway;
• calibrate timing per gateway group because network and motor latency can differ;
• validate and roll back one gateway at a time when testing local mode.

A token from gateway A must not be reused for gateway B.

Security

Never commit:

• Home Assistant .storage contents;
• backups, database files, logs, or diagnostic bundles;
• Somfy account credentials;
• Developer Mode tokens;
• real public URLs, access tokens, or network inventory;
• a populated secrets.yaml.

Before publishing, inspect the complete Git diff and scan the repository history—not only the current files. If a secret was committed, remove it from history and rotate it immediately.

Known limitations

• Percentage labels are approximate when the motor provides no position feedback.
• Timing can drift with load, temperature, radio delivery, motor wear, and network latency.
• A group finishes according to its slowest shade.
• Concurrent scripts can issue conflicting commands unless explicitly serialized.
• A successful TCP connection to port 8443 does not prove that a token, firmware, or device is compatible.
• Local mode has not been validated by this project on production hardware.

Documentation

• Architecture
• Calibration and recovery
• Experimental local API over IP
• Русская версия README

Project status

ShadePilot HA is an independent community project and is not affiliated with or endorsed by Somfy, Overkiz, or Home Assistant. Product names and trademarks belong to their respective owners.

Use the automation around moving equipment carefully. Test while the shades are visible, keep controls accessible, and never rely on an unobserved experimental configuration where unexpected movement could cause harm.