One Of The Guides I Wish We'd Had

Wanted to thank all the people who’ve commented on the (probably highly stupid) questions i’ve posted so far and the help I’ve received and passed along to our team - as we’ve drunk ourselves into oblivion coping with SmartThings.

If you’re a new dev on the community forum, or starting out with the platform, maybe this might help you to navigate some of the obstacles and pitfalls: i originally wrote this as an internal post for on-boarding programmers transferring from other projects.

It’s slightly tongue-in-cheek, and doesn’t cover everything; but it’s a reasonable summary (IMO) to get you through Day 1 Monday morning confusion!

4 Likes

Well done. :sunglasses:

One small point that should help avoid considerable confusion in the future… It’s best to recommend that everyone get to the IDE through the universal sign-on URL. Not https://graph.api.smartthings.com/

The Universal Signon URL: https://account.smartthings.com

The reason is that different people have their cloud account on different “shards“ so some people trying to follow your link will end up on a screen where all of their devices are missing. :scream:

If instead, they use the universal sign on URL, it will automatically direct them to the correct shard. :tada:

See the community FAQ,

2 Likes

I wish i’d known that - i’ll update it. After i’ve finished these bottles of scotch and finished crying. By then i should be at the “forgiveness” stage of grief, so they tell me.

1 Like

A few other small points:

DTH

it is linked/associated with a “cloud driver” or “web firmware”

It’s not firmware. In fact, it’s quite the opposite of firmware, because it is not stored in the device itself. Have you had a chance to look at the community FAQ and custom code? While it is referring to the older platform, it does explain the terms and concepts and what a device type handler is, which still applies.

The IDE

Also, technically the IDE is an integrated development environment because there is a simulator in it. It’s just that the simulator doesn’t work very well and hardly anyone uses it. But it is there.

It’s definitely not a “dashboard,“ because you can’t actuate any of your devices from it.

These days we mostly refer to it as the “web interface to your SmartThings account.”

SmartApps

The smartapp is definitely not a plug-in, because it doesn’t run on your phone at all, which is where the mobile app runs.

On the original platform, smartapps ran in your cloud account. Seriously. They never ran on your phone.

With the new platform, you are supposed to host your own smartapp, and then connect to your SmartThings account via web hooks. So again, not a plug-in and definitely not a plug-in to the mobile app.

Those are small bits, but important ones. To those of us with an engineering background, firmware has a very clear definition and it’s important to enterprise security as well. Firmware would run on the end device itself, and that’s not what a device type handler is. (Also, while smartthings does have a setting to update the firmware on a Zigbee device, that has nothing to do with the device type handler. )

I agree that the definition of smartapps continues to become muddier and muddier, and you give a good description of that very strange development. But they aren’t plug-ins, again, they differ in a way that is very important to enterprise security. They don’t run on your phone.

As for everything else you have from that point on, including the various confusion points, you describe it very well and it is, indeed, very confusing. With different sections that look like they were written by different people, potentially in different languages, and very little communication between them. :thinking:

We keep hearing that this is all a work in progress and everything will be clarified and coordinated in the final version. Here’s hoping! :beers:

2 Likes

Also, this confused me:

Bose, in this example, is reporting different Z-Wave/Zigbee capabilities.

Bose uses neither zigbee nor zwave. The “capabilities” For both the old and the new platform are intentionally removed from the protocols that the device actually uses: they are an abstraction layer that smartthings provides.

I’m pretty sure Bose is an LAN integration, although it might be cloud to cloud. I haven’t looked into it. But the whole point is that smartthings likes to pretend that it doesn’t matter what communication protocol a device actually uses, an automation or smartapp can still Access the features of the device through the abstracted capabilities which are assigned (not exposed) through the DTH.

Also, see if this helps any.

On the original platform, a “smartapp” is a program that someone wrote from scratch to perform a function on the smartthings platform. People were also allowed to copy a program from someone else and use it on their own account.

In the Classic app, A routine is a form that you fill in in the smartthings mobile app that allows you to access some of the features of the platform. They could also be actuated from the app itself or from a widget.

With the new V3 app, routines disappeared. Now there are “automations“ which are still forms that you fill in in the smartthings mobile app that allow you to access some of the features of the platform. However, they can no longer be actuated from the app. Or from a widget.

So on the old platform, for a smartapp you either wrote code or you copied someone else’s code.

For a routine in the classic app or an automation in the new V3 app, you don’t have to write any code. You just fill in values in a form. :sunglasses:

One common example for this kind of distinction is that writing a smartapp is like making dinner from scratch, creating an automation is like ordering a pizza. :pizza:

