# 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](QUICK_START.md) - Get running in 5 minutes
- [Flashing Guide](FLASHING_GUIDE.md) - Comprehensive setup instructions
- [Configuration Template](src/config_template.h) - All settings explained
- [Pin Chart & Wiring](PIN_CHART.md) - Complete connection guide
- [Wiring Diagram](WIRING_DIAGRAM.md) - Visual assembly guide
- [Pin Reference Card](PIN_REFERENCE_CARD.md) - 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)

```powershell
# One-time setup
pip install platformio

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

Or manually:
```powershell
# 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](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.