Homebridge SOMA Smart Shades

Homebridge plugin for controlling SOMA Smart Shades via the local SOMA Connect HTTP API.

This plugin allows you to control your shades directly in Apple Home (HomeKit) with full support for position control and battery monitoring.

Features

• Full HomeKit Window Covering support
• Smooth position control (0–100%)
• Native open / close commands
• Correct direction mapping (SOMA ↔ HomeKit)
• Real-time position updates
• Battery percentage + low battery alerts
• Automatic device discovery

Requirements

• SOMA Smart Shades or SOMA Tilt devices
• SOMA Connect (Raspberry Pi or USB version)
• SOMA Connect connected to your local network
• Homebridge v1.8+ or v2.x
• Node.js 20+

Installation

Option 1 — Install from GitHub

sudo npm install -g https://github.com/YOUR_USERNAME/homebridge-soma-shades

Option 2 — Local Development

git clone https://github.com/YOUR_USERNAME/homebridge-soma-shades.git
cd homebridge-soma-shades
npm install
npm run build
npm link

Then link into Homebridge:

cd /var/lib/homebridge
npm link homebridge-soma-shades

Configuration

Add the platform to your Homebridge config.json:

{
  "platforms": [
    {
      "platform": "SomaShades",
      "name": "Soma Shades",
      "host": "192.168.1.91"
    }
  ]
}

Config Options

| Option | Required | Description | |------|--------|-------------| | platform | Yes | Must be "SomaShades" | | name | Yes | Display name in Homebridge | | host | Yes | IP address of SOMA Connect |

How It Works

The plugin communicates locally with SOMA Connect using its HTTP API:

• /list_devices → discovers shades
• /get_shade_state → retrieves position
• /set_shade_position → sets position
• /open_shade / /close_shade → full open/close
• /get_battery_level → battery status

No cloud or external services are required.

Position Mapping (Important)

SOMA and HomeKit use opposite position scales:

| State | SOMA | HomeKit | |------|------|--------| | Fully Open | 0 | 100 | | Fully Closed | 100 | 0 |

This plugin automatically converts between the two.

Battery Support

• Displays battery percentage in HomeKit
• Triggers low battery warning when voltage is below threshold
• Uses SOMA's battery_percentage when available

Notes

• All communication is local only
• No authentication is required (SOMA API is unsecured by design)
• Avoid exposing SOMA Connect to the internet
• Some devices may appear as "unknown" if not fully detected

Known Limitations

• No real-time motion completion feedback (SOMA limitation)
• Position updates immediately after command (not actual position)
• Light sensor support intentionally excluded (performance reasons)

Development

npm run build
sudo hb-service restart

For live development:

npm run watch

Debugging

View Homebridge logs:

sudo hb-service logs

Common issues:

• No devices found → incorrect host
• Wrong direction → fixed via internal mapping
• Missing devices → SOMA Connect has not detected them yet

Future Improvements

• Tilt support (SOMA Tilt)
• Stop command support
• Configurable inversion toggle
• Light level sensor (optional)

License

Apache-2.0

Credits

• SOMA Smart Home for API access
• Homebridge community