How to generate Endpoint URLs for switches with information from ThingLayer

Developer Programs Writing Device Types
1

This process always seems to come up every few weeks. Instructions appear in varies places using various methods. This method has worked for me to get URL Endpoint control of my switches/dimmers.

Also make sure there are not quotation marks at the beginning/end of the URL.

  1. Here is the SmartThings link to the ThingLayer App topic:
    ThingLayer: An open source real-time web interface for IoT - #132 by BatraD

  1. Install @jody.albritton Thing Layer App in the IDE,
    https://github.com/jodyalbritton/smartthings/blob/master/thingLayer.groovy
    a. Log into the IDE for SmartThings. At this point you need to note which “shard” you are operating under. That detail will be needed to use the correct web path. Please review this link that @tgauchat kindly put together: FAQ: How to find out what “shard” (cloud slice IDE URL) your Account / Location is on?
    This information would impact the links created in steps below.

  2. https://graph.api.smartthings.com/ is the start of the URL that points to the original shard devices were stored on. Things have been updated since this original posting to include a second shard for North America for newer accounts and a shard for European users, as detailed in the link above.
    NA01: https://graph.api.smartthings.com/
    NA02: https://graph-na02-useast1.api.smartthings.com
    EU01: https://graph-eu01-euwest1.api.smartthings.com
    AP01: https://graph-ap01-2??? (to be determined)
    Substitute the correct URL starting point, based on your shard your devices are stored on.
    b. Go to the App Settings and click on the link for the OAuth section near the bottom of the page. That opens the OAuth Client ID and the OAuth Client Secret codes.

  3. CID = OAuth Client ID

  4. SCID = OAuth Client Secret

  5. Once you get the codes go to the bottom of the page and select update. Then go back to the Code page. If you see oauth: [displayName: “Thing Layer”, displayLink: “”]) as the last line in the definition section then go save/publish page otherwise go back to the App Setting’s page.

  1. If the IDE is cooperating or see phone app, run the app to select the items you want the URL code for.
  1. Replace CID with Client ID Code you obtained in the steps above in the URL below.
    https://graph.api.smartthings.com/oauth/authorize?response_type=code&client_id=CID&scope=app&redirect_uri=https://graph.api.smartthings.com/oauth/callback
  1. Copy/Paste URL with you CID code into any browser and open.
  1. The authorization code (once returned) will take the place of a password in the next step of getting the OAuth access token.
  1. Retrieve an authorization code by first authenticating with SmartThings. Set the client_id to the value specified in your SmartApp, and the redirect_uri to a location you have setup to handle these OAuth 2 requestA request with a parameter called Code will now be sent to redirect_uri, which can be used to exchange for an access token in a separate request, in the following steps.
  1. The Smartthings webpage will say: Not Found. We’re sorry, but that page doesn’t exist. The Code is in Web Address field. Copy current Web Address Bar. It should look similar to this:
    a. https://graph.api.smartthings.com/oauth/callback?code=1XXxxx
    b. This is the Code you need 1XXxxx, your code will look different, but be about the same length.
  1. Next obtain an access token using the grant.
  1. Now that you have the code (like 1XXxxx in the URL above), you can make an HTTP request from the SmartThings OAuth endpoint using: + The Code + The OAuth Client ID + The OAuth Client Secret or CODE + CID + SCID
  1. In the URL below replace the CID, SCID and the CODE with the actual alpha numeric codes above.
    a.“https://graph.api.smartthings.com/oauth/token?grant_type=authorization_code&client_id=CID&client_secret=SCID&redirect_uri=https://graph.api.smartthings.com/**oauth/callback&scope=app&code=**CODE”
  1. A web Report should appear on webpage. Keep all information. See example below.
    { “access_token”: “x63x3x36-xx4x-0000-6x62-9c3fe47aaccd”,
    “expires_in”: 1576799999, "
    scope": “app”,
    “token_type”: “bearer” }
  1. The Access Token or AT, from above is need for the URL below:
    a. “https://graph.api.smartthings.com/api/smartapps/endpoints?access_token=**AT**”
  1. Depending on your browser, you will either see the information appear on as a Webpage or you may be prompted to save file.
    For a Webpage, Keep [copy] all information.
    If you are prompted to save and you do select the save option, it will use “endpoint”. I recommend adding “.txt” to the name when saving. This way you can easily open the document as a text file. The report will contain your Client ID or CID and will show you your Installation Code or IC. See example below.
    [{“oauthClient”:{“clientId”:“CID”,“authorizedGrantTypes”:“authorization_code”},“url”:"/api/smartapps/installations/ IC "}]
  1. The next step is going back to the ThingLayer Code and pulling the INPUT name list or Device Type or DT. To save time I have listed them below. These names will be part of the next URLs.
    a. switches
    b. thermostats
    c. dimmers
    d. presences
    e. contacts
    f. illuminants
    g. temperatures
    h. humidities
    i. batteries
    j. lock
    k. powers
    l. energys
    m. motions
    n. accelerations
  1. I like using Excel, so I can use variable in the URL to plug and play with the remaining steps.
  1. The following URL structure will generate the Device ID or DID that will be needed for the final endpoint URL
    a. “https://graph.api.smartthings.com/api/smartapps/installations/IC/DT/?access_token=AT”.
  1. Depending on your browser, you will either see the information appear on as a Webpage or you may be prompted to save file.
    For a Webpage, Keep [copy] all information.
    If you are prompted to save and you do select the save option, , it will use the DN. I recommend adding “.txt” to the name when saving the file. This way you can easily open the document as a text file. The file will contain your Device Type or DT, Device ID or DID, Device Name and its current Status. Repeat this for each Device Type entered into ThingLayer.
    [{“type”:“switch”,“id”:“DID”,“name”:“Basement”,“status”:“off”},{“type”:“switch”,“id”:"“DID”,“name”:“Family Room 1”,“status”:“off”},{“type”:“switch”,“id”:“DID”,“name”:“Family Room 2”,“status”:“off”},{“type”:“switch”,“id”:“DID”,“name”:“Family Room V”,“status”:“off”},{“type”:“switch”,“id”:“DID”,“name”:“Front Light”,“status”:“off”},{“type”:“switch”,“id”:“DID”,“name”:“Kitchen Highlights”,“status”:“on”}]
  1. To create the ENDPoint URL you will need the following codes generated during this process:
    a. IC = Install Code
    b. DT = Device Type
    c. DID = Device ID
    d. AT = Access Token
    e. You will also need the state of some devices like switches [on/off/toggle] You can also dim with dimmable lights/switches [/level/##] where ## is a number between 0-100. If the Dimmer Device Type does not work substitute Switch. The DID is the same for both.
  1. The URL format listed below. Here DT is a switches:
    a. “http://graph.api.smartthings.com/api/smartapps/installations/IC/DT/DID/on/?access_token=AT”
    b. 'http://graph.api.smartthings.com/api/smartapps/installations/**IC**/**DT**/**DID**/off/?access_token=**AT"**
    c. 'http://graph.api.smartthings.com/api/smartapps/installations/IC/DT/DID/toggle/?access_token=AT"
    d. 'http://graph.api.smartthings.com/api/smartapps/installations/IC/DT/DID/level/50/?access_token=AT"
  1. Other devices tend to show the same details as Step 19 for the individual DN file or web view, but with current information.
1 Like
4

@DarcRanger Thanks for putting this all together. Unfortunately I can not get past step 18:
{“error”:true,“type”:“AccessDenied”,“message”:“This request is not authorized by the specified access token”}

Do you have any tips for this? I have tried numerous times over the past two nights via the simulator and building the app on my phone, I can get neither to work. Was something updated since last year that has broken this at step 18?

My goal here is to get a switches/dimmers Web URL that when visited/activated turns on or off a switch. I need this URL to integrate a single click action with a custom app I am work with on a Garmin Forerunner 235 smart watch.

Thanks for your help!

5

@Addizzle,
What is the issue at step 18? Is it “DN” vs “DT”, the device type?
DN should be a device type like “Switches”,

Or is the issue with the Install code or Access Token? The phrase “access_token=” is part of the url.

https://graph.api.smartthings.com/api/smartapps/installations/**Install_Code**/**device_type**/?access_token=**AT**
6

@DarcRanger Thanks for the reply, without being too blunt the issue is it just doesn’t work. I gather all my CID/SCID/AT and IC codes and input everything like you have shown and I get the error in my previous post.

I will admit that the DN vs DT thing did throw me for a min but I assumed it was the device type. I have also been leaving in the “?access_token=”. I refreshed the CID and SCID today, saved, uploaded and went through everything again and I receive the same error message.

7

One thought… This might not have anything to do with it, but different smart things accounts are on different shards, which means you have to use different URLs to make things work.

Right now at the time of this writing there are three different shards.

If your account with SmartThings with set up prior to November 2015, you are probably on NA01, which would use the URLs given in the first post of this thread.

If your account with smartthings was set up after that and you have a US frequency hub, you are probably on NA02

And if you are in the UK, you are probably on Eu01

More about this in the following thread, but I just wondered if this might have anything to do with what you’re seeing. Just a thought.

2 Likes
8

@JDRoberts You are awesome! Thanks for the tip! I am a “na02”, and it solved the problem for now. It actually looks like it doesn’t matter if you put in you correct shard until step 18 and on, as I did it both ways. I would probably advise using using the correct shard the whole time just in case.

@DarcRanger Thanks again, I think this is still a great thread. Maybe you can update your original post to include needing to find out your shard around step 3 or 4?

2 Likes
9

@DarcRanger

I think I stumble on an easier way to do this. If you run ThingLayer is the IDE via the Code>Simulate you can select your switches and hit “install” then it shows you two text fields:

API Token & API endpoint

After following the steps above I determined that:
API Token = Access Token or AT
API Endpoint = ‘https://graph.api.smartthings.com/api/smartapps/installations/{installation code}’ or IC

This means you can skip steps 5 thru 15 and go right to figuring out the DID’s.

Need someone else to check my work though to make sure.