Example using new SmartThings Cloud API!

Fellow developers,

As many of you know, we recently made some announcements at SDC around the SmartThings Cloud. We’ll be providing more information about this soon, but one thing worth calling out is that the new API (it’s REST!) is already available!

While some of the APIs are specific to the new SmartApp model, the /devices and /locations APIs can be used just like any other REST API. All you need is a personal access token, which you can get here.

Example CLI Tool

To highlight some of the APIs, we wrote a simple CLI tool as an example. It allows you to get information about and control your devices, through a simple Command Line Interface. More importantly, it shows how you might use the API for your own projects. It’s open-sourced, and you can find the repository here.

We’re excited about the new API, and encourage you to start experimenting with it. Checkout out the API docs, get a token, and start hacking!

References:

18 Likes

Jim, great to see. I do have a question, what does this mean for the current ST platform and the current SmartApps/DeviceHandler model? The new model looks drastically different from the current setup and I’m guess there’s no migration path here for the apps/dth’s or is it a completely different target market?

3 Likes

Good question @RBoy. We will be providing more information about the new ST cloud platform and what that means for both current and new developers soon (a matter of weeks™ :smile:), and an opportunity to ask all sorts of questions around that.

What I can say now is that Groovy SmartApps and Device Types continue to work as they do today, and we are continuing to build out new developer tools and models that offer developers more flexibility and power.

Right now, what is easily available and pretty cool is the new REST API and personal access tokens, and we wanted to get y’all some visibility around that, because it’s something we’ve all been wanting for a long time :wink:

5 Likes

Right… Yes, I guess there are some questions

  • SmartThings is moving away from the published & SmartThings Cloud hosted Groovy SmartApps.

  • Self-hosted (AWS Lambdas, VPS, Node.js servers, Apps, now get a typical callback API into a customer’s Things). This allows SmartApps to be much more rich, but they minimize use of SmartThings Cloud cycles. No “review, approve, publish” process required anymore or much minimized.

  • Device Type Handlers are simplified, but must (?) conform to Capabilities. Not sure what the new API is for defining DTHs special UIs (SmartThings App tiles) and non-basic processing. I think it is config file based, rather than Groovy.

  • Groovy based coding officially not deprecated, but may lose access to new features, so it is bound to eventually die off.

2 Likes

I loaded the cli on my pi and got it working yesterday just fine. Today, i can’t get it working. I have redone everything. I keep getting directory does not exist error.

No big deal, I was just curious to play around with it anyway.

Any suggestions?

I’m highly concerned with latency of this arrangement. I’m also disappointed at the lack of a build out of local apps.

Instead of HUB ↔ ST CLOUD we will get HUB ↔ ST CLOUD ↔ AWS CLOUD (or private server, etc)

That’s a lot of communication and a lot of potential for things to break. I’m glad to see the Groovy apps will continue to be supported however I take that as a “for now” in light of past broken promises and cancelled features.

3 Likes

I had a little preview of that last night, looks like there an issue with ST executing SmartApp in the cloud between 4am EST and 6am EST. SmartApps were just ignoring events and not executing. Many of my thermostat apps failed to register events from sensors and eventually led to my house having really cold to really hot spots across the rooms because the apps just weren’t executing and managing the thermostat. Around 6am everything started firing as expected and by 7 the temperatures had returned to normal. I have rooms registering 59F at 5:30am in the morning because of this issue!!

Legitimate concerns, and by no means do I have official answers or in-depth knowledge, but here’s some thoughts:

  • SmartThings is still working on improving local execution capacity and abilities. Not sure exactly how that will mesh with the new API / architecture. Perhaps it will be possible to push “lambda functions” to the Hub. Computing at the near-edge (i.e., “fog :fog: computing” instead of just “cloud :cloud: computing”) is a major area of research in the industry. I guess we shouldn’t presume this is a high priority for SmartThings though, especially for 3rd party developers.

I think you may be over estimating the real world impact of this distinction, actually…

  • You see, this already happens in the SmartThings Cloud… Device servers (even the physical hardware) are not likely to be the same servers running SmartApps! And, BTW, they already both run in AWS.

  • So currently it is actually (I think!): HUB ↔ ST Device Handlers in AWS ↔ SmartApps in AWS … Therefore, it’s the same number of hops. And if the 3rd party developer runs in AWS too, then with the new API, there isn’t even any significant extra network latency!

  • The new API also allows callback definitions on subscriptions to be targeted directly to the developer’s front-end application. For apps with a UI, this possibly eliminates one hop, thus no increase in net latency.

  • Finally, note that Samsung is “playing the long game” here, and likely making the assumption that cloud-cloud latencies are going to be increasingly trivial. ActionTiles already uses an intermediary cloud layer and it has not detracted from our customer’s experience. In the current world, it adds a few hundred milliseconds. In the future world with continuing advances in network technology and computing power advances and overhead optimization, it may be reduced to a fraction of that!

