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
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.
The configuration file is a manifest and contains metadata for the driver.
- 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:
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
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.
- vendorId: Reported vendor of a matter device
- productId: Reported product ID for the device
- 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: Reported manufacturer of a device's endpoint
- model: Reported model of a device's endpoint
- 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
- 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.
- 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.
- 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.
Package updates that remove a profile name will be rejected. Devices already using the removed profile would not reflect newly created devices to clients.
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.
- Clone the repository below to your machine:
- Change directories into
- Build the package and upload it to the SmartThings Cloud:
Upon success you will see a response like this:
- Create a Driver Channel to manage your personal drivers with the
smartthings edge:channels:createcommand. Follow the on-screen prompts to finish setting up your channel. See Driver Channels for more info on channels.
- Assign your new driver to the channel you created:
- 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
- Select the newly created driver and install it to your Hub:
- Select the target Hub (in this case #1) and press Enter:
- Select the channel you'd like to install a driver from and press Enter:
- Select the driver to install (in this case #1) and press Enter:
- Add your device in the SmartThings app by navigating to Add a Device > Scan Nearby.