penguin/homekey-relay

homekey-relay

README.md

raw ยท 2227 bytes

HomeKey Reader Relay

PN532 -> ESP32-C3 (this part) -> Home Assistant

In development. NOT FOR USE!

Current firmware connects directly to homekey-go over BLE GATT and relays NFC APDUs. The HACS component and service-data examples below describe the earlier advertisement-based firmware; current firmware does not emit those UID advertisements. See the current relay protocol.

Legacy Home Assistant UI setup

HACS

  1. Settings -> Devices & services -> Add Integration.
  2. Search for HomeKey Reader.
  3. Pick the advertising ESP32-C3 reader.

Because the manifest also contains a Bluetooth matcher, Home Assistant can offer the reader automatically when it sees the service-data advertisement.

Install toolchain

brew install libgcrypt glib pixman sdl2 libslirp dfu-util cmake python

brew tap espressif/eim
brew install eim

eim install

source "$HOME/.espressif/tools/activate_idf_v6.x.x.sh"

Flash the firmware

cd esp32
idf.py set-target esp32c3
idf.py -p /dev/cu.usbmodem101 flash monitor

Current flow

Service UUID:

7b1e0001-7b1e-4a11-9abc-0123456789ab

Advertisement payload after the UUID:

byte 0	  protocol version = 1
byte 1	  message type = 1 (mock PN532 tag)
byte 2..3   sequence, uint16 little-endian
byte 4..7   mock UID = DE AD BE EF

Testing the PN532

LIBNFC_DEVICE=pn532_uart:/dev/cu.usbserial-8310 nfc-list
LIBNFC_DEVICE=pn532_uart:/dev/cu.usbserial-8310 nfc-poll

Test pins

idf.py -B build-pin-test -D PIN_TEST=ON build flash monitor

Test pn532

idf.py -B build-pn532-test -D PNC532_TEST=ON build flash monitor

NFC APDU relay

The firmware now exposes session status and an APDU mailbox for homekey-go 0.0.3. Flash the matching firmware before updating the Go service. NFC runs in one UART owner task; the RF field stays on throughout authentication.

The first test uses an existing Home Key opened manually in Wallet. Express-mode ECP wakeup, FAST authentication and unknown-device attestation are separate follow-up work. homekey-go verifies the key; UID detection alone never unlocks. See esp32/PROTOCOL.md for the mailbox format and tests/run.sh for host tests.