Get Started with SmartThings Edge
Hub Connected Devices connect to a SmartThings-compatible Hub using the Matter, Zigbee, Z-Wave, or LAN protocols. A SmartThings-compatible Hub enables Matter, Zigbee, Z-Wave, and LAN Devices to integrate with the SmartThings Platform, allowing you to view and control your Devices from SmartThings clients and incorporate these Devices into Automations and more.
SmartThings Edge Device Drivers integrate Hub Connected Devices into the SmartThings Platform. Edge drivers enable all Hub Connected device integrations to run locally on the Hub, offering a number of benefits including speed, reliability, and enhanced functionality.
note
See (Legacy) Device Type Handlers for information on DTH/Groovy integrations.
#
The SmartThings Edge ArchitectureThe Platform represents all devices through our Capabilities model. The Edge Device Driver translates to and from this unified model into the device-specific network protocol for each device type, allowing for device control and for translating device messages to events.
For example, when a driver for a light bulb receives an on
Capability
command, the driver will then build and send a message over the network
to the bulb it is connected to. When the driver receives a notification
over the network that the bulb has been turned off via external means,
it will send a capability attribute report to inform the Platform that
the bulb is now off.
Below, we look at some of the many features the SmartThings Edge architecture offers:
✅ Built with Lua
SmartThings Edge is built with the Lua© scripting language and supports many of the preexisting Lua libraries. To maintain security and ensure compatibility across CPU architectures, SmartThings Edge only supports libraries written in Lua.
✅ Real Network Sockets
SmartThings Edge supports most of the LuaSocket API, enabling new device integrations. This API supports direct TCP, TLS, and UDP socket access including UDP Multicast and Broadcast. This enables the use of protocols such as Websockets, Protocol Buffers, and more.
✅ One Driver Per Integration
One driver can be written to support a full Integration including many device types. With SmartThings Edge, a single driver can handle various device types including bulbs, plugs, motions sensors, and more.
✅ Robust Libraries for Matter, Zigbee, and Z-Wave
To better support Matter, Zigbee, and Z-Wave devices, we created libraries that facilitate communication with these devices, including default handling for common behavior. Custom handling is also allowed for devices that require it.
#
About the SmartThings Edge DriverThe driver describes everything necessary to integrate a device into the SmartThings Platform. Once the driver is created, the CLI can be used to upload the package, install to a Hub, uninstall from a Hub, and to delete the driver from the platform. For more information on the driver format and for an installable example driver, see Driver Components and Structure.
#
LuaAt the core of the driver is one or a set of Lua files. These files are responsible for handling commands from the rest of the SmartThings Platform and for generating the protocol-specific messages used to control devices. They are also responsible for decoding messages from devices and generating SmartThings events.
#
LibrariesDriver Library
The Driver Library is the foundational library of an Edge Device Driver. It coordinates all standard work necessary for a functioning device. The two main APIs every driver will use are the driver instantiation call and the run call.
The Driver Library can also create timers and other useful core functionality.
Device Library
The device library provides APIs for emitting events and storing data for a device. Properties of the device are also available such as the
device.device_network_id
.
Capability Library
SmartThings Capabilities are exposed to Edge Device Drivers using the capability library. For more information regarding Capabilities visit the Capabilities Reference.
In order to handle commands, Capability commands are registered with corresponding handlers in the driver initialization.
To emit events, call
emit_event
on the device the event occurred on.Matter Library
This library provides the necessary APIs to handle communications to and from Matter devices.
Zigbee Library
This library provides the necessary APIs to handle communications to and from Zigbee devices.
Z-Wave Library
This library provides the necessary APIs to handle communications to and from Z-Wave devices.
#
Development ToolsThe primary management tools are the SmartThings CLI, a Hub-hosted live logging server, and the SmartThings Console.
#
The CLIThe SmartThings CLI is the command line tool used to manage SmartThings Edge Device Drivers. The CLI enables you to easily build packages and upload them to the SmartThings Cloud to download and run on your Hub.
To build and upload a package:
To install a package to a hub:
To uninstall a package from a hub:
To delete a package from SmartThings:
The CLI also allows you to view logs generated by your driver and by the driver libraries. Live logging is hosted directly by the Hub. Device events as well as any log or print statements in the driver are included in the live log. Logs may be viewed using the edge:logcat
command:
#
The SmartThings Consolenote
Developers not submitting a device for WWST certification can skip this section.
The SmartThings Console is how device manufacturers submit Hub Connected Devices backed by Edge Drivers for Works With SmartThings (WWST) Certification.
important
For Device Certification, it is strongly recommended to start the Edge Driver development process by simply adding a fingerprint to an existing Edge Driver.
You can find existing Edge Drivers in the SmartThingsEdgeDrivers
GitHub repository
If you do not find an existing Driver and Device Profile that match your desired user experience and you wish to create a new Device Profile, add a sub-driver, or add a new Edge Driver, contact us at partners@smartthings.com before proceeding.
Reasons you may want explore a new Device Profile:
- The existing profiles do not have the set of capability combinations your user experience requires.
Reasons you may want to explore a new sub-driver:
- Your capability handling executes in a manner different from any existing sub-driver.
caution
Before proceeding with Edge Driver development for a device intended for certification, we recommend reviewing the Code Formatting and Submission Criteria.