Pigtail

KO | EN

gitlite — search

#javascript #python #hacktoberfest #react #go #golang #deep-learning #docker #awesome #cli #kubernetes #awesome-list #mcp #open-source

(★ 49)

Anti-stalker and surveillance detection software

Pigtail 최신버젼 다운로드

최종 버전 다운로드 (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

![](https://raw.githubusercontent.com/benbaker76/Pigtail/main/images/PigtailLogo.png)

Pigtail is a tiny [Chasing Your Tail](https://github.com/ArgeliusLabs/Chasing-Your-Tail-NG) (CYT) proximity monitor for ESP32 that visualizes nearby wireless activity using icons, color, and retro-style avatars.

It passively observes **Wi-Fi** and **BLE** presence, tracks *how long* devices linger, and ranks them with a simple "suspicion / interest" score. Because MAC addresses are hard to mentally compare (hex bytes separated by `:` or `-`), Pigtail uses **distinct icons**, **consistent colors**, and **unique retro avatars** to help you recognize patterns over time at a glance.

---

## Why "Pigtail"?

This started as a [Chasing Your Tail](https://github.com/ArgeliusLabs/Chasing-Your-Tail-NG) (CYT) app-something that runs on an ESP32 and gives you a lightweight sense of what's around you. The name **Pigtail** is a nod to that idea, plus the small, portable nature of the device.

To add a personal spin, Pigtail integrates **RetroAvatars** (originally by Richard Phipps) with enhancements such as additional color support. RetroAvatars has always felt like it deserved a "real" project where the visuals matter-this was the perfect fit.

---

## What it does

Pigtail watches for:

- **Wi-Fi client activity** (e.g., probe requests)
- **Wi-Fi access points** (AP beacons / presence)
- **BLE advertisements** (nearby BLE devices)

It then:
- Tracks devices over time
- Estimates proximity trends using signal strength (**RSSI**)
- Detects **BLE trackers** (AirTag, SmartTag, Tile, etc.), **smart glasses** (Meta Ray-Ban, Snap Spectacles, EssilorLuxottica), and **Flock Safety surveillance infrastructure** (cameras, Raven gear)
- Assigns a score (0-100) based on how long and how consistently a device appears, plus some environment/crowd heuristics
- Presents everything in a compact UI designed for a **240x135** display

---

## Important note on privacy

Pigtail is designed to be **observational** and **non-identifying**:

- It does **not** attempt to identify individuals.
- Modern phones often use **MAC randomization / anti-tracking** techniques. That means the same physical device may appear under different addresses over time.
- What you typically get is "a device signature that seems to hang around" rather than a stable identity.

Use this responsibly and comply with local laws and venue policies. This project is intended for learning, visualization, and personal experimentation.

---

## Screenshots

![](https://raw.githubusercontent.com/benbaker76/Pigtail/main/images/pigtail_00.gif)

![](https://raw.githubusercontent.com/benbaker76/Pigtail/main/images/pigtail_00.png)

![](https://raw.githubusercontent.com/benbaker76/Pigtail/main/images/pigtail_01.png)

![](https://raw.githubusercontent.com/benbaker76/Pigtail/main/images/pigtail_02.png)

![](https://raw.githubusercontent.com/benbaker76/Pigtail/main/images/pigtail_03.png)

![](https://raw.githubusercontent.com/benbaker76/Pigtail/main/images/pigtail_04.png)

---

## Controls (M5Cardputer keyboard)

Default navigation (as implemented in the current UIGrid input handling):

- **`,`** : left
- **`/`** : right
- **`;`** : up
- **`.`** : down
- **Enter** : open detail / confirm
- **Del / Esc** : go home / back
- **Esc** : reset (grid mode)
- **Space** : cycle grid icon mode
- **`w`**: add to watchlist (eye icon)
- **`w`** (hold 5s): clear entire watchlist (confirmation tone)
- **`i`**: add to ignorelist (warning icon)
- **`i`** (hold 5s): clear entire ignorelist (confirmation tone)
- **`k`**: dump watchlist to `pt_watchlist.kml` file on root of sd card
- **`s`**: toggle sound on/off (a confirmation beep plays when unmuting)

Navigation behavior:
- No wrap-around at the edges (left at start does nothing; right at end does nothing).
- Top/bottom bounds do not wrap to opposite edges.
- Scrolling occurs by rows when moving off the visible grid.

---

## UI overview

### Grid view (main view)
The main screen is a **7x4 grid** (28 slots) designed to fit exactly on a 240x135 display. Each visible slot represents one tracked entity (Wi-Fi client, BLE device, or AP).

The header shows:
- App name + version
- Current entity count (`n=...`)

**Key design goal:** the grid does *not* draw text over icons. Icons are rendered cleanly so you can compare devices quickly.

#### Grid icon modes
Press **Space** to cycle grid icon rendering modes (exact modes may vary by build, but typically include):

- **Large icon mode** (entity type emphasized)
- **RetroAvatar mode** (unique avatar emphasized)
- **Modes with small glyphs / MAC hints** (compact metadata without clutter)

Bars/indicators:
- **Bar 1** is driven by RSSI as a normalized value `0.0-1.0` (stronger signal → higher bar)
- **Bar 2** may be used for secondary metrics (e.g., score normalized to `0.0-1.0`)

#### Colors and quick recognition
Entity types use consistent accent colors so you can differentiate categories instantly. A typical mapping is:

- **BLE**: Blue
- **BLE tracker**: Yellow
- **Smart glasses**: Pink
- **Wi-Fi client**: Green
- **Wi-Fi AP**: Orange

(These mappings are easy to adjust in code if you prefer different colors.)

---

### Detail view
Selecting an entity opens a detail screen with:

- A small type icon (top-left)
- A generated "retro" name (top row, larger text)
- Text details below:
  - MAC address
  - RSSI
  - Score
  - Optional GPS/geo fields (if available in your build)

On the right side, the detail screen can show a large retro avatar for the selected entity, reinforcing recognition even when the MAC changes or is hard to remember.

---

## Trackers

The tracker pipeline has detection and persistence for common BLE "find-my" style devices (e.g., AirTag/Find My, Google Find Hub accessories, and Samsung SmartThings variants).

Trackers it will attempt to identify:

- **Apple AirPods**
- **Apple AirTag**
- **Apple Find My**
- **Chipolo**
- **Google Find Hub**: PebbleBee, Chipolo, Eufy, Motorola, Jio, Rolling Square
- **PebbleBee**
- **SmartThings Find**
- **SmartThings Tracker**: SmartTag 1, SmartTag+, SmartTag 2, Solum SmartTag
- **Tile**

---

## Smart Glasses

Pigtail can detect nearby smart glasses using BLE manufacturer data (company IDs) and device name heuristics. Detected glasses are shown with a **pink glasses icon** in both the grid and detail views.

Glasses it will attempt to identify:

- **Meta Ray-Ban** (company IDs 0x01AB, 0x058E; device name contains "rayban" / "ray-ban" / "ray ban")
- **EssilorLuxottica** (company ID 0x0D53)
- **Snap Spectacles** (company ID 0x03C2)

Glasses detection results are persisted alongside tracker data in the watchlist, so watched glasses survive reboots.

---

## Flock Surveillance Detection

Pigtail can identify nearby **Flock Safety** surveillance hardware (fixed cameras and Raven gear) via BLE advertisements. Detected Flock devices are shown with a **green Flock icon** in the grid (via the vendor mapping) and surface a `Flock: <type>` line plus a side badge in the detail view.

Signals it will check, in priority order:

- **Manufacturer ID `0x09C8`** (XUNTONG, supplies Flock's BLE radios — the strongest single signal). When this hits, the subtype is promoted to `Raven` if a Raven service UUID is also advertised.
- **Raven proprietary service UUIDs** (`0x3100`, `0x3200`, `0x3300`, `0x3400`, `0x3500` — sit above the Bluetooth SIG assigned range and uniquely tag Raven firmware)
- **Device name** containing `"raven"` or `"flock"`
- **OUI prefix `B4:1E:52`** as a fallback when no payload hint matches

Detection results are persisted alongside tracker / glasses data in the watchlist and survive reboots. In KML exports, Flock detections take precedence over Glasses / Tracker labels in the placemark name (and a `FlockType` field appears in the description).

Credits for the underlying research:
- **[colonelpanichacks/flock-you](https://github.com/colonelpanichacks/flock-you)** — main BLE/Wi-Fi Flock detector ecosystem
- **[wgreenberg/flock-you](https://github.com/wgreenberg/flock-you)** — discovered the `0x09C8` (XUNTONG) BLE manufacturer ID signature
- **[GainSec](https://github.com/GainSec)** — Raven BLE service UUID dataset (`raven_configurations.json`)

---

## Watchlist

![](https://raw.githubusercontent.com/benbaker76/Pigtail/main/images/watchlist_00.png)

Pigtail includes a **watchlist** feature to help you keep specific devices pinned and easy to monitor across scans and restarts. While viewing a device (in either the grid or detail view), press **`w`** to toggle the device’s `Watching` flag. When enabled, the UI displays a **red eye** icon on that device’s tile (and in the detail view) to make it immediately obvious that the device is being tracked.

Watchlisted devices are **persisted to flash memory**, so your selections survive reboots and power cycles without needing to re-tag devices each time. In addition, watchlisted entries are automatically **sorted to the front of the list**, ensuring the devices you care about remain visible even as new BLE/Wi-Fi targets appear and the list grows.

To **clear the entire watchlist**, hold **`w`** for 5 seconds. A descending two-tone sound confirms the action. Similarly, hold **`i`** for 5 seconds to **clear the entire ignorelist**.

## KML Export

![](https://raw.githubusercontent.com/benbaker76/Pigtail/main/images/watchlist_01.png)

Press **`k`** at any time to export the current watchlist to a KML file written to the **root of the SD card** as **`pt_watchlist.kml`**. This file can be imported into **Google Maps** (for example, via **Google My Maps**) to visualize watchlisted devices that include location data, making it easier to review sightings and map where tracked devices have been observed.

---

## How it works (high level)

Pigtail collects "observations" from wireless scanning sources and feeds them into a lightweight tracker:

- **Wi-Fi (promiscuous mgmt frames):**
  - Looks at management frames to observe client/AP presence.
- **Wi-Fi (scan results, optional depending on build):**
  - Can also use active scan results to discover APs and RSSI.
- **BLE (NimBLE scan):**
  - Captures BLE advertisement events with RSSI.

Entities are tracked in time windows:
- A device that appears consistently across windows becomes "more interesting"
- A device that appears briefly and vanishes is deprioritized

This is intentionally heuristic-based, because the goal is a *useful visualization* rather than a perfect classifier.

---

## Vendor icons

Vendor icons are stored as **monochrome (1-bit) 16×16** bitmaps to keep the UI fast and memory-efficient. You can use a tool like [LCD Image Converter](https://lcd-image-converter.riuson.com) to generate the **byte array data** for these icons, which can then be compiled directly into the firmware.

Vendor detection is driven by MAC OUI prefixes generated by **`generate_mac_file.py`**, which scans the upstream [nmap-mac-prefixes](https://raw.githubusercontent.com/nmap/nmap/master/nmap-mac-prefixes) database and produces a compact **`macprefixes.h`** header. At runtime, this mapping lets the tracker identify the vendor from the device MAC prefix and display the matching vendor icon automatically.

---

## Hardware

Designed for:
- **M5Stack Cardputer (ESP32-S3)**  
- **240x135** display

---

## Roadmap ideas

Planned future improvements may include:
- More refined scoring heuristics / profiles
- Better handling of randomized addresses (pattern grouping experiments)
- Additional views (filters, grouping, timeline, history)
- "Focus" mode to gather intel on selected device
- Activate tracker sound to locate it
- WiGLE API integration for SSID geolocation
- Device search / filtering
- More hardware support

---

## Credits

- [benbaker76](https://github.com/benbaker76) - Author & Maintainer
- [miyaoka](https://github.com/miyaoka) - Author of original [RetroAvatars](http://wa.zozuar.org/code.php?c=lX5A)
- [Henrique Sebastião](https://github.com/henriquesebastiao/) - Author of original `generate_mac_file.py`
- [nishad2m8](https://github.com/nishad2m8) - Author of original `GNSSModule` class
- [LucidDion](https://github.com/LucidDion) - Author of original `MarkovNameGenerator` class

Pigtail

Pigtail 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

Pigtail

Pigtail 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

Download README