Application guide

This page describes hardware requirements, configuration, building, and verification for the Aliro Access Control Application. For firmware update procedures, see Firmware update. For Test Harness setup and provisioning, see Testing. For common issues, see Troubleshooting.

Requirements

The application supports the following development kits:

Supported hardware platforms

Hardware platforms

PCA

Board name

Build target

nRF54LM20 DK

PCA10184

nrf54lm20dk
nrf54lm20dk/nrf54lm20b/cpuapp
nrf54lm20dk/nrf54lm20a/cpuapp

nRF54L15 DK

PCA10156

nrf54l15dk

nrf54l15dk/nrf54l15/cpuapp

nRF5340 DK

PCA10095

nrf5340dk

nrf5340dk/nrf5340/cpuapp

nRF52840 DK

PCA10056

nrf52840dk

nrf52840dk/nrf52840

You also need an NFC reader expansion board connected to the DK. For Aliro over Bluetooth LE and UWB, add a QM35825 UWB module on the nRF5340 DK or nRF54LM20 DK.

See Hardware requirements for wiring diagrams, VDDIO configuration on nRF54L-series DKs, and the full hardware setup.

Overview

The Aliro Access Control Application implements an Aliro reader that authenticates User Devices and drives a simulated bolt lock through the Access Manager.

You can exercise the application in the following ways:

Application features

The Aliro Access Control Application supports the following capabilities:

This application does not integrate with Matter. For a Matter-enabled variant, see Matter and Aliro Door Lock Application.

Configuration

The following Kconfig options are useful when customizing prj.conf or build arguments. They are not required for the default NFC-only build.

Configuration option

Description

CONFIG_DOOR_LOCK_BLE_UWB

Enables Aliro over Bluetooth LE and UWB. When disabled, the application uses NFC-only Aliro transport. Prefer the uwb_qm35 snippet instead of enabling this option in isolation.

CONFIG_DOOR_LOCK_BLE_UWB_MAX_SESSIONS

Available when CONFIG_DOOR_LOCK_BLE_UWB is enabled. Sets the maximum number of concurrent Aliro Bluetooth LE and UWB sessions. When changing the session count, set CONFIG_BT_MAX_CONN to at least that value plus any connections used on the default identity by other services.

For Bluetooth LE transport and session-limit details, see Bluetooth LE transport.

Debug and release builds

Debug is the default configuration.

In release configuration, the application is built with the following characteristics:

  • All logs are disabled.

  • Power-management options are enabled.

  • Unused peripherals are disabled using the board-specific *_release.overlay.

  • The device resets automatically on a fatal error.

The application keeps the UART shell enabled in release builds so you can provision keys through the CLI (see Provisioning with CLI).

Aliro Access Control Application build configurations

Configuration

File name

FILE_SUFFIX

Supported board

Description

Debug (default)

prj.conf

No suffix

All from Requirements

Debug version of the application.

Enables additional features for verifying the application behavior, such as logs.

Release

prj_release.conf

release

All from Requirements

Release version of the application.

Enables only the necessary application functionality to optimize its performance.

To build in release mode:

west build -p -b <build_target> applications/aliro-access-control-app -- -DFILE_SUFFIX=release

User interface

The reference application exposes a minimal development kit interface. Lock actions are driven by Aliro authentication through the Access Manager, not by lock/unlock buttons as in the Matter door lock sample.

Development kit interface

Button 1:

When the application is built with the dfu_smp snippet, toggles Bluetooth LE advertising for DFU over SMP. You can also use the dfu_smp on and dfu_smp off shell commands.

LED 2:

When CONFIG_DOOR_LOCK_ALIRO_LOCK_SIM_INDICATOR is enabled (default), shows the simulated lock state through the lock-sim-indicator devicetree alias:

  • On — Bolt is retracted (unlocked).

  • Off — Bolt is extended (locked).

The LED stays on for the simulated movement time and any configured auto-relock period. See Lock simulator for lock simulator timing options.

SEGGER J-Link USB port:

Used for logs and the UART shell (provisioning commands).

Building and running

This application can be found under ncs-door-lock-and-access-control/applications/aliro-access-control-app in your folder structure.

