Initial commit: project docs and ignore rules

2026-05-03 23:20:16 -07:00
commit cad8577007
4 changed files with 377 additions and 0 deletions
--- a/setup_guide.md
+++ 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