Skip to main content

soma-shades

CI PyPI Python License: MIT

Control Soma Smart Shades over Bluetooth LE, without the SOMA Connect hub, and add them to Home Assistant through MQTT.

┌──────────────┐               ┌──────────────────────┐          ┌───────────┐          ┌────────────────┐
│ Soma Smart   │ Bluetooth LE  │ Soma Bridge          │   MQTT   │ Mosquitto │   MQTT   │ Home Assistant │
│ Shades       │◄─────────────►│ connection per shade │◄────────►│ broker    │◄────────►│                │
│              │               │ keepalive, reconnect │          │           │          │                │
└──────────────┘               └──────────────────────┘          └───────────┘          └────────────────┘
  • soma command line tool: discover the shades, move them, read the position and battery level.
  • MQTT bridge: the shades appear as covers in Home Assistant, with live position updates, battery and solar panel sensors.
  • Reliable connections: keepalive, automatic reconnects, and no unavailable flapping on short connection drops.
  • Runs anywhere near the shades: Docker image, or a systemd service on a Raspberry Pi.

Only the SOMA Smart Shades 2 are supported. The Smart Shades 3 use a different protocol and are planned for a next version. This project is not affiliated with Soma.

Quick start

Requirements: Python 3.11+, a Bluetooth LE adapter within range of the shades, and for Home Assistant an MQTT broker.

pip install soma-shades                     # or: uv tool install soma-shades

soma discover                               # finds the shades
soma control living_room down
soma control living_room up
soma control living_room set_position 50    # 0 is open, 100 is closed
soma control living_room beep               # probe sound
soma bridge --broker 192.168.1.10           # bridge to Home Assistant

A shade accepts a single Bluetooth connection: close the Soma app and stop the bridge before using soma control.

Home Assistant Integration

  1. Install an MQTT broker: the Mosquitto add-on on Home Assistant OS, or a Mosquitto container with the Docker Compose file.
  2. Add the MQTT integration with the address of the broker.
  3. Start the bridge. Every shade appears as a device through MQTT discovery, with a cover, sensors for the battery level, battery voltage, input voltage of the solar panel or USB charger and the start of the connection, a Sync time button that sets the clock of the shade for the schedules of the Soma app, and a Bluetooth connection switch. On the first connection the shade beeps once.

New shades are found when the bridge starts, or when you publish a scan duration in seconds while it runs:

mosquitto_pub -h <broker> -t homeassistant/cover/discover -m 20

To configure a shade in the Soma app, turn off its Bluetooth connection switch. The bridge disconnects the shade and leaves it alone, also after a restart, until you turn the switch on again. In the meantime the shade is unavailable in Home Assistant, so its automations do not work.

To remove a shade, remove it from the cache file and delete the device in Home Assistant, which also clears its retained discovery messages.

MQTT topics
Topic Direction Payload
homeassistant/cover/smartshade/<shade>/config publish discovery message
homeassistant/cover/smartshade/<shade>/availability publish online, offline
homeassistant/cover/smartshade/<shade>/state publish open, closed, opening, ...
homeassistant/cover/smartshade/<shade>/position publish 0 (open) to 100 (closed)
homeassistant/cover/smartshade/<shade>/battery publish battery level, 0 to 100
homeassistant/cover/smartshade/<shade>/battery_voltage publish battery voltage in mV
homeassistant/cover/smartshade/<shade>/input_voltage publish charging input voltage in mV
homeassistant/cover/smartshade/<shade>/charging_current publish charging current, probably in mA
homeassistant/cover/smartshade/<shade>/connected_since publish start of the connection
homeassistant/cover/smartshade/<shade>/bluetooth_connection publish ON, OFF
homeassistant/switch/smartshade/<shade>_bluetooth_connection/config publish discovery message of the switch
homeassistant/sensor/smartshade/<shade>_<sensor>/config publish discovery messages of the sensors
homeassistant/button/smartshade/<shade>_sync_time/config publish discovery message of the button
homeassistant/cover/smartshade/bridge/availability publish online, offline (last will)
homeassistant/cover/smartshade/<shade>/set subscribe open, close, stop
homeassistant/cover/smartshade/<shade>/set_position subscribe 0 to 100
homeassistant/cover/smartshade/<shade>/sync_time subscribe any payload sets the clock
homeassistant/cover/smartshade/<shade>/bluetooth_connection_set subscribe ON, OFF
homeassistant/cover/discover subscribe scan duration in seconds (max 30)
homeassistant/status subscribe online republishes all messages

