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
#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:
#Update Device Information
Your device needs two files to connect to the SmartThings Platform:
- Device Identity (
- Device Onboarding (
#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:
Note: The serial number for devices used during testing (prior to WWST certification) is created by the Developer Workspace.
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.
|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
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:
You can see an example
onboarding_config.json file below:
Here's a breakdown of the data contained in
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
deviceOnboardingIdis 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
mnIdin 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
#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:
Main function example for ESP8266
#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:
After compilation, you'll see a result similar to this:
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:
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:
menuconfig option is only supported on Espressif chipsets.
#Test Your Device
Visit the Test Your Device page to learn more about testing your Device.