NXP

K32W

This example functions as a light bulb device type, with on/off capabilities. The steps were verified on NXP K32W development board (IOTZTB-DK006 development kit).

Initial setup

Make sure you have Python3 and these packages installed. The steps in this document were validated with Python 3.8.
Download and install K32W061 MCUXpresso SDK 2.6.9.
Once the SDK is built, download the SDK package and extract it to your home directory. Set the environment variable NXP_K32W0_SDK_ROOT to where you extracted the SDK. We also recommend adding this command to the .*rc file for the shell you are using, such as .zshrc:
```
export NXP_K32W0_SDK_ROOT=$HOME/SDK_2_6_9_K32W061DK6/
```

Clone and initialize the NXP/Micro repo:

git clone https://github.com/NXPmicro/matter.git
cd matter
git fetch origin v1.0-branch-nxp
git checkout FETCH_HEAD
git submodule update --init --recursive
source ./scripts/activate.sh

The example uses the "Generic Switch Node" configuration. Make sure that jumpers JP4/JP7 are situated in the left-most position (LPC-JN UART0):

Reconfigure the board for JLink

Download and install JLink on your computer.
On the board, make sure DFU is selected on the BOOT jumper next to the USB port, and connect the board to your computer with a mini USB cable.
Download and install LPCScrypt on your computer.
1. For MacOS, double click on the downloaded package to install it.
2. For Linux, go to the folder where you download the package:
```
chmod +x lpcscrypt-2.1.2_57.x86_64.deb.bin
./lpcscrypt-2.1.2_57.x86_64.deb.bin
```
Once LPCScrypt is installed, execute this script to reprogram your board (replace <LPCScrypt_InstallDir> with the actual installation path of LPCScrypt):
```
<LPCScrypt_InstallDir>/scripts/program_JLINK
```
Note: On some occasions it was found that USB hubs such as Cambrionix might interfere with the enumeration of the board. If you have a irresponsive system while flashing the JLink Firmware, try having the NXP target as the only USB device attached to your computer.

You should see messages similar to the below. Press Space to start programming. When finished, press Enter to exit.

LPCScrypt - J-Link firmware programming script v2.1.2 Nov 2020.

Connect an LPC-Link2 or LPCXpresso V2/V3 Board via USB then press Space.
Booting LPCScrypt
.
LPCXpresso V2/V3 programmed with
Firmware_JLink_LPCXpressoV2_20190404.bin
-To use: remove DFU link and reboot the board

Connect next board then press Space (or <return> to Quit)

Unplug the board and switch the BOOT jumper back to NORMAL. Your board is now reconfigured to use JLink for flashing an image.

Build the image

Prepare the repo:
```
source ./scripts/activate.sh
```
Install dependencies:
```
pip3 install pycrypto pycryptodome
```
Update the VENDOR_ID in your example project config (CHIPProjectConfig.h). This should be your VID as per the CSA Matter specification, or a VID allocated for testing purposes. The value you provide for VENDOR_ID must match the one you use when creating the Matter integration in the Google Home Developer Console.
```
grep VENDOR_ID ./examples/lighting-app/nxp/k32w/k32w0/include/CHIPProjectConfig.h
```
```
 * CHIP_DEVICE_CONFIG_DEVICE_VENDOR_ID
#define CHIP_DEVICE_CONFIG_DEVICE_VENDOR_ID your-hex-VID
```
Check the PRODUCT_ID in your example project config (CHIPProjectConfig.h). The PRODUCT_ID value can remain the same as the example's default, or changed as desired, but it must adhere to the current Product ID restrictions described in the Prerequisites. Also note that the value you provide for PRODUCT_ID must match the one you use when creating the Matter integration in the Developer Console.
```
grep PRODUCT_ID ./examples/lighting-app/nxp/k32w/k32w0/include/CHIPProjectConfig.h
```
```
 * CHIP_DEVICE_CONFIG_DEVICE_PRODUCT_ID
#define CHIP_DEVICE_CONFIG_DEVICE_PRODUCT_ID 0x4B4C
```

Build the lighting app:

If the OM15082 expansion board is attached to your K32W board, make sure to set the chip_with_OM15082 build argument to 1:

cd examples/lighting-app/nxp/k32w/k32w0/
gn gen out/debug --args="k32w0_sdk_root="${NXP_K32W0_SDK_ROOT}" chip_with_OM15082=1 chip_with_ot_cli=0 is_debug=false chip_crypto="platform" chip_with_se05x=0 chip_pw_tokenizer_logging=true chip_enable_ota_requestor=false"
ninja -C out/debug

