After going through the online documentation/website and seeing the architecture page (http://docs.smartthings.com/en/latest/introduction/smartthings-architecture.html), I am still unsure of a few things. So to interact/develop for the SmartThings platform you have to use the SmartThing mobile app? I can’t develop a completely separate iOS/Android (or some other OS) app using the SmartThings API for interacting with the devices? And “SmartApps” are not actual applications at all? They are more like a “widget” within the SmartThings mobile app?
Ummm… Not exactly.
I could write an entire alternate developers guide here, but that seems inefficient.
Send me a Private Message and we could Skype or other screen share for a few minutes and I could give you a tour…?
I am not sure how to do private messages through this forum?
Click on my avatar icon (Beagle face) and near the top left of my Profile page there should be a Private Message button.
Too bad this is going private…sounds like an interesting topic.
I am sorry for the trouble, but when I go to your profile, I see no way to private message you. Not activated since I just joined? Needs to be unlocked? Are you able to private message me?
Oh… I will definitely share a summary that should still be useful and maybe come up with recommendations for additions to the Documentation for @Jim and/or FAQ.
Done. Check your notifications 
Excellent! That would be apprecaited
2 Likes
OK… so here’s a rough summary of what @balkcivil and I discussed. I’m hoping @Jim takes note and will be able to tell us what is planned in the short term documentation, with the rest going into the Community FAQs that @April is encouraging us to write …
This is meant to be a rough draft overview and may have various degrees of inaccuracy or consistency.
Terminology Is Important: Documentation Needs a Glossary?
-
A SmartApp is not a mobile app (and certainly not THE SmartThings Mobile App). A SmartApp is often just a “rule” or “recipe” (
if <open> then <turn on> <light>), where<x>are parameters – called Preferences in a SmartApp. A SmartApp, however, can be much more complex than basic rules, as developers write them with Groovy methods, access to some Java libraries, etc…; but they run in a sandbox as described in the Documentation. SmartApps are also used define Web Services end-points for External Applications. -
A Device Type is called SmartDevice Type in the Reference Documentation. I wish we had official acronyms to save typing… SDT?
-
Device is a Class distinct from SmartDevice Type but has a lot of attributes and methods that map to the applied SmartDevice Type.
-
I still don’t know the best definition of Thing, especially compared to Device. The terms seem sometimes interchangeable in the Documentation, so it would be good to clarify.
-
SmartThings currently does not have any “widgets”. In tech terminology “widget” now commonly means a simple or highly functional user interface object that is placed on the desktop or other top level grouping on a phone, tablet, or computer. It is often a “shortcut” to the functionality of the full app installed on the same mobile or computer. The term “widget” is also similar to the term “control”, which is a user interface object within an panel in an app/application. – SmartThings calls these Tiles and they are available for developers to build a user-interface in a SmartDevice Type. http://docs.smartthings.com/en/latest/device-type-developers-guide/anatomy-of-a-device-type.html
-
There are probably other ambiguous terms applicable to this Topic.
External Applications
-
I define External Applications as applications other than SmartApps, the Mobile App, and the Developer Webpages & IDE (graph.api.smartthings.com). Some examples are *IFTTT, The Ubi,
and **ActiON Dashboard". -
The Documentation about External Applications is at http://docs.smartthings.com/en/latest/smartapp-web-services-developers-guide/index.html ; but seems to be less complete than some 2013 drafts that I have seen. I am presuming that so much of the old drafts is deprecated that they are no longer useful; but I also think that current documentation does not fully document the REST-API and give enough examples.
The “2013 drafts” that I mention are marked as copyright or internal, so I can’t share them directly. -
External Applications cannot be used to add or remove a Device from SmartThings (currently). The Mobile App must be used (though there are some force delete options available in the API).
-
External Applications have access to a limited sub-set of REST-API endpoints without authorization, and a few more end-points with a general user login authorized id-key. Some examples, possibly deprecated, are in a community shared document on GitHub:
https://github.com/tmaiaroto/smartthings-unofficial-docs/blob/master/Documentation.md -
External Applications have “full” (get and put) access to the REST-API endpoints applicable to each Device, only after obtaining the user’s authorization for each device via the OAUTH steps described in the official Developer’s Guide Documentation:
http://docs.smartthings.com/en/latest/smartapp-web-services-developers-guide/index.html. -
This (and various discussions on SmartThings’s architecture and security model) implies and means that each time a user adds a new Device (which must be done via SmartThings Mobile App…), the authorization step needs to be redone for the External Application. So even a “full featured” External User Interface Application (like the ActiON Dashboard) cannot access new devices using the originally granted access token.
I compared OAuth process to authorizing your Facebook account to be accessed by various services such as Rotten Tomatoes. There is some degree of granularity (Post on Feed with Public, Friends, Group of Friends, or “only me”; and so on). NB: in the Facebook analogy, if you add new Friends, Rotten Tomatoes does not need a new authorization (since Facebook’s granularity is at the Group of Friends level, but SmartThings is at the individual Device (Thing?) Level. -
This needs clarification and clearer wording:
A special custom REST-API exposing SmartApp is required for some (most?, all?) External Applications, and there is an instance of these SmartApps for each External Application authorization. IFTTT and ActiON Dashboard are examples of this (the code is only shared for the latter). Authorizing The Ubi, though, doesn’t seem to need or create one of those SmartApp instances; so perhaps there are many default REST-API endpoints available and authorizable without a custom SmartApp (or more likely, I’m just not seeing The Ubi SmartApp … is it hidden or I’m lost?). -
The Open Sourced ActiON Dashboard is likely an excellent example of an External User Interface Application because it provides a full-featured User Interface using SmartThings Web Services (with a
custom SmartApp to provide the REST-API endpoint mappings, etc.).
Questions and comments welcome!
…CP / Terry.
I am watching/listening.
But not in the creepy way 
1 Like
Pay no attention to the man behind the curtain.
1 Like
Great start!
One small thing: I’m confused about who the intended audience is.
If it’s people who have previously coded, the explanation of “widget” should be rewritten. This one from Android world is good
A BRIEF TANGENT: TILES VS WIDGETS
Although Tiles have been becoming more like widgets, and pressing a ST tile does send an action request, I think the use of the term Tiles as is probably makes more sense. These look like Tiles and it’s a standard GUI term.
Tiles imply a specific rectangular format, a typical margin size, the display of a very small amount of information, often only a label, and a minimal amount of processing resources, all of which ST tiles have.
It could be argued either way, but for simplicity’s sake I think I’d just call Tiles Tiles.
BACK TO THE AUDIENCE
If the audience is technical, I really like the official definition of smartapps at the following link:
Similarly, if the audience is technical, I see no reason to avoid mention of web services, which is what the section about “external applications” seems to be trying to do. IFTTT, Ubi, Sonos, etc are web services, behave like web services, and should be familiar to most people who are coders.
I understand “web services” is a term which tends to confuse the heck out of nontechnical people, and I applaud a desire to not confuse them–but once you’ve thrown in discussion of oauth and REST API I think we’re well over that line, right? Which is why defining the audience is so important.
just some thoughts…
2 Likes
According to ST marketing publications, a Thing is a “smart device.” As in Internet of Things. Interchangeable terms.
Which make SmartThings “smart smart devices”, but I guess it sounded better than “SmarterThings.” 
1 Like
I started playing with SmartThings, specifically Device Types, last week. The documentation does not effectively describe the object model and workflow. I’ve wasted a lot of hours experimentally determining how things work, sifting through templates, and searching the forums. This last method for finding information found a lot of results that indicate that it has been this way for a while.
How about a clear list of types, with their properties and methods, along with their relationship (if any) to the metadata. Then, map the metadata back to the types, and show us where in the workflow they come into play (so we have an idea of context and scope).
I’ll probably make a more detailed post in the Devices forum (because Device Type, not SmartApp) regarding what I [think I] figured out in the last week.
3 Likes
This is a worthwhile effort and contribution to the Community. Thank-you!
Please aim to make it a FAQ Topic under this Category:
http://community.smartthings.com/c/devices-integrations/faq
You will get plenty of us to pitch in to answer your piece by piece questions and suggest edits.
SmartThings is working on better documentation, but sometimes the best way is to… demonstrate what documentation “we” think is essential.
PM me if you want any help.
Terminology of tiles vs. widgets aside, I think the first-exposure confusion is because people see “App”, and start looking for something that they interact with. A SmartApp is, if I understand correctly, not something that you interact with. It’s UI is limited to configuration because the SmartApp’s function is tie together devices and services with whatever additional rules are coded into the SmartApp. Meanwhile, what the user can use to control devices are the Device Types, which have the Tile UI, and nothing sounding like “app” in their name.
I think the confusion might also distract from the point that the intent is for any UI to be used primarily for configuration of automated relationships, or for simple mode-change request (though these, more often than not, would probably be coming into one of these relationships from someplace other than the SmartApps UI).
Personally I never had that feeling, but I agree it was perhaps an unfortunate choice of terminology that a User Experience consultant might have fixed. But that ship has long sailed.
The Mobile App is a relatively distinct piece of the system, can perhaps be used rarely, and yet people need a way to visualize the growing complexity of their home, devices, and SmartApps.
If I were to wildly speculate, I would not be surprised to see a complete overhaul of the Mobile App (+ an html app) just because UI overhauls are rather common (Skype, PayPal, Google mobile apps,…) and can be done independently of back end architecture changes.
[quote=“llamas, post:17, topic:10921, full:true”]Meanwhile, what the user can use to control devices are the Device Types, which have the Tile UI, and nothing sounding like “app” in their name.
[/quote]
I think it’s a little different than that, because of the Hello Home Actions, which are limited option scenes. (When X happens, have this device do that. For multiple devices.)
I suspect in the future the most typical homeowner will simply find devices through the pretty automated pairing process. This will use standard device types.
After that, the interaction will be through setting up the Hello Home Actions or using the future Rules Engine through the mobile app, once for each rule set.
And after that, it’s letting the automatic stuff run automatically, and initiating manual actions through either the ST mobile app or a physical controller.
So I think most customers will never touch the IDE, or look at the code for a Device Handler.
( Oh, another weird terminology thing…you’re writing in Groovy, a language which runs in the Java environment. But what the IDE calls MY DEVICES are I think actually device handlers, not device types. The device types are included inline in the groovy code for the smartapp, and are a typical OO interface.)
So most coders will write or borrow device handlers, and work with those through the custom code in a smartapp.
Once the smartapp is written, it has to be associated with some trigger. This could be a timed schedule or a device doing something, often a switch or a sensor.
Also, be very careful when using the word “mode.” It doesn’t just mean a device state in SmartThings, like turning a light On or Off. Those are not considered Modes. Instead, see this explanation:
From Development home page:
Device types are the abstraction layer that allow developers to build applications that connect and communicate with new types of devices and SmartApps. Learn more. Make your own device types using the development tools.
Regardless, my first stop for Terminology are the Class definitions under Reference Material, though it’s hardly solid.