ZeroTrace AirLeak
Firmware Overview
What runs on the AirLeak unit, and how to interact with it
The AirLeak firmware is what makes the unit do what it does. It runs on the ESP32-S3, drives both radios, decodes every captured frame, classifies devices, fires alerts, and streams the result to the desktop app over USB.
This section is the advanced reference for the firmware: the CLI, the settings, every heartbeat field, the alert engine, the safe-mode behavior, and how settings persist across reboots.
If you're just getting started, start with Installation and First Capture. Come back here when you want to tune behavior or understand what the unit is reporting.
What the firmware does
2.4 GHz radio
│
▼
┌─────────────────────┐
│ Capture │
│ WiFi channel sweep │
│ BLE active scan │
└─────────────────────┘
│
▼
┌─────────────────────┐
│ Frame decoder │
│ WiFi mgmt frames │
│ BLE advertisements │
└─────────────────────┘
│
▼
┌─────────────────────┐
│ Aggregator │
│ Classifier │
│ Fingerprinter │
└─────────────────────┘
│
├──────────────► Alert engine
│
▼
┌─────────────────────┐
│ USB stream │──► Desktop app
└─────────────────────┘
┌─────────────────────┐
│ Persistent state │ ← Settings, mode,
│ (survives reboot) │ throttle, alerts
└─────────────────────┘
The work splits across the two cores: radio and scan callbacks on one core, parser and stream tasks on the other. That split is why a single-core ESP32 variant cannot run AirLeak's full pipeline without dropping events under load — see Why ESP32-S3? for the reasoning.
How you interact with the firmware
| Path | Use |
|---|---|
| Desktop app — AirLeak page | Mode picker (Setup / Monitor), live device tables, alerts, sessions, recognized library |
| AirLeak Settings tab | Active BLE scan toggle, throttle window, scan window/interval, persistent flags |
| AirLeak Settings → Command tab | Send any CLI command directly to the firmware, see the response |
| AirLeak Settings → Device log tab | Live serial log, filterable by tag |
| Web Flasher | Reflash firmware (recovery, manual updates) |
For day-to-day operation, the desktop UI covers everything. The CLI is the way to reach advanced controls — channel-sweep timing, alert-rule enable/disable, manual mode override, fingerprint reset, factory wipe.
What persists, what resets
| Setting | Persisted? | When it resets |
|---|---|---|
| Capture mode (Setup / Monitor) | yes (NVS) | Manual change, or factory wipe |
| Active BLE scan | yes (NVS) | Manual change, or factory wipe |
| Event throttle window | yes (NVS) | Manual change, or factory wipe |
| Scan window / interval | yes (NVS) | Manual change, or factory wipe |
| Alert-rule enabled flags | yes (NVS) | Manual change, or factory wipe |
| Device aggregator (live) | no | Reboot or mode change to Setup |
| Alert ring buffer | no | Reboot |
| Heartbeat counters | no | Reboot |
| Boot count | yes (NVS) | Factory wipe only |
| Last firmware version | yes (NVS) | Firmware update |
Full details are on the Persistence page.
Where to read deeper
- CLI Reference — every command the firmware accepts
- Settings Reference — every persistent setting and its defaults
- Heartbeat Fields — every diagnostic field in the 2 s heartbeat
- Throttle & Performance — how the throttle works, when to tune it, capacity numbers
- Alert Rules — every alert the engine can fire
- Safe Mode — when it triggers and what it disables
- Persistence — what survives reboot, what doesn't
- Updates — firmware update flow and rollback
Open the desktop app → AirLeak → Settings → Command tab. Type a command, press Enter, see the response. Every command in the CLI reference works there. The desktop UI uses the same commands behind the scenes.