393 lines
11 KiB
Markdown
393 lines
11 KiB
Markdown
# 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.
|