Device onboarding for direct-connected devices

Device onboarding is the process of pairing a direct-connected device with the SmartThings app and integrating the device with SmartThings Cloud. The SmartThings app guides the user through each step of device onboarding with images and text that you can customize.

Device onboarding consists of three steps:

  1. A new device is found by the SmartThings app.
  2. The device attempts to connect with the SmartThings app.
  3. The device is successfully paired to the SmartThings app.

Use Developer Workspace to enter information for device onboarding. This article explains how to add device onboarding information for a device and how to customize the images and text.

How to add device onboarding information

You can add device onboarding information in the following cases:

  • When integrating a direct-connected device:
  1. In Developer Workspace, go to Develop > DEVICES > DEVICE INTEGRATION and click + NEW.
  2. Select Connect your device directly with SmartThings Cloud.
  3. Add the device onboarding information when setting the device information.
  • When requesting publication for a direct-connected device:
  1. In Developer Workspace, go to Publish and click + NEW.
  2. Select your self-published direct-connected device.
  3. Add the device onboarding information when setting the device information.

In this example, we have set up a direct-connected device. Below are the steps for integrating the device with SmartThings Cloud:

  1. Add device onboarding information when integrating a new direct-connected device.
  2. Self-publish the device.
  3. Test device onboarding for the device.

Step 1. Add device onboarding information

  1. When setting the device information, select New device onboarding. Step 1-0
  2. Enter a unique three-digit number as your device onboarding ID and device onboarding name.
  3. Select your device identity type.
  4. If you want to use the default images and text we provide, click SAVE. If you want to customize them, move to the next step.
  5. Click View details to view detail information for device onboarding. Step 1-1
  6. Click Add in the Supported languages field. Step 1-2
  7. Developer workspace provide you with default images and texts. You can customize the images and text for device onboarding by clicking Edit contents. You will see the form below. Step 1-3
  • Upload the images (.png only, W1550 x H936) for each step. See our style guidelines on device onboarding images. Also recall the three steps of device onboarding.
  • Select a language in the combo box to enter device onboarding information for that language
  • Enter a Display name to represent this device onboarding flow in the SmartThings app
  • Fill out text for each device onboarding step
  1. Click SAVE.

Step 2. Self-publish the device

After entering the device onboarding information, click SAVE and then SELF-PUBLISH to self-publish your device. The device information is sent to SmartThings Cloud.

Step 3. Test device onboarding for the device

Launch the SmartThings app and enable Developer Mode in the SmartThings app. Then add your device.

Device onboarding will now begin: Step 3

In the above image, steps 1, 2 and 3 are the device onboarding screens that you created earlier. When device pairing is completed, your device will be added to the SmartThings app and will appear on your device list. Now you can control your device using the SmartThings app.

Device onboarding error codes

The SmartThings app will display an error popup if there are problems with device pairing. Click REPORT to check the error code. Possible error codes are listed below.

  • MC: Mediator to cloud
  • ME: Mediator to Enrollee
  • EC: Enrollee to Cloud
Prefix Code Description
MC 01 Cloud sign-in timeout (beginning of setup)
02 Cloud sign-in DNS lookup failure
03 Get auth code timeout
04 Get access token timeout
05 Home AP connection failure
13 Home AP connection failure - association rejection
14 Home AP connection failure - authentication failure
15 Home AP connection failure - DHCP failure
16 Cloud signin timeout (after homeAP)
17 Network error (no-internet)
ME 01 SoftAP connection failure
02 Disconnected
03 Wrong password
04 Wifi disabled
05 Provisioning info discovery failure
06 Fail to get provisioning info detail info
07 Onboarding resource discovery failure
08 Fail to get onboarding resource detail info
09 Fail to create remote enrollee
10 OTM fail - wrong pin
11 OTM fail - confirm deny
12 OTM fail - resource discovery failure
13 Reset request resource
14 Reset response resource
17 Fail to get device configuration
35 Fail to device provisioning
36 Fail to cloud provisioning
40 Fail to send OTM support feature
41 Fail to send confirm code
42 Fail to local discovery 
43 Fail to post credential 
45 Router invalid state
47 OTM fail - etc error
48 OTM fail - mobile timeout
49 OTM fail - wrong cert
50 SoftAP connection fail - association rejection
51 SoftAP connection fail - authentication failure
52 SoftAP connection fail - DHCP failure
65 OTM fail - not matched provisioning info
EC 01 HomeAP connection failure
02 Cloud sign-up failure
03 Cloud sign-in failure
06 Not found device on cloud

Device image style guideline


The SmartThings app provides images and text that guide users through each device onboarding step. Depending on the device type, you may need to create custom images. Aim to depict the minimum characteristics in the simplest fashion so that the user can focus on the setup process.

Image types

1. Focused Device Image (1440x936 / Unit: pt)

2. Preparing/Confirm Image (1440x936 / Unit: pt)

Device Button Pairing (e.g., Sound bar)

Preparing/Confirm Image

Remote Control Button Pairing (e.g., RVC)

Guide area

The Guide area consists of the following layers and is created in 1440x936.

Basic style

Use the color #ffffff for the widest area of your guide image, and use the color #e8e7e7 to create a shadow to match the characteristics of a product. Typically, lines are used to express the details of a product. When you need a Point area (i.e., a finger pointing at something), use the color #757575.

Focused Device Image Focused Device Image Focused Device Image

Image Location Value
Main Device A: Device's shadow #e8e7e7
Main Device B: Main device color #ffffff
Main Device C: Device's internals line #757575, 1.5 point
Main Device D: Device's externals line #757575, 5 point
Main Device E: Details color #e7f5fd
Hand F: Internal color #ffffff
Hand G: External line #757575, 5 point
Remote Control H: Internal color #ffffff
Remote Control I: External line #757575, 5 point
Remote Control J: Internal line #757575, 1.5 point

Apply different thicknesses to the external line of the overall shape and the detailed internal lines to help users easily perceive the device

Omit detailed descriptions irrelevant to the Setup process and provide a minimum number of characteristics of the device.


When displaying your product, use one consistent view as much as possible to prevent users from perceiving the images as different devices.

If it is difficult to use a single view due to the characteristics of the product, you may use more than one view in the top-front-facing orientation.


If you need to display two devices in the Guide area at the same time, design the one that the user needs to control to be bigger.

For a large product, if it is difficult to fit the whole product on one screen, clearly display the part that needs to be controlled.

Touch point

Emphasize the part the user needs to control using a hand image or touch symbol.

When you use a hand, make sure that it is placed at the following angles only.

When you use a hand, make sure that it is placed at the following angles only.

Touch point

Bubble icon

Use a Bubble icon when you need to display additional information. Make sure that the start point of the bubble points to the direction of the relevant information. Use an easy-to-understand icon inside the bubble for users. Do not use text inside the bubble.