homebridge-somfi-blinds

A Homebridge plugin to add HomeKit compatibility to Somfy RTS devices (rolling shutters, blinds, awnings, ...) requiring only a Raspberry Pi and a simple 433 MHz transmitter. The hardware setup and part of the code base is adapted from homebridge-rpi-rts, but with a modification so that the device now appears as only a single stateful On/Off button in HomeKit rather than mirror the remote buttons of Up, Down, My, Prog. This makes it compatible with Apple HomeKit Scenes and Siri voice controls.

| Advantages | Limitations | | ---------- | ----------- | | Cheap: should be under 10 €, or under 40 € in total with a Raspberry Pi Zero WH and accessories includedUp to 150 Somfy RTS devices controlled simultaneously (HomeKit limit per bridge)Self sufficient: pairing with Somfy RTS devices can be performed directly in Homebridge or Apple Home App with the Prog buttonOnce configured the device appears as only a single window covering accessory in Apple Home | Requires a bit of hacking with the hardware and softwareRequires to give root privilege to HomebridgeDue to limitations with Somfy RTS, the state is purely cached in Homebridge and not received from the device. If you use the physical remote it will get out of syncState is either Open or Closed and does not support partial openingPersonal project without any guarantee of updates and support |

Hardware Setup

Somfy RTS uses a frequency of 433.42 MHz instead of the usual 433.92 MHz, which requires to replace the resonator to increase the range of the transmitter. The range is typically less than 3 meters at 433.92 MHz and more than 20 meters at 433.42 MHz with a 17 cm antenna (quarter wavelength).

Parts

• Raspberry Pi (I personally used a 4 Model B) with micro SD card and power source
• 433 MHz RF transmitter (example)
• 433.42 MHz saw resonator (example)
• antenna (my transmitter cam with one, but any wire should work)
• 3 female to female jumper wires (example)

Modification of the Transmitter

1. Remove the original resonator by pulling it while heating its 3 pins with a soldering iron
2. Clean the remaining solder
3. Solder the 433.42 MHz resonator instead
4. Solder the antenna to the ANT pad

Connection to the Raspberry Pi

Using the female to female jumper wires, connect the transmitter to the Raspberry Pi GPIO:

• Transmitter GND to Raspberry Pi GND
• Transmitter VCC to Raspberry Pi +5V
• Transmitter ATAD (DATA) to Raspberry Pi GPIO 4

Software Setup

Installation

If not done yet, install Raspberry Pi OS, Node.js and Homebridge. You can get there directly by installing the Homebridge Raspberry Pi Image.

Install the pigpio C library with the following command in a terminal window:

sudo apt install pigpio

To install the plugin, go to Homebridge Config UI X (the visual interface of Homebridge accessible with a browser), go to the Plugins tab, search for homebridge-somfi-blinds and click Install.

Alternatively, use the following command line in a terminal window:

sudo npm install -g homebridge-somfi-blinds

Modification of Homebridge Service

Root privileges are required to send waveform signals to the transmitter through the Rapsberry Pi GPIO.

1. Open the file /etc/systemd/system/homebridge.service:

sudo nano /etc/systemd/system/homebridge.service

Change the user to root:

User=root

Comment the line starting by CapabilityBoundingSet by adding # at the beginning of it:

# CapabilityBoundingSet=CAP_IPC_LOCK CAP_NET_ADMIN CAP_NET_BIND_SERVICE CAP_NET_RAW CAP_SETGID CAP_SETUID CAP_SYS_CHROOT CAP_CHOWN CAP_FOWNER CAP_DAC_OVERRIDE CAP_AUDIT_WRITE CAP_SYS_ADMIN

Ctrl + O to save and Ctrl + X to exit.

The final file should look like this (some lines may differ depending on Node.js and Homebridge configuration, leave them as they are):

sudo cat /etc/systemd/system/homebridge.service

[Unit]
Description=Homebridge
Wants=network-online.target
After=syslog.target network-online.target

[Service]
Type=simple
User=root
PermissionsStartOnly=true
WorkingDirectory=/var/lib/homebridge
EnvironmentFile=/etc/default/homebridge
ExecStartPre=-run-parts /etc/hb-service/homebridge/prestart.d
ExecStartPre=-/usr/local/lib/node_modules/homebridge-config-ui-x/dist/bin/hb-service.js before-start $HOMEBRIDGE_OPTS
ExecStart=/usr/local/lib/node_modules/homebridge-config-ui-x/dist/bin/hb-service.js run $HOMEBRIDGE_OPTS
Restart=always
RestartSec=3
KillMode=process
# CapabilityBoundingSet=CAP_IPC_LOCK CAP_NET_ADMIN CAP_NET_BIND_SERVICE CAP_NET_RAW CAP_SETGID CAP_SETUID CAP_SYS_CHROOT CAP_CHOWN CAP_FOWNER CAP_DAC_OVERRIDE CAP_AUDIT_WRITE CAP_SYS_ADMIN
AmbientCapabilities=CAP_NET_RAW CAP_NET_BIND_SERVICE

[Install]
WantedBy=multi-user.target

2. Open the file /etc/default/homebridge:

sudo nano /etc/default/homebridge

