drjones/docs
1
0
Fork 0
Code Issues 1 Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit: project docs and ignore rules

Browse Source
This commit is contained in:
Dr Jones
2026-05-03 23:20:16 -07:00
commit cad8577007
4 changed files with 377 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
.gitignore vendored Normal file
View File

@@ -0,0 +1,2 @@
.DS_Store
*.bak

5
README.md Normal file
View File

@@ -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.

231
setup_guide.md Normal file
View File

@@ -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

139
wiring_diagram.md Normal file
View File

@@ -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