Skip to main content

(Legacy) Device Type Handlers

important

Device Type Handler integrations are now deprecated. SmartThings Edge is the latest method for connecting your Hub Connected Device to the SmartThings Platform. The content below is for reference only.

Prerequisites#

Before starting development, you will need:

  • Your Zigbee, Z-Wave, or LAN Device.
  • A SmartThings-compatible Hub.
  • A Samsung account.
  • Before publishing your Device, you must be enrolled as an organization member in the Developer Workspace.
  • A local fork of the SmartThingsPublic GitHub repo.

Supported Regions#

  • NA
  • EU
  • AP

Log in to the Developer Workspace and IDE#

Begin development by logging in to the Developer Workspace and creating a Hub Connected Device integration.

important

You must be enrolled in an organization to create a Hub Connected Device. Be sure that you have switched from Private Workspace to your organization's workspace (see the pulldown in the upper-right corner of the Developer Workspace banner).

Open the Groovy IDE and log in with the same credentials. You must log in to the Groovy IDE and Developer Workspace using the same Samsung account credentials. If you already have two separate accounts, you can request to join your current organization with your graph.api.smartthings.com credentials.

Set Up Your GitHub Integration#

  1. Link your GitHub account with the IDE. In the IDE, navigate to My Device Handlers and click Enable GitHub Integration to authorize the application.
  2. Fork the SmartThingsPublic GitHub repository. You can commit changes made in the IDE to this repository and update the IDE with changes merged into this repository from other sources.

Create a Device Handler in the IDE#

A Device Handler is a representation of a physical device in the SmartThings platform. It is responsible for communicating between the actual device and the SmartThings Platform.

info

We recommend using an existing Device Handler whenever possible. This will allow you to add or remove a fingerprint for your Device.

To search for and use an existing Device Handler:

  1. Under My Device Handlers in the IDE, click Create a New Device Handler.
  2. In the From Template tab, select the protocol and capabilities that correspond to your device.
    • If there is no Device Handler match (i.e. you are creating a New Device Handler Form), we recommend creating a Device Handler from an existing example (described below).
    • If there is a Device Handler match, the corresponding Device Handler is shown. Enter the required fields to create a unique fingerprint for your device. Required fields may include: Manufacturer Name/ID, Product ID, Model Name/ID, Device Join Name, Namespace, Device Handler Name.
  3. Click Update Existing Device Handler or Create. This will display the template code.
  4. Click Save, then click Publish > For Me to publish this Device Handler to your account.

In addition to the method described above, there are two additional ways to create a Device Handler in the IDE:

  • From Code: Copy the Groovy code from an existing Device Handler in the SmartThingsPublic repo and paste it in the empty field in the IDE.
  • From an Existing Example: Select an existing Device Handler from this tab in the IDE. We recommend this method when creating a New Device Handler Form.

Test Your Device Integration#

Visit Test Your Device for information on testing your Device Integration.

Once you have completed testing, send an invitation to the user st-hubreview@smartthings.com to join your Location. This allows the SmartThings team to test and approve your Device for publication.

Add a product in Developer Workspace#

Return to the Developer Workspace. In the Develop menu, click Add Product Info to register the products that are supported by your Device Handler:

  • Add a Product Name.
  • Select an appropriate Category for the product.
  • Select the connection Protocol this product uses.
  • Pairing Instructions help the user pair the device with the SmartThings app.
    • You can select existing pairing instructions for the product, or create new pairing instructions.
      • Your pairing instructions should be as generic as possible, so that they can be re-used with other devices belonging to the same family.
      • The pairing instructions should be named in the format <Brand Name> <ZigBee /Z Wave> <Unique Family Name> (e.g. Samsung ZigBee EnergyMaster).
  • Country is a list of the countries in which your published device is visible.
  • Product Number / SKU is used to differentiate models of the same product.

Submit Your Request to Publish#

After registering your products in the Developer Workspace and completing testing, you are ready to submit your request to publish your Devices. Publishing will make your products available to all SmartThings users in the regions you specify in your request to publish.