A PlatformIO project for the Xiao ESP32 S3 that detects Flock Safety cameras via multiple detection methodologies including WiFi sniffing, BLE scanning, MAC address detection, and device name patterns.

Enhanced Detection Methods

1. WiFi SSID Detection

Promiscuous Mode: Captures probe requests and beacon frames in real-time
Active Scanning: Monitors all WiFi traffic on 2.4GHz channels (1-13)
Detects SSIDs containing: "flock", "Flock", "FLOCK", "FS Ext Battery", "Penguin", "Pigvision"
Channel Hopping: Automatically cycles through channels every 2.5 seconds
Probe Request Monitoring: Captures device probe requests even for hidden networks

2. BLE Device Detection

Passive BLE scanning for nearby devices
MAC address prefix matching from known Flock Safety device ranges
Device name pattern matching in BLE advertisement data
Detects devices broadcasting names like "FS Ext Battery", "Penguin", etc.

3. MAC Address Detection

35+ known MAC address prefixes from real Flock Safety devices
Covers multiple device types: FS Ext Battery, Penguin, Flock WiFi, Pigvision
Detects devices even when SSIDs are randomized or hidden

4. Device Name Detection

Pattern matching for device names in BLE advertisements
Case-insensitive matching for maximum detection coverage

Features

Multi-Method Detection: WiFi + BLE + MAC + Device Names
Promiscuous WiFi Monitoring: Captures probe requests and beacons in real-time
JSON Detection Output: Structured data with timestamps, RSSI, MAC addresses, and device info
Audio Alerts: Buzzer notifications with distinct sound patterns
Boot Sequence: Two beeps (low, medium) on startup
Detection Alert: Three consecutive high-pitch beeps when Flock device detected
Channel Hopping: Automatically cycles through 2.4GHz WiFi channels
Passive Operation: No signals transmitted, only receives and monitors

Hardware Requirements

Xiao ESP32 S3 board
Buzzer connected to GPIO3 (D2) and GND
USB-C cable for programming and power

Wiring

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

Installation

Install PlatformIO (if not already installed):
```
pip install platformio
```
Clone or download this project

Build and upload:

cd flock-squawk
pio run --target upload

Monitor serial output:
```
pio device monitor
```

Usage

Power on the device - you'll hear two beeps (low, then medium pitch)
Wait for the device to start scanning (WiFi + BLE simultaneously)
When a Flock Safety device is detected, you'll hear three consecutive high-pitch beeps
Check the serial monitor for JSON detection output including:
- Timestamp: Milliseconds since boot
- Detection Type: "wifi" or "ble"
- Detection Method: "probe_request", "beacon", "mac_prefix", "device_name"
- RSSI: Signal strength in dBm
- MAC Address: Full device MAC address
- SSID: Network name (for WiFi detections)
- Device Name: BLE advertised name (for BLE detections)
- Matched Pattern: Specific pattern that triggered detection

Example JSON Output

WiFi Probe Request Detection:

{
  "timestamp": 45230,
  "type": "wifi",
  "detection_method": "probe_request",
  "ssid": "Flock-Cam-01",
  "rssi": -65,
  "mac": "70:c9:4e:12:34:56",
  "matched_pattern": "Flock"
}

BLE Device Detection:

{
  "timestamp": 47890,
  "type": "ble", 
  "detection_method": "mac_prefix",
  "mac": "58:8e:81:ab:cd:ef",
  "rssi": -72,
  "device_name": "FS Ext Battery",
  "matched_pattern": "58:8e:81"
}

Detection Coverage

WiFi Detection

Channels: 2.4GHz (1-13) with automatic channel hopping
Scan Method: WiFi promiscuous mode - captures all frames in real-time
Frame Types: Probe requests, beacon frames, and other management frames
SSID Patterns: 6 different patterns covering all known Flock Safety naming conventions
Channel Hop Interval: Every 2.5 seconds

BLE Detection

Scan Type: Passive scanning (no interference)
MAC Prefixes: 35+ known Flock Safety device MAC address ranges
Device Names: Pattern matching for 4 different device name types
Advertisement Parsing: Complete and short local name detection

MAC Address Ranges Detected

FS Ext Battery: 58:8e:81, cc:cc:cc, ec:1b:bd, 90:35:ea, 04:0d:84, f0:82:c0, etc.
Flock WiFi: 70:c9:4e, 3c:91:80, d8:f3:bc, 80:30:49, 14:5a:fc, etc.
Penguin: cc:09:24, ed:c7:63, e8:ce:56, ea:0c:ea, d8:8f:14, etc.
Pigvision: Various manufacturer-specific ranges

Technical Details

Framework: Arduino (with NimBLE for BLE)
Board: Xiao ESP32 S3
Buzzer Pin: GPIO3 (D2)
WiFi Channels: 2.4GHz (1-13)
Channel Hop Interval: 2.5 seconds per channel
JSON Output: Structured detection data with full device information
BLE Scanning: Continuous passive scanning
Detection Patterns: 6 SSID + 35 MAC + 4 Device Name patterns

Detection Accuracy

High Detection Rate

Multiple detection vectors ensure devices are caught even if one method fails
MAC address detection works regardless of SSID naming
BLE scanning detects devices that may not broadcast WiFi
Pattern matching covers various naming conventions

False Positive Reduction

Specific MAC address ranges from real device databases
Multiple pattern confirmation before alerting
Case-insensitive matching with exact pattern requirements

Limitations

Requires devices to be within WiFi/BLE range (~100m)
May miss devices using only cellular connectivity
Some devices may use randomized MAC addresses
Detection depends on devices actively broadcasting

Real-World Effectiveness

This enhanced system significantly improves detection rates by:

Covering multiple communication protocols (WiFi + BLE)
Using real device databases for accurate MAC address ranges
Implementing pattern matching for various naming conventions
Providing redundant detection methods for maximum coverage

Credits

Based on the original Flock Safety Trap Shooter Sniffer Alarm concept. Enhanced with real-world device data from multiple Flock Safety deployments.

Real-World Device Data

The detection patterns in this system are based on real device databases located in the datasets/ folder:

FS+Ext+Battery: 4,908 Flock Safety Extended Battery devices
Penguin: Large dataset of Penguin surveillance devices
Flock WiFi: Standard Flock Safety WiFi network data
Pigvision: Physical camera location data
Maximum Dots: Multi-manufacturer surveillance system data

See datasets/README.md for detailed information about the data sources and analysis.

License

Same as original project - see LICENSE file.