Skip to main content

Driver Components and Structure

Driver Components​

A SmartThings Edge Device Driver consists of up to five main components:

  • A configuration file
  • The driver code itself
  • Device profiles for the supported devices
  • Fingerprint (applicable only for Matter, Zigbee, and Z-Wave devices)
  • Search Parameters (optional, applicable to LAN devices only)

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)
└── search-parameters.yaml (optional, applicable to LAN devices only)
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'
description: 'Hello World example configuration file'
vendorSupportInformation: 'YourBrandName'
permissions:
  lan: {}
  discovery: {}
  • name: Name of driver
  • packageKey: Unique identifier of the package
  • description: A description of the configuration file
  • vendorSupportInformation: The vendor supporting the driver
  • 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.

Search Parameters​

The search-parameter.yaml file is an optional file that can be used to control when a LAN driver runs discovery. The hub software will first pre-scan the local network for devices that respond to mdns/ssdp queries with information that matches what is in the search-parameter.yaml file. This allows the system to more intelligently chose when it will start a driver to perform discovery and save system resources.

In cases where the driver is already running and contains populated search-parameters, the pre-scan will determine whether the driver receives the "discovery start" event.

File format​

The file format contains two fields: mdns and ssdp. These fields correspond to the associated network discovery protocol. Each field contains a list of service (for mdns) or searchTerm (for ssdp) entries. Device-to-driver matches are permissive; any match across either protocol will result in the driver receiving a discovery event.

This example file will cause a driver to run discovery if any device is found on the local network that matches either of the mdns services or the two ssdp terms:

mdns:
  - service: _foo._tcp
  - service: _bar._tcp
ssdp:
  - searchTerm: urn:schemas-upnp-org:device:Foo:1
  - searchTerm: urn:schemas-upnp-org:device:Bar:1

Guidelines for usage​

The search-parameters.yml file should only be added to the driver package if the driver in question uses a supported protocol (mdns, ssdp) to search the local network for supported devices. This functionality is completely optional for drivers that do utilize a supported protocol. Issues with discovering local devices may be harder to debug with this functionality enabled (i.e. search-parameters.yml is populated) as the pre-scan may block a driver from ever running and logging any debug information.

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.

  1. Clone the repository below to your machine:
git clone git@github.com:SmartThingsDevelopers/SampleDrivers.git
  1. Change directories into SampleDrivers:
cd SampleDrivers
  1. 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 │ └────────────────────┴──────────────────────────────────────┘

  1. 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          │
└──────────────────────┴──────────────────────────────────────┘
  1. Assign your new driver to the channel you created:
smartthings edge:channels:assign <YOUR-DRIVER-ID> <YOUR-DRIVER-VERSION> -C <YOUR-CHANNEL-ID>
  1. 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>
  1. Select the newly created driver and install it to your Hub:
smartthings edge:drivers:install
  1. 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
  1. 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.
  1. 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.
  1. Add your device in the SmartThings app by navigating to Add a Device > Scan Nearby.