Develop Your Device App

A Device app is deployed on your Device's firmware. It defines the behavior of your Device and dictates your Device's action when the SmartThings platform interacts with it. For example, a Device app determines how your switch physically behaves when it is send an on command.

Create a new Device project

We recommend getting started by branching off of one of the example projects provided in the References Git repository. In this example, we will use the switch_example application from the References repo. The full path of ESP8266 is displayed below:

~/st-device-sdk-c-ref/apps/esp8266/switch_example/

Update Device Information

Your device needs two files to connect to the SmartThings platform:

• Device Identity (device_info.json)
• Device Onboarding (onboarding_config.json)

Device Identity File

All devices must be provisioned in advance with the SmartThings cloud. The device's identity and authentication data are needed before the device can connect.

Note: the device serial number has a specific format for non-WWST certified devices. This serial number is generated in the Developer Workspace in the last steps when registering your device.

For individual contributors

When testing your device, provide the following information in the device_info.json file in the main directory of your device application:

{
  "deviceInfo": {
    "firmwareVersion": "<FW20190919>",
    "privateKey": "<privateKey_here>",
    "publicKey": "<publicKey_here>",
    "serialNumber": "<serialNumber_here>"
  }
}

Note: The serial number for devices used during testing (prior to WWST certification) is created by the Developer Workspace.

For manufacturers

It is expected that commercially-ready devices will store the device identity information of each device in a secure location during the manufacturing process for the production level device app. For example, device identity data will be flashed into the SmartThings non-volatile memory location.

For ED25519

Flashed item	Type	Description	Examples
PKType	data	Public key algorithm type	ED25519
CACert	file	Server CA Certificate	root_crt.pem
SubCert	file	Client (=Device) Certificate, only for X.509	device.pubkey.b64
PrivateKey	file	Client (=Device) Private key	device.seckey.b64
SerialNum	data	Device Serial Number	cc50e309dcd0

Device onboarding file

The onboarding_config.json file was created in the Developer Workspace during the Device registration process. Download the file from the Developer Workspace project page and copy it to the root directory of the Device app.

The location for ESP8266 is displayed below:

~/st-device-sdk-c-ref/apps/esp8266/switch_example/main/

You can see an example onboarding_config.json file below:

{
  "onboardingConfig": {
    "deviceOnboardingId": "NAME",
    "mnId": "MNID",
    "setupId": "999",
    "vid": "VID",
    "deviceTypeId": "TYPE",
    "ownershipValidationTypes": [
      "JUSTWORKS",
      "BUTTON",
      "PIN",
      "QR"
    ],
    "identityType": "ED25519",
    "deviceIntegrationProfileKey": {
      "id": "DIP_UUID",
      "majorVersion": 0,
      "minorVersion": 1
    }
  }
}

Here's a breakdown of the data contained in onboarding_config.json:

• deviceOnboardingId - the prefix used in the SSID of Soft-AP during the Easy-setup process. The value is defined in the final stages of device registration. This value is tightly coupled with the device identity provisioned in the Developer Workspace. If deviceOnboardingId is changed, all previously provisioned device identities will not be able to authenticate; the device identities will need to be submitted again.
• mnId - manufacturer ID. A unique four-letter ID assigned by SmartThings to developers to uniquely identify accounts. Organizations have their own mnId, which is shared with its members. You can find your mnId in the Developer Workspace under My Page -> MNID.
• setupId - a unique three-digit number. This value comes from the Device onboarding ID when you performed the Create a device onboarding profile step in the Developer Workspace.
• vid - an alphanumeric vendor identifier that you give to your device. This vendor identifier is created when you Create a device profile in the Developer Workspace.
• deviceTypeId - determines the device icon and default UI layout in the SmartThings app. This value is selected when creating your device profile.
• ownershipValidationTypes - This is the method your device will apply to validate ownership when onboarding to SmartThings. There are four supported types:
  • JUSTWORKS - no owner intervention needed
  • BUTTON - owner will press a button
  • PIN - owner enters a 4 digit code
  • QR - owner scans the device's QR code
• identityType - a unique certificate or public key pair used for authentication when connecting to the SmartThings Cloud. At this time only ED25519 is supported.

Develop Your Device Application

A device application is developed using the APIs provided by the IoT Core Device Library. We recommend that you start by using the supplied sample applications in Git (e.g. switch_example). This allows for rapid development as you begin to develop your new Device. Please refer to the API references related to the IoT Core Device Library as shown below:

Connection Management

• st_conn_init()
• st_conn_set_noti_cb()
• st_conn_start()
• st_conn_cleanup()
• st_conn_ownership_confirm()

Capability Management

st_cap_handle_init() st_cap_cmd_set_cb() st_cap_create_attr() ST_CAP_CREATE_ATTR_NUMBER ST_CAP_SEND_ATTR_NUMBER ST_CAP_CREATE_ATTR_STRING ST_CAP_SEND_ATTR_STRING ST_CAP_CREATE_ATTR_STRINGS_ARRAY ST_CAP_SEND_ATTR_STRINGS_ARRAY st_cap_free_attr() st_cap_send_attr()

Main function example for ESP8266

void app_main(void)
{
    /**
      SmartThings Device SDK 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();
}

Build and Flash the Device App

Navigate to the root directory of the References repo and execute the build script build.sh with the parameters below:

# Example for ESP8266
$ cd ~/st-device-sdk-c-ref/
$ python build.py apps/esp8266/switch_example  # python build.py {app_directory}

After compilation, you'll see a result similar to this:

# Example for ESP8266
$ cd ~/st-device-sdk-c-ref/
$ tree output/ -L 3
output/
`-- esp8266
    ├── iotcore_switch_example_20200729_65a1678_0a8cbe1
    │   ├── address_info.txt
    │   ├── bootloader.bin
    │   ├── debug
    │   ├── ota_data_initial.bin
    │   ├── partitions.2MB.bin
    │   └── switch_example.bin

For Espressif chipsets (in this case ESP8266), You can now execute the following command to flash the entire project (app, bootloader, and init data bin) to the chipset:

# Example for ESP8266
# python build.py {app_directory} {option}
$ cd ~/st-device-sdk-c-ref/
$ python build.py apps/esp8266/switch_example flash

tip

You do not need to run python build.py apps/esp8266/switch_example before running python build.py apps/esp8266/switch_example flash; this will automatically rebuild everything that needs to be built before flashing.

For serial port flashing, the serial port must be matched to your local machine's environment. For example, in ESP8266, the settings for serial port flashing can be configured with menuconfig. If the serial port setting does not match your environment, please execute the following:

note

The menuconfig option is only supported on Espressif chipsets.

# Example for ESP8266
# python build.py {app_directory} {option}
$ cd ~/st-device-sdk-c-ref
$ python build.py apps/esp8266/switch_example menuconfig

Test Your Device

Visit the Test Your Device page to learn more about testing your Device.