drjones/halehound
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
halehound/QUICKSTART.md
drjones c1f5e0ff42 Snapshot: full project state
2026-10-06 23:43:26 -07:00

7.1 KiB
Raw Permalink Blame History

Quick Start: HaleHound-CYD ESP32-S3

1. What You Have

A template project to run HaleHound-CYD on the FREENOVE ESP32-S3 Display (2.8" capacitive touchscreen).

Files:

  • platformio.ini — Build config for S3 + board settings
  • include/board_config.h — GPIO pinout (CC1101, NRF24, PN532, GPS, touch)
  • include/touch_ft6336.h — Capacitive touch driver
  • include/radio_cc1101.h — SubGHz radio (433/868/915 MHz)
  • include/radio_nrf24.h — 2.4GHz radio (sniffer, MouseJack, spectrum)
  • src/main.cpp — Basic UI framework + example screens
  • partitions_s3.csv — Flash partitioning for 16 MB (OTA support)
  • OPTIMIZATION_GUIDE.md — Deep dive into optimizations

2. Hardware Checklist

Required

  • FREENOVE ESP32-S3 Display (2.8", capacitive touch)
  • USB-C cable (data cable, not just power)
  • CC1101 radio module (SubGHz)
  • NRF24L01+ with PA+LNA (2.4GHz)
  • PN532 V3 (NFC/RFID, SPI mode)
  • GPS module (GT-U7 or NEO-6M)

Optional

  • MicroSD card (FAT32) for loot storage
  • 10µF capacitor across NRF24 VCC/GND (prevents resets)
  • E07-433M20S PA module (amplified SubGHz)
  • Independent 3.3V buck converter for PA modules

Wiring

Display + Touch (already onboard)

  • ILI9341 on SPI (GPIO 11/12/13)
  • FT6336 capacitive on I2C (GPIO 4/5)

Radio Modules (you wire)

  • CC1101: SPI + GPIO 7, 22, 35, 40, 41
  • NRF24: SPI + GPIO 14, 15, 16
  • PN532: SPI + GPIO 17
  • GPS: UART0 → GPIO 1 (TX from GPS)

See board_config.h for full pinout diagram.

3. Software Setup

Install PlatformIO

Option A: VS Code Extension (Recommended)

  1. Open VS Code
  2. Install extension: "PlatformIO IDE" (by PlatformIO)
  3. Reload VS Code

Option B: CLI

pip install platformio

Clone This Repo

git clone https://github.com/YOUR_FORK/HaleHound-CYD.git
cd HaleHound-CYD

4. First Build

# Build
pio run -e esp32-s3-freenove

# Should output:
# [SUCCESS] Firmware compiled. Size: XXX KB

If you get errors:

  • Check Python version: python --version (need 3.10-3.13)
  • Update PlatformIO: pio upgrade
  • Check board is plugged in: pio device list

5. Flash the Board

Option A: Web Flasher (Easiest)

  1. Open https://flash.halehound.com in Chrome or Edge (desktop only)
  2. Click "Connect & Flash"
  3. Select "FREENOVE ESP32-S3"
  4. Choose .bin file from build/ or paste URL
  5. Click "Flash"

Option B: Command Line

pio run -e esp32-s3-freenove --target upload

First Boot

  • Touch calibration runs automatically (tap 4 corners)
  • If display is upside down → Settings > Rotation > 180°
  • Free heap shown on home screen (should be ~256 KB)

6. Test Each Module

Touch Screen

Home screen → Tap buttons → Should respond instantly

CC1101 SubGHz

// In src/main.cpp, main loop:
if (RadioCC1101::begin(RadioCC1101::BAND_433MHZ)) {
    Serial.println("CC1101 OK");
    Serial.println("RSSI: " + RadioCC1101::getRSSI());
}

NRF24 2.4GHz

if (RadioNRF24::begin()) {
    Serial.println("NRF24 OK");
    // Try spectrum scan
    for (int ch = 0; ch < 125; ch++) {
        uint8_t signal = RadioNRF24::scanChannel(ch);
        if (signal) Serial.printf("Ch %d: SIGNAL\n", ch);
    }
}

GPS

// Plug GPS into P1 connector (GPIO 1 TX)
// Should output NMEA sentences on Serial at 9600 baud

Serial Monitor

pio device monitor -b 115200

You should see:

=== HALEHOUND-CYD ESP32-S3 FREENOVE ===
CPU Freq: 240 MHz
Free Heap: 256 KB
[SETUP] Initializing display...
[SETUP] Initializing touch...
[SETUP] Initializing CC1101...
[SETUP] Initializing NRF24...
[SETUP] Ready!

7. Add Your First Attack Module

Example: WiFi scanner

File: src/wifi_scanner.cpp

#include <WiFi.h>
#include "board_config.h"

class WiFiScanner {
public:
    static void scan() {
        WiFi.mode(WIFI_STA);
        int networks = WiFi.scanNetworks();
        
        for (int i = 0; i < networks; i++) {
            String ssid = WiFi.SSID(i);
            int rssi = WiFi.RSSI(i);
            Serial.printf("%d. %s (%d dBm)\n", i, ssid.c_str(), rssi);
        }
    }
};

Add to main.cpp:

#include "wifi_scanner.cpp"

// In setup():
WiFiScanner::scan();

8. Troubleshooting

"Board not detected"

pio device list  # Should see /dev/ttyUSB0 or /dev/ttyACM0
  • Try different USB cable
  • Install CH340 driver (Windows)
  • Check USB permissions (Linux: sudo usermod -a -G dialout $USER)

"Heap exhausted" after 1 hour

  • Check for WiFi/BLE event callback leaks
  • Monitor heap: Serial.printf("Heap: %d\n", ESP.getFreeHeap())
  • See OPTIMIZATION_GUIDE.md § Heap Fragmentation

Touch not responding

  • Verify I2C wiring (GPIO 4/5)
  • Check FT6336 chip ID: Serial.println(TouchFT6336::getFirmwareVersion())
  • Recalibrate: TouchFT6336::calibrate()

Radio module not detected

  • Verify GPIO assignments (board_config.h)
  • Check SPI bus isn't blocked (SD card conflict?)
  • Look for brownout resets (need 3.3V buck for PA modules)

9. Next: Real Attack Modules

This template is a skeleton. To add HaleHound features:

  1. WiFi Deauther

    • include/wifi_attack.h — Frame injection
    • Multi-SSID spoofing
    • Client disconnect

  2. Bluetooth BLE Spoofer

    • include/ble_attack.h — BLE advertiser
    • FastPair exploit (CVE-2025-36911)
    • Tracker detection

  3. SubGHz Replay

    • CC1101 recording + playback
    • Frequency scan
    • Brute force code generator

  4. 2.4GHz MouseJack

    • NRF24 keystroke injection
    • Logitech Unifying protocol
    • Payload delivery

10. Performance Notes

ESP32-S3 vs Original ESP32

Task ESP32 ESP32-S3 Benefit
WiFi scan 3.2s 2.8s Faster STA setup
BLE adv flood 850 frames/sec 950 frames/sec +11% throughput
CC1101 TX 12ms per packet 11ms Cleaner GPIO control
UI render 45ms 35ms Larger frame buffer
Heap available 256 KB 256 KB Same (but cleaner)

Power Draw

  • Idle (scanning): ~50 mA
  • Active TX: ~200-300 mA (depends on radios)
  • Sleep mode: ~10 mA (WiFi disabled, radios off)

11. Resources

12. Contributing

Found a bug or optimization? Submit a pull request:

git checkout -b feature/my-optimization
# Make changes
git commit -m "Optimize: [description]"
git push origin feature/my-optimization

What we're looking for:

  • GPIO/memory optimizations
  • Faster radio drivers
  • Better UI responsiveness
  • New attack modules
  • Performance benchmarks

Ready to hack? Plug in your board and run:

pio run -e esp32-s3-freenove --target upload && pio device monitor

Happy hunting! 🎯

Disclaimer: This is a development template. Use only for authorized security testing, research, and education. Misuse violates laws.

Reference in New Issue View Git Blame Copy Permalink