[RFC] Automatic RF-gain protection for the Hermes-Lite 2

[on8st]

Rewritten 2026-09-10, much shorter. The original was far too long — apologies.

Problem

On a real antenna the HL2's front end clips at any usable RF gain. Measured on my station with an N2ADR filter board: every gain at or above 0 dB clips 86–100 % of samples, and the connect path restores +20 dB. A clipping ADC intermodulates across the whole receive span, so the band sounds busier and the natural reaction — more gain — makes it worse.

There is no automatic protection today. docs/HERMES.md roadmap 14 wants some.

What I measured

• The clean→clipping transition is 3–5 dB wide (six sweeps, two antennas, five bands, 1 dB steps).
• Above about −4 dB, 23 dB of the 31 dB gain range is railed.
• The ADC overload flag is a threshold, not a rate: at fixed gain its rate swings 0 %→90 % between successive 3 s windows.

Proposal

An Auto RF Gain toggle, off by default, on host-modulating backends:

• overload observed → back off 6 dB (6 clears the measured knee in one move)
• after a quiet interval → try 6 dB back; if it clips again, restore and double the interval
• the operator's own gain setting is never overwritten — the servo's offset is a separate number and the sum is displayed

The question I actually need answered

Is this wanted at all? With 23 of 31 dB saturated, the honest fix for a strong-signal station is a filter or an attenuator, not software. A reasonable answer is "ship the readout, not the controller" — surface the overload state so an operator can see it and decide. I would not argue with that.

Status

Implemented and unit-tested locally, not pushed and not offered as a PR — GOVERNANCE.md puts the RFC first. Happy to close this if it is not wanted.

Full measurements and the gateware reasoning are in my lab notes; I will keep them out of here unless asked.

[aethersdr-agent]

Thanks for filing this. This issue involves CI/CD workflows, build infrastructure, or release packaging — that is outside what I can help with, as I am restricted to source code changes in src/ and docs/.

Jeremy will need to handle this one directly.

— AetherClaude (automated agent for AetherSDR)

---

_{🤖 aethersdr-agent · cost: $19.3871 · model: claude-opus-5}

[on8st]

An operating objection to my own Decision 1 — posted ahead of the measurement, with its falsifier

From operating the station rather than reading the code. Posted before the measurement finishes, because the cycle takes 24 hours to traverse and the controller's shape should be argued now.

1. Decision 1 rests on one evening. Signal levels vary through the day: at night this antenna is red hot and the LNA has to sit near its minimum to stay clean, and in daytime it does not. Every live figure behind Decision 1 was taken 21:18–21:35 local at one site, and the RFC says so itself — the transition width survives that confound, the knee position does not.

The prediction, with its falsifier: I expect the knee to move 10–20 dB between a quiet afternoon and a loud evening. If it moves less than about 6 dB, two fixed states per band are viable and this objection collapses. The result gets posted either way.

The 6 dB is not arbitrary. The first sample is in — last night 23:07–23:16 local, three bands, same instrument and the same 1 dB sweep — and it is deliberately a repeatability control, taken the same night ~90 min after the Decision 1 sweeps. Against those, the knee moved 0, 2 and 1 dB on 80 m, 40 m and 20 m and the usable clean ceiling moved 4, 2 and 0 dB (1920 polls per sweep, 60 per gain step, dummy-load negative control 0/1920). Same-hour scatter is therefore about 2 dB on the knee, and 6 dB sits well clear of it. One site, two moments, both at night — there is not yet a single daytime sample, so this supports nothing yet; it sets the bar the daytime samples must clear.

2. It does not revive the servo. The flag is still one bit. At a fixed gain the observed rate ran 0 % → 90 % across successive 3 s windows — the same-gain negative control, 2 of 8 pairs positive, median +0.0 %. Nothing about the hour gives a threshold detector a magnitude. Decision 1's ruling stands.

3. What a moving knee breaks is the lookup table, not the controller. The distinction is not servo-versus-switch: the error signal is one bit, but the actuator is multi-valued. An integrator accumulating fixed steps on a sign-only error is an ordinary incremental controller.

