One Of The Guides I Wish We'd Had

@jody.albritton Yep i am. Feel free! It’s built from feedback from multiple people over a few months and very generalized. Essentially a copy of an internal doc i’ve given to new devs who know nothing about SmartThings to get them up and running. It’s not an attempt to be canonical or absolute, just to get people started. In some respects it’s not technically accurate (as noted) but more a conceptual thought-primer; the audience is Python/C/Go devs who have never heard of Z-Wave, Zigbee, or with any real experience in IoT. Bear that in mind.

See, Jody is a real expert. I might know a little more about zigbee installations than he does, but I guarantee he knows way more about ST architecture than I ever will. :sunglasses:

1 Like

Honestly, as i say in the article, the real information is in here, despite how nice the docs look now (and credit where credit is due for that). That’s what’s so sad; there shouldn’t be the need to do this much of a deep dive to do simple stuff.

WHY do you have to develop blind not knowing what SmartThings will POST to your endpoint?

The life cycle events are fairly well documented.

https://smartthings.developer.samsung.com/docs/smartapps/lifecycles.html

WHY isn’t there a web UI to design how your plugin will look with the JSON you send back?

Customization of the UI is not supported in the new app today. We are working on custom capabilities that will make use of custom UI plugins.

WHY is OAuth2 being renamed instead of just being OAuth?

Not sure what this question references

WHY is there no web dashboard to do this in, and everyone forced to do inside a phone app?

No actual development is done inside the mobile app. You view the results of your app/automation there. You can run the app in a VM on your desktop if you want to.

WHY do you have to continually “install” and "uninstall"your “SmartApp” when it breaks or doesn’t complete its setup?

Is this a question about “classic” smartapp development?

WHY do you have to check the “Live Logging” for the “network error” details when you are in “Developer Mode”?

Where would you view this information on the phone?

WHY is there no multi-language support?

There is.

WHY is there no connection between a personal access token and a “SmartApp” access token?

Personal Access Token is a user principal scoped to a specific user for development purposes. The personal part means it is your token. App specific tokens are just that, scoped to the app.

WHY is an access token only valid for 5 minutes?

The short lived token that is sent with a callback is only valid for five minutes because it is meant to be throw away. The long lived token and refresh you get follow the standard oAuth pattern. Short lived tokens allow the app to take some immediate action without the need to burn your token and refresh.

WHY are “configuration” and “healthcheck” some form of “capability” you can add during CONFIGURATION?

A device can have a health check capability and can also be configured?

WHY is the documentation so full of mindless abstract jargon and Samsung unable to ever commit to when they will be updating it?

We are updating it. If you have specific feedback I am happy to hear it.

WHY is the SmartThings Hub listed as a device you can talk when … you can’t?

Are you asking why it’s listed in your devices as a thing?

WHY do you have to delete subscriptions to update them?

Not sure what this means.

The JSON examples don’t work in any JSON linter. They’re invalid syntax - e.g. many have trailing commas.

We user swagger internally to generate the examples

The API requires posts as JSON objects, not url-encoded form fields: not a bad thing in itself, but it’s not exactly clear.

Pretty standard since we are’t processing form fields from a url.

The permissions are wrong: although it might state to include i:deviceprofiles as a scope, the actual one is i:deviceprofiles:* (note the asterisk). That’s why configuration screens crash without explanation.

The docs could and will be improved here but there is a reason for the *

The capabilities aren’t as stated - many have a status of proposed .

They are as stated but are currently in a proposed state.

Elsewhere in the article it seems much of the information is mixing up our old classic platform with the entirely different new way of doing things. The classic documentation is clearly labeled as such and is only there for legacy reasons at this point.

@JDRoberts is not a veteran developer on the platform.

There is a lot more but I figured we could start the conversation here.

1 Like

Here is a short video showing the creation of a “SmartApp” (Note the shout out to localization at 1:40)

Start to finish in less than 10 minutes.

We called the groovy IDE an “IDE” because it was the integrated development environment for legacy apps and devices.

3 Likes

@JDRoberts is not a veteran developer on the platform.

Agreed. :sunglasses:

@Alex_Cstr8 ,

I am not, nor have I ever been, a coder for the SmartThings platform. Trust me, you do not want to do groovy with voice recognition.

I am a long-time user (going back to 2015), but I generally try to use no custom code if possible.

So I’m not even a novice developer: I literally have never done any for this platform except some copy and paste when absolutely required.

quoting the article

WHY is OAuth2 being renamed instead of just being OAuth?

Ooh, I know this one. I think…:sunglasses:

OAuth2 (more formally OAuth 2.0, but frequently referred to as OAuth2) is a separate protocol published in 2012 As RFC 6749. It is not backwards compatible with the original OAuth.

