Soma Smart Shades (HTTP API) Device Handler HELP required!

chippie · October 9, 2019, 3:39pm

Hi Guys,

Not been around for quite a while so very rusty Hope we are all doing well!?!

I have some Soma Smart Shades around the house and have just seen on their website that they have finally released the API (beta). I was wondering/hoping if someone, hopefully who has the units and Soma Connect (BT/WiFi Bridge) could take a look and see if it would be possibe to create a DH based on what they have released please.
It is just a little above me and been out the game for quite a while now.

Soma HTTP API

Thanks!

sidjohn1 · October 10, 2019, 3:36am

Yes, or you can use core/webcore to send the http commands

chippie · October 10, 2019, 3:28pm

Thanks!

Is it easy to create a DH. I do not use Core much these days, well not at all. Would be great to be able to just have a DH to integrate the blinds into ST compltely.

nix · May 18, 2020, 10:58am

Hi Mark

I also have some Soma Smart Shades and a SmartThings hub so I took your post as a challenge to learn how to write a SmartThings Device Handler (and more fundamentally the Groovy language).

It took me a bit longer than I’d hoped due to physicalgraph.device.HubAction being way harder to use (and poorly documented) than you’d expect. Along the way I think I’ve found a couple of bugs in the Soma API which I’ve reported to support, as well as a few places where the API could be easily improved to make it more useful (eg. returning the Shade MAC in all responses)

This DTH is still a work in progress and which I hope to improve on as and when I have time. As of today it doesn’t yet have an associated SmartApp for the Soma Connect “Hub” and only supports a single Shade MAC so if you have multiple shades you’ll need to pick one for testing for now.

Please note that you need to configure the Soma Connect IP address and Shade MAC in the DTH preferences after you create the device from the SmartThings Web UI.

Let me know what you think:

github.com

peternixon/SmartThings-PeterNixon/blob/master/devicetypes/peternixon/soma-smart-shades.src/soma-smart-shades.groovy

