Snapshot: full project state

2026-10-06 23:43:26 -07:00
commit c1f5e0ff42
15 changed files with 2816 additions and 0 deletions
--- a/OPTIMIZATION_GUIDE.md
+++ b/OPTIMIZATION_GUIDE.md
@@ -0,0 +1,392 @@
+# HaleHound-CYD ESP32-S3 FREENOVE Optimization Guide
+
+**Target Board:** FREENOVE ESP32-S3 Display (2.8" IPS Capacitive, 240x320)  
+**Status:** Template / Work-in-Progress  
+**Last Updated:** 2026-07-16
+
+---
+
+## Overview
+
+This is a **template project** that optimizes HaleHound-CYD for the **FREENOVE ESP32-S3 Display** variant. The ESP32-S3 offers significant improvements over the original ESP32 used in early CYD boards:
+
+| Feature | ESP32 | ESP32-S3 | Benefit |
+|---------|-------|----------|---------|
+| **SRAM** | 320 KB | 520 KB | +200 KB for larger radio buffers & frame caching |
+| **Flash** | 4-8 MB | 8-16 MB | Room for more attack modules or assets |
+| **USB OTG** | ❌ | ✅ | Native USB (faster serial, potential for external peripherals) |
+| **GPIO** | 34 | 45 | More pins for radio module expansion |
+| **CPU** | 240 MHz dual | 240 MHz dual | Same clock, but S3 has better pipeline efficiency |
+| **Touch** | Resistive XPT2046 | **Capacitive FT6336** | Better responsiveness, multi-touch capable |
+
+---
+
+## Hardware Layout
+
+### FREENOVE ESP32-S3 Pinout
+
+This configuration maps HaleHound radio modules to FREENOVE S3 breakout pins:
+
+```
+Display (ILI9341)         SPI Radio Bus (VSPI)
+├── CS: GPIO 10          ├── CLK: GPIO 12
+├── DC: GPIO 8           ├── MOSI: GPIO 11
+├── RST: GPIO 9          ├── MISO: GPIO 13
+├── BL: GPIO 46 (PWM)    └── Shared with SD card
+
+Touch (FT6336 Capacitive) Radio Chip Selects
+├── SDA: GPIO 4          ├── CC1101: GPIO 7
+├── SCL: GPIO 5          ├── NRF24: GPIO 14
+└── INT: GPIO 3          └── PN532: GPIO 17
+
+GPS (UART0)              Power/Control
+├── TX: GPIO 1           ├── LED R: GPIO 42
+└── RX: GPIO 3           ├── LED G: GPIO 2
+                         └── Button: GPIO 0 (boot)
+```
+
+**See `include/board_config.h` for complete pinout.**
+
+---
+
+## Memory Optimization
+
+### Heap Allocation Strategy
+
+ESP32-S3 has **520 KB SRAM**. Suggested allocation:
+
+```
+┌─────────────────────────────────────┐
+│ ESP32-S3 SRAM Layout (520 KB total) │
+├─────────────────────────────────────┤
+│ WiFi Buffers       │ 32 KB           │
+│ BLE Buffers        │ 64 KB           │
+│ Radio RX Queue     │ 48 KB           │
+│ Display/UI Frames  │ 80 KB (↑ from 40 KB on ESP32)
+│ Packet Assembly    │ 40 KB           │
+│ Available          │ 256 KB remaining│
+└─────────────────────────────────────┘
+```
+
+**Key improvements:**
+- **Larger packet buffers** → Capture longer SubGHz/WiFi frames without truncation
+- **Bigger UI frame buffer** → Smoother menu transitions, animated status bars
+- **BLE spool** → Cache more Bluetooth advertisement packets for analysis
+
+Set in `board_config.h`:
+```c
+#define HEAP_SIZE_UI     (80 * 1024)   // Up from 40 KB
+#define HEAP_SIZE_RADIO  (48 * 1024)   // Up from 32 KB
+```
+
+---
+
+## Touch Driver: FT6336 Capacitive
+
+### Why It Matters
+
+- **Original CYD:** XPT2046 resistive touchscreen (slow, pressure-dependent, inaccurate)
+- **FREENOVE S3:** FT6336 capacitive (responsive, fast, finger-area aware)
+
+**Impact on HaleHound:**
+- Menu navigation feels snappy
+- No calibration drift (capacitive is stable)
+- Can detect press area (useful for slider controls, spectrum graphs)
+
+### Driver: `include/touch_ft6336.h`
+
+```cpp
+TouchFT6336::begin()           // Initialize I2C
+auto tp = TouchFT6336::readTouch()  // Get XY + pressed state
+TouchFT6336::sleep()           // Low-power mode
+```
+
+The FT6336 auto-calibrates on startup. If touch feels offset, recalibrate:
+```cpp
+TouchFT6336::calibrate()
+```
+
+---
+
+## Radio Modules: Optimized for S3
+
+### CC1101 SubGHz (300-928 MHz)
+
+**File:** `include/radio_cc1101.h`
+
+```cpp
+RadioCC1101::begin(RadioCC1101::BAND_433MHZ, true)  // use_pa = E07 module
+RadioCC1101::setFreq(433.92f)
+RadioCC1101::setMaxPower()
+RadioCC1101::transmit(data, len)
+uint8_t rssi = RadioCC1101::getRSSI()
+```
+
+**S3 Advantage:** More GPIO means cleaner PA module control (TX_EN/RX_EN on dedicated pins, no GPIO conflicts).
+
+### NRF24L01+ 2.4GHz
+
+**File:** `include/radio_nrf24.h`
+
+```cpp
+RadioNRF24::begin()
+RadioNRF24::setChannel(80)      // 2400 + (ch * 1) MHz
+RadioNRF24::setMaxPower()       // +20 dBm with PA+LNA
+RadioNRF24::transmit(data, len)
+RadioNRF24::enablePromiscuous() // Goodspeed sniffer mode
+uint8_t signal = RadioNRF24::scanChannel(ch)
+```
+
+**S3 Advantage:** Faster SPI (10 MHz) due to better clock distribution on S3 vs base ESP32.
+
+### PN532 NFC/RFID
+
+**File:** `include/radio_nrf24.h` (ready for expansion)
+
+```cpp
+// Stub - implement PN532 SPI driver
+// Uses GPIO 17 (CS)
+```
+
+---
+
+## Display & UI
+
+### Adafruit GFX + ILI9341
+
+Uses standard Adafruit libraries. S3 variant benefits:
+
+1. **Larger frame buffer** → 80 KB (vs 40 KB on ESP32)
+   - Smoother scrolling on spectrum analyzers
+   - Better animation performance
+
+2. **Faster SPI** → 80 MHz possible on S3
+   - Current: 40 MHz (conservative, stable)
+   - Could upgrade: Edit `platformio.ini` SPI freq for testing
+
+3. **Capacitive touch** → Better UX
+   - Tap-to-select menus feel responsive
+   - Swipe gestures possible (not implemented yet)
+
+### Main Screen Layout
+
+```
+┌──────────────────────────────────────┐
+│ HALEHOUND-CYD v3.7.2 (ESP32-S3)      │
+├──────────────────────────────────────┤
+│  [WiFi]  [BLE]    [SubGHz]           │
+│  [2.4GHz] [RFID]  [Settings]         │
+├──────────────────────────────────────┤
+│ Free RAM: 256 KB | Signal: -45 dBm   │
+└──────────────────────────────────────┘
+```
+
+---
+
+## Firmware Partitioning
+
+**File:** `partitions_s3.csv`
+
+Optimized for 16 MB flash (typical FREENOVE S3 boards):
+
+```
+NVS (6 KB)       → WiFi credentials, settings
+OTA Data (8 KB)  → Firmware update tracking
+App0 (4 MB)      → Primary firmware
+App1 (4 MB)      → OTA fallback
+SPIFFS (8 MB)    → User files (.sub, captures, loot)
+```
+
+This allows **OTA firmware updates** without external tools.
+
+---
+
+## Build & Flash
+
+### PlatformIO
+
+```bash
+# Build for ESP32-S3 FREENOVE
+pio run -e esp32-s3-freenove
+
+# Flash
+pio run -e esp32-s3-freenove --target upload
+
+# Serial monitor
+pio device monitor -b 115200
+
+# Debug build
+pio run -e debug --target upload
+```
+
+### VS Code Setup
+
+Add to `.vscode/settings.json`:
+```json
+{
+  "platformio.defaultToolchain": "arm-none-eabi-gcc",
+  "platformio.defaultLibDepth": 2
+}
+```
+
+### Web Flash (Recommended)
+
+Use [flash.halehound.com](https://flash.halehound.com) once this is merged with main HaleHound:
+1. Plug in FREENOVE ESP32-S3
+2. Select board
+3. Flash in browser (no drivers needed on modern systems)
+
+---
+
+## Performance Optimization Tips
+
+### 1. CPU Frequency Scaling
+
+Default: 240 MHz (both cores)
+
+For low-power mode (WiFi scanning only):
+```cpp
+setCpuFreqMhz(80); // Reduce to 80 MHz
+// Saves ~60-70 mA during passive monitoring
+setCpuFreqMhz(240); // Back to full speed
+```
+
+### 2. Radio Module Duty Cycle
+
+Don't leave TX on continuously:
+
+```cpp
+// ✅ GOOD: Burst TX + sleep
+RadioCC1101::transmit(payload, len);
+delay(100); // Listen for response
+RadioCC1101::sleep();
+
+// ❌ BAD: TX in loop (overheats, drains battery)
+while (1) RadioCC1101::transmit(payload, len);
+```
+
+### 3. Touch IRQ for Wake
+
+Capacitive touch can wake from sleep:
+```cpp
+esp_sleep_enable_ext0_wakeup(GPIO_NUM_3, ESP_EXT0_WAKEUP_LOW);
+esp_light_sleep_start();
+// Wakes on TOUCH_INT press
+```
+
+### 4. PSRAM (Optional)
+
+FREENOVE S3 does NOT include PSRAM. If you add it later:
+```
+Board: esp32-s3-devkitc-1-n16r8
+build_flags = -DBOARD_HAS_PSRAM=1
+```
+
+This gives unlimited heap for large captures.
+
+---
+
+## Troubleshooting
+
+### Touch Not Working
+
+1. Check I2C address: `0x38` (hard-coded in driver)
+2. Verify wiring: GPIO 4 (SDA), GPIO 5 (SCL)
+3. Try `TouchFT6336::calibrate()` in setup
+4. Serial debug: Enable `LOG_LOCAL_LEVEL=ESP_LOG_DEBUG` in platformio.ini
+
+### Radio Module Not Detected
+
+1. Check GPIO assignments in `board_config.h`
+2. Verify SPI bus (GPIO 11/12/13 shared)
+3. Look for brownout resets → need external 3.3V buck for PA modules
+4. Test with `Tools > Radio Test` module once UI is complete
+
+### Heap Fragmentation
+
+If you see "heap memory exhausted" after ~1 hour:
+
+1. Enable psram logging: `heap_trace_start(HEAP_TRACE_ALL)`
+2. Find leaks: Check WiFi/BLE event callbacks
+3. Increase heap size: Edit `HEAP_SIZE_*` in board_config.h
+
+### Slow SPI Performance
+
+If radio throughput is poor:
+
+```cpp
+// Current (conservative):
+SPI.setFrequency(10000000); // 10 MHz
+
+// Try higher (test stability):
+SPI.setFrequency(20000000); // 20 MHz
+SPI.setFrequency(40000000); // 40 MHz (risky, may corrupt)
+```
+
+---
+
+## Integration with HaleHound
+
+This template provides:
+
+1. ✅ GPIO pinout for FREENOVE S3
+2. ✅ Capacitive touch driver (FT6336)
+3. ✅ Radio module stubs (CC1101, NRF24)
+4. ✅ Memory-optimized partition table
+5. ✅ Basic UI framework
+6. ✅ PlatformIO build config
+
+**To merge with HaleHound source:**
+
+1. Copy `include/` → your HaleHound project
+2. Copy `platformio.ini` (add as new `[env:esp32-s3-freenove]` section)
+3. Update `src/main.cpp` with actual attack module logic
+4. Test each radio module individually (use `Radio Test` mode)
+5. Submit PR with optimizations
+
+---
+
+## Next Steps
+
+### Short Term (MVP)
+- [ ] Implement full WiFi scanner (APSTA mode)
+- [ ] Add BLE advertiser
+- [ ] SubGHz replay recorder
+- [ ] NRF24 sniffer (Goodspeed)
+- [ ] SPIFFS file browser
+
+### Medium Term
+- [ ] GARMR captive portal
+- [ ] Drone RID detection
+- [ ] GPS integration
+- [ ] Spectrum analyzer with FFT visualization
+- [ ] OTA firmware updates
+
+### Long Term
+- [ ] Multi-radio simultaneous operation (dual-core)
+- [ ] Packet capture to SD card (high-speed DMA)
+- [ ] Machine learning for threat classification
+- [ ] Cloud loot exfiltration (if permitted)
+- [ ] Touchscreen gesture support
+
+---
+
+## References
+
+- **Adafruit GFX:** https://github.com/adafruit/Adafruit-GFX-Library
+- **Adafruit ILI9341:** https://github.com/adafruit/Adafruit_ILI9341
+- **ESP32-S3 Datasheet:** https://www.espressif.com/sites/default/files/documentation/esp32-s3_datasheet_en.pdf
+- **FT6336 Datasheet:** Search for "FT6336 capacitive touch controller"
+- **CC1101 Datasheet:** TI CC1101 docs (SubGHz ISM band radio)
+- **NRF24L01+PA+LNA:** Nordic nRF24L01+ 2.4GHz transceiver
+
+---
+
+## License
+
+This template is part of HaleHound-CYD optimization work.  
+**Use responsibly. Offensive security tools require proper authorization.**
+
+---
+
+**Questions or issues?** Open a GitHub issue or reach out to @JesseCHale.