Skip to main content
Korlinx

Getting Started with Matter Quickly on NX Families

This tutorial is the shortest path from a connected NX development board to a commissioned Matter device.

You will flash a validated firmware package, commission the device over Bluetooth Low Energy, join it to a Thread network, and verify one Matter command. You do not need to build the firmware from source in this tutorial.

caution

Publication gate Do not publish this tutorial until KORLINX provides a tested prebuilt firmware package, setup code, supported board list, flash procedure, LED and button behavior, and validated commissioner ecosystem.

What you will do​

  1. Download the validated Matter sample.
  2. Connect the NX development board.
  3. Erase and flash the firmware.
  4. Confirm Bluetooth Low Energy advertising.
  5. Commission the device using its QR code or manual pairing code.
  6. Join the device to Thread.
  7. Send a Matter command and confirm the device response.
NX Families tutorial: Download to Connect to Flash to BLE Commission to Join Thread to Control

Required hardware​

ItemRequirement
NX development platform[CONFIRM: NX15, NX40, or both]
USB cableData-capable cable compatible with the selected board
Development hostComputer with the environment from the previous tutorial
Commissioner/controller[CONFIRM: Google Home, Apple Home, CHIP Tool, or another tested option]
Thread Border RouterRequired for the Matter over Thread workflow
Local networkThe controller and Border Router must be reachable as required by the selected setup

Required files and information​

Before continuing, obtain all items listed below from the KORLINX release location.

ItemWorking placeholder
Firmware package[FIRMWARE_FILE]
Firmware version[FIRMWARE_VERSION]
SHA-256 checksum[SHA256]
Supported hardware revision[HW_REVISION]
Setup QR code[QR_CODE_FILE_OR_URL]
Manual pairing code[MANUAL_PAIRING_CODE]
Expected serial settings[SERIAL_SETTINGS]
Expected LED/button behavior[BOARD_UI_BEHAVIOR]
warning

Development credentials only Use only the setup code and test credentials supplied with the validated development package. Do not copy credentials from screenshots, third-party tutorials, or another device.

Step 1: Download and verify the firmware package​

  1. Download [FIRMWARE_FILE] from [KORLINX_RELEASE_URL].
  2. Confirm that the package supports your NX board and hardware revision.
  3. Calculate the SHA-256 checksum.

On Linux:

sha256sum [FIRMWARE_FILE]

On macOS:

shasum -a 256 [FIRMWARE_FILE]

On Windows PowerShell:

Get-FileHash [FIRMWARE_FILE] -Algorithm SHA256
  1. Compare the result with the published checksum.

Do not flash the package if the checksum does not match.

NX Families tutorial: Firmware release metadata beside a successful SHA-256 comparison

Step 2: Connect the NX development board​

  1. Disconnect external loads that are not required by the sample.
  2. Connect the board to the development host using the approved USB or debug connection.
  3. Open an SDK terminal.
  4. Confirm that the device is detected:
nrfutil device list
  1. Record the device identifier and serial port.
NX Families tutorial: NX board, USB/debug port, power state, and any required jumper positions

Step 3: Erase and flash the prebuilt firmware​

Use the validated KORLINX programming method.

Using Programmer​

  1. Open Programmer in nRF Connect for Desktop.
  2. Select the connected device.
  3. Select Add file and open [FIRMWARE_FILE].
  4. Confirm that the memory layout is accepted.
  5. Select the approved erase option.
  6. Select Write or Erase and Write.
  7. Wait for the programming and verification steps to complete.
NX Families tutorial: Device selection to Add file to memory map to erase option to successful write verification

Step 4: Open the serial log​

  1. Open the validated serial terminal.
  2. Select the recorded serial port.
  3. Apply [SERIAL_SETTINGS].
  4. Reset the board.
  5. Confirm that the expected Matter sample log appears.

The pass condition must include a KORLINX-approved log message such as:

[EXPECTED_UNCOMMISSIONED_OR_ADVERTISING_LOG]
NX Families tutorial: First complete boot after flashing with the expected advertising state highlighted

Step 5: Confirm the commissioning window​

After startup, the sample should enter a commissionable state and advertise over Bluetooth Low Energy for a limited period.

Confirm the state using the approved LED behavior or serial log.

