00. Download - Install
ESP32 Hardware Compatibility:
- Zero-Hardware Receiver: INTERCEPTOR is a pure Python script that utilizes your computer's native Wi-Fi card in Monitor Mode to sniff ESP-NOW traffic directly from the air. It requires no ESP32 hardware to function as a receiver, and is universally compatible with reading packets originating from any Espressif chip (ESP32, ESP32-S2, ESP32-S3, ESP32-C3, ESP32-C6).
Prerequisites & Libraries:
pip install scapy mac-vendor-lookup customtkinterRequires Python 3. Because this script interacts directly with
raw network hardware, it *must* be executed using sudo. If using the GUI version on
Linux, `sudo -E` may be required to preserve display server variables.
01. Architecture
A lightweight, zero-hardware bridge that turns your computer's native Wi-Fi card into a direct ESP-NOW receiver.
OSC Sniffing
Instead of requiring a dedicated "Receiver ESP32" plugged into your computer via USB, this script sniffs raw radio waves, identifies packets coming from Espressif chips, perfectly slices out OSC (Open Sound Control) payloads, and forwards them instantly over UDP.
Live Hardware Discovery
Maintains an active memory bank of all ESP32s in the room, printing a clean
Session Summary of unique MAC addresses when you kill the script via Ctrl+C.
Works in fully offline environments after running the internal `update` command.
02. Command Line Arguments
| POS | Argument | Examples | Description |
|---|---|---|---|
| 1 | OS | mac, linux | Your current operating system variant to load specific sniffers. |
| 2 | TARGET | ALL, 24:0A:C4... | The specific MAC address to track, or ALL for all traffic. |
| 3 | INTERFACE | en0, wlan1 | The physical Wi-Fi hardware interface name. |
| 4 | CHANNEL | 1, 6, 11, 0 | The 2.4GHz Wi-Fi channel. Use 0 on Linux for background scanning. |
| 5 | DESTINATION | 127.0.0.1, pro-mac | Local IP or smart-handled Hostname of the target art machine. |
| 6 | PORT | 8000, 9000 | The UDP port the visual/audio software is listening to. |
| - | [LOG_FILE] | session.csv | (Optional) Save a full timestamped packet history. |
| - | [--wrap-raw] | --wrap-raw | (Optional) Non-OSC plain text payloads are pushed back in. |
03. Payload Gatekeeping
Valid OSC (Pass-Through)
If a packet contains a standard OSC address (`/`) or bundle (`#bundle`) paired with a valid null-terminated type tag, the script strips the radio header and forwards the raw bytes immediately.
Raw Text Wrappers (--wrap-raw)
If an ESP32 sends normal text (e.g.
"temp: 24.5") and the --wrap-raw flag is enabled, the router
intercepts it, mathematically pads it into 4-byte boundaries, and encapsulates the string
inside a valid /rawdata OSC message so it won't crash your target audio
software.
04. Execution Workflows
The Graphical Interface (GUI)
A dark-themed tracking dashboard built with CustomTkinter. All commands below are wrapped securely within this interface with real-time log scrolling.
sudo python3 INTERCEPTOR_GUI.pyCLI Mode: macOS Run Example
Because Apple heavily restricts background hardware control,
the script uses libpcap to read the raw radio waves, but you must manually lock
the frequency.
Hold Option(⌥) > Click Wi-Fi > Wireless Diagnostics > Window > Sniffer
> Lock to Channel
sudo python3 INTERCEPTOR.py mac ALL en0 1 visuals-macpro 8000Linux Environment Runner
Linux allows Python to fully control the hardware. The script
will automatically tear down your managed Wi-Fi, force the adapter into Monitor Mode, lock
the channel, and restore everything to normal the moment you press Ctrl+C.
sudo python3 INTERCEPTOR.py linux ALL wlan1 1 127.0.0.1 8000 session.csv --wrap-rawLinux Scan Mode Background Sweep
If you don't know what channel your devices are on, pass
0 as the channel argument. The script will launch a background thread that
continuously sweeps channels 1, 6, and 11 to discover lost devices.
sudo python3 INTERCEPTOR.py linux ALL wlan1 0 visuals-macpro 8000