Pull request project-chip#41: OTA documentation

Merge in WMN_TOOLS/matter from ota_documentation to silabs

Squashed commit of the following:

commit 9d84675d5ce8fb24df2fa993e14b1c8d97e314d4
Author: Mathieu Kardous <[email protected]>
Date:   Mon Aug 15 16:08:44 2022 -0400

    Address PR comments

commit 7623e3aca7b9c654c15cf0e60d3620e149ca0bcd
Author: Sergei Lissianoi <[email protected]>
Date:   Sun Aug 14 16:30:36 2022 -0400

    Add images to the bootloader document

commit 58d719d433eb82855d957bb76daa9125c1593b56
Author: Sergei Lissianoi <[email protected]>
Date:   Sun Aug 14 16:14:08 2022 -0400

    Add the OTA bootloader document

commit 89e1aed977acfb49ff9d1f413accf9f81f7b6cad
Author: Sergei Lissianoi <[email protected]>
Date:   Sun Aug 14 15:53:24 2022 -0400

    Update the top level doc with the OTA doc link

commit dc7458dd78d1dff07fb768a312a2aa1325f06cf9
Author: Sergei Lissianoi <[email protected]>
Date:   Sun Aug 14 15:47:10 2022 -0400

    Fix formatting

commit 3a2c5020be4a3107e2ed2a46c48bd1cce641f3c6
Author: Sergei Lissianoi <[email protected]>
Date:   Sun Aug 14 15:44:14 2022 -0400

    Fix formatting

commit 59f7bdae5780a88e9a842c1785e5dd63571a382e
Author: Sergei Lissianoi <[email protected]>
Date:   Sun Aug 14 15:38:00 2022 -0400

    Add OTA user guide document

docs/silabs/README.md

@@ -27,8 +27,9 @@
 
     1. [How to Flash a Silicon Labs Device](general/FLASH_SILABS_DEVICE.md)
     2. [How to Find Your Raspberry Pi](general/FIND_RASPI.md)
-    3. [Silicon Labs Matter Commit Hashes](general/COMMIT_HASHES.md) <br><br>
-
+    3. [Silicon Labs Matter Commit Hashes](general/COMMIT_HASHES.md)
+    4. [OTA Software Update](general/OTA_SOFTWARE_UPDATE.md) <br><br>
+
 5. Frequently Asked Questions (FAQ)
     - [Thread FAQ](thread/FAQ.md)
     - [Wifi FAQ](wifi/FAQ.md)

docs/silabs/general/OTA_BOOTLOADER.md

