Skip to main content

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 Architecture#

The 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 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 management tools are the SmartThings CLI, a Hub-hosted live logging server, and the SmartThings Console.

The CLI#

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

The SmartThings Console#

note

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.