Professional surveillance camera detection for the Oui-Spy device available at colonelpanic.tech

Flock You is an advanced detection system designed to identify Flock Safety surveillance cameras and similar surveillance devices using multiple detection methodologies. Built for the Xiao ESP32 S3 microcontroller, it provides real-time monitoring with audio alerts and comprehensive JSON output.

• WiFi Promiscuous Mode: Captures probe requests and beacon frames
• Bluetooth Low Energy (BLE) Scanning: Monitors BLE advertisements
• MAC Address Filtering: Detects devices by known MAC prefixes
• SSID Pattern Matching: Identifies networks by specific names
• Device Name Pattern Matching: Detects BLE devices by advertised names

• Boot Sequence: 2 beeps (low pitch → high pitch) on startup
• Detection Alert: 3 fast high-pitch beeps when device detected
• Heartbeat Pulse: 2 beeps every 10 seconds while device remains in range
• Range Monitoring: Automatic detection of device leaving range

• JSON Detection Data: Structured output with timestamps, RSSI, MAC addresses
• Real-time Web Dashboard: Live monitoring at http://localhost:5000
• Serial Terminal: Real-time device output in the web interface
• Detection History: Persistent storage and export capabilities (CSV, KML)
• Device Information: Full device details including signal strength and threat assessment
• Detection Method Tracking: Identifies which detection method triggered the alert

• Microcontroller: Xiao ESP32 S3
• Display: 5-inch 1280x720 IPS TFT with multi-touch
• Wireless: Dual WiFi/BLE scanning capabilities
• Audio: Built-in buzzer system
• Connectivity: USB-C for programming and power

• Microcontroller: Xiao ESP32 S3 board
• Buzzer: 3V buzzer connected to GPIO3 (D2)
• Power: USB-C cable for programming and power

Xiao ESP32 S3    Buzzer
GPIO3 (D2)  ---> Positive (+)
GND         ---> Negative (-)

• PlatformIO IDE or PlatformIO Core
• Python 3.8+ (for web interface)
• USB-C cable for programming
• Oui-Spy device from colonelpanic.tech

1. Clone the repository:

   git clone <repository-url>
   cd flock-you

2. Connect your Oui-Spy device via USB-C

3. Flash the firmware:

   pio run --target upload

4. Set up the web interface:

   cd api
   python3 -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   pip install -r requirements.txt

5. Start the web server:

   python flockyou.py

6. Access the dashboard:

   • Open your browser to http://localhost:5000
   • The web interface provides real-time detection monitoring
   • Serial terminal for device output
   • Detection history and export capabilities

7. Monitor device output (optional):

   pio device monitor

• Probe Requests: Captures devices actively searching for networks
• Beacon Frames: Monitors network advertisements
• Channel Hopping: Cycles through all 13 WiFi channels (2.4GHz)
• SSID Patterns: Detects networks with "flock", "Penguin", "Pigvision" patterns
• MAC Prefixes: Identifies devices by manufacturer MAC addresses

• Advertisement Scanning: Monitors BLE device broadcasts
• Device Names: Matches against known surveillance device names
• MAC Address Filtering: Detects devices by BLE MAC prefixes
• Active Scanning: Continuous monitoring with 100ms intervals

Detection patterns are derived from actual field data including:

• Flock Safety camera signatures
• Penguin surveillance device patterns
• Pigvision system identifiers
• Extended battery and external antenna configurations

Datasets from deflock.me are included in the datasets/ folder of this repository, providing comprehensive device signatures and detection patterns for enhanced accuracy.

• Frequency: 2.4GHz only (13 channels)
• Mode: Promiscuous monitoring
• Channel Hopping: Automatic cycling every 2 seconds
• Packet Types: Probe requests (0x04) and beacons (0x08)

• Framework: NimBLE-Arduino
• Scan Mode: Active scanning
• Interval: 100ms scan intervals
• Window: 99ms scan windows

• Boot Sequence: 200Hz → 800Hz (300ms each)
• Detection Alert: 1000Hz × 3 beeps (150ms each)
• Heartbeat: 600Hz × 2 beeps (100ms each, 100ms gap)
• Frequency: Every 10 seconds while device in range

