Capture Modes

AirLeak has two capture modes. The current mode determines whether the radios are running, whether sessions are being recorded, and whether alerts are armed.

---

At a glance

---

Setup mode

The radios are off. The USB stream stays alive — the desktop sees heartbeats, can issue commands, can read settings — but no events flow because no frames are being captured.

This is the safe mode for:

• Initial connect (it's the default at boot if no mode is persisted in NVS)
• Switching locations between captures
• Long idle periods where you don't want to fill the device aggregator with stale entries
• Configuration: changing throttle, BLE active-scan toggle, scan window/interval

The mode is intentional silence. If you switch to Setup mid-capture, the active session is finalized to disk, the device aggregator is preserved (devices stay listed in the desktop's live view but won't update), and the radios power down.

---

Monitor mode

The full passive RF capture mode. This is what you want 99% of the time.

When you switch to Monitor:

1. WiFi promiscuous mode starts — captures all 802.11 management frames (probe-req, beacon, probe-resp, assoc-req, deauth) on the current channel.
2. Channel hopper starts sweeping channels 1 through 13. Default dwell time is ~150 ms per channel — fast enough to catch beacons (which fire every ~100 ms on most APs), slow enough to actually parse what arrives.
3. BLE active scan starts. 75 ms scan window inside a 100 ms interval — 75 % duty cycle. SCAN_REQs go out for every scannable advertisement received.
4. Alert engine is fully armed. Every event runs through the rule set; matching alerts go to the alert ring and stream over USB.
5. Session auto-recording kicks off. A new session ID is generated, a stub payload is written to <appData>/sessions/<id>.json, and every device + event + alert is folded into that session until you switch modes again.
6. Heap pressure increases — the radios + queues + aggregator consume real memory. Expect heap_free_pct to drop from ~28% to ~10%. That's normal — safe-mode triggers below 7%.

What happens when you switch back to Setup

• Active session is finalized — final device/event/alert counts written, ended_at timestamp set.
• The session file becomes downloadable via the Sessions page.
• WiFi and BLE radios power down.
• The cross-session library still has every device's history; nothing is lost.

---

Mode persistence

The active mode is saved to NVS (airleak.mode namespace) on every switch. After a reboot — power cycle, firmware update, watchdog reset — the firmware automatically restores the last mode before yielding to the desktop.

This means: once you've picked Monitor on a fresh device, every subsequent boot starts capturing immediately. You don't need to manually switch every time.

If you want to start in Setup for a particular session, click Setup in the Overview, then power-cycle. NVS will remember Setup.

To clear the persisted mode (and every other persisted setting): use airleak-factory-reset from the AirLeak Settings → Command tab. The unit reboots into the default setup mode.

---

Sub-modes (legacy)

The CLI still accepts these older mode names as aliases for Monitor, kept for backward compatibility:

Earlier firmware versions had distinct behaviors per name. The modern firmware unifies them into a single Monitor mode — every alert rule is always armed, every channel always swept, no need to pick a flavor. The legacy aliases are kept so existing scripts and CLI muscle memory keep working.

The desktop UI exposes only the two cards (Setup / Monitor) since they're the only meaningful distinction.

---

Quick mode switching from the CLI

If you prefer the keyboard, the firmware accepts mode commands over the serial CLI. From the desktop's AirLeak → Settings → Command tab:

airleak-mode monitor
airleak-mode setup
airleak-mode               # echoes current mode

The desktop UI updates within a heartbeat (~2 s) of the change.

---

Throttle interaction with mode

The event throttle (airleak-throttle <ms>) is independent of mode — it gates the USB stream regardless of which mode is active. Default is 1000 ms (1 s) per (MAC, event_type) pair.

In Monitor mode under heavy load (50+ active devices), expect events_throttled to grow into the thousands within a minute. That's healthy — it means the throttle is doing its job: every device still gets aggregated, but you only see one EV: line per second per fingerprint.

To see every single event (debug / packet-trace use case): airleak-throttle 0 (firehose mode). Brace for ~500 events/sec.