From d1068d965b64eb99dc173cde7f2d8efcb1cf5270 Mon Sep 17 00:00:00 2001
From: drjones <drjones@MBook-Air.local>
Date: Wed, 25 Mar 2026 10:37:05 -0700
Subject: [PATCH] first commit

Made-with: Cursor
---
 README.md | 54 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 54 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..6348af5
--- /dev/null
+++ b/README.md
@@ -0,0 +1,54 @@
+# 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.