Get started
Three routes in, ordered by what they cost you: watch the firmware run in a browser tab, flash a real lock without a toolchain, or build the whole thing. Pick one; it opens in place.
Pick a route
0 minutes · no hardwareWatch it runThe firmware itself, compiled to WASM, in a browser tab
Not a mock-up of the decision: the twin runs the same modules/woz_uwb logic the board runs, compiled to WASM, and CI rebuilds it and byte-diffs the result so the page cannot drift from the firmware.
~10 minutes · no toolchainFlash a real lockAn ESP32 written straight from this site, then added to Apple Home
- Flash an ESP32 lock from the browserNo toolchain: this site writes the merged firmware image (ESP32-S3, C5 or C6) over WebSerial (Chrome, Edge, or Firefox).
- Add the keyCommissioning, for every target: the setup code, the uncertified-accessory warning, and what a healthy pairing looks like.
- ESP32 bring-up (S3, C5, and C6)DWM3000EVB to the board, pin by pin, and what good output looks like — the table CI keeps in sync with
board_pins.h. - Release bundlesPrebuilt images for every target, if you would rather not flash from the browser.
What this needs on the desk: an ESP32-S3, C5 or C6 dev board, a Qorvo DWM3000EVB, eleven jumper wires and a USB data cable. Chrome, Edge or Firefox on a computer does the writing over WebSerial.
Apple’s side: an iPhone with a UWB chip, a home hub, and a 2.4 GHz Wi-Fi network for the board to join. No ESP-IDF, no clone, nothing to install.
What is actually validated on each chip
ESP32-S3: approach unlock, on hardware.
ESP32-C6: approach unlock, on hardware; it drives a BU04 over direct SPI.
ESP32-C5: builds and releases, no hardware validation recorded.
None of the three has an NFC tap path. That needs the nRF5340 DK.
a full dev setupBuild it yourselfClone, bootstrap the toolchain, and flash the board you have
DWM3001CDK — the primary target
One nRF52833 and the DW3110 in the same module: nothing to wire, an on-board J-Link, and the reader, a Matter node and a Thread MTD in one image. Bare targets always mean this board; the image lands in build/cdk-matter.
make dfu-key is not optional and not once-per-machine. Every image is signed, the key is gitignored, and without one the build fails at configure rather than falling back to MCUboot’s published demo key — so a fresh clone or a new git worktree needs its own.
make bootstrap is the ~8.5 GB one: host tools, the pinned NCS v3.3.0 toolchain, then NCS itself into ./workspace. An existing toolchain is detected and skipped. make monitor is RTT over probe-rs; this board has no UART console at all.
nRF5340 DK — the target with the NFC tap
A DK plus a DWM3000EVB shield, and the only target with a reader IC, so Express Mode tap works here and nowhere else. make nrf-flash-erase is required after any net-core config change.
ESP32-S3, C5 and C6
ESP-IDF and esp-matter rather than NCS, with the same shared modules/ underneath. TARGET takes esp32s3, esp32c5 or esp32c6; APP=reader builds the standalone bench reader instead of the full lock.
No board yet? The host suites need none
make test is the host KAT suite: no NCS toolchain, no hardware. make verify is the pre-PR sweep — every CI gate a host can run, in about 35 seconds, and the same script CI itself calls.
- InstallingThe full install guide — every target, every knob.
- ConfiguringBuild options, Kconfig overlays, and the runtime consoles.
- Add the keyCommissioning into Apple Home, once something is flashed.
- Hardware validationWhat to prove on the bench that automated CI cannot.
- TroubleshootingSymptoms, grouped by target, leading with the CDK.
The step-by-step version of this route sits on the landing page.
Once it is running
Firmware internalsHow the reader is put together
- ArchitectureThe module graph, color-keyed by subsystem, and every module’s declarations.
- ModulesEvery file in the tree, grouped by directory, with the brief from its own docstring.
- Memory usageWhere the build’s flash and RAM go, measured.
- ReferenceThe Doxygen tree, generated from the declarations themselves.
Protocol & researchHow the unlock actually works on air
- Protocol researchBLE + UWB proximity unlock, as observed on air.
- Time synchronizationWall-clock time and credential validity in the firmware.
- Approach DirectionThe Home app’s Left/Front/Right control, end to end.
- Range integrityWhat a signed distance is worth, and what defends it.
- Deriving the ranging keyThe credential auth, phase by phase.
Project & contributingCI, releasing, and where the work happens
- RepositorySource, issues and pull requests on GitHub.
- IssuesReport a bug or pick something up.
- ReleasingHow a release is cut and what gates it.
- Porting openaliroWhat moving the engine to a new chipset costs, and how to prove it.
What CI checks, and how to run it here
Host tests with a coverage floor, ASan/UBSan sanitizer runs, clang-format and clang-tidy, shell and workflow lint, fuzzing, CBMC proofs, port tests, and the blocking security gates.
CI is one job and it runs make verify, so a green sweep and a green PR mean the same thing. make tools says what each gate needs and what is missing here; a gate whose tool is absent fails the sweep rather than passing quietly, because CI runs it either way. Firmware images are never built on a push: that workflow is dispatch-only, because it needs the full toolchains.