Announcement

Collapse
No announcement yet.

SmartThings API

Collapse
X
 
  • Filter
  • Time
  • Show
Clear All
new posts

    SmartThings API

    Using Big5 HTTP I am now able to successfully send commands through the SmartThings REST API and control devices on the SmartThings hub. I am able to turn lights on/off, set levels of dimmer switches and various other things. Device response is near instantaneous. Using webCORE and JSON commands I am also able to monitor device changes on SmartThings and keep HS3 and SmartThings in sync with one another.

    Using RegEx statements I was able to keep the number of required steps for each ST device down to a minimum. One single HS3 event will either turn on, turn off or set dim level for a device on SmartThings. No need to create multiple events in HS3 for each device's individual actions. My desire to be able to set dimmer levels on either platform and keep each in sync with the other required just a little RegEx magic but saved tons of time.

    When I get some extra time I'll post a "how-to" if there is any interest.

    --Barry

    #2
    Count me interested in your setup and solution. I would appreciate you sharing the setup and configuration.

    Thanks
    Billy

    Comment


      #3
      +1

      Comment


        #4
        Using the SmartThings Devices API, webCORE and Big5 you can achieve 2 way communication between Homeseer HS3 and SmartThings. In this tutorial I am going to assume that you already have a SmartThings IDE account and you have installed the webCORE smartapp for SmartThings. webCORE is the event engine we will use to get device status updates from SmartThings. Working with webCORE takes a bit of getting used to, but once you learn your way around it you will find it is a very powerful program with an excellent design and layout. It should also be noted that my system is running on Windows Server 2016 and I haven't tested any of this with any other operating system, but I see no reason it shouldn't work the same.

        I will being using the program Postman for easier illustration purposes. Postman is a free API Development app and you can download it here.

        First thing you need to do is get an API personal access token from SmartThings by going here. Unlike smartapp access tokens that expire every 30 days, personal access tokens are good for 50 years. Choose all available fields on the token permissions form, generate your token and save it to Notepad locally. You won't be able to see it again after you leave the page. You'll be using this access token in Big5 HTTP profiles.

        Next we will open Postman and retrieve a list of all devices on the SmartThings hub. In the Postman window, select GET and paste in this SmartThings API address:

        Code:
        https://api.smartthings.com/v1/devices
        Go to the Authorization section, choose Bearer Token from the drop down list and a new form field will open to the right. Paste your access token in the field. Click Send in the top right and you'll see below a JSON response from SmartThings that contains a list of all your devices.

        Click image for larger version  Name:	postman_example.png Views:	3 Size:	120.2 KB ID:	1273534

        Congratulations, you just sent your first API REST request to SmartThings!

        The "deviceId" is what we are after here for each device that you want to control remotely. We will use the deviceID later to remotely control devices from Homeseer to SmartThings.

        To get more information about a particular device, do another GET command using this address and the deviceId for the device:

        Code:
        https://api.smartthings.com/v1/devices/{PASTE THE DEVICEID HERE AND REMOVE BRACES}
        You can test control now by using Postman and doing a Post request. Pick a switch or an outlet from the list you want to control. In the Postman address bar change from Get to POST in the drop-down list. Use this address:

        HTML Code:
        https://api.smartthings.com/v1/devices/{PASTE THE DEVICEID HERE AND REMOVE BRACES}/commands
        In the Body section, select the Raw option and JSON (application/json) in the drop menu. In the Body section below past this command code:

        Code:
        {
        "commands": [
            {
                "component": "main",
                "capability": "switch",
                "command": "on"
            }
        ]
        }
        Next click Send to execute the command.

        Click image for larger version  Name:	post_example.png Views:	1 Size:	117.1 KB ID:	1273537


        That's it! Your device should have responded by turning on. Change the command to "off", resend and it should turn off. Note in the response field below the only response you'll get back from SmartThings is a "Status: 200" and "{ }". This indicates SmartThings received the Post request and it was a good request (meaning your syntax was proper). It does not serve as a confirmation that the command request was executed.

        In the next post I will go through how to set up webCORE to communicate with Homeseer.

        --Barry

        Comment


          #5
          Next we'll create a "Piston" in webCORE to send device status updates to Homeseer using JSON. A Piston in webCORE is equivalent to an event in Homeseer.

          First create a virtual device in Homeseer that represents the device you are wanting to sync from SmartThings to Homeseer. (Note to the plugin developer Ivan: Because of the way the Big5 plugin creates new devices, manually creating a virtual device in Homeseer is necessary, particularly for devices that are status only devices without controls (example, water leak sensor). This is due to a limitation of JSON commands available for Homeseer. If not for this we could simply create a HTTP profile in Big5 and directly import the devices from SmartThings using the the procedures from my first post. The "device creation type" is something you may consider changing within the plugin.)

          For this example I will use a Leviton Wifi Switch that is controlled by SmartThings. Leviton makes some of the best wifi switches on the market but unfortunately are not supported by Homeseer. Until now.

          Create the virtual switch in Homeseer and accept the default device status values of 0 for off and 100 for on. Make note of the reference id of the new virtual device you just created.

          Open webCORE in a browser and choose "New Piston" in the left navigation pane. Give your Piston a name and click Create.

          Click image for larger version  Name:	new piston.png Views:	1 Size:	142.8 KB ID:	1273665

          On the next screen open the "Options" menu from the right side navigation and choose "Show Restrictions".

          Click image for larger version  Name:	show restrictions.png Views:	1 Size:	34.6 KB ID:	1273666


          Next click on "add a new restriction" under the "only when" section:

          Click image for larger version  Name:	new restriction.png Views:	1 Size:	9.5 KB ID:	1273667

          Here we are going to add a restriction that prevents this piston from executing if it has already executed within the last 3 seconds. This prevents a loop from forming between SmartThings and Homeseer, similar to microphone feedback.

          Click image for larger version  Name:	restriction screen.png Views:	1 Size:	37.5 KB ID:	1273668

          Next, click on "add a new statement", and then click "add an if statement", and then click "add a condition". Now choose your device and "changes to" and "off" as the trigger.



          Notice how webCORE is building the code for us. We already have the restrictions and a simple "if" statement:

          Click image for larger version  Name:	code example.png Views:	1 Size:	20.0 KB ID:	1273670

          continued...

          Comment


            #6

            Next click on "add a new statement" under the "then" section. Then choose "Add an Action". On the next screen simply accept the default device "Location" by clicking "Add a Task".



            Under "Do" choose "Make a Web Request".



            On the next screen we will specify where webCORE needs to send a GET request to, which is your Homeseer server address, and to use the JSON command "controldevicebyvalue". Use the below URL and put in your own Homeseer IP address and port number (usually 80). For the "ref" part of the URL replace the XXX with the reference id of the virtual device you created in Homeseer.

            Code:
            192.168.X.XXX:80/JSON?request=controldevicebyvalue&ref=XXX&value=0
            Mine looks like this:



            Next under the "Else" section, click "add a new statement" and then "Add an if", and then "Add a condition". Then simply repeat the above steps for "on" instead of "off".



            This time change the command value at the end of the JSON string from 0 to 100 for "on".

            [CODE]192.168.X.XXX:80/JSON?request=controldevicebyvalue&ref=XXX&value=100[/CODE]




            Your Piston code should now look like this:




            That's it! Now every time the device value changes on the SmartThings Hub it will send a JSON push notification to Homeseer via your webCORE piston. Give it a try by changing the device in SmartThings and you should see it updated near instantly in Homeseer.

            In the next post I'll show you how to complete the loop using Big5. This will allow you to control the device from Homeseer by sending API commands via Big5 to SmartThings.

            --Barry

            Comment


              #7
              Hi, logman . You have a v2 hub or a v3? Not sure about this, but I think the v3 has lower specs than the v2?

              Comment


                #8
                Originally posted by MattLau View Post
                Hi, logman . You have a v2 hub or a v3? Not sure about this, but I think the v3 has lower specs than the v2?
                I'm using the v2. I've got a v3 sitting in the server room on idle that I've never got around to deploying.

                --Barry

                Comment


                  #9
                  Thanks

                  Comment


                    #10
                    In this post I'll show you how to set up a Big5 HTTP profile for your SmartThings managed device and set up an event that will send change notifications to SmartThings for when our SmartThings Virtual Switch is changed in Homeseer.

                    First let's set up our HTTP profile. Go to Big5 Configuration and then to the HTTP Profiles section. Create a new HTTP profile using the POST method pointing towards this URL containing the deviceID that you are wanting to control:

                    Code:
                    [B]https://api.smartthings.com/v1/devices/{PASTE THE DEVICEID HERE AND REMOVE BRACES}/commands[/B]
                    In the Extra Headers field, we need to pass our Bearer Token:

                    Code:
                    [B]Authorization:Bearer {PASTE YOUR PERSONAL TOKEN HERE AND REMOVE BRACES}[/B]
                    Toggle the "Locked" field and enter "False" in the Device Create Expression field because we don't want this profile creating a new device (we've already done this earlier when we created the virtual device in Homeseer). Click "Save" to create and save the profile.

                    Your profile should look like this when you are done:

                    Click image for larger version  Name:	profile.png Views:	1 Size:	54.4 KB ID:	1274696


                    Now we'll create an event that uses our Big5 HTTP Post profile to send status change updates to SmartThings via the SmartThings Commands API.

                    Create a new event in Homeseer and for the Trigger choose "This Device Changes and becomes", then select your virtual SmartThings device, and then choose "Any Value". We are not worried about "On" or "Off" because we are going to handle either status change with this one event.

                    Now for the action choose "Big5 HTTP". From the window that opens choose the HTTP profile that you just created from the drop-down. In the message field use this command with the included RegEx statement:

                    Code:
                    { "commands": [ { "component": "main", "capability": "switch", "command": "${ If(val[B]XXX[/B] > 0, "on" , "off") }" } ] }
                    The bold "XXX" within the RegEX statement must be replaced with the reference id of your SmartThings virtual switch, which in my case is "139"...

                    Click image for larger version  Name:	Big5 Event2.png Views:	1 Size:	69.2 KB ID:	1274697

                    Note: All spaces, braces, brackets, colons and quotes as exactly shown are necessary or you will get an error back from the SmartThings API server.

                    The command string in the message box contains a boolean true/false regular expression that tells Big5 to send the command "On" if the virtual device has a value greater than 0; Else send the command "Off" (value if true, value if false). This RegEx statement relieves you from having to create 2 separate events to sync on/off.

                    Next, under Event Options choose "Cannot Re-Run For 3 Seconds" to prevent a "Feedback Loop" from forming between SmartThings and Homeseer. Click Save and you're done!

                    Anytime you control the SmartThings virtual device in Homeseer the above Big5 event will fire off an API call to SmartThings, which will update the new device status within SmartThings.

                    This completes the circle so you can now control a SmartThings managed device from Homeseer, and vice-versa.

                    In my next post I'll show you how to slightly modify the above procedures to control a dimmer switch, and how to pass dimmer values back and forth between SmartThings and Homeseer.

                    --Barry


                    Comment


                      #11
                      logman Thanks for the great tutorials and congratulations on the solid grasp of the complex and versatile Big5 functionality. Furthermore, Samsung is not a company that can be ignored. I think that whoever masters the Samsung's SmartThings will be at the forefront of the technology and soon will see HS3 cooking, vacuuming, making coffee, doing laundry, keeping refrigerator inventory, locking doors, etc.

                      Comment


                        #12
                        Originally posted by risquare View Post
                        logman Thanks for the great tutorials and congratulations on the solid grasp of the complex and versatile Big5 functionality. Furthermore, Samsung is not a company that can be ignored. I think that whoever masters the Samsung's SmartThings will be at the forefront of the technology and soon will see HS3 cooking, vacuuming, making coffee, doing laundry, keeping refrigerator inventory, locking doors, etc.
                        Samsung definitely has their stuff together in a tight ball, no denying that. They have the money and the talent to throw at whatever they decide is worth pursuing. They usually aim their efforts towards products for the masses where than can count their unit sales in the millions. Thus you have the SmartThings hub. It's a great little setup for 80% of the home automation market. And they are smart enough to give devs the tools to target the other 20% that consists more of the "enthusiasts" crowd.

                        Every company introducing a new smart home product sets their top 5 priorities as a Smart App and then integration with Alexa, SmartThings, IFTTT and Google Home... Usually in that order. Having the ability to port ST devices to HS3 keeps you from being at the mercy of HS3 or plugin devs, wondering when someone will hopefully get around to developing a plugin for the latest toy you are interested in.

                        SmartThings also has a 1st class Zigbee controller built in and they offer some very nice and affordable Zigbee devices. In an upcoming post I'll show how to map ST Zigbee devices to Homeseer using a webCORE routine.



                        --Barry

                        Comment


                          #13
                          I will definitely test this when i got some time ! thanks logman

                          Comment


                            #14
                            that make me think... I Would be able to automate some things on my moms HUb v2 LOL. If i go that route I won't go to far since we live 30 minutes apart.)

                            But simple things like . Alexa turn on X at my mom's place . ( when i come to visit her).

                            or when i am near her house ( with geophency) ( or at her city) , then do something


                            Comment


                              #15
                              What abilities does the ST hub offer the enhance homeseer? Not requiring the cloud of course and so you have to allow Samsung j to your house? Feel like I signed my life away with their tv

                              Comment

                              Working...
                              X