I really appreciate a lot of these points (and the time taken to provide them, thank you!), but i have to disagree; the reason being to do with the confusion apparent in the flawed conceptual framework attempted with the SmartThings architecture. Simple things are self-evidently simple, and there is so much confusion in all of this which is not apparent in other systems possessing far more complexity: a developer doesn’t need to read an FAQ about how Twitter’s API works, for example.

That’s the reason i added a note about it not being the technically accurate way to describe how it works.

You’re absolutely right: it’s not firmware. However, for all intents in purposes, in the developer’s eyes, it is performing the same role - conceptually. That’s where i’m aiming. We have to find ways to on-board people using concepts they are familiar with already. Firmware might be the wrong choice of wording here, but it’s a loose kind which conceptually fits; not technically accurate, but a way of communicating what’s going on.

The “IDE” isn’t an IDE, by any definition at all: Eclipse is an IDE. It speaks volumes that a “web interface to your account” is supposed to be a simple definition. Honestly, it’s entirely unclear what it is, and this entire section of ST needs to be re-thought. It may be technically brilliant, but unless it’s for use by extraterrestrials, us ordinary humans aren’t going to be cheering it on any time soon.

Again, you’re absolutely right: it’s not a plugin. I’m back on the conceptual level. When i visually show a dev a host program (SmartThings app) and their piece of code is something listed in it, the nearest analogue which comes to mind, mentally, is a plugin. Nobody can seem to define what a “SmartApp” is!

This is an example of where the whole thing goes way off the rails. The “SmartApp” in question is someone’s normal web app, in Ruby, Python, Laravel, Go. We already have a name for it. Webhooks are used every day for CI/deployment, API callbacks etc. To put it bluntly, Twitter, Twilio, Nexmo, Sparkpost or any other provider don’t refer to 3rd party apps/platforms invoking their API as TwitApps, TwilApps, NexApps, or SparkApps; they’re just web apps processing multiple POST webhooks from differing sources.

The reason i’m pointing that out is to illustrate where SmartThings differs in its understanding of how the relationship between providers and developers has changed since Windows 98.

How many versions are we going to have from this multi-billion dollar giant company before it it’s “final” and works like most people expect it to?

2 Likes

Also, see if this helps any.

On the original platform, a “smartapp” is a program that someone wrote from scratch to perform a function on the smartthings platform. People were also allowed to copy a program from someone else and use it on their own account.

This is my point: all of this is massive over-engineering. Why is there even a conception of a “SmartApp” at all? It’s just a client connecting with OAuth2. Is it a TwitApp, because it uses Twitter’s API?

Bose uses neither zigbee nor zwave. The “capabilities” For both the old and the new platform are intentionally removed from the protocols that the device actually uses: they are an abstraction layer that smartthings provides.

Ish. It’s referred to as a LAN connection, just as Philips Hue is. Ours connects over Wi-fi, which in itself isn’t accurate (the setup is done over a self-hosted SSID, and the product itself claims it is controllable over Bluetooth/Wifi). Wifi is technically a LAN, but again, terminology: LANs are typically associated with Ethernet. When was the last time anyone went into a LAN cafe? Do you put a password in to connect to an encrypted LAN? Is there an Ethernet cable plugged into the speaker? We have 20+ devices in the lab. No-one has the time to be figuring out what SmartThings actually means.

However, also true: Bose doesn’t work with SmartThings. It can’t switch the speaker on or off, mute, adjust volume, or anything useful. It barely reports the “online” (power) status correctly. However, it’s listed on the “Works with SmartThings” site and the SmartThings API reports capabilities for the device which aren’t in the list, or even usable.

Wouldn’t it be more honest to put it in the “we try our best to talk to it, but no promises” section?

1 Like

I agree that A lot of the smartthings terminology is bonkers, and some of it is self contradictory. But let’s not add to that.

“Firmware” Has a very specific meaning in an IT context, that predates smartthings by many years. It runs on the end device itself. That’s the most critical part of the definition.

Device type handlers do not run on the end device. They are exactly equivalent to a printer driver. The printer driver runs on your laptop, not on the printer. All it does is format the messages that get sent to the printer or interpret the messages that were received from the printer. The DTH does the same thing. Formats the messages sent to the device or interprets the messages received from the device. DTH is not loaded onto the device itself.

That’s a hugely important part of the firmware concept, because it affects efficiency, power utilization, and device security of the device itself.

In addition, a DTH cannot change what the device itself does. It cannot add or remove features. It can expose or hide features, but that’s not the same thing, particularly from a power utilization and security standpoint.

If you start telling IOT people that smartthings lets you change the firmware for a device, they are going to start out being very excited, and then severely disappointed. :disappointed_relieved:

