The purpose of this guide is to help Gecko OS developers configure Azure Device Service (DPS) and write Gecko OS application to provision WGM160P device(s) into Azure using DPS
Note: Azure DPS is only supported starting from Gecko OS 4.1
1. Introduction
“The IoT Hub Device Provisioning Service is a helper service for IoT Hub that enables zero-touch, just-in-time provisioning to the right IoT hub without requiring human intervention, allowing customers to provision millions of devices in a secure and scalable manner.” – definition by Microsoft
The general overview of the process is defined as the following:
Device manufacturer adds the device registration information to the enrollment list in the Azure portal.
Device contacts the provisioning service endpoint set at the factory. The device passes the identifying information to the provisioning service to prove its identity.
The provisioning service validates the identity of the device by validating the registration ID and key against the enrollment list entry using standard X.509 verification (X.509).
The provisioning service registers the device with an IoT hub and populates the device's desired twin state.
The IoT hub returns device ID information to the provisioning service.
The provisioning service returns the IoT hub connection information to the device. The device can now start sending data directly to the IoT hub.
The device connects to IoT hub.
The device gets the desired state from its device twin in IoT hub.
2. Create and Configure DPS via Azure IoT Portal
2.1. Create an IoT Hub (if you do not have already)
For Provisioning Host, enter the Global device endpoint of your DPS (obtained above)
For ID Scope, enter the ID Scope for your DPS (obtained above)
For Certificate, paste in your generated certificate (e.g., root_private.pem obtained above)
For RSA Private Key, paste in your generated key (e.g., root_cert.pem obtained above)
Click Save
The created connector is linked to your product, and any device activated to this product can communicate with it.
4. Device side: Gecko OS Application
Note: Gecko OS example app source code is released as a part of Gecko OS SDK 4.1.11. Once you have the SDK downloaded, you can find it under: sdk\standard\wgm160p\4.1.11-7064\applications\gecko_os\cloud\dps_demo
Now you have a connector ready and DPS configured in Azure, it is the time to send a provisioning request from the device side to the DMS connector. DMS in turn sends the request to Azure and returns back the device certificate and key. Once device obtains the cert and key pair, it encrypts and stores them securely on the file system then using them for farther communication with Azure IoT Hub. The DPS and DMS connector are done at this stage
Note: This part assumes basic knowledge of development using Gecko OS. For more info, please head to the online doc:
Activate device to the product created above (since, it can use the connector). This is not done automatically in the example app and you need to do that using the standard dms_activate command. More here: https://dms.zentri.com/tutorial/activate-to-product
In Gecko OS, enable the DMS websocket to automatically start when the network is brought up (please see resources\settings.ini file where this setting is already enabled):
set dms.auto_start_enabled 1
Configure the different application custom variables:
dps.connector: DMS connector code (make sure your device is activated)
dps.hostname: Hostname or IP address of the broker/server
dps.port: Port of the provisioning server/broker"
dps.ca_cert: CA cert filename used for TLS verification request
dps.key_filename: Filename used to store the client certificate (if provisioning succeeded)
dps.key_filename: Filename used to store the client key (if provisioning succeeded)
Configure the network credentials: wlan.ssid and wlan.passkey, then save all.
Now, issue the custom command dps_provision
Device establishes a secure websocket connection with DMS using its own device cert.
Device registers for DMS message responses
Once device connects to DMS websocket, app sends a provisioning request in the form:
{
request: 'provision',
code: code
}
DMS gets the request (including the device UUID as an identifier), then talks to Azure to provision the device in IoT Hub
If successful, Azure replies back with the device cert/key pair
DMS responds to the provision request with the device cert/key pair. The response format looks like:
Device retrieves the cert and key, then write them to the file system securely (files defined by dps.key_filename and dps.cert_filename)
Device disconnects
To verify the provisioning process, use the custom command dps_verify. This will use the obtained cert and key files, in addition to the configured CA cert to establish a TLS connection to the host defined by dps.hostname:dps.port
Later, when device wants to communicate with Azure IoT Hub, it establishes TLS connection using the client key and cert. That is done as the following:
set network.tls.client_cert azure_client_cert.pem
set network.tls.client_key azure_client_key.pem
tls_client .azure-devices.net 8883
In this test, we used WGM160P mounted on WSTK, the default evaluation starer kit. For more info, please refer to: WGM160P Wi-Fi Module Starter Kit
The current measurement is averaged over 60 to 100 seconds (captured 1-minute after associating, or not in case of sleep/shutdown)
We use used Cisco Linksys WRT610N access point configured with 100ms beacon interval and default beacon duration
For the WLAN power saving move, we use used Alfa access point configured with beacon interval 102.4ms and 1ms duration (Cisco Linksys WRT610N used for the default, sleep, and shutdown measurements)
The measurements below obtained for the current official release (at the time of writing this article), in addition to the new alpha and beta releases for coming Gecko OS 4.1
To get access to Gecko OS BETA, please issue the command: dfu_update -b 4.1.10 --multi
Note: do not use a “listen interval” higher than 3 to avoid potential issue with some Access Points.
Note: Listen interval higher than 0 uses DTIM skipping and so this could add jitters/delay on the packet arrival time.
Measurements
ON BOOTUP/DEFAULT
get wlan.mac
factory_reset <MAC_ADDRESS>
Gecko OS 4.0.18
Gecko OS 4.1.9 ALPHA
Gecko OS 4.1.10 BETA
16 mA
5.20 mA
5.17 mA (Figure 1)
UART & WLAN POWERSAVE
set wlan.powersave.mode 2
set uart.powersave.mode uart0:1,uart1:1
set system.powersave.wakeup_gpio_mask 0x1000000
set system.powersave.idle_timeout 250
set system.powersave.mode 2
set wlan.ssid LINKSYS
set wlan.passkey password
set broadcast.interval 0
uartu 0
nup
Gecko OS 4.1.10 BETA
Listen Interval 0*
Listen Interval 3*
Listen Interval 5*
DTIM 1 Alfa AP
Beacon duration 1ms
920 µA
632 µA
576 µA
DTIM 3 Alfa AP
Beacon duration 1ms
666 µA
560 µA
550 µA
DTIM 10 Alfa AP
Beacon duration 1ms
558 µA
521 µA
520 µA
* : Listen Interval set the number of DTIM beacon which will be skipped (not Received).
** : ping timeout possible because of delay on the packet arrival time
SLEEP
set uart.powersave.mode uart0:1,uart1:1
set system.powersave.wakeup_gpio_mask 0x1000000
set system.powersave.idle_timeout 250
set system.powersave.mode 2
uartu 0
Gecko OS 4.0.18
Gecko OS 4.1.9 ALPHA
Gecko OS 4.1.10 BETA
N/A
530 µA
530 µA (Figure 5)
SHUTDOWN
set system.shutdown.wakeup_gpio_mask 0x4004000
shutdown
Gecko OS 4.0.18
Gecko OS 4.1.9 ALPHA
Gecko OS 4.1.10 BETA
N/A
990 nA
940 nA (Figure 6)
Figures
Figure 1: ON BOOTUP/DEFAULT (Gecko OS 4.1.10)
Figure 2: UART/WLAN POWERSAVE (Gecko OS 4.1.10 LINKSYS DITM1)
Figure 3: UART/WLAN POWERSAVE (Gecko OS 4.1.10 LINKSYS DITM3)
Figure 4: UART/WLAN POWERSAVE (Gecko OS 4.1.10 LINKSYS DITM10)
If you used Gecko OS for WGM160P, you must have heard about development vs production many times. The development and production terms are used across different topics and get confusing sometimes. This article explains the difference in detail and helps to understand the different use cases for these terms.
Development vs Production Device Credentials:
To communicate with Zentri Device Management Service (DMS), a device needs to establish a secure channel with the server. That is done using the device’s credentials. The device's updatable security credentials reside in a specific memory section of the device’s flash. This memory section will persist through Device Firmware Update (DFU). The credentials are programmed during manufacturing and updated during DFU if needed. These can be also flashed and replaced with development credentials as explained below. Without valid credentials (either production or development), a device cannot communicate with DMS.
Production Credentials:
Silicon Labs programs DMS credentials into the device during the manufacturing process (hence the term production credentials). Once programmed, the process makes sure to LOCK the device. Locking the device refers to “debug interface locking” which disables access to the internal flash and the Cortex-M4 core from the debug interface.
Unlocking the debug interface will erase those credentials along with the rest of the internal flash. That guarantees devices with unlocked debug interface cannot expose the production credentials at all. In other words, the device is considered compromised once it has its debug interface unlocked. We do not know what users used it for and it will live forever as a development device.
Development Credentials:
Once a device is unlocked, the production credentials are deleted (and never recovered). Now, how to use the device if you still need to work with DMS? You need to use development credentials. During development, the device is given development DMS credentials that expire after 30 days. This is done during the device setup step of development (using Gecko OS Studio or Gecko OS SDK). The credentials are re-renewed every time the device is setup again using Gecko OS Studio. Once credentials expire, the device will not be able to communicate with DMS (any update or query will fail with error 403/400).
In the final product, never ship non-locked devices to end users. Always make sure that the device is locked and programmed with production credentials. In other words, once the device is used for development once, never use it in a consumer product. Keep it for development and testing.
Devices come locked and pre-programmed with production credentials. To keep those during your production process, you should only program your devices via one of the methods below:
Using factory/offline DFU via the UART interface, as described here.
Development vs Production DMS Flow:
The second context that uses production and development terms is the production flow via DMS. In this case, we are distinguishing between a development and production product on DMS. The difference is highlighted below. Note that this context has nothing to do with the device credentials explained earlier.
Development Product:
This is the default, most commonly used product type used during the development cycle. Once you create a project in Gecko OS Studio, a development product is created on DMS. The product code always starts with your user account code (6-character length code, starting with 0). For example, 0ST3XD-AZURE_DEMO. Once you use the Gecko OS SDK/Studio to release a bundle, this linked product is used. More about bundle release (application deployment) is described in this tutorial.
You can also create a development product directly using DMS UI and either add a new bundle or copy it from another product you have access to. This is also explained in this tutorial.
To update your device’s firmware with a development product bundle, you will need to claim the device to your account, then activate it to the product using the product code. Once activated, you can pick any bundle published on this product. Latest released bundle is obtained via the “dfu_update” command, while you can choose a different bundle if you specify the bundle number using the -b argument.
If you have many products you have access to, you can easily move across different products via activating using the product code, then issuing the DFU update command.
Note that a DMS user account is limited to a number of devices that can be activated to development products. As explained earlier, this phase is only recommended for development and testing activities.
Production Product:
Once you are happy with the firmware you developed, it is the time to “productize” it. That means creating a production product and moving the bundle across. A production product is not linked to a DMS user, but to a DMS customer account. That is, it does not start with a user code but with customer code. A customer code is a 6-character length string you chose while creating a customer account. An example of a production product is SILABS-AZURE_DEMO. More about creating a customer account and linking it to your user account is explained here.
Production products can have an unlimited number of devices activated to it. The main differences introduced for production products are explained below:
You cannot use the product code anymore. You will have to use activation tokens to activate a device to production product. Also, you do not need to claim the device first. The reason here is that device is not “owned” by your user account anymore but associated to the customer account instead. If you have access to the customer account, you still have access to the device on DMS. More about activation tokens and how to obtain them is described here. Remember that a token is a secret key, and anyone that knows your activation token can use it to activate any device to your product and obtain a copy of your firmware binaries.
Devices cannot pick a random bundle to update using the -b parameter. The extra argument will be ignored, and only the latest released bundle that matches the device’s tag will be downloaded.
Devices activated to a production account can not reactivate to another product from the device’s side. In other words, you can issue the command “dms_activate ” only once using Gecko OS command API. Second activation will fail unless device is reset first (explained later). The reason here is that production devices are distributed to end users, and you do not want a user to change the device’s standard product (if you shipped the device as a “toaster”, you do not want anyone has access to the device’s terminal to change it to a “fridge”).
As an account owner, you can move devices across different products under the same customer account. This is from the DMS UI only though, and only the account admin can do that. The use case here is that if you wanted to upgrade the device from a “toaster” to a “toaster plus”, you can do that using the UI. You can also factory reset the device back to the platform product (SILABS-WGM160P) from the DMS UI.
Caution: once you factory-reset the device, you will lose access to the device and it needs to use the terminal to activate it again. You should not perform this factory reset to a device in field, or a device you do not have a physical access to.
The regular recommended DMS flow is to first use a development product to release your firmware. Evaluate and test the bundle on your development device. Once everything is alright, create a production product and clone this bundle across. Always activate fleet devices to a production product (using an activation token) before shipping.
AEM/Energy Profiler is not enabled by default for WGM160P target (using WSTK). Until that is being enabled in Simplicity Studio, you can follow the instruction below:
2. In Simplicity Studio right click on the "J-Link Silicon Labs" debug adapter and choose "Device Configuration":
3. Under the "Device hardware" tab change the "Target Part" to EFM32GG11B820F2048GM64 as shown below.
4. Click OK then launch Energy Profiler
5. Under "Quick Access" select "Start Energy Capture"
6. Choose the J-Link adapter then click OK.
Note:
There are two power domains on the STK. One for the WGM160P and peripherals, where the other is for the board controller (debugger, etc.). The Energy Profiler only measures the first one. Therefore the measurements are extremely close to the true power consumption of the WGM160P itself. Also note that the Energy Profiler circuit on the STK has a max reading of 95mA so it might max-out during Wi-Fi transmission.
If you want to get even more precise or more range you would need to use a scope or power analyzer to measure the current at resistor R616 or at J1 on the WGM160P radio board. See/request the board schematic and layout for reference.
If you are trying to re-certify the module, or the end product using Gecko OS, please have a look at the certification example app found in the SDK at ~\applications\gecko_os\test\certification. The purpose of this example is to provide the functionality needed for certification. Like all example apps you can clone it from Gecko OS studio. It is found under "Test Examples" as shown below:
Note: the test app referred below is based on Gecko OS 4.1.11
Please see below for the different variables and settings:
Variable
Commands
Abbreviated
Default
Comments
Channel
get/set wifi_test.channel <1 .. 14>
get/set wt c
1
Wi-Fi 2.4GHz channel (1 -> 14)
Test Mode
get/set wifi_test.mode
get/set wt m
tx_cw
Selects the activated test mode: rx: received frames and count number of good or bad packets tx_packet: transmit the frames in the mode selected according to other wifi_test settings tx_cw: transmit a sinus wave signal at the selected frequency
There is also a custom command to start the transmission or reception of frames: wifi_test start
Examples:
Get TX_PACKET 11n MCS7 continuously to RF2 output (test in conducted):
set wlan.antenna.select 2
set wifi_test.channel 6
set wifi_test.mode tx_packet
set wifi_test.period 5000
set wifi_test.tx.protocol n
set wifi_test.tx.rate 7
set wifi_test.tx.ht_format mm
set wifi_test.tx.length 1400
set wifi_test.tx.number 0
wifi_test start
TX_PACKET 11g 54Mbps:
set wlan.antenna.select 2
set wifi_test.channel 6
set wifi_test.mode tx_packet
set wifi_test.period 5000
set wifi_test.tx.protocol g
set wifi_test.tx.rate 54
set wifi_test.tx.length 1400
set wifi_test.tx.number 0
wifi_test start
DSSS 11b 11Mbps
set wlan.antenna.select 2
set wifi_test.channel 6
set wifi_test.mode tx_packet
set wifi_test.tx.protocol b
set wifi_test.period 5000
set wifi_test.tx.rate 11
set wifi_test.tx.length 1000
set wifi_test.tx.number 0
wifi_test start
Stop TX after 100 frames and update the TX for rate MCS4 (if already in 11n):
set wifi_test.mode tx_packet
set wifi_test.tx.number 100
wifi_test start
TX stopped. Set tx.rate in MCS4 and then TX frames continuously
set wifi_test.tx.rate 4
set wifi_test.tx.number 0
wifi_test start
Get CW signal to RF2 output:
set wlan.antenna.select 2
set wifi_test.channel 6
set wifi_test.mode tx_cw
set wifi_test.period 5000
wifi_test start
WLAN backoff of 5dB on channel 6 for mod_group_5
set wlan.backoff 6 0,0,0,0,0,5
RX_PACKET for 11bgn 20MHz signals on channel 7 on RF2
set wlan.antenna.select 2
set wifi_test.channel 7
set wifi_test.mode rx
set wifi_test.period 5000
wifi_test start
We get then every 5 seconds (wifi_test.period=5000µs) this Rx statistic report:
The statistics are done on 5 seconds. In this example, the Wi-Fi source transmits only 802.11n MCS7 frames in the channel 7.
Please note when some packets are completely erroneous and not detected like a Wi-Fi frame then they are not counted in “Frames received” or “Bad Frames”.
This PER accuracy issue, it happens more when we are close or below the sensitivity level.
So in order to get an accurate PER, you have to compute it based on number of transmitted frames by the Wi-Fi source.
To stop this Rx mode with statistic report:
set wifi_test.mode tx_packet
set wifi_test.tx.number 100
wifi_test start
Factory DFU is intended to be used during factory programming (as opposed to in-field programming). Rather than cache DFU package files to extended flash, package files intended for internal flash are directly written. This allows for faster programming at the expense of reduced reliability. Factory programming is less 'reliable' as the internal flash is erased before the DFU package is fully validated. This is not recommended for the field as a bad DFU package could leave the Device in a non-functional state.
Note: This is an early implementation of the factory DFU process. Some changes on how the package is encrypted is currently under discussion and might affect the user experience. Feel free to use it for devices under development for now.
Disclaimer: the process explained below is a one-way process. Once "dfu_update --factory SILABS" command is invoked, there is no going back. The device will only boot into the Gecko OS bootloader until a GBL image is successfully programmed. Both the internal and extended flash memories are completely erased BEFORE the DFU is executed (the device credentials on internal flash persist). The device could be left in an unusable state should the DFU fail
2. DESCRIPTION:
In this method, multiple devices are updated with a single DFU package consisting of images to be programmed to specified flash locations.
Devices programmed with a Factory DFU cannot retain NVM variable settings or files. All existing NVM variable settings and files are erased from the device, other than the device credentials.
The DFU image/package is obtained once using DMS UI (coming soon), or RESTful API call as highlighted below.
The DFU package is generated for a certain product bundle. Version number will need to be specified in the request.
The request also should specify the ‘from product’ field. This is the product currently programmed on the target devices (for fresh devices, this is the SILABS-WGM160PK product)
Once package is transferred to the device, it is decrypted, and update process starts.
The RESTful request should be issued using a token of a user has access to both products
Device does not need to be connected to internet to receive the DFU package.
Device also does not need to be claimed to a certain user or activated to a certain product.
The package is delivered over serial interface using XMODEM protocol (1k blocks).
An executable is provided to transfer the DFU package over serial. You can use any other implementation of XMODEM-1K (explained farther below)
3. OBTAINING THE GBL PACKAGE
GBL file presents the binary package that will be used in the update procedure later.
The package can only be obtained through DMS. User can not build it using Gecko OS binaries, or any other method.
Until the UI on DMS side is ready, this RESTful API can be used. Here is the cURL request:
user_token: Replaced by user API Token obtained from DMS: (Profile -> API Tokens -> Issue API Token) – for example: RkxhQkdCRkEzWFNYxxxxxx
SILABS-WGM160PK: current product installed on the target device. Can be any product code, but generally SILABS-WGM160PK for any fresh modules never used before
0.0.1: bundle version number you need to update to
development: if device used earlier with GSS or SDK, this needs to be “development”. For production devices that are never used for development, this should be set to “production”. For more info regarding development vs production, please review this application note.
SILABS-WGM160PK-to-DFU-PACKAGE_0.0.1.gbl: Package GBL file name (use any name of your choice)
4. THE UPDATE PROCESS:
Connect your target device to your PC using the USB. Assuming evaluation board is used here, device will be detected as COM port
In case you are using the bare module, you will need to use a UART to USB converter connected to the modules UART pins (UART0 TX and UART0 RX). If you are using one of the evaluation boards, then use the USB connection directly.
Use the provided tool (attached as a zip file) to download the package to device – replace COMxx with the COM port detected:
Leave it running until operation completes successfully. You should see something similar to this:
gecko_os_dfu.exe COM21 SILABS-WGM160PK-to-DFU-PACKAGE_0.0.1.gbl
+----------------------------------------------------------------------------+
| Welcome to Gecko OS offline/standalone programmer |
| Version 1.0.0 - Released 26 July 2019 |
| Use this tool to program Gecko OS factory package via the serial interface |
+----------------------------------------------------------------------------+
Opening serial port: COM21
Performing DFU update...
Erasing flash...
Starting package transfer, please wait...
100% transferred
Package transferred successfully...
Finalizing update, please wait...
Device ready. Reading DFU status...
Device firmware updated successfully!
UUID: EADE2FF3D61F482913FA5B5BDxxxxxxxxxxxxxxx
Firmware version: SILABS-WGM160PK-4.0.18, Gecko_OS-STANDARD-4.0.18, WGM160P
DFU response in base64 format (to send later to DMS):
-----------------------------------------------------
gqdHVyZcpSZ...etc...amy1PVlNwX8owo6WmQBg==
-----------------------------------------------------
DFU response (in msgpack format) is written to file EADE2FF3D61F482913FA5B5BDxxxx.bin
+----------------------------------------------------------------------------+
| DEVICE UPDATED SUCCESSFULLY |
+----------------------------------------------------------------------------+
At this stage, device is completely updated to the new firmware bundle. You can go ahead and start using your device is usual.
Note: the offline DFU procedure will intentionally put the device in machine format, where the command/response header is enabled. This will persist after a successful update, until device is physically unplugged and plugged again. Soft reboot will not set it back to human format. This makes it easier for the update tool to detect errors and parse different responses.
If you do not want to use the tool, you can use TeraTerm terminal to send the file over XMODEM. To do so:
Connect to the COM port detected by your PC
From the serial interface, issue the command: dfu_update --factory SILABS
Note: Once this command is invoked, there is no going back. The device will only boot into the Gecko OS bootloader until a GBL image is successfully programmed. Both the internal and extended flash memories are completely erased BEFORE the DFU is executed (the device credentials on internal flash persist). The device could be left in an unusable state should the DFU fail
Enter ‘start’ word then hit enter
Now, use TeraTerm to send the file over XMODEM (File -> Transfer -> XMODEM -> Send). Select the GBL file obtained earlier. Select the 1K check box at the dialog box before sending the file
It will take some time then reboot the device into the new updated bundle.
5. SEND RESULT TO DMS:
Once the DFU operation is completed, we will need to post the 'DFU Success' result back to DMS. Doing so will help DMS to know the current firmware bundle installed in device. In the future, if device requests over-the-air (OTA) update, DMS can provide the right bundle based on the devices’ status.
To do that, you will need to specify your user token as an optional parameter:
Where user_token is the user API Token obtained from DMS: (Profile -> API Tokens -> Issue API Token) – for example: RkxhQkdCRkEzWFNYxxxxxx
If this token optional argument is not passed, this step is skipped.
Note: In case you are using this setup offline and there is no internet connection to submit the result while updating, you will need submit the results manually later using the API demonstrated in the cURL request (in this case, do not pass the token optional argument):
base64_data: the DFU response printed on completion of the DFU process. This is presented in base64 format. It can be obtained using the Gecko OS command “dfu_response”. For example: gqdwYXlsb2FkxgAABPv5qB2r4xDINzqpws1ZYFz4KLqXNpZ25...etc...1346vtxOx8v5mpEZn1YcYr4mZ5u9Tw3X9ME0E2GzOviIN0RtPEA7qrYzISZmR+82g==
user_token: Replaced by user API Token obtained from DMS: (Profile -> API Tokens -> Issue API Token) – for example: RkxhQkdCRkEzWFNYxxxxxx
Same can be done using the msgpack binary data returned by the provided tool as well. You will notice once DFU operation successes, there is a bin file created in the working directory named with device UUID. This file contains the same base64 DFU result but in binary msgpack format. It can also be generated using Gecko OS command “dfu_response -m”. The cURL call to use this binary file is:
EADE2FF3D61F482913FA5B5BDxxxxxxxxxxxxxxx.bin: the DFU response in msgpack format obtained using the DFU tool as explained above.
user_token: Replaced by user API Token obtained from DMS: (Profile -> API Tokens -> Issue API Token) – for example: RkxhQkdCRkEzWFNYxxxxxx
6. VERIFICATION:
To verify that everything is working as expected, please make sure of these two steps (verify only one random device, as rest should behave similarly):
The current version on device after DFU is matching what you requested first. This can be checked using the command “ver” on Gecko OS command interface.
From DMS UI, you should be able to locate the device using its uuid and verify that current firmware version installed matches the version obtain in step 1 above.
For any question or farther clarification, please comment below or go ahead and create a technical support case using Silicon Labs support portal: https://www.silabs.com/support
Wi-Fi Knowledge Base
Working with Azure DPS in Gecko OS
The purpose of this guide is to help Gecko OS developers configure Azure Device Service (DPS) and write Gecko OS application to provision WGM160P device(s) into Azure using DPS
Note: Azure DPS is only supported starting from Gecko OS 4.1
1. Introduction
“The IoT Hub Device Provisioning Service is a helper service for IoT Hub that enables zero-touch, just-in-time provisioning to the right IoT hub without requiring human intervention, allowing customers to provision millions of devices in a secure and scalable manner.” – definition by Microsoft
The general overview of the process is defined as the following:
Device manufacturer adds the device registration information to the enrollment list in the Azure portal.
Device contacts the provisioning service endpoint set at the factory. The device passes the identifying information to the provisioning service to prove its identity.
The provisioning service validates the identity of the device by validating the registration ID and key against the enrollment list entry using standard X.509 verification (X.509).
The provisioning service registers the device with an IoT hub and populates the device's desired twin state.
The IoT hub returns device ID information to the provisioning service.
The provisioning service returns the IoT hub connection information to the device. The device can now start sending data directly to the IoT hub.
The device connects to IoT hub.
The device gets the desired state from its device twin in IoT hub.
2. Create and Configure DPS via Azure IoT Portal
2.1. Create an IoT Hub (if you do not have already)
Go to your Azure Portal: https://portal.azure.com, and sign in using your Azure account.
Click Create a resource
Click Internet of Things
Click IoT Hub
Fill out the form and click Create
Once created, head to the Overview tab and take a note of the "Hostname". That will be used later in the application (i.e., dps.hostname)
2.2. Create an IoT Hub Device Provisioning Service
Same as before: Azure Portal > Create a resource > Internet of Things
This time choose IoT Hub Device Provisioning Service
Fill out the required fields and click Create
2.3. Link the IoT Hub to your Device Provisioning Service
Click the DPS instance that you created (you can access it from All resources link to the left)
Click Linked IoT hubs
Click Add
Select your IoT hub and Save
2.4. Create a Certificate for your Device Provisioning Service
You need a .pem file that contains an intermediate or root CA X.509 certificate. We use OpenSSL here to create the CA cert:
Generate root key and X509 cert
Note: the validity for this cert is set to 10 years. Change if you want a longer/shorter lifetime
Press enter for default values
Create verification key:
2.5. Upload the Certificate to your Device Provisioning Service
Open your instance of Device Provisioning Service instance
Click Certificates
Click Add.
Give it a name of your choice in the Certificate Name field
Upload your certificate (root_cert.pem) and click Save
2.6. Verify the Certificate
Click the certificate you’ve just created
Click Generate Verification Code. That will generate a 48 characters length code. Take a note of it.
Using the code, create the verification cert:
Press enter to choose default parameters.
For "Common Name", use the verification code obtained above
Create the proof of possession certificate:
This will sign the verification.csr, that has the verification code as the Common Name, with the root private key.
Upload your verification certificate verificationCert.pem as a proof of possession, and click Verify
2.7. Create an Enrollment Group
Open your instance of Device Provisioning Service instance
Click Manage enrollments
Click Enrollment Groups
Click Add
Fill out the form and click Save
2.8. Take a note of your DPS details
Open your instance of Device Provisioning Service instance
Click Overview
Take note of the Global device endpoint and ID Scope. Those parameters will be used in the following steps.
3. Create a DMS Connector
Now you have created and configured your DPS, it is the time to create a “connector” and link it to your DPS instance
Notes:
For more about DMS connectors, please have a look at the tutorial here: https://dms.zentri.com/tutorial/connectors
This step assumes you have already a product created. If not, please follow the tutorial here: https://dms.zentri.com/tutorial/create-product
Go to the DMS: https://dms.zentri.com/
Click Products
Choose your product out of the list
Click Connectors
Click Create Connector
Fill out the form:
For Type, select Provision
For Endpoint, select Azure IoT Hub
For Provisioning Host, enter the Global device endpoint of your DPS (obtained above)
For ID Scope, enter the ID Scope for your DPS (obtained above)
For Certificate, paste in your generated certificate (e.g., root_private.pem obtained above)
For RSA Private Key, paste in your generated key (e.g., root_cert.pem obtained above)
Click Save
The created connector is linked to your product, and any device activated to this product can communicate with it.
4. Device side: Gecko OS Application
Note: Gecko OS example app source code is released as a part of Gecko OS SDK 4.1.11. Once you have the SDK downloaded, you can find it under: sdk\standard\wgm160p\4.1.11-7064\applications\gecko_os\cloud\dps_demo
Now you have a connector ready and DPS configured in Azure, it is the time to send a provisioning request from the device side to the DMS connector. DMS in turn sends the request to Azure and returns back the device certificate and key. Once device obtains the cert and key pair, it encrypts and stores them securely on the file system then using them for farther communication with Azure IoT Hub. The DPS and DMS connector are done at this stage
Note: This part assumes basic knowledge of development using Gecko OS. For more info, please head to the online doc:
https://docs.silabs.com/gecko-os/4/standard/latest/
https://docs.silabs.com/gecko-os/4/standard/latest/cmd/
https://docs.silabs.com/gecko-os/4/standard/latest/sdk/
Activate device to the product created above (since, it can use the connector). This is not done automatically in the example app and you need to do that using the standard dms_activate command. More here: https://dms.zentri.com/tutorial/activate-to-product
In Gecko OS, enable the DMS websocket to automatically start when the network is brought up (please see resources\settings.ini file where this setting is already enabled):
Configure the different application custom variables:
dps.connector: DMS connector code (make sure your device is activated)
dps.hostname: Hostname or IP address of the broker/server
dps.port: Port of the provisioning server/broker"
dps.ca_cert: CA cert filename used for TLS verification request
dps.key_filename: Filename used to store the client certificate (if provisioning succeeded)
dps.key_filename: Filename used to store the client key (if provisioning succeeded)
Configure the network credentials: wlan.ssid and wlan.passkey, then save all.
Now, issue the custom command dps_provision
Device establishes a secure websocket connection with DMS using its own device cert.
Device registers for DMS message responses
Once device connects to DMS websocket, app sends a provisioning request in the form:
{ request: 'provision', code: code }DMS gets the request (including the device UUID as an identifier), then talks to Azure to provision the device in IoT Hub
If successful, Azure replies back with the device cert/key pair
DMS responds to the provision request with the device cert/key pair. The response format looks like:
{ "assignedHub": "my-iot-hub.azure-devices.net", "deviceId": "ffffffffffffffffffffffffffffffffffffffff", "cert": "-----BEGIN CERTIFICATE-----\n<...>\n-----END CERTIFICATE-----", "key": "-----BEGIN RSA PRIVATE KEY-----\n<...>\n-----END RSA PRIVATE KEY-----" }Device retrieves the cert and key, then write them to the file system securely (files defined by dps.key_filename and dps.cert_filename)
Device disconnects
To verify the provisioning process, use the custom command dps_verify. This will use the obtained cert and key files, in addition to the configured CA cert to establish a TLS connection to the host defined by dps.hostname:dps.port
Later, when device wants to communicate with Azure IoT Hub, it establishes TLS connection using the client key and cert. That is done as the following:
For more details about Gecko OS TLS client: https://docs.silabs.com/gecko-os/4/standard/latest/networking-and-security#tls-client
Appendix:
The console log of the example app should look like:
WGM160P Power Consumption using Gecko OS (Setup and Results)
Introduction
In this article, we describe how to configure Gecko OS running on WGM160P to obtain the lowest current results.
If you are interested in WF200/WFM200, please refer to the article: How to do current measurements on WF(M)200
In this test, we used WGM160P mounted on WSTK, the default evaluation starer kit. For more info, please refer to: WGM160P Wi-Fi Module Starter Kit
The current measurement is averaged over 60 to 100 seconds (captured 1-minute after associating, or not in case of sleep/shutdown)
We use used Cisco Linksys WRT610N access point configured with 100ms beacon interval and default beacon duration
For the WLAN power saving move, we use used Alfa access point configured with beacon interval 102.4ms and 1ms duration (Cisco Linksys WRT610N used for the default, sleep, and shutdown measurements)
For more details on how to setup the Energy Profiler to detect WGM160P, please refer to the article: Configure AEM/Energy Profiler to work with WGM160P
The measurements below obtained for the current official release (at the time of writing this article), in addition to the new alpha and beta releases for coming Gecko OS 4.1
To get access to Gecko OS BETA, please issue the command: dfu_update -b 4.1.10 --multi
Note: do not use a “listen interval” higher than 3 to avoid potential issue with some Access Points.
Note: Listen interval higher than 0 uses DTIM skipping and so this could add jitters/delay on the packet arrival time.
Measurements
ON BOOTUP/DEFAULT
get wlan.mac
factory_reset <MAC_ADDRESS>
Gecko OS 4.0.18
Gecko OS 4.1.9 ALPHA
Gecko OS 4.1.10 BETA
16 mA
5.20 mA
5.17 mA (Figure 1)
UART & WLAN POWERSAVE
set wlan.powersave.mode 2
set uart.powersave.mode uart0:1,uart1:1
set system.powersave.wakeup_gpio_mask 0x1000000
set system.powersave.idle_timeout 250
set system.powersave.mode 2
set wlan.ssid LINKSYS
set wlan.passkey password
set broadcast.interval 0
uartu 0
nup
Beacon duration 1ms
Beacon duration 1ms
Beacon duration 1ms
* : Listen Interval set the number of DTIM beacon which will be skipped (not Received).
** : ping timeout possible because of delay on the packet arrival time
SLEEP
set uart.powersave.mode uart0:1,uart1:1
set system.powersave.wakeup_gpio_mask 0x1000000
set system.powersave.idle_timeout 250
set system.powersave.mode 2
uartu 0
Gecko OS 4.0.18
Gecko OS 4.1.9 ALPHA
Gecko OS 4.1.10 BETA
N/A
530 µA
530 µA (Figure 5)
SHUTDOWN
set system.shutdown.wakeup_gpio_mask 0x4004000
shutdown
Gecko OS 4.0.18
Gecko OS 4.1.9 ALPHA
Gecko OS 4.1.10 BETA
N/A
990 nA
940 nA (Figure 6)
Figures
Figure 1: ON BOOTUP/DEFAULT (Gecko OS 4.1.10)
Figure 2: UART/WLAN POWERSAVE (Gecko OS 4.1.10 LINKSYS DITM1)
Figure 3: UART/WLAN POWERSAVE (Gecko OS 4.1.10 LINKSYS DITM3)
Figure 4: UART/WLAN POWERSAVE (Gecko OS 4.1.10 LINKSYS DITM10)
Figure 5: SLEEP (Gecko OS 4.1.10)
Figure 6: SHUTDOWN (Gecko OS 4.1.10)
DMS & Gecko OS: Development vs Production Explained
Note: this app note below is also published on Gecko OS online docs here: https://docs.silabs.com/gecko-os/4/standard/latest/sdk/development/development-v-production
If you used Gecko OS for WGM160P, you must have heard about development vs production many times. The development and production terms are used across different topics and get confusing sometimes. This article explains the difference in detail and helps to understand the different use cases for these terms.
Development vs Production Device Credentials:
To communicate with Zentri Device Management Service (DMS), a device needs to establish a secure channel with the server. That is done using the device’s credentials. The device's updatable security credentials reside in a specific memory section of the device’s flash. This memory section will persist through Device Firmware Update (DFU). The credentials are programmed during manufacturing and updated during DFU if needed. These can be also flashed and replaced with development credentials as explained below. Without valid credentials (either production or development), a device cannot communicate with DMS.
Production Credentials:
Silicon Labs programs DMS credentials into the device during the manufacturing process (hence the term production credentials). Once programmed, the process makes sure to LOCK the device. Locking the device refers to “debug interface locking” which disables access to the internal flash and the Cortex-M4 core from the debug interface.
Unlocking the debug interface will erase those credentials along with the rest of the internal flash. That guarantees devices with unlocked debug interface cannot expose the production credentials at all. In other words, the device is considered compromised once it has its debug interface unlocked. We do not know what users used it for and it will live forever as a development device.
Development Credentials:
Once a device is unlocked, the production credentials are deleted (and never recovered). Now, how to use the device if you still need to work with DMS? You need to use development credentials. During development, the device is given development DMS credentials that expire after 30 days. This is done during the device setup step of development (using Gecko OS Studio or Gecko OS SDK). The credentials are re-renewed every time the device is setup again using Gecko OS Studio. Once credentials expire, the device will not be able to communicate with DMS (any update or query will fail with error 403/400).
In the final product, never ship non-locked devices to end users. Always make sure that the device is locked and programmed with production credentials. In other words, once the device is used for development once, never use it in a consumer product. Keep it for development and testing.
Devices come locked and pre-programmed with production credentials. To keep those during your production process, you should only program your devices via one of the methods below:
Over-The-Air (OTA) via the DMS, as explained here.
Using factory/offline DFU via the UART interface, as described here.
Development vs Production DMS Flow:
The second context that uses production and development terms is the production flow via DMS. In this case, we are distinguishing between a development and production product on DMS. The difference is highlighted below. Note that this context has nothing to do with the device credentials explained earlier.
Development Product:
This is the default, most commonly used product type used during the development cycle. Once you create a project in Gecko OS Studio, a development product is created on DMS. The product code always starts with your user account code (6-character length code, starting with 0). For example, 0ST3XD-AZURE_DEMO. Once you use the Gecko OS SDK/Studio to release a bundle, this linked product is used. More about bundle release (application deployment) is described in this tutorial.
You can also create a development product directly using DMS UI and either add a new bundle or copy it from another product you have access to. This is also explained in this tutorial.
To update your device’s firmware with a development product bundle, you will need to claim the device to your account, then activate it to the product using the product code. Once activated, you can pick any bundle published on this product. Latest released bundle is obtained via the “dfu_update” command, while you can choose a different bundle if you specify the bundle number using the -b argument.
If you have many products you have access to, you can easily move across different products via activating using the product code, then issuing the DFU update command.
Note that a DMS user account is limited to a number of devices that can be activated to development products. As explained earlier, this phase is only recommended for development and testing activities.
Production Product:
Once you are happy with the firmware you developed, it is the time to “productize” it. That means creating a production product and moving the bundle across. A production product is not linked to a DMS user, but to a DMS customer account. That is, it does not start with a user code but with customer code. A customer code is a 6-character length string you chose while creating a customer account. An example of a production product is SILABS-AZURE_DEMO. More about creating a customer account and linking it to your user account is explained here.
Production products can have an unlimited number of devices activated to it. The main differences introduced for production products are explained below:
You cannot use the product code anymore. You will have to use activation tokens to activate a device to production product. Also, you do not need to claim the device first. The reason here is that device is not “owned” by your user account anymore but associated to the customer account instead. If you have access to the customer account, you still have access to the device on DMS. More about activation tokens and how to obtain them is described here. Remember that a token is a secret key, and anyone that knows your activation token can use it to activate any device to your product and obtain a copy of your firmware binaries.
Devices cannot pick a random bundle to update using the -b parameter. The extra argument will be ignored, and only the latest released bundle that matches the device’s tag will be downloaded.
Devices activated to a production account can not reactivate to another product from the device’s side. In other words, you can issue the command “dms_activate ” only once using Gecko OS command API. Second activation will fail unless device is reset first (explained later). The reason here is that production devices are distributed to end users, and you do not want a user to change the device’s standard product (if you shipped the device as a “toaster”, you do not want anyone has access to the device’s terminal to change it to a “fridge”).
As an account owner, you can move devices across different products under the same customer account. This is from the DMS UI only though, and only the account admin can do that. The use case here is that if you wanted to upgrade the device from a “toaster” to a “toaster plus”, you can do that using the UI. You can also factory reset the device back to the platform product (SILABS-WGM160P) from the DMS UI.
Caution: once you factory-reset the device, you will lose access to the device and it needs to use the terminal to activate it again. You should not perform this factory reset to a device in field, or a device you do not have a physical access to.
The regular recommended DMS flow is to first use a development product to release your firmware. Evaluate and test the bundle on your development device. Once everything is alright, create a production product and clone this bundle across. Always activate fleet devices to a production product (using an activation token) before shipping.
Configure AEM/Energy Profiler to work with WGM160P
AEM/Energy Profiler is not enabled by default for WGM160P target (using WSTK). Until that is being enabled in Simplicity Studio, you can follow the instruction below:
1. Plug your target platform: WGM160P Wi-Fi® Module Starter Kit (SLWSTK6121A)
2. In Simplicity Studio right click on the "J-Link Silicon Labs" debug adapter and choose "Device Configuration":
3. Under the "Device hardware" tab change the "Target Part" to EFM32GG11B820F2048GM64 as shown below.
4. Click OK then launch Energy Profiler
5. Under "Quick Access" select "Start Energy Capture"
6. Choose the J-Link adapter then click OK.
Note:
There are two power domains on the STK. One for the WGM160P and peripherals, where the other is for the board controller (debugger, etc.). The Energy Profiler only measures the first one. Therefore the measurements are extremely close to the true power consumption of the WGM160P itself. Also note that the Energy Profiler circuit on the STK has a max reading of 95mA so it might max-out during Wi-Fi transmission.
If you want to get even more precise or more range you would need to use a scope or power analyzer to measure the current at resistor R616 or at J1 on the WGM160P radio board. See/request the board schematic and layout for reference.
WGM160P Certification Testing (using an example application provided in Gecko OS SDK)
WGM160P module is pre-certified for CE, FCC, ISED, KC South Korea, and Japan. For more information, please see:
https://www.silabs.com/community/wireless/wi-fi/knowledge-base.entry.html/2019/05/06/kba_wgm160p_rf_cert-QAcu
https://www.silabs.com/community/wireless/wi-fi/forum.topic.html/wgm160p_certifications-n4KK
If you are trying to re-certify the module, or the end product using Gecko OS, please have a look at the certification example app found in the SDK at ~\applications\gecko_os\test\certification. The purpose of this example is to provide the functionality needed for certification. Like all example apps you can clone it from Gecko OS studio. It is found under "Test Examples" as shown below:
Note: the test app referred below is based on Gecko OS 4.1.11
Please see below for the different variables and settings:
Variable
Commands
Abbreviated
Default
Comments
Channel
get/set wifi_test.channel <1 .. 14>
get/set wt c
1
Wi-Fi 2.4GHz channel (1 -> 14)
Test Mode
get/set wifi_test.mode
get/set wt m
tx_cw
Selects the activated test mode:
rx: received frames and count number of good or bad packets
tx_packet: transmit the frames in the mode selected according to other wifi_test settings
tx_cw: transmit a sinus wave signal at the selected frequency
Tx Protocol
get/set wifi_test.tx.protocol
get set wt t p
b
Wi-Fi protocol version to use
Period
get/set wifi_test.period <150 .. 65535>
get/set wt d
1000
Period in ms for reporting test results
Rate
get/set wifi_test.tx.rate [<10/20/55/11> / <6/9/12/18/24/36/48/54> / <0/1/2/3/4/5/6/7>]
get/set wt t r
10
Tx Rate / MCS
tx.ht_format
get/set wifi_test.tx.ht_format
get/set wt t t h
mm
High-throughput format: Mixed Mode or Green Field
tx.ifs
get/set wifi_test.tx.ifs <0 .. 255>
get/set wt t i
0
Inter-frame spacing in microseconds
tx.length
get/set wifi_test.tx.length <25 .. 4091>
get/set wt t l
25
Tx frame length
tx.number
get/set wifi_test.tx.number <0 .. 65535>
get/set wt t n
100
Number of frames to transmit, 0 = continuous
tx.tx_power
get/set wifi_test.tx.tx_power <-200 .. +300>
get/set wt t p o
20
Max TX packet mode output power
cw.freq1
get/set wifi_test.cw.freq1 <-31 .. +31>
get/set wt w f
0
CW Mode Frequency 1 Offset (step of 312kHz)
cw.freq2
get/set wifi_test.cw.freq2 <-31 .. +31>
get/set wt w r
0
CW Mode Frequency 2 Offset (step of 312kHz)
cw.mode
get/set wifi_test.cw.mode
get/set wt w m
single
CW Mode single or dual
coex.mode
get/set wifi_test.coex.mode
get/set wt x m
wlan
Radio Coex Mode
There is also a custom command to start the transmission or reception of frames: wifi_test start
Examples:
Get TX_PACKET 11n MCS7 continuously to RF2 output (test in conducted):
TX_PACKET 11g 54Mbps:
DSSS 11b 11Mbps
Stop TX after 100 frames and update the TX for rate MCS4 (if already in 11n):
TX stopped. Set tx.rate in MCS4 and then TX frames continuously
set wifi_test.tx.rate 4 set wifi_test.tx.number 0 wifi_test startGet CW signal to RF2 output:
WLAN backoff of 5dB on channel 6 for mod_group_5
RX_PACKET for 11bgn 20MHz signals on channel 7 on RF2
We get then every 5 seconds (wifi_test.period=5000µs) this Rx statistic report:
Frames received : 7764 Bad Frames : 451 Total PER : 0.0580 Throughput : 47870 Protocol Rate Frames PER SNR RSSI CFO 11B 1 0 0.0000 0.00 0 0 11B 2 0 0.0000 0.00 0 0 11B 5.5 0 0.0000 0.00 0 0 11B 11 0 0.0000 0.00 0 0 11G 6 0 0.0000 0.00 0 0 11G 9 0 0.0000 0.00 0 0 11G 12 0 0.0000 0.00 0 0 11G 18 0 0.0000 0.00 0 0 11G 24 0 0.0000 0.00 0 0 11G 36 0 0.0000 0.00 0 0 11G 48 0 0.0000 0.00 0 0 11G 54 0 0.0000 0.00 0 0 11N MCS0 0 0.0000 0.00 0 0 11N MCS1 0 0.0000 0.00 0 0 11N MCS2 0 0.0000 0.00 0 0 11N MCS3 0 0.0000 0.00 0 0 11N MCS4 0 0.0000 0.00 0 0 11N MCS5 0 0.0000 0.00 0 0 11N MCS6 0 0.0000 0.00 0 0 11N MCS7 7764 0.0580 22.61 -72 15The statistics are done on 5 seconds. In this example, the Wi-Fi source transmits only 802.11n MCS7 frames in the channel 7.
Please note when some packets are completely erroneous and not detected like a Wi-Fi frame then they are not counted in “Frames received” or “Bad Frames”.
This PER accuracy issue, it happens more when we are close or below the sensitivity level.
So in order to get an accurate PER, you have to compute it based on number of transmitted frames by the Wi-Fi source.
To stop this Rx mode with statistic report:
set wifi_test.mode tx_packet set wifi_test.tx.number 100 wifi_test startGecko OS Offline/Factory Device Firmware Update (DFU)
1. INTRODUCTION:
Factory DFU is intended to be used during factory programming (as opposed to in-field programming). Rather than cache DFU package files to extended flash, package files intended for internal flash are directly written. This allows for faster programming at the expense of reduced reliability. Factory programming is less 'reliable' as the internal flash is erased before the DFU package is fully validated. This is not recommended for the field as a bad DFU package could leave the Device in a non-functional state.
Note: This is an early implementation of the factory DFU process. Some changes on how the package is encrypted is currently under discussion and might affect the user experience. Feel free to use it for devices under development for now.
Disclaimer: the process explained below is a one-way process. Once "dfu_update --factory SILABS" command is invoked, there is no going back. The device will only boot into the Gecko OS bootloader until a GBL image is successfully programmed. Both the internal and extended flash memories are completely erased BEFORE the DFU is executed (the device credentials on internal flash persist). The device could be left in an unusable state should the DFU fail
2. DESCRIPTION:
In this method, multiple devices are updated with a single DFU package consisting of images to be programmed to specified flash locations.
Devices programmed with a Factory DFU cannot retain NVM variable settings or files. All existing NVM variable settings and files are erased from the device, other than the device credentials.
The DFU image/package is obtained once using DMS UI (coming soon), or RESTful API call as highlighted below.
The DFU package is generated for a certain product bundle. Version number will need to be specified in the request.
The request also should specify the ‘from product’ field. This is the product currently programmed on the target devices (for fresh devices, this is the SILABS-WGM160PK product)
Once package is transferred to the device, it is decrypted, and update process starts.
The RESTful request should be issued using a token of a user has access to both products
Device does not need to be connected to internet to receive the DFU package.
Device also does not need to be claimed to a certain user or activated to a certain product.
The package is delivered over serial interface using XMODEM protocol (1k blocks).
An executable is provided to transfer the DFU package over serial. You can use any other implementation of XMODEM-1K (explained farther below)
3. OBTAINING THE GBL PACKAGE
GBL file presents the binary package that will be used in the update procedure later.
The package can only be obtained through DMS. User can not build it using Gecko OS binaries, or any other method.
Until the UI on DMS side is ready, this RESTful API can be used. Here is the cURL request:
product_id: Replaced by ID of the product you want to update to – for example: bcbf4fd8-8564-4a7d-bdc2-bc553d69d4a6. You can get this ID from the URL when you head to the product page on DMS ( e.g., https://dms.zentri.com/products/bcbf4fd8-8564-4a7d-bdc2-bc553d69d4a6)
user_token: Replaced by user API Token obtained from DMS: (Profile -> API Tokens -> Issue API Token) – for example: RkxhQkdCRkEzWFNYxxxxxx
SILABS-WGM160PK: current product installed on the target device. Can be any product code, but generally SILABS-WGM160PK for any fresh modules never used before
0.0.1: bundle version number you need to update to
development: if device used earlier with GSS or SDK, this needs to be “development”. For production devices that are never used for development, this should be set to “production”. For more info regarding development vs production, please review this application note.
SILABS-WGM160PK-to-DFU-PACKAGE_0.0.1.gbl: Package GBL file name (use any name of your choice)
4. THE UPDATE PROCESS:
Connect your target device to your PC using the USB. Assuming evaluation board is used here, device will be detected as COM port
In case you are using the bare module, you will need to use a UART to USB converter connected to the modules UART pins (UART0 TX and UART0 RX). If you are using one of the evaluation boards, then use the USB connection directly.
Use the provided tool (attached as a zip file) to download the package to device – replace COMxx with the COM port detected:
Leave it running until operation completes successfully. You should see something similar to this:
At this stage, device is completely updated to the new firmware bundle. You can go ahead and start using your device is usual.
Note: the offline DFU procedure will intentionally put the device in machine format, where the command/response header is enabled. This will persist after a successful update, until device is physically unplugged and plugged again. Soft reboot will not set it back to human format. This makes it easier for the update tool to detect errors and parse different responses.
If you do not want to use the tool, you can use TeraTerm terminal to send the file over XMODEM. To do so:
Connect to the COM port detected by your PC
From the serial interface, issue the command: dfu_update --factory SILABS
Note: Once this command is invoked, there is no going back. The device will only boot into the Gecko OS bootloader until a GBL image is successfully programmed. Both the internal and extended flash memories are completely erased BEFORE the DFU is executed (the device credentials on internal flash persist). The device could be left in an unusable state should the DFU fail
Enter ‘start’ word then hit enter
Now, use TeraTerm to send the file over XMODEM (File -> Transfer -> XMODEM -> Send). Select the GBL file obtained earlier. Select the 1K check box at the dialog box before sending the file
It will take some time then reboot the device into the new updated bundle.
5. SEND RESULT TO DMS:
Once the DFU operation is completed, we will need to post the 'DFU Success' result back to DMS. Doing so will help DMS to know the current firmware bundle installed in device. In the future, if device requests over-the-air (OTA) update, DMS can provide the right bundle based on the devices’ status.
To do that, you will need to specify your user token as an optional parameter:
Where user_token is the user API Token obtained from DMS: (Profile -> API Tokens -> Issue API Token) – for example: RkxhQkdCRkEzWFNYxxxxxx
If this token optional argument is not passed, this step is skipped.
Note: In case you are using this setup offline and there is no internet connection to submit the result while updating, you will need submit the results manually later using the API demonstrated in the cURL request (in this case, do not pass the token optional argument):
base64_data: the DFU response printed on completion of the DFU process. This is presented in base64 format. It can be obtained using the Gecko OS command “dfu_response”. For example: gqdwYXlsb2FkxgAABPv5qB2r4xDINzqpws1ZYFz4KLqXNpZ25...etc...1346vtxOx8v5mpEZn1YcYr4mZ5u9Tw3X9ME0E2GzOviIN0RtPEA7qrYzISZmR+82g==
user_token: Replaced by user API Token obtained from DMS: (Profile -> API Tokens -> Issue API Token) – for example: RkxhQkdCRkEzWFNYxxxxxx
Same can be done using the msgpack binary data returned by the provided tool as well. You will notice once DFU operation successes, there is a bin file created in the working directory named with device UUID. This file contains the same base64 DFU result but in binary msgpack format. It can also be generated using Gecko OS command “dfu_response -m”. The cURL call to use this binary file is:
EADE2FF3D61F482913FA5B5BDxxxxxxxxxxxxxxx.bin: the DFU response in msgpack format obtained using the DFU tool as explained above.
user_token: Replaced by user API Token obtained from DMS: (Profile -> API Tokens -> Issue API Token) – for example: RkxhQkdCRkEzWFNYxxxxxx
6. VERIFICATION:
To verify that everything is working as expected, please make sure of these two steps (verify only one random device, as rest should behave similarly):
The current version on device after DFU is matching what you requested first. This can be checked using the command “ver” on Gecko OS command interface.
From DMS UI, you should be able to locate the device using its uuid and verify that current firmware version installed matches the version obtain in step 1 above.
For any question or farther clarification, please comment below or go ahead and create a technical support case using Silicon Labs support portal: https://www.silabs.com/support