Skip to content

Commit

Permalink
[NXP][OTA][doc] update OTA doc for RTs boards
Browse files Browse the repository at this point in the history
  • Loading branch information
jby-nxp committed Oct 3, 2024
1 parent c08f1d5 commit 948122f
Show file tree
Hide file tree
Showing 3 changed files with 79 additions and 218 deletions.
Original file line number Diff line number Diff line change
@@ -1,11 +1,16 @@
# Matter Over-The-Air Software Update with NXP RW61x example applications
# Matter Over-The-Air Software Update with NXP RTs example applications

## Overview

This document describes OTA feature on NXP devices:
- RW61x
- RT1060_EVKC
- RT1170_EVKB

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 RW61x
This section explains how to perform an OTA Software Update with NXP RTs
example applications. Throughout this guide, the all-clusters application is
used as an example.

Expand All @@ -24,10 +29,9 @@ steps :

### Flash Memory Layout

The RW61x Flash is divided into different regions as follow :
The RTs Flash is divided into different regions as follow :

- Bootloader : MCUBoot resides at the base of the flash and occupies 0x20000
(128 kB).
- Bootloader : MCUBoot resides at the base of the flash.
- Primary application partition : The example application which would be run
by the bootloader (active application). The size reserved for this partition
is 4.4 MB.
Expand All @@ -36,23 +40,23 @@ The RW61x Flash is divided into different regions as follow :

Notes :

- The CPU1/CPU2 firmware are embedded in the CPU3 example application.
- For RW61x: The CPU1/CPU2 firmware are embedded in the CPU3 example application.
- The sizes of the primary and secondary applications are provided as an
example (currently 4.4 MB is reserved for each partition). The size can be
changed by modifying the `m_app_max_sectors` value in the linker script of
the application (`RW610_flash.ld`).
the application .

### MCUBoot Bootloader

MCUBoot is an open-source secure bootloader used by RW61x to apply the
self-upgrade. For more details, please refer to the
[MCUBoot documentation](https://github.com/mcu-tools/mcuboot/blob/main/docs/design.md).

For RW61x platform, the bootloader is configured to use the flash remapping
For RTs platform, the bootloader is configured to use the flash remapping
mechanism by default, in order to perform the image upgrade. This is achieved by
using the `MCUBoot DIRECT-XIP` upgrade mode.

## OTA Software Update process for RW61x example application
## OTA Software Update process for RTs example application

### Flashing the bootloader

Expand All @@ -71,44 +75,59 @@ $ JLink

Run the following commands :

```
Connect J-Link debugger to device:
```sh
J-Link > connect
Device> ? # you will be presented with a dialog -> select `RW612`
Device> ? # you will be presented with a dialog -> select `RW612` for RW61x, `MIMXRT1062XXX6B` for RT1060, `MIMXRT1176xxxA_M7` for RT1170
Please specify target interface:
J) JTAG (Default)
S) SWD
T) cJTAG
TIF> S
Specify target interface speed [kHz]. <Default>: 4000 kHz
Speed> # <enter>
```

Erase flash:
```
J-Link > exec EnableEraseAllFlashBanks
```
For RW61x
```
J-Link > erase 0x8000000, 0x88a0000
```
For RT1060-EVKC
```
J-Link > erase 0x60000000, 0x61000000
```
For RT1170-EVKB
```
J-Link > erase 0x30000000, 0x34000000
```

- MCUBoot application can be built with SDK installed, using instructions

- MCUBoot application can be built with SDK installed, using intructions
below.
- Retrieve the mcuboot directory located at
>*<matter_repo_root>/third_party/nxp/nxp_matter_support/github_sdk/common_sdk/repo/examples/<`RT_board`><sup>[1](#RT_board)</sup>/ota_examples/mcuboot_opensource/armgcc*
- Retrieve the mcuboot directory with :

*<a name="RT_board">1</a> : `rdrw612bga` or `frdmrw612` for RW61x, `evkcmimxrt1060` for RT1060-EVKC, `evkbmimxrt1170` for RT1170-EVKB*
```
user@ubuntu: cd ~/Desktop/connectedhomeip/third_party/nxp/nxp_matter_support/github_sdk/common_sdk/repo/examples/<rw612 board>/ota_examples/mcuboot_opensource/armgcc
user@ubuntu: cd ~/Desktop/connectedhomeip/third_party/nxp/nxp_matter_support/github_sdk/common_sdk/repo/examples/<RT_board>/ota_examples/mcuboot_opensource/armgcc
```

`<rw612 board>`: Supported rw612 boards are: `rdrw612bga` or `frdmrw612`

- Build the mcuboot application :

- Build the mcuboot application with running <`build_script`><sup>[2](#mcuboot_build_script)</sup>

```
user@ubuntu: chmod +x build_flash_release.sh
user@ubuntu: chmod +x <build_script>
user@ubuntu: export ARMGCC_DIR=/opt/gcc-arm-none-eabi-10.3-2021.10 # with ARMGCC_DIR referencing the compiler path
user@ubuntu: ./build_flash_release.sh
user@ubuntu: ./<build_script>
```
*<a name="mcuboot_build_script">2</a> : `build_flash_release.sh` for RW61x, `build_flexspi_nor_release.sh` for RT1060 and RT1170*


- Program the generated binary to the target board.

```
J-Link > loadbin ~/Desktop/connectedhomeip/third_party/nxp/nxp_matter_support/github_sdk/common_sdk/repo/examples/<rw612 board>/ota_examples/mcuboot_opensource/armgcc/flash_release/mcuboot_opensource.elf
J-Link > loadbin <path_to_mcuboot>/mcuboot_opensource.elf
```

- If it runs successfully, the following logs will be displayed on the
Expand All @@ -128,8 +147,8 @@ Note : By default, mcuboot application considers the primary and secondary
partitions to be the size of 4.4 MB. If the size is to be changed, the partition
addresses should be modified in the flash_partitioning.h accordingly. For more
information about the flash partitioning with mcuboot, please refer to the
dedicated readme.txt located in
"`<matter_repo_root>/third_party/nxp/nxp_matter_support/github_sdk/common_sdk/repo/examples/<rw612 board>/ota_examples/mcuboot_opensource/`".
dedicated *readme.txt* located in
>*<matter_repo_root>/third_party/nxp/nxp_matter_support/github_sdk/common_sdk/repo/examples/<`RT_board`><sup>[1](#RT_board)</sup>/ota_examples/mcuboot_opensource/.*
### Generating and flashing the signed application image

Expand All @@ -143,15 +162,21 @@ The image must have the following format :
signature, the upgrade type, the swap status...

The all-clusters application can be generated using the instructions from the
[README.md 'Building'](../../../examples/all-clusters-app/nxp/rt/rw61x/README.md#building)

README.md<sup>[3](#board)</sup> 'Building'
section. The application is automatically linked to be executed from the primary
image partition, taking into consideration the offset imposed by mcuboot.

The resulting executable file found in out/debug/chip-rw61x-all-cluster-example
<a name="board">3</a> : [RW61x README.md 'Building'](../../../examples/all-clusters-app/nxp/rt/rw61x/README.md#building), [RT1060 README.md 'Building'](../../../examples/all-clusters-app/nxp/rt/rt1060/README.md#building), [RT1170 README.md 'Building'](../../../examples/all-clusters-app/nxp/rt/rt1170/README.md#building)

The resulting executable file found in out/release/chip-<`rt_board`><sup>[4](#rt_board)</sup>-all-cluster-example
needs to be converted into raw binary format as shown below.

```
arm-none-eabi-objcopy -R .flash_config -R .NVM -O binary chip-rw61x-all-cluster-example chip-rw61x-all-cluster-example.bin
*<a name="rt_board">4</a> : `rw61x` for RW61x, `rt1060` for RT1060-EVKC, `rt1170` for RT1170-EVKB*


