311 lines
7.1 KiB
Markdown
311 lines
7.1 KiB
Markdown
# 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.
|