Append --allow-root at the end of the HOMEBRIDGE_OPTS line (the /var/lib/ path may differ, leave it as it is):

HOMEBRIDGE_OPTS=-I -U "/var/lib/homebridge" --allow-root

Ctrl + O to save and Ctrl + X to exit.

3. Refresh systemd:

sudo systemctl daemon-reload

4. Restart hb-service:

sudo hb-service restart

Configuration

Each Somfy device listens to a list of remotes that were previously registered on this device.

The remotes send 3 values:

• Its unique ID
• A rolling code that is incremented each time a button is pressed on the remote
• A command: Up, Down, My, Prog

When a device receives a signal it does the following:

• It verifies that the unique ID of the remote is in the list of its registered remotes
• It verifies that the rolling code is the same or very close to the one it knows for this remote ID
• It increments the rolling code for this remote ID (so it keeps the same value than the one stored on the remote)
• It performs the command (move up, down, ...)

A same remote can even be registered on many devices (intentionally or inadvertently), and thus control simultaneoulsy many devices.

Configuration of the Plugin

Go to Homebridge Config UI X, go to the Plugins tab, and click on Settings under Homebridge Rpi Rts.

Create as many accessories as needed (e.g. one per device to control). Each accessory is equivalent to a virtual remote. Each accessory must get a unique ID.

Alternatively, edit the JSON config file and add the following block inside the accessories array for each accessory to create:

{
    "accessory": "Somfy Blinds",
    "name": "XXXXX",
    "id": 12345,
    "adminMode": true,
    "invertToggle": false,
    "repetitions": 4,
    "openToMyPosition": false,
    "blindTimeToOpen": 12000
}

Where:

• accessory must be "Somfy Blinds" (required)
• name is the name of the accessory as it will appear in HomeKit (required)
• id is the unique ID of the virtual Somfy RTS remote to choose between 0 and 16777216 (required)
• adminMode when sets to true shows four stateless buttons (Up, Down, My, Prog) and when false shows only a single On/Off button
• invertToggle is used for blinds that extend upwards where the Up command actually closes the blind
• repetitions is an optional parameter that states how many times the signal should be sent. Sending multiple times may improve reception, however if the number is too large some blinds may detect it as a long button press, which only moves the blinds one step (Default = 4)
• openToMyPosition should be enabled for venetian blinds or other window coverings that should be opened to a partial position. It sends a MY button press when open is set as target position
• blindTimeToOpen defines the time in ms that it typically takes for the blind to open or close. Used to mock the current position that is reported. For venetian blinds the recommendation is to lower this number to 2000 or 2s (Default = 10000)

Pairing

For each virtual remote created:

1. Take the current physical remote that controls the Somfy device to be programmed. If the remote controls several channels, make sure to select the good one.

2. With this remote, use the Up/Down/My buttons to make the device approximately half way between the opened and closed positions (the aim is to not be totally opened or totally closed).

3. On the same remote, locate the Prog button (usually a small button on the back) and keep it pressed until the Somfy device does a short up and down movement.

4. Without waiting, press the Prog button on the virtual remote to pair with this device. The Somfy device should do again a short up and down movement confirming the registration of this new remote.

5. Wait at least 5 minutes before pairing another remote to avoid pairing a remote to multiple devices.

Post Setup

Once pairing is complete, you can switch the controls to a single stateful On/Off window covering. Go to Homebridge Config UI X, then in the Config tab, edit the JSON to set the adminMode to false. Restart homebridge.

Backup

Any loss of unique IDs and/or rolling codes, leads to the impossibility to control the Somfy RTS devices.

Even worst, it makes unregistering the virtual remotes impossible, because the unique ID and correct rolling code are necessary to send the command to unregister a remote. The only solution would be a hard reset of the device involving accessing the motor, resetting the upper/lower limits and registering the remotes from scratch.

As rolling codes are incremented each time a signal is sent, it is strongly advised to perform Homebridge backups frequently.

Rolling codes are stored in text files in the Homebridge storage path with the unique ID as the name, e.g. 12345.json, and are thus normally backed-up during Homebridge backups.

Troubleshooting

• Error below: make sure to follow the instructions in Modification of Homebridge Service

+---------------------------------------------------------+
|Sorry, you don't have permission to run this program. |
|Try running as root, e.g. precede the command with sudo. |
+---------------------------------------------------------+

• Error initMboxBlock: init mbox zaps failed: reboot the Raspberry Pi: sudo reboot.

• Error Can't lock /var/run/pigpio.pid: stop current pigpio daemon instance: sudo killall pigpiod.

If it does not solve the problem, please open an issue in GitHub with as much information on the environment and error as possible (Raspberry Pi model, Node.js version, Homebridge version, ...)

• Blind only moves a small step instead of fully opening/closing. The blind is detecting the signal as a long-press. Change your config file and lower the repetitions parameter to 2.

Links

• homebridge-rpi-rts from which this plugin was originally based.
• Pushstack for a detailed description of the Somfy RTS protocol.
• joan2937 for the pigpio C library.
• fivdi for the pigpio javascript wrapper.
• Nickduino for a python implementation of the Somfy RTS protocol.