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
-
Samsung Account
-
Any version SmartThings Hub with firmware version 38.x or greater
-
Set up the SmartThings CLI according to the usage section in the repository.
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
Assign your driver to the corresponding channel
smartthings edge:channels:assign
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
-
Use your network router to locate and copy the IP Address for your Hub.
-
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
-
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) -
Put your device in pairing mode; the specifications will vary by manufacturer (for the SmartThings Multi, press the device’s reset button once).
-
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:
-
Open the URL in a web browser
-
Sign in with your Samsung Account
-
Accept the invitation
-
Invitation web page will redirect to drivers WebPage on Accept
-
Find hub you wish to install driver to
-
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.smartthings.com/