The OTA Requestor feature enables the device to be informed of, download and apply a software update from an OTA Provider.
This section explains how to perform an OTA Software Update with NXP platform using NXP/Zephyr SDK. Throughout this guide, the all-clusters application is used as an example.
In general, the Over-The-Air Software Update process consists of the following steps :
The Flash is divided into different regions as follow :
The size reserved for each partition can be found in src/platform/nxp/zephyr/boards/board.overlay
.
Notes :
board.overlay
.(example: src/platform/nxp/zephyr/boards/rd_rw612_bga.overlay
)Current OTA solution is using MCUBoot Bootloader. MCUBoot is an open-source secure bootloader used to apply the self-upgrade. For more details, please refer to the MCUBoot documentation.
In our use case, the bootloader runs the application residing in the primary partition. In order to run the OTA update image, the bootloader will swap the content of the primary and the secondary partitions. This type of upgrade is called swap-move and is the default upgrade configured by MCUBoot.
The all cluster app is able to demonstrate the usage of OTA. To have this OTA support, prj_ota.conf configurations needs to be used. This can be done by adding -DEXTRA_CONF_FILE=prj_ota.conf
to the west build command.
Current OTA implementation automates the following procedures:
modules/connectedhomeip/build_mcuboot/zephyr/zephyr.bin
)*zephyr/zephyr.bin
)*zephyr/zephyr.signed.bin
)*zephyr/zephyr_full.bin
)*Note: *All paths are relative to the output folder.
The final binary to be used is zephyr_full.bin
.
The application image have the following format :
In the all-cluster-app example, the image is signed with the default private key provided by MCUBoot(/zephyrproject/bootloader/mcuboot/root-rsa-2048.pem
). MCUBoot is built with its corresponding public key which would be used to verify the integrity of the image. It is possible to generate a new pair of keys using the following commands. This procedure should be done prior to building the mcuboot application.
user@ubuntu: python3 imgtool.py keygen -k priv_key.pem -t rsa-2048
user@ubuntu: python3 imgtool.py getpub -k priv_key.pem
To use a different key than the default one, CONFIG_BOOT_SIGNATURE_KEY_FILE
and CONFIG_MCUBOOT_SIGNATURE_KEY_FILE
needs to point to that same key.
CONFIG_BOOT_SIGNATURE_KEY_FILE
: This is used for the MCUboot bootloader image. The path to the key can be either absolute or relative. Relative paths starts from the MCUBoot repository root. This option can be changed in: config/nxp/app/bootloader.conf
CONFIG_MCUBOOT_SIGNATURE_KEY_FILE
: This is used for the application to be loaded by the bootloader. The path can be either absolute or relative. Relative paths starts from the west workspace location. This option can be changed in the application .conf files.
Refer to those two files for more information:
When an OTA image is received it can either be marked as permanent or as a test, The Kconfig CONFIG_CHIP_OTA_REQUEST_UPGRADE_TYPE
can choose one of those configurations (Defined in /config/nxp/chip-module/Kconfig
):
CONFIG_CHIP_OTA_REQUEST_UPGRADE_PERMANENT
: From the next reboot, this image will be run permanently.CONFIG_CHIP_OTA_REQUEST_UPGRADE_TEST
: The image will be run on the next reboot, but it will be reverted if it doesn't get confirmed. The image needs to confirm itself to become permanent.By default, the upgrade type used is CONFIG_CHIP_OTA_REQUEST_UPGRADE_TEST
, and OTA image confirms itself during the initialization stage after the fundamental parts of the application are initialized properly to make sure this new image boots correctly. This confirmation is done by chip::NXP::App::OTARequestorInitiator::HandleSelfTest()
.
JLink can be used to flash the mixed binary at the base address 0x8000000, using the command :
J-Link > loadbin zephyr_full.bin 0x8000000
The bootloader should then be able to jump directly to the start of the application and run it.
The same procedure can be followed from the Generating and flashing application image sub-section, replacing CONFIG_CHIP_DEVICE_SOFTWARE_VERSION
with a number greater than the initial one used on the active application (Candidate application version number should be greater than the one used on the active application). By default the value is set to 0, try resetting this option to 1 to generate the OTA update Image. You can do this by adding -DCONFIG_CHIP_DEVICE_SOFTWARE_VERSION=1
to the west build command.
The current implementation automates the following procedures:
zephyr/zephyr.bin
)*zephyr/zephyr.signed.bin
)*zephyr/matter.ota
)*Note: *All paths are relative to the output folder.
The generated OTA file matter.ota
can be used to perform the OTA Software Update. The instructions below describes the procedure step-by-step.
Setup example :
Before starting the OTA process, the Linux OTA Provider application can be built on the RPi (if not already present in the pre-installed apps) :
user@ubuntu:~/connectedhomeip$ : ./scripts/examples/gn_build_example.sh examples/ota-provider-app/linux out/ota-provider-app chip_config_network_layer_ble=false user@ubuntu:~/connectedhomeip$ : rm -rf /tmp/chip_* user@ubuntu:~/connectedhomeip$ : ./out/ota-provider-app/chip-ota-provider-app -f matter.ota
The OTA Provider should first be provisioned with chip-tool by assigning it the node id 1, and then granted the ACL entries :
user@ubuntu:~/connectedhomeip$ : ./out/chip-tool-app/chip-tool pairing onnetwork 1 20202021 user@ubuntu:~/connectedhomeip$ : ./out/chip-tool-app/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
The second step is to provision the device with the node id 2 using ble-wifi or ble-thread commissioning. For example :
user@ubuntu:~/connectedhomeip$ : ./out/chip-tool-app/chip-tool pairing ble-wifi 2 WIFI_SSID WIFI_PASSWORD 20202021 3840
Once commissioned, the OTA process can be initiated with the “announce-ota-provider” command using chip-tool (the given numbers refer respectively to [ProviderNodeId][vendorid] [AnnouncementReason][endpoint] [node-id][endpoint-id]) :
user@ubuntu:~/connectedhomeip$ : ./out/chip-tool-app/chip-tool otasoftwareupdaterequestor announce-otaprovider 1 0 0 0 2 0
When the full update image is downloaded and stored, the bootloader will be notified and the device will reboot with the update image.