Heartbeat Fields

The firmware emits a heartbeat every 2 seconds, regardless of capture mode. The heartbeat is a structured status record covering connection state, capture activity, memory, and timing.

The desktop's status bar reads from the heartbeat. If you're scripting against the unit, the heartbeat is what you should poll.

---

Field reference

Identity

Capture state

When mode=setup, scan_state=off and current_channel=0.

Activity counters

When events_throttled is much larger than events, the throttle is doing its job — most events are aggregated but not streamed. That's normal in dense environments.

Memory

The status bar's Heap NK (X%) is heap_free / 1024 and heap_free_pct. Color coding:

• >12% — green (healthy)
• 7–12% — orange (under pressure)
• <7% — red (safe-mode armed)

largest_block matters under pressure: even with 30 KB free heap, if the largest contiguous block is only 3 KB, the unit can't allocate large queues and may stutter.

Timing

time_since_last_event_ms is useful for diagnosing "is anything happening." If it climbs above 30 s in Monitor mode, either the area is empty or the radio is wedged.

Health flags

If any of wifi_healthy / ble_healthy / parser_healthy is false, the desktop displays a red dot and surfaces a diagnostic in the status bar.

Per-task CPU snapshot

A small per-task CPU usage table is included for diagnostic purposes:

These are rolling averages over the last second. Saturation (any task > 90 % consistently) means the throttle should be increased.

Aggregator state

A growing aggregator_evicted count in a long capture means devices were rotating fast enough to fill the aggregator. The desktop's library still has them via cross-session matching — eviction only affects the live in-firmware aggregator.

Channel histogram (last minute)

A compact representation of how many frames hit each channel in the last minute:

ch_hist: 1=12 2=8 3=4 4=2 5=3 6=58 7=2 8=4 9=5 10=8 11=124 12=1 13=2

Useful for spotting "channel 6 and 11 are busy, the rest are quiet." The dominant channels are usually the non-overlapping ones (1, 6, 11).

---

Heartbeat cadence

The cadence is constant — the heartbeat doesn't slow down or speed up under load. A heartbeat skipped is a sign of trouble (parser starved, USB queue saturated).

---

Reading heartbeats from the desktop

Open AirLeak → Settings → Device log. Filter for HB::

HB: mode=monitor scan=active devices=87 events=4421 ...
HB: mode=monitor scan=active devices=89 events=4533 ...
HB: mode=monitor scan=active devices=89 events=4631 ...

Each line is one heartbeat. The desktop's status bar parses these in real time.

---

Reading heartbeats from a script

If you connect to the unit's COM port directly (921600 baud, USB-CDC), you'll see lines prefixed:

• HB: — heartbeats
• EV: — events (when in Monitor)
• AL: — alerts (when in Monitor)
• DEV: — device dumps (on demand via airleak-snapshot)
• LOG: — diagnostic log

Heartbeats arrive every 2 s on a steady cadence. The format is structured (key=value pairs) — easy to parse without a JSON dependency.

---

When heartbeats matter most

• Connection lost — heartbeat freezes; desktop dot turns gray
• Heap pressure — heap_free_pct drops; orange / red threshold
• Stuck channel — current_channel doesn't advance; wifi_healthy=false follows
• Stream backlog — usb_dropped climbs; drop_pct > 5 %
• Aggregator full — aggregator_full=true; evictions begin

Watch the heartbeat first when something feels wrong. It's the most informative single log line on the unit.

---