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

# Install via pip
pip install platformio

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

2. Clone Repository

git clone <repository-url>
cd WiFiX-Enhanced

3. Install Dependencies

pio lib install

Flashing Instructions

Method 1: PlatformIO (Recommended)

ESP32 Firmware

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

# Monitor serial output
pio device monitor -e esp32_main

BW16 Firmware

# 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)

# Upload web interface files
pio run --target uploadfs -e esp32_main

Configuration

Pre-Flash Configuration

Edit src/config.h (create if not exists):

#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

# List available ports
pio device list

# Check Windows Device Manager
# Update drivers if needed

"Timeout communicating" Error

# Hold BOOT button during upload start
# Release when upload begins
# Try lower upload speed (115200)

"Wrong boot mode" Error

# 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

# 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

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