halehound/QUICKSTART.md

# 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**
```bash
pip install platformio
```

### Clone This Repo
```bash
git clone https://github.com/YOUR_FORK/HaleHound-CYD.git
cd HaleHound-CYD
```

---

## 4. First Build

```bash
# 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
```bash
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
```cpp
// In src/main.cpp, main loop:
if (RadioCC1101::begin(RadioCC1101::BAND_433MHZ)) {
    Serial.println("CC1101 OK");
    Serial.println("RSSI: " + RadioCC1101::getRSSI());
}
```

### NRF24 2.4GHz
```cpp
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
```cpp
// Plug GPS into P1 connector (GPIO 1 TX)
// Should output NMEA sentences on Serial at 9600 baud
```

### Serial Monitor
```bash
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`

```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:**
```cpp
#include "wifi_scanner.cpp"

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

---

## 8. Troubleshooting

### "Board not detected"
```bash
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

- **PlatformIO Docs:** https://docs.platformio.org/
- **ESP32-S3 Datasheet:** https://www.espressif.com/en/products/socs/esp32-s3/resources
- **Adafruit GFX:** https://github.com/adafruit/Adafruit-GFX-Library
- **Original HaleHound:** https://github.com/JesseCHale/HaleHound-CYD
- **FREENOVE Board:** https://www.freenove.com/

---

## 12. Contributing

Found a bug or optimization? Submit a pull request:

```bash
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:
```bash
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.