OpenParcelBox/hardware/interfaces.md

Hardware Interfaces

This document describes the hardware interfaces independently from the GPIO assignments used by a specific board revision.

---

Keypad

Production target:

• Vertical 2x6 physical layout.
• Matrix keypad implemented on a custom PCB.

Development target:

• Freenove 4x4 matrix keypad.
• PCF8574 GPIO expander.

Features:

• Software debounce.
• Key press detection.
• Zephyr-compatible driver.

---

NFC

The nRF52840 integrated NFC peripheral is NFCT hardware. It supports the tag-side NFC-A role and requires an NFC antenna on NFC1/P0.09 and NFC2/P0.10.

It is not a standalone active NFC reader for passive badges.

Credential badge reading currently uses a PN532 module in I2C mode (1 0) at the fixed 7-bit address 0x24. It shares XIAO SDA and SCL with the PCF8574 keypad expander at 0x20.

Functions:

• UID reading.
• Badge validation.
• Unlock request trigger.

The PN532 module and its integrated antenna provide the development reader. Reader placement, range, interference, and the production PCB implementation still need physical validation.

---

KR-S79 Lock

Command:

• 150 ms positive pulse on SIG in the current development firmware.

Validation:

The current firmware monitors the COM/NC contact independently for open-state LED, serial, and buzzer feedback. Correlating that transition with the command pulse and reporting a timeout is planned; opening must not ultimately be validated from a fixed delay alone.

Target validation sequence:

SIG command
    |
Opening pulse
    |
Wait for COM/NC
    |
    +-- State change detected: opening confirmed
    |
    +-- Timeout: opening error

---

RGB LEDs

The original front LEDs are not considered reusable in the current hardware plan.

The new PCB will provide replacement red, green, and blue indicators.

---

Buzzer

The buzzer provides audible feedback.

The current validated design uses an active buzzer driven through a transistor.

Examples:

• Key press feedback.
• Opening confirmed.
• Error feedback.
• Diagnostic feedback.

---

Battery

The original battery compartment is retained.

The firmware will provide:

• Voltage measurement.
• Battery level estimation.
• Low battery alerts.

---

Zigbee

OpenParcelBox is intended to communicate natively with Home Assistant over Zigbee.

The firmware should not depend directly on an MQTT broker.

Zigbee integration may be exposed through:

• ZHA.
• Zigbee2MQTT.

---

OTA

Updates must be performed securely.

Each firmware image must be verified before installation.