Tutorial | Creating Drivers for Zigbee Devices with SmartThings Edge

Creating Drivers for Zigbee Devices with SmartThings Edge

SmartThings Edge is our new architecture for Hub Connected devices that uses Device Drivers to execute commands locally on SmartThings Hubs. In this tutorial you will learn how to create a SmartThings Edge Driver for a Zigbee device - the SmartThings Multi Sensor.


Prerequisites

  1. Samsung Account

  2. Any version SmartThings Hub with firmware version 38.x or greater

  3. Set up the SmartThings CLI according to the configuration document.

You will be using the CLI to interact with and publish drivers. If you need instructions on installing the CLI you can find them on the Documentation Portal.

Edge Drivers are written in Lua, an easy-to-use scripting language. If you are not familiar with Lua, here are some good resources to get you started:

PRO TIP: set up your IDE to allow for autocompletion and enable the type hints provided by the library.


Video Tutorial


Written Guide


Crafting your Driver

Package Structure

The structure of your Driver can change based on the type of device (e.g., LAN devices do not have fingerprints). Driver packages are commonly organized into the following hierarchy with the logic of your driver residing in the src folder.


package

β”œβ”€β”€ config.yaml

β”œβ”€β”€ profiles

β”‚        β”œβ”€β”€ { Profile Name }.yaml

β”‚        └── { Other Profile Name }.yaml

β”œβ”€β”€ fingerprints.yaml (Zigbee/Z-Wave)

└── src

         β”œβ”€β”€ init.lua

         β”œβ”€β”€ file1.lua

         β”œβ”€β”€ file2.lua

         └── <folder>

           β”œβ”€β”€ init.lua

           └── file3.lua

Config.Yaml

config.yaml is the package definition file. Here you define the package name and package key. Each of your package key names needs to be unique within your developer account.


name: 'Zigbee Sensor'

packageKey: 'zigbee-sensor'

permissions:

  zigbee: {}

Profiles Directory

A Device Profile defines a Device and its features (e.g., Capabilities) on the SmartThings Platform. The profiles directory allows your driver package to support more than one type of device. Each type of device must be defined in its own .yaml file.

For example, a driver package can support both the color and non-color versions of your light bulb, but each bulb would have a separate profile.

Here is an example of a Profile for a generic color changing light bulb:


./profiles/color-bulb.yaml

name: color-bulb

components:

  - id: main

    capabilities:

    - id: switch

      version: 1

    - id: switchLevel

      version: 1

    - id: colorControl

      version: 1

    - id: refresh

      version: 1

    categories:

     - name: Light

Here is an example of a Profile for the most basic of light bulb:


./profiles/bulb.yaml

name: bulb

components:

- id: main

  capabilities:

  - id: switch

    version: 1

  - id: refresh

    version: 1

  categories:

  - name: Light

Fingerprints.yaml

In order to correctly onboard Zigbee and Z-Wave devices, you must include the Fingerprints with the Driver. In the Fingerprint, you are binding a Device Type to a Device Profile. These will allow the Hub to apply the correct Profile to your hardware.

In fingerprints.yaml, you should define all of the hardware variants supported by the package

Example Fingerprint:


zigbeeManufacturer:

  - id: "Samjin/multi"

    deviceLabel: Multipurpose Sensor

    manufacturer: Samjin

    model: multi

    deviceProfileName: st-multipurpose

  - id: "SmartThings/multiv4"

    deviceLabel: Multipurpose Sensor

    manufacturer: SmartThings

    model: multiv4

    deviceProfileName: st-multipurpose

SRC Directory

The src directory contains the Lua code and any supporting files specific to your driver. Here you will define the device command handlers, event handlers, discovery services, and any other helper functions that may be required.


Uploading Your Driver to SmartThings

Once you wrap development of your driver, you can upload the driver from the source directory on your workstation.

On the command prompt at the location of the driver you created, enter the following commands:


    smartthings edge:drivers:package [PROJECTDIRECTORY]

The output of this command will be the Driver Id, Name, Package Key and Version.

Next, create a channel for your driver


    smartthings edge:channels:create

Enroll your driver into the channel


    smartthings edge:channels:enroll

Publish your driver to the channel


    smartthings edge:drivers:publish

If the package was successfully created, you can call the command below and follow the on-screen prompts to install the Driver in your Hub :


    smartthings edge:drivers:install

You should see the confirmation message: β€œDriver {driver-id} installed to Hub {hub-id}”


Onboarding your New Device

  1. Use your network router to locate and copy the IP Address for your Hub.

  2. From a computer on the same local network as your hub, open a new terminal window and run the command to get the logs from all the installed drivers.


    smartthings edge:drivers:logcat

  1. Open the SmartThings App and go to the Location where the Hub is installed.

    a. Select Add (+) > Device
    
    b.Tap on β€œScan nearby” (If you have more than one, select the corresponding Hub as well)
    
  2. Put your device in pairing mode; the specifications will vary by manufacturer (for the SmartThings Multi, press the device’s reset button once).

  3. Keep the terminal view open until you see only reporting values messages in the logs.

Example Output


<ZigbeeDevice: device-id [source-id] (Multipurpose Sensor f1)> emitting event: {"attribute_id":"temperature",

"component_id":"main","state":{"unit":"C","value":28.66},"capability_id":"temperatureMeasurement"}

If your Device paired correctly and the Driver was applied, you should not see any errors in the logs (including β€œUNSUPPORTED” responses to any Zigbee TX message). You can validate this by opening the SmartThings app and controlling and/or viewing all of the devices Capabilities (e.g., open/close or change the temperature).


Distributing your Driver with Channels

With SmartThings Edge, you can use Driver Channels to publish and distribute your driver to others. Here are steps to get started:

Create Invitation to Share Your Channel


smartthings edge:channels:invitations:create

This will return a unique URL for the web page to accept the invitation.

Joining a Driver Channel / Accessing a Shared Driver

Once a developer invites you to their channel, you can access it with the following steps:

  1. Open the URL in a web browser

  2. Sign in with your Samsung Account

  3. Accept the invitation

  4. Invitation web page will redirect to drivers WebPage on Accept

  5. Find hub you wish to install driver to

  6. Enroll Hub into Channel

Note: As the developer you can determine when to update all installations that use your Driver Channel by assigning the new version to the channel.


Additional Notes on Local Execution


Drivers are executed locally on SmartThings Hubs. Automations that use only Edge drivers and local Actions (e.g., time of day) will execute locally.

For more information on SmartThings Edge, stay tuned to our Developer Community and visit https://developer-preview.smartthings.com/

13 Likes