Settings Reference

This page documents every persistent setting in the AirLeak firmware. All settings survive reboot, firmware updates, and power loss — only airleak-factory-reset clears them.

Most settings can be changed from the desktop's AirLeak → Settings → Settings tab. The full set is reachable via the CLI.

---

Capture mode

Determines whether the radios are running and whether sessions are recording.

• setup — radios off, no events flowing. Used when configuring or moving locations.
• monitor — full sweep. Channel hopper sweeps 1–13, BLE active scan runs, all alert rules armed, session auto-recorded.

After power-cycle, the firmware automatically restores the previous mode before the desktop attaches. A unit last left in Monitor wakes up capturing.

See Capture Modes for the full picture.

---

Active BLE scan

Controls whether the unit transmits SCAN_REQs to elicit SCAN_RSPs from BLE peers.

• on (default) — captures friendly device names, full Service UUID lists, richer manufacturer data
• off — passive only, smaller RF footprint, but ~80 % of devices appear nameless

Most BLE devices put their friendly name in the scan response, not the legacy advertisement. Without active scan you'd see all the AirTags and AirPods, but the laptop named DESKTOP-II1L6R8, the TV named [TV] Samsung 5 Series, and the watch named Galaxy Watch5 (VBNY) would all be unnamed.

The single SCAN_REQ packet per peer is a 30-byte burst once per scan window. It is not decoded as anything other than a scan request by surrounding equipment, but technically the unit is transmitting. Set off for fully passive mode.

---

BLE scan window

How long the radio listens within each scan period. With the default 75 ms window inside a 100 ms interval, the BLE radio is receiving 75 % of the time.

• Larger window → more frames captured per period
• Smaller window → more time for WiFi capture to use the radio

The default is tuned for typical environments (≥10 BLE peers). In a dense public space (50+ peers), increasing to 100 ms matched with a 100 ms interval (100 % duty cycle on BLE) catches more advertisements but starves the WiFi side. The right choice depends on whether BLE or WiFi is your priority.

---

BLE scan interval

The total period of one scan cycle (window + gap). Default 100 ms gives a fast scan rate.

A (window=75, interval=100) setup is the sweet spot we ship by default — high BLE duty cycle with enough gap for WiFi to interleave.

---

Event throttle window

The minimum gap between consecutive same-type events from the same MAC, on the USB stream. Events arriving sooner are aggregated into the device record but suppressed from the wire.

Important: the throttle only affects the USB stream, not the aggregator or the alert engine. Every captured event still updates last_seen, RSSI, classification, and runs through alert rules. You're choosing how often the desktop sees updates — not how fast the firmware works.

See the Throttle page for capacity numbers.

---

WiFi channel list

Which 2.4 GHz channels the channel hopper visits.

Common alternatives:

Note: regulatory channels in some regions are limited (e.g. US allows 1–11). The unit doesn't enforce regulatory limits on capture (passive listening is generally allowed) but be aware of local rules.

---

Per-channel dwell time

How long the WiFi radio stays on each channel before hopping.

A typical AP beacons every ~102 ms. Dwelling at least 150 ms guarantees catching one beacon per visit, even when the channel-hop timing is unlucky.

---

Alert-rule enabled state

Each alert rule has an enabled flag. Disabled rules don't fire and don't consume cycles.

Default enabled state per rule:

See Alert Rules for what each rule does.

---

Internal counters (read-only)

These survive reboot but you can't write them:

These are surfaced via airleak-info.

---

Default-restoring

Two ways to return to defaults:

1. Per-setting — pass default to most commands:

   airleak-channels default
   airleak-throttle default
   airleak-scan-window default
   

2. All settings — airleak-factory-reset wipes the NVS partition entirely.

---