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’ filed. This is the product currently programmed on the target devices (for fresh devices, this is the SILABS-WGM160P 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. THE UPDATE PROCESS:

1. Until the UI on DMS side is ready, this RESTful API can be used. Here is the cURL request:

curl -X POST https://dms.zentri.com/api/products/product_id/dfu/0.0.1 -H "Authorization: Bearer user_token" -H "Content-Type: application/json" -d "{ \"allowed\": {\"product\": \"SILABS-WGM160P\"}, \"package_type\": \"factory\", \"cred_type\":\"development\"}" -o SILABS-WGM160P-to-DFU-PACKAGE_0.0.1.gbl

• product_id: Replaced by ID of the product you want to update to – for example: 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-WGM160P: current product installed on the target device. Can be any product code, but generally SILABS-WGM160P 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”

• SILABS-WGM160P-to-DFU-PACKAGE_0.0.1.gbl: Package GBL file name (use any name of your choice) 

2. Connect your target device to your PC using the USB. Assuming evaluation board is used here, device will be detected as COM port

Note: 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.

3. Use the provided tool (attached as a zip file) to download the package to device – replace COMxx with the COM port detected:

gecko_os_dfu.exe COMxx SILABS-WGM160P-to-DFU-PACKAGE_0.0.1.gbl

4. Leave it running until operation completes successfully. You should see something similar to this:

gecko_os_dfu.exe COM21 SILABS-WGM160P-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-WGM160P-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 EADE2FF3D61F482913FA5B5BDxxxxxxxxxxxxxxx.bin

+----------------------------------------------------------------------------+
|                        DEVICE UPDATED SUCCESSFULLY                         |
+----------------------------------------------------------------------------+

5. If you do not want to use the tool, you can use TeraTerm terminal to send the file over XMODEM. To do so:

   1. Connect to the COM port detected by your PC

   2. 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

   3. Enter ‘start’ word then hit enter

   4. 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

   5. It will take some time then reboot the device into the new updated bundle.

4. 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:

gecko_os_dfu.exe <com#> <gbl_file> --token <user_token>

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):

curl -X POST https://dms.zentri.com/api/dfu/result -H "Content-Type: text/plain" -H "Authorization: Bearer user_token" -d "base64_data"

• 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:

curl -X POST https://dms.zentri.com/api/dfu/result -H "Content-Type: application/octet-stream" -H "Authorization: Bearer user_token" --data-binary "@EADE2FF3D61F482913FA5B5BDxxxxxxxxxxxxxxx.bin"

• 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

5. 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):

1. 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.

2. 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

Platform:

Using Gecko OS 2.1/2.0 or ZentriOS 1.5, or any earlier versions on AMW007/AMW037

Introduction:

As reported by many customers, rrror 0x7200 is returned when trying to establish TLS connection with 'some' servers. The error is caused by TLS handshaking failure. It is a known issue, and we have a fix for it. Please read below.

Root cause:

A TLS connection to a server that sends fragment sizes larger than 4K fails. The connection may fail during TLS handshaking, but it may fail at any time after connection if the server sends a fragment larger than 4K.

That is a known issue in Gecko OS 2.1 and earlier (also in ZentriOS 1.5 and earlier). Please see the known issues in the release notes here:

https://docs.silabs.com/gecko-os/2/amw007-w00001/latest/release-notes#known-issues

Solution:

We just released BETA Gecko OS 2.2.9 that has fixes for the 4K issue discussed above. To get access to this release, please issue the command 'ota -b 2.2.9'.
Kindly note that this is a BETA firmware (when this article is published), and once we collect all the feedback from waiting customers, will flip this to release. Beta releases should only be used for test and verification, not for mass production.

Also discussed here:

https://www.silabs.com/community/wireless/wi-fi/forum.topic.html/amw007_error_withtl-CIId

https://www.silabs.com/community/wireless/wi-fi/forum.topic.html/amw-037_https_reques-XgAj

Depending on WGM160P part number chosen by customer, WGM160P features or not an integrated chip antenna.

