01 / ARCHITECTURE

One seam per component.

The firmware is split around the parts that are expected to change independently: NFC hardware, Aliro transactions, access policy, configuration and network integrations.

TRANSACTION PATH

From RF field to decision.

Phone / watch
      │  ISO 14443-4 NFC
      ▼
┌─────────────────────┐
│   nfc_transport     │  poll / activate / exchange
└──────────┬──────────┘
           │ APDUs
           ▼
┌─────────────────────┐
│    aliro_reader     │  session + authentication
└──────────┬──────────┘
           │ credential + result
           ▼
┌─────────────────────┐
│   access_control    │  identity + policy + lock
└─────────────────────┘

Browser ──HTTP──> web_server ──> app_config ──> NVS
                         │
                    net_manager
                         │
                    MQTT / Matter

WHY THE BOUNDARIES

The NFC chip can change without rewriting the reader.

NFC transport

PN532, PN7160 and ST25R3916 do not share the same bus, driver or quirks. The transport interface keeps those details isolated.

Aliro reader

The Espressif Aliro library owns protocol state and cryptographic session handling. The project wraps it rather than duplicating the protocol.

Access control

Credential lookup and the decision to unlock are policy. Keeping them outside protocol code leaves room for schedules, revocation and multiple locks.

ONE TAP

The reader task owns the session.

Polling, activation, session creation, credential lookup, exchange and result handling occur in one controlled lifecycle. The result is handed to access control only after the field is released.

poll()
  → activate()
  → create Aliro session
  → expedited transaction
      ↳ NFC exchange
      ↳ credential key-slot lookup
  → exchange phase
  → delete session
  → deactivate NFC field
  → access_control_on_reader_result()

DESIGN CONSTRAINTS

Some limits are intentional.

Constraint	Reason
One reader session	The SDK is singleton-shaped, so callbacks safely route through module state.
Boot-time configuration	Changing a live SPI bus or lock GPIO mid-transaction is worse than requiring a restart.
NVS first	Reader identity, group information and configuration need persistent storage before the protocol starts.
Network is optional	The reader must remain a reader when Wi-Fi or a controller is unavailable.