Copyright © 2021-2022 Erik Baauw. All rights reserved.
This Homebridge plugin exposes to Apple's HomeKit: SOMA Smart Shades 2 and SOMA Tilt 2 devices, using the native Bluetooth Low Energy (BLE) interface to communicate with the devices.
Using BLE from NodeJS proves to be quite challenging, see Bluetooth Low Energy (BLE) below. Consequently, I expect this plugin to work only when running on a Raspberry Pi. If you don't want to run a Raspberry Pi, check out Homebridge SC, which uses the SOMA Connect instead of BLE to communicate with the SOMA devices.
Homebridge SOMA provides the following features:
-
Automatic discovery of SOMA devices.
-
Each device is exposed as a HomeKit accessory with a Window Covering, a Light Sensor, and a Battery service. Each trigger is exposed as a separate custom Resource service.
Note that Current Ambient Light Level currently reports the raw value as reported by the solar panel. -
The Window Covering service carries additional custom characteristics:
- Close Upwards (for Tilt devices): indicates whether the blinds are (to be) tilted upwards;
- Morning Mode (not yet implemented): move the device slowly, making less noise;
- Last Seen: updated (once a minute) as BLE advertisements are received;
- Motor Speed: to set the speed of the motor;
- Log Level: sets the level of debug messages. Note that Homebridge debug mode must be enabled for level 2 and above;
- Heartrate: sets the polling rate;
- Restart: restart the device.
-
The Light Sensor service carries additional custom characteristics:
- Last Updated: updated when the device is polled;
- Sunrise: the sunrise time, as computed by the device;
- Sunset: the sunset time, as computed by the device.
-
Each Resource service carries custom characteristics:
- Enabled: to enable/disable the trigger;
- Resource: shows the trigger condition.
-
Current Position and Battery Level are updated from the BLE advertisements. Last Seen is updated (once a minute) as BLE advertisements are received.
-
The other characteristics are updated by polling the device. Last Updated is updated when the device is polled. The polling rate can be set dynamically using Heartrate. Issue Identify (on the Accessory Information service) to force poll the device immediately, and to play a sound on the device.
-
Keep the device clock and timezone offset in sync with the server running Homebridge, for when you don't use the SOMA Connect nor SOMA Smart Shades app.
Note that Apple's Home app doesn't support custom services nor characteristics. To use the full features of Homebridge SOMA, you need a decent HomeKit app, like Eve.
Homebridge SOMA includes two command-line tools, ble, to interact with generic
BLE devices, and soma to interact with SOMA devices specifically.
Both tools take a -h or --help argument to provide a brief overview of
their functionality and command-line arguments.
This plugin is still under development. It is my first venture into Bluetooth, so I expect some ironing before it will be stable. If you're looking for a stable plugin, check out Homebridge SC.
Still to do:
- Implement Morning Mode;
- Additional commands for
somato interact with the device from the command line and/or shell scripts.
This plugin communicates with the SOMA devices over Bluetooth Low Energy (BLE). While their Bluetooth API hasn't been published, Wazombi Labs OÜ have been very helpful providing me the information needed to expose all features of the SOMA devices.
This plugin uses Noble to interact with BLE from NodeJS. While no longer maintained by its original authors, the Abandonware community have adopted Noble. It seems to run fine on a Raspberry Pi. On macOS, discovering and monitoring a shade works, but the connection hands after the first read or write. I workaround this by reconnecting after each read or write, but I cannot seen to get notifications to work. I don't have Windows, nor Docker, nor any other container, nor VMs to test, but there seem plenty of open issues trying to run Noble on these.
Bottom line: this plugin is supported only running natively on a Raspberry Pi. Obviously, this should be a Pi with BLE hardware, such as the 4B, 3B+, 3B, 3A+, or Zero W. I have no experience using USB dongles for BLE support on older models.
If you don't want to run a Raspberry Pi, check out Homebridge SC, which uses the SOMA Connect instead of BLE to communicate with the SOMA devices.
Before installing this plugin, be sure to install Noble's dependencies:
sudo apt-get install bluetooth bluez libbluetooth-dev libudev-dev
and to allow NodeJS to access the BLE hardware:
sudo setcap cap_net_raw+eip $(eval readlink -f `which node`)
Note that this last command needs to be repeated after each update of NodeJS.
In Homebridge's config.json you need to specify Homebridge SOMA as a platform
plugin.
"platforms": [
{
"platform": "SOMA"
}
]I strongly recommend to run Homebridge SOMA isolated, in a seperate child bridge.
If you run into Homebridge startup issues, please double-check what versions of Node.js and of Homebridge have been installed. Homebridge SOMA has been developed and tested using the latest LTS version of Node.js and the latest version of Homebridge. Other versions might or might not work - I simply don't have the bandwidth to test these.
As mentioned above, I only expect Homebridge SOMA to run on a Raspberry Pi, due to issues with the Noble library for communicating with BLE devices.
If you run into Homebridge issues, please run Homebridge SOMA in a separate child bridge. This way, you can determine whether the issue is related to Homebridge SOMA itself, or to the interaction of multiple Homebridge plugins in your setup.
If you have a question, please post a message to the #soma channel of the Homebridge community on Discord.
If you encounter a problem, please open an issue on GitHub. Please enable Homebridge debug mode(using the Homebridge UI), set Log Level to 2 (using Eve), download the Homebridge log file (using the Homebridge UI), and attach it to the issue. Please do not copy/paste large amounts of log output.