Develop a device app

You have the environment set up and you have registered a device, so now it is time to create a new device project.

Step 1: Create a new device project

An easy way to get started is to branch off of one of the example projects provided in the git repository. We will use the "st_switch" application from the STDK directory here.

Full path of the ESP8266
~/st-device-sdk-c-ref/apps/esp8266/st_switch/

Step 2: Update the device information

Your IoT device needs two files of information to connect to the SmartThings Cloud Server:

  • Device Identity
  • Device Onboarding

Device Identity

All devices must be provisioned in advance with SmartThings cloud. The device's identity along with authentication data is needed before it can connect. Note that the device serial number has a pecific format for non WWST certified devices. This serial number is generated in the Developer Workspace in the last steps as you registered your device.

As an Individual

When testing your device provide the following information in the device_info.json file in the main directory of the device application.
Note: The serial number for devices used during testing (previous to WWST certification) is manufactured by Developer Workspace.

Example of device_info.json
{
  "deviceInfo": {
    "firmwareVersion": "FW20190919",
    "privateKey": "privateKey_here",
    "publicKey": "publicKey_here",
    "serialNumber": "serialNumber_here"
  }
}

As a Manufacturer

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 Configuration JSON

The onboarding_config.json was created in the Developer Workspace during the device registration steps. Download the file and copy to the root directory of the device app.

Example

Location for ESP8266
~/st-device-sdk-c-ref/apps/esp8266/st_switch/main/
{
  "onboardingConfig": {
    "deviceOnboardingId": "STDK-MyIoTSwitch",
    "mnId": "fIJ3",
    "setupId": "001",
    "vid": "STDK_SWITCH_0001",
    "deviceTypeId": "Switch",
    "ownershipValidationTypes": [ "JUSTWORKS" ], 
    "identityType": "ED25519"
  }
}
  • deviceOnboardingId - is 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 Developer Workspace. If deviceOnboardingId is changed, all previously provisioned device identities will not be able to authenticate. The device identities must 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 Developer Workspace.
  • vid - an alphanumeric identifier that you give your device. This vendor identifier is assigned when you 'Create a device profile' in 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 SmartThings Cloud Server. At this time only ED25519 is supported.

Step 3: Develop device application

A device application is developed using the APIs provided by the IoT Core Library. We recommend that you start by using the supplied sample applications in git, like st_switch. 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:

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_attr_create_int()
  • st_cap_attr_create_number()
  • st_cap_attr_create_string()
  • st_cap_attr_create_string_array()
  • st_cap_attr_free()
  • st_cap_attr_send()

Main function example for ESP8266

/**
SmartThings Device Kit(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. st_iot_core currently offers 13 APIs.
//create an iot context
1. st_conn_init();
//create a handle to process capability
2. st_cap_handle_init();
//register a callback function to process capability command when it comes from the SmartThings Server.
3. st_cap_cmd_set_cb();
//needed when it is necessary to keep monitoring the device status
4. user_defined_task()
//process on-boarding procedure. There is nothing more to do on the app side than call the API.
5. st_conn_start();
**/
void app_main(void)
{
unsigned char *onboarding_profile = (unsigned char *) onboarding_profile_start;
unsigned int onboarding_profile_len = onboarding_profile_end - onboarding_profile_start - 1;
unsigned char *device_info = (unsigned char *) device_info_start;
unsigned int device_info_len = device_info_end - device_info_start - 1;
IOT_CAP_HANDLE *handle = NULL;
int iot_err;
// 1. create an iot context
ctx = st_conn_init(onboarding_profile, onboarding_profile_len, device_info, device_info_len);
if (ctx != NULL) {
iot_err = st_conn_set_noti_cb(ctx, cap_switch_noti_cb, NULL);
if (iot_err)
printf("fail to set notification callback function\n");
// 2. create a handle to process capability
// implement init_callback function (cap_switch_init_cb)
handle = st_cap_handle_init(ctx, "main", "switch", cap_switch_init_cb, NULL);
// 3. register a callback function to process capability command when it comes from the SmartThings Server
// implement callback function (cap_switch_cmd_off_cb)
iot_err = st_cap_cmd_set_cb(handle, "off", cap_switch_cmd_off_cb, NULL);
if (iot_err)
printf("fail to set cmd_cb for off\n");
// implement callback function (cap_switch_cmd_on_cb)
iot_err = st_cap_cmd_set_cb(handle, "on", cap_switch_cmd_on_cb, NULL);
if (iot_err)
printf("fail to set cmd_cb for on\n");
} else {
printf("fail to create the iot_context\n");
}
// 4. needed when it is necessary to keep monitoring the device status
xTaskCreate(smartswitch_task, "smartswitch_task", 2048, (void *)handle, 10, NULL);
// 5. process on-boarding procedure. There is nothing more to do on the app side than call the API.
st_conn_start(ctx, (st_status_cb)&iot_status_cb, IOT_STATUS_ALL, NULL, NULL);
}

Step 4: Build and flash the app

Go to the root directory of the STDK and execute the build script (build.sh) with the below parameter:

cd ~/st-device-sdk-c-ref/
./build.sh esp8266 st_switch #
./build.sh {chip_name} {app_directory}

After compilation, you shoudl see a result similar to below:

Example for ESP8266
|-- output
| `-- iotcore_st_switch_20190719_771f5140 <-- iotcore_'project_name'_'date'_'commit_id'
| |-- address_info.txt
| |-- bootloader.bin
| |-- debug
| |-- partition.bin
| `-- st_switch_demo.bin

You can now execute the following command to flash the entire project (app, bootloader, and init data bin) to a new chip

cd ~/st-device-sdk-c-ref/
./build.sh esp8266 st_switch flash

The serial port needs to be matched to the computer environment for serial port flashing. For example, in ESP8266 the settings for serial port flashing can be configured with 'make menuconfig'. If the serial port setting does not match your environment, please execute the following:

Example for ESP8266
cd ~/st-device-sdk-c/apps/esp8266/st_switch
make menuconfig

Step 5: Test

The SmartThings App should be used to control an IoT device that is running with the SmartThings Cloud server. Go to Google Play or the iOS App Store and download the SmartThings app on your phone.

Reset the Device

Push the reset button of the device or run the command below in the console window.

cd ~/st-device-sdk-c-ref
./build.sh esp8266 st_switch monitor

**Launch the SmartThings App**

Launch the SmartThings App and select the onboarding profile name of your testing device.

Add your test device (executed through the above Reset command)

Android

Control & Monitor a device

Now that your device is on the SmartThings App you can control and monitor your device. Execute your test scripts to make sure the App is working the way you think it should.