bw16-research/ResearchSPEC.md

# WiFiX-Enhanced Research Specification

## 1. Objective & Scope
This project is a **dual-band WiFi deauthentication and evil portal system** designed for wireless penetration testing. It combines an ESP32 for 2.4GHz operations and evil portal hosting with a BW16 module for 5GHz deauthentication attacks, enabling coordinated dual-band security testing.

## 2. Hardware Requirements

### **Core Components:**
- **ESP32 Development Board** (ESP32-WROOM-32 or equivalent)
- **BW16 Module** (Realtek RTL8720DN-based 5GHz WiFi module)
- **OLED Display** (SSD1306 128x64 I2C)
- **Power Supply** (5V 2A recommended for both devices)

### **ESP32 Pin Configuration:**
```
SSD1306_SDA  = GPIO 21
SSD1306_SCL  = GPIO 22
BW16_UART_TX = GPIO 17
BW16_UART_RX = GPIO 16
```

### **BW16 Pin Configuration:**
```
ESP32_UART_TX = GPIO 7
ESP32_UART_RX = GPIO 8
```

### **Optional Components:**
- **LoRa Module** (SX1276) - GPIO 5 (SS), 14 (RST), 2 (DIO0)
- **Bluetooth** (Built-in ESP32)
- **SPIFFS Storage** (For portal templates and credential storage)

## 3. Framework/SDK Requirements

### **ESP32 Framework:**
- **Arduino Core for ESP32** (v3.3.1+)
- **ESP-IDF Compatibility Layer** for raw 802.11 packet injection

### **BW16 Framework:**
- **Realtek AmebaD SDK** (v3.1.9+)
- **WiFi Compatibility Layer** for promiscuous mode operations

## 4. Libraries & Dependencies

### **Core Libraries:**
```cpp
#include <WiFi.h>          // ESP32 WiFi
#include <WebServer.h>     // HTTP server
#include <DNSServer.h>     // DNS server for captive portal
#include <SPIFFS.h>        // File system for templates
#include <ArduinoJson.h>   // JSON communication
#include <SSD1306Wire.h>   // OLED display
#include <BluetoothSerial.h> // Bluetooth attacks
```

### **Advanced Features:**
```cpp
#include <TensorFlowLite_ESP32.h> // AI target selection
#include <LoRa.h>           // LoRa communication
#include <vector>          // STL containers
```

### **PlatformIO Configuration:**
```ini
[env:esp32]
platform = espressif32
board = esp32dev
framework = arduino
monitor_speed = 115200

[env:bw16]
platform = realtek-ameba
board = bw16
framework = arduino
```

## 5. Communication Protocols

### **UART Serial Communication:**
- **Baud Rate:** 115200
- **Protocol:** JSON-based messages
- **Message Types:**
  - `BW16_READY` - Module initialization complete
  - `DEAUTH_SUCCESS` - Successful 5GHz deauthentication
  - `start_scan_5ghz` - Initiate 5GHz scanning
  - `start_deauth` - Begin deauthentication attack

### **JSON Message Structure:**
```json
{
  "type": "DEAUTH_SUCCESS",
  "data": "{\"target\":\"AA:BB:CC:DD:EE:FF\",\"ssid\":\"TestNetwork\"}"
}
```

## 6. Attack Capabilities

### **5GHz Deauthentication (BW16):**
- **Channels:** 36, 40, 44, 48, 149, 153, 157, 161, 165
- **Packet Injection:** Raw 802.11 deauth frames
- **Burst Mode:** 50 packets per burst, 100ms intervals
- **Success Detection:** 10+ successful deauths triggers ESP32

### **2.4GHz Evil Portal (ESP32):**
- **Captive Portal:** DNS hijacking and web server
- **Templates:** Corporate, Hotel, Coffee Shop, Airport, Generic
- **Credential Harvesting:** Form capture and storage
- **AI Integration:** Target selection using machine learning

### **Additional Attack Vectors:**
- **Bluetooth:** SerialBT for additional wireless attacks
- **LoRa:** Long-range communication for distributed attacks
- **Zigbee:** IoT device targeting (placeholder)

## 7. Documentation Requirements

### **Immediate Needs:**
1. **Hardware Setup Guide** - Physical wiring and connections
2. **Flashing Instructions** - Step-by-step firmware deployment
3. **Library Installation** - Dependency management
4. **Usage Manual** - Operational procedures and safety

### **Technical Documentation:**
1. **API Documentation** - Communication protocol specs
2. **Attack Methodology** - Technical details of deauthentication
3. **Security Considerations** - Legal and ethical guidelines

### **Reference Materials Needed:**
1. **ESP32 Datasheets** - Pinouts and capabilities
2. **BW16 Technical Reference** - Realtek RTL8720DN documentation
3. **802.11 Protocol Specs** - Deauthentication frame structure
4. **WiFi Security Standards** - WPA2/WPA3 vulnerabilities

## 8. Risks & Constraints

### **Technical Limitations:**
- **5GHz Range:** Limited by BW16 antenna design
- **Concurrent Operations:** ESP32 handles multiple tasks
- **Memory Constraints:** Limited SPIFFS storage for templates
- **Power Requirements:** High current draw during attacks

### **Legal Considerations:**
- **Authorization Required:** Only test on owned networks
- **Regulatory Compliance:** FCC/CE regulations for radio transmission
- **Ethical Guidelines:** Responsible disclosure principles

### **Security Risks:**
- **Credential Storage:** Encrypted storage required
- **Network Exposure:** Isolated testing environment recommended
- **Firmware Integrity:** Signed updates to prevent tampering

## 9. Development Tools

### **Required Software:**
- **Arduino IDE** or **PlatformIO**
- **ESP32 Board Package** (v3.3.1+)
- **Realtek AmebaD Board Package** (v3.1.9+)
- **Python 3.8+** (for optional AI components)

### **Testing Equipment:**
- **WiFi Analyzer** - For attack verification
- **Spectrum Analyzer** - Optional for RF analysis
- **Isolated Test Network** - Safety and compliance

## 10. Glossary

- **BSSID** - Basic Service Set Identifier (MAC address of AP)
- **Deauthentication** - 802.11 management frame forcing disconnection
- **Evil Twin** - Rogue access point mimicking legitimate network
- **Promiscuous Mode** - WiFi interface capturing all traffic
- **SPIFFS** - SPI Flash File System for ESP32

---

*This documentation serves as the foundation for understanding, deploying, and operating the WiFiX-Enhanced penetration testing system. All operations must comply with local laws and regulations.*