Tutorial | Creating Drivers for LAN Devices with SmartThings Edge

Developer Programs Tutorials
1

Creating Drivers for LAN 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 custom LAN Light Bulb device.

Prerequisites

Any version of the SmartThings Hub with firmware version 38.x or greater and a LAN device ready to connect.

For this tutorial, we used an ESP8266, but the same principles can be used to integrate any LAN-based device that supports SSDP and TCP/UDP protocols.

  1. Install and Authorize your SmartThings CLI instance:

    # Using NPM, install it globally
> npm install --global @smartthings/cli

# This command will prompt you
# to the SmartThings Login Page
> smartthings edge:drivers

Note: If you have a Personal Access Token configured, delete it and try to authorize your ST CLI again.

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 help you learn more, but if you have any programming experience you’ll likely not have much trouble picking things up:

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

ESP8266 Preparation - Here

Video Tutorial

1. 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 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 Only)
  └── 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: "LAN LightBulb"
packageKey: "LAN-LightBulb"
permissions:
  lan: {}
  discovery: {}

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, your 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 Color Light Bulb:

# ./profiles/ColorLightBulb.yml
  name: ColorLightBulb.v1
  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 a Basic Light Bulb:

# ./profiles/BasicLightBulb.yml

name: BasicLightBulb
components:
  - id: main
  capabilities:
    - id: switch
    version: 1
    - id: refresh
    version: 1
    categories:
      - name: Light

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 the development of your driver, you can upload the driver from the src/ directory on your workstation.
On the command prompt at the location of the driver you created, enter the following commands:

> smartthings edge:drivers:package [DRIVER_DIRECTORY]

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

┌─────────────┬──────────────────────────────────────┐
│ Driver Id   │ e99942e5-1dd7-4f61-a587-59a10c00185a │
├─────────────┼──────────────────────────────────────┤
│ Name        │ LAN LightBulb                        │
├─────────────┼──────────────────────────────────────┤
│ Package Key │ LAN-LightBulb                        │
├─────────────┼──────────────────────────────────────┤
│ Version     │ 2021-08-30T20:23:09.302725           │
└─────────────┴──────────────────────────────────────┘

Next, create a channel for your driver:

> smartthings edge:channels:create
> ? Channel name: ST-Demo-JAST
> ? Channel description: Demo Channel For Tutorial
> ? Channel terms of service URL: https://community.smartthings.com
> ┌──────────────────────┬──────────────────────────────────────┐
> │ Channel Id           │ b4b39792-5bc5-4378-85c8-4a2b02c2d9bb │
> ├──────────────────────┼──────────────────────────────────────┤
> │ Name                 │ ST-Demo-JAST                         │
> ├──────────────────────┼──────────────────────────────────────┤
> │ Description          │ Demo Channel For Tutorial            │
> ├──────────────────────┼──────────────────────────────────────┤
> │ Type                 │ DRIVER                               │
> ├──────────────────────┼──────────────────────────────────────┤
> │ Terms Of Service URL │ https://community.smartthings.com    │
> ├──────────────────────┼──────────────────────────────────────┤
> │ Created Date         │ 2021-08-30T20:25:31.212324Z          │
> ├──────────────────────┼──────────────────────────────────────┤
> │ Last Modified Date   │ 2021-08-30T20:25:31.212325Z          │
> └──────────────────────┴──────────────────────────────────────┘

To enroll your Hub into the channel, run this command and follow the prompt:

> smartthings edge:channels:enroll

To assign your driver to the corresponding channel

> smartthings edge:channels:assign

If the package was successfully created and your Hub was properly enrolled into the channel, you can execute the command below to install the driver:

> smartthings edge:drivers:install

Once your driver has been successfully installed, you’ll see the confirmation message: “Driver <driver-id> installed to Hub <hub-id>”

Onboarding your New Device

To onboard the LAN Light Bulb according to the following instructions both devices must be under the same WiFi Network, hence, make sure your network can handle enough connections simultaneously.

  1. Setup the ESP8266 board and embedded app according to these instructions.

  2. Use your WiFi router or the SmartThings IDE > My Hubs to locate and copy the IP Address of your Hub and run the logcat command to connect to your Hub and begin listening to the Driver logs:

> smartthings edge:drivers:logcat [DRIVER_ID] --hub-address [HUB_IP_ADDRESS]

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

    a. Select Add (+) and then Device
    b.Tap on “Scan nearby” and check the logs emitted at your logcat session

If the device gets integrated successfully, you will see the following logs:

TRACE LAN-LightBulb  scanning...
TRACE LAN-LightBulb  fetching device metadata...
TRACE LAN-LightBulb  creating device...
DEBUG LAN-LightBulb  discovery device thread event handled
TRACE LAN-LightBulb  Received event with handler device_lifecycle
INFO LAN-LightBulb  <Device: 59f92dd9-0713-4ed0-a929-45fb94d30d64 (LightBulbESP8266)> received lifecycle event: added

And once onboarded, the driver will fetch the current state of the device:

TRACE LAN-LightBulb  Refreshing Switch Level
INFO LAN-LightBulb  <Device: 59f92dd9-0713-4ed0-a929-45fb94d30d64 (LightBulbESP8266)>
emitting event:
{"state": "value":0},"component_id":"main","capability_id":"switchLevel","attribute_id":"level"}
TRACE LAN-LightBulb  Refreshing Switch
INFO LAN-LightBulb  <Device: 59f92dd9-0713-4ed0-a929-45fb94d30d64 (LightBulbESP8266)>
emitting event:
{"state":{"value":"off"},"component_id":"main","capability_id":"switch","attribute_id":"switch"}
TRACE LAN-LightBulb  Refreshing Color Control
INFO LAN-LightBulb  <Device: 59f92dd9-0713-4ed0-a929-45fb94d30d64 (LightBulbESP8266)>
emitting event:
{"state":{"value":0},"component_id":"main","capability_id":"colorControl","attribute_id":"saturation"}
INFO LAN-LightBulb  <Device: 59f92dd9-0713-4ed0-a929-45fb94d30d64 (LightBulbESP8266)>
emitting event:
{"state":{"value":0},"component_id":"main","capability_id":"colorControl","attribute_id":"hue"}

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.smartthings.com/

4 Likes