ESP-Sniffer

A real-time Wi-Fi packet sniffer built on the ESP32. The ESP32 runs in promiscuous mode, captures raw 802.11 frames, and streams them over USB serial in PCAP format to a Python host tool that decodes, classifies, and displays them in a live color-coded terminal view.

System Architecture

The system is split into two halves:

• ESP32 firmware — puts the Wi-Fi radio into promiscuous mode, hops channels every 500 ms, wraps every captured frame in a PCAP packet header, and streams the raw bytes over UART at 921600 baud.
• Python host tool — syncs to the PCAP magic bytes, reads packet headers and frames, decodes the 802.11 control field, resolves vendor names from MAC addresses, and prints a live colored packet log with periodic statistics.

Live Output

Each line shows:

Every 50 packets a summary line prints packet rate and top frame types.

Project Structure

ESP-Sniffer/
├── esp/
│   ├── esp.ino          # Arduino entry point (setup / loop)
│   ├── sniffer.cpp      # ESP32 promiscuous sniffer + PCAP serializer
│   └── sniffer.h        # Constants and function declarations
├── assets/
│   ├── logigrame.png    # System architecture diagram
│   └── screenshot.png   # Live terminal output screenshot
├── manuf.txt            # Wireshark OUI/vendor database
├── requirements.txt     # Python dependencies
└── sniffer.py           # Python host tool

Requirements

ESP32 Firmware

• Arduino IDE or PlatformIO
• ESP32 board support package
• Board: any ESP32 development board (tested with CP2102 / CH340 USB-serial chips)

Python Host Tool

• Python 3.8+

Install dependencies:

pip install -r requirements.txt

Flashing the ESP32

1. Open esp/esp.ino in