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 our 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 is the part of the Platform responsible for ensuring automations are executed, for maintaining device health, and for onboarding devices. 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.
For example, a SmartThings Motion Sensor will send Motion events to the SmartThings Cloud. The SmartThings Cloud will notify all Automations subscribed to the motion event, send notifications, and perform any other actions that have a subscription to the event.
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
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 (For information on SmartThings Schema and SmartApps, see PLACEHOLDER).
- 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 Zigbee, Z-Wave, 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.
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.