Commercial smart locks that support Apple Home Key or Google Wallet cost north of $250 and lock you into a single vendor ecosystem. The Aliro specification, published in February 2026, finally gives us a universal NFC credential standard that works across Apple Wallet, Google Wallet, and Samsung Wallet through the Matter protocol. The question is: can you build a compliant access controller yourself, on a $12 ESP32 board and a $6 NFC module?
That is exactly what the Aliro access controller project does. It started as a Proxmark3-based HomeKey research tool and evolved into a full Aliro access controller built on ESP32-S3 and PN532. The firmware handles the complete flow: Aliro NFC transaction, lock actuation, Matter provisioning, MQTT telemetry, tamper detection, and Prometheus metrics. One codebase, three wallet ecosystems, zero vendor lock-in.
This article walks through the project architecture, the hardware you need to replicate it, how the Aliro protocol differs from proprietary HomeKey, and where the firmware stands today. Whether you want to build your own smart lock or just understand how phone-based NFC access control works under the hood, this is the complete technical breakdown.
- Why Aliro Changes Everything for DIY Smart Locks
- Project Architecture: Seven Tracks in One Monorepo
- aliro-esp32 — The Primary Target
- homekey-esp32 — Frozen Baseline
- homekey_reader.py — Proxmark3 Research Tool
- Other Tracks
- Hardware: What You Need to Build This
- Core Components
- Wiring (SPI, Default Preset)
- How Aliro Differs from HomeKey Under the Hood
- The Testing Rig: Why Both Phones Matter
- Current State: What Works and What Does Not
- Proxmark3 Research Tool: Sniffing Real Lock Traffic
- DIY Lock MVP: The Simplest Path to a Working Lock
- Hardware Roadmap: From PN532 to PN7160 to PN7642
- Getting Started: Flash and Test in 10 Minutes
- Related Projects and Protocol References
- Frequently Asked Questions
- Can I use this as my actual door lock?
- Does it work with Google Wallet?
- Do I need a Proxmark3?
- What about security? UID matching is trivially cloneable.
- Can I contribute to the Aliro firmware?
Why Aliro Changes Everything for DIY Smart Locks
Before Aliro, building a phone-based smart lock meant choosing sides. Apple Home Key uses a proprietary protocol built on ECP (Enhanced Contactless Polling), ECDH key exchange, and AES-GCM encryption, all tied to the HomeKit accessory framework. Android had no equivalent standard. If you wanted Android support, you had to write a custom HCE (Host Card Emulation) app and a bespoke reader protocol from scratch.
Aliro 1.0, shipped by the Connectivity Standards Alliance in February 2026, eliminates that fragmentation. It defines a single NFC credential format that Apple, Google, and Samsung have all adopted for their wallet apps. The transport layer uses the Matter DoorLock cluster with the ALIRO feature flag, so any Matter-compatible controller can provision keys from any wallet. One reader, all phones.
The critical insight is that Aliro is implementable end-to-end without CSA membership. The specification is publicly downloadable, the Matter SDK is open source (espressif/esp-matter), and the NFC transaction uses standard ISO 14443-A commands. You do not need a certification lab or a licensing agreement to build a working controller.
Project Architecture: Seven Tracks in One Monorepo
The repository is structured as a monorepo with seven distinct tracks, each serving a specific role in the development lifecycle. This is not scope creep. Each track exists because the Aliro bring-up process requires regression baselines, research tooling, and fallback paths that a single-firmware repo cannot provide.
aliro-esp32 — The Primary Target
The main firmware. ESP32-S3 + PN532 Aliro access controller built on esp-matter. This is not just an NFC reader. It implements the full controller stack:
- Aliro NFC transaction (SELECT, AUTH0, key schedule parsing)
- Lock output control with configurable actuation
- Matter BLE commissioning and DoorLock cluster
- Local HTTP API for direct LAN control
- MQTT telemetry for home automation integration
- Tamper and anomaly detection with CCTV webhook triggers
- Prometheus metrics endpoint for monitoring
The firmware boots, advertises for BLE commissioning, and already reaches live Aliro SELECT and AUTH0 commands on iPhone. The main open item is the cold-tap Step-up transition after AUTH0 = 6984, which is the subject of active development.
homekey-esp32 — Frozen Baseline
A vendored fork of rednblkx/HomeKey-ESP32 that implements the full Apple HomeKey stack: ECP polling, ECDH, AES-GCM, and HomeKit accessory pairing. This firmware is frozen. It is not being rewritten or extended. Its job is to serve as a regression baseline: before each Aliro development session, we reflash it to verify the hardware rig is healthy.
The HomeKey firmware also runs on the LilyGO T-ETH-Lite-ESP32S3 field baseline, where Ethernet connectivity via the W5500 chip provides WebUI, OTA updates, and log access over LAN even when USB is not available.
homekey_reader.py — Proxmark3 Research Tool
A Python script that drives a Proxmark3 (Iceman fork) into Apple ECP Access mode. This is a research and sniffing tool, not a functioning lock. The PM3 is the only hardware in this project that can sniff ISO 14443-A traffic, making it indispensable for reverse-engineering real Aliro locks and observing what iPhones actually put on the wire during a HomeKey or Aliro transaction.
Other Tracks
- android-smartkey — Kotlin HCE companion app for custom Android NFC credentials. Deprioritized now that Aliro covers Android natively through wallet apps
- smartkey-esp32-patch — Draft C++ patches for the HomeKey firmware. Kept outside the subtree until tested
- aliro-site — Project website at aliro.mayday.software, deployed via Cloudflare Workers
- aliro-bridge — Planned MQTT-to-Telegram bridge for remote notifications, CCTV dispatch, and analytics aggregation
Hardware: What You Need to Build This
The entire rig costs under $25 and uses components available from any electronics supplier. No custom PCBs, no specialized tools, no certification hardware required.
Core Components
| Component | Role | Price |
|---|---|---|
| ESP32-S3-WROOM-1 DevKitC | Host MCU (dual USB-C: native USB + UART) | ~$12 |
| PN532 NFC breakout | NFC frontend (SPI mode: SET0=H, SET1=L) | ~$6 |
| Y65592 screw-terminal adapter | Solderless wiring between ESP32 and PN532 | ~$3 |
For a field-deployable setup, replace the DevKitC with a LilyGO T-ETH-Lite-ESP32S3 which adds W5500 Ethernet and a proper enclosure footprint. Note that the Ethernet chip occupies GPIO 9-14, so PN532 pins must be remapped from the default DevKitC preset.
Wiring (SPI, Default Preset)
| PN532 Pin | ESP32-S3 GPIO | Function |
|---|---|---|
| 5V | 5V | Power |
| GND | GND | Ground |
| SCK | GPIO 12 | SPI clock |
| MISO | GPIO 13 | SPI MISO |
| MOSI | GPIO 11 | SPI MOSI |
| NSS | GPIO 10 | SPI chip select |
| IRQ | GPIO 14 | Frame-ready interrupt (optional) |
| RST | GPIO 9 | Hardware reset (optional) |
Pin mapping is runtime-configurable via the captive portal WebUI on first boot. The table shows the firmware’s built-in Default preset. IRQ enables interrupt-driven frame signaling for lower CPU usage. RST is pre-wired for future hardware reset capability but not currently driven by firmware.
How Aliro Differs from HomeKey Under the Hood
Both protocols use NFC (ISO 14443-A) as the physical layer, but they diverge sharply at the application level.
| Aspect | Apple Home Key | Aliro |
|---|---|---|
| Ecosystem | Apple only (HomeKit) | Apple, Google, Samsung (Matter) |
| Provisioning | HomeKit accessory pairing (HAP) | Matter BLE commissioning + DoorLock cluster |
| Key exchange | Proprietary ECDH + AES-GCM | Standard Aliro auth (SELECT + AUTH0 + Step-up) |
| Wakeup mechanism | ECP Access frame (proprietary) | Standard NFC polling (ISO 14443-A) |
| Express Mode | Yes (no Face ID needed) | Yes (wallet-dependent implementation) |
| Specification | Reverse-engineered | Published by CSA (downloadable) |
| Reader certification | MFi required for commercial products | None required for implementation |
The practical consequence: HomeKey readers exist because people like kormax and rednblkx reverse-engineered Apple’s protocol. Aliro readers can be built from the official specification. That is a fundamental difference in sustainability and legal footing.
The Testing Rig: Why Both Phones Matter
End-to-end validation of an Aliro controller requires devices from multiple wallet ecosystems. Our test bench includes:
| Device | Wallet | What It Tests |
|---|---|---|
| iPhone 16 Pro Max | Apple Wallet (Home Key / Aliro) | ECP wakeup, SELECT/AUTH0 traces, cold-tap Step-up |
| Samsung Galaxy Z Fold7 | Samsung Wallet (Aliro Digital Key) | Samsung polling pattern, Aliro-only crypto path |
Both wallets provision keys through the same Matter DoorLock cluster SetAliroReaderConfig command. The keys land in the AliroDelegate NVS store regardless of which phone provisioned them. This is the whole point of a standard: one reader, multiple credential sources.
This dual-device setup is not common in the open-source community. The upstream HomeKey-ESP32 author landed experimental Aliro support in the underlying DigitalDoorKey library but has not wired it into the firmware. A reasonable reading of the commit timeline suggests the author has an iPhone for Apple-side testing but not a Samsung device for the Android-side Aliro flow. Having both phones lets us drive both paths and close the integration gap.
Current State: What Works and What Does Not
| Track | Status | Details |
|---|---|---|
| aliro-esp32 | In progress | Matter skeleton + Aliro provisioning landed; live iPhone traces reach SELECT/AUTH0; cold-tap Step-up pending |
| homekey-esp32 | Working (frozen) | Full HomeKey stack confirmed on iPhone; Ethernet/WebUI baseline on T-ETH-Lite |
| android-smartkey | Partial | JVM-testable APDU codec, stub HCE service; deprioritized in favor of Aliro |
| aliro-site | Live | RU/EN landing page deployed via Cloudflare Workers |
| aliro-bridge | Planned | MQTT-to-Telegram/CCTV/analytics service; not started |
The main blocker is the cold-tap Step-up transition. When the iPhone responds to AUTH0 with status 6984, the controller needs to escalate the authentication flow. This is the difference between a “known device, express unlock” tap and a “new device, verify identity” tap. The 6984 response is documented in the Aliro spec, but the Step-up implementation requires careful state machine work in the PN532 transport layer.
Proxmark3 Research Tool: Sniffing Real Lock Traffic
The homekey_reader.py script configures a Proxmark3 to emit HomeKey-compatible ECP polling frames and capture the iPhone’s response. This is pure research tooling: it does not unlock anything. What it does is let you observe the NFC transaction between a real phone and a real (or emulated) lock at the protocol level.
python3 homekey_reader.py
# Interactive menu:
# 2 → Enable ECP Access polling
# 4 → Continuous poll (tap iPhone near antenna)
# 6 → Decode last traceThe script includes TCI (Target Card Identifier) presets for known commercial locks:
| Lock | TCI Value |
|---|---|
| Aqara U200 | 0007 |
| Schlage Encode Plus | 0006 |
| Yale Assure Lock 2 | 0005 |
| Level Lock+ | 0003 |
These TCI values were observed via hf 14a sniff against physical locks and may vary across firmware versions. When iPhone has Express Mode active (default for HomeKey), it responds to any ECP Access frame with a HomeKey applet select, no user interaction required. If you see 5a / 5e / 90 00 in the trace, the phone is engaging with the ECP pipeline.
DIY Lock MVP: The Simplest Path to a Working Lock
For those who want a working lock today without waiting for the Aliro firmware to reach end-to-end completion, the repository includes lock_mvp.py: a minimum-viable lock that uses UID-based authentication via Proxmark3.
# Enroll your first card:
python3 lock_mvp.py --enroll
# Start the lock (polls every 0.8s):
python3 lock_mvp.py
# Live keyboard commands:
# e → arm enroll mode (next unknown tap auto-adds)
# l → list current allowlist
# s → show lock state
# q → quitThe MVP supports ISO 14443-A cards (Mifare, DESFire, NTAG) and LF EM410x fobs common in European and Russian building access systems. It intentionally skips Mifare sector authentication (just UID matching), DESFire AID verification, and all HomeKey/Aliro crypto. It is a prototyping tool, not a security product.
Hardware Roadmap: From PN532 to PN7160 to PN7642
The current rig uses the PN532, which is the most accessible and well-documented NFC frontend for hobbyist projects. But the project has a clear hardware upgrade path:
- Now: ESP32-S3 + PN532 — the only proven rig for the current development cycle. All regression testing and Aliro bring-up happens here
- Next: NXP PN7160-EVK (OM27160) — NCI-based NFC controller. Evaluate once the PN532 path is stable enough for meaningful comparison
- Later: NXP PN7642-EVK (OM27642) — secure NFC controller with hardware crypto. Future architecture study for a production-grade reader
The PN7160 evaluation kit is ordered and pending arrival. The PN7642 is a longer-term target: it provides hardware-backed key storage and tamper resistance that the PN532 cannot offer, which matters for any deployment beyond a lab prototype.
Getting Started: Flash and Test in 10 Minutes
The fastest path from zero to a working HomeKey reader (the frozen baseline, not Aliro) takes about 10 minutes:
- Wire the PN532 to the ESP32-S3 DevKitC using the 8-pin SPI wiring table above. A Y65592 screw-terminal adapter makes this solderless
- Flash the firmware via the web flasher at
homekey-esp32.vercel.app(Chrome or Edge, select ESP32-S3 target, connect via USB-C) - Connect to the setup AP (
HomeSpan-Setup/homespan), open the captive portal, keep the NFC pin preset on Default - Pair with Apple Home using the HomeKit setup code displayed on screen
- Tap your iPhone near the PN532 antenna. Express Mode should trigger automatic unlock
For local builds with the full ESP-IDF toolchain:
cd homekey-esp32
nix develop
idf.py set-target esp32s3
idf.py build flash monitorRelated Projects and Protocol References
This project builds on extensive reverse-engineering work by the community:
- kormax/apple-home-key-reader — the original Python/nfcpy HomeKey reader and protocol research reference
- kormax/apple-home-key — comprehensive HomeKey protocol documentation
- kormax/aliro — Aliro protocol research, primary external reference for the ESP32 firmware
- rednblkx/HomeKey-ESP32 — the canonical ESP32 HomeKey implementation (~900 stars), basis of the frozen baseline
- rednblkx/DigitalDoorKey — the library with experimental Aliro auth class support
- kormax/apple-enhanced-contactless-polling — ECP frame examples for all Apple NFC modes
Frequently Asked Questions
Can I use this as my actual door lock?
The HomeKey baseline (homekey-esp32) is functional for Apple devices. Wire a relay to the ESP32 GPIO and you have a working lock. The Aliro firmware is not yet ready for daily use: the cold-tap Step-up flow is incomplete. For a production deployment, wait for the Aliro end-to-end unlock path to be validated.
Does it work with Google Wallet?
The Aliro specification supports Google Wallet, and the firmware’s Matter DoorLock cluster will accept keys from any Aliro-compliant wallet. Full validation with Google Wallet is pending until the Samsung Wallet flow is confirmed first (Samsung Wallet shipped Aliro support ahead of Google).
Do I need a Proxmark3?
No. The PM3 is only needed for the research/sniffing tool (homekey_reader.py). The actual lock firmware runs on ESP32-S3 + PN532, which is the only hardware you need for a functioning reader. Get a PM3 only if you want to sniff and analyze NFC traffic at the protocol level.
What about security? UID matching is trivially cloneable.
Correct. The lock_mvp.py tool uses UID-only authentication, which any $5 magic card can defeat. It is a prototyping scaffold, not a security system. The HomeKey and Aliro firmwares use full cryptographic authentication (ECDH, AES-GCM for HomeKey; standard Aliro auth for Aliro) that cannot be cloned by reading the card UID.
Can I contribute to the Aliro firmware?
The project website is at aliro.mayday.software — reach out there if you want to collaborate. The main area that needs work is the cold-tap Step-up transition (TODO section 7.3). If you have an iPhone or Samsung device with wallet-provisioned Aliro credentials and an ESP32-S3 + PN532 rig, your NFC traces are immediately valuable for debugging the Step-up state machine.
