# 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.