Sniff''em
Sniff''em is a plug-and-play passive WiFi environmental monitor with an integrated reactive digital pet — designed for the LilyGO T-Display-S3 (ESP...
Sniff''em
Category: Embedded Systems / Cybersecurity / Wireless Monitoring / Digital Pet
Platform: LilyGO T-Display-S3 (ESP32-S3)
Framework: Arduino IDE / PlatformIO | C++
Status: Active — Production Ready
Project Overview
Sniff''em is a plug-and-play passive WiFi environmental monitor with an integrated reactive digital pet — designed for the LilyGO T-Display-S3 (ESP32-S3). It continuously monitors the wireless environment by sniffing 802.11 frames in promiscuous mode, calculates live packet-per-second (PPS) rates, tracks deauthentication frames, and expresses the wireless environment state through an animated pixel-art creature that changes its mood and appearance based on what it detects.
The name is a nod to both network sniffing and the Tamagotchi-era digital pet concept — Sniff''em is simultaneously a useful wireless security tool and an endearing piece of interactive hardware art.
Core Features
Passive WiFi Sniffing
- Places the ESP32-S3 WiFi radio into promiscuous mode — captures all 802.11 frames without joining any network
- Channel hopping: Automatically cycles channels 1 through 11 every 500ms for broad-spectrum coverage
- Frame classification: Distinguishes between:
- Beacon frames (access points advertising themselves)
- Probe Request frames (devices searching for networks)
- Data frames (active data transmission)
- Deauthentication frames (forced disconnection attacks)
- Disassociation frames (graceful disconnection messages)
Real-Time Packet Rate Calculation
- Measures live Packets Per Second (PPS) — the primary health indicator of the wireless environment
- Tracks Peak PPS — the highest single-second packet rate recorded since boot
- Both metrics displayed live on the sidebar telemetry panel
Deauthentication Frame Tracking
- Counts deauthentication frames separately from general traffic
- Cumulative deauth count displayed and highlighted in red when non-zero
- Elevated deauth rates trigger the ALERT pet state (see Reactive Pet below)
Reactive Digital Pet — Three Mood States
| State | Trigger Condition | Eyes | Mouth | Background |
|---|---|---|---|---|
| IDLE | Less than 50 PPS | Half-lidded / blinking | Floating Zzz dots | Dark blue + grid |
| EXCITED | 50-299 PPS or probe requests detected | Star eyes | Big smile with teeth | Dark teal |
| ALERT | 300+ PPS or 10+ deauths/second | X eyes | Angry frown | Flashing red |
The pet face occupies the left portion of the 320x170 display. It features:
- Pixel-art face with antennae
- Pulsing glow ring that animates around the face
- State-specific eye and mouth expressions
Visual Effects System
The rendering engine implements a rich set of visual effects that vary by pet state:
| Effect | State | Description |
|---|---|---|
| Floating ZZZ bubbles | IDLE | Animated text bubbles rise from the face |
| Sparkling star effects | EXCITED | Twinkling pixel stars burst around the pet |
| Particle burst system | EXCITED/ALERT | Dot particles spray outward on packet spikes |
| Red background flash | ALERT | Full background pulses red on high deauth rate |
| Scanline glitch effect | ALERT | Horizontal scanline distortion overlaid on display |
On-Screen Telemetry Sidebar
The right portion of the display shows a live statistics panel:
| Metric | Colour | Description |
|---|---|---|
| PPS | Colour-coded bar | Packets per second with visual intensity bar |
| PEAK PPS | White | Highest PPS recorded since boot |
| DEAUTHS | Red (non-zero) / White (zero) | Cumulative deauth frame count |
| STATE | Cyan badge | Current pet mood label (IDLE/EXCITED/ALERT) |
| CH | Green | Current sniffing channel (1-11) |
Hardware Reference (T-Display-S3)
| Pin | GPIO | Function |
|---|---|---|
| Power Enable | 15 | Must be HIGH for display power rail |
| Backlight | 38 | PWM backlight control |
| TFT MOSI | 6 | SPI data line |
| TFT SCLK | 7 | SPI clock |
| TFT CS | 5 | Chip select |
| TFT DC | 4 | Data/Command select |
| TFT RST | 48 | Display reset |
Display: 1.9" ST7789 IPS TFT — 320x170 pixels — 16-bit colour
MCU: ESP32-S3 — Xtensa LX7 dual-core @ 240MHz
Flash: 16MB QIO
PSRAM: 8MB OPI
USB: Native USB-C (VID 303A PID 1001)
Technical Architecture
| Component | Detail |
|---|---|
| MCU | ESP32-S3 @ 240 MHz |
| Display | ST7789 1.9" IPS — 320x170px |
| Display Library | TFT_eSPI (Bodmer) — sprite-based rendering |
| WiFi Mode | Promiscuous (no network join) |
| Channel Hopping | Every 500ms via millis() timer |
| Frame Callback | esp_wifi.h promiscuous receive callback |
| Serial Debug | 115200 baud — real-time PPS/state output |
| Build System | Arduino IDE or PlatformIO |
Serial Debug Output
Connect a serial monitor at 115200 baud to see real-time statistics:
[WiFi] Promiscuous mode active. Sniffing channel 1...
[Sniff'em] Ready.
[Stats] PPS=127 Peak=284 Deauth=0 (total=3) CH=6 State=1
[Stats] PPS=312 Peak=312 Deauth=12 (total=15) CH=7 State=2
State encoding: 0=IDLE, 1=EXCITED, 2=ALERT
Automated Flash Tool
Sniff''em includes a comprehensive Python flash utility (flash_device.py) that automates the entire build and deployment workflow:
| Command | Action |
|---|---|
| python flash_device.py | Auto-detect COM port and flash pre-built binary |
| python flash_device.py --port COM3 | Flash to specific port |
| python flash_device.py --build | Download arduino-cli, compile from source, flash |
| python flash_device.py --build-only | Compile only — do not flash |
| python flash_device.py --binary path\fw.bin | Flash specific binary file |
| python flash_device.py --list-ports | List all available COM ports |
| python flash_device.py --skip-deps | Skip Python dependency checks |
The --build flag orchestrates the complete pipeline:
- Downloads arduino-cli automatically
- Installs ESP32-S3 board support package
- Installs required Arduino libraries (TFT_eSPI)
- Compiles the sketch
- Flashes to detected device
Python Dependencies (PC-side)
| Package | Purpose |
|---|---|
| pyserial | COM port detection and communication |
| esptool | ESP32 firmware flashing |
| colorama | Coloured terminal output (optional) |
Legal Notice
Sniff''em uses passive monitoring only. It does not transmit any WiFi frames or deauthenticate any devices — it only reads 802.11 headers broadcast over the air.
Use responsibly and only on networks and environments you own or have explicit permission to monitor.
Use Cases
- WiFi security awareness device — visual indicator of wireless activity density
- Deauth attack detector for home network protection
- Network security education and demonstration tool
- Conference and event ambient wireless monitoring
- Hardware art piece — pixel pet that reacts to the invisible radio environment
- Penetration testing lab passive monitoring companion