homebridge-selve-home-server-2

Homebridge plugin for controlling shutters and similar Selve devices through the Selve Home Server 2.

It connects to the local Selve API and exposes configured devices to Apple Home through Homebridge.

Features

• control Selve shutters from Apple Home
• current position and movement state updates
• optional buttons for intermediate position 1 and 2
• support for multiple configured shutters
• compatible with Homebridge 2

Requirements

• Homebridge ^2.0.1
• Node.js 22.x or 24.x
• a reachable Selve Home Server 2 in your local network
• device IDs (sid) for the shutters you want to expose

Installation

Install from npm:

npm install -g homebridge-selve-home-server-2

Configuration

Add the platform to your Homebridge config:

{
  "platform": "SelveHomeServer2",
  "name": "Selve Home Server 2",
  "url": "http://192.168.2.1",
  "password": "your-password",
  "pollInterval": 15,
  "shutters": [
    {
      "name": "Living Room",
      "device": 1,
      "showIntermediate1": true,
      "showIntermediate2": true
    }
  ]
}

Configuration Options

Platform

• platform: must be SelveHomeServer2
• name: display name of the platform in Homebridge
• url: local URL or IP address of the Selve Home Server 2
• password: optional password of the Selve Home Server 2
• pollInterval: optional refresh interval in seconds, minimum 5, default 15

Shutters

• name: display name in Apple Home
• device: Selve device number (sid) from the Home Server
• showIntermediate1: optional switch for intermediate position 1
• showIntermediate2: optional switch for intermediate position 2

Finding the Device Number

The plugin uses the Selve device number (sid) for each shutter.

If you are working with the Selve API directly, the official Postman collection may help:

Selve Home Server 2 Postman Collection

Notes

• the plugin communicates with the local Selve endpoint /cmd
• state handling is aligned with the Selve Home Server 2 API documentation
• intermediate position commands use movetoP1 and movetoP2

Raspberry Pi Zero 2

If you run Homebridge on a Raspberry Pi Zero 2, this repository also includes helper scripts for creating a customized Homebridge image with the plugin preinstalled on first boot.

Relevant files:

• build-custom-pi-image.sh
• build-pi-zero2-bundle.sh

Short workflow:

1. Download an official Homebridge Raspberry Pi image.
2. Run:

sudo ./scripts/build-custom-pi-image.sh /path/to/homebridge-image.img.xz /path/to/homebridge-selve-zero2.img

3. Flash the generated image to the SD card.
4. Boot the Raspberry Pi with network access.

Troubleshooting

• verify that the Selve Home Server 2 is reachable from the Homebridge machine
• verify that the configured device numbers match the Selve sid values
• if states update too slowly, reduce pollInterval
• if the server is password protected, make sure password is set correctly

Compatibility

Tested target:

• Homebridge 2.0.2

Supported runtime:

• Node.js 22.x
• Node.js 24.x

License

MIT