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
Gecko 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