Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/andersonshatch/soma-ctrl
Node util for controlling SOMA smart shade via MQTT or HTTP
https://github.com/andersonshatch/soma-ctrl
blind bluetooth bluetooth-le btle home-assistant home-automation http mqtt nodejs soma
Last synced: about 2 months ago
JSON representation
Node util for controlling SOMA smart shade via MQTT or HTTP
- Host: GitHub
- URL: https://github.com/andersonshatch/soma-ctrl
- Owner: andersonshatch
- License: mit
- Created: 2018-02-20T20:38:38.000Z (almost 7 years ago)
- Default Branch: master
- Last Pushed: 2022-12-10T16:16:55.000Z (about 2 years ago)
- Last Synced: 2024-10-31T17:26:32.745Z (about 2 months ago)
- Topics: blind, bluetooth, bluetooth-le, btle, home-assistant, home-automation, http, mqtt, nodejs, soma
- Language: JavaScript
- Homepage:
- Size: 430 KB
- Stars: 21
- Watchers: 4
- Forks: 6
- Open Issues: 18
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
# SOMA Blind Controller Util [](https://badge.fury.io/js/soma-ctrl)
Util for controlling SOMA smart shade, either over MQTT or via a HTTP API
# Requirements
- SOMA smart shade device that has been configured with the SOMA app
- Bluetooth 4.0 LE hardware
- OS supported by [noble](https://github.com/abandonware/noble) (I've only tested on macOS and Raspbian)
- Node 8.16.1 or higher (Tested on Node 12.10.0, 11.15.0, 10.15.2, 9.11.2, 8.16.1)
- (Potentially a Bluetooth stick to itself, if you're using some other Bluetooth software, see [#59](https://github.com/andersonshatch/soma-ctrl/issues/59#issuecomment-497662843))
# Installation
Run `npm install -g soma-ctrl`
# Usage
`somactrl` by itself will print usage information
By default, device scanning will be active for 30 seconds, and any supported ones will be connected to.
You may optionally:
- Alter the device scanning timeout, e.g. scan for 60 seconds: `somactrl -t 60`
- Specify the number of devices you expect to connect to, e.g. 4 devices expected: `somactrl -e 4`
- Manually specify a list of device IDs to connect to, e.g. connect to RISE108 and RISE117: `somactrl RISE108 RISE117`
- Manually specify a list of MAC addresses to connect to, e.g.: `somactrl f5:11:7b:ee:f3:43`
You must then specify options to use either MQTT, HTTP or both
## To use with HTTP
Specify a port for the API to listen on with `-l`:
`somactrl -l 3000`
## To use with MQTT
Specify a broker URL with `--url` option:
`somactrl --url mqtt://yourbroker` (mqtt/mqtts/ws/wss accepted)
Username and password for MQTT may be specified with `-u` and `-p` option
If no password argument is supplied, you can enter it interactively
Base topic defaults to `homeassistant`, but may be configured with the `-topic` option
# MQTT
For each device connected, data will be published to the following topics:
`/cover//position` - position
`/cover//connected` - `connected` or `disconnected`
`/cover//battery` - battery level
To issue commands:
Move: `/cover//move` - message: int position between 0 (closed) and 100 (open)
Stop: `/cover//move` - message: 'stop'
Identify (beep device): `/cover//cover//config` will be set to, e.g.:
```
{
"name": "Living Room1",
"availability_topic": "homeassistant/cover/RISE148/connection",
"payload_available": "connected",
"payload_not_available": "disconnected",
"position_topic": "homeassistant/cover/RISE148/position",
"set_position_topic": "homeassistant/cover/RISE148/move",
"command_topic": "homeassistant/cover/RISE148/move",
"payload_open": 100,
"payload_close": 0,
"unique_id": "soma_RISE148_cover",
"device": {
"identifiers": "soma_RISE148",
"name": "RISE148",
"manufacturer": "Soma",
"model": "Smart Shade"
}
}
```
To automatically setup a battery sensor:
`/sensor/cover__battery/config` will be set to, e.g.:
```
{
"name": "Cover battery",
"state_topic": "/cover//battery",
"unit_of_measurement": "%",
"device_class": "battery",
"unique_id": "soma__battery",
"device": {
"identifiers": "soma_RISE148",
"name": "RISE148",
"manufacturer": "Soma",
"model": "Smart Shade"
}
}
```
## Parameters
`` has format `RISEnnn` or the device's MAC address in lowercase, with the colon's stripped out and cannot be changed
`` will be the device name (as configured in the app) with spaces replaced by underscores
# HTTP Endpoints
`GET /`: list devices.
Response type: `[String : Device]` - ID as String key, Device as value
```
{
"RISE148": {
"id": "RISE148",
"battery": 29,
"batteryLevelLastChanged": "2018-05-03T17:14:10.590Z",
"position": 0,
"positionLastChanged": "2018-05-03T17:14:10.320Z",
"connectionState": "connected",
"state": "closed",
"group": "Living Room",
"name": "Living Room1"
},
"RISE236": {
"id": "RISE236",
"battery": 28,
"batteryLevelLastChanged": "2018-05-03T17:14:10.497Z",
"position": 0,
"positionLastChanged": "2018-05-03T17:14:10.198Z",
"connectionState": "connected",
"state": "closed",
"group": "Living Room",
"name": "Living Room2"
}
}
```
`GET /`: Get individual device data (or 404 if no device by that ID).
Response type: `Device` example:
```
{
"id": "RISE148",
"battery": 29,
"batteryLevelLastChanged": "2018-05-03T17:14:10.590Z",
"position": 0,
"positionLastChanged": "2018-05-03T17:14:10.320Z",
"connectionState": "connected",
"state": "closed",
"group": "Living Room",
"name": "Living Room1"
}
```
`POST //identify`: Ask deviceID to identify itself (beep). Response type: `200 - OK` or `404 - Not Found`
`POST //move?position=`: Ask deviceID to move to ``. Response type: `Device` or `404`
`POST //stop`: Ask deviceID to stop moving. Response type: `200 - OK` or `404 - Not Found`
`POST //calibrateModeStart`: Enable calibrate mode on deviceID. Response type: `200 - OK` or `404 - Not Found`
`POST //moveUp`: Request device to move up. Beware that if calibration mode is enabled, the defined top position is not honoured. Response type: `200 - OK` or `404 - Not Found`
`POST //stop`: Request device to stop moving. Response type: `200 - OK` or `404 - Not Found`
`POST //moveDown`: Request device to move down. Beware that if calibration mode is enabled, the defined bottom position is not honoured. Response type: `200 - OK` or `404 - Not Found`
`POST //calibrateTop`: When in calibrate mode, set the current position as the top-most position. Response Type: `200 - OK` or `404 - Not Found`
`POST //calibrateBottom`: When in calibrate mode, set the current position as the bottom-most position. Response Type: `200 - OK` or `404 - Not Found`
`POST //calibrateModeStop`: Disable calibrate mode on deviceID. Response type; `200 - OK` or `404 - Not Found`
`POST /exit`: Quit somactrl (useful if you run with systemd and want to restart). Response type: `200 - OK`
## Parameters
`` has format `RISEnnn` or the device's MAC address in lowercase, with the colon's stripped out and cannot be changed
`` should be an integer between 0 (closed) and 100 (open)