If you’re only going to read one of the following links, read the One from Smashing Magazine, which explains the differences between the two generations. :sunglasses:

.
https://hueniverse.com/introducing-oauth-2-0-b5681da60ce2

It Was widely adopted in 2017.

This article is a great help towards me understanding the different components of a SmartThings system, though I still have much to learn. Some terminology I find confusing though. For example, as had been pointed out earlier, “web firmware” just sounds wrong :slight_smile:

Thank you for writing this up.

@jody.albritton Thanks so much for taking the time to address all of those. I think @JDRoberts should be a veteran though. 5 years using and building sounds pretty veteran to me.

I’m more than happy to retire that “web firmware” idea, believe me. It’s so abstract it’s difficult to conceptualize it at all. Didn’t see the localization either, so thanks for that!

Let’s definitely go one by one here.

That’s not the point i’m raising. The process of trial and error to work with this is a nightmare. The only way to test it is to host an endpoint on a staging box or ngrok it to localhost, and that’s installing an app which isn’t built (or built blindly). Software 101 is not to trust what you’ll receive in a payload. Couldn’t we have a nice big button in the workspace which says “Send Test Payload” for each phase, with dummy data? How do we mock this locally , for tests?

The whole thing is basically OAuth: create an app with client_id and client_secret, get access/refresh tokens, get callbacks. It’s exactly the same as a Twitter, Facebook, Twilio app. Why not just call it OAuth and follow convention?

Why on earth would anyone want to do that? Errmaaghheeerrd!

Nope. Let’s say you’ve written your code for the lifecycles, and for some reason the webhook gets a 500 error during the INSTALL phase. The UI will display “a network error occured”, meaning it didn’t complete. When you go back to the SmartApps list, your project is there, looking like it’s installed. Shouldn’t it only be seen as an “installed” app if it completes properly?

In the dialogue which appears saying “a network error occurred”. If in developer mode, display the remote response received there instead of the log? I don’t want to have to do this in “live” mode on a phone; only to stage it there. There’s a double problem here: you have to copy/paste the live log data, then get it into a readable format (e.g. JSON viewer), then unparse the error, which is a JSON-encoded error string inside a JSON object! (backslashes)

Why can’t the API tell if our own app is linking our own devices?

This is one of my biggest gripes, although i do understand the security precaution here. If we create an OAuth app which displays a permissions screen for a user to view and accept, the token we get is valid until it’s revoked. Unless i’m missing something here, don’t the docs say the only access token an app receives is the 5min one? I’ve looked over this in our logs and the only time we get it is during INSTALL and UPDATE.

Advice Erick gave me over email. Subscriptions can’t be updated - have to be deleted first, then re-created. I spent the best part of a few hours trying to understand why i got 403s using a personal access token which worked with anything else. It seems like a bit of a pointless thing.

Try them in https://jsonlint.com/ . Not a big thing but it’s annoying when you’re copying/pasting when simulating an webhook POST on local.

That’s true, and it’s largely because it’s often the only way of understanding anything (see a lot of the forum posts on here) as well as figuring out what some devices claim as capabilities (e.g. the musicPlayer example from Bose). The lock codes one is a great example of this. It’s entirely possible to set and remove lock codes on those Yale products, but - and i’m not joking on this - it took one of our guys about half a day to find the answer to something we knew we could do: Correct Z-Wave Lock API Command - #6 by awesam. The commands listed under capabilities are just lock() and unlock();

I feel your pain.

You are still a hero. Even if you don’t wear a cape, or weren’t the one we wanted. Non, je ne regrette rien!

1 Like
  • SmartThings Hub - a Z-Wave/Zigbee router

Might want to change this one, too. A zigbee “router” is something like a light switch which is capable of repeating mesh messages. And there is no such thing as a Z wave router. The device which establishes a Zigbee network is a “coordinator.“ The device which establishes a Z wave network is The “primary controller.“

This is the equivalent of saying that a television is an FM radio with a screen. It just isn’t.

A smartthings hub is a plastic box that includes multiple radios and a small CPU. It is certified as a zigbee coordinator and a Z wave primary controller. Some models also include a Wi-Fi radio. :sunglasses:

The point @jody.albritton was making is that I don’t “build.” Never did, never said I did, never contributed any code to the community, and it’s unlikely that I ever will. I can’t work with code because I am voice dependent. I used the classic app quite a bit back when it was voice friendly. Never used the new V3 app much.

Again, my area of expertise is in network protocols, which is a fairly unusual specialty, so I have been able to be helpful in those topics. But there are lots of grandmaster coders in the community, and I’m not even a novice in that regard. :sunglasses:

1 Like

See my post above. OAuth and 0Auth2 are 2 different things, in some ways quite different, and not backward compatible.

