Skip to main content

Driver Components and Structure

A SmartThings Edge Device Driver consists of 4 main components:

  • A configuration file
  • Fingerprint (optional)
  • The driver code itself
  • Device profiles for the supported devices

Structure#

package
├── src
│ ├── init.lua
│ ├── file1.lua
│ ├── file2.lua
│ └── <folder>
│ ├── init.lua
│ └── file3.lua
├── profiles
│ ├── { Profile Name }.yaml
│ └── { Other Profile Name }.yaml
├── config.yaml
└── fingerprints.yaml (optional)
note

fingerprints.yaml should not be included in packages for Drivers that don't define fingerprints (LAN devices). Fingerprints are currently required for Zigbee and Z-Wave devices.

Configuration File#

The configuration file is a manifest and contains metadata for the driver.

Example

# config.yaml
name: 'Hello World'
packageKey: 'helloworld.example'
permissions:
lan {}
discovery: {}
  • name: Name of driver
  • packageKey: Unique identifier of the package
  • permissions: List of necessary permissions to control the device

Permissions are used to control what external APIs a driver can interact with. Currently, the options are very broad and cover only the different device types. Start by selecting one of the following configurations:

LAN:

permissions:
lan: {}
discovery: {}

Zigbee:

permissions:
zigbee: {}

Z-Wave:

permissions:
zwave: {}

Fingerprints#

Some devices, usually mesh, are added to the SmartThings Platform through the use of a fingerprint. Upon a device being discovered by the Hub, some properties of the device are read and a device fingerprint is created. The fingerprint is then sent to the SmartThings Cloud to look for a matching fingerprint. Upon a successful match, the Edge Driver associated with the fingerprint is then installed to the Hub to enable device operation.

LAN devices are an exception to this process. Refer to the LAN Edge Device Driver Development Guide for more details.

Example

# fingerprints.yaml
zigbeeManufacturer:
- id: "SmartThings/motionv4"
manufacturer: SmartThings
model: motionv4
deviceProfileName: { Profile Name }
deviceLabel: { Device Label }
  • id: Unique identifier for fingerprint, namespaced by the driver
  • manufacturer: Reported manufacturer of a device\'s endpoint
  • model: Reported model of a device\'s endpoint
  • deviceProfileName: Name of device profile that device should use
  • deviceLabel: Label to initialize device record with

Driver#

The Driver is the Lua code itself. This code will run on the Hub and implement code necessary for communications to and from the device (refer to the Driver structure).

For code contents of a Driver, visit Write Your First Lua Driver.

Profiles#

Device profiles describe the type of device and its capabilities to the SmartThings Platform

In the example below, hello world will appear as a light switch to the Platform.

# hello-world-profile
name: hello-world.v1
components:
- id: main
capabilities:
- id: switch
version: 1
categories:
- name: Light
important

Package updates that remove a profile name will be rejected. Devices already using the removed profile would not reflect newly created devices to clients.