Persistence

The AirLeak firmware uses ESP32-S3 NVS (non-volatile storage) for settings that must survive reboots. This page is a complete reference for what persists and what doesn't.

---

At a glance

---

NVS partition

The NVS partition is 24 KB. Across all firmware uses, we consume well under 2 KB — plenty of headroom for future settings.

NVS is wear-leveled flash storage. Settings can be written effectively unlimited times during the unit's lifetime — the controller spreads writes across cells.

---

What's stored

Settings namespace

Holds user-configurable settings:

airleak.mode             → "monitor"
airleak.active_scan      → 1 (on)
airleak.scan_window      → 75
airleak.scan_interval    → 100
airleak.throttle         → 1000
airleak.channels         → "1,2,3,4,5,6,7,8,9,10,11,12,13"
airleak.dwell            → 150
airleak.alerts_disabled  → "cafe_ssid_in_probe,random_mac_no_name"

Writes happen automatically when you change a setting via the CLI or the desktop UI. The write is synchronous — the command response confirms persistence.

Counters namespace

Holds firmware-internal lifetime counters:

boot.count               → 47
boot.last_firmware       → "airleak-v1.4.2"
boot.last_factory_reset  → 1714492800000  (epoch ms)
runtime.total_uptime_h   → 1432

boot.count increments on every successful boot. The last firmware version helps detect "this is the first boot after an update" so the unit can run any one-time post-update tasks.

runtime.total_uptime_h accumulates across boots — useful for diagnostics ("this unit has been on for 1432 hours total").

---

What doesn't persist

By design, these reset on every reboot:

Live device aggregator

The 768-slot aggregator lives in PSRAM. Reboot clears it. Devices repopulate as new advertisements arrive.

The desktop's library covers the cross-session story — devices seen in one session appear in the library the next session, even though the firmware aggregator is empty at boot.

Alert ring buffer

The 1024-entry alert ring is in PSRAM. Reboot clears it.

Alerts from before reboot live in the desktop's session record (if a session was active and finalized). The firmware-side ring is short-term operational state only.

Heartbeat counters

devices, events, events_throttled, usb_dropped, alerts — all reset to 0 on reboot.

Per-session counters

The aggregator's first_seen_ms and last_seen_ms for each device are timestamps within the current boot. Reboot resets the clock baseline.

---

Reboots vs power cycles

Both clear the in-RAM state identically. NVS settings survive both.

---

Mode auto-restoration

The capture mode is the most user-visible persisted setting. Sequence on boot:

1. ESP-IDF starts up → ROM bootloader → 2nd-stage bootloader → app
2. AirLeak firmware initializes, hardware checks pass
3. NVS read → mode restored from airleak.mode
4. If mode is monitor: radios start, sweeping begins, session auto-recording engages
5. If mode is setup: radios stay off, USB-CDC waits for a desktop connection

The whole sequence takes ~2 seconds. By the time the desktop connects, the unit is already capturing if mode was Monitor.

---

Settings update flow

When you change a setting via the CLI or desktop:

1. Command parsed, validity checked
2. New value written to NVS (synchronous)
3. In-RAM setting updated
4. Acknowledgment returned
5. (If applicable) Subsystem reconfigured — e.g. throttle change updates the throttle map immediately

The unit doesn't need to reboot for any setting change. Active scan toggle, scan window, channels, throttle — all take effect within the next scan period.

---

Factory reset

The full reset sequence:

1. Erase NVS partition
2. Re-initialize NVS with defaults
3. Reset boot count to 1
4. Re-write factory-default settings
5. Restart

Defaults after factory reset:

• mode: setup
• active_scan: on
• scan_window: 75 ms
• scan_interval: 100 ms
• throttle: 1000 ms
• channels: 1–13 (all)
• dwell: 150 ms
• alerts: all enabled except cafe_ssid_in_probe and random_mac_no_name

The boot count resets to 1, last firmware version is preserved (so the unit doesn't re-trigger first-boot tasks unnecessarily).

---

Firmware updates and persistence

When the firmware is updated (via Web Flasher or desktop auto-update):

1. New firmware writes to the inactive OTA slot
2. New firmware boots once for verification
3. If verification passes, the boot loader marks the new slot as active
4. If verification fails, automatic rollback to the previous slot

NVS is not touched in this process. All your settings — mode, throttle, alerts, channel list — survive firmware updates intact.

The single exception is the boot.last_firmware field, which is updated to record the new version.

---

NVS read errors

If the NVS partition becomes corrupt (extremely rare), the firmware boots into a recovery state:

1. Logs LOG: NVS read failed, using defaults to USB
2. Initializes all settings to factory defaults in RAM
3. Operates normally without writing back

You won't lose access to the unit — it just runs with defaults. Issuing a successful airleak-mode setup (or any setting write) repairs the NVS.

If reads continue to fail after a write, run airleak-factory-reset to fully reformat the NVS.

---