Sergei Lissianoi | 510069d | 2022-03-14 17:12:04 -0400 | [diff] [blame] | 1 | # Matter Software Update with EFR32 example applications |
| 2 | |
| 3 | The Over The Air (OTA) Software Update functionality can be added to any of the |
| 4 | EFR32 example applications by passing the `chip_enable_ota_requestor=true` |
| 5 | option to the build script. This option is supposed to be enabled by default for |
| 6 | all of the EFR32 example applications. |
| 7 | |
| 8 | ## Running the OTA Download scenario |
| 9 | |
| 10 | - For Matter with OpenThread: Bring up the OpenThread Border Router as |
CuRahman | b989fb3 | 2024-02-12 22:33:47 -0500 | [diff] [blame] | 11 | discussed in examples/lighting-app/silabs/README.md and get its operational |
Sergei Lissianoi | 510069d | 2022-03-14 17:12:04 -0400 | [diff] [blame] | 12 | dataset. |
| 13 | |
| 14 | - On a Linux or Darwin platform build the chip-tool and the ota-provider-app |
| 15 | as follows: |
| 16 | |
| 17 | scripts/examples/gn_build_example.sh examples/chip-tool out/ |
| 18 | scripts/examples/gn_build_example.sh examples/ota-provider-app/linux out/debug chip_config_network_layer_ble=false |
| 19 | |
Sergei Lissianoi | af5f7c9 | 2022-07-18 13:19:54 -0400 | [diff] [blame] | 20 | - Build or download the Gecko Bootloader binary. Follow the instructions in |
| 21 | "UG266: Silicon Labs Gecko Bootloader User’s Guide". For the bootloader |
| 22 | using the external flash select the "external SPI" bootloader type |
| 23 | configured with a single slot of at least 1000 KB. For the bootloader using |
| 24 | the internal flash see the Internal Storage Bootloader section below. |
Sergei Lissianoi | 6329339 | 2022-08-29 15:56:54 -0400 | [diff] [blame] | 25 | Pre-built binaries for some configurations are available at the following |
| 26 | location, see README.md for details |
Sergei Lissianoi | 510069d | 2022-03-14 17:12:04 -0400 | [diff] [blame] | 27 | |
Sergei Lissianoi | af5f7c9 | 2022-07-18 13:19:54 -0400 | [diff] [blame] | 28 | third_party/silabs/matter_support/matter/efr32/bootloader_binaries |
Sergei Lissianoi | 510069d | 2022-03-14 17:12:04 -0400 | [diff] [blame] | 29 | |
| 30 | - Using the commander tool upload the bootloader to the device running the |
| 31 | application. |
| 32 | |
| 33 | - Create a bootable image file (using the Lighting application image as an |
| 34 | example): |
| 35 | |
| 36 | commander gbl create chip-efr32-lighting-example.gbl --app chip-efr32-lighting-example.s37 |
| 37 | |
| 38 | - Create the Matter OTA file from the bootable image file: |
| 39 | |
Sergei Lissianoi | af5f7c9 | 2022-07-18 13:19:54 -0400 | [diff] [blame] | 40 | ./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 |
Sergei Lissianoi | 510069d | 2022-03-14 17:12:04 -0400 | [diff] [blame] | 41 | |
| 42 | - In a terminal start the Provider app passing to it the path to the Matter |
| 43 | OTA file created in the previous step: |
| 44 | |
Sergei Lissianoi | 8d0761d | 2023-09-11 15:51:14 -0400 | [diff] [blame] | 45 | rm -r /tmp/chip_kvs_provider |
| 46 | ./out/debug/chip-ota-provider-app --KVS /tmp/chip_kvs_provider -f chip-efr32-lighting-example.ota |
Sergei Lissianoi | 510069d | 2022-03-14 17:12:04 -0400 | [diff] [blame] | 47 | |
| 48 | - In a separate terminal run the chip-tool commands to provision the Provider: |
| 49 | |
Andrei Litvin | a76f75e | 2022-04-13 08:34:42 -1000 | [diff] [blame] | 50 | ./out/chip-tool pairing onnetwork 1 20202021 |
| 51 | ./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 |
Sergei Lissianoi | 510069d | 2022-03-14 17:12:04 -0400 | [diff] [blame] | 52 | |
| 53 | - If the application device had been previously commissioned hold Button 0 for |
| 54 | six seconds to factory-reset the device. |
| 55 | |
| 56 | - In the chip-tool terminal enter: |
| 57 | |
Andrei Litvin | a76f75e | 2022-04-13 08:34:42 -1000 | [diff] [blame] | 58 | ./out/chip-tool pairing ble-thread 2 hex:<operationalDataset> 20202021 3840 |
Sergei Lissianoi | 510069d | 2022-03-14 17:12:04 -0400 | [diff] [blame] | 59 | |
| 60 | where operationalDataset is obtained from the OpenThread Border Router. |
| 61 | |
| 62 | - Once the commissioning process completes enter: |
| 63 | |
Marcin Kajor | ecd0f6f | 2023-06-14 11:34:04 +0200 | [diff] [blame] | 64 | ./out/chip-tool otasoftwareupdaterequestor announce-otaprovider 1 0 0 0 2 0 |
Sergei Lissianoi | 510069d | 2022-03-14 17:12:04 -0400 | [diff] [blame] | 65 | |
| 66 | - The application device will connect to the Provider and start the image |
| 67 | download. Once the image is downloaded the device will reboot into the |
| 68 | downloaded image. |
| 69 | |
Sergei Lissianoi | af5f7c9 | 2022-07-18 13:19:54 -0400 | [diff] [blame] | 70 | ## Internal Storage Bootloader |
| 71 | |
| 72 | Internal storage bootloader for Matter OTA software update is supported on MG24 |
| 73 | boards only. In this use case both the running image and the downloadable update |
| 74 | image must fit on the internal flash at the same time. This in turn requires |
| 75 | that both images are built with a reduced feature set such as disabled logging |
| 76 | and Matter shell. The following set of compile flags leaves out all the optional |
| 77 | features and results in the minimal image size: |
| 78 | |
Sergei Lissianoi | af5f7c9 | 2022-07-18 13:19:54 -0400 | [diff] [blame] | 79 | 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 |
Sergei Lissianoi | af5f7c9 | 2022-07-18 13:19:54 -0400 | [diff] [blame] | 80 | |
| 81 | Using LZMA compression when building the .gbl file ( passing `--compress lzma` |
| 82 | parameter to the `commander gbl create` command) further reduces the downloaded |
| 83 | image size. |
| 84 | |
| 85 | When building an internal storage bootloader the two key configuration |
| 86 | parameters are the Slot Start Address and Slot Size in the Bootloader Storage |
| 87 | Slot component. The storage slot must not overlap with the running image and the |
| 88 | NVM section of the flash. In other words, the slot start address must be greater |
| 89 | than the end of the running image address and the sum of the start address and |
| 90 | the slot size must be less than the address of the NVM section. The simplest way |
| 91 | to get the relevant addresses for the running image and NVM would be by using |
| 92 | the Silicon Labs `commander` tool (Device Info->Main Flash->Flash Map). |
| 93 | |
| 94 | The pre-built bootloader binaries are configured with slot start address of |
| 95 | 0x080EC000 and slot size of 548864 |
| 96 | |
| 97 | ## Managing the Software Version |
| 98 | |
| 99 | In order for the Provider to successfully serve the image to a device during the |
| 100 | OTA Software Update process the Software Version parameter that the .ota file |
| 101 | was built with must be greater than the |
| 102 | CHIP_DEVICE_CONFIG_DEVICE_SOFTWARE_VERSION parameter set in the application's |
| 103 | `CHIPProjectConfig.h` file. The Software Version parameter is set by the `-vn` |
| 104 | parameter passed to the `ota_image_tool.py create` command. For example, if the |
| 105 | application's running image was built with |
| 106 | CHIP_DEVICE_CONFIG_DEVICE_SOFTWARE_VERSION set to 1 and if the `.ota` file is |
| 107 | built with `-vn 2` then the Provider will serve the update image when requested. |
| 108 | |
| 109 | In order for the OTA Software Update subsystem to consider an update to be |
| 110 | successful and for the NotifyUpdateApplied command to be transmitted the |
| 111 | CHIP_DEVICE_CONFIG_DEVICE_SOFTWARE_VERSION in the updated image must exceed the |
| 112 | software version of the running image (continuing the above example, the image |
| 113 | for the update must be built with CHIP_DEVICE_CONFIG_DEVICE_SOFTWARE_VERSION set |
| 114 | to 2). |
| 115 | |
| 116 | ## Managing the Vendor and Product ID |
Sergei Lissianoi | 510069d | 2022-03-14 17:12:04 -0400 | [diff] [blame] | 117 | |
| 118 | Starting the ota-provider-app with the --otaImageList command line option allows |
| 119 | the user to supply a JSON file specifying the Software Version, Vendor and |
| 120 | Product ID that identify the image served by the Provider, see |
| 121 | [ota-provider-app](../../examples/ota-provider-app/linux/README.md) |
| 122 | |
| 123 | Example provider configuration file: |
| 124 | |
| 125 | ``` |
| 126 | { "foo": 1, // ignored by parser |
| 127 | "deviceSoftwareVersionModel": |
| 128 | [ |
| 129 | { "vendorId": 65521, "productId": 32773, "softwareVersion": 1, "softwareVersionString": "1.0.0", "cDVersionNumber": 18, "softwareVersionValid": true, "minApplicableSoftwareVersion": 0, "maxApplicableSoftwareVersion": 100, "otaURL": "chip-efr32-lighting-example.ota" } |
| 130 | ] |
| 131 | } |
| 132 | ``` |
| 133 | |
Sergei Lissianoi | af5f7c9 | 2022-07-18 13:19:54 -0400 | [diff] [blame] | 134 | ## Additional Info |
| 135 | |
| 136 | Developers can find more resources on |
| 137 | [Silicon Labs Matter Community Page](https://community.silabs.com/s/article/connected-home-over-ip-chip-faq?language=en_US) |
| 138 | . |