Develop a SmartThings Find-compatible device


Objective

Learn how to create your own SmartThings Find-compatible device using SmartThings Find Partnership Program (Device SDK and Test Suite).

Partnership Request

The SmartThings Find Partnership Program is closed to the public and available only to registered partners who wish to commercialize. You can only do this Code Lab and get the resources after successful partnership. To form a partnership, visit www.smartthings.com/partners and complete the application. Specify the partnership to be Mobile Connected.

Overview

The SmartThings Find Partnership Program comprises SmartThings Find device specification, SmartThings Find Device SDK, test tool, and technical support. It facilitates the development of devices operating with SmartThings Find services and mobile applications. The SmartThings Find Device SDK is small enough to work on resource-limited Micro-Controller Unit (MCU) devices.

In this Code Lab, you can learn how to develop your own SmartThings Find device. It is explained in three parts. The first explains how you can set up your project in SmartThings using Developer Workspace. Then, it demonstrates how to build your firmware with SmartThings Find Device SDK. The third part shows how to check the functionalities of your device with the SmartThings Find Test Suite application.

Set up your environment

You will need the following:

  • Host PC running on Windows 11
  • Visual Studio Code
  • SmartThings Find Device SDK code
  • SmartThings Find Test Suite
  • SmartThings Find mobile application
  • Toolchain for nRF52833 DK:
  • nRF52833 DK and buzzer module

Register and deploy to test your device

Using Developer Workspace, you can create a device profile, customize the instructions for onboarding the device on the SmartThings mobile app, and test the devices by deploying them. You can edit the configurations until you submit the device for publication in the SmartThings ecosystem.

Sign in to SmartThings Developers

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

Select a project and add a device profile

Select STFind CodeLab example and check its device profile.

Under the device profile, you can specify whether your device will operate on Bluetooth Low Energy (BLE) only, or will it also support Ultra Wide Band (UWB).

Afterward, you can customize your device’s onboarding experience in SmartThings by uploading your product images, user instructions, and brand name under Device Onboarding.

Lastly, you can fill in basic product information in the Product Info.

Deploy your device to test

After you complete all of these, you can go back to the Overview tab and press Deploy to Test.

You can download the TagOnboardingConfig.h file which includes your project configuration. The SDK code needs this configuration file.

Register test devices

You can add the identity of the device in the SmartThings cloud for authentication. 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 have reached it, you should remove the existing one.

This example shows how to create an ED25519 key pair with SDK tools. Press the TagKeygen red action button of Visual Studio Code at the bottom.

By pressing the TagKeygen, you can generate the serial number, private key, and public key. Register it to the SmartThings cloud via the developer workspace and include it in your firmware.

After checking the created information on Visual Studio Code:

  1. Go to Developer Workspace again.
  2. Go to Test > Test Devices menu, and click Register New Device.
  3. Copy and paste the serial number and public key to the popup in Developer Workspace.

Build the firmware with SDK

Open Visual Studio Code on the host PC and build the firmware for your device.

Open the SDK project

There are two tabs at the primary side bar.
The first tab is File Explorer. You can find four Code Lab files here.

The second tab is nRF Connect. In this tab, there are important functions such as Build, Flash, and Serial log.

Check the configuration files

Ensure that two essential configuration files are applied:

  • TagOnboardingConfig.h
  • TagDeviceInfo.h

Write your code

  • Complete the main.c code to call the API of Device SDK. You can find CODE_MISSION in the source code. You can follow the instructions in the code by simply removing the comments:
#include <zephyr/zephyr.h>
#include <zephyr/sys/printk.h>

#include "TagSdk.h"
#include "mbedtls/aes.h"

static void init_aes_table(void)
{
    mbedtls_aes_context dump_ctx;
    unsigned char dump_key[16];
    mbedtls_aes_setkey_enc(&dump_ctx, dump_key, 128);
}

void main(void)
{
    int err = 0xff;
    TagResult_t result = TAG_RESULT_NOT_SUPPORTED;

    /**
     * CODE_MISSION
     * You will check this serial log later in this codelab.
     */
    printk("Tag DEMO! %s-%s-%s\n", CONFIG_BOARD, __DATE__,__TIME__);

    init_aes_table();

    /**
     * CODE_MISSION
     * Call TagInit API by removing comment(//).
     * 
     * By calling this API, Tag SDK will load NV, set RTC and
     * initialize crypto, and so on. 
     * You shall initialize BSP before call this API
     * services and starts BLE advertising.
     */

    // result = TagInit();
    if (result != TAG_RESULT_SUCCESS)
    {
        printk("Failed to init:%d\n", result);
        return;
    }

    err = bt_enable(0);
    if (err)
    {
        printk("Failed to init bt :%d\n", err);
        return;
    }

    /**
     * CODE_MISSION
     * Call TagStart API by removing comment(//).
     * 
     * By calling this API, Tag SDK will initialize BLE GATT
     * DB and services and starts BLE advertising.
     * You shall initialize BLE stack before call this API.
     */

    // result = TagStart();
    if (result != TAG_RESULT_SUCCESS)
    {
        printk("Failed to start MainTask:%d\n", result);
        return;
    }
}
  • Complete the PortBuzzerControl.c code to call the API of Device SDK. You can find CODE_MISSION in the source code. Follow the instructions in the code by simply removing the comments:
