# NFC Scanner - ESP32 & PN532

A comprehensive NFC/RFID scanner that extracts maximum legal/public data from cards using ESP32-S3 and PN532.

## Hardware Setup

### Components
- **XIAO ESP32-S3** - Main microcontroller
- **Elechouse PN532 NFC Module** - NFC/RFID reader
- **Battery** (optional) - For portable operation

### Wiring (SPI Mode)
| XIAO ESP32-S3 | PN532 | Function |
|---------------|-------|----------|
| GPIO9 (MOSI)  | MOSI  | SPI Data Out |
| GPIO8 (MISO)  | MISO  | SPI Data In |
| GPIO7 (SCK)   | SCK   | SPI Clock |
| GPIO1 (A0/D0) | SS/SDA| Chip Select |
| 5V or 3V3     | VCC   | Power |
| GND           | GND   | Ground |

### PN532 Configuration
Set your Elechouse PN532 to **SPI mode** using the onboard DIP switches/jumpers according to the module's silkscreen.

## Software Features

### NFC Technologies Supported
- **ISO14443 Type A** - MIFARE Classic, Ultralight, NTAG
- **ISO14443 Type B** - Government/corporate cards
- **FeliCa** - Japanese transit cards
- **Multi-tech discovery** with anti-collision

### Data Extraction
- **UID/NUID** - Unique identifiers
- **ATQA/SAK/ATS** - Protocol parameters
- **Type 2 Cards**: CC, TLVs, user pages, GET_VERSION, lock bits, signature
- **Type 4 Cards**: NDEF applications, CC/NDEF files, frame size limits
- **FeliCa**: System codes, service lists, public blocks
- **NDEF Parsing** - All record types and payloads
- **Timing Statistics** - Performance metrics

### Web Interface
- **WiFi Access Point** - Creates its own network "NFC-Scanner"
- **REST API** - `/version`, `/scan`, `/dump` endpoints
- **Simple UI** - Scan and dump buttons with JSON display
- **Real-time Results** - Immediate feedback

## Getting Started

### 1. Hardware Assembly
1. Wire the PN532 to ESP32-S3 according to the wiring table above
2. Set PN532 to SPI mode using DIP switches
3. Connect battery to BAT pads (optional)

### 2. Software Setup
1. Install PlatformIO in VS Code
2. Open this project folder
3. Build and upload: `pio run -t upload`

### 3. Usage
1. Power on the device
2. Connect to WiFi network: **NFC-Scanner** (password: `nfc123456`)
3. Open browser to: `http://192.168.4.1`
4. Use Scan/Dump buttons to read NFC cards

## API Endpoints

### GET /version
Returns PN532 firmware version and system info.

### GET /scan  
Performs one-shot multi-tech discovery, returns UID and card type.

### GET /dump
Extracts maximum public data from detected card, includes raw hex and parsed NDEF.

## Security & Ethics

- **Read-only by default** - No writing to cards
- **Public data only** - No key guessing or unauthorized access
- **LAN-only** - WiFi AP mode for local access
- **Audit trail** - All responses include timestamps

## Development Roadmap

### Current (MVP)
- [x] SPI communication with PN532
- [x] WiFi Access Point mode
- [x] Basic web interface
- [x] Multi-tech card detection
- [x] Type A card data extraction

### Future Enhancements
- [ ] Full NDEF record parsing
- [ ] Type B and FeliCa support
- [ ] WebSocket real-time updates
- [ ] Scan history and export
- [ ] OTA firmware updates
- [ ] Advanced mode with user-provided keys

## Troubleshooting

### PN532 Not Detected
- Check SPI wiring connections
- Verify PN532 is set to SPI mode
- Check power supply (3.3V or 5V depending on module)

### WiFi Connection Issues
- Look for "NFC-Scanner" network
- Default password: `nfc123456`
- Default IP: `192.168.4.1`

### Card Reading Issues
- Ensure card is close to PN532 antenna
- Try different card orientations
- Check for metal interference near antenna

## License

This project is for educational and research purposes. Respect local laws and card holder privacy.