halehound/OPTIMIZATION_GUIDE.md

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:

#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

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:

TouchFT6336::calibrate()

---

Radio Modules: Optimized for S3

CC1101 SubGHz (300-928 MHz)

File: include/radio_cc1101.h

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

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)

// 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

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

{
  "platformio.defaultToolchain": "arm-none-eabi-gcc",
  "platformio.defaultLibDepth": 2
}

Web Flash (Recommended)

Use 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):

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:

// ✅ 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:

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:

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