So…not firmware.

If you want a general concept for a DTH using generally accepted industry terms, just call it a device driver. :sunglasses:

Submitted with respect.

This may be accurate for the new platform, I don’t know. The term “smartapp” comes from the original generation of smartthings, And was not a client. It was a program that ran in the smartthings cloud.

But if you’re suggesting that it be dropped altogether For the new platform, that would be fine with me. :sunglasses:

The first two generations of the smartthings hub didn’t have Wi-Fi. Hence “LAN connection.” But my apologies if I wasn’t clear: I don’t care what you call the type of connection that is made with the Bose, I’m just saying that capabilities in a smartthings context were never limited to just Zigbee or Z wave. They were always intended to be an abstraction level above the actual protocol being used, so that they could work with anything, whether it connected via Wi-Fi, ethernet, Bluetooth, zigbee, Z wave, or cloud to cloud connection. The person filling in the form for the routine/automation was not supposed to have to know whether the device was using Zigbee or Wi-Fi or whatever.

Those of us with experience in the network engineering side are just going to immediately stop reading and go get another drink if you say that a Bose speaker identifies itself with Zigbee/Z wave capabilities, because it has neither. :wink: So, like I said, it just interrupted the flow of my reading to come across that.

My tone might be inaccurately be coming across as intemperate or uncharitable, for which i apologise. I think the larger discussion here is worthwhile and seemingly been coming for a long time. There may be some confusion because of the target audience of the article: you’re an expert on this stuff, and the people i’ve been using it to train are absolute beginners.

Would “cloud driver” be more appropriate then, in your view? I added that as an alternative, but i’m still not clear. Even with the point about Bose, does this thing even know what it is?

My sense is the SmartThings developer ecosystem is a bit of an awkward inconvenience to Samsung. It’s like some management board looking at it thinking “Why would we want 3rd parties, when someone can use our app? Oh yeah, it’s fashionable. We’ll add that so we can get more people to sign up for a Samsung account”.

“Cloud driver” would be fine. :sunglasses: I like that it puts the emphasis on the cloud, because that’s a major area of confusion for most people coming to smartthings.

And, yeah… Smartthings staff have said multiple times in this forum that the majority of their customers have 15 or fewer devices and never use any custom code at all. That’s their target audience, particularly if at least one of those 15 devices is a very expensive Samsung smart appliance or tv. Everything else comes second.

As far as me being an expert: I am absolutely not. :face_with_monocle:

I have professional experience with network protocols, which puts me in a pretty small minority, but I was always just a field tech. :factory_worker:t4:

Most of my expertise is in a) getting things to work and b) helping the person signing off on the job understand both the problem and the solution In a way that allows them to go back and explain what’s going on to the people actually paying for it. Win win. :tada:

I’m not sure what “this thing” Means in this sentence. If you’re asking if Bose uses a protocol which advertises its device class the way a certified zigbee or Z wave device does, I have no idea, but I would be surprised if it did. That’s actually what the new Project CHIP group is trying to create for IP IOT devices. (“I’m a light switch. I turn on and off.“ “I’m a dimmer. I accept levelset instructions from 0 to 100%.“) but right now very few protocols do that.

I’d question that - your contributions here are brilliantly helpful. The “Classic” FAQ is a bit confusing though. Maybe needs an update.

Which begs the question - why put this degree of work into a developer ecosystem which is this complex?

The logic of that is definitely corporate because of how circular it is: we don’t have customers to develop it for, but won’t have, until we develop it.

I look at this with outside eyes and share the opinion we generally have internally (about 15 guys of whom 4 are tasked with ST on a project) - this could be so simple. Why isn’t it? Just build it into a sort of online studio, and use OAuth in the same way everyone else does, with some tutorials? Arduino is crazy complex but it’s a lot easier and more enjoyable to work with, even if you have to learn C! Take the “clever” stuff out (a la Python philosophy) and make it fun?

Thanks. :sunglasses:

As the FAQ says, I haven’t been able to keep it up-to-date because the new V3 app is not voice navigable and I haven’t kept up with the new platform. Somebody else can write a new one anytime.

And, definitely, ST was never designed by people trying to create a development tool.

Hi @JDRoberts, I’ve been on this forum for almost 2 years now and I have never seen this reiterated by any staff member. Where does this statement come from? Thanks.

It’s been posted a couple of different times by different staff members on different threads. Usually in discussions about migration from one hub to another. Also it was discussed at one of the Samsung developers conferences. I’m tired right now, but I’ll see if I can find one for you later.

@Alex_Cstr8 Are you the author of the article? There are a lot of incorrect conclusions included there and I can help clear them up if you like.

1 Like