ZephCore/docs/ADAPTIVE_CAD.md

Adaptive CAD — Site-Calibrated Listen-Before-Talk

ZephCore's listen-before-talk (LBT) runs a hardware Channel Activity Detection (CAD) before every transmission: the radio's LoRa correlator searches the channel for chirps, and TX is deferred while activity is detected. How sensitive that search is comes down to one register value, cadDetPeak — and the right value depends on where the node lives.

• Too sensitive (detPeak too low): chirp-like interference — other LoRa networks, other spreading factors on the same frequency — triggers false positives. The node keeps deferring TX for nothing, wasting 100–200 ms retry cycles and adding latency; in bad cases it hits the 4-second CAD watchdog.
• Not sensitive enough (detPeak too high): real transmissions are missed and the node transmits over ongoing packets, causing on-air collisions.

A quiet valley node and a 50-network hilltop node need different values. Adaptive CAD measures the site and finds the value, instead of shipping one hardcoded number to everyone.

Important physics note: cadDetPeak is a correlation peak-to-noise threshold inside the radio's despreader — not a dBm level. The RSSI noise floor cannot be converted into a detPeak value, which is why this feature measures CAD behaviour directly instead of deriving it from RSSI.

The mental model: strong signals vs. faint ones

This is the picture that makes every knob below make sense. Skip it and the numbers look arbitrary; read it and "SmartCAD" is one idea seen from three angles.

detPeak gates on correlation strength, which tracks link budget — and it is blind to distance. The despreader's correlation peak is essentially the signal's SNR after processing gain, so a strong arrival produces a big peak and a weak one a small peak, regardless of how far it travelled. A 90 km line-of-sight repeater that arrives strong and a 1 km neighbour arriving strong both trip CAD; a faint straggler at the edge of decodability, a multipath echo, or a distant node buried in noise all produce small peaks. Raising detPeak raises the bar to "strong only"; lowering it means "hear even the faint stuff." There is no knob that separates near from far — only strong from faint — because the radio only ever knew signal strength, never distance.

Semtech's recommended values (21–29 across all SF/BW for the SX126x; our base is their table, ~20–24 at BW125) are tuned for a receiver that wants to hear everything down to its sensitivity limit — i.e. to catch the faint. Listen-before-talk on a busy backbone often wants the opposite: deliberately sit above that band so it ignores faint contention it would win on capture anyway. So "operating above 29" is not a misconfiguration here; it is the point.

Scale sanity, because the register is deceptive. cadDetPeak is a full 8-bit field (0–255), but the useful range is only ~18–35 on the SX126x. The driver's 48 ceiling is well above the highest value Semtech recommends anywhere — a near-blind guardrail, not an operating point. And the LR11xx/LR2021 family's ~50–85 numbers are a different chip's correlation scale; porting them onto an SX126x makes CAD deaf. If a value feels like it should be "mid-scale," that instinct is the trap: this scale is compressed, not linear over 0–255.

Bandwidth matters, and it matters unequally. Semtech's tables are bracketed by bandwidth, not just SF. On the SX126x the effect is mild — 1–3 counts per octave — but on the LR11xx it is roughly 12 counts per octave (at SF7: 52 at BW125, 64 at BW250, 77 at BW500). A bandwidth-blind base table is therefore a small error on one family and a large one on the other. This is not theoretical: the LR11xx base table used to be bandwidth-blind and taken from the wrong chip (it was the LR20xx 2-symbol row), reading 56 at SF7 where Semtech says 52. Field T1000-E companions at SF7/BW62.5 walked eight rungs down to the offset rail because of it, while an SX1262 in the same room settled at −1.

Below BW125 Semtech declines to give any value, and MeshCore's default preset is BW62.5 — so our normal operating point is off the end of the published tables. Both drivers reuse the BW125 row there rather than extrapolating the trend downward: the curve is noisy empirical PER data, and the staircase's whole job is to find the local value anyway.

Why the probes only ever measure the faint side. A calibration probe is skipped whenever RSSI is more than 7 dB above the noise floor (a strong signal is present — see the prefilter below). So every probe that runs does so in a quiet moment, and the only thing CAD can trip on there is a sub-floor, faint, correlation-only-detectable signal. That makes the entire adaptive loop a faint-rejection tuner: the busy% you read in get cad.stats is "how often a quiet moment still held a faint signal", not total channel occupancy. Strong signals never enter the statistics — they were filtered out before the probe, and in real LBT they trip on their own merits.

