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 required for Matter, 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.

info

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

There are two main types of fingerprints:

Manufacturer-specific fingerprints are used when a device is matched based on the specific manufacturer and model information of the device.
Generic fingerprints match based on the functionality that the device reports that it supports.

What exists in the definition for these fingerprints is dependent on protocol and fingerprint type. Below are examples and explanations of the different fingerprint categories.

How is a fingerprint chosen?#

Given the options below as fingerprints, a device may potentially match multiple fingerprints. In this case, a "best match" must be selected. Because manufacturer-specific fingerprints are very specific and intentional based on the individual devices, a match to a manufacturer-specific fingerprint will always be preferred over a match to a generic fingerprint. And a generic fingerprint will be prioritized if it matches more fields than fewer fields

Shared Fields#

There are three fields used by all fingerprints:

id: A unique identifier for a fingerprint, name-spaced by the driver.
deviceProfileName: The name of the device profile that the device should use (defined within your driver package).
deviceLabel: A label used when creating a record for the device on the SmartThings Platform. This label will be displayed in the SmartThings clients, such as the mobile app.

Matter#

Manufacturer-Specific Fingerprints#

# fingerprints.yaml
matterManufacturer:
  - id: "Samsung/DoorLock/Wifi"
    deviceLabel: Samsung Door Lock WiFi
    vendorId: 0x10E1
    productId: 0x3002
    deviceProfileName: base-lock

vendorId: Reported vendor of a matter device
productId: Reported product ID for the device

Generic Fingerprints#

# fingerprints.yaml
matterGeneric:
  - id: generic-temperature-and-humidity
    deviceLabel: "Temperature and Humdity Sensor"
    deviceTypes:
      - id: 0x0302 # Temperature Sensor
      - id: 0x0307 # Humidity Sensor
    deviceProfileName: temperature-and-humidity-sensor

deviceTypes: The Matter device types to match when checking all of a devices endpoints.

tip

In general, when multiple generic fingerprints match, the one with the most device types will be chosen.

Zigbee#

Manufacturer-Specific Fingerprints#

# fingerprints.yaml
zigbeeManufacturer:
  - id: "SmartThings/motionv4"
    manufacturer: SmartThings
    model: motionv4
    deviceProfileName: { Profile Name }
    deviceLabel: { Device Label }

manufacturer: Reported manufacturer of a device's endpoint
model: Reported model of a device's endpoint

Generic Fingerprints#

# fingerprints.yaml
zigbeeGeneric:
  - id: "dimmer-generic"
    deviceLabel: "Zigbee Dimmer"
    zigbeeProfiles:
      - 0x0104
      - 0xC05E
    deviceIdentifiers:
      - 0x0101
      - 0x0104
    clusters:
      server:
        - 0x0006
        - 0x0008
      client:
        - 0x0019

zigbeeProfiles (optional): The Zigbee profile IDs that can match your driver. This is optional and can be left blank for most fingerprints. If unset, the default will match 0x0104 (HA) and 0xC05E (ZLL) devices.
deviceIdentifiers (optional): The device ID reported by the device. This is optional, and if unspecified any device ID will match. If specified, if the device has any of the included IDs it will be considered a match
clusters: Has 2 sub fields, at least one of which must be specified:
- clusters > server: Clusters that an endpoint of the Zigbee device must report as supporting as a server. All clusters listed in the fingerprint MUST be supported by the device.
- clusters > client: Clusters that an endpoint of the Zigbee device must report as supporting as a client. All clusters listed in the fingerprint MUST be supported by the device.

tip

In general, if there are multiple generic matches, the fingerprint with the most matching details will be preferred.

Z-Wave#

Manufacturer-Specific Fingerprints#

# fingerprints.yaml
zwaveManufacturer:
  - id: "GE/Switch/03"
    deviceLabel: GE Switch 03
    manufacturerId: 0x0063
    productType: 0x5250
    productId: 0x3130
    deviceProfileName: switch-binary

manufacturerId: This is the manufacturer ID value reported by the device in the manufacturer-specific report command
productType: This is the product ID value reported by the device in the manufacturer-specific report command
productId: This is the product type value reported by the device in the manufacturer-specific report command

The manufacturerId is required to be non-null, and one of productId or productType must be be non-null.

Generic Fingerprints#

zwaveGeneric:
  - id: "generic-switch"
    deviceLabel: Z-Wave Switch
    genericType: 0x10
    specificType:
      - 0x01
      - 0x03
    commandClasses:
      supported:
        - 0x25
      controlled:
        - 0x86
      either:
        - 0x2B
        - 0x40
    deviceProfileName: switch-binary

