OpenParcelBox/docs/firmware/nfc.md

NFC

Purpose

This module provides the application-level NFC credential flow and persistent NFC tag UID storage.

NFC tag UIDs are stored in non-volatile settings, like access codes. They remain available after power loss and expose add, replace, and clear APIs used by the mobile application and reserved for the future Home Assistant integration.

The Seeed Studio XIAO nRF52840 exposes the Nordic NFCT pins (NFC1/P0.09 and NFC2/P0.10). The integrated NFCT peripheral is tag-side NFC-A hardware and is not a standalone active reader for passive badges.

Passive badge UID reading is provided by a PN532 module connected to the same I2C bus as the development keypad expander. The module uses the fixed 7-bit address 0x24 (0x48 in NXP's 8-bit address notation).

---

Persistent Tags

• Up to 10 NFC tag UIDs can be stored, each with a 31-character name.
• UID length can be 1 to 10 bytes.
• The first default development UID is 60:4F:E2:B5.
• A valid stored table can contain zero enabled tags. This allows future applications to delete all tags without having the default test UID recreated after reboot.

Public API:

int nfc_tags_init(void);

bool nfc_tags_is_valid(const uint8_t *uid, size_t length);

int nfc_tags_set(size_t slot, const uint8_t *uid, size_t length);

int nfc_tags_clear(size_t slot);

---

Scan Mode

The firmware keeps the PN532 in its I2C-wakeable power-down mode by default.

The first keypad key press wakes the PN532 and starts one fixed 15-second scan window. Additional key presses during that window never extend or restart its deadline. A later key press can start a new window only after the previous one has ended.

An authenticated administrator can start a separate 15-second enrollment scan from the mobile application. This explicit administration flow is the only exception to keypad-triggered scanning. A new UID is returned through BLE but is not authorized until the administrator enters a name and validates it in the active modal. A duplicate tag or timeout is returned as an enrollment error, and cancellation powers the reader down immediately.

While scan mode is active, the RGB LED is blue.

When the PN532 detects an ISO/IEC 14443-A tag:

• The UID is printed over UART.
• A valid UID triggers the same success beep and unlock path as a valid keypad code.
• After a valid NFC unlock, scan mode is disabled immediately.
• An invalid UID triggers the same three-beep error sequence as an invalid six-digit code, then scan mode remains active until timeout or a valid tag.

Runtime UART messages:

Scan NFC: ON
Scan NFC: OFF
NFC detected: 60:4F:E2:B5
NFC valid
NFC not valid

---

PN532 Driver

• Interface selection: I2C 1 0 on the module switches.
• Bus: XIAO SDA / SCL, shared with the PCF8574 at 0x20.
• Address used by Zephyr: 0x24.
• Reader initialization verifies the PN532 firmware response and configures SAM normal mode plus bounded passive-target retries.
• Disabling scan sends the PN532 PowerDown command with I2C wake enabled.
• If the reader is absent, local keypad access, persistent storage, and BLE continue operating; UART reports the NFC initialization/start error.