If the commissioning window has closed, use the validated button action or reset procedure to open it again.

Commissioning action: [CONFIRM_BUTTON_OR_RESET_ACTION]
Advertising duration: [CONFIRM_DURATION]
Expected LED state: [CONFIRM_LED_PATTERN]

Step 6: Obtain the onboarding code​

Use one of the following values supplied with the validated firmware package:

  • Matter setup QR code
  • Manual pairing code
  • Pairing payload displayed in the approved serial log

Do not publish a shared development passcode as if it were suitable for production.

NX Families tutorial: Clearly labeled development-only example with all real credentials replaced

Step 7: Commission the NX device​

The exact screens depend on the validated commissioner. The required flow is:

  1. Open the selected Matter commissioner application.
  2. Choose Add device or the equivalent command.
  3. Scan the QR code or enter the manual pairing code.
  4. Keep the NX device close enough for the Bluetooth Low Energy commissioning connection.
  5. Select or confirm the target Matter fabric.
  6. Allow the commissioner to transfer the Thread Operational Dataset.
  7. Wait until the device joins the Thread network.
  8. Assign the device name and room if the application requests them.
NX Families tutorial: Add device to scan code to connect to credential setup to Thread join to success

:::note Bluetooth Low Energy and Thread Bluetooth Low Energy is used to open and complete the commissioning session. After commissioning, normal Matter application commands in this workflow use IPv6 over Thread. :::

Step 8: Verify the Matter command​

Open the commissioned device in the selected controller and perform the function implemented by the sample.

For a light sample:

  1. Send On.
  2. Confirm that the assigned LED or load turns on.
  3. Send Off.
  4. Confirm that the assigned LED or load turns off.
  5. Check the serial log for the corresponding application event.
NX Families tutorial: Controller showing On/Off and NX board showing the matching physical state

Expected result​

The Quick Start is complete when:

  • The validated firmware is programmed successfully.
  • The device opens a Bluetooth Low Energy commissioning window.
  • The commissioner accepts the onboarding code.
  • The device joins the selected Thread network.
  • The device appears in the Matter controller.
  • The sample responds to the expected Matter command.
  • The serial log shows the expected commissioned and operational state.

Troubleshooting​

ProblemAction
Firmware checksum does not matchDownload the package again and confirm that the correct board variant was selected.
Programmer cannot detect the boardCheck the cable, power, debugger connection, USB permissions, and device selection.
No Bluetooth Low Energy advertisement is foundReset the board or use the validated action to reopen the commissioning window.
QR code is rejectedConfirm that the QR code belongs to the exact firmware instance and that the device has been reset to the expected state.
Commissioning stops while configuring ThreadConfirm the Thread Border Router, dataset, local network, and controller compatibility.
Device was already commissionedRemove it from the previous fabric or perform the validated factory-reset procedure.
Matter command has no physical effectConfirm the correct device type, endpoint, LED mapping, and sample firmware.

Developer reference keywords​

  • Matter commissioning window
  • Bluetooth LE advertising
  • Matter setup payload
  • manual pairing code
  • Matter fabric
  • Thread Operational Dataset
  • Thread Border Router
  • Matter controller
  • device attestation
  • factory reset

Official references​

🎉 You're Ready!​

Your First NX Matter Device Is Commissioned​

You've flashed a validated sample, commissioned the NX device over Bluetooth Low Energy, and controlled it over Thread.

You are now ready to build the same workflow from source.

Here's what you accomplished:​

  • ✅ Downloaded and verified the firmware package
  • ✅ Connected and programmed the NX development board
  • ✅ Confirmed the commissioning window
  • ✅ Used a Matter onboarding code
  • ✅ Commissioned the device over Bluetooth Low Energy
  • ✅ Joined the device to a Thread network
  • ✅ Sent and verified a Matter command

What's Next?​

Build from Source

Configure, build, flash, commission, and test the Matter sample from its source code.

Start Matter Development →

Framework Overview

Learn where the Matter Node, Endpoint, Clusters, and application callbacks are configured.

Explore the Framework →

Environment Setup

Review the SDK, toolchain, board detection, and serial-terminal setup.

Review the Environment →

Your NX device can now join a Matter fabric and respond over Thread. Continue by reproducing the result from the validated source release.