5 Likes

The execution target, Groovy SmartApp vs λ \ Private Server should end up being the same number of hops, the only area that is majorly different is sandboxing and device control. Device control via the API will be the most direct control long term. Depending on the device backing that looks slightly different but that API will be where the work control flows from.

The other area that will help long term is the more defined APIs and ways we deliver data makes future improvements easier.

1 Like

I guess one of the big changes in the now the code will be written and executing on non smartthings servers, the ST platform is just going to provide hooks. That pretty much takes development for the average experimeter off the table unless you’re familiar with creating webservices.

4 Likes

@RBoy Nothing stopping someone from creating a “web app” that uses the new API but presents the user with an IDE/interface such as blockly There is wide consensus in the company that we need to maintain a path for hobbyist and entry level developers.

6 Likes

The way I look at it (I’m super biased so take this with a grain of salt.) is we are moving to open the core building blocks of the system and have that be the API. Instead of having a sandboxed quick dev web ide be the main integration point we are moving down a layer of abstraction. This layer of abstraction will expect more understanding of REST and general programming. So there will be the ability to build more levels of abstraction on top of this but moving down a layer I think will help us in the long run. I also strongly think it will help the development community but once again I’m biased I like this type of programming.

As for the average experimenter I think we already assume a lot of programming knowledge there are other offerings built on the system right now that give more experimentation around home automation and less need to get into the services.

My challenge out to everyone, if you think this layer of abstraction is limiting to some experimenters build a new way to tinker with the APIs. That will be a great way to test out some of the new APIs see what areas are missing/lacking etc. Also we (the community not me I think APIs are cool like bow ties) may come out with some really cool things to work with.

4 Likes

Why is that Jody? How are hobbyist and entry level developers a priority for SmartThings today?

An open API will lay the groundwork for so much of what the community has been asking for since the beginning of my time with SmartThings. Like it or not Javascript is becoming the lingua franca of the Internet and our new restful API will allow users a very easy path to building things on the SmartThings platform. Consumption of a rest API is a pretty standard tutorial in javascript. There is far more documentation out there for doing that than there is building things in a sandbox with a modified version of groovy.

Just check out Jim’s simple example above

I would argue that if entry level developers were not still a priority for us that this community and things like that example would not exist.

1 Like

I have done a lot of programming in years past. Started out in machine language hand assembled, then Basic, Some C, C++. But not in a long time. For the last 20 years or so all I have done is PLC programming. I am now semi-retired and really don’t have the desire to learn a new language. Us retired folks are awful busy, you know. I use WebCore quite a bit and like that kind of interface. I can understand it without learning a new language.

But what I would like to see and would think this API would maybe cause it to happen. Someone would write a program that I can load on my local system, such as my PI, or a backup computer I keep around. Then It can control my automations locally. I realize there still has to be some cloud interaction, but would like to see a lot of it local if possible. Living in a rural area it’s not uncommon to lose internet service, sometimes for several days.

Just a few cents worth from someone who is between being a programmer and a raw beginner.

2 Likes

You need someone to test drive the new APIs, sure. I guess it’s cool to turn lights on and off via HTTP endpoints. I don’t see too many entry level developers jumping on it, yet.

Not to derail the conversation - I just couldn’t find a quick answer…

Which apps are officially local (not which apps that I have installed are local - just what’s available)

And more out of curiosity, is the availability - or ability - of self written smart apps for local control a restriction of storage on the device or of processing power (or both)? Or is it more of a - we don’t want you bricking your device and blaming us for it - thing (which I could understand). I only ask because I’m sure there’s very few people on here who wouldn’t be happy to go put together a nas or repurpose an old laptop just to get local app (and device) availability. Heck, I’d pay for it - on a subscription basis! I’m not an economist though and I’m sure there’s some point to be made about maintaining control over the ecosystem. Just promise us that if ST ever goes belly up, we can maintain our own stuff! (pretty please)

Trying to request an access token (here: https://account.smartthings.com/create-token) and Im just getting this error: “Unexpected token < in JSON at position 0”

Anybody know what’s up?

It’s more of a…

The firmware on the Hub is currently monolithic (probably except for chip-level firmware like the ZigBee/Z-Wave).

It can’t just download / plug-and-play an arbitrary DTH or SmartApp.

Currently, SmartThings has to build a complete new Hub Firmware whenever they add or change DTHs and Smart Lighting.

Ah… I guess that makes sense - and explains why its such a thing adding new stuff… So I take it then that Smart Lighting is literally the only ‘Local’ smart-app?