soma-shades
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 │ │ │ │ │
└──────────────┘ └──────────────────────┘ └───────────┘ └────────────────┘
somacommand 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.
- 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 (Linux with BlueZ, or macOS), and for Home Assistant an MQTT broker.
pip install soma-shades # or: uv tool install soma-shades
soma discover # find the shades, stored with the name from the Soma app
soma control living_room down # 0 is open, 100 is closed
soma control living_room set_position 50
soma bridge --broker 192.168.1.10 # bridge to Home Assistant
Home Assistant
- Install an MQTT broker: the Mosquitto add-on on Home Assistant OS, or a Mosquitto container with the Docker Compose file.
- Add the MQTT integration with the address of the broker.
- Start the bridge. Every shade appears as a cover through MQTT discovery. 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 remove a shade, remove it from the cache file and clear its discovery message:
mosquitto_pub -h <broker> -r -n -t homeassistant/cover/smartshade/<shade>/config
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/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/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.
- The shades drop idle connections after 3 minutes, so the bridge reads the battery every 2 minutes.
- A shade is only reported unavailable when it cannot be reconnected within 2 minutes.
- A shade accepts a single connection: stop the bridge before using
soma controlor the Soma app.
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.
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 user pi 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.service
For another user or broker, override User, Group, ExecStart or Environment=SOMA_BROKER=... with
sudo systemctl edit soma-bridge.service.
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] |
up, down, stop, set_position, position, battery, solar_panel, motor_speed, set_motor_speed, info, beep |
soma bridge |
Bridge the shades to Home Assistant through MQTT |
soma probe-sounds SHADE |
Play the sound codes one by one |
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 bridgeand look forCannot connect. Check the range withsoma control <shade> batterywhile the bridge is stopped. - The Home Assistant Bluetooth integration competes for the same adapter. Give it a separate adapter, or disable it.
Python API
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
git clone https://github.com/vanderkley/soma-shades.git && cd soma-shades
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]" && pre-commit install
pytest && ruff check . && mypy # the end-to-end tests need mosquitto
To release, update the version in pyproject.toml and the
changelog, and push a tag like v1.0.0.
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.0.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| soma_shades-1.0.1.tar.gz | 32.1 kB | With provenance | Details for soma_shades-1.0.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| soma_shades-1.0.1-py3-none-any.whl | Python 3 | none | any | Details for soma_shades-1.0.1-py3-none-any.whl |
Total release size: 59.9 kB
Release files / soma_shades-1.0.1.tar.gz
| Download URL | soma_shades-1.0.1.tar.gz |
|---|---|
| Size | 32.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
c6d655095fe61233c91eef1580a38890f062b35af5276539db453e7e0ae094a6
|
|
BLAKE2b-256 checksum How to use checksums |
d42c236d2b675ca99487eb7794f59dd0eeb5f302d92efa95cb1bb19faf419301
|
| 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 27, 2026.
Transparency logRelease files / soma_shades-1.0.1-py3-none-any.whl
| Download URL | soma_shades-1.0.1-py3-none-any.whl |
|---|---|
| Size | 27.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
6b5ab29ebc461de027030ca7a29d6481527fe8f34278f6abad6746a42db0e2fc
|
|
BLAKE2b-256 checksum How to use checksums |
6eec72b4e385eaef2cac65668668355914e1b44a8071dea2866d3ac496dd816a
|
| 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 27, 2026.
Transparency logSecurity for soma-shades 1.0.1
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.
Attestation for soma_shades-1.0.1.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 27, 2026.
Transparency logA 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.