```sh
arm-none-eabi-objcopy -R .flash_config -R .NVM -O binary chip-<"rt_board">-all-cluster-example chip-<"rt_board">-all-cluster-example.bin
```

To sign the image and wrap the raw binary of the application with the header and
Expand All @@ -161,10 +186,10 @@ trailer, "`imgtool`" is provided in the SDK and can be found in
The following commands can be run (make sure to replace the /path/to/file/binary
with the adequate files):

```
```sh
user@ubuntu: cd ~/Desktop/<matter_repo_root>/third_party/nxp/nxp_matter_support/github_sdk/common_sdk/repo/middleware/mcuboot_opensource/scripts/

user@ubuntu: python3 imgtool.py sign --key ~/Desktop/<matter_repo_root>/third_party/nxp/nxp_matter_support/github_sdk/common_sdk/repo/examples/<rw612 board>/ota_examples/mcuboot_opensource/keys/sign-rsa2048-priv.pem --align 4 --header-size 0x1000 --pad-header --pad --confirm --slot-size 0x440000 --max-sectors 1088 --version "1.0" ~/Desktop/connectedhomeip/examples/all-clusters-app/nxp/rt/rw61x/out/debug/chip-rw61x-all-cluster-example.bin ~/Desktop/connectedhomeip/examples/all-clusters-app/nxp/rt/rw61x/out/debug/chip-rw61x-all-cluster-example_SIGNED.bin
user@ubuntu: python3 imgtool.py sign --key ~/Desktop/<matter_repo_root>/third_party/nxp/nxp_matter_support/github_sdk/common_sdk/repo/examples/<RT board>/ota_examples/mcuboot_opensource/keys/sign-rsa2048-priv.pem --align 4 --header-size 0x1000 --pad-header --pad --confirm --slot-size 0x440000 --max-sectors 1088 --version "1.0" ~/Desktop/connectedhomeip/examples/all-clusters-app/nxp/rt/<"rt_board">/out/debug/chip-<"rt_board">-all-cluster-example.bin ~/Desktop/connectedhomeip/examples/all-clusters-app/nxp/rt/<"rt_board">/out/debug/chip-<"rt_board">-all-cluster-example_SIGNED.bin
```

Notes :
Expand All @@ -176,7 +201,7 @@ Notes :
adjusted accordingly.
- In this example, the image is signed with the private key provided by the
SDK as an example
(`<matter_repo_root>/third_party/nxp/nxp_matter_support/github_sdk/common_sdk/repo/examples/<rw612 board>/ota_examples/mcuboot_opensource/keys/sign-rsa2048-priv.pem`),
(`<matter_repo_root>/third_party/nxp/nxp_matter_support/github_sdk/common_sdk/repo/examples/<RT_board>/ota_examples/mcuboot_opensource/keys/sign-rsa2048-priv.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
Expand All @@ -195,17 +220,25 @@ user@ubuntu: python3 imgtool.py getpub -k priv_key.pem
```

- The extracted public key can then be copied to the
`<matter_repo_root>/third_party/nxp/nxp_matter_support/github_sdk/common_sdk/repo/examples/<rw612 board>/ota_examples/mcuboot_opensource/keys/sign-rsa2048-pub.c`,
`<matter_repo_root>/third_party/nxp/nxp_matter_support/github_sdk/common_sdk/repo/examples/<RT_board>/ota_examples/mcuboot_opensource/keys/sign-rsa2048-pub.c`,
given as a value to the rsa_pub_key[] array.

The resulting output is the signed binary of the application version "1.0".

JLink can be used to flash the application at the address 0x8020000, using the
command :
JLink can be used to flash the application using the command :

For RW61x
```
J-Link > loadbin chip-rw61x-all-cluster-example_SIGNED.bin 0x8020000
```
For RT1060-EVKC
```
J-Link > loadbin chip-rt1060-all-cluster-example_SIGNED.bin 0x60040000
```
For RT1170-EVKB
```
J-Link > loadbin chip-rt1170-all-cluster-example_SIGNED.bin 0x30040000
```

The bootloader should then be able to jump directly to the start of the
application and run it.
Expand All @@ -216,18 +249,18 @@ To generate the OTA update image the same procedure can be followed from the
[Generating and flashing the signed application image](#generating-and-flashing-the-signed-application-image)
sub-section, replacing the "--version "1.0"" argument with "--version "2.0""
(recent version of the update), without arguments "--pad" "--confirm" when
running `imgtool` script during OTA Update Image generation.
running imgtool script during OTA Update Image generation.

Note : When building the update image, the build arguments
nxp_software_version=2 nxp_software_version_string=\"2.0\" can be added to the
gn gen command in order to specify the upgraded version.
nxp_software_version=2 nxp_software_version_string=\"2.0\" can be added to the gn
gen command in order to specify the upgraded version.

When the signed binary of the update is generated, the file should be converted
into OTA format. To do so, the ota_image_tool is provided in the repo and can be
used to convert a binary file into an .ota file.

```
user@ubuntu:~/connectedhomeip$ : ./src/app/ota_image_tool.py create -v 0xDEAD -p 0xBEEF -vn 2 -vs "2.0" -da sha256 chip-rw61x-all-cluster-example_SIGNED.bin chip-rw61x-all-cluster-example.ota
```sh
user@ubuntu:~/connectedhomeip$ : ./src/app/ota_image_tool.py create -v 0xDEAD -p 0xBEEF -vn 2 -vs "2.0" -da sha256 chip-<"rt_board">-all-cluster-example_SIGNED.bin chip-rw61x-all-cluster-example.ota
```