• Two fixed gain states per band is a lookup table, and 20 dB of drift destroys it — a pair set for the evening leaves the radio deaf by lunchtime, one set for lunchtime clips all night.
• Incremental N × 6 dB back-off does not care where the knee is: 20 dB is four steps, and it behaves the same whether the drift is 5 dB or 25 dB.

6 dB is the right quantum precisely because the transition measured 3–5 dB — one step clears the knee outright and cannot stall inside it, where a 3 dB step can oscillate on the same edge. The 26 dB floor is then exactly four steps. Hl2AutoGainPolicy.h is parameterised (binaryHighLowConfig, AutoGainConfig::attackStepDb, the hold and the offset are inputs, not structure), so this is a configuration change, not a redesign — the same reason Decision 1 cost no rewrite.

4. The release condition is the hard part, and the obvious answer is wrong. I asked whether we can watch for the signal sitting consistently below some fraction of full scale. Not with WDSP's RXA_ADC_PK. docs/HERMES.md §12.5 records why: RXA_ADC_PK/RXA_ADC_AV measure the post-DDC slice while the clip flag measures the pre-DDC full spectrum, and — its words — "You can be far from clipping in a 48 kHz slice while a broadcast station saturates the converter." A quiet slice reads as headroom and walks the gain straight back into clipping. That is this RFC's own argument against #1162, pointed at the release path.

Three candidates, ranked:

(a) The wideband bandscope — strongest, because it needs nothing from anyone else. In hermeslite_core.v, usbs_fifo_i takes rx_data as its write data with wr_tvalid tied high — and rx_data is the same registered 12-bit pre-DDC signal that ad9866_i derives rxclip and rxgoodlvl from (ad9866.v: rxclipp/rxclipn against the two exact rails, rxgoodlvlp/rxgoodlvln against rx_data[11:9]). It leaves as bs_tdata on endpoint 0x04 at full 12-bit resolution, in usopenhpsdr1.v's wide_data_next. So the bandscope carries the very samples that clip, and the host could compute a true 0–38.4 MHz peak in dBFS with no gateware change at all. Caveats I own: docs/HERMES.md roadmap 18 is unimplemented, sized M; the stream is duty-cycled, not continuous — set_bs_cnt is host-settable and counts frames between wideband blocks, so a peak from it can miss a transient that rxclip, which sees every sample, catches; and it shares the 100BASE-T link with the IQ stream. We have neither implemented nor costed it.

(b) Probing — hold, try one step up, accept an occasional deliberate clip as the price of finding out. Works today, needs nothing new.

(c) rxgoodlvl exposed — a second pre-DDC threshold at −2.5 dBFS. Cheap in the gateware: control.v's response-address-0 composition carries a literal 8'h00 byte immediately beside (&clip_cnt), and address 2'b11 is marked "Unused in HL". But it needs the Hermes-Lite 2 project — Decision 3.

The bandscope route makes Decision 3 less of a blocker than the RFC implies, because (a) is a software change in this repository. It does not make the gateware ask worthless — (c) is far cheaper at runtime than decoding a wideband stream — but the RFC presents the release problem as having no in-tree answer, and it has one.

[on8st]

The release condition, built: probing, with its cost measured rather than waved at

This is candidate (b) from my ranking above, implemented. It needs nothing from anyone else — no gateware change, no rxgoodlvl, no bandscope decode, no endpoint that is not already carrying data today. It uses the one bit we have, at the cadence we already run at.

