The HTTP API is currently made available as a beta feature, we welcome your feedback (here or send an email to firstname.lastname@example.org).
- SOMA Smart Shades / SOMA Tilt devices have been set up in the Smart Shades app
- Install latest version of SOMA Connect following the instructions here
- SOMA Connect has been connected to the network using Wi-Fi or ethernet cable
- SOMA Connect local IP address is known
The HTTP API responds to GET requests on port 3000 on the SOMA Connect local IP address. At the moment the API does not need any credentials and is not secured in any way. We recommend to only use the API locally and not expose it to the internet.
Response data is JSON encoded.
List of API endpoints is as follows (this may change without notice for now):
- /list_devices : This endpoint will return a JSON encoded list of all shades this SOMA Connect has seen since last restart. For each entry in the list a name and a MAC address will be provided. The MAC address is needed for controlling and querying devices on other endpoints.
- /get_shade_state/"MAC" : This endpoint needs a MAC address from the list. The MAC address can be copied in the format it appears in the list (for example: http://192.168.0.104:3000/get_shade_state/dd:9b:89:47:a5:e7). This will return the current position of the shade. Position is in the range 0..100. This endpoint will make a request to the device over BLE so it may take a few seconds to come back depending on signal strength and distance to device.
- /get_battery_level/"MAC" : This endpoint returns the current battery level from the device. The battery level is in units of 10 mV. The battery level should usually be between 420 and 320. Anything under 320 is critically low. The device itself considers 360 the minimum to move the motor - anything under this will reject all motion commands. This endpoint will make a request to the device over BLE so be patient if the device is far from the Connect.
- /set_shade_position/"MAC"/"position" : This endpoint will send a position update (move) command to the device addressed. Position should be a value between 0..100. This will return as soon as the command is sent - it will not wait for the motion to end and the endpoint to be reached. The position value in the state endpoint will also be updated immediately so currently there is no way to tell when the shades have reached target positions.
- /open_shade/"MAC" : Endpoint to fully open the shade.
- /close_shade/"MAC" : Endpoint to fully close the shade.
- /stop_shade/"MAC" : Endpoint to stop the shade immediately.
There is a Python 3 wrapper library in the works as well. Current version can be downloaded from PiP.
"sudo pip install pysoma"