Skip to main content

SmartThings Edge Architecture

important

Building a custom Edge Driver is highly technical and is generally not required to bring your device to the SmartThings platform. We strongly recommend bringing your Hub Connected Device to the platform through the use of the Edge Device Builder, eliminating the need to write code or customize an Edge Driver for your device.

If you cannot find an existing Edge Driver that fits your device, contact partners@smartthings.com before proceeding with Edge Driver development.

Creating a custom Edge Driver may allow you to bring functionality not found in an existing Edge Driver to the SmartThings platform. Before getting started, we recommend familiarizing yourself with the SmartThings Edge Architecture, Edge Driver, and development tools.

The SmartThings Edge Architecture​

The SmartThings 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 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.

The SmartThings Edge Driver​

The 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.

Lua​

At 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.

Libraries​

  • Driver 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.

    local example_driver = Driver("example", {
      discovery = handle_discovery,
      lifecycle_handlers = {
        added = device_added,
        init = device_init,
        removed = device_removed
      },
      capability_handlers = {
        [capabilities.switch.ID] = {
          [capabilities.switch.commands.on.NAME] = command_handlers.switch_on,
          [capabilities.switch.commands.off.NAME] = command_handlers.switch_off,
        },
      }
    })

    example_driver:run()

    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.

    device:emit_event(capabilities.switch.switch.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 Tools​

The primary development tools for Edge Driver development include:

Code Lab

Want to learn how to build a sample SmartThings Edge Driver interactively? Visit the Create a SmartThings Edge Driver for an IoT bulb code lab to get started.

The 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:

smartthings edge:drivers:package [path_to_dir]

To install a package to a hub:

smartthings edge:drivers:install [ID]

To uninstall a package from a hub:

smartthings edge:drivers:uninstall [ID]

To delete a package from SmartThings:

smartthings edge:drivers:delete [ID]

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:

$ smartthings edge:drivers:logcat --hub-address=10.0.0.37
┌───┬──────────────────────────────────────┬─────────────────────────────────────┐
│ # │ Driver Id                            │ Name                                │
├───┼──────────────────────────────────────┼─────────────────────────────────────┤
│ 1 │ xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx │ Hello World                         │
└───┴──────────────────────────────────────┴─────────────────────────────────────┘
? Select a driver. 1
connecting... connected
2021-07-23T19:23:33.285429119+00:00 INFO Hello World  Starting Hello World Discovery
2021-07-23T19:23:33.291739786+00:00 INFO Hello World  Adding new Hello World device

Certification Tools​

tip

Learn more about certifying your Hub Connected Devices in Certify Your Device.

Works With SmartThings (WWST) Certification tools include:

  • The Edge Device Builder - A quick and easy way to certify your Hub Connected Device. After joining your device to your SmartThings account, this tool helps match your device with a pre-built Device Profile and submit for certification without the need to modify existing Edge Drivers or add code.
  • The Certification Console - Manage your certification submissions, including defining device onboarding profiles, managing your brand, and submitting device certification requests.

If you need functionality beyond what an existing Edge Driver and the Edge Device Builder can provide, you can submit a pull request against the SmartThingsEdgeDrivers GitHub repository with your driver customizations. Contact us at partners@smartthings.com before modifying an existing driver.