All published messages are retained, so Home Assistant also gets the covers when it starts after the bridge.

How the bridge works

  • Each shade has its own connection, reconnected with a backoff from 1 second up to 5 minutes.
  • On battery the shades drop a connection 3 minutes after the last write, so the bridge sets their clock every 2 minutes. While charging they keep the connection open.
  • A shade is only reported unavailable when it cannot be reconnected within 2 minutes.

Bluetooth adapter

The bridge keeps a connection open to every shade, so the adapter has to hold several connections at the same time. After connecting, a shade asks for a connection interval of 20 to 40 ms and a supervision timeout of 800 ms, and drops the connection when the adapter cannot provide that.

Use an adapter from the list of Home Assistant, e.g. a branded CSR8510A10 adapter or a Realtek RTL8761BU adapter like the ASUS USB-BT500. Avoid adapters with an Actions ATS2851 chip (USB ID 10d7:b012), often sold as "Bluetooth 5.3": they reject the request, and the shades then drop the connection every 105 seconds. Also avoid unbranded CSR clones (USB ID 0a12:0001). On Linux, check the chip with lsusb and sudo btmgmt info.

On Linux, let BlueZ connect with these parameters right away, so the shades do not need to ask for them. Add this to /etc/bluetooth/main.conf on the host, then restart BlueZ with sudo systemctl restart bluetooth:

BlueZ settings for /etc/bluetooth/main.conf
[LE]
# shortest time between two connection events, in units of 1.25 ms: 16 × 1.25 = 20 ms (default 24: 30 ms)
# the shades ask for 16 (20 ms)
MinConnectionInterval=16
# longest time between two connection events, in units of 1.25 ms: 32 × 1.25 = 40 ms (default 40: 50 ms)
# the shades ask for 32 (40 ms), with a longer interval they ask for an update and drop the connection when it fails
MaxConnectionInterval=32
# connection events the shade may skip to save power: none (default 0)
# the shades ask for 0, they answer every event, so a command arrives within one interval
ConnectionLatency=0
# time without an answer before the connection is lost, in units of 10 ms: 80 × 10 = 800 ms (default 42: 420 ms)
# the shades ask for 80 (800 ms), a weak connection then survives short interference
ConnectionSupervisionTimeout=80

Running the bridge as a service

Docker Compose

The docker-compose.yml runs Mosquitto and the bridge. The bridge uses the Bluetooth of the host through D-Bus, so the host must be Linux with BlueZ. It scans for shades when it starts, and uses the timezone of the host for the Sync time button.

curl -LO https://raw.githubusercontent.com/vanderkley/soma-shades/main/docker-compose.yml
mkdir -p deploy/mosquitto
curl -Lo deploy/mosquitto/mosquitto.conf \
    https://raw.githubusercontent.com/vanderkley/soma-shades/main/deploy/mosquitto/mosquitto.conf
docker compose up -d
docker compose logs -f soma-bridge

Raspberry Pi with systemd

The systemd unit runs the bridge as your user, with the broker on localhost:

sudo apt-get install bluetooth pi-bluetooth pipx
sudo usermod -aG bluetooth $USER
pipx install soma-shades

sudo curl -Lo /etc/systemd/system/soma-bridge@.service \
    https://raw.githubusercontent.com/vanderkley/soma-shades/main/deploy/systemd/soma-bridge@.service
sudo systemctl daemon-reload
sudo systemctl enable --now soma-bridge@$USER
journalctl -u soma-bridge@$USER -f

For another broker, set Environment=SOMA_BROKER=... with sudo systemctl edit soma-bridge@$USER.

Mosquitto on Linux, without Docker
sudo apt-get install mosquitto mosquitto-clients
sudo tee /etc/mosquitto/conf.d/soma-shades.conf <<EOF
listener 1883 0.0.0.0
allow_anonymous true
EOF
sudo systemctl restart mosquitto

allow_anonymous true lets every host on the network connect. Only expose port 1883 on your local network, or configure a password file and start the bridge with --username and --password.

