The Architecture of SmartThings
Before you start developing, it’s important to understand the basic principles behind the SmartThings Platform. In this section we define several key components, or basic building blocks, of the Platform.
#The SmartThings Platform
The SmartThings Platform encompasses all of the components required to execute the functions and capabilities of the SmartThings ecosystem. This includes executing a user's request, enabling device and cloud-to-cloud communication, running Automations, monitoring events in a user's home and in the SmartThings Cloud, and more.
#The SmartThings Cloud
The SmartThings Cloud is the part of the Platform responsible for ensuring complex automations are executed, for maintaining device health, for onboarding devices, and for allowing users to remotely access their Devices and Automations through SmartThings Clients, such as through the SmartThings app.
The SmartThings Cloud is built using standard data entities and subscriptions for the home, car, and life. Devices and Connected Services use these data entities to display data, track events, trigger automations, and more.
With the launch of SmartThings Edge, we are taking some events that would have happened in the Cloud and moving them to the SmartThings Hub. SmartThings Edge uses Lua-based device drivers and our Rules API to control and automate devices connected directly to a SmartThings Hub. This includes Matter, Zigbee, Z-Wave, and LAN devices as well as automations triggered by timers and other Hub Connected Devices using drivers.
#Users and Accounts
A Samsung account is required to access the SmartThings Platform.
Multiple users, or members, may have access to a shared Location, but only one user is considered the owner of a Location. Any member of a given Location typically has access to all properties and associations of the Location (such as Automations, SmartApps, Devices, Rooms, and Scenes).
Locations are created by users - usually from within the SmartThings app - for grouping hubs, devices, and automations together into a logical group. Locations are usually tagged with a geolocation.
A Location can have:
- Devices and Hubs
And is associated with:
- A Location Owner
- Additional SmartThings user accounts ("Members")
Locations can be identified and managed using the LocationID. You can have up to 10 Locations associated with a user.
Modes are always associated with Locations. A Mode is the user-specified state of a Location such as Away, Home, or Night. Modes are useful for incorporating into an Automation (more on that later).
Rooms, also typically created by users in the SmartThings app, are a subgroup that exists inside a Location. A room is used to group:
- Devices and Hubs
Rooms can also be managed using the Rooms API. Refer to the SmartThings API documentation for more information
#Devices and Hubs
Devices are physical products that connect to the SmartThings Platform. Types of Devices include:
- Cloud Connected Device - Devices that communicate with the SmartThings Cloud through a third-party cloud. This includes SmartThings Schema and select products that connect using a SmartApp.
- Direct Connected Device - Devices that connect directly to the SmartThings Cloud via WiFi. This includes Samsung Appliances, products from third-party OEMs using protocols such as OCF and MQTT, and more.
- Mobile Connected Device - Devices that communicate with the SmartThings Platform via a mobile device. This typically includes Bluetooth products that connect via your mobile device, such as wearables and headphones.
- Hub Connected Device - Devices that connect directly to a SmartThings Hub to communicate with the SmartThings Platform. This typically includes Matter, Zigbee, Z-Wave, LAN (via SmartThings Edge Drivers), and Bluetooth products.
- Hub - A Hub connects to the SmartThings Cloud and provides Platform connectivity for Hub Connected Devices.
Automations are used to automate Devices and Connected Services that are on the SmartThings Platform. Examples include turning a light off when a user’s Location changes, or sending a notification when a motion sensor is triggered.
There are two types of Automations on the SmartThings Platform:
- Rules enable you to automate the Devices and services that connect to the SmartThings Platform.
- Scenes enable you to simultaneously set a group of devices to a particular state.
Automations appear in the Automations section of the SmartThings app. They are associated with a Location and not an individual user account; all users with access to the Location will therefore have access to all Automations created for the Location.
The second method to control and automate your devices is by building a Connected Service. With a Connected Service, you can subscribe to events, run the automation logic on your server, and send events back to the device you want to automate.
While Automations and Connected Services share some similarities, Connected Services are typically used to build connections outside the SmartThings Platform. Connected Services can connect a user’s smart home to the broader world through third-party apps, services, and integrations.
#Visualizing the Platform
Here's a look at how these concepts work together on the SmartThings Platform. The high-level diagram below shows the Platform connections as they exist after a user’s smart home setup is complete:
Notice that the user account shown is associated with one Location containing two rooms. Remember, a user account can be associated with more than one Location, and multiple users can be associated with a single Location.
Also note that this diagram shows a single hub with connected devices in two separate rooms. Typically, SmartThings recommends Locations have a single hub. In some instances however, a user may have multiple hubs at a Location. Devices connected to two different hubs in the same Location can communicate with each other and are displayed in the SmartThings app no differently than if the devices were connected to the same hub.