blob: 9f94753aa7d29ff2761926a5578c0fe843ffcf5d [file] [log] [blame] [view]
Sergei Lissianoi510069d2022-03-14 17:12:04 -04001# Matter Software Update with EFR32 example applications
2
3The Over The Air (OTA) Software Update functionality can be added to any of the
4EFR32 example applications by passing the `chip_enable_ota_requestor=true`
5option to the build script. This option is supposed to be enabled by default for
6all 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
CuRahmanb989fb32024-02-12 22:33:47 -050011 discussed in examples/lighting-app/silabs/README.md and get its operational
Sergei Lissianoi510069d2022-03-14 17:12:04 -040012 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 Lissianoiaf5f7c92022-07-18 13:19:54 -040020- 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 Lissianoi63293392022-08-29 15:56:54 -040025 Pre-built binaries for some configurations are available at the following
26 location, see README.md for details
Sergei Lissianoi510069d2022-03-14 17:12:04 -040027
Sergei Lissianoiaf5f7c92022-07-18 13:19:54 -040028 third_party/silabs/matter_support/matter/efr32/bootloader_binaries
Sergei Lissianoi510069d2022-03-14 17:12:04 -040029
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 Lissianoiaf5f7c92022-07-18 13:19:54 -040040 ./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 Lissianoi510069d2022-03-14 17:12:04 -040041
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 Lissianoi8d0761d2023-09-11 15:51:14 -040045 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 Lissianoi510069d2022-03-14 17:12:04 -040047
48- In a separate terminal run the chip-tool commands to provision the Provider:
49
Andrei Litvina76f75e2022-04-13 08:34:42 -100050 ./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 Lissianoi510069d2022-03-14 17:12:04 -040052
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 Litvina76f75e2022-04-13 08:34:42 -100058 ./out/chip-tool pairing ble-thread 2 hex:<operationalDataset> 20202021 3840
Sergei Lissianoi510069d2022-03-14 17:12:04 -040059
60where operationalDataset is obtained from the OpenThread Border Router.
61
62- Once the commissioning process completes enter:
63
Marcin Kajorecd0f6f2023-06-14 11:34:04 +020064 ./out/chip-tool otasoftwareupdaterequestor announce-otaprovider 1 0 0 0 2 0
Sergei Lissianoi510069d2022-03-14 17:12:04 -040065
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 Lissianoiaf5f7c92022-07-18 13:19:54 -040070## Internal Storage Bootloader
71
72Internal storage bootloader for Matter OTA software update is supported on MG24
73boards only. In this use case both the running image and the downloadable update
74image must fit on the internal flash at the same time. This in turn requires
75that both images are built with a reduced feature set such as disabled logging
76and Matter shell. The following set of compile flags leaves out all the optional
77features and results in the minimal image size:
78
Sergei Lissianoiaf5f7c92022-07-18 13:19:54 -040079 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 Lissianoiaf5f7c92022-07-18 13:19:54 -040080
81Using LZMA compression when building the .gbl file ( passing `--compress lzma`
82parameter to the `commander gbl create` command) further reduces the downloaded
83image size.
84
85When building an internal storage bootloader the two key configuration
86parameters are the Slot Start Address and Slot Size in the Bootloader Storage
87Slot component. The storage slot must not overlap with the running image and the
88NVM section of the flash. In other words, the slot start address must be greater
89than the end of the running image address and the sum of the start address and
90the slot size must be less than the address of the NVM section. The simplest way
91to get the relevant addresses for the running image and NVM would be by using
92the Silicon Labs `commander` tool (Device Info->Main Flash->Flash Map).
93
94The pre-built bootloader binaries are configured with slot start address of
950x080EC000 and slot size of 548864
96
97## Managing the Software Version
98
99In order for the Provider to successfully serve the image to a device during the
100OTA Software Update process the Software Version parameter that the .ota file
101was built with must be greater than the
102CHIP_DEVICE_CONFIG_DEVICE_SOFTWARE_VERSION parameter set in the application's
103`CHIPProjectConfig.h` file. The Software Version parameter is set by the `-vn`
104parameter passed to the `ota_image_tool.py create` command. For example, if the
105application's running image was built with
106CHIP_DEVICE_CONFIG_DEVICE_SOFTWARE_VERSION set to 1 and if the `.ota` file is
107built with `-vn 2` then the Provider will serve the update image when requested.
108
109In order for the OTA Software Update subsystem to consider an update to be
110successful and for the NotifyUpdateApplied command to be transmitted the
111CHIP_DEVICE_CONFIG_DEVICE_SOFTWARE_VERSION in the updated image must exceed the
112software version of the running image (continuing the above example, the image
113for the update must be built with CHIP_DEVICE_CONFIG_DEVICE_SOFTWARE_VERSION set
114to 2).
115
116## Managing the Vendor and Product ID
Sergei Lissianoi510069d2022-03-14 17:12:04 -0400117
118Starting the ota-provider-app with the --otaImageList command line option allows
119the user to supply a JSON file specifying the Software Version, Vendor and
120Product ID that identify the image served by the Provider, see
121[ota-provider-app](../../examples/ota-provider-app/linux/README.md)
122
123Example 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 Lissianoiaf5f7c92022-07-18 13:19:54 -0400134## Additional Info
135
136Developers 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.