Articles in this section

HTTP API

  • Updated

The HTTP API is currently made available as a beta feature, we welcome your feedback (here or send an email to support@somasmarthome.com).

Preconditions

  • 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 is valid for the Raspberry Pi based versions, for the USB version scroll down further):

  • /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. For example: http://192.168.0.104:3000/list_devices. You will need to replace the IP address part in this to whatever your Connect is actually issued in your network (IP address is the 192.168.0.104). You can use any browser - just copy and paste this into the address bar.
    • As of SOMA Connect version 2.2.6, the endpoint also returns type=shade/tilt for each device.
  • /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
    • As of SOMA Connect version 2.2.5, for SOMA Tilt devices, the endpoint returns closed_upwards = true in case the blind's closing direction is upwards.
  • /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 360 and 410. 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.
    • As of SOMA Connect version 2.2.5, the endpoint also returns battery_percentage with values in the range 0..100.
  • /get_light_level/"MAC" : This endpoint returns the current solar panel light level from the device. SOMA Connect makes a connection to the Smart Shades device to get the light level - do not overuse it / poll it too often or do not poll it on many devices at the same time.
    • This feature was added in SOMA Connect version 2.3.0
  • /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. 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.
    • As of SOMA Connect 2.2.5 there are new request parameters close_upwards = 0/1 and morning_mode = 0/1
      • close_upwards specifies the closing direction for the SOMA Tilt devices, example: http://192.168.0.104:3000/set_shade_position/dd:9b:89:47:a5:e7/100?close_upwards=1
      • morning_mode specifies if Morning Mode is to be used for moving the motor, example: http://192.168.0.104:3000/set_shade_position/dd:9b:89:47:a5:e7/0?morning_mode=1
  • /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.

API endpoints for the USB version are very similar but currently they implement parameter passing in a different way.

  • /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 along with the device type and a count of advertising packets the Connect has seen since last restart. The MAC address is needed for controlling and querying devices on other endpoints. The count of packets seen can be used to assess the signal quality on a per device basis. The more packets the Connect sees the better the connection is.
  • /get_shade_state?mac="MAC" : Returns the current position of the shade. Position is in the range 0..100
  • /get_battery_level?mac="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 360 and 410. 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. The endpoint also returns battery_percentage with values in the range 0..100 that should match what the SOMA app shows.
  • /set_shade_position?mac="MAC"&pos="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.
  • /open_shade?mac="MAC" : Endpoint to fully open the shade.
  • /close_shade?mac="MAC" : Endpoint to fully close the shade.
  • /stop_shade?mac="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"

 

Powered by Zendesk