Initial commit: project docs and ignore rules

2026-05-03 23:19:51 -07:00
commit 197724f7a5
55 changed files with 35824 additions and 0 deletions
--- a/ESP32-C5-Toolkit/BUILD_SUCCESS.md
+++ b/ESP32-C5-Toolkit/BUILD_SUCCESS.md
@@ -0,0 +1,241 @@
+# ESP32-C5 Toolkit - Build & Flash Summary
+
+## ✅ BUILD SUCCESSFUL - FIRMWARE FLASHED
+
+**Date**: December 9, 2024  
+**Firmware Version**: ESP32-C5 Toolkit v2.0  
+**Binary Size**: 998KB (1021584 bytes)  
+**Partition Usage**: 97% (3% free space)  
+**Target**: ESP32-C5 (RISC-V, revision v1.0)  
+**Device MAC**: d0:cf:13:e0:a6:b8
+
+---
+
+## Changes Made
+
+### 1. Fixed Missing `index_html` Declaration
+- **File**: `main/web_server.c`
+- **Fix**: Added `static const char index_html[] =` before HTML content
+
+### 2. Updated Component Dependencies
+- **File**: `main/CMakeLists.txt`
+- Changed `json` to `cjson` (ESP-IDF v6.x compatibility)
+- Created `main/idf_component.yml` to include espressif/cjson dependency
+
+### 3. Temporarily Disabled Bluetooth
+- **Reason**: BLE GAP functions have linking issues in current IDF version for ESP32-C5
+- **Files Modified**:
+  - `main/main.c` - Commented out `bt_scanner_init()`
+  - `main/web_server.c` - Stubbed BT API handlers
+  - `main/CMakeLists.txt` - Removed `bt_scanner.c` from build
+  - `main/bt_scanner.c` - Added `#ifdef CONFIG_BT_BLE_ENABLED` guards
+- **Impact**: Bluetooth features disabled, all WiFi features work perfectly
+
+### 4. Frame Bypass Functions
+- **File**: `main/wifi_init.c`
+- Changed `__attribute__((used))` to `__attribute__((weak))` 
+- Prevents multiple definition errors with WiFi library
+
+### 5. Partition Table
+- **Configuration**: `CONFIG_PARTITION_TABLE_SINGLE_APP_LARGE=y`
+- **App Size**: 1MB (fits firmware perfectly)
+
+---
+
+## Device Access
+
+### WiFi Network
+- **SSID**: `ESP32-C5-Toolkit`
+- **Password**: `h4ck3rm4n`
+- **IP Address**: `192.168.4.1`
+
+### Web Interface
+1. Connect to ESP32-C5-Toolkit WiFi
+2. Open browser to: **http://192.168.4.1**
+
+---
+
+## Available Features
+
+### ✅ Working Features
+- **WiFi Scanner**: Dual-band (2.4GHz + 5GHz) network discovery
+- **Packet Sniffer**: Advanced packet capture with filtering
+- **Deauth Engine**: Dual-band deauth attacks (2.4GHz + 5GHz simultaneously)
+- **Signal Analysis**: Real-time RSSI tracking and channel utilization
+- **Channel Map**: Visual channel occupancy mapping
+- **System Dashboard**: Real-time stats, graphs, and monitoring
+- **Web Interface**: Hacker-style UI with Chart.js visualizations
+
+### ⚠️ Temporarily Disabled
+- **Bluetooth Scanner**: BLE linking issues (will fix in next update)
+- **Bluetooth Jamming**: Depends on BLE scanner
+
+---
+
+## Deauth Engine Usage
+
+### From Web Interface
+
+1. Navigate to **DEAUTH ENGINE** page
+2. Click **SCAN NETWORKS** to discover targets
+3. Select targets:
+   - Click **2.4GHz** button for 2.4GHz targets
+   - Click **5GHz** button for 5GHz targets
+   - You can select BOTH bands simultaneously
+4. Set **Duration** (10-600 seconds)
+5. Click **START ATTACK**
+6. Monitor real-time statistics:
+   - Total packets sent
+   - 2.4GHz packets
+   - 5GHz packets
+   - Elapsed time
+
+### How It Works
+- **Dual-Band Simultaneous**: Rapidly switches between 2.4GHz and 5GHz targets
+- **Fast Channel Switching**: 5ms delays for optimal performance
+- **Multiple Reason Codes**: Uses 5 different deauth reason codes (0x01, 0x03, 0x06, 0x07, 0x08)
+- **Burst Mode**: Sends 10 packets per channel per cycle
+- **AP Preservation**: AP mode is disabled during attack, restored after completion
+
+### Performance
+- **Expected PPS**: 400-800+ packets/second
+- **Channel Switch Rate**: ~100 cycles/second
+- **Effectiveness**: Excellent on most devices
+
+---
+
+## Technical Details
+
+### Build Configuration
+- **IDF Version**: v6.1-dev-786-g130fdc7ce7
+- **Compiler**: riscv32-esp-elf-gcc 15.2.0
+- **Target**: esp32c5
+- **Optimization**: -Og (debug optimize)
+- **Flash Mode**: DIO
+- **Flash Frequency**: 80MHz
+- **Flash Size**: 2MB
+
+### Memory Usage
+- **Bootloader**: 22KB
+- **Partition Table**: 3KB
+- **Application**: 998KB
+- **Free Space**: 26KB (3%)
+
+### Components Used
+- WiFi (esp_wifi)
+- HTTP Server (esp_http_server)
+- cJSON for JSON parsing
+- FreeRTOS for task management
+- NVS for settings storage
+- Signal analysis engine
+- Custom deauth engine
+
+---
+
+## Serial Monitor
+
+To view detailed logs and debugging info:
+
+```bash
+cd ESP32-C5-Toolkit
+source ~/esp-idf/export.sh
+idf.py -p /dev/tty.usbmodem5A7A0357351 monitor
+```
+
+Press `Ctrl+]` to exit monitor.
+
+---
+
+## Next Steps
+
+### To Re-enable Bluetooth
+
+Once ESP-IDF fixes BLE GAP linking for ESP32-C5:
+
+1. Uncomment in `main/main.c`:
+   ```c
+   #include "bt_scanner.h"
+   bt_scanner_init();
+   ```
+
+2. Restore in `main/CMakeLists.txt`:
+   ```cmake
+   "bt_scanner.c"
+   ```
+   and add `bt` to REQUIRES
+
+3. Restore in `main/web_server.c`:
+   ```c
+   #include "bt_scanner.h"
+   ```
+   and restore full API handlers
+
+4. Enable in sdkconfig:
+   ```
+   CONFIG_BT_ENABLED=y
+   CONFIG_BT_BLUEDROID_ENABLED=y (or CONFIG_BT_NIMBLE_ENABLED=y)
+   CONFIG_BT_BLE_ENABLED=y
+   ```
+
+### To Rebuild and Reflash
+
+```bash
+cd ESP32-C5-Toolkit
+source ~/esp-idf/export.sh
+idf.py build
+idf.py -p /dev/tty.usbmodem5A7A0357351 flash
+```
+
+---
+
+## Legal Notice
+
+⚠️ **USE ONLY ON NETWORKS YOU OWN OR HAVE EXPLICIT PERMISSION TO TEST**
+
+Unauthorized use of deauth attacks or network interference may be illegal in your jurisdiction. This tool is for **AUTHORIZED TESTING AND EDUCATIONAL PURPOSES ONLY**. You are responsible for your actions.
+
+---
+
+## Support
+
+### Logs Location
+- Build logs: `build/log/`
+- Serial output: Available via `idf.py monitor`
+
+### Common Issues
+
+**Q: Web interface doesn't load?**
+- Ensure you're connected to ESP32-C5-Toolkit WiFi
+- Try http://192.168.4.1 (not https)
+- Check serial monitor for errors
+
+**Q: Deauth not working?**
+- Verify target is on correct band (2.4GHz or 5GHz)
+- Some devices have deauth protection
+- Check AP mode restored after attack
+
+**Q: Partition table errors?**
+- Using `CONFIG_PARTITION_TABLE_SINGLE_APP_LARGE=y`
+- 1MB app partition (sufficient for current build)
+
+---
+
+## Firmware Features Summary
+
+| Feature | Status | Details |
+|---------|--------|---------|
+| WiFi Scanner | ✅ Working | Dual-band 2.4/5GHz |
+| Packet Sniffer | ✅ Working | All frame types, channel hopping |
+| Deauth Engine | ✅ Working | Simultaneous dual-band attacks |
+| Signal Analysis | ✅ Working | RSSI tracking, channel util |
+| Web Dashboard | ✅ Working | Real-time graphs via Chart.js |
+| BT Scanner | ⚠️ Disabled | Linking issues (future fix) |
+| BT Jamming | ⚠️ Disabled | Depends on BT scanner |
+
+---
+
+**Built with ESP-IDF v6.1 for ESP32-C5**  
+**Total Build Time**: ~3 minutes  
+**Flash Time**: ~15 seconds
+
+