/*
*  SOMA Smart Shades
*  Category: Device Handler
*
*  List of SOMA Connect API endpoints is as follows (https://support.somasmarthome.com/hc/en-us/articles/360026064234-HTTP-API):
*    /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.

This file has been truncated. show original

Garrett_Banker · May 22, 2020, 6:26pm

It seems to be working for me. So why does it only work for one device? I’m just curious where the limitation is from.

nix · May 28, 2020, 6:34am

Hi Garrett
There a few reasons why my DTH doesn’t (yet) work with multiple blinds in no particular order:

I’m writing this in my spare time and learning both Groovy and the SmartThings APIs as I go along.
It was easier to treat the Soma Connect (bridge) plus a single blind as one device until I had the basics working. I’ve now started work on a “composite device” in a branch in my git repo. I’ll definitely merge it back to the master if and when I can get it all working.
Then there are some technical issues which I’ve hit:
** The SmartThings physicalgraph.device.HubAction seems to be asynchronous (which is normally a good thing) in a way that completely disconnects the request from the response so if you send two separate status queries to the Soma Connect Bridge for two different blinds, you get two different responses as asynchronous “events” and you have no way of understanding which response came from which blind (at least that I can find. If anyone can help with this it would be great!)
** The SOMA Connect API doesn’t include the blind Name or MAC address in several of the API response, so this can’t (yet) be used to work around the above issue. (I’ve requested that SOMA extend their JSON to include this information and they have agreed to do so in some future release…) I’m in the process of testing custom callbacks as a possible solution for this also…
** There also appears to be an outright (and long standing) bug in SmartThings physicalgraph.device.HubAction which causes all responses to go missing unless you have very particular DNIs. (eg. See Device Handler not receiving HubAction to parse())
** Due to the above issue, at present, the issue I have with trying to get a Composite device working is that all responses from any child device arrives as events to the parent which is not at all what I’d expect! (Although I see that some other DTH/SmartApp combinations work this way)
Now it’s possible that I’m making some basic mistake, or that there is a simple work around but I’ve done a lot of trolling through this site and many Google searches as well as several weekends of trial and error coding and I’m afraid that I still haven’t managed to crack this (multiple shade issue) fully. If and when I do, I’ll update here, but in the meantime, any and all suggestions are appreciated!

chippie · May 28, 2020, 1:02pm

Hi guys,

We have had this running with multiple blinds since December. You just have to go by MAC address of each bind unit.

I started the DH off but a very clever chap @wookierama cracked on with it and got it running extremely well. We were on Soma build 2.0.6 from memory.

I have tagged him above as it is not really my DH to hand out and have not been able to do any more on it as I fell extremely unwell at the end of December, in hospital and just back to being able to walk a little the last week, literally.

I am hoping he will pick up on the tag and join us here. But his DH does work with multiple blinds or at least did back in December as we tested it thoroughly.

Would be good to get it moving again, if anything to take my mind of the pain for a little while LOL

nix · May 29, 2020, 2:09am

Hi Mark

Well, that’s somewhat disappointing news that someone has developed a DTH but not posted it , but on the other hand it’s been an interesting project for me. It’s good news that it is possible to get all the functions working with multiple blinds, I clearly just need to do a bit more learning

chippie · May 29, 2020, 3:47am

Hi.
As mentored, I fell extremely unwell. It was not a conscious decision. The gentleman that did most of the work was not involved in this thread at all and I have no idea if he even has smartthings anymore yet alone the blinds. Just have to wait for a reply or until I’m able to move a little more.

Thanks.

nix · May 30, 2020, 7:51am

Hi Mark
That’s fine. At this point, I have basically all of the code written but am stuck on how to get the events for child devices (the shades/blinds) to show up correctly in the child device handler as they all return to the parse() handler in the parent device handler (ie. the SOMA Connect bridge). I’m guessing I only need to change a couple of lines but I haven’t worked out which ones

wookierama · May 30, 2020, 10:19am

Hey nix, sounds like you’ve done a great job with the Soma!

Apologies for not posting my device handler earlier, I got it to the stage where I was happy with its functionality but the UI in the smartthings app needed some work. I wanted to have it looking tidy before posting, but things have been crazy since that point and I havent had the headspace to finish it off (I live in Australia and we were smashed by bushfires late last year for a few months immediately followed this COVID business we are all in the middle of).

But it’s great to hear you have been working on a DH for the Soma and I hope I can still help you out. I havent looked at it since last year, so I cant recall all the details, but the issues you have described sound like the same things I came across. I did pass on the feedback to Soma who said they were working on integration with ST but I havent seen anything come of that yet.

You can find my code here:

Feel free to use my DH as is, use some of the code for your project, or if you prefer you could build on top of mine. Id be more than happy to collaborate with you if you were interested, but full disclosure I primarily code in Python and worked out just enough Groovy to get the job done! I was pretty happy that it had as much functionality that could be reasonably achieved via the Soma API, and I just wanted to tidy up the UI for the smartthings app. I had been using some icons and layout from a DH that A4refillpad had made for the Ikea blinds as a template to get started, and I wanted to confirm he was fine with us using his icons before posting the DH on the forum.

I only have one Soma, and it wasnt until Mark started using this DH that we realised it wouldnt support multiple devices. It took a bit of digging, but I did end up finding a way to get it to support this. Best to look at the code as Im sure you are intimately familiar with the Soma API now!

I recall there were various improvements that Mark and I would have like to implement, but as you would have found out the Soma API is quite limited (unless it has been updated since last year). From memory if you open the blinds but issue a stop command part way through, it will report the blinds as being 100% open rather than the position that you stopped it at. Small things like this made it hard to have a slick UI for it.

You mentioned the challenge parsing responses, and I recall this was an issue for me too. I ended up changing the method I initially used to capture the responses in order to support multiple devices, and if you are interested you can browse back through my commits to see what I originally did.

Hope this helps, and please let me know if you have any questions (although Im a little rusty on what I did).

Cheers,
Ben

nix · May 30, 2020, 10:39am

Hi @wookierama

I literally just got my DTH mine working again after restructuring it into a composite device an hour before you responded. You can see my code on the composite_device branch at:

Having said that, I will sit down now and have a look at how you’ve done things to see if I can learn something as my language of choice is also Python and this is my first ever project in Groovy so it’s been a bit of a learning curve

Cheers
Peter

wookierama · May 30, 2020, 10:50am

Ha, nice work @nix , way more rewarding to push through and find a solution yourself. Im interested to see what you’ve done, although Im a little rusty now.

nix · May 30, 2020, 11:01am

Hi @wookierama (& @chippie)

Now that I’ve had a look through Ben’s code, I can see that he solved the multiple shade issue with a callback handler which is also the approach I had established as the solution to the problem (after many hours of reading this forum) but didn’t end up implementing as I received the 2.0.12 firmware from the team at Soma who very kindly added the “mac” field into all JSON responses that didn’t previously have it thereby allowing me to treat the SOMA Connect API responses as if they truly were “unconnected” events that just happen to land in the parse() function. The version of my DTH on the composite_device branch therefore requires version 2.0.12 as a minimum.

The things I have been working on over the last few days which your DTH currently does not implement is the whole “composite device” concept, which means that there is a separate parent DTH for the Soma Connect “bridge” and then a child DTH for the shade(s). The parent DTH discovers all the shades attached to the bridge and creates each device automatically in a similar manner to the way the Philips Hue DTH discovers and creates separate devices for each attached bulb. This means that you do not need to care about the Mac address(es) of the shades…

In addition, I’ve implemented a separate Service Manager SmartApp which is the only “thing” which needs configuration (ie. the IP address of the Soma Connect) which it asks you for when you add the SmartApp on your phone.
I’m attempting to do away with this configuration step also by implementing network autodiscovery (Hue, Sonos etc do this to) but at present I haven’t yet managed to get SmartThings to correctly do Bonjour discovery (which SOMA recently added support for), while SSDP discovery (which definitely works in ST) isn’t (yet) supported by Soma. The good folk at Soma have said that they will take a look at adding SSDP support, but in the meantime you’ll still need to know the IP of your Connect.
I’m also thinking of adding support for multiple Soma Connects for people with large houses but I don’t have a second one at present so it’s still on the todo list.
@wookierama I may nab a few small snippets of code from your DTH, but on the whole I think mine is now way more “complete” feature wise, albeit at this point in time the code on the branch is still a bit of a mess so you might want to hold off on trying it out until I have a couple of extra hours to clean it up and merge back into the code master.
Cheers
Peter

wookierama · May 30, 2020, 11:21am

That sounds awesome @nix, great to hear you’ve gone the composite device approach which it really needs for anyone with multiple devices. I’ll definitely be trying this out soon once you’re happy with it, you’ve taken this way further than my initial efforts!

Good to hear the team at Soma have been so responsive, that will really help getting the the devices integrated with ST.

Cheers,
Ben

chippie · June 1, 2020, 11:59am

@nix @wookierama

Hi Peter,

Thank you for the replies and thank you Ben for jumping in.
I am only able to get on occasionally and am really looking forward to what you both manage to cook up together (at a distance though ).
Not really in a great position to help with any coding but have 3 Soma devices here so happy to help with any testing as and when or if required. With my current situation the ST integration with Soma is such a great help.

Thank you both again! Stay safe and well out there, it is still not over

Looking forward to the updates.

Mark.

nix · June 2, 2020, 2:22pm

I’ve spent the last two days trying to figure out why some buttons were (always) timing out even though the associated action and event is fired correctly, only to figure out that it all works perfectly in the SmartThings Classic app (I’m not sure if I’ve hit rate limits or other guardrails in the new app or if there’s another issue).
While troubleshooting this issue I moved a bunch of code around (as I thought it might have been a Parent:Child DTH issue) but I was also adding features as I went so I have some cleanup to do, but the code is basically feature complete, albeit a bit messy.

I am therefore throwing it out there and asking for testers and comments. The features it has are:

A SmartApp “Service Manager” which asks for the SOMA Connect IP address upon installation. This is the only mandatory configuration in the whole solution.
A Parent Device Handler to deal with communication with the SOMA Connect bridge, and enumerate the shades attached to the bridge.
A Child Device Handler for the Shades. This is used to create an additional device for each shade attached to the bridge and includes the following features:
** Open/Pause/Close of the Shade (as well as On/Off for backwards compatibility)
** Preset Position button (Defaults to 50% open but is configurable per shade)
** Position Slider to adjust the shade position manually
** Battery status in Volts and Percentage
** Refresh Status button

I’ve tested all features with two shades but I have no reason to believe that it won’t work with more. I’ve not yet tested with multiple SmartThings hubs but I will when my second hub arrives later this week. I haven’t implemented (yet) support for multiple SOMA Connect bridges.

Basic install instructions are to add https://github.com/peternixon/SmartThings-PeterNixon as a git repo in your SmartThings dashboard and install the SmartApp and both device handlers found there, then add the SmartHandler from the ST app on your phone. If you want to do it the hard way the three files are at:

github.com

peternixon/SmartThings-PeterNixon/blob/master/smartapps/peternixon/soma-smart-shades-service-manager.src/soma-smart-shades-service-manager.groovy

/*
*  SOMA Smart Shades Service Manager
*  Category: SmartApp Service Manager
* 
*/

