commit cad8577007c71973ac99296ec4df874a398b1938 Author: Dr Jones Date: Sun May 3 23:20:16 2026 -0700 Initial commit: project docs and ignore rules diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..13d6c95 --- /dev/null +++ b/.gitignore @@ -0,0 +1,2 @@ +.DS_Store +*.bak diff --git a/README.md b/README.md new file mode 100644 index 0000000..1d1461a --- /dev/null +++ b/README.md @@ -0,0 +1,5 @@ +# docs + +Supporting documentation for the **dual PN532** project (see [parent README](../README.md)): schematics, wiring notes, and any PDFs or images you keep beside the `listener_firmware` / `emulator_firmware` split. + +This folder is intentionally lightweight — it is meant to travel with `common/`, `listener_firmware/`, and `emulator_firmware/` when you archive that system. diff --git a/setup_guide.md b/setup_guide.md new file mode 100644 index 0000000..82e2867 --- /dev/null +++ b/setup_guide.md @@ -0,0 +1,231 @@ +# Setup and Usage Guide + +## Prerequisites + +### Software Requirements +- PlatformIO IDE or Arduino IDE with ESP32 support +- USB-C cable for programming ESP32-C3 modules +- Serial monitor for debugging + +### Hardware Requirements +- 2x ESP32-C3 Super Mini modules +- 2x PN532 NFC modules +- 1x MicroSD card module +- 1x MicroSD card (formatted as FAT32) +- Jumper wires +- Breadboards (optional) + +## Step-by-Step Setup + +### 1. Hardware Assembly + +#### Listener Module +1. Connect ESP32-C3 to PN532 according to wiring diagram +2. Set PN532 DIP switches for I2C mode (both switches OFF) +3. Connect status LED to GPIO10 (optional) + +#### Emulator Module +1. Connect ESP32-C3 to PN532 according to wiring diagram +2. Connect ESP32-C3 to SD card module according to wiring diagram +3. Set PN532 DIP switches for I2C mode (both switches OFF) +4. Insert formatted MicroSD card +5. Connect status LED to GPIO2 (optional) + +### 2. Software Installation + +#### Using PlatformIO (Recommended) + +1. **Install PlatformIO** + ```bash + # Install PlatformIO Core + pip install platformio + ``` + +2. **Clone/Download Project** + ```bash + # Navigate to project directory + cd /path/to/dual-nfc-system + ``` + +3. **Build and Upload Listener Firmware** + ```bash + # Connect listener ESP32-C3 via USB + pio run -e listener --target upload --target monitor + ``` + +4. **Build and Upload Emulator Firmware** + ```bash + # Connect emulator ESP32-C3 via USB + pio run -e emulator --target upload --target monitor + ``` + +#### Using Arduino IDE + +1. **Install ESP32 Board Package** + - File → Preferences → Additional Board Manager URLs + - Add: `https://raw.githubusercontent.com/espressif/arduino-esp32/gh-pages/package_esp32_index.json` + - Tools → Board → Boards Manager → Search "ESP32" → Install + +2. **Install Required Libraries** + - Adafruit PN532 Library + - SD Library (built-in) + +3. **Configure Board Settings** + - Board: "ESP32C3 Dev Module" + - Upload Speed: 921600 + - CPU Frequency: 160MHz + - Flash Size: 4MB + - Partition Scheme: Default + +4. **Upload Firmware** + - Open `listener_firmware/src/main.cpp` for listener module + - Open `emulator_firmware/src/main.cpp` for emulator module + - Select correct COM port + - Upload to respective modules + +### 3. Initial Testing + +#### Power-On Sequence +1. **Power on Emulator module first** + - Should show "Emulator module ready - waiting for listener..." + - LED blinks 3 times on startup + +2. **Power on Listener module** + - Should show "Listener module ready!" + - LED blinks 3 times on startup + - Should automatically discover and pair with emulator + +#### Pairing Verification +- Both modules should show pairing success messages +- LEDs on both modules blink 5 times when paired +- Serial monitors show MAC addresses of paired devices + +### 4. Operation + +#### Normal Operation Flow +1. **Automatic Pairing**: Modules automatically discover each other on power-up +2. **NFC Scanning**: Listener continuously scans for NFC tags +3. **Data Transmission**: When tag detected, data sent to emulator instantly +4. **Tag Emulation**: Emulator replicates the captured tag behavior +5. **Data Logging**: All captured data logged to SD card with timestamps + +#### Status Monitoring +- **Serial Output**: Connect to both modules via USB for detailed logs +- **LED Indicators**: Visual status of system operation +- **SD Card Logs**: Persistent storage of all NFC interactions + +## Usage Examples + +### Basic NFC Cloning +1. Present NFC card/tag to listener module +2. Listener LED turns on (tag detected) +3. Data transmitted to emulator +4. Emulator LED turns on (emulation active) +5. Present NFC reader to emulator module +6. Reader should detect the cloned tag + +### Data Analysis +1. Remove SD card from emulator module +2. Insert into computer +3. Open log file (CSV format) +4. Analyze captured NFC data + +## Troubleshooting + +### Common Issues + +#### Modules Won't Pair +- **Check Power**: Ensure both modules are properly powered +- **Check Serial Output**: Look for error messages +- **Reset Modules**: Power cycle both modules +- **Check Distance**: Ensure modules are within ESP-NOW range (~100m) + +#### PN532 Not Detected +- **Check Wiring**: Verify I2C connections (SDA/SCL) +- **Check Power**: Ensure 3.3V supply is stable +- **Check DIP Switches**: Both switches should be OFF for I2C mode +- **Check Pull-ups**: I2C requires pull-up resistors (usually built-in) + +#### SD Card Issues +- **Format**: Ensure SD card is formatted as FAT32 +- **Size**: Use SD cards ≤32GB for best compatibility +- **Connections**: Verify SPI wiring +- **Power**: Ensure stable 3.3V supply + +#### NFC Detection Problems +- **Distance**: Keep NFC tags close to PN532 antenna +- **Orientation**: Try different tag orientations +- **Tag Type**: Some exotic NFC types may not be supported +- **Interference**: Keep away from metal objects and other RF sources + +### Debug Commands + +#### Serial Monitor Commands +``` +# Check system status +Status: [Paired/Unpaired] +Last heartbeat: [timestamp] +NFC tags detected: [count] +``` + +#### LED Diagnostic Patterns +- **Continuous single blinks**: Hardware error +- **No LED activity**: Power or firmware issue +- **Rapid blinking**: Communication error + +## Performance Optimization + +### Range Extension +- Use external antennas for ESP32-C3 modules +- Position modules for optimal line-of-sight +- Avoid interference sources (WiFi, Bluetooth, metal objects) + +### Power Management +- Implement sleep modes for battery operation +- Use external power supplies for continuous operation +- Monitor current consumption + +### Data Throughput +- Adjust scan intervals based on requirements +- Implement data compression for large payloads +- Use acknowledgment system for critical data + +## Security Considerations + +### Data Protection +- NFC data is transmitted unencrypted over ESP-NOW +- Consider adding encryption for sensitive applications +- SD card data is stored in plain text + +### Access Control +- Physical access to modules allows firmware modification +- SD card data is accessible to anyone with physical access +- Consider tamper-evident enclosures for production use + +## Maintenance + +### Regular Checks +- Monitor SD card storage space +- Check for firmware updates +- Verify connection stability +- Clean NFC antenna surfaces + +### Log Management +- Rotate log files periodically +- Archive important capture sessions +- Monitor SD card health + +## Advanced Configuration + +### Custom Parameters +Edit `common/nfc_protocol.h` to modify: +- Communication timeouts +- Data buffer sizes +- Retry attempts +- Heartbeat intervals + +### Extended Features +- Add WiFi connectivity for remote monitoring +- Implement web interface for configuration +- Add GPS logging for location tracking +- Integrate with external databases \ No newline at end of file diff --git a/wiring_diagram.md b/wiring_diagram.md new file mode 100644 index 0000000..c2fe7a1 --- /dev/null +++ b/wiring_diagram.md @@ -0,0 +1,139 @@ +# Wiring Diagrams for Dual PN532 NFC System + +## ESP32-C3 Super Mini Pinout Reference + +``` + ESP32-C3 Super Mini + ┌─────────────────┐ + │ [USB-C] │ + │ │ + 3V3 ●──┤ 3V3 GND ├──● GND + GND ●──┤ GND D0 ├──● GPIO0 + D1 ●──┤ D1 D1 ├──● GPIO1 + D2 ●──┤ D2 D2 ├──● GPIO2 + D3 ●──┤ D3 D3 ├──● GPIO3 + D4 ●──┤ D4 D4 ├──● GPIO4 + D5 ●──┤ D5 D5 ├──● GPIO5 + D6 ●──┤ D6 D6 ├──● GPIO6 + D7 ●──┤ D7 D7 ├──● GPIO7 + D8 ●──┤ D8 D8 ├──● GPIO8 + D9 ●──┤ D9 D9 ├──● GPIO9 + D10 ●──┤ D10 D10 ├──● GPIO10 + └─────────────────┘ +``` + +## Listener Module Wiring + +### ESP32-C3 to PN532 (I2C Mode) + +``` +ESP32-C3 Super Mini PN532 Module +┌─────────────────┐ ┌─────────────┐ +│ │ │ │ +│ 3V3 ────┼─────────┤ VCC │ +│ GND ────┼─────────┤ GND │ +│ GPIO8 (SDA) ────┼─────────┤ SDA │ +│ GPIO9 (SCL) ────┼─────────┤ SCL │ +│ GPIO10 ────┼─────────┤ LED (opt) │ +│ │ │ │ +└─────────────────┘ └─────────────┘ +``` + +### PN532 DIP Switch Configuration (I2C Mode) +``` +Switch 1: OFF (I2C mode) +Switch 2: OFF (I2C mode) +``` + +## Emulator Module Wiring + +### ESP32-C3 to PN532 (I2C Mode) + +``` +ESP32-C3 Super Mini PN532 Module +┌─────────────────┐ ┌─────────────┐ +│ │ │ │ +│ 3V3 ────┼─────────┤ VCC │ +│ GND ────┼─────────┤ GND │ +│ GPIO8 (SDA) ────┼─────────┤ SDA │ +│ GPIO9 (SCL) ────┼─────────┤ SCL │ +│ │ │ │ +└─────────────────┘ └─────────────┘ +``` + +### ESP32-C3 to SD Card Module (SPI Mode) + +``` +ESP32-C3 Super Mini SD Card Module +┌─────────────────┐ ┌─────────────┐ +│ │ │ │ +│ 3V3 ────┼─────────┤ VCC │ +│ GND ────┼─────────┤ GND │ +│ GPIO10 (CS) ────┼─────────┤ CS │ +│ GPIO6 (MOSI)────┼─────────┤ MOSI │ +│ GPIO5 (MISO)────┼─────────┤ MISO │ +│ GPIO4 (SCK) ────┼─────────┤ SCK │ +│ GPIO2 ────┼─────────┤ LED (opt) │ +│ │ │ │ +└─────────────────┘ └─────────────┘ +``` + +## Complete Emulator Module Wiring + +``` + ESP32-C3 Super Mini + ┌─────────────────┐ + │ │ + PN532 VCC ──┤ 3V3 │ + SD Card VCC ──┤ │ + │ │ + PN532 GND ──┤ GND │ + SD Card GND ──┤ │ + │ │ + │ D2 ├── LED (Status) + │ D4 ├── SD Card SCK + │ D5 ├── SD Card MISO + │ D6 ├── SD Card MOSI + │ D8 ├── PN532 SDA + │ D9 ├── PN532 SCL + │ D10 ├── SD Card CS + │ │ + └─────────────────┘ +``` + +## Power Considerations + +- **Voltage**: Both PN532 and SD card modules operate at 3.3V +- **Current**: ESP32-C3 can provide sufficient current for both modules +- **Power Supply**: Use quality USB cable or external 3.3V supply for stable operation + +## Troubleshooting + +### I2C Issues +- Check SDA/SCL connections +- Verify pull-up resistors (usually built into modules) +- Ensure PN532 DIP switches are set correctly + +### SD Card Issues +- Verify SPI connections +- Check SD card formatting (FAT32 recommended) +- Ensure proper power supply + +### Communication Issues +- Check ESP-NOW channel settings +- Verify both modules are powered and programmed correctly +- Monitor serial output for pairing status + +## LED Status Indicators + +### Listener Module (GPIO10) +- **3 quick blinks**: System startup +- **5 quick blinks**: Successfully paired with emulator +- **Solid ON**: NFC tag detected +- **Single blink every 500ms**: PN532 error + +### Emulator Module (GPIO2) +- **3 quick blinks**: System startup +- **5 quick blinks**: Successfully paired with listener +- **Solid ON**: Emulating NFC tag +- **Single blink every 500ms**: PN532 error \ No newline at end of file