Flock-You ESP32 - Complete Build Package

WiFi promiscuous-mode detector for Flock Safety surveillance cameras

Ported to standard ESP32 hardware for maximum accessibility and cost savings.

🚀 Quick Links

Setup Instructions - Get started in 3 steps
Solderless Build Guide - No soldering required! ($9-11 total)
3D Printable Case - Professional enclosure design
Business Analysis - Market opportunity & financials
Porting Guide - Technical documentation

✨ What's Included

This package contains everything you need to build and deploy your own Flock-You detector:

📁 Firmware (`/firmware`)

main.cpp - Modified for ESP32 (GPIO 25, 2, 17)
platformio.ini - ESP32 DevKit configuration
partitions_4mb.csv - Optimized for 4MB flash
api/ - Flask dashboard for GPS wardriving
datasets/ - OUI lists & research data

🔧 Hardware (`/hardware`)

openscad/ - Parametric case source files
stl/ - Ready-to-print STL files (coming soon)
assembly_photos/ - Step-by-step build photos (coming soon)

📚 Documentation

Complete user manuals
Troubleshooting guides
Business planning resources
Technical specifications

💰 Cost Breakdown

Build Type	Components	Total Cost	Detection Accuracy
Minimal	ESP32 + USB cable	$5	✅ 100%
Breadboard	+ Buzzer + breadboard	$9-11	✅ 100%
With Case	+ 3D printed enclosure	$10-12	✅ 100%
OUI-SPY	Pre-built board	$85	✅ 100%

Same detection performance, 85% cost savings!

🎯 Three Ways to Build

Option 1: LED-Only (Cheapest)

Cost: $5 | Time: 5 minutes | Difficulty: ⭐☆☆☆☆

ESP32 DevKit + USB cable
Onboard LED provides visual feedback
Perfect for testing or silent operation
Instructions

Option 2: Breadboard Build (Recommended)

Cost: $9-11 | Time: 10 minutes | Difficulty: ⭐⭐☆☆☆

Add passive buzzer module + breadboard
Audio chirps on detection
No soldering required
Full Guide

Option 3: Enclosed Build (Professional)

Cost: $10-12 | Time: 15 minutes + 3hr print | Difficulty: ⭐⭐⭐☆☆

3D printed case with snap-fit lid
LED light pipe
USB strain relief Case Design

🛠️ Quick Start

1. Get Hardware

Minimum:

ESP32 DevKit ($5-6)
USB Micro cable ($1)

Recommended:

ESP32 Breadboard Kit ($15-20)
Includes everything: ESP32 + breadboard + jumpers + buzzer

2. Flash Firmware

# Install PlatformIO
pip install platformio

# Clone / enter the repo
cd flock-you-esp32

# WiFi-only (recommended first flash — works on any ESP32 DevKit)
pio run -e esp32dev -t upload && pio device monitor

# WiFi + BLE coexistence (continuous BLE scan + WiFi simultaneously)
pio run -e esp32dev-ble -t upload && pio device monitor

# M5Atom variants — use the unified flasher script
./flash.sh          # interactively identifies your device
./flash.sh --once   # flash one device and exit

All supported environments:

Environment	Board	BLE
`esp32dev`	ESP32 DevKit	—
`esp32dev-ble`	ESP32 DevKit	✅ COEX
`m5atom-lite`	M5Atom Lite	—
`m5atom-lite-ble`	M5Atom Lite	✅ COEX
`m5atom-echo`	M5Atom Echo	—
`m5atom-echo-ble`	M5Atom Echo	✅ COEX
`m5atom-voice`	M5Atom Voice	—
`m5atom-voice-ble`	M5Atom Voice	✅ COEX
`m5atom-voices3r`	Atom VoiceS3R (S3)	—
`m5atom-voices3r-ble`	Atom VoiceS3R (S3)	✅ COEX
`lilygo-t-dongle-c5`	LILYGO T-Dongle C5	—
`lilygo-t-dongle-c5-ble`	LILYGO T-Dongle C5	✅ NimBLE 2.x

