OTA Requestor

The Matter Over-The-Air is a process that allows a Matter device in a Matter fabric to update its firmware.

The Matter Core Specification requires that each device implements a method for firmware update for security reasons. This OTA requestor sample demonstrates the usage of the Matter operational network for querying and downloading a new firmware image.

This sample can be used as a reference for creating an application.

OTA Provider - This is a node that can respond to the OTA Requestors’ queries about available software updates and share the update packages with them.
OTA Requestor - This is any node that needs to be updated and can communicate with the OTA Provider to fetch applicable software updates.

In this sample, the OTA Provider will be a Linux application and this example will work as the OTA Requestor. Realtek’s OTA solution can be divided into supporting Bank switching scheme and non-supporting Bank switching scheme depending on the Flash layout; please refer to the OTA Scheme for more information. This example will demonstrate supporting Bank switching scheme.

Requirements

The sample supports the following development kits:

Supported Development Kits
Hardware platforms	Board name
RTL8777G HDK	RTL8777G EVB

Prepare Matter Environment

To set up the Matter environment, follow the steps listed in Development Setup.

Prepare CHIP Tool

The CHIP Tool (chip-tool) is a Matter controller implementation that allows commissioning a Matter device into the network and communicating with it using Matter messages, which may encode Data Model actions, such as cluster commands. The tool also provides other utilities specific to Matter, such as parsing the setup payload or performing discovery actions.

To build the target, follow the steps listed on the CHIP Tool.

Configurations

The following configurations may be used in this sample.

CHIP_DEVICE_CONFIG_DEVICE_SOFTWARE_VERSION
A monotonic number identifying the software version running on the device.

CHIP_DEVICE_CONFIG_DEVICE_SOFTWARE_VERSION_STRING
A string identifying the software version running on the device.

See Matter APP Config for more information about configuration items. Additionally, the CMakePresets.json file in the ./subsys/openthread directory will also be used, and this example will use the dual configuration set.

ENABLE_OTA_REQUESTOR
Whether to enable the Matter OTA Requestor function.

OTA_VERSION
The version number of the OTA Header.

Building and Downloading

Building

Navigate to the specified directory and build ota-requestor app.

$ cd ./subsys/matter/samples
$ rm -r build/
$ ./build.py rtl8777g ota-requestor --preset dual

Downloading

After a successful compilation, the app bin matter-cli-ftd_bank0_MP_dev_*.bin will be generated in the directory build/bank0/bin.

To download app bin into EVB board, follow the steps listed on the Downloading in Quick Start. If the factory data is enabled, also refer to Program Factory Data in Factory Data.

Then press reset button on EVB board and it will start running.

Note

MPTool needs to load the flash_map.ini file from the directory ./subsys/openthread/vendor/bee4/rtl8777g_dual.

Other files required for downloading, as shown in Corresponding Download File,: the System Config File and OTA Header File can be generated by referring to Quick Start in System Config File and OTA Header.

Corresponding Download File
File type	File name	File path
System Config File	configFile_xxx.bin	(Generated by MP Tool)
Bank0 Boot Patch Image	BANK0_boot_patch_MP_release_xxx.bin	\subsys\openthread\vendor\bee4\rtl8777g_dual\firmware\bank0
Bank0 OTA Header File	OTAHeader_Bank0_xxx.bin	(Generated by MP Tool)
Bank0 System Patch Image	sys_patch_MP_release_xxx.bin	\subsys\openthread\vendor\bee4\rtl8777g_dual\firmware\bank0
Bank0 Bluetooth Stack Patch Image	bt_stack_patch_MP_master_xxx.bin	\subsys\openthread\vendor\bee4\rtl8777g_dual\firmware\bank0
Bank0 Bluetooth Host Image	bt_host_MP_xxx.bin	\subsys\openthread\vendor\bee4\rtl8777g_dual\firmware\bank0

Preparing OTA image

To validate booting into a newer OTA Requestor image, the following must be performed:

The current software version of the OTA Requestor application is defined by CHIP_DEVICE_CONFIG_DEVICE_SOFTWARE_VERSION in CHIPProjectConfig.h. Modify CHIP_DEVICE_CONFIG_DEVICE_SOFTWARE_VERSION to a value greater than the current running version.
Modify the CMakePresets.json file in the ./subsys/openthread directory, and change the OTA_VERSION under the dual configuration to a value greater than the currently running version.
Building an OTA Requestor application with the new version.
The Matter OTA image is one of the build output files. The default location of the ota image is build/ota/matter.ota in the build directory.
Use this generated binary when supplying the image file to the OTA Provider application.

Note

CHIP_DEVICE_CONFIG_DEVICE_SOFTWARE_VERSION needs to be greater than the current running version number for the Matter OTA to start correctly.
OTA_VERSION corresponds to the version of the OTA Header File, and needs to be greater than the current running version number so that the correct bank can be brought up after the Matter OTA transfer is completed and device is restarted.

Experimental Verification

To test the sample, it is necessary to complete the following steps:

Navigate to the CHIP root directory.

Build the OTA Provider application for Linux:

$ scripts/examples/gn_build_example.sh examples/ota-provider-app/linux out/provider chip_config_network_layer_ble=false

Run OTA Provider application with matter.ota replaced with the path to the Matter OTA image which is intended to be provided to the Matter device. Note that the Matter OTA image is, by default, generated at build/ota/matter.ota in the example’s build directory:
```
$ ./out/provider/chip-ota-provider-app -f matter.ota
```
- Keep the application running and use another terminal for the remaining steps.
Commission the Matter device using Node ID 1. The parameter starting with the hex: prefix is the Thread network’s Active Operational Dataset. It can be retrieved from the OTBR in case the default network settings have been changed when forming the network.
```
$ ./out/chiptool/chip-tool pairing ble-thread 1 hex:<operationalDataset> 20202021 3840
```
Commission the OTA Provider into the Matter network using Node ID 2:
```
$ ./out/chiptool/chip-tool pairing onnetwork 2 20202021
```
Configure the Matter device with the default OTA Provider by running the following command (the last two arguments are Requestor Node ID and Requestor Endpoint ID, respectively):
```
$ ./out/chiptool/chip-tool otasoftwareupdaterequestor write default-otaproviders '[{"fabricIndex": 1, "providerNodeID": 2, "endpoint": 0}]' 1 0
```

Configure the OTA Provider with the access control list (ACL) that grants Operate privileges to all nodes in the fabric. This is necessary to allow the nodes to send cluster commands to the OTA Provider:

$ ./out/chiptool/chip-tool accesscontrol write acl '[{"fabricIndex": 1, "privilege": 3, "authMode": 2, "subjects": null, "targets": [{"cluster": 41, "endpoint": null, "deviceType": null}]}]' 2 0

Use chip-tool to send the Announce OTA Provider command to the device (the numeric arguments are Provider Node ID, Provider Vendor ID, Announcement Reason, Provider Endpoint ID, Requestor Node ID and Requestor Endpoint ID, respectively):
```
$ ./out/chiptool/chip-tool otasoftwareupdaterequestor announce-otaprovider 2 0 0 0 1 0
```
The OTA process should include downloading the image, verification of image header, erasing upgraded flash partition, writing to flash and checksum verification. Once OTA signature is updated, the device will reboot into the new image after 10 seconds countdown.