Development

Step 1: Register and deploy to test your device

Using the Developer Workspace create a device profile, 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.

1. Sign up & sign in to SmartThings Developers

You need to sign in to the Developer Workspace with your Samsung account. Go to https://smartthings.developer.samsung.com/

2. 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.

3. 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.


4. Add a 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.


5. 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.

6. Deploy your device to test

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

a. Via Overview menu

b. 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.

7. 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 stdk-keygen.py --firmware switch_example_001
Use following serial number and public key
for the identity of your device in Developer Workspace.

Serial Number:
STDK**E90W***uCX

Public Key:
nFN5x***uQusQ****ZHoBSFaAoP9***kNdLnjDJRew=

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.

8. 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 python3 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 = 'https://qr.samsungiots.com/?m=' + mnid + '&s=' + onboardingId + '&r=' + serialNumber
qrcode.QRCode(box_size=10, border=4)
img = qrcode.make(qrUrl)
img.save(serialNumber + '.png')

Step 2: Write device application

1. Open and edit sample device app

Currently, we 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 in Setup page.

  • 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 file from the Setup page 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
          capability_init();
      
          gpio_init();
          register_iot_cli_cmd();
          uart_cli_main();
          xTaskCreate(app_main_task, "app_main_task", 4096, NULL, 10, NULL);
      
          // connect to server
          connection_start();
      }
      
      
    • 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();
          change_switch_state(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);
          }
      }
      

2. 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 build.py apps/esp8266/switch_example
$ python build.py apps/esp8266/switch_example flash
$ python build.py apps/esp8266/switch_example monitor
Or
$ cd ~/Workspace/st-device-sdk-c-ref
$ python build.py apps/esp8266/switch_example flash monitor

Step 3: Onboard and control the device via SmartThings app

1. Onboarding

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.

2. Control by SmartThings application

a. Device control from dashboard

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

b. Device control from plugin

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

You're done!

Congratulations! You have successfully achieved the goal of this Code Lab activity. Now, you can control your IoT devices using the SmartThings App all by yourself! But, if you're having trouble, you may check out the link below.

SmartThings Device SDK Complete Code2.89 KB