3. Test Detection

Device boots with Super Mario 1-2 startup tune
LED flashes on WiFi traffic
Buzzer chirps on Flock camera detection
Drive near known camera locations to verify

That's it! You're detecting.

📊 Detection Methodology

This firmware uses five research-proven techniques with a confidence score (0–100):

1. WiFi Promiscuous Sniffing (@NitekryDPaul)

Monitors 2.4 GHz management & data frames
Three OUI confidence tiers (PR#39):
- HIGH (32 OUIs) — exclusively Flock Safety registered → score 40, always alerts
- MFR (6 OUIs) — Liteon/USI contract manufacturer → score 20, silent log only
- SoundThinking (1 OUI) — acoustic sensor co-deployed with Flock → score 35, alerts
addr1 receiver-side detection (catches sleeping cameras)
addr3 BSSID fallback for randomized addr2 frames (now ON by default)

2. Wildcard Probe Signature (DeFlockJoplin)

Flock cameras send probe requests with empty SSID
Combined score OUI+probe = 62 → HIGH CONFIDENCE on first match
Field-tested: 11/12 cameras detected, only 2 false positives

3. SSID Pattern Matching — including LAA-MAC cameras (issue #43)

Patterns: "Flock Camera net.", "Flock-XXXXXX", "FLOCK-XXXXXX", "penguin", "pigvision"
"Flock Camera net." cameras use locally-administered MACs (OUI matching won't work)
ALERT_LAA_SSID type detects these — SSID is the sole WiFi handle
Sequential-MAC heuristic: :DE/:DF last-byte pair on adjacent channels → +10 pts

4. BLE Cross-Correlation (`ENABLE_BLE_SCAN=1`)

Passive NimBLE scan for Flock BLE advertisements
Checks: mfr-ID 0x09C8 (XUNTONG/Flock), Raven 128-bit service UUIDs (GainSec), device names
BLE_COEX_MODE=1 (default for all -ble environments): ESP-IDF SW coexistence scheduler runs WiFi promiscuous + BLE simultaneously — no promiscuous pause needed
BLE hit within 60 s of WiFi hit → +20 confidence bonus

5. Multi-Address Matching

addr2 (transmitter) — standard detection
addr1 (receiver) — catches cameras receiving probe responses
addr3 (BSSID) — fallback for randomized MACs

Confidence tiers: < 30 = LOW (log only) · 30–59 = PROBABLE · ≥ 60 = HIGH (alert)

See DETECTION_IMPROVEMENTS.md for full scoring tables and examples.

🧪 Native Unit Tests

The detection pattern library (fy_detect.h) is fully tested via a host-side Unity test suite — no ESP32 hardware needed:

cd flock-you-esp32
pio test -e native                         # run all 38 tests
pio test -e native -f test_ble_matching    # MAC / BLE name / mfr-ID tests (22)
pio test -e native -f test_uuid_matching   # Raven UUID / firmware version (16)

All 38 tests pass against the current fy_detect.h. The test suite covers:

All 32 high-confidence Flock OUI prefixes (case-insensitive)
All 6 contract-manufacturer OUIs (Liteon/USI)
SoundThinking OUI isolation (not in high or mfr lists)
BLE device name substring matching (case-insensitive)
BLE mfr-ID 0x09C8 match + rejection of the old incorrect 0x05A7
All 8 Raven 128-bit GATT service UUIDs (case-insensitive)
Raven firmware version estimation from UUID categories

🎵 Audio Feedback

Startup Sound

Super Mario Bros. World 1-2 (underground theme)

6 notes: C5 → C4 → A4 → A3 → G#4 → G#3
Confirms buzzer is working

New Detection

Two fast ascending beeps (2000 Hz → 2800 Hz)

First time seeing a camera MAC
Or camera reappears after 30+ seconds
This is the only runtime audio alert — the firmware does not emit any periodic/idle "still tracking" beep. Audio fires exclusively on a genuine new-detection event (confidence >= CHIRP_MIN_CONFIDENCE).

Visual

Onboard LED flashes on every detection

Works even without buzzer
Visible through case light pipe

📱 Flask Dashboard (GPS Wardriving)

Features

Real-time detection visualization
GPS coordinate tagging (USB puck or browser)
Export formats: JSON, CSV, KML (Google Earth)
Multi-device support
Historical tracking

Quick Setup

cd firmware/api
pip install -r requirements.txt
python flockyou.py

Open http://localhost:5000 and select your serial port.

📺 LILYGO T-Dongle C5 — Display & RGB LED

The lilygo-t-dongle-c5 and lilygo-t-dongle-c5-ble environments target the LILYGO T-Dongle C5 — a USB-C dongle packing an ESP32-C5 (dual-band WiFi 6 + BT 5), an ST7735S 80×160 colour TFT, and a WS2812B RGB LED.

What shows on the TFT

State	Display	RGB LED
Startup	Splash screen "T-Dongle C5 ready" → "Scanning…"	Blue blink × 3, then green
Idle scanning	`Scanning…` · Channel & detection count	Dim green
Detection (conf < 30)	Detection type (large) · MAC tail · RSSI · Channel · Confidence%	Dim green
Detection (conf 30–59)	Same, dark-orange background	Amber
Detection (conf ≥ 60)	Same, dark-red background	Red

Pin reference

Signal	GPIO
TFT SCLK	5
TFT MOSI	6
TFT CS	4
TFT DC	2
TFT RST	3
TFT Backlight	1
RGB LED (WS2812B)	11
BOOT button	9

Flash commands

# WiFi-only (no BLE)
pio run -e lilygo-t-dongle-c5 -t upload

# WiFi + BLE (NimBLE 2.x required for ESP32-C5 BLE support)
pio run -e lilygo-t-dongle-c5-ble -t upload

Note: The T-Dongle C5 environments are marked experimental (continue-on-error in CI) because ESP32-C5 toolchain support is still maturing in espressif32@6.7.0.

🔬 Technical Specs

Detection

Channels: 1, 6, 11 (customizable)
Dwell time: 350ms per channel
RSSI threshold: -95 dBm (configurable)
Range: 50-100m typical, 300m with external antenna
Latency: <10ms from RF frame to alert

Hardware

MCU: ESP32-WROOM-32 (dual-core 240 MHz)
RAM: 520KB (uses ~85KB)
Flash: 4MB (uses ~1.2MB)
Power: ~180mA @ 3.3V (WiFi active)
Battery: 6-8 hours on 3,000mAh 18650

Storage

SPIFFS: 1MB partition
Capacity: 200 unique detections with full metadata
Persistence: CRC32-validated, atomic writes
Recovery: Survives power loss mid-save

📦 What Makes This Special?

vs. Original Flock-You (XIAO ESP32-S3)

✅ 85% cheaper ($6 vs $85 for OUI-SPY)
✅ Same detection (identical WiFi chipset)
✅ More available (ESP32 everywhere, XIAO only Seeed)
✅ Easier to prototype (breadboard-friendly)
✅ Larger community (ESP32 has huge support)

vs. Other Solutions

✅ Passive detection (no transmission, legal)
✅ Proven accuracy (field-tested research)
✅ Open source (modify freely)
✅ Portable (pocket-sized with case)
✅ Expandable (add GPS, batteries, external antenna)

🚗 Use Cases

Privacy Awareness

Know when you're being surveilled
Document camera locations
Share data with DeFlock community
Raise awareness in your area

Security Research

Test detection algorithms
Map surveillance infrastructure
Contribute to open research
Develop counter-measures

Wardriving

GPS-tagged detection mapping
Export to Google Earth (KML)
Build community databases
Identify high-surveillance zones

Vehicle Integration

Dashboard mount (case design included)
USB power from car
Audio alerts while driving
Optional battery for portability

📋 Complete BOM

Electronics

Part	Qty	Unit Price	Total
ESP32 DevKit	1	$5-6	$5-6
KY-006 Passive Buzzer	1	$1-2	$1-2
400-pt Breadboard	1	$2	$2
Male-Male Jumpers (3)	1	<$1	<$1
USB Micro Cable	1	$1	$1
Subtotal			$9-11

3D Printed Case (Optional)

Part	Material	Cost
Case Base	15g PLA	$0.30-0.50
Case Lid	8g PLA	$0.15-0.25
LED Light Pipe	2g Clear	$0.05
Mounting Bracket	12g PLA	$0.25
Subtotal		$0.75-1.00

Grand Total: $10-12

🐛 Troubleshooting

No startup sound?

Check passive (not active) buzzer
Verify GPIO 25 connection
Try swapping buzzer polarity
Disable in code: #define USE_BUZZER 0

No detections?

No cameras nearby (drive to known locations)
Check serial output (should show channel hopping)
Lower RSSI threshold: #define RSSI_MIN -100
Verify WiFi promiscuous mode enabled

Compilation errors?

Update PlatformIO: pio upgrade
Check board definition: esp32dev
Verify partition file exists
Clean build: pio run -t clean

Case doesn't fit?

Scale STL by 101% for looser fit
Sand snap-fit tabs if too tight
Check component dimensions against specs
Use OpenSCAD to customize

Full Troubleshooting Guide

🤝 Contributing

Ways to Contribute

📸 Share your build photos
🐛 Report bugs & issues
💡 Suggest features
📝 Improve documentation
🎨 Design case variants
🧪 Field-test and report accuracy
🗺️ Submit camera locations to DeFlock

Remix Culture

This project is licensed CC-BY-SA 4.0:

✅ Use commercially
✅ Modify and remix
✅ Share freely
📝 Credit original authors
🔄 Share-alike license

🏆 Credits

Original Firmware

colonelpanichacks - Original Flock-You creator
ØяĐöØцяöЪöяцฐ (@NitekryDPaul) - WiFi research, 30 OUIs, addr1 technique
Michael / DeFlockJoplin - Wildcard-probe signature, 31st OUI
Will Greenberg - BLE manufacturer ID detection
DeFlock / FoggedLens - Crowdsourced ALPR data
GainSec - Raven BLE service UUIDs

This ESP32 Port

Modified for standard ESP32 (4MB flash, UART)
Solderless assembly guide
3D printable case design
Business analysis & documentation
Community testing & feedback

⚖️ Legal & Disclaimer

What This Device Does

Passively receives publicly-broadcast WiFi frames
Does not transmit any signals
Does not authenticate to networks
Does not decrypt any data
Educational/research purposes

Legality

Passive WiFi reception is legal in most jurisdictions
Equivalent to listening to public radio broadcasts
No different from WiFi analyzers or network sniffers
Always comply with local laws

Use Responsibly

Respect privacy and property rights
Use for legitimate security research
Contribute findings to public good (DeFlock)
Don't use to enable illegal activity

The authors assume no liability for misuse.

🔗 Resources

Community

Original Repo: colonelpanichacks/flock-you
De-Flock: deflock.me - Crowdsourced camera maps
Research: firmware/datasets/ - Full methodology

Hardware

ESP32: espressif.com
PlatformIO: platformio.org
OpenSCAD: openscad.org

Learn More

WiFi Sniffing: ESP32 Promiscuous Mode
3D Printing: All3DP Guides
Privacy Tech: EFF Surveillance Self-Defense

📈 Project Stats

Hardware Cost: $5-12 (vs $85 OUI-SPY)
Build Time: 5-15 minutes
Detection Accuracy: Same as premium hardware
Supported Boards: Any ESP32 with 4MB+ flash
Community: Growing!

🎉 Get Started!

You're 3 steps away from detecting surveillance:

Buy hardware → $5-11
Flash firmware → 10 minutes
Build case → Optional

Questions? Check the docs or open an issue!

Ready? Start Building →

Built with love for privacy, security, and open knowledge.
Detect. Document. DeFlock.

Name		Name	Last commit message	Last commit date
.clinerules		.clinerules
.github/workflows		.github/workflows
api		api
boards		boards
datasets		datasets
docs		docs
hardware		hardware
test		test
.gitignore		.gitignore
CASE_DESIGN.md		CASE_DESIGN.md
DETECTION_IMPROVEMENTS.md		DETECTION_IMPROVEMENTS.md
LICENSE		LICENSE
NOTICE		NOTICE
README.md		README.md
SOLDERLESS_BUILD_GUIDE.md		SOLDERLESS_BUILD_GUIDE.md
beacon_frames.h		beacon_frames.h
beacon_test.cpp		beacon_test.cpp
ble_selftest.h		ble_selftest.h
c5_display.h		c5_display.h
flash.sh		flash.sh
flash_atom.sh		flash_atom.sh
flash_voices3r.sh		flash_voices3r.sh
flock.png		flock.png
fy_confidence.h		fy_confidence.h
fy_detect.h		fy_detect.h
led_gpio.h		led_gpio.h
led_neopixel.h		led_neopixel.h
m5basic_display.h		m5basic_display.h
m5stickc_display.h		m5stickc_display.h
main.cpp		main.cpp
monitor_all.sh		monitor_all.sh
oui.txt		oui.txt
partitions.csv		partitions.csv
partitions_4mb.csv		partitions_4mb.csv
platformio.ini		platformio.ini
sdkconfig.defaults		sdkconfig.defaults
ui_task.h		ui_task.h

Latest commit

History

Folders and files

Repository files navigation

Flock-You ESP32 - Complete Build Package

🚀 Quick Links

✨ What's Included

📁 Firmware (/firmware)

🔧 Hardware (/hardware)

📚 Documentation

💰 Cost Breakdown

🎯 Three Ways to Build

Option 1: LED-Only (Cheapest)

Option 2: Breadboard Build (Recommended)

Option 3: Enclosed Build (Professional)

🛠️ Quick Start

1. Get Hardware

2. Flash Firmware

3. Test Detection

📊 Detection Methodology

1. WiFi Promiscuous Sniffing (@NitekryDPaul)

2. Wildcard Probe Signature (DeFlockJoplin)

3. SSID Pattern Matching — including LAA-MAC cameras (issue #43)

4. BLE Cross-Correlation (ENABLE_BLE_SCAN=1)

5. Multi-Address Matching

🧪 Native Unit Tests

🎵 Audio Feedback

Startup Sound

New Detection

Visual

📱 Flask Dashboard (GPS Wardriving)

Features

Quick Setup

📺 LILYGO T-Dongle C5 — Display & RGB LED

What shows on the TFT

Pin reference

Flash commands

🔬 Technical Specs

Detection

Hardware

Storage

📦 What Makes This Special?

vs. Original Flock-You (XIAO ESP32-S3)

vs. Other Solutions

🚗 Use Cases

Privacy Awareness

Security Research

Wardriving

Vehicle Integration

📋 Complete BOM

Electronics

3D Printed Case (Optional)

🐛 Troubleshooting

No startup sound?

No detections?

Compilation errors?

Case doesn't fit?

🤝 Contributing

Ways to Contribute

Remix Culture

🏆 Credits

Original Firmware

This ESP32 Port

⚖️ Legal & Disclaimer

What This Device Does

Legality

Use Responsibly

🔗 Resources

Community

Hardware

Learn More

📈 Project Stats

🎉 Get Started!

About

Resources

Stars

Watchers

Forks

Releases

Packages

📁 Firmware (`/firmware`)

🔧 Hardware (`/hardware`)

4. BLE Cross-Correlation (`ENABLE_BLE_SCAN=1`)