The WGM160P is certified for FCC/ISED and CE with the integrated antenna (see section 4.7 of the datasheet) or with an external antenna (See section 11.1 of the datasheet https://www.silabs.com/documents/login/data-sheets/wgm160p-datasheet.pdf). The WGM160P certification ID is provided in the datasheet so that certificates can directly be downloaded from the web (See section 11 of the datasheet).

The external antenna used for certification on RF port is 50 ohms connectorized coaxial dipole antenna with maximum gain of 2.14dBi, achieving at least -10dB return loss over WiFi frequency band.  An example of such external antenna, is the Pulse Part Number W1030.

Any external antenna of the same kind and with equal or less gain and at least same -10dB VSWR over the WiFi frequency band should be fine and should not void FCC/ISED certifications as long as spot-check testing is performed to verify that no performance changes compromising compliance have been introduced.
Any other antenna (such as a chip antenna, a PCB trace antenna or a patch) will require the customer to do some testing and apply for a C2PC (Class 2 Permissive Change) as indicated by the customer’s TCB (Telecommunication Certification Body).

With CE, anyway, customer has to perform certification test with the end-product.

You could find some explanations in the section 10.3 Power On, Reset, and Boot in the WF200 datasheet :  
https://www.silabs.com/documents/login/data-sheets/wf200-datasheet.pdf

Moreover there is also some details in https://www.silabs.com/documents/login/user-guides/ug382-wf200-hardware-design-ug.pdf in section 4,.

When device is not supplied yet, pin RESETn shall be set to LOW and No HIGH voltage is expected to be applied to input pin LP_CLK.
Once power supplies have settled, a delay of 100µs is recommended before releasing pin RESETn to HIGH.
When powering down the device, it is recommended to set RESETn pin back to LOW before shutting down its power supplies. 

The power down step sets the WF(M)200 in standby mode according to these two ways below:

• Our lower MAC API command SHUT_DOWN allows to put the chip in standby mode.
• Alternative way is to assert RESETn pin low, at the expense of slightly higher current consumption due to the internal 43kohms typ. pull-up resistor.

WFX Linux driver parameters are accessible under /sys/module/wfx/parameters/

sudo tree /sys/module/wfx/parameters/

/sys/module/wfx/parameters/
├── gpio_reset
├── gpio_wakeup
└── power_mode

Each parameter can be checked

sudo cat /sys/module/wfx/parameters/gpio_reset
-2
sudo cat /sys/module/wfx/parameters/gpio_wakeup
-2
sudo cat /sys/module/wfx/parameters/power_mode
0

These parameters match those listed in the modinfo wfx parameters description

parm: gpio_reset:gpio number for reset. -1 for none. (int)
parm: gpio_wakeup:gpio number for wakeup. -1 for none. (int)
parm: power_mode:Force power save mode. 0: Disabled, 1: Allow doze, 2: Allow quiescent (int)

Possible values

• -2 (default): use values set in device tree
• -1: none (GPIO unused)
• any positive value: GPIO number as it would be set in the device tree

To check which GPIOs are currently allocated, use sudo cat /sys/kernel/debug/gpio

Typical result when using WF(M)200 in SPI mode

GPIOs 0-53, platform/3f200000.gpio, pinctrl-bcm2835:
 gpio-12 ( |wakeup ) out lo
 gpio-13 ( |reset ) out hi
GPIOs 100-101, platform/soc:virtgpio, brcmvirt-gpio, can sleep:
 gpio-100 ( |? ) out lo

Above, the 'wakeup' and 'reset' names match the names listed in the modinfo wfx parameters description:

parm: gpio_reset:gpio number for reset. -1 for none. (int)
parm: gpio_wakeup:gpio number for wakeup. -1 for none. (int)
parm: power_mode:Force power save mode. 0: Disabled, 1: Allow doze, 2: Allow quiescent (int)

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:

1. Device manufacturer adds the device registration information to the enrollment list in the Azure portal.
2. Device contacts the provisioning service endpoint set at the factory. The device passes the identifying information to the provisioning service to prove its identity.
3. 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).
4. The provisioning service registers the device with an IoT hub and populates the device's desired twin state.
5. The IoT hub returns device ID information to the provisioning service.
6. The provisioning service returns the IoT hub connection information to the device. The device can now start sending data directly to the IoT hub.
7. The device connects to IoT hub.
8. 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

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.

openssl req -x509 -newkey rsa:2048 -keyout root_private.pem -nodes -days 3650 -out root_cert.pem

• Press enter for default values
• Create verification key:

openssl genrsa -out verification.key 2048   

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:

openssl req -new -key verification.key -out verification.csr

• Press enter to choose default parameters.
• For "Common Name", use the verification code obtained above
• Create the proof of possession certificate:

openssl x509 -req -in verification.csr -CA root_cert.pem -CAkey root_private.pem -CAcreateserial -out verificationCert.pem -days 1024 -sha256

• 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:

1. For more about DMS connectors, please have a look at the tutorial here: https://dms.zentri.com/tutorial/connectors
2. This step assumes you have already a product created. If not, please follow the tutorial here: https://dms.zentri.com/tutorial/create-product

• Then, 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 project is attached for reference

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:

1. https://docs.silabs.com/gecko-os/4/standard/latest/
2. https://docs.silabs.com/gecko-os/4/standard/latest/cmd/
3. https://docs.silabs.com/gecko-os/4/standard/latest/sdk/

• Activate device to the product created above (since, it can use the connector): https://dms.zentri.com/tutorial/activate-to-product
• In Gecko OS, enable the DMS websocket to automatically start when the network is brought up:

set dms.auto_start_enabled 1

• 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
• Device disconnects
• 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

• For more details about Gecko OS TLS client:

https://docs.silabs.com/gecko-os/4/standard/latest/networking-and-security#tls-client

The BRD8022A provides a way to do current measurement (the same way is possible with the BRD8023A for WFM200).

The snapshot below provides the top overview of the BRD8022A board where U1 is the WF200:

In the blue circle, there is a way to do current measurement of the WF200. The schematic of this part is described below :

The R616 is a 0.1 Ohm resistor which connects the VMCU with the VMCU_NCP (WF200).
The J1 could be used to solder a HE10 connector (2.54mm) useful to do measurements.
So using R616 and J1, there are two ways to do WF200 current measurements during Tx, Rx or averaged on DTIM3:

• using a Voltmeter on J1-1 and J2-2, you could monitor the R616 voltage and then compute the current consumption.
• using a Ampere meter in serial between J1-1 and J1-2 after removing the R616 resistor. 

Removing the R616 resistor, you could alternatively use a monitored power supply using J1, like described in the snapshot below:

We recommend this way, if you want to measure the average lowest current consumption of 22uA during the sleep state.

To better understand the current consumption provided in the WF200 datasheet, I recommend to read the following KBA : https://www.silabs.com/community/wireless/wi-fi/knowledge-base.entry.html/2019/03/05/kba_wfx200_dtim3-tmpo

Moreover, to get the average sleep current consumption of 22uA, you should :

• use the SPI interface because with the Raspberry Pi, the SDIO clock is not switched off  during the sleep state (this increases the current consumption).
• remove the SDIO/SPI pull-up resistors highlighted in yellow in the above top view (these pull-up are not needed with the Raspberry Pi because the host has internal pull-up on the interface like required by the standard).

In order to do WF200 current measurements in Tx, Rx or in sleep state, we have used the Keysight DC power analyzer N6705C set in 2-wire sensing for short supply cables (voltage is monitored at supply output terminals) else set in in 4-wire sensing for longer twisted supply cables (voltage is monitored at the load and automatically compensate for any voltage drop within supply cables).

In the datasheet, the current consumption of 337 μA in DTIM3 provides the WFx200 average current consumption when there is no TX/RX of data frame (only receiving Beacon with the DTIM interval and using the sleep state).
So with this consumption, the WFx200 stays associated  with the Wi-Fi Access Point ready to transmit or receive data frame and it goes in sleep state between two Rx beacons with a current consumption of only 22 μA.

The 337 μA current are measured in DTIM3 when the WFX200 receives only one over 3 beacons with a beacon interval of 102ms and a beacon time duration of 1ms.

The Platform Data Set (PDS) file is used by the customer to fine tune the WF(M)200 usage according to his design or/and application.

When the TEST_FEATURE_CFG field is in the PDS file then it allows to do RF tests with the WFx200 (without WLAN protocol).

The test feature is available only if the power save mode is disabled. To disable the power save mode with Linux : sudo iw dev wlan0 set power_save off
You could get some details on this at the end of the README.md with an example enabling RF Tx in CW (tone) on channel 11:
https://github.com/SiliconLabs/wfx-firmware/tree/master/PDS#test_featurepdsin-minimal-file-for-continuous-tx-testing

If using the Linux Lower MAC driver, we have the possibility to update some part of the PDS, on fly (for example to modify the test_feature channel):
https://github.com/SiliconLabs/wfx-firmware/tree/master/PDS#sending-a-pds-file-during-execution

On Linux (using the Lower MAC driver), we also provide python scripts allowing to automate RF measurements . Please read the readme in: https://github.com/SiliconLabs/wfx-linux-tools/tree/master/test-feature

With the Full MAC, it is also possible to update the PDS (using the API) and so to do RF measurements.