The generated OTA file can be used to perform the OTA Software Update. The
Expand All @@ -240,17 +273,18 @@ Setup example :
- [Chip-tool](../../../examples/chip-tool/README.md) application running on
the RPi.
- OTA Provider application built on the same RPi (as explained below).
- RW61x board programmed with the example application (with the instructions
- RT board programmed with the example application (with the instructions
above).

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 chip-rw61x-all-cluster-example.ota
```
```sh
user@ubuntu:~/connectedhomeip$ : ./out/ota-provider-app/chip-ota-provider-app -f chip-<"rt_board">-all-cluster-example.ota
```

The OTA Provider should first be provisioned with chip-tool by assigning it the
Expand Down
2 changes: 1 addition & 1 deletion examples/all-clusters-app/nxp/rt/rt1170/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -241,7 +241,7 @@ Optional GN options that can be added when building an application:
- To build the application with the OTA Requestor enabled, the arguments
`chip_enable_ota_requestor=true no_mcuboot=false` must be added to the _gn
gen_ command. (More information about the OTA Requestor feature in
[OTA Requestor README](README_OTA_Requestor.md)))
[OTA Requestor README](../../../../../docs/guides/nxp/nxp_RTs_ota_software_update.md)))

<a name="manufacturing-data"></a>

Expand Down
Loading

0 comments on commit 948122f

Please sign in to comment.