@@ -0,0 +1,79 @@
+# Creating Gecko Bootloader for Use in Matter OTA Software Update
+
+The Matter OTA Software Update functionality on EFR32 devices requires the use of a Gecko Bootloader built with correct configuration parameters. The key parameters are the storage slot size and (in case of internal storage) storage slot address. The current document lists the steps required to build the Gecko Bootloader for Matter OTA Update and discusses the configuration parameter selection. For a detailed discussion of Gecko Bootloader refer to _UG489: Silicon Labs Gecko Bootloader User's Guide for GSDK 4.0 and Higher_.
+
+The Gecko Bootloader is built with Silicon Labs Simplicity Studio. These instructions assume that you have installed Simplicity Studio 5, the Simplicity Commander tool (installed by default with Simplicity Studio), the GSDK and associated utilities, and that you are familiar with generating, compiling, and flashing an example application in the relevant version.
+
+## Bootloader Project In Studio
+### Creating the Project
+In Simplicity Studio click on Project->New->Silicon Labs Project Wizard to create a new project. Select the correct Target Board, SDK and the Toolchain. For Matter 1.0 it is recommended that the bootloader is built with GSDK 4.1. 
+
+In the next screen select the example project the bootloader will be based on. For a bootloader using external storage select "Bootloader SoC SPI Flash Storage (single image with slot size of 1024K)". For a bootloader using internal storage select "Bootloader - SoC Internal Storage (single image on 512kB device)"
+
+### Configuring Storage Components and Parameters
+In the newly created project select the project's .slcp file, click the "Software Components" tab, and select Platform->Bootloader->Storage. In the Bootloader Storage Slot component (it should be already installed) configure Slot 0's Start Address and Slot size.
+
+-   For external storage bootloaders the Start Address should be 0 and Slot size should be 1048576 -- both values are set by default
+-   For internal storage bootloaders see the "Internal Bootloader: Image Size, Selecting Storage Slot Address and Size" section below 
+In the Common Storage component leave the "Start address of bootload info" at 0. 
+
+### Configuring Other Components
+It is recommended to install the "GBL Compression (LZMA)" component under Platform->Bootloader->Core: this allows the bootloader to handle compressed GBL files. This component is required for internal storage bootloaders.
+
+At this point the project contains all the components necessary to support the Matter OTA Software Update functionality. Other components can now be added to support additional features such as Secure Boot. Refer to _UG489: Silicon Labs Gecko Bootloader User's Guide for GSDK 4.0 and Higher_  for the description of various Bootloader features and the steps to enable them. 
+
+### Building and Flashing the Bootloader
+Build the project by clicking on the hammer icon in the Studio toolbar. Flash the bootloader to the board using the "Upload Application" option from the Debug Adapters view. 
+
+## Internal Bootloader: Image Size, Selecting Storage Slot Address and Size  
+The internal storage bootloader for Matter OTA software update is supported on MG24 boards only. In this use case both the running image and the downloadable update image must fit on the internal flash at the same time. This in turn requires that both images are built with a reduced feature set such as disabled logging and Matter shell (see [here](./OTA_SOFTWARE_UPDATE.md#Internal-Storage-Bootloader) for the list of features). Using LZMA compression when building the GBL file further reduces the downloaded image size.
+
+When building an internal storage bootloader the two key configuration parameters are the Slot Start Address and Slot Size in the Bootloader Storage Slot component. The storage slot must not overlap with the running image and the NVM section of the flash. In other words, the slot start address must be greater than the end of the running image address and the sum of the start address and the slot size must be less than the address of the NVM section.
+
+![Internal Flash Layout](./images/InternalFlashLayout.png)
+
+The simplest way to get the relevant addresses for the running image and NVM is by using the Simplicity Commander tool:
+
+-   Build the running image for the Matter application
+-   Erase the chip and flash the running image to it (For example: use Simplicity Studio's Debug Adapters view context menu to flash the application image and some bootloader valid for the device board. Make sure to select the "Erase chip before uploading image" option).
+-   In Simplicity Commander, select Device Info -> Flash Map. The blank area in the middle of the flash (between the running image in the beginning and NVM at the end) is available for the bootloader storage slot. Each block represents a flash page (8K on MG24 boards). Hovering the mouse over a block shows the block's start and end address.
+-   Set the Slot Start Address to be the address of the first available block. Calculate the Slot Size to be the difference between the end address of the last free block and the Slot Start Address. The Slot Size must be greater that the size of the GBL file for the update image.
+-   (Optional) It might be advisable to set the Slot Start Address to the beginning of the second or third available block to account for potential growth of the application image -- this way the bootloader won't have to be reconfigured for every increase in the image size. The storage slot must still be able to accommodate the GBL image for the update.
+Another way to calculate the Storage Slot parameters is by examining the application's .map file:
+
+-   Build the running image for the Matter application
+-   In the application .map file find the highest address preceding the .data section, round it up to align on the 8K page boundary (e.g.  0x00000000080f1704 would round up to 0x00000000080f2000) and then add 0x2000 get the next page block address -- the result would be the Slot Start Address. The address of the .nvm section in the .map file is the end of the space available for the Storage Slot. The Slot Size is the difference of the .nvm address and the Slot Start Address.
+
+## Example
+This example is for an internal storage bootloader for the Matter lighting app on BRD4186C.
+
+-   Build the application disabling all optional features 
+
+           $ ./scripts/examples/gn_efr32_example.sh examples/lighting-app/efr32/ out/lighting-app BRD4186A chip_detail_logging=false chip_automation_logging=false chip_progress_logging=false is_debug=false show_qr_code=false chip_build_libshell=false enable_openthread_cli=false chip_openthread_ftd=true
+
+
+Build the GBL file for the update image and note its size
+
+           $ commander gbl create --compress lzma ~/chip/connectedhomeip/out/lighting-app/BRD4186A/chip-efr32-lighting-example.gbl --app ~/chip/connectedhomeip/out/lighting-app/BRD4186A/chip-efr32-lighting-example.s37
+
+           $ ls -la out/lighting-app/BRD4186A/chip-efr32-lighting-example.gbl
+           451176 Jul 19 16:39 out/lighting-app/BRD4186A/chip-efr32-lighting-example.gbl
+
+
+-   Flash the application image, bootloader (pre-built BRD4186C bootloader binary from https://github.com/SiliconLabs/sdk_support/tree/main/matter/efr32/bootloader_binaries), erase the flash.
+
+![Erase Flash](./images/ApplicationUploadEraseFlash.png)
+
+
+
+-   In Simplicity Commander display the flash map
+![Flash Map](./images/CommanderFlashMap.png)
+
+
+
+-   The address of the first available page is 0x080b8000, the end address of the last available block is 0x08172000. This means you can set the Slot Start Address to 0x080b8000 and the Slot Size to 761856 (761856 = 0x08172000 - 0x080b8000). The slot size is sufficient for our GBL file (451176 bytes)
+-   Create a project base on the "Bootloader - SoC Internal Storage (single image on 512kB device)" example. Configure the Bootloader Storage Slot component and set Slot Address and Slot Size.
+![StudioProject](./images/StudioProject.png)
+
+-   Enable the "GBL Compression (LZMA)" component.
+-   Build the project

docs/silabs/general/OTA_SOFTWARE_UPDATE.md

@@ -0,0 +1,151 @@
+# Matter Software Update with EFR32 Example Applications
+
+The Over The Air (OTA) Software Update functionality is enabled by default
+for all of the EFR32 example applications. Its inclusion in an application
+is controlled by the `chip_enable_ota_requestor` compile flag.
+
+## Running the OTA Download Scenario
+
+-   For Matter with OpenThread: Bring up the OpenThread Border Router as
+    discussed in examples/lighting-app/efr32/README.md and get its operational
+    dataset.
+
+-   On a Linux or Darwin platform build the chip-tool and the ota-provider-app
+    as follows:
+
+           
+           scripts/examples/gn_build_example.sh examples/chip-tool out/
+           scripts/examples/gn_build_example.sh examples/ota-provider-app/linux out/debug chip_config_network_layer_ble=false
+          
+
+-   Build or download the Gecko Bootloader binary. Follow the instructions in
+    [Creating the Bootloader for Use in Matter OTA](OTA_BOOTLOADER.md). For the bootloader
+    using the external flash select the "external SPI" bootloader type
+    configured with a single slot of at least 1000 KB. For the bootloader using
+    the internal flash see the Internal Storage Bootloader section below.
+    Pre-built binaries for some configurations are available here:
+    [bootloader_binaries](https://github.com/SiliconLabs/sdk_support/tree/main/matter/efr32/bootloader_binaries)
+
+-   Using the commander tool, upload the bootloader to the device running the
+    application.
+
+-   Create a bootable image file (using the Lighting application image as an
+    example):
+
+     
+           commander gbl create chip-efr32-lighting-example.gbl --app chip-efr32-lighting-example.s37
+     
+
+-   Create the Matter OTA file from the bootable image file:
+
+     
+           ./src/app/ota_image_tool.py create -v 0xFFF1 -p 0x8005 -vn 2 -vs "2.0" -da sha256 chip-efr32-lighting-example.gbl chip-efr32-lighting-example.ota
+     
+
+-   In a terminal start the Provider app and pass to it the path to the Matter
+    OTA file created in the previous step:
+
+           
+           rm -r /tmp/chip_*
+           ./out/debug/chip-ota-provider-app -f chip-efr32-lighting-example.ota
+           
+
+-   In a separate terminal run the chip-tool commands to provision the Provider:
+
+           
+           ./out/chip-tool pairing onnetwork 1 20202021
+           ./out/chip-tool accesscontrol write acl '[{"fabricIndex": 1, "privilege": 5, "authMode": 2, "subjects": [112233], "targets": null}, {"fabricIndex": 1, "privilege": 3, "authMode": 2, "subjects": null, "targets": null}]' 1 0
+           
+
+-   If the application device had been previously commissioned, hold Button 0 for
+    six seconds to factory-reset the device.
+
+-   In the chip-tool terminal enter:
+
+           
+           ./out/chip-tool pairing ble-thread 2 hex:<operationalDataset> 20202021 3840
+           
+
+where operationalDataset is obtained from the OpenThread Border Router.
+
+-   Once the commissioning process completes enter:
+
+           
+           ./out/chip-tool otasoftwareupdaterequestor announce-ota-provider 1 0 0 0 2 0
+           
+
+-   The application device will connect to the Provider and start the image
+    download. Once the image is downloaded the device will reboot into the
+    downloaded image.
+
+## Internal Storage Bootloader
+
+Internal storage bootloader for Matter OTA software update is supported on MG24
+boards only. In this use case both the running image and the downloadable update
+image must fit on the internal flash at the same time. This in turn requires
+that both images are built with a reduced feature set such as disabled logging
+and Matter shell. The following set of compile flags leaves out all the optional
+features and results in the minimal image size:
+
+           
+           chip_detail_logging=false chip_automation_logging=false chip_progress_logging=false is_debug=false show_qr_code=false chip_build_libshell=false enable_openthread_cli=false chip_openthread_ftd=true
+           
+
+Using LZMA compression when building the .gbl file ( passing `--compress lzma`
+parameter to the `commander gbl create` command) further reduces the downloaded
+image size.
+
+When building an internal storage bootloader the two key configuration
+parameters are the Slot Start Address and Slot Size in the Bootloader Storage
+Slot component. The storage slot must not overlap with the running image and the
+NVM section of the flash. In other words, the slot start address must be greater
+than the end of the running image address and the sum of the start address and
+the slot size must be less than the address of the NVM section. The simplest way
+to get the relevant addresses for the running image and NVM is by using
+the Silicon Labs `Simplicity Commander` (Device Info->Main Flash->Flash Map).
+
+The pre-built bootloader binaries are configured with slot start address of
+0x080EC000 and slot size of 548864
+
+## Managing the Software Version
+
+In order for the Provider to successfully serve the image to a device during the
+OTA Software Update process the Software Version parameter that the .ota file
+was built with must be greater than the
+CHIP_DEVICE_CONFIG_DEVICE_SOFTWARE_VERSION parameter set in the application's
+`CHIPProjectConfig.h` file. The Software Version parameter is set by the `-vn`
+parameter passed to the `ota_image_tool.py create` command. For example, if the
+application's running image was built with
+CHIP_DEVICE_CONFIG_DEVICE_SOFTWARE_VERSION set to 1 and if the `.ota` file is
+built with `-vn 2` then the Provider will serve the update image when requested.
+
+In order for the OTA Software Update subsystem to consider an update to be
+successful and for the NotifyUpdateApplied command to be transmitted the
+CHIP_DEVICE_CONFIG_DEVICE_SOFTWARE_VERSION in the updated image must exceed the
+software version of the running image (continuing the above example, the image
+for the update must be built with CHIP_DEVICE_CONFIG_DEVICE_SOFTWARE_VERSION set
+to 2).
+
+## Managing the Vendor and Product ID
+
+Starting the ota-provider-app with the --otaImageList command line option allows
+the user to supply a JSON file specifying the Software Version, Vendor and
+Product ID that identify the image served by the Provider, see
+[ota-provider-app](../../examples/ota-provider-app/linux/README.md)
+
+Example provider configuration file:
+
+
+        { "foo": 1, // ignored by parser
+          "deviceSoftwareVersionModel":
+          [
+           { "vendorId": 65521, "productId": 32773, "softwareVersion": 1, "softwareVersionString": "1.0.0", "cDVersionNumber": 18, "softwareVersionValid": true, "minApplicableSoftwareVersion": 0, "maxApplicableSoftwareVersion": 100, "otaURL": "chip-efr32-lighting-example.ota" }
+          ]
+        }
+
+
+## Additional Info
+
+Developers can find more resources on
+[Silicon Labs Matter Community Page](https://community.silabs.com/s/article/connected-home-over-ip-chip-faq?language=en_US)
+.