definition(
    name: "SOMA Smart Shades Service Manager",
    namespace: "peternixon",
    author: "Peter Nixon",
    description: "Creates a SOMA Smart Shades Device..",
    category: "My Apps",
    iconUrl: "https://github.com/chancsc/icon/raw/master/standard-tile%401x.png",
    iconX2Url: "https://github.com/chancsc/icon/raw/master/standard-tile@2x.png",
    iconX3Url: "https://github.com/chancsc/icon/raw/master/standard-tile@3x.png",
    singleInstance: true
    )

preferences {
	input("bridgeIp", "text", title: "SOMA Connect IP", required: true)

This file has been truncated. show original

github.com

peternixon/SmartThings-PeterNixon/blob/master/devicetypes/peternixon/soma-connect-bridge.src/soma-connect-bridge.groovy

/*
*  SOMA Connect
*  Category: Device Handler
*
*  List of SOMA Connect API endpoints is as follows (https://support.somasmarthome.com/hc/en-us/articles/360026064234-HTTP-API):
*    /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.

This file has been truncated. show original

github.com

peternixon/SmartThings-PeterNixon/blob/master/devicetypes/peternixon/soma-smart-shades.src/soma-smart-shades.groovy

/*
*  SOMA Smart Shades
*  Category: Device Handler
*
*  List of SOMA Connect API endpoints is as follows (https://support.somasmarthome.com/hc/en-us/articles/360026064234-HTTP-API):
*    /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.

This file has been truncated. show original

Enjoy

Peter

rfus76 · June 3, 2020, 10:26am

Hi thank you for the upload
I’ve installed the smart app and two device handlers
I’ve set up the soma hub and have it added in st
But I can’t see the blinds anywhere
What am I missing

Thanks once again

nix · June 3, 2020, 11:20am

Hi @rfus76

Using the new ST app, after pulling the groovy files into your workspace from my git repo and publishing them, all you need to install is the “SOMA Smart Shades Service Manager” from your phone and give it the (static) IP of your SOMA Connect. In the debug log it should get as far as:

installed() Soma Connect with settings [bridgeIp:192.168.xxx.yyy]

At that point you should have a new device called “SOMA Connect” which should log as far as:

My attached (child) devices are: [Room 1 shade, Room 2 shade, Room N shade]

At that point you should have addition shade devices for the ones that it’s discovered emitting their own logs like:

55f7ec13-6574-4396-9cb1-07e8778e86d1 9:12:10 PM: debug windowShade: closed
55f7ec13-6574-4396-9cb1-07e8778e86d1 9:12:10 PM: info SOMA Shade Position for e4:cf:3c:f1:91:4c is: 0
55f7ec13-6574-4396-9cb1-07e8778e86d1 9:12:10 PM: debug received JSON from parent DTH: [mac:e4:cf:3c:f1:91:4c, position:100, result:success, version:2.0.12]
55f7ec13-6574-4396-9cb1-07e8778e86d1 9:12:10 PM: info Checking shade battery level…
55f7ec13-6574-4396-9cb1-07e8778e86d1 9:12:10 PM: info Checking shade position…
55f7ec13-6574-4396-9cb1-07e8778e86d1 9:12:10 PM: info Device ID: E4CF3CF1914C refresh() was triggered
55f7ec13-6574-4396-9cb1-07e8778e86d1 9:12:10 PM: debug updated()
55f7ec13-6574-4396-9cb1-07e8778e86d1 9:12:10 PM: debug windowShade: unknown
55f7ec13-6574-4396-9cb1-07e8778e86d1 9:12:10 PM: debug installed() Shade with settings [:]

Let me know how far you are getting in this process…

PS. Please make doubly sure that you are running SOMA Connect Firmware 2.0.12 (or later) and have a static IP assigned to it.

Cheers
Peter

rfus76 · June 4, 2020, 10:44am

Thank you so much for the help
It was my fault I didn’t have the newest firmware installed on the soma connect
I had to go into my devices and select the other soma smart shade in the list fir the blinds to connect
Is there a way to change the icon to a blind icon ?
Thanks again for your help and code
Its greatly appreciated

Soma Smart Shades (HTTP API) Device Handler HELP required!

Customers

Developers

Download the SmartThings App