Skip to main content

Get Started with SmartThings Edge

Hub Connected Devices connect to a SmartThings-compatible Hub using the Zigbee, Z-Wave, or LAN protocols. A SmartThings-compatible Hub enables 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 are the new method for integrating Hub Connected Devices into the SmartThings Platform.

SmartThings Edge enables all Hub Connected device integrations to run locally on the Hub. This offers 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 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 Zigbee and Z-Wave#

    To better support 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 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())
  • 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 and a Hub-hosted live logging server.

The CLI#

The SmartThings CLI with the SmartThings Edge Plugin 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. For a complete list of Edge CLI commands, visit the Edge CLI Plugin README.

tip

The Edge CLI plugin is automatically installed when installing the SmartThings CLI.

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
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
listening for logs... ⣟

Install the Hello World Example Driver#

Ready to get started? Install the Hello World example Edge Driver below to learn more about uploading an Edge Driver to your Hub and adding your Hub Connected Device to your Hub.

tip

Ensure you are using the latest release of the SmartThings CLI and have authenticated either with the appropriate scopes, or with a PAT Token.

  1. Clone the repository below to your machine:
git clone git@github.com:SmartThingsDevelopers/SampleDrivers.git
  1. Change directories into SampleDrivers:
cd SampleDrivers
  1. Build the package and upload it to the SmartThings Cloud:
smartthings edge:drivers:package hello-world

Upon success you will see a response like this:

┌────────────────────┬──────────────────────────────────────┐
│ Driver Id │ xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx │
│ Name │ Hello World │
│ Package Key │ helloworld.example │
│ Version │ 2021-07-07T13:31:53.699513 │
└────────────────────┴──────────────────────────────────────┘
  1. Create a Driver Channel to manage your personal drivers with the smartthings edge:channels:create command. Follow the on-screen prompts to finish setting up your channel. See Driver Channels for more info on channels.
smartthings edge:channels:create
? Channel name: personal-drivers
? Channel description: My custom drivers
? Channel terms of service URL: my-tos.com
┌──────────────────────┬──────────────────────────────────────┐
│ Channel Id │ xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx │
│ Name │ personal-drivers │
│ Description │ My custom drivers │
│ Type │ DRIVER │
│ Terms Of Service URL │ https://example.com/tos │
│ Created Date │ 2021-07-07T14:48:44.316949Z │
│ Last Modified Date │ 2021-07-07T14:48:44.316952Z │
└──────────────────────┴──────────────────────────────────────┘
  1. Assign your new driver to the channel you created:
smartthings edge:channels:assign <YOUR-DRIVER-ID> <YOUR-DRIVER-VERSION> -C <YOUR-CHANNEL-ID>
  1. Enroll your Hub in your channel. This will make all drivers on the channel visible to your Hub:
smartthings edge:channels:enroll -C <YOUR-CHANNEL-ID> <YOUR-HUB-ID>
  1. Select the newly created driver and install it to your Hub:
smartthings edge:drivers:install
  1. Select the target Hub (in this case #1) and press Enter:
┌───┬──────────────────────────────────────┬─────────────────┬──────────┬──────┐
│ # │ Device Id │ Name │ Location │ Room │
├───┼──────────────────────────────────────┼─────────────────┼──────────┼──────┤
│ 1 │ xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx │ SmartThings Hub │ Home │ │
└───┴──────────────────────────────────────┴─────────────────┴──────────┴──────┘
? Enter id or index
  1. Select the channel you'd like to install a driver from and press Enter:
┌───┬──────────────────┬──────────────────────────────────────┐
│ # │ Name │ Channel Id │
├───┼──────────────────┼──────────────────────────────────────┤
│ 1 │ personal-drivers │ xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx │
└───┴──────────────────┴──────────────────────────────────────┘
? Select a channel to install the driver from.
  1. Select the driver to install (in this case #1) and press Enter:
┌───┬──────────────────────┬──────────────────────────────────────┐
│ # │ Name │ Driver Id │
├───┼──────────────────────┼──────────────────────────────────────┤
│ 1 │ Hello World │ xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx │
└───┴──────────────────────┴──────────────────────────────────────┘
? Select a driver to install.
  1. Add your device in the SmartThings app by navigating to Add a Device > Scan Nearby.