# PN532 NFC Toolkit (ESP32-S3)

Production-style firmware and embedded web UI for **PN532** NFC controllers attached to **ESP32-S3** (and other ESP32-class targets with minor config tweaks).

## Features

- **Wi-Fi AP** default: SSID `PN532-Toolkit`, password `nfc-toolkit`, URL [http://192.168.4.1](http://192.168.4.1)
- **mDNS** hostname `pn532tool.local` (HTTP port 80)
- **REST API**: poll tags, MIFARE Classic read/write, Ultralight page read, PN532 general status, raw command injection, OTA stub (`501` — extend with `esp_https_ota`)
- **WebSocket** `/ws`: continuous tag presence stream when enabled from the UI
- **Web UI** (Vite + React + Tailwind + Framer Motion): dashboard, read/analyze, write helpers, local tag library, key dictionary, raw console, settings

## Build — Web UI

```bash
cd web
npm install
npm run build:fw
```

This compiles the SPA and copies `dist/*` into `firmware/data/` for SPIFFS embedding.

## Build — Firmware (ESP-IDF 5.x)

```bash
cd firmware
idf.py set-target esp32s3
idf.py menuconfig   # PN532 Host → SPI / I2C / UART pins (Kconfig)
idf.py build flash monitor
```

Partition table targets a **8MB** flash module (adjust `partitions.csv` + `sdkconfig` for 4MB/16MB).

## Hardware / Kconfig

Open **Component config → PN532 Host** in `menuconfig`:

- **SPI** (default): MOSI / MISO / SCLK / CS + clock Hz (start **100 kHz** if unstable)
- **I2C**: SDA / SCL, **7-bit address `0x24`** (left-shifted to `0x48` on the wire)
- **UART (HSU)**: TX/RX, **115200**

Refer to [docs/PINOUT.md](docs/PINOUT.md) for ESP32-S3-DevKitC-1 wiring notes.

## Repository layout

| Path | Purpose |
|------|---------|
| `firmware/` | ESP-IDF project, `components/pn532_host`, `nfc_engine`, `net_service` |
| `web/` | SPA source |
| `docs/` | Flashing, workflows, limitations |

## Legal / ethics

Use only on tags and systems you own or are explicitly authorized to test.