ultrawidelock/ultrawidelock: implements Aliro, the CSA door-lock credential standard, over BLE

Portable firmware for NFC and UWB smart locks.

UltraWideLock implements Aliro, the CSA door-lock credential standard, over BLE, NFC and UWB on real hardware. One portable core behind five HAL seams drives four lock applications, a second UWB anchor and standalone reader, initiator, anchor and witness examples, across Zephyr, ESP-IDF and FreeRTOS.

Features

Quick start

The host suite needs a C compiler and python3.

git clone https://github.com/ultrawidelock/ultrawidelock.git
cd ultrawidelock
make check

Bare targets build for the Qorvo DWM3001CDK.

make dfu-key                # once per clone   · the image-signing key
make bootstrap              # once per machine · NCS v3.3.0
make build                  # -> build/cdk-matter
make flash
make monitor

Adding the key needs an iPhone with UWB on iOS 26 or later, a home hub and a Thread border router: add the key.

make help lists every target. make tools reports what this machine is missing.

Unlock sequence

Boards

make nrf-build && make nrf-flash && make nrf-term    # nRF5340 DK
make esp-bootstrap && make esp-go APP=matter-lock TARGET=esp32s3
make freertos-build && make freertos-flash           # the Zephyr-free port
make sat-build && make sat-flash                     # the satellite
make hitl                                            # unattended end-to-end bench

Apple Home and Home Assistant share one CDK and one Thread network: the multi-admin guide.

_{Home Key · Approach Direction · provisioning · NFC tap · live lock state}

Updates

ultrawidelock.com/flash finds the board, reads what it is running and sends the one update that applies. Chrome or Edge on a computer, Chrome on Android.

Writing starts once the update window is open on the board: SW2 on the CDK, a double-click on the ESP32's button. Authenticity is a P-256 signature, checked before the first byte is written and again by the bootloader.

The CDK also reinstalls whole over that cable through MCUboot serial recovery, which runs from the bootloader alone.

make fota                   # CDK: one file a phone can install
make fota-done              # after every phone push, to record what the board runs
make ota-fan  PREV_HEXES=…  # the delta fan and the index the web page reads
make release  RELEASE_KEY=… # the published bundle

make fota-done is required: a CDK delta is cut against the exact bytes on the part, and only the build host keeps that record.

In a browser

ultrawidelock.com is generated from this tree by stdlib Python. make docs-serve serves it on localhost:8080.

The twin compiles the untouched modules/ultrawidelock_uwb sources against the host shim the test suite links, so every block is a real CCM*-encrypted exchange decoded by the firmware's own RX state machine.

Verification

make check                  # 18 host suites, 9,608 checks, no hardware
make ci                     # every pull-request gate, in CI's order
make regress                # everything a machine can check without a board
make regress-hil            # and then on air, against a live reader

make sdk-check builds an out-of-tree C consumer against the installed CMake package. make app-diff diffs this tree's door-lock app against pinned upstream. make instrument serves a latency dashboard captured from a real board.

SDK

#include <ultrawidelock/reader.h>     // the lock side
#include <ultrawidelock/device.h>     // the initiator side
#include <ultrawidelock/tlv.h>        // the codec alone

Ports implement the five seams in <ultrawidelock/ultrawidelock_hal.h>: DW3000 GPIO/IRQ, DW3000 SPI, reader BLE, central BLE and credential storage. New board or chipset: PORTING.md. Consuming the CMake package directly: reference.

Documentation

Repository layout

ultrawidelock/
├── apps/           complete lock products
├── examples/       independently buildable role and bench examples
├── modules/        the portable protocol, with no OS in it
│   ├── ultrawidelock_cred/       credential sessions, TLV, key ladder
│   ├── ultrawidelock_cred_stack/ that stack, adapted into the Nordic app
│   ├── ultrawidelock_uwb/        ranging engine behind the STS seam
│   ├── ultrawidelock_dw3000/     DW3000 driver integration
│   ├── ultrawidelock_anchor/     side of door: fusion, latch, witnesses, seal
│   ├── ultrawidelock_matter/     the hand-written Matter node
│   ├── ultrawidelock_ml/         on-device classifiers
│   ├── ultrawidelock_nfc/        ECP and reader transports
│   ├── ultrawidelock_dfu/        signed delta updates
│   └── ultrawidelock_port/       the OS, flash, log and byte-order contracts
├── ports/          zephyr · esp32 · freertos-nrf52833
├── integrations/   patches for external upstream applications
├── tests/          host, shared, port, tooling, sdk, on-target
├── include/        SDK umbrella and public-API ownership
├── cmake/          shared CMake helpers
├── mk/             what sits behind each Make target
├── scripts/        setup, release, DFU, sizing, device utilities
├── docs/           the guides, read on GitHub and published to the site
├── web/            the site, the flasher, the WASM twin, the graph
└── release/        templates and scripts for release bundles

_{A Wallet home key, on approach, recorded on hardware.}

FAQ

What is needed to add the key? An iPhone with UWB on iOS 26 or later, a home hub such as a HomePod or Apple TV, and the network the target joins: a Thread border router for the nRF boards, 2.4 GHz Wi-Fi for ESP32. The image ships no credential; Apple Home mints the Aliro key during Matter commissioning.

Which board should come first? The Qorvo DWM3001CDK. It carries the nRF52833, the DW3110 radio and a J-Link on one module, and every bare make target builds for it.

Can it be tried without hardware? Yes. make check runs the whole host suite, and the digital twin runs the firmware's own ranging engine in a browser.

Does the phone have to be awake? No. An NFC tap is validated in Express Mode with the screen off (HV-5).

Where does the console come from? RTT, not UART. make monitor attaches with the ELF that was flashed. The ring survives reset, so the first block belongs to the previous run.

What does make flash-erase cost? The commissioning. Apple Home has to add the lock again, and Home Assistant has to be shared again afterward.

Can one lock open another? Yes. make build CLIENT=1 compiles the Matter client role, which opens a bound lock over CASE through the Binding cluster.

[!WARNING] These are bench defaults. Do not secure valuables with them, and never lock APPROTECT: recovery needs a mass erase, which takes the reader's private key and every phone key on it. scripts/check-approtect.sh checks a part.