Build Guide — ORA Matter Firmware

End-to-end steps for building, flashing, and commissioning a Matter device on Nordic nRF54L15 using NCS v3.2.2.

1. Prerequisites

nRF Connect SDK v3.2.2 installed under ~/ncs/v3.2.2/.
Toolchain at ~/ncs/toolchains/927563c840/.
Python venv at ~/ncs/v3.2.2/ora/blinky/.venv/ (West v1.5.0 lives here).
nRF54L15 DK connected over USB.
nrfutil in $PATH.

2. Project layout (per device)

<device>/
├── CMakeLists.txt
├── prj.conf
├── sysbuild_internal.conf
├── boards/
│   ├── nrf54l15dk_nrf54l15_cpuapp.overlay              # base
│   ├── nrf54l15dk_nrf54l15_cpuapp_internal.overlay     # our pin map
│   └── nrf54l15dk_nrf54l15_cpuapp_internal.conf
├── src/
│   ├── main.cpp
│   ├── app_task.cpp / .h
│   ├── zcl_callbacks.cpp        # Matter cluster handlers
│   └── default_zap/
│       ├── <device>.zap          # source of truth (edit via ZAP GUI)
│       ├── <device>.matter       # generated
│       └── zap-generated/        # generated; READ-ONLY
└── HANDOVER.md

3. Build (one-shot script)

Replace PROJECT with the actual device folder name.

cat > /tmp/build_PROJECT.sh << 'EOF'
#!/bin/bash
source /home/voltex-aura/ncs/v3.2.2/ora/blinky/.venv/bin/activate
TC=/home/voltex-aura/ncs/toolchains/927563c840
CHIP_CERT=/home/voltex-aura/chip/third_party/openthread/ot-realtek/third_party/Realtek/rtl87x2g_sdk/subsys/matter/vendor/factory_data/tool
export PATH=$CHIP_CERT:$TC/bin:$TC/usr/bin:$TC/usr/local/bin:$TC/opt/bin:$TC/nrfutil/bin:$PATH
export LD_LIBRARY_PATH=$TC/lib:$TC/lib/x86_64-linux-gnu:$TC/usr/local/lib
export ZEPHYR_SDK_INSTALL_DIR=$TC/opt/zephyr-sdk
export ZEPHYR_TOOLCHAIN_VARIANT=zephyr
export ZEPHYR_BASE=/home/voltex-aura/ncs/v3.2.2/zephyr
export NRFUTIL_HOME=$TC/nrfutil/home
west build -p -b nrf54l15dk/nrf54l15/cpuapp \
  -s /home/voltex-aura/ncs/v3.2.2/ora/PROJECT \
  -d /home/voltex-aura/ncs/v3.2.2/ora/PROJECT/build \
  -- -DFILE_SUFFIX=internal
EOF
chmod +x /tmp/build_PROJECT.sh && bash /tmp/build_PROJECT.sh

4. Flash

TC=/home/voltex-aura/ncs/toolchains/927563c840
HEX=/home/voltex-aura/ncs/v3.2.2/ora/PROJECT/build/merged.hex
export PATH=$TC/nrfutil/bin:$TC/bin:$PATH
export NRFUTIL_HOME=$TC/nrfutil/home
SN=$(nrfutil device list 2>&1 | head -1)
nrfutil device recover --serial-number $SN
nrfutil device recover --serial-number $SN     # twice
nrfutil device program --firmware $HEX --serial-number $SN --core Application
nrfutil device reset --serial-number $SN

5. Watch logs

stty -F /dev/ttyACM0 115200 raw -echo
cat /dev/ttyACM0    # or: picocom -b 115200 /dev/ttyACM0

6. Regenerate ZAP (only after editing the .zap)

cd /home/voltex-aura/ncs/v3.2.2/ora/PROJECT
west zap-generate                              # single .zap
west zap-generate -z src/default_zap/foo.zap   # multiple .zap files

7. Gotchas

FILE_SUFFIX=internal is required — picks up the internal-flash overlay/Kconfig variant.
gpio2 (P2.x) has no GPIOTE on nRF54L15 — interrupts impossible on P2 pins. Buttons must live on P0 or P1.
RRAMC protected region on flash? Run nrfutil device recover first (sometimes twice).
Never hand-edit anything in src/default_zap/zap-generated/ — regenerated on every west zap-generate.
ZAP path fix: some .zap files reference /home/voltex-aura/modules which doesn't exist. Symlink it to /home/voltex-aura/ncs/v3.2.2/modules.