I don’t know about Twilio, but the others all use OAuth2 and do not use OAuth anymore. So it’s not simply a convention, particularly for developers: if you code your authorisation for OAuth, it will not be successful if the destination is using OAuth2.

Again, see the links in my post above.

First,

@JDRoberts is a hero, no argument there. But he still isn’t a veteran developer on the platform :slight_smile:

You can test your code and create mocks based expected results.

There are quite a few tests here.

Depends on which work flow you are using. We do have straight up oAuth integrations and that is what they are called. When working with such integrations the tokens and other interfaces behave just as you would expect. The token you get with an oAuth app lasts a lot longer than five minutes. If all you want is oAuth, then you should follow that guide.

https://smartthings.developer.samsung.com/docs/oauth/oauth-integration.html

SmartApp or Device development is not called oAuth because it’s not just oAuth. The intention behind an automation smartapp is for you the developer that to create an application that performs a specific purpose and is installed by the user on the end user’s mobile phone. If you don’t want to be in the SmartApp catalog and want the install flow to happen entirely on your server or client, then you build an oAuth integration.

Technically you don’t need to look at the developer console for this info as you can see it on your local or remote development machine as well if you have proper logging in place. And I don’t think throwing a blob of data out on the mobile screen is that useful for debugging since you are likely going to need to copy the error/ code ref for discovery anyway.

A token is sent with every event as well. The whole concept of a SmartApp is that you want to provide packaged functionality to an end user (See my very simple example from the video) where they install the application and it does a thing for them. You shouldn’t need to fuss around with refresh tokens in this scenario. Again, from my video, I never used a token or a refresh token to make that app work.

OK, now I understand. The answer is that you are either subscribed to device/app events or not. An example case would be a device updates its capabilities and you want to then update your subscription. The security model should have you ask for brand new permissions and then create a new subscription based on those new permissions.

Which examples are you talking about? If you are referencing the example responses from the API, those are only snippets of the full response body with some truncation so, yes, they won’t lint properly.

1 Like

What is the alternative? In the classic IDE we did have an emulator but it was only an approximation of how things “should” work in the mobile app. We also had html in the UI back then so it made more sense to see how it would look. We do have a web version of the SmartThings app currently in closed beta so you will be able to use that for development when it is released as well.

2 Likes

This is what i’m talking about: this isn’t going to help anyone when they’re starting out, which is who the article is for.

The OAuth2 thing is a typo, apologies. Didn’t mean to introduce that ambiguity. In all points i’m referring to v2.

We did take a look at that as it was the first thing we pinged support about. I had 2 guys assigned to explaining it to the rest of us and nobody could understand it.

We looked at this one too. For our use case, we’are never touching equipment we don’t own, so all we need is a way to poll our own devices (potentially 1000+ of them per location). The concept (which i can’t go into publicly) as is an IT engineer has a dev smartapp and identifies each “room” of devices onto our system for commands we proxy through our API, and telemetry.

Our UI uses Web Application Messaging Protocol (WAMP v2) to send ST events down the wire to JS clients which in turn also send upstream RPCs. Was using Crossbar (Python WAMP router), but we’re moving to Lua/Influx/Telegraf. “Topics” in our implementation are the ST device IDs, so the backend “publishes” the event part of the lifecycle to its subscribers, who can also call procedures on them. The alternative to events is calling /devices/id/status every X seconds with watchdogd, but that causes problems with API limits.

For 500s, yes (we use loggly). But not for 422 validation errors. I’ve seen at least 5-10 situations where we’re sending up dynamic config triggering an unknown network error. The only place we’ve been able to find out why is the live log. It would just be nice not to have to do any of this.

A web-based UI for sandboxing, like you’re beta-ing (hurrah!!!)

The other part of the ecosystem i just cannot understand for the life of me is the idea of cloud connectors, direct-connected, cloud-connected devices, hub-connected, schemas etc. There’s so much word salad it defies all logical analysis. I even have those docs printed out on my desk, with a highlighter pen. My boss can understand the Haversine formula; but none of us can make sense of this.

Would it be possible to get some clarification on that as well as the OAuth integration part?

I don’t think you can have 1000 devices per location on a smartthings account, can you? Last I heard it maxed out at 300.

@johnconstantelo

Spot on @JDRoberts. Been there, done that, and won’t do it again…

1 Like

I’m going to have to respectfully disagree for two different reasons.

First, you indicated that your audience has a technical background. In that case, they can definitely understand a box of radios. In addition, if they go out and look up any other resources, it’s going to be really confusing because “zigbee router” is specific terminology for the official Zigbee certification. But it’s not used in the way that you are using it.

Second, over the last five years I have spoken with dozens of people in this forum who don’t have a technical background at all. From the feedback I’ve received most of them have found the conversations helpful.

We’re doing it a bit differently to this but would love to hear this story!