1.0.18 • Published 2 years ago

homebridge-soma v1.0.18

Weekly downloads
-
License
Apache-2.0
Repository
github
Last release
2 years ago

Homebridge SOMA

Downloads Version Homebridge Discord verified-by-homebridge

GitHub issues GitHub pull requests JavaScript Style Guide

Homebridge plugin for SOMA devices

Copyright © 2021-2022 Erik Baauw. All rights reserved.

Note: This plugin is no longer being maintained.

This Homebridge plugin exposes to Apple's HomeKit: SOMA Smart Shades and SOMA Tilt 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. I only expect this plugin to function when running on a Raspberry Pi. Even then, the BLE connection to the SOMA devices doesn't meet my standard for reliability and I am no longer using this plugin myself.

For production, I recommend to use Homebridge SC instead, 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 and a Battery service. Each trigger is exposed as a separate custom Resource service.
    Note that Current Ambient Light Level on the Windows Covering service reports the raw value as reported by the solar panel, not the value in lux as expected by HomeKit.

  • 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;
    • Current Ambient Light Level: the raw light level as reported by the solar panel;
    • 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.
    • 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.
  • 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.

Command-Line Tool

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.

Bluetooth Low Energy (BLE)

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 reasonably well on a Raspberry Pi. On macOS, it no longer does. 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 had mixed results using USB dongles for BLE support, see issue 6.

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.

Configuration

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.

Troubleshooting

Check Dependencies

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.

Run Homebridge SOMA Solo

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.

Getting Help

I cannot help you with issues related to Bluetooth connectivity. I am no longer working on this plugin. If you have a question, please post a message to the #soma channel of the Homebridge community on Discord.

1.0.18

2 years ago

1.0.17

2 years ago

1.0.16

2 years ago

1.0.15

2 years ago

1.0.14

2 years ago

1.0.9

2 years ago

1.0.10-1

2 years ago

1.0.10-0

2 years ago

1.0.11

2 years ago

1.0.10

2 years ago

1.0.13

2 years ago

1.0.12

2 years ago

1.0.8

2 years ago

1.0.7

2 years ago

1.0.6

2 years ago

1.0.5

2 years ago

1.0.8-0

2 years ago

1.0.5-3

2 years ago

1.0.5-2

2 years ago

1.0.5-1

2 years ago

1.0.4

2 years ago

1.0.3

2 years ago

1.0.5-0

2 years ago

1.0.2

2 years ago

1.0.1

2 years ago

1.0.0

2 years ago

1.0.3-1

2 years ago

1.0.3-0

2 years ago

1.0.2-1

2 years ago

1.0.2-0

2 years ago

1.0.0-5

2 years ago

1.0.0-6

2 years ago

1.0.0-4

2 years ago

1.0.0-3

2 years ago

1.0.0-1

3 years ago

1.0.0-0

3 years ago

1.0.0-2

3 years ago

0.0.14

3 years ago

0.0.13

3 years ago

0.0.10

3 years ago

0.0.11

3 years ago

0.0.12

3 years ago

0.0.9

3 years ago

0.0.8

3 years ago

0.0.7

3 years ago

0.0.5

3 years ago

0.0.4

3 years ago

0.0.6

3 years ago

0.0.3

3 years ago

0.0.2

3 years ago

0.0.1

3 years ago

0.0.0

3 years ago