To build it, follow the instructions in Building an application for your preferred building environment. See also programming for programming steps and testing for general information about testing and debugging in the nRF Connect SDK.

  1. Connect the DK to your computer using the DEBUGGER port and set the POWER switch to ON.

  2. In the project-workspace directory, navigate to the ncs-door-lock-and-access-control folder.

  3. Build the application for your DK and NFC reader expansion board. Find <build_target> for your DK in the table in Requirements or in Development kit.

    NFC reader expansion board

    Extra CMake argument

    Notes

    X-NUCLEO-NFC12A1

    —

    Recommended for new designs.

    X-NUCLEO-NFC09A1

    -DCONFIG_ST25R200_DRV=y

    Supported, but not recommended for new products.

    Example for the nRF5340 DK with X-NUCLEO-NFC12A1:

    west build -p -b nrf5340dk/nrf5340/cpuapp applications/aliro-access-control-app

    Example for the nRF54L15 DK with X-NUCLEO-NFC09A1:

    west build -p -b nrf54l15dk/nrf54l15/cpuapp applications/aliro-access-control-app -- -DCONFIG_ST25R200_DRV=y

  4. Flash the firmware:

    west flash

  5. Verify that the application runs (see Flash and verify).

Build variants

The default quick-start build is Aliro over NFC only. Use the variants below when you need Bluetooth LE with UWB, optional Bluetooth LE services, release optimizations, or QM35 firmware update support.

Replace <build_target> with your DK target from Development kit. For UWB hardware setup, see Ultra-wideband (UWB) module and UWB integration in the reference applications.

Note

Support for the Qorvo QM35825 UWB example implementation is currently experimental.

Variant

Example build command

Aliro standalone (NFC only)

west build -p -b <build_target> applications/aliro-access-control-app

QM35825 UWB

west build -p -b <build_target> applications/aliro-access-control-app -- -Daliro-access-control-app_SNIPPET=uwb_qm35 See Aliro QM35 SDK repository for the required workspace setup.

SMP DFU over Bluetooth LE

west build -p -b <build_target> applications/aliro-access-control-app -- -Daliro-access-control-app_SNIPPET=dfu_smp See Firmware update and DFU SMP service.

Nordic UART Service (NUS)

west build -p -b <build_target> applications/aliro-access-control-app -- -Daliro-access-control-app_SNIPPET=bt_nus See NUS service.

Combined snippets

Separate snippet names with semicolons, for example -Daliro-access-control-app_SNIPPET='uwb_qm35;dfu_smp'.

QM35 firmware update (DFU)

Pass the sysbuild uwb_qm35_dfu snippet together with uwb_qm35, for example -- -DSNIPPET=uwb_qm35_dfu -Daliro-access-control-app_SNIPPET=uwb_qm35. You must add dfu_smp to the application snippet when you update the main application over SMP. See Firmware update.

Release build

west build -p -b <build_target> applications/aliro-access-control-app -- -DFILE_SUFFIX=release Combine with snippets when needed.

QM35 front/back disambiguation

Add -DCONFIG_DOOR_LOCK_ALIRO_UWB_QM35_FRONT_BACK_DETECTION=y to a QM35 UWB build. See UWB front/back disambiguation.

The uwb_qm35 snippet enables the CONFIG_DOOR_LOCK_BLE_UWB Kconfig option and configures the board overlay so the NFC and UWB modules share the same SPI bus. Use the snippet rather than setting CONFIG_DOOR_LOCK_BLE_UWB alone, which enables the transport without the Qorvo QM35825 implementation. The snippet uses the UWB stack and QM35 host driver from the qm35-aliro-sdk repository, so you must first add it to your workspace (see Aliro QM35 SDK repository).

Example for the nRF5340 DK with QM35825 UWB:

west build -p -b nrf5340dk/nrf5340/cpuapp applications/aliro-access-control-app -- \
    -Daliro-access-control-app_SNIPPET=uwb_qm35

Example for the nRF54LM20 DK with QM35825 UWB:

west build -p -b nrf54lm20dk/nrf54lm20b/cpuapp applications/aliro-access-control-app -- \
    -Daliro-access-control-app_SNIPPET=uwb_qm35

Flash and verify

After building, flash the firmware:

west flash

Verify that the application runs correctly:

Connect to the DK with a terminal emulator that supports VT100/ANSI escape characters. The Serial Terminal app is recommended. See Testing and optimization in the nRF Connect SDK documentation for serial settings.

Note

This application has Hardware Flow Control mechanism enabled by default in serial communication. When enabled, it allows devices to manage transmission by informing each other about their current state, ensuring more reliable connection in high-speed communication scenarios.

Press RESET on the DK. You should see the Zephyr boot banner and a line similar to:

Starting nRF Door Lock and Access Control Application

When QM35 UWB is enabled, you should also see UWB initialization logs ending with:

uwb: Initializing UWB device...
uwb: UWB device initialized successfully.

An Awake frame not received line from hsspi_helpers can appear during init and does not necessarily indicate a fault if initialization completes successfully.

If UWB initialization fails on first boot, complete Initial QM35 module programming before retesting.

Dependencies

This application uses the following nRF Door Lock and Access Control Add-on and nRF Connect SDK components:

When DFU is enabled, the application also uses MCUboot for image management.

The application depends on the following Zephyr facilities: