Creating Drivers for Z-Wave Devices with SmartThings Edge

Creating Drivers for Z-Wave 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 Z-Wave device - the Aeotec Z-Wave MultiSensor 6.


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 here [Install CLI Tutorial Link].


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: 'Z-Wave Aeotec Multisensor'
packageKey: 'zwave-aeotec-multisensor'
permissions:
  zwave: {}

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/model of device. Each type of device must be defined in its own .yaml file.

For example, this driver package uses a single fingerprint for the four different models of the Aeotec MultiSensor (see Fingerprints.yaml) as all have the same capabilities. However, we could separate them to assign a different profile to each one of them.

Note we are setting up the motion clear time as a custom preference.

# ./profiles/aeotec-multisensor-profile.yml
name: aeotec-multisensor-pr
components:
- id: main
  capabilities:
  - id: motionSensor
    version: 1
  - id: illuminanceMeasurement
    version: 1
  - id: temperatureMeasurement
    version: 1
  - id: battery
    version: 1
  - id: healthCheck
    version: 1
  categories:
    - name: MotionSensor
metadata:
  deviceType: MotionSensor
  ocfDeviceType: x.com.st.d.sensor.motion
  deviceTypeId: MotionSensor
preferences:
  - title: "Motion Clear Time"
    description: "PIR time in seconds (default 240)"
    required: false
    preferenceType: integer
    definition:
      minimum: 10
      maximum: 3600
      default: 240
  - title: "Motion sensor sensitivity"
    description: "0-5 where 0 disables the sensor (default 5)"
    required: false
    preferenceType: integer
    definition:
      minimum: 0
      maximum: 5
      default: 5

If a device model had a different configuration (capabilities, metadata, etc.), we would create another profile like the one below where the capability “Temperature Measurement” was removed.

# ./profiles/aeotec-multisensor-profile2.yml
name: aeotec-multisensor-2
components:
- id: main
  capabilities:
  - id: motionSensor
    version: 1
  - id: illuminanceMeasurement
    version: 1
  - id: battery
    version: 1
  - id: healthCheck
    version: 1
  categories:
    - name: MotionSensor

Preferences.lua

motionClearTime is a custom preference that will configure the Z-Wave parameter 3. We can then refer to this custom variable in other areas of the code.

local preferences = {
  motionSensorSensitivity = {parameter_number = 4, size = 1},
  motionClearTime = {parameter_number = 3, size = 2}
}

return preferences

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:

zwaveManufacturer:
  - id: "Aeotec/ZW100-X"
    deviceLabel: Aeotec MultiSensor 6
    manufacturerId: 0x0086
    productId: 0x0064
    deviceProfileName: aeotec-multisensor-pr

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

  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 Aeotec MultiSensor 6, press the device’s action button once).

  3. Keep the terminal view open until the “infoChanged” lifecycle event is received and the driver starts getting the REPORT commands from the device.

Example Output

If your Device paired correctly and the Driver was applied, you should not see any errors in the logs. You can validate this by opening the SmartThings app and controlling and/or viewing all of the devices Capabilities (e.g., motion 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 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 the 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.

Delete the device

  1. Open the SmartThings App, select the hub where the device was included.

  2. Go to menu (three dots symbol) > Z-Wave utilities

  3. Select “Z-Wave exclusion” to put the hub in exclusion mode.

  4. Click the action button on the device once. You should see a success message on this page and the led of the device should flash.


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 developer.samsung.com/SmartThings

3 Likes