{
  "timestamp": 12345,
  "detection_time": "12.345s",
  "protocol": "wifi",
  "detection_method": "probe_request",
  "alert_level": "HIGH",
  "device_category": "FLOCK_SAFETY",
  "ssid": "Flock_Camera_001",
  "rssi": -65,
  "signal_strength": "MEDIUM",
  "channel": 6,
  "mac_address": "aa:bb:cc:dd:ee:ff",
  "threat_score": 95,
  "matched_patterns": ["ssid_pattern", "mac_prefix"],
  "device_info": {
    "manufacturer": "Flock Safety",
    "model": "Surveillance Camera",
    "capabilities": ["video", "audio", "gps"]
  }
}

1. Power on the Oui-Spy device
2. Listen for boot beeps (low → high pitch)
3. Start the web server: python flockyou.py (from the api directory)
4. Open the dashboard: Navigate to http://localhost:5000
5. Connect devices: Use the web interface to connect your Flock You device and GPS
6. System ready when "hunting for Flock Safety devices" appears in the serial terminal

• Web Dashboard: Real-time detection display at http://localhost:5000
• Serial Terminal: Live device output in the web interface
• Audio Alerts: Immediate notification of detections (device-side)
• Heartbeat: Continuous monitoring while devices in range
• Range Tracking: Automatic detection of device departure
• Export Options: Download detections as CSV or KML files

• WiFi: Automatically hops through channels 1-13
• BLE: Continuous scanning across all BLE channels
• Status Updates: Channel changes logged to serial terminal

• flock* - Flock Safety cameras
• Penguin* - Penguin surveillance devices
• Pigvision* - Pigvision systems
• FS_* - Flock Safety variants

• AA:BB:CC - Flock Safety manufacturer codes
• DD:EE:FF - Penguin device identifiers
• 11:22:33 - Pigvision system codes

• Flock* - Flock Safety BLE devices
• Penguin* - Penguin BLE identifiers
• Pigvision* - Pigvision BLE devices

• WiFi Range: Limited to 2.4GHz spectrum
• Detection Range: Approximately 50-100 meters depending on environment
• False Positives: Possible with similar device signatures
• Battery Life: Continuous scanning reduces battery runtime

• Interference: Other WiFi networks may affect detection
• Obstacles: Walls and structures reduce detection range
• Weather: Outdoor conditions may impact performance

1. Web Server Won't Start: Check Python version (3.8+) and virtual environment setup
2. No Serial Output: Check USB connection and device port selection in web interface
3. No Audio: Verify buzzer connection to GPIO3
4. No Detections: Ensure device is in range and scanning is active
5. False Alerts: Review detection patterns and adjust if needed
6. Connection Issues: Verify device is connected via the web interface controls

• Web Dashboard: Real-time status and connection monitoring at http://localhost:5000
• Serial Terminal: Live device output in the web interface
• Channel Hopping: Logs channel changes for debugging
• Detection Logs: Full JSON output for analysis

• Research and Education: Understanding surveillance technology
• Security Assessment: Evaluating privacy implications
• Technical Analysis: Studying wireless communication patterns

• Local Laws: Ensure compliance with local regulations
• Privacy Rights: Respect individual privacy and property rights
• Authorized Use: Only use in authorized locations and situations

This project is based on extensive research and public datasets from the surveillance detection community:

• DeFlock - Crowdsourced ALPR location and reporting tool

  • GitHub: FoggedLens/deflock
  • Provides comprehensive datasets and methodologies for surveillance device detection
  • Datasets included: Real-world device signatures from deflock.me are included in the datasets/ folder

• GainSec - OSINT and privacy research

  • Specialized in surveillance technology analysis and detection methodologies
  • Research referenced: Some methodologies are based on their published research on surveillance technology

Flock You unifies multiple known detection methodologies into a comprehensive scanner/wardriver specifically designed for Flock Safety cameras and similar surveillance devices. The system combines:

• WiFi Promiscuous Monitoring: Based on DeFlock's network analysis techniques
• BLE Device Detection: Leveraging GainSec's Bluetooth surveillance research
• MAC Address Filtering: Using crowdsourced device databases from deflock.me
• Pattern Recognition: Implementing research-based detection algorithms

Special thanks to the researchers and contributors who have made this work possible through their open-source contributions and public datasets. This project builds upon their foundational work in surveillance detection and privacy protection.

• Technical Support: Available through colonelpanic.tech
• Firmware Updates: Regular updates with improved detection patterns
• Community: Join our community for tips and modifications

Oui-Spy devices are available exclusively at colonelpanic.tech

This project is provided for educational and research purposes. Please ensure compliance with all applicable laws and regulations in your jurisdiction.

Flock You: Professional surveillance detection for the privacy-conscious