Integrate IoT Devices into the SmartThings Ecosystem


Learn how to create your own IoT device using SmartThings Device SDK.


The SmartThings Device SDK (STDK) is provided to ease the development of devices which operate with SmartThings Cloud and mobile application. The STDK is small enough to work on resource limited embedded devices.

In this Code Lab, you will learn how to create your own IoT device profile at SmartThings cloud and how to implement on your test device.

It is explained into three parts. The first explains how you can register and deploy to test your own IoT device profile in SmartThings using the Developer Workspace.

Then, it demonstrates how to create your own IoT device application with SmartThings Device SDK.

The last part shows how to onboard and control instances of your device with SmartThings mobile application.

The Switch example is covered in this Code Lab, but after learning it, you will also be able to do the Light example.

Set up your environment

You will need the following:

Sample Code

Here is a sample code for you to start coding in this Code Lab. Download it and start your learning experience!

SmartThings Device SDK Sample Code
(2.91 KB)

Alternatively, you may simply get it by git cloning or downloading a zip file from the GitHub link above.

Register and deploy to test your device

Using the Developer Workspace, create a device profile and customize the instructions for onboarding the device on the SmartThings mobile app, and deploy devices to be tested. These configurations can be edited up until the point you submit the device for publication in the production of the SmartThings ecosystem.

Sign in to SmartThings Developers

You need to sign in to SmartThings Developer Workspace using your Samsung account.

Create new project

You need to create an integration project for a direct-connected device. Create a new device project for device integration. Select Device Integration, then Direct-connected. Afterwards, name your project as Switch Example.

Add a device profile

Define your device’s functionalities with SmartThings capability. First, navigate and select Define Device Profile and then, Add A Device Profile. Fill the required fields with respective values. Afterwards, select a capability for your device.

You can get more information about the capabilities available here.

Add device onboarding

The device onboarding guides device owners when their device is first registering and connecting to SmartThings. You can customize the screens presented by adding a device onboarding profile. The ownership validation type is also defined at this stage.

You may customize the screens displayed when the device onboard via the SmartThings mobile app, or just use the default values.

Add a product info

The product info defines how this device is shown at SmartThings mobile app catalog. You can define device’s category and its regional availability.

Deploy your device to test

You can start testing by deploying your device to test. There are two ways to do this:

Via Overview menu

Via Test > Test Devices

You will be able to see your device in the SmartThings mobile app when in Developer Mode only after it has been deployed for testing.

Register test devices

You can add the identity of device for authenticating it to the SmartThings cloud. This requires device information like serial number and device public key (ED25519). Since the maximum number of test device is limited per user, once you’ve reached it, you should remove the existing one.

This example shows how to create ED25519 key pair with SDK tools. You can get device_info.json file as a result from tools/keygen/linux/output_{ serialNumber}.

Linux version of key generator (keygen) utility is located at st-iot-device-sdk-c-reference/iot-core/tools/keygen/linux or st-device-sdk-c/tools/keygen/.

Serial number for testing device would be randomly generated by this tool which has STDK + 12-digit alphanumeric format:

$ cd ~/Workspace/st-device-sdk-c-ref/iot-core/tools/keygen/
$ python3 --firmware switch_example_001
Use following serial number and public key
for the identity of your device in Developer Workspace.

Serial Number:

Public Key:

Copy STDK\*\*E90W\*\*\*uCX from keygen output and paste it into Serial Number field of Register A Test Device page.
Copy public key string from keygen output (nFN5x\*\*\*uQusQ\*\*\*\*ZHoBSFaAoP9\*\*\*kNdLnjDJRew= in this example) and paste it into Public Key field.

Generate device QR code

Using the device QR code could be helpful while device onboarding. QR code should have format like below. Refer here for more details.

{Your mnId}: 4-digit alphanumeric mnId of your account

{Device onboardingId}: 3-digit number Onboarding ID, you can find it from your developer workspace project Device Onboarding > Other Info page

{Device serialNumber}: device serial number which is registered at your developer workspace project

You can simply generate QR code with using below Python script:

import qrcode

mnid = 'FFFF' # "FFFF" is an example. you should replace it with yours
onboardingId = '111' # "111" is an example. you should replace it with yours
serialNumber = 'STDKtest0001' # "STDKtest0001" is an exmaple. you should replace it with yours
qrUrl = '' + mnid + '&s=' + onboardingId + '&r=' + serialNumber
qrcode.QRCode(box_size=10, border=4)
img = qrcode.make(qrUrl) + '.png')

Write device application

Open and edit sample device app

