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 an external 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:

• On a single DK using the serial shell and Provisioning with CLI.

• With the Aliro Test Harness acting as the User Device (see Testing).

Application features

The Aliro Access Control Application supports the following capabilities:

• Aliro over NFC — Default tap-to-unlock transport. See NFC integration in the reference applications.

• Aliro over Bluetooth LE and UWB — Optional hands-free unlock. See Bluetooth LE transport and UWB integration in the reference applications.

• CLI provisioning — Provision reader credentials through shell. See Provisioning with CLI.

• Device Firmware Update over SMP — Field updates over Bluetooth LE (enabled by default). See Firmware update and DFU SMP service.

• Nordic UART Service — Optional Bluetooth LE command channel. See NUS service.

• Advanced Aliro phases — Optional expedited-fast and step-up authentication. See Advanced Aliro protocol features.

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. By default, the in-tree stub_impl is built as the backend for the UWB facade. Provide a functional UWB implementation as described in Integrating a UWB implementation to make the Aliro UWB transport operational.
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.
CONFIG_DOOR_LOCK_DFU_SMP_SERVICE	Enables Device Firmware Update over Bluetooth LE SMP. Enabled by default.

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:

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 with SMP DFU enabled. Use the following variants when you need Bluetooth LE with UWB, optional Bluetooth LE services, or release optimizations.

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.

Variant	Example build command
Aliro standalone (NFC only)	west build -p -b <build_target> applications/aliro-access-control-app
Aliro over Bluetooth LE and UWB	west build -p -b <build_target> applications/aliro-access-control-app -- -DCONFIG_DOOR_LOCK_BLE_UWB=y Builds the in-tree UWB stub by default. Provide a UWB backend as described in Integrating a UWB implementation.
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='bt_nus'.
Disable SMP DFU	west build -p -b <build_target> applications/aliro-access-control-app -- -DCONFIG_DOOR_LOCK_DFU_SMP_SERVICE=n
Release build	west build -p -b <build_target> applications/aliro-access-control-app -- -DFILE_SUFFIX=release Combine with snippets when needed.

The CONFIG_DOOR_LOCK_BLE_UWB Kconfig option enables the Bluetooth LE and Aliro UWB transport. By default, DOOR_LOCK_ALIRO_UWB_IMPL selects the in-tree stub_impl implementation, in which all methods return -ENOSYS. This lets the application build and run without ranging support. To get working ranging, plug in a UWB implementation as described in Integrating a UWB implementation.

Flash and verify

After building, flash the firmware:

west flash

Verify that the application runs correctly:

Debug configurationRelease configuration

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

With the default in-tree stub, UWB reports as not implemented and the application continues without ranging.

Dependencies

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

• Aliro stack (binary library in lib/aliro)

• Aliro Access Manager

• Lock simulator

• NFC integration in the reference applications — NFC transport and RFAL driver

• PSA Crypto

The application uses MCUboot for image management.

The application depends on the following Zephyr facilities:

• Logging

• Kernel Services

• Bluetooth host stack (when Bluetooth LE features or UWB transport are enabled)