# 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](esp32/PROTOCOL.md).

## 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

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

## Current flow

```text
```

Service UUID:

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

Advertisement payload after the UUID:

```text
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.