TagError_t PortBuzzerHwCtrlSetVolume(SoundVolume_t volume)
{
    switch (volume)
    {
        case SOUND_VOLUME_MUTE:
            /**
              * CODE_MISSION
              * Set currentVolume and call Mute function
              * by removing comments(//) below.
              */
            // currentVolume = PWM_DUTY_FOR_MUTE;
            // PortBuzzerHwCtrlMute();
            break;
        case SOUND_VOLUME_NORMAL:
            /**
              * CODE_MISSION
              * Set currentVolume and call Unmute function
              * by removing comments(//) below.
              */
            // currentVolume = PWM_DUTY_FOR_NORMAL;
            // buzzerHwCtrlUnmute();
            break;
        case SOUND_VOLUME_LOUD:
            /**
              * CODE_MISSION
              * Set currentVolume and call Unmute function
              * by removing comments(//) below.
              */
            // currentVolume = PWM_DUTY_FOR_LOUD;
            // buzzerHwCtrlUnmute();
            break;
        default:
            TAG_LOG_E("Error volume level value!");
            return TAG_ERROR_INVALID_ARG;
    }
    return TAG_ERROR_NONE;

Build

To build, you need to:

  1. Select the nRF Connect tab.
  2. Go into Actions.
  3. Press Build.
  4. It takes some time for the build to finish. By checking the popup at the bottom right corner of the IDE, you can see the progress. You can also select nRF Connect: Build in the terminal to check the detailed status.

Flash

To flash, you need to:

  1. Connect the nRF52833 DK to the host PC.
  2. Select the nRF Connect tab.
  3. Go into Actions.
  4. Press Flash.
  5. Once completed, you can hear a notification sound from the device.

Check the serial log of the device

Here, to check the serial log, you have to:

  1. Select the nRF Connect tab.
  2. Go to Connected Devices.
  3. Press VCOM0 COMxx.
  4. Click the Plug icon on the right.
  5. The list will be shown at the top of Visual Studio Code. Select the first item under Connected Devices.

  1. Press the Reset button briefly on the device.

  1. By checking the timestamp from the serial log, you can verify whether the device successfully downloaded the firmware.

Create a device configuration file for the Test Suite

You have now completed creating a device with the SDK. To test this device with the Test Suite, a device configuration file is needed:

  1. Click the TestSuite Config green action button.
  2. Here, you can see the location where the CSV file was created.

  1. Go to the file location and copy the CSV file to your mobile device (Internal Storage > Downloads).

Test via SmartThings Find Test Suite app

SmartThings Find Test Suite allows you to check and test each function and log the results.

Load the device configuration file

To load CSV file, you have to:

  1. Launch the Test Suite app on the mobile device.
  2. Press Upload File to load the device configuration file.
  3. Select the CSV file you copied from the host PC.
  4. You can now see the loaded project.

Out of Box State Advertisement

Once you load the device configuration file, you can start testing items listed by category:

  1. Press Out of Box State Advertisement.
  2. Press Start test.
  3. Once completed, press Next Test Group to go to the next test.

Onboarding

Onboarding is the process of creating a secure communication channel between the app and the device, as well as registering the device information in SmartThings Find Test Suite. To do this, you need to:

  1. Press Start test.
  2. Once completed, press Next Test Group to go to the next test.

Other States Advertisement

To test this:

  1. Press Start test.
  2. Make sure all items listed have a check mark beside them.
  3. Once completed, press Next Test Group to go to the next test.

Authentication

To test this:

  1. Press Start test.
  2. Make sure all items listed have a check mark beside them.
  3. Once completed, press Next Test Group to go to the next test.

Ringtone Status

To test this:

  1. Press Read Ringtone Status.
  2. Once completed, press Ringtone On.
  3. Check if there's a ringtone sound from the device.
  4. Press Ringtone Off.
  5. Check if the ringtone sound stops.
  6. Once completed, press Write Ringtone invalid value.
  7. Then, press Next Test Group to go to the next test.

Factory reset

To test this:

  1. Press Factory Reset wrong value.
  2. Once completed, press Factory reset.
  3. Then, the device should beep.
  4. Press Finish Test.

Export test report

Test reports can be exported as a file either during the test or when the test is completed:

  1. Click the Export icon at the top right of the screen.
  2. Press OK to continue.

Onboard and control the device via SmartThings app

Onboarding

To onboard the device, you need to:

  1. Launch the SmartThings app.
  2. Press + icon at the top right of the screen.
  3. Click on Add device.
  4. Press Add in the Partner devices section.
  5. Select My Testing Devices.
  6. Then, select STFind Codelab Example to start onboarding.

  1. Allow use of location information and press Agree.
  2. Verify your device by pressing the button on the board.
  3. After verifying, a Success! page shows up. Then, press Done to finish.

Ring the device and view it on a map

Here, you can view the location of the Find-compatible device and send a command to ring it:

  1. Press View map to view the device on a map.
  2. Select Ring and the device should produce a sound through its buzzer module.
  3. You may switch to either high volume or low volume ringing.
  4. Press Stop to stop the ringing.

You're done!

Congratulations! You have successfully achieved the goal of this Code Lab topic. Now, you can develop your own SmartThings Find-compatible devices.

To form a partnership, visit www.smartthings.com/partners and complete the application. Remember to specify the partnership to be Mobile Connected.