Aliro HomeKey

Open-source Aliro access reader for ESP32

One reader. One standard. Multiple wallet ecosystems.

Website · Architecture · Roadmap · Releases

An ESP32 firmware that turns the board into an experimental Aliro access reader. A phone or wearable presents an Aliro credential, the reader runs the transaction, and the ESP32 drives an access-control output — relay, strike, or test LED.

It's built on Aliro, the Connectivity Standards Alliance standard for interoperable mobile access credentials, so the reader isn't locked to one wallet vendor.

Apple / Google / Samsung Wallet ──▶ Aliro protocol ──▶ ESP32 Reader ──▶ Lock / Relay
                                                       (NFC · Matter · MQTT)

Build the reader once. Let the wallet ecosystem handle the credential experience.

v0.5 beta: a phone opens the door on tested hardware, and the surrounding product layer works alongside it.

Verified on an ESP32-WROOM-32 with a PN532: commissioned into Apple Home, provisioned with an Aliro credential over Matter, and driven through both transaction paths — 569 ms on the fast path, 2047 ms on the standard path. Home app lock/unlock, OTA with rollback, the configuration UI, MQTT, and Home Assistant discovery have all been exercised on the same board.

main also carries fixes not yet in a tagged release: the Apple ECP beacon defaults back off after it was found to wedge the NFC bus, Wi-Fi power save is disabled once connected (it was silently timing out Matter subscriptions), and a duplicate-notification bug in Matter lock reporting is fixed.

This remains a research/beta project, not a certified access-control product. Apple shows an uncertified-accessory warning during commissioning. Google and Samsung wallet flows are untested, and Apple Wallet Express Mode still needs confirmation on the physical test lock.

Three ways in — pick whichever fits.

idf.py set-target esp32
idf.py -D SDKCONFIG_DEFAULTS="sdkconfig.defaults;boards/sdkconfig.defaults.esp32" build
idf.py -p /dev/ttyUSB0 flash monitor

# Wipes the board and installs everything: bootloader, partitions, app
python -m esptool --chip esp32 write_flash 0x0 esp32.firmware.factory.bin

# Or, over the device's own OTA page once it's already running:
# open http://<device-ip>/#/ota and upload esp32.firmware.bin

docker run --rm -it -v "$PWD:/work" -w /work \
  espressif/esp-matter:latest_idf_v5.5.4 bash -lc \
  '. "$IDF_PATH/export.sh" && . "$ESP_MATTER_PATH/export.sh" && \
   idf.py -D SDKCONFIG_DEFAULTS="sdkconfig.defaults;sdkconfig.matter" \
   set-target esp32 build'

Aliro transactions run over ISO 7816 APDUs on ISO 14443-4 NFC (this project's current focus; BLE/UWB are part of the broader spec but not yet implemented here).

1. Reader detects the device and selects the Aliro applet.
2. An expedited P-256 handshake authenticates both sides.
3. The device identifies its credential via an Aliro key slot.
4. The reader checks that key slot against local access data.
5. Transaction completes, access output fires.

A previously-seen credential can use the fast path, skipping most of the handshake.

The ESP-Aliro SDK handles the protocol, crypto, and transaction state. Aliro HomeKey builds everything around it: NFC transport, credentials, access decisions, lock control, config, OTA, MQTT, Matter, and the device UI.

Board-level validation ≠ SDK target support. A target above may still need its own pin map, partitioning, wiring, and hardware validation before it's fully supported.

Typical hardware: an ESP32-WROOM-32 (or other supported target), a PN532 or compatible NFC frontend, a relay/strike/LED for the access output, and a USB connection for flashing.

• Access — Aliro transactions, fast + standard paths, key-slot access decisions, lock/relay GPIO output
• Device — browser config UI, Wi-Fi setup AP, NVS-backed config, OTA with rollback, GPIO validation
• Integrations — Matter Door Lock endpoint, Aliro provisioning over Matter, MQTT, Home Assistant discovery
• Developer tools — ESP-IDF based, serial diagnostics, per-board defaults, architecture docs

On first boot without Wi-Fi credentials, the reader raises its own setup network:

Aliro-Setup-XXXX
password: aliro1234

Open http://192.168.4.1/. Config lives in NVS, so changing wiring or network settings never needs a rebuild — NFC bus, GPIO assignments, lock polarity, Wi-Fi, MQTT, and system settings are all in there.

MQTT is optional and off by default. Enabled, it publishes lock state and tap events, accepts unlock commands, and announces itself to Home Assistant. Full API in docs/WEB.md.

Aliro-homekey/
├── website/                 # GitHub Pages public site
├── main/                    # Firmware entry point (+ certs/: generated dev identity)
├── components/
│   ├── app_config/          # Runtime configuration + NVS
│   ├── nfc_transport/       # NFC hardware abstraction
│   ├── aliro_reader/        # Aliro transaction integration
│   ├── access_control/      # Credentials + access decisions + lock output
│   ├── net_manager/         # Wi-Fi + setup AP
│   ├── mqtt_manager/        # MQTT + Home Assistant integration
│   ├── matter_lock/         # Matter Door Lock + Aliro provisioning
│   └── web_server/          # REST API + embedded configuration UI
├── boards/                  # Board-specific ESP-IDF defaults
├── tools/                   # Development and firmware tooling
└── docs/                    # Architecture, API and roadmap

NFC drivers, board support, wallet testing, protocol research, docs, and bug fixes are all useful. Read CONTRIBUTING.md and check the roadmap before opening a PR.

• grapefizz — restored Apple Wallet Express Mode polling (#1, #3), fixed Apple Home status resuming after a restart (#4), and added Matter lock activity event publishing (#5).

Aliro HomeKey is a research and hobbyist implementation, not certified for production access control.

Aliro is a trademark of the Connectivity Standards Alliance. This project is not affiliated with or endorsed by the CSA, Espressif, Apple, Google, or Samsung.

A shipping access-control product requires the appropriate ecosystem provisioning, certification, security review, and hardware validation.

Released under the Apache License 2.0. See LICENSE.