Develop a SmartThings Find-compatible device

Objective

Learn how to create your own SmartThings Find-compatible device using the SmartThings Find Partnership Program (Device SDK). Learn how to measure the Radio Frequency (RF) performance of a Bluetooth Low Energy (BLE) device using Tag Toolbox.

Partnership Request

The SmartThings Find Partnership Program is available only to registered partners who wish to commercialize. You can only do this Code Lab and get the resources after a successful partnership. To form a partnership, contact partners@smartthings.com.

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 Microcontroller Unit (MCU) devices.

In this Code Lab, you can learn how to develop your own SmartThings Find device. First, you can know how to set up your project in SmartThings using the Developer Workspace. Next, you can learn how to build your firmware with SmartThings Find Device SDK. Lastly, you can know how to check the functionalities of your device's RF performance using the Tag Toolbox app.

Set up your environment

You will need the following:

Host PC running on Windows 11
Visual Studio Code as the IDE
SmartThings Find Device SDK code
SmartThings Find Tag Toolbox
SmartThings app
Toolchain for nRF52833 DK:
- Use the NCS nRF Connect SDK version 2.6.1
nRF52833 DK with buzzer module and NFC antenna

Galaxy SmartTag2

Register and deploy to test your device

Using the SmartThings Developer Workspace, you can create a device profile, customize the instructions for onboarding the device on the SmartThings 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

Go to SmartThings Developer Workspace and sign in 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, specify whether the device operates on:

BLE
BLE and 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 your devices

You can add the identity of your device in the SmartThings cloud for authentication. This requires device information like serial number and device public key (ED25519). When you reach the maximum number of test devices per user, remove the existing ones.

This example shows how to create an ED25519 key pair with SDK tools. In Visual Studio Code, press the TagKeygen button at the bottom. Afterward, you can generate the serial number, private key, and public key.

Register it to the SmartThings cloud using the SmartThings Developer Workspace and include it in your firmware. After checking the created information on Visual Studio Code:

Go to the Developer Workspace.
Go to Test > Test Devices menu, and click Register New Device.
Input the generated serial number and public key.

Build the firmware with the SDK

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

Open the SDK project

In the File Explorer of Visual Studio Code, you can find four Code Lab files here.

When you click the nRF Connect icon, it shows 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

In main.c, complete the code to call the TagInit and TagStart APIs of Device SDK. You can find CODE_MISSION in the source code and 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;
    }
}

In PortNFC.c, call the setURL function. You can find CODE_MISSION in the source code and follow the instructions in the code by simply removing the comments:

TagError_t PortNFCSetURL(char *url, size_t urlLen)
{
    TagError_t ret = TAG_ERROR_NONE;

    ret = disableNFC();
    if (ret != TAG_ERROR_NONE)
    {
        TAG_LOG_E("Failed to disable NFC");
        return ret;
    }

    /**
     * CODE_MISSION
     * Remove comment(//) below to call setURL function.
     */
	 
    // ret = setURL(url, urlLen);
    if (ret != TAG_ERROR_NONE)
    {
        TAG_LOG_E("Failed to set URL message");
        return ret;
    }

    ret = enableNFC();
    if (ret != TAG_ERROR_NONE)
    {
        TAG_LOG_E("Failed to enable NFC");
        return ret;
    }

    return TAG_ERROR_NONE;
}

Build

Go to nRF Connect > Actions
Click on Build.

NoteIt may take some time for the build to finish. You can see the progress by checking the popup at the bottom-right corner of the IDE. You can also select nRF Connect: Build in the terminal to check the detailed status.

Flash

Connect the nRF52833 DK to your computer.
Go to nRF Connect > Actions
Click on Flash.

Once completed, you can hear a notification sound from your device.

Check the serial log of your device

Go to nRF Connect > Connected Devices.
Click the Plug icon on the right side of VCOM0 COMxx.
At the top of the IDE, select the first item in the list under Connected Devices.

Press the Reset button briefly on your device.

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

Onboard and control your device via SmartThings app

Onboard your device

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

Allow the use of location information and press Agree.
Verify your device by pressing the button on the board.
In the Success! page, tap on Done to finish onboarding your device.

Locate and ring your device

Tap on View map to show the location of your device.
Select Ring and your device produces a sound through its buzzer module.
You may switch to either high-volume or low-volume ringing.
Press Stop to stop the ringing.

Configure the lost mode of your device

When Lost mode is activated, it allows you to view a lost message showing the owner's contact information and any personalized messages.

In the Smartthings app, tap on View map > More > Lost mode.
In the Lost mode page, select Next.
Add Email, Contact, and Message information. Then, tap on Turn on.
Test it by placing an NFC device (or a mobile device) at the NFC antenna of your device. A lost message should show on your mobile device.

Test the device's RF performance via Tag Toolbox

SmartThings Find Tag Toolbox allows you to measure the RF performance of a BLE device and log the results.

Create a new test item

Launch the Tag Toolbox app on a mobile device.
Tap on BLE Performance > Add new test to create a new test item.
Select a Target device and a Reference device to compare RF performance:
a. Target device: this is your device created through this Code Lab.
b. Reference device: this is the SmartTag2 as a comparison target.

Conduct RF performance tests

Press Start session and check your device's RF performance.
Once completed, tap on Take a picture and capture how far away the mobile device is from both your device and the SmartTag2.
Tap on Test result to find out your device's RF performance.

Export test result

Test reports can be exported as a file either during the test or after completing the test:

Check your device's RF performance in the List of session menu.
a. Min RSSI: minimum value of your device's RF signal.
b. Max RSSI: maximum value of your device's RF signal.
c. Packet detection rate: if the advertising transmission interval is two seconds, it indicates how many packets were detected during the test duration.
Press Export test result and it shows the location of the file on your mobile device.

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, contact partners@smartthings.com.