Skip to main content

The Architecture of SmartThings

⚡ Quick Links

🚀 Want to publish your Matter, Zigbee, or Z-Wave device to the SmartThings catalog? Get started with Hub Connected Devices.
☁️ Want to integrate your existing cloud with the SmartThings cloud? Get started with Cloud Connected Devices.
📄 The SmartThings Capabilities Reference provides a list of abstracted device functions on the platform.
❓ Our Community is a great place to ask questions, get help, find tutorials, and more.

Welcome to the SmartThings developer documentation portal!

The SmartThings ecosystem includes over a billion Galaxy devices and Samsung appliances, millions of customers, and an ever-increasing number of partners and developers. We believe that a large ecosystem of partners is the best way to bring joyful and meaningful moments to customers. At SmartThings, we’re working towards a more integrated, innovative, and impactful future. Join us.

SmartThings provides a cohesive platform for IoT devices to interoperate and communicate, enabling smarter living solutions that enrich our world. SmartThings Developers can access a unified set of capabilities, an instant mobile UI, and leverage voice control with Amazon Alexa, Bixby, and Google Assistant.

To achieve this, we provide a robust set of development tools that empower you to build new and innovative user experiences that leverage and enhance the SmartThings platform.

The SmartThings Platform​

We believe that a great user experience starts with a great developer experience. By integrating with the SmartThings platform, you’ll be making your product accessible to millions of users. The developer documentation portal is intended to help you learn about the SmartThings platform and the different types of integrations you can build, and to provide instructions on how you can integrate your product experiences with 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 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.

tip

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​

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:

  • Rooms
  • Devices and Hubs
  • Automations
  • Scenes

And is associated with:

  • A Location Owner
  • Additional SmartThings user accounts ("Members")
  • Modes

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​

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:

  • 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.
  • 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 - A Hub connects to the SmartThings Cloud and provides platform connectivity for Hub Connected Devices.

Automations​

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.

Connected Services​

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:

Platform

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.