Skip to main content

Driver Channels

Driver Channels are used to group SmartThings Edge Device Drivers and share access to them with other users. The drivers contained within the driver channel are locked to a specific version, allowing you to make changes to your drivers without affecting other users of your drivers.

This topic will help you create a Driver Channel, add a driver to your channel, share your channel, and install a driver from your channel onto a Hub. The CLI commands presented here are intended for Driver Channel owners. For info on enrolling and installing drivers from channels you have been invited to, see Enroll in a Shared Channel and Install Drivers.

Prerequisites#

Before getting started, make sure you have the following up and running:

  • The SmartThings CLI
  • The Edge CLI plugin
important

If you are using a Personal Access Token with the CLI, ensure the token's scope includes r:channgels:* and w:channels:*.

Create a Driver Channel#

Create a new channel using the SmartThings CLI with the following command:

smartthings edge:channels:create -i <my_channel>.json

Below is an example JSON file generated from the above command:

{
"name": "My Channel Name",
"description": "my channel description",
"termsOfServiceUrl": "https://example.com",
"type": "DRIVER"
}
tip

The termsOfServiceUrl is a link to any terms of service you would like your users to accept before they gain access to your channel and its drivers.

Enroll Your Hub in Your Channel#

Use the following CLI command to enroll your Hub in a Driver Channel you have created:

smartthings edge:channels:enroll [<hubID>]
  • If <hubID> is omitted, you will be presented with a list of Hubs to choose from.
  • The --channel or -C flag can be used to specify the desired channel. If no channel is specified, you will be presented a list of available channels to choose from.

Publish Your Edge Device Drivers to Your Channel#

Assign a particular SmartThings Edge Device Driver and version to a channel you own with the following SmartThings CLI command:

smartthings edge:channels:assign [<driverID>] [<version>]
  • If driverID is not specified, you will be presented a list of available drivers to choose from.
  • If <version> is not specified, the latest published version of the driver will be used.
  • The --channel or -C flag can be used to specify the desired channel. If no channel is specified, you will be presented a list of available channels to choose from.

Install a Driver From Your Channel Onto Your Hub#

tip

The driver version installed on your Hub when using Driver Channels will remain the same, even if you publish a new driver version.

Install a driver from a Driver Channel you own onto your Hub with the following SmartThings CLI command:

smartthings edge:drivers:install

  • The --hub or -H flag can be used to specify the Hub ID. If the Hub ID is not specified, you will be presented with a list to choose from.
  • The --channel or -C flag can be used to specify the desired channel. If no channel is specified, you will be asked if you want to install from a Driver Channel.

After specifying a channel and Hub, you will be presented with a list of available drivers to install from the specified channel. Select a driver to install it to your Hub.

Create an Invitation to Your Channel#

Use the following CLI command to create a new invitation to your channel:

smartthings edge:channels:invites:create

After running the above command, you will be asked a series of questions. The options you choose while creating your invite will determine what users will be able to accept your invite.

A resulting JSON file will be built for you specifying your channel share options. A URL for users to navigate to and accept your channel invitation will also be generated for you.

tip

If you have an existing JSON or YAML file specifying your sharing options, use the --input or -i CLI option to use a pre-existing file.

Search for Created Channel Invites#

Use the following CLI command to search for channel invites:

smartthings edge:channels:invites

A list of your currently created invites and their sharing URLs will be returned.

Sharing a Driver Channel Invitation#

Once a Driver Channel is created, you can share it with other users. Sharing a Driver Channel with other users allows them to install any SmartThings Edge Device Drivers available on the channel.

Access to Driver Channels is controlled using an invitation. An invitation is a URL that can be sent to users, inviting them to your channel and allowing them to install any drivers in the channel onto their Hub.

To share a channel invitation with a user, provide the user with the URL generated when you created the channel invitation.