Overview
openaliro/openaliro
Developer documentation
openaliro
BLE + UWB · one board · no app · no cloud · no vendor Aliro binary
$git clone https://github.com/openaliro/openaliro.git
422subsystems
84%documented
2449symbols
openaliro · zsh
$git clone https://github.com/openaliro/openaliro.git
$cd openaliro
$make dfu-key # 1 · once per clone · this checkout's image-signing key
$make bootstrap # 2 · once per machine · host tools + pinned NCS v3.3.0 (~8.5 GB)
$make build # 3 · the lock -> build/cdk-matter
$make flash # 4 · over the on-board J-Link, no external probe
$make monitor # 5 · the console, over RTT
$
Get running
- 1Clone the repository$git clone https://github.com/openaliro/openaliro.git
- 2Mint this checkout's signing key every image is signed and the key is gitignored, so a fresh clone or a new worktree fails at configure until it has one$make dfu-key
- 3Set the machine up host tools, the NCS v3.3.0 toolchain, then the SDK workspace (~8.5 GB) into ./workspace — anything already installed is skipped$make bootstrap
- 4Build the firmware the DWM3001CDK image lands in ./build/cdk-matter/merged.hex; make nrf-build builds the nRF5340 DK instead$make build
- 5Flash the board over the DWM3001CDK's on-board J-Link OB; make monitor then streams its RTT console$make flash
No toolchain? make test runs as-is. On an
ESP32-S3, C5 or C6, start at the
bring-up checklist. Once something is flashed,
Apple Home has to mint the key.
- ArchitectureEvery subsystem on one page, in reading order.
- HardwareESP32-S3 gotchas
- TroubleshootingTroubleshooting
- ModulesAll 422 modules, grouped by directory.
Guides
Set up
- InstallingThe DWM3001CDK is the primary target; the nRF5340 DK and the ESP32-S3, ESP32-C5 and ESP32-C6 apps port the same engine. No hardware needed until you flash.
- Add the keyFlashing a board is half the job. The image carries no credential: Apple Home mints the Aliro key during Matter commissioning, and until that happens the lock is a…
- ConfiguringThree layers: build options on the make command line, the Kconfig overlays behind them, and runtime consoles on the running reader.
- TroubleshootingCommon issues, grouped by target. Deeper protocol background is in
protocol-research.md(on-air behavior) andprotocol-notes.md(firmware time and credential… - Home AssistantBring the lock into Home Assistant: UWB distance and Aliro access events over MQTT, lock control over Matter. Beta, and gated behind
HA=1everywhere.
Hardware
- nRF5340 bring-upParts on the bench to a healthy first boot; toolchain install is in set-up.md.
- nRF5340 wiringEvery pin and every connection on the nRF bench stack in one table. Bring-up procedure is in nrf5340-bringup.md.
- ESP32 bring-up (S3, C5, and C6)One page, match-the-table. The pin map's source of truth is
ports/esp32/components/woz_uwb/port/board_pins.h; if you change it there, change it here. - Hardware validationAutomated CI gates the host-side logic (KAT suite, coverage floor, sanitizers, fuzz, CBMC, the ESP32 port suite), and a dispatch of
firmware-builds.yml…
Research
- Protocol researchThis report documents the on-air behavior of a phone-driven ultra-wideband (UWB) proximity unlock: how a phone opens a fixed reader on approach. The phone conducts…
- Time synchronizationFirmware-level notes on one subsystem: how the reader obtains wall-clock time, how that interacts with Aliro's time-based credential checks, and the fixes this repo…
- Wireshark dissector
tools/aliro.luaturns the reverse-engineering in protocol-research.md into something you can run against a live capture. It decodes the parts of an Aliro… - Approach DirectionHow the Apple Home app's "Approach Direction" control is exposed by an Aliro lock, and every trap hit making it appear on the ESP32-S3 port. Validated on silicon…
- Passive carry verificationHands-free unlock should arm only while the credential is actually being carried by a walking person, not while the phone sits on a hall table, rides in a relay, or…
- PresenceTurn the lock into a proof. A presence assertion is a signed statement that a named human's phone was within a few tens of centimetres of this board, at a distance…
- Range integrity: what a signed distance is worthA presence assertion exists to be believed by someone who was not in the room. Its whole content is a distance, so the interesting question is not "what did the radio…
- PINless proximity unlock on macOS 26This report records a read-only investigation of smart-card and proximity screen unlock on macOS 26.4.1, build 25E253, using the macOS 26.4 SDK. It combines:
- Deriving the ranging keyPrerequisite reading:
porting-esp32.md(roadmap and retrospective) andprotocol-research.md(the reverse-engineered protocol notes; this doc stays at that same…
Engineering log
- RSSI power gate and the power-profile studyContinuous UWB is what keeps an Aliro reader off battery power: the DW3000 listens with its receiver hard-on, and until now it started doing that the moment a phone…
- Memory usageScope: the nRF5340 DK image only. The DWM3001CDK image (
firmware/pm_static.yml) and the ESP32-S3 apps (ports/esp32/apps/*/partitions.csv) have their own budgets… - Home Assistant internalsHow the bridge is built, what contract it holds with the firmware console, and what to check when you change either side. The user-facing guide is Home Assistant.
- Phase 0: can the WASM twin run inside a Cloudflare Worker?Spike for the
/twinDiscord command design (build-on-demand bot, prompt 3, part B). Question: canweb-twin/twin.js's inline-embedded WASM be instantiated and run… - The digital twin as a Discord ActivityThe walk-up simulator that runs at
web-twin/also runs inside Discord, as an Activity. Launch it in a voice channel and everyone in the call can watch the same… - Discord Activity, phase 0: does the twin's WASM survive a sandbox CSP?Record of the spike that gates the whole "run
web-twin/as a Discord Activity" idea. Written against8d6ede1. Reproduce the local half withweb-twin/csp_probe.py. - Distributing the Activity: what it costResearched 2026-08-04 from Discord's developer support documentation. Treat every figure here as needing a re-check before acting on it: these are policy pages, not…
Porting
- Porting to a new chipsetHow the UWB engine moves to a new chipset, what it costs, and how to prove a port did not change the code the validated target runs.
- Porting to ESP32-S3This document keeps the original plan, written before any ESP32 code existed, and marks what the plan got right and wrong. The plan's own estimates are left unedited…
- ESP32-S3 gotchasHard-won, non-obvious findings from porting the Aliro UWB door-lock reader to ESP32-S3 (ESP-IDF + esp-matter + NimBLE + DWM3000EVB). Each entry is a trap actually hit…
- DWM3001CDK surgeryHard-won, non-obvious findings from putting a hand-written Matter node next to the Aliro UWB reader on a DWM3001CDK (nRF52833 + DW3110, NCS v3.3.0 / Zephyr). The goal…
Project
- ReferenceThe API reference at
site/api/index.htmlis a separate tree, generated by Doxygen from the declarations themselves. It is built rather than committed, so there is… - ReleasingHow to cut a release. Versions follow SemVer (
vMAJOR.MINOR.PATCH); pre-1.0, a minor bump means new capability and a patch bump means fixes only. - PrivacyWhat the Discord bot stores, where, and how to get rid of it.
- TermsWhat you are agreeing to by using the Discord bot, and what this project does and does not promise about the firmware.