genericType: The one byte Generic Device Type reported by the Z-Wave device
specificType: The one byte Specific Device Type reported by the Z-Wave device
commandClasses (optional): Has 3 lists of command classes the device reports as supporting: those that are listed as controlled, those that are listed as supported, and clusters that can be either.

One of either the genericType or specificType must be non-null for the fingerprint to be valid.

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.

Install the `Hello World` Example Driver#

Ready to get started with SmartThings Edge? Install the Hello World example Edge Driver below to learn more about uploading an Edge Driver to your Hub and adding your Hub Connected Device to your Hub.

tip

Ensure you are using the latest release of the SmartThings CLI and have authenticated either with the appropriate scopes, or with a PAT Token.

Clone the repository below to your machine:

git clone git@github.com:SmartThingsDevelopers/SampleDrivers.git

Change directories into SampleDrivers:

cd SampleDrivers

Build the package and upload it to the SmartThings Cloud:

smartthings edge:drivers:package hello-world

Upon success you will see a response like this:

┌────────────────────┬──────────────────────────────────────┐
│ Driver Id          │ xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx │
│ Name               │ Hello World                          │
│ Package Key        │ helloworld.example                   │
│ Version            │ 2021-07-07T13:31:53.699513           │
└────────────────────┴──────────────────────────────────────┘

Create a Driver Channel to manage your personal drivers with the smartthings edge:channels:create command. Follow the on-screen prompts to finish setting up your channel. See Driver Channels for more info on channels.

smartthings edge:channels:create

? Channel name: personal-drivers
? Channel description: My custom drivers
? Channel terms of service URL: my-tos.com

┌──────────────────────┬──────────────────────────────────────┐
│ Channel Id           │ xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx │
│ Name                 │ personal-drivers                     │
│ Description          │ My custom drivers                    │
│ Type                 │ DRIVER                               │
│ Terms Of Service URL │ https://example.com/tos              │
│ Created Date         │ 2021-07-07T14:48:44.316949Z          │
│ Last Modified Date   │ 2021-07-07T14:48:44.316952Z          │
└──────────────────────┴──────────────────────────────────────┘

Assign your new driver to the channel you created:

smartthings edge:channels:assign <YOUR-DRIVER-ID> <YOUR-DRIVER-VERSION> -C <YOUR-CHANNEL-ID>

Enroll your Hub in your channel. This will make all drivers on the channel visible to your Hub:

tip

Find the device ID of your Hub with the CLI command smartthings devices --type=HUB

smartthings edge:channels:enroll -C <YOUR-CHANNEL-ID> <DEVICE-ID-OF-YOUR-HUB>

Select the newly created driver and install it to your Hub:

smartthings edge:drivers:install

Select the target Hub (in this case #1) and press Enter:

    ┌───┬──────────────────────────────────────┬─────────────────┬──────────┬──────┐
    │ # │ Device Id                            │ Name            │ Location │ Room │
    ├───┼──────────────────────────────────────┼─────────────────┼──────────┼──────┤
    │ 1 │ xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx │ SmartThings Hub │ Home     │      │
    └───┴──────────────────────────────────────┴─────────────────┴──────────┴──────┘
    ? Enter id or index

Select the channel you'd like to install a driver from and press Enter:

    ┌───┬──────────────────┬──────────────────────────────────────┐
    │ # │ Name             │ Channel Id                           │
    ├───┼──────────────────┼──────────────────────────────────────┤
    │ 1 │ personal-drivers │ xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx │
    └───┴──────────────────┴──────────────────────────────────────┘
    ? Select a channel to install the driver from.

Select the driver to install (in this case #1) and press Enter:

    ┌───┬──────────────────────┬──────────────────────────────────────┐
    │ # │ Name                 │ Driver Id                            │
    ├───┼──────────────────────┼──────────────────────────────────────┤
    │ 1 │ Hello World          │ xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx │
    └───┴──────────────────────┴──────────────────────────────────────┘
    ? Select a driver to install.

Add your device in the SmartThings app by navigating to Add a Device > Scan Nearby.

Structure#

note

Configuration File#

Fingerprints#

info

How is a fingerprint chosen?#

Shared Fields#

Matter#

Manufacturer-Specific Fingerprints#

Generic Fingerprints#

tip

Zigbee#

Manufacturer-Specific Fingerprints#

Generic Fingerprints#

tip

Z-Wave#

Manufacturer-Specific Fingerprints#

Generic Fingerprints#

Driver#

Profiles#

important

Install the Hello World Example Driver#

tip

tip

Install the `Hello World` Example Driver#