So the busy cap is really a faint-tolerance dial. set cad.busycap says "keep raising detPeak until fewer than N% of quiet moments trip on faint signals." A lower cap rejects faint traffic more aggressively (ignore echoes and stragglers); a higher cap tolerates more of it. On a saturated hilltop that should react only to strong contention, set the cap low (e.g. 10); the default 25 is a moderate setting suited to mixed and leaf nodes. This is the same mechanism as "airtime protection" below — two names for one lever, because the airtime a busy node wastes is the airtime spent deferring for faint traffic.

The one thing you cannot see locally. Because strong signals are prefiltered out of the measurement, a node can never confirm from its own stats that it still catches strong — the numbers only cover the faint side it is rejecting. The only check is behavioural: does the node still defer for its known strong peers? If it climbs so high that even they stop tripping, back the cap up. (This is the same "miss side is invisible" caveat noted at the end, viewed through the strong/faint lens.)

How it works

Every probe.interval seconds (default 15), when the radio is idle in receive mode, the firmware runs one calibration CAD probe and immediately re-arms RX. A probe takes one CAD duration — about 4 ms at SF7/250 kHz, up to ~130 ms at SF12/125 kHz — so the added radio deaf time is roughly 0.1%. Probes also run in RX duty-cycle (sniff) mode: the duty cycle is briefly interrupted and re-armed, within the same preamble-catch budget philosophy the sniff-mode math already accepts.

Each probe tests one level: a signed offset from the chip family's base detPeak for the current SF, bandwidth and CAD symbol count (all three from Semtech's LoRa Basics Modem reference tables — SX126x ~18–34, LR11xx ~50–85, LR2021 its own symbol-indexed table). Results accumulate per level:

• probes — how many CADs ran at this level
• busy — raw "activity detected" verdicts
• fp — suspected false positives: busy verdicts where no packet materialised right after (see filtering below)
• tp — true positives: busy verdicts confirmed by actual RX activity immediately after the probe

Filtering, because a "busy" verdict during apparent silence may be a real below-noise-floor packet (detecting those is CAD's whole purpose):

1. Probes are skipped entirely when the channel is visibly busy (RSSI more than 7 dB above the learned noise floor) or a packet is being received — those teach nothing about false positives. (This is also the prefilter that limits probing to the faint regime; see the mental model above.)
2. After a busy verdict, RX is restarted and the firmware watches a ~12-symbol window for either signal of a real transmitter: (a) the restarted RX syncs on it, or (b) instantaneous RSSI climbs above the noise floor. If neither appears, the verdict counts as a suspected false positive. Path (b) matters: tearing RX down to run the probe routinely eats a real packet's preamble, so RX often fails to re-sync on a signal that is genuinely there — an earlier isReceiving()-only check booked those as false positives, a detPeak-independent floor that flattened the FP curve and drove the staircase into the ceiling. Channel energy does not depend on winning the preamble race, so it recovers them. Residual contamination by real below-floor traffic biases the estimate conservative (higher detPeak), which is the safe direction.

Statistics decay (halve) every 6 hours so the picture stays fresh, and reset completely whenever the radio parameters change (frequency, SF, BW — the data is only valid for one configuration).

Auto mode (staircase) — ON by default

cad.auto ships on, on repeaters and companions alike. A one-sided staircase controller acts on the probe stats:

The controller is knee-seeking. The false-positive-vs-detPeak curve falls as detPeak rises (less sensitive → fewer false detects) and flattens past a knee; the sweet spot is that knee — the most sensitive detPeak whose FP has already bottomed out. Probes sample the operating level and both neighbours (op−1 more sensitive, op+1 less sensitive; op weighted half, each neighbour a quarter) so the staircase can read the local curve slope:

• Airtime protection (highest priority): step up when the operating level's total busy rate — real traffic plus false positives — exceeds the busy cap (set cad.busycap, percent; default 25%, 0 = off). The knee logic only minimises false busy, but on a congested hilltop most busy verdicts are real distant traffic we'd win on capture anyway; deferring for all of it starves the node's own airtime. Self-targeting — a quiet node's busy rate never reaches the cap, so only a genuinely busy backbone backs off. Shown as bc: in get cad.stats.
• Step up (less sensitive) when the level above is markedly cleaner — FP drops ≥5%/level (CAD_KNEE_SLOPE_PERMILLE). That means we're on the steep part below the knee; climb toward it.
• Step down (more sensitive) only on a flat plateau (frontier no worse than operating, slope <5%/level) that is already clean (FP ≤5%, CAD_PLATEAU_CLEAN_PERMILLE) — reclaim sensitivity that costs nothing.
• Otherwise hold — either at the knee (steep below, flat above) or on a noisy flat plateau.

Using slopes rather than an absolute FP target makes convergence independent of a site's FP floor (which varies with traffic and with the classifier's residual false-positive rate). The clean-plateau guard is what stops a flat-but-noisy curve from walking to the sensitive rail: there, holding is the least-bad move, while a genuinely quiet flat-low site correctly descends to the floor. Each involved rung needs ≥120 samples (CAD_STEP_MIN_PROBES) before a step, so a decision lands roughly every 1–2 hours at the default interval.

