bw16-research/WiFiX-Enhanced/FLASHING_GUIDE.md

# WiFiX-Enhanced Flashing Guide & Usage Instructions

## Overview
This guide provides comprehensive instructions for flashing and using the WiFiX-Enhanced firmware on BW16 and ESP32 devices. The system creates realistic WiFi captive portals for security testing and research purposes.

## Hardware Requirements

### Primary Components
- **BW16 Module**: Realtek RTL8720DN-based WiFi module (5GHz capable)
- **ESP32 DevKit**: ESP32-WROOM or ESP32-WROVER (for enhanced features)
- **OLED Display**: 128x64 I2C SSD1306 (optional but recommended)
- **SD Card Module**: SPI-based SD card reader for credential storage
- **Power Supply**: 5V 2A minimum (USB or external)

### Pin Connections
```
BW16 to ESP32:
- BW16 TX → ESP32 GPIO16 (RX)
- BW16 RX → ESP32 GPIO17 (TX)
- GND → GND
- 3.3V → 3.3V

OLED Display (I2C):
- SDA → GPIO21
- SCL → GPIO22
- VCC → 3.3V
- GND → GND

SD Card Module (SPI):
- MOSI → GPIO23
- MISO → GPIO19
- CLK → GPIO18
- CS → GPIO5
- VCC → 3.3V
- GND → GND
```

## Software Setup

### Prerequisites
1. **PlatformIO Core** (recommended) or Arduino IDE
2. **USB to Serial Drivers**:
   - CP2102/CH340 drivers for ESP32
   - RTL8720DN drivers for BW16
3. **Python 3.8+** (for PlatformIO)

### Installation Steps

#### 1. Install PlatformIO
```powershell
# Install via pip
pip install platformio

# Or install VS Code extension
# Search for "PlatformIO IDE" in VS Code extensions
```

#### 2. Clone Repository
```powershell
git clone <repository-url>
cd WiFiX-Enhanced
```

#### 3. Install Dependencies
```powershell
pio lib install
```

## Flashing Instructions

### Method 1: PlatformIO (Recommended)

#### ESP32 Firmware
```powershell
# Build and flash ESP32 firmware
pio run -e esp32_main --target upload

# Monitor serial output
pio device monitor -e esp32_main
```

#### BW16 Firmware
```powershell
# Build and flash BW16 firmware
pio run -e bw16_deauth --target upload

# Monitor serial output
pio device monitor -e bw16_deauth
```

### Method 2: Arduino IDE

#### ESP32 Setup
1. Add ESP32 board support:
   - File → Preferences → Additional Boards Manager URLs
   - Add: `https://raw.githubusercontent.com/espressif/arduino-esp32/gh-pages/package_esp32_index.json`
   - Tools → Board → Boards Manager → Search "ESP32" → Install

2. Select board: "ESP32 Dev Module"
3. Configure settings:
   - CPU Frequency: 240MHz
   - Flash Frequency: 80MHz
   - Flash Mode: QIO
   - Flash Size: 4MB
   - Upload Speed: 921600

#### BW16 Setup
1. Add Realtek Ameba support:
   - File → Preferences → Additional Boards Manager URLs
   - Add: `https://github.com/ambiot/ambd_arduino/raw/master/Arduino_package/package_realtek.com_amebad_index.json`
   - Tools → Board → Boards Manager → Search "Ameba" → Install

2. Select board: "BW16"
3. Upload speed: 115200

### Upload File System (SPIFFS)
```powershell
# Upload web interface files
pio run --target uploadfs -e esp32_main
```

## Configuration

### Pre-Flash Configuration
Edit `src/config.h` (create if not exists):
```cpp
#define DEVICE_NAME "CityNet_WiFi"
#define DEFAULT_SSID "CityNet_Public_WiFi"
#define DEFAULT_PASSWORD ""
#define CAPTIVE_PORTAL_IP "192.168.4.1"
#define CAPTIVE_PORTAL_DOMAIN "wifi.citynet.local"
#define SD_CARD_CS_PIN 5
#define OLED_ADDRESS 0x3C
#define ENABLE_SD_BACKUP true
#define ENABLE_DEAUTH true
#define ENABLE_OLED true
```

