# NFC Box Connection Guide

This guide matches the firmware pin setup in `nfc.code`.

## 1) Main Controller

- Board: ESP32 (DevKit style)
- Serial speed: 115200

## 2) Pin Mapping Summary

### OLED Display (I2C, SSD1306 at 0x3C)

| OLED Pin | ESP32 Pin |
|---|---|
| VCC | 3V3 (or module-supported VCC) |
| GND | GND |
| SDA | GPIO 21 |
| SCL | GPIO 22 |

### RFID Reader (MFRC522, SPI)

| RC522 Pin | ESP32 Pin |
|---|---|
| VCC | 3V3 |
| GND | GND |
| SDA / SS | GPIO 5 |
| SCK | GPIO 18 |
| MOSI | GPIO 23 |
| MISO | GPIO 19 |
| RST | GPIO 4 |
| IRQ | Not connected |

### Buttons

The firmware uses `INPUT_PULLUP`, so each button should connect between the GPIO pin and GND (no external pull-up resistor required).

| Button | ESP32 Pin | Other Side |
|---|---|---|
| BTN1 | GPIO 15 | GND |
| BTN2 | GPIO 14 | GND |
| BTN3 | GPIO 32 | GND |

### Buzzer

| Device Pin | ESP32 Pin |
|---|---|
| Buzzer Signal (+) | GPIO 26 |
| Buzzer GND (-) | GND |

Note: If your buzzer draws high current, drive it through a transistor instead of directly from GPIO.

## 3) Important Wiring Rules

- Use a common GND for ESP32, OLED, RFID, buzzer, and buttons.
- Keep RC522 on 3.3V (do not power MFRC522 with 5V).
- Confirm OLED I2C address is `0x3C` (as used in firmware).
- Keep SPI wires short and solid to avoid read failures.

## 4) Quick Bring-Up Check

1. Power on ESP32.
2. OLED should show boot screens (`ARIGATOO`, then `NFC BOX`).
3. Press BTN3 to enter mode menu.
4. Tap an RFID card near RC522.
5. UID should appear on OLED and print in Serial Monitor.

## 5) Firmware Pins Reference

The mapping above is taken from these definitions in `nfc.code`:

- `SDA_PIN 21`, `SCL_PIN 22`
- `BTN1 15`, `BTN2 14`, `BTN3 32`
- `BUZZER 26`
- `SS_PIN 5`, `RST_PIN 4`
- `SPI.begin(18, 19, 23, 5)`

## 6) Wi-Fi Attendance Setup

The firmware now sends attendance directly to your web server over Wi-Fi.

### A) Configure Wi-Fi and API URL in firmware

Open `nfc.code` and update:

- `WIFI_SSID`
- `WIFI_PASSWORD`
- `API_BASE_URL`

Example:

- `API_BASE_URL = "http://192.168.1.100/nfc/api"`

Use your PC's LAN IP address, not `localhost`.

### B) Start server

- Start Apache in XAMPP.
- Ensure project path is served at `http://<PC_IP>/nfc`.

### C) Verify API endpoints in browser

Check these URLs from phone or browser on same Wi-Fi:

- `http://<PC_IP>/nfc/api/get_mode.php`
- `http://<PC_IP>/nfc/api/attend.php?uid=TEST01&source=esp32&raw=1`

You should receive plain text responses like:

- `SUCCESS|Name|Status`
- `ERROR|Message`

### D) Flash and test device

1. Upload firmware to ESP32.
2. Open Serial Monitor at `115200`.
3. Wait for Wi-Fi connected message and IP print.
4. Add real UID users from `users.html`.
5. Tap card on NFC reader.

Expected behavior:

- OLED shows short result (for example `PRESENT`, `CHECK-IN`, `ALREADY`).
- Serial Monitor prints API response.
- Attendance appears in `dashboard.html` and `analytics.html`.

### E) Mode sync behavior

- Enter menu with `BTN3`.
- Change mode using `BTN1` and `BTN2`.
- Press `BTN3` to confirm.

On confirm, firmware sends mode to:

- `api/set_mode.php?mode=clg|school|office|construction`