A step decision requires the operating rung (and, for the direction chosen, its neighbour) to be warm; get cad.stats's three-rung window shows exactly those levels, so the slope the controller is acting on is visible directly. The offset is persisted to flash whenever it steps.

The offset is clamped to −8…+12 levels around the family base — wide enough that a dense hilltop can settle much less sensitive and a quiet valley node much more sensitive. The driver additionally clamps the absolute detPeak (SX126x 12–48, LR11xx 40–100, LR20xx 48–90), and now reports that clamp to the controller, which narrows the offset window to match. That reporting matters: where base+offset falls outside the clamp, several offsets collapse onto the same peak, and the staircase reads the sampling noise between identical configurations as curvature — which is how a node can random-walk to a rail. That absolute clamp is a firmware guardrail, not a chip limit — cadDetPeak is a full 8-bit register (0–255) — it simply stops the staircase from wandering into "CAD never fires" (detPeak too high → LBT effectively off) or "CAD always busy" (too low → node can't transmit) territory. Quiet sites converge below the standard value — more sensitive LBT than any fixed-config firmware, meaning fewer TX-over-RX stomps. Noisy sites ratchet up until false positives vanish.

To watch or hand-tune instead of letting it self-adjust, set cad.auto off (see below).

Reading the status

Out of the box the node calibrates itself — you don't have to do anything. To see what it's doing:

get cad

Compact output (kept short so it survives a truncated LoRa reply):

> a:on o:-1 pk:20(b21/4s) sp:0.9/84%(312) bc:25%
 -2(19) 241p 9b 7f 2t 3%
*-1(20) 900p 5b 3f 2t 0%
 +0(21) 300p 2b 0f 2t 0%

Header: a auto on/off · o operating offset · pk operating detPeak · b family base · 4s 4 symbols · sp RSSI burst quality · bc busy cap.

sp — are the noise-floor sampler's reads independent? The floor sampler takes a median of 8 RSSI reads. The chip refreshes RSSI only once per averaging window (~16 µs at BW 62.5, ~134 µs at BW 7.8); reads issued faster than that return the same underlying value repeatedly and the median collapses to a single read. sp reports mean spread (max−min) across a burst, the share of bursts whose spread was 0, and the burst count.

Read it this way:

• A non-zero mean proves the reads are independent, however high the zero-spread share climbs. A quiet or steadily-occupied channel genuinely reads the same value 8 times at integer-dB resolution — that is correct, not broken.
• Mean 0.0 with a high share is the fault signature: no burst ever spans anything, i.e. 8 copies of one sample.
• The count matters. The burst rate is not derivable from uptime, because the sampler's guards (TX, mid-RX, duty-cycle sleep) block an unknown fraction of attempts, so a share without its denominator is unreadable. It appears on the local USB console only — a remote reply is capped at 161 B and the three level rows have first claim on it. All three counters halve together at 8192 bursts, so the count stays four digits and the figures describe a recent window rather than everything since boot.

Measured on-air at BW 62.5: 0.6/90% on a quiet channel, 0.9/84% with the floor at −103 dBm. The share falls and the spread rises as ambient comes up — independent reads, responding the right way.

Note what this median does and does not do. The burst spans ~300 µs against a ~200 ms SF8/BW62.5 packet — about 0.15% of one transmission — so a neighbour's packet is either wholly inside the burst or wholly outside it, every read sees the same level, and the median returns it rather than rejecting it. The median rejects sub-300 µs glitches and bad SPI reads. Interference is handled by the mid-receive guard and the +14 dB threshold filter, not here.

The probe interval used to sit in this slot; it moved out because it is a pref you set, readable with get probe.interval, whereas burst spread is only observable from inside the sampler. Then a three-rung window centred on the operating offset (* marks it): the frontier (one step more sensitive), the operating level, and one step less sensitive — exactly the three rungs the staircase reads to judge the local slope. Per level: level(peak) probes busy fp tp fp%% — fp = suspected false positives, tp = busy verdicts confirmed by a real signal, fp%% = integer false-positive rate.

Here the staircase has already stepped to offset −1 (peak 20): the −1 level is clean (0%) over 900 probes while −2 shows a 3% jump, so −1 is this site's knee. Remember (mental model above) these numbers describe the faint regime only — strong signals were prefiltered out before probing.

Dry-run / manual tuning

Prefer to observe or pin the value yourself? Turn the staircase off:

set cad.auto off

Probing continues (stats keep updating) but the operating offset no longer moves. In dry-run the probe sweep covers levels −4…+4 evenly, so get cad.stats shows the whole false-positive-vs-detPeak curve. Read it bottom-up: the level where fp%% jumps from ~0 is the knee; sit one step above it. Then pin it:

set cad.offset -1

Negative offset = more sensitive LBT (catches weaker signals, risks false busy); positive = less sensitive. Range −8…+12. Re-enable the staircase any time with set cad.auto on. Offset changes (manual or automatic) appear in the log as cad: step down/up -> offset N.

To collect dry-run data faster, drop the interval (probing is temporary then): set probe.interval 10. At the default 15 s, allow ~a day for a knee to resolve clearly, longer to capture day/night variation.

Command reference

Command	Default	Description
get cad.stats		Status + per-level statistics (see above).
set cad.auto <on|off>	on	Staircase controller acts on the stats. Off = observe/hand-tune.
set cad.offset <n>	0	Operating offset, −8…12. Negative = more sensitive. Applied live.
set probe.interval <sec>	15	Shared cadence for the noise-floor sample and the CAD probe that consumes it; 0 disables probing (and freezes auto), 10–255 otherwise.
set cad.busycap <pct>	25	Faint-tolerance / airtime cap: raise detPeak once more than this % of (quiet-moment) probes trip on faint signals. Lower = reject faint/echo harder (busy backbones); 0 = off. 10–90 otherwise.
set cad.reset		Clear accumulated statistics (RAM only).

All settings persist in prefs and apply to every role — repeater, room server, and companion (companions reach the CLI via the v-contact admin chat or USB serial). Command keywords are case-insensitive (Get cad works); command values like passwords and node names are not, so on /off must be lowercase.

Notes and limits

• SX127x boards (TTGO LoRa32, T-Beam classic) have no hardware CAD; get cad.stats reports not available and the settings are inert. Their LBT remains the RSSI-based int.thresh gate.
• The false-positive side is measured; the miss side mostly is not. A too-high detPeak shows up as on-air collisions, which a single node cannot observe. That is why the workflow is "find the lowest clean level and sit at it", never "raise it until problems stop being visible". The tp column is the one local miss-side signal: probes that detected real below-noise-floor traffic.
• detPeak is the only adaptive knob. cadDetMin stays at Semtech's universal 10; the symbol count is fixed at 4 (better mid-payload detection than 2 — most of a mesh packet's airtime is payload, and that is where a pre-TX CAD usually lands). The drivers scale their CAD timeout with symbol count and preset automatically.
• Statistics are RAM-only and restart after a reboot; the learned offset is persisted. Mixed fleets are fine — this feature changes only when this node decides the channel is busy, not anything on the air.
• Related but separate: int.thresh (RSSI-above-floor software gate) and dc.restarts (sniff-mode false-preamble counter) still work as before; adaptive CAD complements them.