Currently, you are doing the Switch example, but afterwards you may also try out the Light example. These sample applications are located at apps/esp8266/directory of the GitHub links that are mentioned when you set up your environment.

  • Download onboarding_profile.json from the Overview of your device in Developer Workspace.

  • Copy onboarding_profile.json file into your application directory (apps/esp8266/st_switch/main):

    $ cd ~/Workspace/st-device-sdk-c-ref/apps/esp8266/switch_example/main/
    $ cp ~/Downloads/onboarding_config.json 
  • Copy device_info.json from tools/keygen/linux/output_{serialNumber} which contains your device specific information to application directory, apps/esp8266/switch_example/main:

    $ cd ~/Workspace/st-device-sdk-c-ref/iot-core/tools/keygen/
    $ cp output_{serialNumber}/device_info.json ~/Workspace/st-device-sdk-c-ref/apps/esp8266/switch_example/main/

    firmwareVersion: version string

    privateKey: base64 encoded ED25519 private key. This value should be paired with what you registered to Developer Workspace.

    publicKey: base64 encoded ED25519 public key. This value should be same with what you registered to Developer Workspace.

    serialNumber: This value should be same with what you registered to Developer Workspace

        "deviceInfo": {
            "firmwareVersion": "switch_example_001",
            "privateKey": "dH**JKMRD5X****BaV+fGoXa3qZfNW3V****jHXOmd0=",
            "publicKey": "nFN5x***uQusQ****ZHoBSFaAoP9***kNdLnjDJRew=",
            "serialNumber": "STDK**E90W***uCX"
  • Open sample application source code

    • Browse apps/esp8266/switch_example/main/ directory or download the sample code of this Code Lab

    • Open main.c file.

  • Write your device application code

    • Write the main function using SmartThings Device SDK APIs:

      void app_main(void)
            SmartThings Device SDK(STDK) aims to make it easier to develop IoT devices by providing
            additional st_iot_core layer to the existing chip vendor SW Architecture.
            That is, you can simply develop a basic application
            by just calling the APIs provided by st_iot_core layer like below.
            // create a iot context
            1. st_conn_init();
            // create a handle to process capability
            2. st_cap_handle_init(); (called in function 'capability_init')
            // register a callback function to process capability command when it comes from the SmartThings Server.
            3. st_cap_cmd_set_cb(); (called in function 'capability_init')
            // process on-boarding procedure. There is nothing more to do on the app side than call the API.
            4. st_conn_start(); (called in function 'connection_start')
          unsigned char *onboarding_config = (unsigned char *) onboarding_config_start;
          unsigned int onboarding_config_len = onboarding_config_end - onboarding_config_start;
          unsigned char *device_info = (unsigned char *) device_info_start;
          unsigned int device_info_len = device_info_end - device_info_start;
          int iot_err;
          // create a iot context
          ctx = st_conn_init(onboarding_config, onboarding_config_len, device_info, device_info_len);
          if (ctx != NULL) {
              iot_err = st_conn_set_noti_cb(ctx, iot_noti_cb, NULL);
              if (iot_err)
                  printf("fail to set notification callback function\n");
          } else {
              printf("fail to create the iot_context\n");
          // create a handle to process capability and initialize capability info
          xTaskCreate(app_main_task, "app_main_task", 4096, NULL, 10, NULL);
          // connect to server
    • Write your command callback function for each capability. It should contain your device control upon each command (e.g., LED on/off control). Capability example for each capability would be helpful to handle attribute, command for each capability. You can find capability example at apps/esp8266/capability_example/main:

      void cap_switch_cmd_cb(struct caps_switch_data *caps_data)
          int switch_state = get_switch_state();
      static void capability_init()
          cap_switch_data = caps_switch_initialize(ctx, "main", NULL, NULL);
          if (cap_switch_data) {
          const char *switch_init_value = caps_helper_switch.attr_switch.value_on;
              cap_switch_data->cmd_on_usr_cb = cap_switch_cmd_cb;
              cap_switch_data->cmd_off_usr_cb = cap_switch_cmd_cb;
              cap_switch_data->set_switch_value(cap_switch_data, switch_init_value);

Build, flash, and monitor

You can build, flash, and monitor in the console with the following instructions:

$ cd ~/Workspace/st-device-sdk-c-ref
$ python apps/esp8266/switch_example
$ python apps/esp8266/switch_example flash
$ python apps/esp8266/switch_example monitor
$ cd ~/Workspace/st-device-sdk-c-ref
$ python apps/esp8266/switch_example flash monitor

Onboard and control the device via SmartThings app


a. Enable developer mode

Developer mode should be enabled on SmartThings mobile application.

Launch the SmartThings app, go to Dashboard > Settings. Long-press About SmartThings for 20 seconds. Enable the Developer mode, then restart the SmartThings app.

You can find out more information here.

b. Add STDK device

Go to Add device and click My Testing Devices or Scan QR code. You can now see and add your self-published STDK devices.

Control by SmartThings application

a. Device control from dashboard

You can turn your STDK device on/off by clicking the button on dashboard.

b. Device control from plugin

You can control various attributes and get more detailed information from the plugin user interface.

You're done!

Congratulations! You have successfully achieved the goal of this Code Lab. Now, you can control your IoT devices using the SmartThings app all by yourself! If you're having trouble, you may download this file:

SmartThings Device SDK Complete Code
(2.89 KB)