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


├── 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)

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.


# config.yaml
name: 'Hello World'
packageKey: 'helloworld.example'
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: {}
discovery: {}


zigbee: {}


zwave: {}


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


Manufacturer-Specific Fingerprints#

# fingerprints.yaml
- 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
- id: generic-temperature-and-humidity
deviceLabel: "Temperature and Humdity Sensor"
- 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.

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


Manufacturer-Specific Fingerprints#

# fingerprints.yaml
- 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
- id: "dimmer-generic"
deviceLabel: "Zigbee Dimmer"
- 0x0104
- 0xC05E
- 0x0101
- 0x0104
- 0x0006
- 0x0008
- 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.

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


Manufacturer-Specific Fingerprints#

# fingerprints.yaml
- 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#

- id: "generic-switch"
deviceLabel: Z-Wave Switch
genericType: 0x10
- 0x01
- 0x03
- 0x25
- 0x86
- 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.


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.


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
- id: main
- id: switch
version: 1
- name: Light

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.


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
  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:
│ Channel Id │ xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx │
│ Name │ personal-drivers │
│ Description │ My custom drivers │
│ Type │ DRIVER │
│ Terms Of Service URL │ │
│ 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:

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.