docs/setup_guide.md

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

   # Install PlatformIO Core
   pip install platformio
   

2. Clone/Download Project

   # Navigate to project directory
   cd /path/to/dual-nfc-system
   

3. Build and Upload Listener Firmware

   # Connect listener ESP32-C3 via USB
   pio run -e listener --target upload --target monitor
   

4. Build and Upload Emulator Firmware

   # 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