### Network Configuration
The device creates a WiFi network with these defaults:
- **SSID**: "CityNet_Public_WiFi"
- **Password**: (open network)
- **IP Range**: 192.168.4.0/24
- **Gateway**: 192.168.4.1
- **DNS**: 192.168.4.1

## Usage Instructions

### Initial Setup
1. **Power On**: Connect power to both modules
2. **Wait for Boot**: OLED will show startup sequence
3. **Connect to WiFi**: Look for "CityNet_Public_WiFi" on target device
4. **Access Portal**: Browser should auto-open, or navigate to `http://192.168.4.1`

### Web Interface
The portal includes realistic pages:
- **Login Page**: Professional municipal WiFi portal
- **Welcome Page**: Connection status and usage info
- **Error Pages**: Various authentication failure scenarios

### Credential Collection
- Captured credentials are stored in SPIFFS
- Auto-backup to SD card (if enabled)
- Real-time display on OLED
- Export via serial console or web interface

### OLED Display Information
```
┌─────────────────────────────────┐
│ WiFiX-Enhanced v1.0             │
│ Mode: CAPTIVE PORTAL            │
│ Clients: 3                      │
│ Creds: 12                       │
│ IP: 192.168.4.1                 │
└─────────────────────────────────┘
```

### Serial Console Commands
Connect at 115200 baud and use these commands:
```
help          - Show available commands
status        - Show system status
creds         - List captured credentials
clearcreds    - Clear credential storage
backup        - Manual backup to SD
deauth [MAC]  - Target specific device
reset         - Factory reset
```

## Troubleshooting

### Flashing Issues

#### "Port not found" Error
```powershell
# List available ports
pio device list

# Check Windows Device Manager
# Update drivers if needed
```

#### "Timeout communicating" Error
```powershell
# Hold BOOT button during upload start
# Release when upload begins
# Try lower upload speed (115200)
```

#### "Wrong boot mode" Error
```powershell
# Ensure proper wiring
# Check power supply (must be 3.3V)
# Try different USB cable
```

### Runtime Issues

#### Device Won't Start
1. Check power connections
2. Verify 3.3V regulation
3. Check for short circuits
4. Monitor serial output during boot

#### WiFi Not Visible
1. Check antenna connection
2. Verify BW16 module power
3. Check serial communication
4. Reset both modules

#### Portal Not Loading
1. Verify IP configuration
2. Check DNS redirection
3. Test with different browsers
4. Clear browser cache

#### SD Card Not Working
1. Check SPI connections
2. Verify card format (FAT32)
3. Test with known-good card
4. Check power supply stability

## Safety and Legal Considerations

### Important Notes
- **Educational Use Only**: This tool is for security research and testing
- **Authorization Required**: Only use on networks you own or have permission to test
- **Compliance**: Follow local laws and regulations
- **Ethics**: Respect privacy and data protection laws

### Best Practices
1. Always inform network owners before testing
2. Use in controlled environments
3. Secure collected data appropriately
4. Delete captured credentials after analysis
5. Document your testing procedures

## Performance Optimization

### Power Consumption
- Use deep sleep between activations
- Optimize WiFi transmission power
- Disable unused features
- Consider battery operation for portability

### Range Enhancement
- Use external antennas
- Optimize placement
- Consider power amplifiers
- Test different environments

## Advanced Features

### Custom Portal Templates
Edit files in `data/` directory:
- `index.html` - Login page
- `welcome.html` - Success page
- Add custom CSS/JS for realism

### Credential Export
```powershell
# Export via serial
pio device monitor -e esp32_main | grep "CREDENTIAL"

# Export from SD card
# Remove SD card and read backup files
```

### Integration with Tools
- Wireshark for packet analysis
- Aircrack-ng for advanced attacks
- Custom scripts for automation
- Database storage for large deployments

## Support and Updates

### Getting Help
1. Check this documentation first
2. Review serial console output
3. Test with minimal configuration
4. Document your setup

### Updates
```powershell
# Update PlatformIO
pio update

# Update libraries
pio lib update

# Pull latest code
git pull origin main
```

### Contributing
- Report issues with detailed logs
- Suggest improvements
- Share successful configurations
- Contribute documentation

## Version History
- v1.0.0: Initial release with BW16/ESP32 support
- v1.1.0: Added SD card backup and OLED display
- v1.2.0: Enhanced web interface and credential management

---

**Remember**: With great power comes great responsibility. Use this tool ethically and legally.