search

yenoiwesa / homebridge-connexoon

A homebridge plugin to integrate Somfy blinds with the Connexoon RTS hub
Apache License 2.0
27 stars 2 forks source link
homebridge homebridge-plugin homekit rts somfy

readme

Connexoon logo

Homebridge Connexoon for RTS

A Homebridge plugin providing support for the Connexoon (Somfy), TaHoma (Somfy) and Cozytouch (Atlantic, Thermor, Sauter) platforms and accessories working over the RTS protocol.

This plugin's implementation is inspired by and initially based on Romain Duboc's homebridge-tahoma plugin.

This plugin does not support Somfy IO devices, only RTS devices. Use the homebridge-tahoma plugin if you have IO devices in your installation.

Requirements

Installation

  1. Install homebridge using:
npm install -g homebridge
  1. Install the plugin using:
npm install -g homebridge-connexoon
  1. Update your configuration file. See bellow for a sample.

Important: If the plugin fails with login errors, make sure to set the service configuration to one that works for your geographical region, as your Somfy account will be linked to only one of the services (servers). See the settings section below.

Note: it is also possible to install this plugin in a local npm package instead using the homebridge option --plugin-path.

Configuration

General settings

To configure homebridge-connexoon, add the Connexoon platform to the platforms section of your homebridge's config.js file:

{
    "bridge": { "...": "..." },

    "description": "...",

    "platforms": [
        {
            "platform": "Connexoon",
            "name": "My Connexoon Hub",

            "username": "<Somfy account username>",
            "password": "<Somfy account password>",
            "service": "Connexoon"
        }
    ]
}

The platform can be configured with the following parameters:

Required settings

Parameter Type Default Note
username String null Your Somfy / TaHoma / Cozytouch account username.
password String null Your Somfy / TaHoma / Cozytouch account password.
service String ConnexoonRTS The name of the service used by your hub. Can be: Cozytouch, TaHoma, TaHomaUSA, Connexoon or ConnexoonRTS.

Optional settings

Parameter Type Default Note
devices Object null A JSON object that allows to configure specific devices, using their name as key and configuration Object as value. Accepted configurations differ from device to device. See sections below.
pollingInterval Number (minutes) 10 The polling interval for refreshing the platform's accessories state for automations, in minutes. By detault set to 10 minutes, it can be set to 0 to disable polling. Note that the information is refreshed on demand when using the Home app, this configuration is designed to let Homekit automations react to state updates in the background.
useListedDevicesOnly Boolean false If set to true, only the devices listed in the devices setting will be included in the platform. Other devices will be filtered out. To include a device with no additional configuration, use an empty object as value: "Bedroom Blind": {}.

Device-specific configuration

Each device can receive additional configurations according to its device type registered in the Connexoon app (or equivalent).

Window Coverings

Screens (such as window blinds) and Roller Shutters accept the commands configuration:

{
    "platforms": [
        {
            "platform": "Connexoon",
            "...": "...",

            "devices": {
                "Bedroom Blind": {
                    "commands": ["close", "my", "open"]
                }
            }
        }
    ]
}

Note that the above configuration is the default for a Screen, and thus does not need to declared in the homebridge configuration file to use the default.

commands - Array - Optional

An Array of Strings mapping RTS commands (one of open, my, close) to homekit window covering positions.

The default value is:

["close", "my", "open"]

The above configuration means that the shade will have three 'steps' in the Home app, with the bottom one sending the close command, the middle one sending the my command and the top one sending the open command.

If your shades have been installed in the opposite direction, simply reverse the commands array to:

["open", "my", "close"]

It is also possible to override the configuration to have only two 'steps' for the shade's closure, and for instance, use the 'my' preferred position as the open state, with:

["close", "my"]

Limitation

This platform has been designed to support RTS devices only. As of now, the following device types are supported:

Support for more types may be added as needed.

Since the RTS protocol is one-way, actual closure state is unknown and must be inferred from the last command that was submitted to the device.

Contribute

Please feel free to contribute to this plugin by adding support for new device types, implementing new features or fixing bugs. Pull requests are welcome.