Skip to content

Commit be51162

Browse files
chapongatienchapongatien
committed
[nxp toup] docs: add MCXW72 as experimental Zephyr platform
Document frdm_mcxw72 as an experimental platform under the Zephyr build flow (Matter over Thread, contact-sensor-app only) and note that OTA Software Update is not supported on MCXW72 under the Zephyr flow. - nxp_zephyr_guide.md: add frdm_mcxw72 board, Thread support, build example and NBU flashing note - nxp_zephyr_ota_software_update.md: note OTA not supported on MCXW72 - contact-sensor-app README: add MCXW72 (Zephyr, experimental) entry
1 parent 2a7ea12 commit be51162

3 files changed

Lines changed: 121 additions & 93 deletions

File tree

‎docs/platforms/nxp/nxp_zephyr_guide.md‎

Lines changed: 44 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -10,15 +10,15 @@ commissioning and different cluster control.
1010

1111
<hr>
1212

13-
- [Introduction](#introduction)
14-
- [Building](#building)
15-
- [Flashing and debugging](#flashing-and-debugging)
16-
- [Factory data](#factory-data)
17-
- [Manufacturing data](#generate-factory-data)
18-
- [DAC private key blob generation](#dac-private-key-blob-generation)
19-
- [OTA Software Update](#ota-software-update)
20-
- [Testing the example](#testing-the-example)
21-
- [Using Matter CLI in NXP Zephyr examples](#using-matter-cli-in-nxp-zephyr-examples)
13+
- [Introduction](#introduction)
14+
- [Building](#building)
15+
- [Flashing and debugging](#flashing-and-debugging)
16+
- [Factory data](#factory-data)
17+
- [Manufacturing data](#generate-factory-data)
18+
- [DAC private key blob generation](#dac-private-key-blob-generation)
19+
- [OTA Software Update](#ota-software-update)
20+
- [Testing the example](#testing-the-example)
21+
- [Using Matter CLI in NXP Zephyr examples](#using-matter-cli-in-nxp-zephyr-examples)
2222

2323
<hr>
2424

@@ -32,14 +32,21 @@ NXP/Zephyr SDK.
3232

3333
The example supports:
3434

35-
- Matter over Wi-Fi with BLE commissioning
36-
- Matter OTA requestor
37-
- Matter Factory Data
35+
- Matter over Wi-Fi with BLE commissioning
36+
- Matter over Thread with BLE commissioning (MCXW72 only)
37+
- Matter OTA requestor
38+
- Matter Factory Data
3839

3940
The supported boards are:
4041

41-
- `rd_rw612_bga`
42-
- `frdm_rw612`
42+
- `rd_rw612_bga`
43+
- `frdm_rw612`
44+
- `frdm_mcxw72` (experimental)
45+
46+
> **Note**: `frdm_mcxw72` support under the Zephyr build flow is
47+
> **experimental**. On MCXW72, Matter runs over Thread, and only the
48+
> contact-sensor-app example is supported. OTA Software Update is **not**
49+
> supported on MCXW72 under the Zephyr flow.
4350
4451
<a name="building"></a>
4552

@@ -50,12 +57,12 @@ distribution (the demo-application was compiled on Ubuntu 20.04).
5057

5158
Prerequisites:
5259

53-
- Follow instruction from [BUILDING.md](../../guides/BUILDING.md) to setup the
54-
Matter environment
55-
- Follow instruction from
56-
[Getting Started Guide](https://docs.zephyrproject.org/4.3.0/develop/getting_started/index.html)
57-
to setup a Zephyr workspace, however, the west init command to use is as
58-
follows:
60+
- Follow instruction from [BUILDING.md](../../guides/BUILDING.md) to setup the
61+
Matter environment
62+
- Follow instruction from
63+
[Getting Started Guide](https://docs.zephyrproject.org/4.3.0/develop/getting_started/index.html)
64+
to setup a Zephyr workspace, however, the west init command to use is as
65+
follows:
5966

6067
```shell
6168
$ west init zephyrproject -m https://github.com/nxp-zephyr/nxp-zsdk.git --mr nxp-v4.4.1.1
@@ -95,7 +102,15 @@ As an example with the `frdm_rw612` board:
95102
west build -b frdm_rw612 -p auto -d build_zephyr examples/all-clusters-app/nxp/zephyr
96103
```
97104

105+
As an example with the `frdm_mcxw72` board (experimental), building the
106+
contact-sensor-app (Matter over Thread):
107+
108+
```shell
109+
west build -b frdm_mcxw72 -p auto -d build_zephyr examples/contact-sensor-app/nxp/zephyr
110+
```
111+
98112
A folder `build_zephyr` will be created in the same folder you run the command
113+
99114
from. The binaries will be created in `build_zephyr/zephyr` with the name
100115
`zephyr.elf` and `zephyr.bin`. We recommend using the `-d build_zephyr` if you
101116
are building from Matter repo root folder as a build folder already exists and
@@ -122,13 +137,19 @@ You can get more details on `west flash` with
122137
> **Note**: `west flash` will not start a debug session, it will only flash and
123138
> reset the device
124139
140+
> **Note (experimental - MCXW72)**: On `frdm_mcxw72`, the `NBU` (radio) firmware
141+
> must already be present on the board before running the Matter application.
142+
> Refer to the `Flashing the NBU firmware` section of the
143+
> [NXP MCXW72 Guide](./nxp_mcxw72_guide.md#flashing-and-debugging) for the
144+
> procedure.
145+
125146
### Flash and debug
126147

127148
To debug a Matter with Zephyr application, you could use several methods:
128149

129-
- [MCUXpresso IDE (version >= 11.6.0)](https://www.nxp.com/design/software/development-software/mcuxpresso-software-and-tools-/mcuxpresso-integrated-development-environment-ide:MCUXpresso-IDE)
130-
- `west debug`
131-
[Zephyr's debugging guide](https://docs.zephyrproject.org/3.7.0/develop/west/build-flash-debug.html#id29)
150+
- [MCUXpresso IDE (version >= 11.6.0)](https://www.nxp.com/design/software/development-software/mcuxpresso-software-and-tools-/mcuxpresso-integrated-development-environment-ide:MCUXpresso-IDE)
151+
- `west debug`
152+
[Zephyr's debugging guide](https://docs.zephyrproject.org/3.7.0/develop/west/build-flash-debug.html#id29)
132153

133154
> **Note**: As the build provides an elf file, any compatible debugging tool can
134155
> be used.

‎docs/platforms/nxp/nxp_zephyr_ota_software_update.md‎

Lines changed: 60 additions & 58 deletions
Original file line numberDiff line numberDiff line change
@@ -9,39 +9,42 @@ This section explains how to perform an OTA Software Update with NXP platform
99
using NXP/Zephyr SDK. Throughout this guide, the all-clusters application is
1010
used as an example.
1111

12+
> **Note**: OTA Software Update is **not** supported on `frdm_mcxw72` under the
13+
> Zephyr build flow. MCXW72 is an experimental Zephyr platform and this guide
14+
> does not apply to it.
15+
1216
In general, the Over-The-Air Software Update process consists of the following
1317
steps :
1418

15-
- The OTA Requestor queries an update image from the OTA Provider which
16-
responds according to its availability.
17-
- The update image is received in blocks and stored in the external flash of
18-
the device.
19-
- Once the update image is fully downloaded, the bootloader is notified and
20-
the device resets applying the update in test-mode.
21-
- If the test is successful, the update is applied permanently. Otherwise, the
22-
bootloader reverts back to the primary application, preventing any
23-
downgrade.
19+
- The OTA Requestor queries an update image from the OTA Provider which responds
20+
according to its availability.
21+
- The update image is received in blocks and stored in the external flash of the
22+
device.
23+
- Once the update image is fully downloaded, the bootloader is notified and the
24+
device resets applying the update in test-mode.
25+
- If the test is successful, the update is applied permanently. Otherwise, the
26+
bootloader reverts back to the primary application, preventing any downgrade.
2427

2528
### Flash Memory Layout
2629

2730
The Flash is divided into different regions as follow :
2831

29-
- Bootloader : MCUBoot resides at the base of the flash.
30-
- Primary application partition : The example application which would be run
31-
by the bootloader (active application).
32-
- Secondary application partition : Update image received with the OTA
33-
(candidate application).
32+
- Bootloader : MCUBoot resides at the base of the flash.
33+
- Primary application partition : The example application which would be run by
34+
the bootloader (active application).
35+
- Secondary application partition : Update image received with the OTA
36+
(candidate application).
3437

3538
The size reserved for each partition can be found in
3639
`<example folder>/boards/<board>.overlay`.
3740

3841
Notes :
3942

40-
- When applicable, BLE/15.4/Wi-Fi firmware are embedded in the application
41-
binary, ensuring compatibility between the application and the controllers.
42-
- The sizes of the primary and secondary applications are provided as an
43-
example. The size can be changed by overriding the partitions located at
44-
`<board>.overlay`.
43+
- When applicable, BLE/15.4/Wi-Fi firmware are embedded in the application
44+
binary, ensuring compatibility between the application and the controllers.
45+
- The sizes of the primary and secondary applications are provided as an
46+
example. The size can be changed by overriding the partitions located at
47+
`<board>.overlay`.
4548

4649
### MCUBoot Bootloader
4750

@@ -65,26 +68,25 @@ adding `-DEXTRA_CONF_FILE=prj_ota.conf` to the west build command.
6568

6669
Current OTA implementation automates the following procedures:
6770

68-
- Generation of MCUBOOT image (File generated:
69-
`modules/connectedhomeip/build_mcuboot/zephyr/zephyr.bin`)\*
70-
- Generation of Matter application image (File generated:
71-
`zephyr/zephyr.bin`)\*
72-
- Signature of the application image (File generated:
73-
`zephyr/zephyr.signed.bin`)\*
74-
- Generation of a single binary merging the signed application with the
75-
MCUBoot Image (File generated: `zephyr/zephyr_full.bin`)\*
71+
- Generation of MCUBOOT image (File generated:
72+
`modules/connectedhomeip/build_mcuboot/zephyr/zephyr.bin`)\*
73+
- Generation of Matter application image (File generated: `zephyr/zephyr.bin`)\*
74+
- Signature of the application image (File generated:
75+
`zephyr/zephyr.signed.bin`)\*
76+
- Generation of a single binary merging the signed application with the MCUBoot
77+
Image (File generated: `zephyr/zephyr_full.bin`)\*
7678

7779
> **Note**: \*All paths are relative to the output folder.
7880
7981
The final binary to be used is `zephyr_full.bin`.
8082

8183
The application image have the following format :
8284

83-
- Header : contains general information about the image (version, size,
84-
magic...)
85-
- Code of the application : generated binary
86-
- Trailer : contains metadata needed by the bootloader such as the image
87-
signature, the upgrade type, the swap status...
85+
- Header : contains general information about the image (version, size,
86+
magic...)
87+
- Code of the application : generated binary
88+
- Trailer : contains metadata needed by the bootloader such as the image
89+
signature, the upgrade type, the swap status...
8890

8991
In the all-cluster-app example, the image is signed with the default private key
9092
provided by MCUBoot(`/zephyrproject/bootloader/mcuboot/root-rsa-2048.pem`).
@@ -93,13 +95,13 @@ the integrity of the image. It is possible to generate a new pair of keys using
9395
the following commands. This procedure should be done prior to building the
9496
mcuboot application.
9597

96-
- To generate the private key :
98+
- To generate the private key :
9799

98100
```
99101
user@ubuntu: python3 imgtool.py keygen -k priv_key.pem -t rsa-2048
100102
```
101103

102-
- To extract the public key :
104+
- To extract the public key :
103105

104106
```
105107
user@ubuntu: python3 imgtool.py getpub -k priv_key.pem
@@ -108,30 +110,30 @@ user@ubuntu: python3 imgtool.py getpub -k priv_key.pem
108110
To use a different key than the default one, `CONFIG_BOOT_SIGNATURE_KEY_FILE`
109111
and `CONFIG_MCUBOOT_SIGNATURE_KEY_FILE` needs to point to that same key.
110112

111-
- `CONFIG_BOOT_SIGNATURE_KEY_FILE`: This is used for the MCUboot bootloader
112-
image. The path to the key can be either absolute or relative. Relative
113-
paths starts from the MCUBoot repository root. This option can be changed
114-
in: `config/nxp/app/bootloader.conf`
113+
- `CONFIG_BOOT_SIGNATURE_KEY_FILE`: This is used for the MCUboot bootloader
114+
image. The path to the key can be either absolute or relative. Relative paths
115+
starts from the MCUBoot repository root. This option can be changed in:
116+
`config/nxp/app/bootloader.conf`
115117

116-
- `CONFIG_MCUBOOT_SIGNATURE_KEY_FILE`: This is used for the application to be
117-
loaded by the bootloader. The path can be either absolute or relative.
118-
Relative paths starts from the west workspace location. This option can be
119-
changed in the application .conf files.
118+
- `CONFIG_MCUBOOT_SIGNATURE_KEY_FILE`: This is used for the application to be
119+
loaded by the bootloader. The path can be either absolute or relative.
120+
Relative paths starts from the west workspace location. This option can be
121+
changed in the application .conf files.
120122

121123
Refer to those two files for more information:
122124

123-
- [MCUBoot Config used for the MCUBoot Image](https://github.com/zephyrproject-rtos/mcuboot/blob/main/boot/zephyr/Kconfig)
124-
- [MCUBoot Config used for the application](https://github.com/zephyrproject-rtos/zephyr/blob/main/modules/Kconfig.mcuboot)
125+
- [MCUBoot Config used for the MCUBoot Image](https://github.com/zephyrproject-rtos/mcuboot/blob/main/boot/zephyr/Kconfig)
126+
- [MCUBoot Config used for the application](https://github.com/zephyrproject-rtos/zephyr/blob/main/modules/Kconfig.mcuboot)
125127

126128
When an OTA image is received it can either be marked as permanent or as a test,
127129
The Kconfig `CONFIG_CHIP_OTA_REQUEST_UPGRADE_TYPE` can choose one of those
128130
configurations (Defined in `/config/nxp/chip-module/Kconfig`):
129131

130-
- `CONFIG_CHIP_OTA_REQUEST_UPGRADE_PERMANENT`: From the next reboot, this
131-
image will be run permanently.
132-
- `CONFIG_CHIP_OTA_REQUEST_UPGRADE_TEST`: The image will be run on the next
133-
reboot, but it will be reverted if it doesn't get confirmed. The image needs
134-
to confirm itself to become permanent.
132+
- `CONFIG_CHIP_OTA_REQUEST_UPGRADE_PERMANENT`: From the next reboot, this image
133+
will be run permanently.
134+
- `CONFIG_CHIP_OTA_REQUEST_UPGRADE_TEST`: The image will be run on the next
135+
reboot, but it will be reverted if it doesn't get confirmed. The image needs
136+
to confirm itself to become permanent.
135137

136138
By default, the upgrade type used is `CONFIG_CHIP_OTA_REQUEST_UPGRADE_TEST`, and
137139
OTA image confirms itself during the initialization stage after the fundamental
@@ -162,11 +164,11 @@ to generate the OTA update Image. You can do this by adding
162164

163165
The current implementation automates the following procedures:
164166

165-
- Generation of the Image to be used for update (File generated:
166-
`zephyr/zephyr.bin`)\*
167-
- Signature of the Image (File generated: `zephyr/zephyr.signed.bin`)\*
168-
- Conversion of the signed Image into the OTA format (.ota file) (File
169-
generated: `zephyr/matter.ota`)\*
167+
- Generation of the Image to be used for update (File generated:
168+
`zephyr/zephyr.bin`)\*
169+
- Signature of the Image (File generated: `zephyr/zephyr.signed.bin`)\*
170+
- Conversion of the signed Image into the OTA format (.ota file) (File
171+
generated: `zephyr/matter.ota`)\*
170172

171173
> **Note**: \*All paths are relative to the output folder.
172174
@@ -177,10 +179,10 @@ Update. The instructions below describes the procedure step-by-step.
177179

178180
Setup example :
179181

180-
- [Chip-tool](../../../examples/chip-tool/README.md) application running on
181-
the RPi.
182-
- OTA Provider application built on the same RPi (as explained below).
183-
- Board programmed with the example application (with the instructions above).
182+
- [Chip-tool](../../../examples/chip-tool/README.md) application running on the
183+
RPi.
184+
- OTA Provider application built on the same RPi (as explained below).
185+
- Board programmed with the example application (with the instructions above).
184186

185187
Before starting the OTA process, the Linux OTA Provider application can be built
186188
on the RPi (if not already present in the pre-installed apps) :

‎examples/contact-sensor-app/nxp/README.md‎

Lines changed: 17 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,12 @@
11
# Matter NXP Contact Sensor Example Application
22

3-
- [Overview](#overview)
4-
- [Supported Platforms](#supported-platforms)
5-
- [Environment Setup, Building, and Testing](#build)
6-
- [Data Model](#data-model)
7-
- [Manufacturing Data](#factory-data)
8-
- [Long Idle Time ICD Support](#long-idle-time-icd-support)
9-
- [Low Power](#low-power)
3+
- [Overview](#overview)
4+
- [Supported Platforms](#supported-platforms)
5+
- [Environment Setup, Building, and Testing](#build)
6+
- [Data Model](#data-model)
7+
- [Manufacturing Data](#factory-data)
8+
- [Long Idle Time ICD Support](#long-idle-time-icd-support)
9+
- [Low Power](#low-power)
1010

1111
<a name="overview"></a>
1212

@@ -43,13 +43,16 @@ a QR code or printed to the device's UART console.
4343

4444
The Contact Sensor example is supported on the following platforms:
4545

46-
| NXP platform | Dedicated readme |
47-
| ------------ | ------------------------------------------------------------------- |
48-
| MCXW72 | [NXP MCXW72 Guide](../../../docs/platforms/nxp/nxp_mcxw72_guide.md) |
46+
| NXP platform | Dedicated readme |
47+
| --------------------- | ------------------------------------------------------------------- |
48+
| MCXW72 (FreeRTOS) | [NXP MCXW72 Guide](../../../docs/platforms/nxp/nxp_mcxw72_guide.md) |
49+
| MCXW72 (Zephyr, exp.) | [NXP Zephyr Guide](../../../docs/platforms/nxp/nxp_zephyr_guide.md) |
4950

5051
For details on platform-specific requirements and configurations, please refer
5152
to the respective platform's readme.
5253

54+
> **Note**: MCXW72 support under the Zephyr build flow is **experimental**.
55+
5356
A list of popular standard contact sensor app build targets is presented below.
5457
These targets can be used with the `build_example.py` tool.
5558

@@ -71,8 +74,10 @@ where `device` is one of the [supported platforms](#supported-platforms).
7174
All the information required to set up the environment, build the application,
7275
and test it can be found in the common readme for NXP platforms:
7376

74-
- NXP FreeRTOS Platforms : Refer to the
75-
[CHIP NXP Examples Guide for FreeRTOS platforms](../../../docs/platforms/nxp/nxp_examples_freertos_platforms.md)
77+
- NXP FreeRTOS Platforms : Refer to the
78+
[CHIP NXP Examples Guide for FreeRTOS platforms](../../../docs/platforms/nxp/nxp_examples_freertos_platforms.md)
79+
- NXP Zephyr Platform (experimental, MCXW72) : Refer to the
80+
[NXP Examples Guide for Zephyr platform](../../../docs/platforms/nxp/nxp_zephyr_guide.md)
7681

7782
<a name="data-model"></a>
7883

0 commit comments

Comments
 (0)