Firmware Overview

The AirLeak firmware is what makes the unit do what it does. It runs on the ESP32-S3, drives the BLE radio, decodes every captured advertisement, classifies devices, fires alerts, and streams the result to the mobile app over Bluetooth.

This section is the advanced reference for the firmware: how you talk to it, what settings persist, the alert engine, the safe-mode behavior, and how state survives 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 BLE radio
        │
        ▼
   ┌─────────────────────┐
   │  Observer scan      │
   │  (NimBLE, passive   │
   │   + active SCAN_REQ)│
   └─────────────────────┘
        │
        ▼
   ┌─────────────────────┐
   │  Parser             │
   │  BLE advertisement  │
   │  decoders           │
   └─────────────────────┘
        │
        ▼
   ┌─────────────────────┐
   │  Aggregator         │
   │  Classifier         │
   │  Leakage scoring    │
   └─────────────────────┘
        │
        ├──────────────►  Alert engine ──► threat-indicator LED
        │
        ▼
   ┌─────────────────────┐
   │  Delta ring → CBOR  │──►  Mobile app (BLE notify)
   │  capture stream     │
   └─────────────────────┘

   ┌─────────────────────┐
   │  Persistent config  │  ←  device name, LED,
   │  (LittleFS + NVS)   │     threat-indicator tuning
   └─────────────────────┘

The work splits across the two cores: the NimBLE host and scan callbacks on core 0, the parser / aggregator / stream tasks on core 1. That split is why a single-core ESP32 variant cannot run AirLeak's pipeline without dropping advertisements under load, see Why ESP32-S3?.

---

How you interact with the firmware

The only control surface is the mobile app over a BLE link. There is no web UI, no access point, and no serial console. (A compile-time AL_DEBUG_SERIAL flag exists for print-only USB diagnostics during development, but it's off in shipping firmware and is one-directional.)

Control rides a Nordic UART Service (NUS) JSON-RPC channel; the capture stream rides a separate dedicated BLE characteristic. The app calls these methods:

For day-to-day use you never touch these directly, the app's tabs (Live, Hunt, Drive, Insights, Modes, Settings, About) cover everything.

---

What persists, what resets

Full details are on the Persistence page.

---

Where to read deeper

• Settings Reference, every persistent setting and its default
• Heartbeat / state fields, what state.read reports
• Throttle & emit policy, how the stream is coalesced
• Alert Rules, every alert the engine can fire
• Safe Mode, when it triggers and what it does
• Persistence, what survives reboot, what doesn't

---