Command line

Command Description
soma discover Scan for shades and add them to the cache
soma control SHADE ACTION [VALUE] Run an action on a shade, see below
soma bridge Bridge the shades to Home Assistant through MQTT
soma probe-sounds SHADE Play the sound codes one by one

Actions of soma control:

  • Move: up, down, stop, set_position VALUE (0 is open, 100 is closed)
  • Read: position, battery, battery_voltage, charging, motor_speed, info
  • Other: set_motor_speed VALUE (0 to 100), sync_time, beep

Run soma COMMAND --help for the options and soma -v COMMAND for debug logging. The options can also be set with the environment variables SOMA_CACHE_FILE, SOMA_BROKER, SOMA_PORT, SOMA_USERNAME, SOMA_PASSWORD and SOMA_DISCOVER.

Troubleshooting

Check the Bluetooth access on Linux:

ls -l /run/dbus/system_bus_socket     # the D-Bus socket exists
systemctl status bluetooth            # active (running)
bluetoothctl show                     # Powered: yes
Error Cause
FileNotFoundError no D-Bus socket; in Docker, /run/dbus is not mounted
AccessDenied, PermissionError D-Bus or AppArmor denies the access to BlueZ, or the user is not in bluetooth
No Bluetooth adapters found bluetoothd runs without an adapter, check bluetoothctl show and rfkill list
  • A shade stays unavailable: run soma -v bridge and look for Cannot connect. Check the range with soma control <shade> battery while the bridge is stopped.
  • The Home Assistant Bluetooth integration competes for the same adapter. Give it a separate adapter, or disable it.
  • All shades fail with TimeoutError or device disappeared: BlueZ can get stuck after many failed connections. Restart it with sudo systemctl restart bluetooth.
  • Connections drop at a fixed interval: show the reason with sudo btmon | grep -A4 "Disconnect Complete". Unacceptable Connection Parameters (0x3b) every 105 seconds is the adapter, see Bluetooth adapter. Connection Timeout (0x08) is the range.

Python API

Example: read the state of a shade and move it
import asyncio

from soma_shades import ShadeFleet


async def main() -> None:
    fleet = ShadeFleet()  # the shades from the cache
    if not fleet.shades:
        await fleet.discover(scan_for=20)

    shade = fleet.get("living_room")
    await shade.connect(timeout=15)
    try:
        print(await shade.get_position(), await shade.get_battery_level())
        await shade.set_position(50)
    finally:
        await shade.disconnect()


asyncio.run(main())

Development

See CONTRIBUTING.md for the development setup, the checks and the release steps.

Credits

Thanks to rzuppur/smart-shades-documentation for the protocol documentation, and andersonshatch/soma-ctrl for the original Node.js implementation. Licensed under MIT.

Metadata

Release files for soma-shades 1.4.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for soma-shades 1.4.0
File Size Uploaded Provenance Actions
soma_shades-1.4.0.tar.gz 40.4 kB With provenance Details for soma_shades-1.4.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for soma-shades 1.4.0
File Interpreter ABI Platform Actions
soma_shades-1.4.0-py3-none-any.whl Python 3 none any Details for soma_shades-1.4.0-py3-none-any.whl

Total release size: 72.7 kB

Release files / soma_shades-1.4.0.tar.gz

Download URL soma_shades-1.4.0.tar.gz
Size 40.4 kB
Tags Source
SHA-256 checksum
How to use checksums
c4f38917359727bdc2eadcb5fa4c1f9f23cb9183a95cd70968dd41a13e6498c4
BLAKE2b-256 checksum
How to use checksums
4318bfdec9c64036f304b7dc30e08fe1a7b6a518a061cbe7082cb0ad29f54b32
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 31, 2026.

Transparency log

Release files / soma_shades-1.4.0-py3-none-any.whl

Download URL soma_shades-1.4.0-py3-none-any.whl
Size 32.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
5d654ede971f2f374c51f1f407223dc6a54a35c3acd9c1868ed46407a7570b20
BLAKE2b-256 checksum
How to use checksums
5ea6d856417e1226e06ee99f7c5c0e8b369bd57c23bed48426d7f697b8ef2c29
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 31, 2026.

Transparency log

Security for soma-shades 1.4.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for soma_shades-1.4.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 31, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page