If the OM15082 expansion board is not attached, omit the chip_with_OM15082 build argument:
```
cd examples/lighting-app/nxp/k32w/k32w0/
gn gen out/debug --args="k32w0_sdk_root="${NXP_K32W0_SDK_ROOT}" chip_with_ot_cli=0 is_debug=false chip_crypto="platform" chip_with_se05x=0 chip_pw_tokenizer_logging=true chip_enable_ota_requestor=false"
ninja -C out/debug
```
Note that the Pigweed tokenizer, which is a pigweed module that allows hashing the strings to greatly reduce the flash needed for logs, is enabled above by setting the chip_pw_tokenizer_logging to true. The detokenizer script will be needed for parsing the hashed scripts. See here for more information.

For MacOS users (skip this step if you are NOT building on MacOS):

Open the sign_images.sh script (located at $NXP_K32W0_SDK_ROOT/tools/imagetool/sign_images.sh) in a text editor and make the following changes:
1. Comment out or remove these lines to resolve the "package not installed" error on MacOS:
```
is_linux_package_installed "python3"
is_linux_package_installed "python3-pip"
```
2. Fix the argument to the file utility ("-ib" should be "-Ib"), otherwise the signing script will silently fail to generate a .bin file:
```
MIME_SET="$(file -ib $FILENAME)"
```
  Change to:
```
MIME_SET="$(file -Ib $FILENAME)"
```

Sign the image:

chmod +x $NXP_K32W0_SDK_ROOT/tools/imagetool/sign_images.sh
$NXP_K32W0_SDK_ROOT/tools/imagetool/sign_images.sh out/debug/

Flash the board

Launch JLink command line with your board connected by a mini USB cable:
```
JLinkExe -device K32W061 -if SWD -speed 4000 -autoconnect 1
```

In JLink command line, enter the erase command to wipe out an existing image on the board. This is needed if you have flashed the board before.

erase
Without any give address range, Erase Chip will be executed
Erasing device...
J-Link: Flash download: Total time needed: 2.878s (Prepare: 0.051s, Compare: 0.000s, Erase: 2.789s, Program: 0.000s, Verify: 0.000s, Restore: 0.037s)
Erasing done.

Then flash the image using the loadbin command:

loadbin out/debug/chip-k32w061-light-example.bin, 0
Downloading file [out/debug/chip-k32w061-light-example.bin]...
J-Link: Flash download: Bank 0 @ 0x00000000: 1 range affected (586752 bytes)
J-Link: Flash download: Total: 7.492s (Prepare: 0.054s, Erase: 2.738s, Program & Verify: 4.661s, Restore: 0.037s)
J-Link: Flash download: Program & Verify speed: 122 KB/s
O.K.

Exit the JLink CLI by typing exit.

Relaunch JLink:

JLinkExe -device K32W061 -if SWD -speed 4000 -autoconnect 1

Flash the image again, skipping the erase command this time:

loadbin out/debug/chip-k32w061-light-example.bin, 0
Downloading file [out/debug/chip-k32w061-light-example.bin]...
J-Link: Flash download: Bank 0 @ 0x00000000: 1 range affected (586752 bytes)
J-Link: Flash download: Total: 7.492s (Prepare: 0.054s, Erase: 2.738s, Program & Verify: 4.661s, Restore: 0.037s)
J-Link: Flash download: Program & Verify speed: 122 KB/s
O.K.

Once the loadbin command is done, press the SW2 button on the expansion board to perform a factory reset, then press the SW4 RESET button on the main board to start running the image.

Validate the example

The device should present itself as a USB serial device on your computer. You may look it up in /dev/:
```
ls -la /dev/tty*
```
You can open the serial console with the python3 script detokenizer.py, which is a script that decodes the Pigweed tokenized logs from a serial port. For example, if the device is at /dev/ttyACM0:
```
python3 ./scripts/detokenizer.py serial -i /dev/ttyACM0 -d out/debug/chip-k32w061-light-example-database.bin
```

To factory reset the board, press the SW2 button. LED2 and LED3 will blink together for a while. You should see messages like this in serial console:

[Info]Factory Reset Triggered. Push the RESET button within 6000 ms to cancel!
[Info]Device will factory reset...
[Info]Performing factory reset

To toggle the lightbulb's state (on/off), click SW3 the button. It should toggle LED D3.

Commissioning prerequisites

Before commissioning the NXP K32W development board, be aware of the following:

BLE advertising must be enabled before the device can be discovered and commissioned within the Google Home ecosystem. To temporarily enable advertising (for 15 minutes, per the Matter specification), press the USERINTERFACE button.
Without a cryptographic hardware accelerator module, the K32 development board may not be able to complete commissioning before the flow times out from the Android mobile device side. You can identify that a timeout occurred by using adb logcat from a computer attached to your phone. When a timeout occurs, you will see a log message like:
```
Device connection failed. Error third_party/connectedhomeip/src/protocols/secure_channel/CASESession.cpp:275: CHIP Error 0x00000032: Timeout
```
See Troubleshooting for more information on setting up and using adb.

Next steps

When your Matter example has been successfully built, create a developer project.