The scheme. Clip observed → 6 dB of back-off, immediately, no dwell. Hold at that back-off for a probe interval. Then remove the 6 dB and find out. A clip inside the confirmation period is a failed probe: the 6 dB goes straight back on and the interval doubles — 30 s → 60 → 120 → 240 → 480 — and stops at the cap. A probe that stays clean for the confirmation period is believed: the gain stays reclaimed, the interval collapses to base, and the next 6 dB follows one confirmation period later. The asymmetry is the mechanism, not the commentary — slow and quiet while the band is genuinely hot, fast to reclaim once it is not. It is §3 of my earlier comment carried into the release path: the memory is in time, not in decibels, which is the only kind that survives a knee moving 10–20 dB across the day. 6 dB because the measured transition is 3–5 dB wide, median 4, so one step clears the knee and cannot stall inside it. 3 s to confirm because the same-gain control saw the observed rate swing 0 % → 90 % between successive 3 s blocks at a fixed gain — anything shorter can sit entirely inside a lull and call it headroom.

The cost, and the number the whole scheme rests on. The flag reaches the controller on the EP6 stream, not on the 20 Hz discovery polls the bench used, so I traced the real cadence rather than assuming it. MetisClient's receive loop parses both frames of every datagram, accumulates response-address-0 observations with their denominator, and publishes them coalesced at MetisClient::kTelemetryMinIntervalMs; Hl2Backend::publishTelemetry evaluates the control law on that publish and on no other clock — the member comment beside the enable flag says "NO TIMER" in as many words. So one detection window is 100 ms, carrying ~19 response-address-0 observations at 48 kHz with one receiver and ~9 in the worst case where command ACKs displace every other classic slot; both are above the minimum denominator, so the window is a real rate rather than a thin one. A failed probe therefore rails the converter for roughly one tenth of a second — plus the few milliseconds it takes the gain bank to come round in the C&C rotation, since setLnaGainDb only updates the bank the round robin sends. That is a 0.33 % duty cycle at the base interval and about 6 seconds of clipping across an eight-hour night once the backoff reaches the cap. It can land mid-QSO, and it will. The clean accumulator is reset by every unkey, so a probe cannot fire until the loop has had a whole uninterrupted probe interval of receive — which means it cannot land in a short over and certainly can land in a long one. If that is not tolerable, the base interval is a number and not a law.

The upgrade path, and it is a replacement. If the wideband bandscope (a) is implemented, or rxgoodlvl is exposed in the gateware (c), the release condition becomes a real headroom reading and the probing is replaced, not supplemented — you do not probe for something you can measure. Neither is a prerequisite for this, and this is not an argument against either: it is what the release path looks like in the meantime, and the meantime is open-ended.

Status, and what it is not. Implemented and unit-tested locally on hl2/auto-rf-gain; unpushed, and not offered as a pull request, consistent with everything else in this RFC — GOVERNANCE.md puts the RFC first. Thirteen new properties against the pure control law, red before green, and the full suite at 372/372. It stayed a configuration of the same pure function alongside binaryHighLowConfig() — with two exceptions I would rather state than paper over: it needed one new field to reset the interval on a confirmed probe (nothing in the shipped law ever reset it, so last night's backoff would be carried into this afternoon), and one to stop the remembered trip offset flooring the release (that memory is a remembered decibel, and the test shows it stranding the loop 12 dB down long after the plant's knee had moved 18 dB). Both default to the shipped behaviour, so the law with no configuration is the law that shipped. No on-radio result exists and none is claimed — the plant in those tests is synthetic, and a synthetic converter cannot be wrong in the ways a real one is. The operator procedure that would test it on air is written and has not been run.

[jensenpat]

@on8st I can't decipher this much Claude speak. I don't think I've ever seen an issue like this - you opened an RFC with an issue on your own existing PR, which you're claiming isn't documented correctly? Why are there so many separate PR filings on doc bugs? Please clean this up.

[on8st]

You're right, and I'm sorry — that was far too much text and too many filings.

What I've changed: this issue's body is cut from about 64,000 characters to a page, and the two documentation PRs are now one — #5520 is closed and folded into #5533. I'm not opening anything else until what's already open is dealt with.

On the confusion, which was my fault for linking them: #5535 is a feature proposal, #5533 is a separate documentation fix that happens to correct a wrong premise in the same area. Two things, and I made them look like one.

If the feature still isn't worth your time, say so and I'll close it — the honest answer to my own question in there may well be "a filter, not software".