bw16-research/WiFiX-Enhanced/README.md

WiFiX-Enhanced

A professional-grade WiFi captive portal system for security research and testing, featuring realistic web interfaces, credential collection, and advanced deauthentication capabilities.

🎯 Features

Core Capabilities

• Dual-Module Architecture: ESP32 + BW16 for maximum performance
• Realistic Web Portals: Professional municipal WiFi interface
• Credential Collection: Secure storage with encryption and SD backup
• 5GHz Deauthentication: Targeted disconnection of modern devices
• OLED Display: Real-time status and credential monitoring
• Auto-Backup: Automatic credential backup to SD card
• Multiple Authentication Types: Generic, Hotel, Corporate, Public, Social

Technical Specifications

• ESP32 Framework: Arduino Core with PlatformIO
• BW16 Module: Realtek RTL8720DN (5GHz capable)
• Storage: SPIFFS + SD card support
• Display: 128x64 I2C OLED (SSD1306)
• Web Interface: Responsive HTML5 with JavaScript
• Security: AES encryption for stored credentials

📚 Documentation

Quick Start

• Quick Start Guide - Get running in 5 minutes
• Flashing Guide - Comprehensive setup instructions
• Configuration Template - All settings explained
• Pin Chart & Wiring - Complete connection guide
• Wiring Diagram - Visual assembly guide
• Pin Reference Card - Quick reference

Hardware Setup

• Pin Connections: See FLASHING_GUIDE.md for detailed wiring
• Power Requirements: 5V 2A minimum
• Antennas: External recommended for range

Software Requirements

• PlatformIO Core (recommended) or Arduino IDE
• USB Drivers: CP2102/CH340 for ESP32, RTL8720DN for BW16
• Python 3.8+ for PlatformIO

⚡ Quick Flash (Windows)

# One-time setup
pip install platformio

# Flash everything
flash_windows.bat
# Select option 4: "Flash All (ESP32 + Web Files)"

Or manually:

# Flash ESP32
pio run -e esp32_main --target upload

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

# Flash BW16
pio run -e bw16_deauth --target upload

🔧 Configuration

1. Copy src/config_template.h to src/config.h
2. Modify settings as needed:
   • Network SSID and passwords
   • Hardware pin assignments
   • Feature toggles
   • Security settings

📱 Usage

Connection Process

1. Power on device (both modules)
2. Connect to "CityNet_Public_WiFi" network
3. Browser auto-opens to captive portal
4. Enter credentials on realistic login page
5. View captured data on OLED display

Serial Console Commands (115200 baud)

help          # Show available commands
status        # System status
creds         # List captured credentials
clearcreds    # Clear credential storage
backup        # Manual backup to SD
deauth [MAC]  # Target specific device
reset         # Factory reset

🛡️ Safety & Legal

IMPORTANT: This tool is for authorized security testing only!

• Use only on networks you own or have explicit permission to test
• Follow all applicable laws and regulations
• Respect privacy and data protection requirements
• Delete captured credentials after analysis
• Document your testing procedures

📁 Project Structure

WiFiX-Enhanced/
├── data/                   # Web interface files
│   ├── index.html         # Login portal
│   └── welcome.html       # Success page
├── src/                    # Source code
│   ├── esp32_enhanced.ino # Main ESP32 firmware
│   ├── bw16_5ghz_deauth.ino # BW16 deauth firmware
│   ├── credential_manager.cpp # Credential handling
│   ├── credential_manager.h
│   ├── oled_display.cpp   # OLED interface
│   └── oled_display.h
├── platformio.ini         # Build configuration
├── FLASHING_GUIDE.md      # Detailed setup guide
├── QUICK_START.md         # Rapid deployment guide
└── flash_windows.bat      # Windows flashing script

🚀 Advanced Features

Credential Management

• Encrypted storage with AES-256
• Automatic SD card backup
• Multiple credential types (Generic, Hotel, Corporate, Public, Social)
• Real-time statistics on OLED
• CSV export capability

Web Interface

• Professional municipal WiFi branding
• Responsive design for all devices
• Real-time connection status
• Session management with countdown timer
• Social login simulation

Deauthentication

• Targeted 5GHz deauth attacks
• Channel hopping for maximum coverage
• Whitelist support for protected devices
• Configurable attack intervals

🐛 Troubleshooting

Common Issues

• Port not found: Install USB drivers, check Device Manager
• Upload timeout: Hold BOOT button during upload
• No WiFi: Check antenna connections, verify BW16 power
• Portal won't load: Clear browser cache, try different browser

See FLASHING_GUIDE.md for detailed troubleshooting.

🤝 Contributing

1. Fork the repository
2. Create feature branch
3. Test thoroughly on hardware
4. Submit pull request with documentation

📄 License

This project is for educational and authorized security testing purposes only. Users are responsible for complying with all applicable laws and regulations.

⚠️ Disclaimer

This tool is provided as-is for legitimate security research and testing. The authors are not responsible for misuse or any damages resulting from use of this software. Always obtain proper authorization before testing any network.

---

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