fix(hl2): forward power meter keeps the loudest sample per window

[on8st]

Summary

On a Hermes-Lite 2, the TX forward-power meter reads well below true PEP on speech. It reads correctly on a steady carrier. The cause is on the host: the radio reports forward power ~190 times a second at 48 kHz, and MetisClient keeps 1 of every ~19 samples. This PR keeps the loudest sample of each publish window instead of the last one, and feeds that into the existing hold from #4696 while keyed. Nothing changes unkeyed.

What happens

On the air, 40 m LSB, RF power 100 %, into a dummy load: AetherSDR's gauge showed ~1 W while a Nissei in PEP MAX read 2.7 W. That is about 4.3 dB low, with the Nissei near the bottom of its accuracy. On steady tones, the same coupler reading agrees with prediction to within 0.3 dB (see "Evidence" below), so the calibration curve is not the problem.

Why

Hl2TxLevelPolicy.h (the fwdPeakHoldStep comment) and #4696 state that forward power reaches us at 10 Hz. The radio does not limit it to that; the host does.

• The radio samples the detector at the frame rate. In gateware 74.2 (883a338), control.v:261 triggers the slow ADC on every other EP6 response: slow_adc_sample = run ? (resp_rqst & resp_cnt) : …. usopenhpsdr1.v toggles resp_rqst once per 512-byte frame, in SYNC_RESP. control_i is clocked by clk_ctrl (2.5 MHz) and slow_adc runs i2c_master at prescale 2, which is 312.5 kHz. A four-channel read, about 110 bit times, is therefore ~0.35 ms. At 48 kHz with one receiver, a trigger comes every ~2.6 ms, so the ADC keeps up.

• The radio reports it at that rate. Forward power rides in RADDR 1 of the response cycle. MetisProtocol.h already records that RADDR 0 arrives up to ~190 times a second; RADDR 1 is the next slot of the same cycle.
  Measured on this radio (gateware 74, receive only, unkeyed, 3 s each):

  stream rate	EP6 frames/s	RADDR 1 responses/s	forward-power field changed value
  48 kHz, 1 RX	764	191	≥ 99/s
  384 kHz (power-on default)	6098	1525	≥ 845/s

  So at 48 kHz, the 100 ms publish keeps 1 of 19. With the stream at 384 kHz, which is where AetherSDR ran the HL2 in the keyed test below, RADDR 1 arrived 1,524 times a second, and the last-value coalesce kept about 1 in 150. Unkeyed, the field is detector noise of a few counts, so repeated values hide some fresh samples. The change rate is a lower bound on the re-sample rate, and it already rules out a fixed 10 Hz.

• The host throws most of it away. MetisClient's receive loop merges every response into m_telemetry with Hl2Telemetry::apply() (last value wins) and emits at kTelemetryMinIntervalMs = 100 ms. So publishTelemetry sees one forward-power sample in roughly 19. The hold from fix(hl2): mic gain reached nothing, and the wattmeter read voice ~3.5 dB low #4696 then accumulates maxima of that decimated stream, which is why it "climbs toward PEP" and settles a few dB short.

The same decimation was already found and fixed for the ADC-overload bit: adcSamples and adcOverloadSamples are accumulated per window in exactly this loop, for exactly this reason. Forward power was left on last-value-wins.

The change (host-only, HL2 backend only, no behaviour change unkeyed)

1. ForwardPowerWindow in MetisProtocol.h. A small accumulator that keeps the maximum of DATA[15:0] over non-ACK RADDR 1 responses, plus a sample count. It sits in the header so the rule is unit-testable without a socket.
2. Accumulated in MetisClient's receive loop, beside the ADC-overload pair. The result is stamped onto Hl2Telemetry::forwardPowerPeakRaw and forwardPowerSamples at each emit, then cleared. The value is nullopt for a window with no RADDR 1, never a stale carry. It is cleared on session reset too.
3. In Hl2Backend::publishTelemetry, while keyed, the window maximum feeds the existing hold. Unkeyed, it keeps the last value exactly as today: the maximum of ~19 noise samples would sit above the no-carrier floor that MeterModel snaps to zero on.
4. Left alone. forwardPowerRaw (last value) stays for Radio Health, the bridge and SWR, which pairs forward and reverse. directionalWatts() and the hold constants are untouched. The fwdPeakHoldStep and kFwdPeakReleaseAlpha comments now describe the window-maximum input instead of a 10 Hz detector sample.
5. Tests. hl2_metis_protocol_test gets a window where the peak lands mid-window and the window ends on a trough. It checks that the window reports the peak, that RADDR 2 words and ACK echoes are excluded, and that clear() leaves no stale peak. The new socket-free hl2_fwd_window_wiring_test feeds synthetic EP6 datagrams through MetisClient's receive loop and pins the wiring: the emit carries the peak while forwardPowerRaw keeps the last value, a window with no RADDR 1 publishes nullopt, and the window clears at every emit. hl2_backend_seam_test pins publishTelemetry: keyed, TX:FWDPWR takes the window peak; unkeyed, or keyed with no RADDR 1 in the window, it takes the last value.

Every source change is under src/core/backends/hl2/; the rest are HL2 tests. Nothing above the seam changes.

What this does not fix, stated plainly. It is still a sampled detector. At ~190 samples a second, a speech peak shorter than ~5 ms can fall between samples. The detector's own RC time constant on the HL2 board is not established here, and it sets how much of that gap remains. A further step would be a host-side PEP estimate from the transmitted IQ envelope, scaled by a steady-carrier reference. That changes what the meter means, so it would be a separate RFC, not part of this fix.

Constitution principle honored

Principle VIII — Evidence Over Assertion. The "10 Hz" in the code comment was an assertion about the radio; the gateware and a receive-only rate measurement show it was the host's own decimation.

Test plan

• Local build passes (macOS, Ninja, Qt 6.8.3)
• Full ctest on this commit: green, except vkamp_connection_test. That one is a known timing flake on this machine: it also fails 3 runs in 5 on a tree without this change, and it passed 5 of 5 run on its own on this branch. It does not touch the HL2 backend.
• New hl2_metis_protocol_test case (window peak, RADDR 2 and ACK exclusion, clear())
• Keyed before/after on speech against true PEP (from the transmitted IQ envelope): old meter −2.7 to −8.4 dB, this PR −0.2 to −0.7 dB. Results: fix(hl2): forward power meter keeps the loudest sample per window #6019 (comment)
• Existing tests pass (CI)

Evidence

• Gateware: control.v:261 (sample strobe), usopenhpsdr1.v SYNC_RESP (resp_rqst toggle), slow_adc.v (four-channel I2C read, ain3 = fwd_pwr).
• Steady tones, same radio, keyed into a dummy load (TUNE at 5.66 W as the reference):
  • −6 dBFS tone: 4.38 W on the coupler, −1.12 dB against −1.28 dB on the wire.
  • 0 dBFS tone: 4.64 W, −0.86 dB against −1.04 dB on the wire.
  • So the coupler tracks the transmitted level to within 0.2 dB at the top of the range.
• Receive-only rate measurement: the table above. The probe starts the stream by unicast, checks the MAC, sends no MOX, and stops the stream.

Tested on macOS only. The change is in the platform-neutral backend and has no platform-specific code.

Checklist

• Commits are signed (docs/COMMIT-SIGNING.md)
• No new flat-key AppSettings calls
• Code is clean-room — the gateware cited is the open-source Hermes-Lite 2 RTL
• All meter UI uses MeterSmoother — no meter UI changed
• Documentation: no user-visible setting changes; the corrected claim lives in the code comment in Hl2TxLevelPolicy.h
• Security-sensitive changes reference a GHSA — not applicable

Whose keying. The peak path follows m_keyed, which is the host's keying intent. An operator keying through the HL2's own PTT input, without AetherSDR keying, still sees the old last-value reading, as the #4696 hold already did.

73, ON8ST

🤖 Generated with Claude Code

[aethersdr-agent]

Issue fit

There is no Fixes #NNNN in the body — this is a bug fix with a stated root cause, which GOVERNANCE.md explicitly exempts from needing an RFC first, so I reviewed it against its own stated intent. That intent is met: the receive loop did merge every EP6 response last-value-wins into m_telemetry and emit at kTelemetryMinIntervalMs (MetisClient.cpp:1944), so publishTelemetry genuinely saw one forward-power sample per ~100 ms window. The window maximum is the right shape of fix and it is placed beside the adcSamples/adcOverloadSamples pair that already solved the identical decimation for the overload bit. The decode is correct: RADDR 1 DATA[15:0] is exactly what Hl2Telemetry::apply writes to forwardPowerRaw (MetisProtocol.cpp:402-405), and the ACK guard is real — parseEp6Response reads a 6-bit raddr on ACKs (:326), so an ACK for command 0x01 would otherwise land in the window as our own echo.

What is not demonstrated is the headline number. The 1 W-vs-2.7 W symptom and the "keyed before/after on speech" checkbox are both unticked in your own test plan. The receive-only rate table (191 RADDR-1/s, ≥99 value-changes/s at 48 kHz) is solid evidence that the field is not 10 Hz-limited, and that alone justifies the change — but nothing here yet shows the gauge actually moved toward PEP. Please post that measurement before merge; it is the claim the whole PR rests on.

Scope

File	What it changes	Claimed?	Verdict
MetisProtocol.h	Hl2Telemetry::forwardPowerPeakRaw / forwardPowerSamples; new ForwardPowerWindow struct	Yes (items 1, 2)	In scope. Header-internal to the HL2 backend — not bridge/protocol surface; the health verb loops snap.order and neither field is added there.
MetisClient.{h,cpp}	window member; observe() in the receive loop; stamp + clear at emit; reset in start()	Yes (item 2)	In scope
Hl2Backend.cpp	keyed → peak, unkeyed → last	Yes (item 3)	In scope
Hl2TxLevelPolicy.h	comment correction only	Yes (item 4)	In scope
tests/hl2_metis_protocol_test.cpp	ForwardPowerWindow unit case	Yes (item 5)	In scope

Everything in the diff is explained by the PR's own description. No CHANGELOG.md entry (correct). No new bridge key, settings key, capability field or protocol verb. No deleted guard: I read the - lines — the only removals are the five comment lines in Hl2TxLevelPolicy.h being rewritten, and nothing they described was a behavioural guard. No sibling left behind: forwardPowerRaw, reversePowerRaw, biasCurrentRaw and temperatureRaw all still ride last-value-wins, and that is correct — SWR pairs fwd/rev and would be wrong on a max-of-one-and-last-of-the-other, temperature is deliberately slewed, and the PR says so.

Socket tests: none added or modified. hl2_metis_protocol_test is pure struct arithmetic with no QTcpServer/QUdpSocket/bind/listen/peer process. Nothing to surface.

Blockers

None. The correctness attacks below all failed to break it.

Nits (non-blocking)

• forwardPowerSamples has no reader anywhere in the tree — MetisProtocol.h:706, inline. Its adcSamples counterpart is consumed in four places; this one is consumed in zero. Either wire it or drop it.
• The m_keyed gate is host intent only, so external-PTT operators keep the old reading — Hl2Backend.cpp:9061, inline. Pre-existing (the #4696 hold already gated the same way), but it means the fix is silent about one class of HL2 operator.
• A stale cross-reference now points at a comment that says the opposite. Hl2Backend.cpp:9052-9053 still reads "See kFwdPeakReleaseAlpha for why a 10 Hz instantaneous sample of a speech envelope reads ~10 dB low" — and the whole point of the Hl2TxLevelPolicy.h hunk is that the 10 Hz was the host's coalesce, not the radio. Since that comment is the thing the reader follows to the corrected text, please fix it in the same PR.
• "For a carrier that costs nothing" is the one untested claim in the new comment — MetisProtocol.h:696, inline. TUNE routes through setKeying(true) (Hl2Backend.cpp:5789), so TUNE now reads a max-of-~19 too.
• No coverage of the wiring, only of the leaf — MetisClient.cpp:1910, inline. MetisClientTestAccess::feedDatagram already exists and is used socket-free by four tests; the two decisions that actually carry the behaviour have no test. Not a blocker under canon, but this is the cheap one to add.

What I tried to break

• Stale peak carried across windows or sessions. m_fwdWindow.clear() runs on every emit and in start() alongside the adcWindow* reset, and m_telemetry.forwardPowerPeakRaw is overwritten unconditionally at each emit rather than merged. I grepped for a second emit telemetryUpdated that could publish the struct with last window's peak still on it — MetisClient.cpp:1956 is the only one. stop() doesn't clear the window, but handleDatagram is unreachable with m_socket null and start() clears, so no path carries a peak into a new session.
• A window with no RADDR 1. forwardPowerPeakRaw stays nullopt and Hl2Backend.cpp:9061 falls through to *t.forwardPowerRaw — the pre-PR value. Correct, and a deliberate nullopt rather than a sentinel 0.
• First-sample and zero handling. if (!peak || v > *peak) makes a genuine 0 a measured zero rather than "no peak", and the test's "an empty window has no peak, not a zero" pins exactly that boundary. data & 0xFFFF can't go negative through the int cast.
• The ACK path putting our own echo in the window. I traced parseEp6Response's two raddr decodes; the test's ACK frame is 0x82, which decodes to raddr == 1 under the 6-bit ACK rule and is only excluded by the r.ack half of the guard. That test would fail if you dropped r.ack ||. The duplicate r.ack check against the caller's non-ACK branch is redundant but is what makes the rule testable without a socket, which the comment states.
• Whether the diff quietly changed SWR, Radio Health or the bridge. swrFromRaw, the kMinForwardCountsForSwr floor, healthSnapshot, the bandscope verb and the aether.hl2.tx debug line all still read forwardPowerRaw. Unkeyed behaviour is byte-identical.
• Thread affinity. m_fwdWindow is touched in handleDatagram and start() only — the same two places, on the same thread, as m_adcWindowSamples. No new cross-thread surface.
• Key-edge straddle. A window straddling key-down maxes to a keyed sample (fine). A window straddling key-up where m_keyed hasn't flipped yet reports the pre-unkey peak for up to one extra 100 ms window — slightly longer tail than before, but kFwdPeakReleaseAlpha's release dominates it, so I could not make this produce a visible defect.

Could not check: CI is green on all five checks, but hl2_metis_protocol_test appears in none of ci.yml's -R filters, so the new case did not run there — the evidence is your local ctest only. And I am headless: everything above is reasoned from the code in the head checkout, not reproduced at runtime. The gateware claims (control.v:261, slow_adc.v, the I2C prescale timing) are not in this repo and I could not verify them; the ≥99 value-changes/s measurement is what actually carries that argument, and it is enough.

Recommendation

Approve with nits, conditional on the keyed speech measurement. The mechanism is right, the seam is in the right place, the decode is correct against apply(), and the unkeyed path is genuinely untouched. Fix the stale Hl2Backend.cpp:9052 cross-reference (it now contradicts the comment it points at, in a PR whose whole argument is Principle VIII), decide forwardPowerSamples' fate, and post the before/after against the Nissei. A feedDatagram case over the receive loop would be a welcome addition but I would not hold the merge for it.

Nice piece of work — the rate table is the kind of evidence that makes a comment correction land.

---

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

[on8st]

Thanks. All five points are addressed in 8a929c1, e1ec3a3 and 1eda61c. The full suite is 553/553 locally and CI is green.

1. Stale cross-reference: fixed at Hl2Backend.cpp ~9052. The kFwdPeakReleaseAlpha comment in Hl2Backend.h carried the same 10 Hz premise and is corrected too.

2. forwardPowerSamples: kept, and now read. The lcHl2Tx directional debug line logs the window peak, the sample count and adcWindowMs, which comes from the same emit, so it is this window's length. The count is what a "sluggish meter" report needs.

3. "Costs nothing": replaced with a measured figure. On a steady keyed carrier into a dummy load, on this radio, the maximum of the last-value readings sits above their median by 0.031–0.052 dB from 0.5 W to 5.7 W. That is one radio. The TUNE reference quoted in the body moves from 5.66 W to about 5.71 W, about +1 %.

4. Wiring test: new hl2_fwd_window_wiring_test drives MetisClientTestAccess::feedDatagram with synthetic EP6 frames. It covers:

   • the peak landing mid-window, while forwardPowerRaw stays the last value;
   • RADDR 2 words and ACK 0x01 echoes kept out;
   • nullopt for a window with no RADDR 1;
   • the window clearing between emits.

   The keyed/unkeyed branch in Hl2Backend has no existing seam, so I left it alone.

5. External PTT: one sentence added to the body.

Keyed speech measurement, partial. Setup: 40 m LSB, RF power 100 %, mic 64, into a dummy load, three 8 s overs of the operator speaking, on this branch's build. Both directions of the radio traffic were captured.

• AetherSDR ran the HL2 stream at 384 kHz, so RADDR 1 arrived 1,524 times a second and the old coalesce kept about 1 in 150 (the body now says so).
• Reconstructed from the captured EP6 readings, against the highest coupler reading in each over:

over	old meter at unkey	new meter at unkey	new meter, held peak
1	−8.1 dB	−2.0 dB	0.0 dB
2	−3.6 dB	−2.0 dB	0.0 dB
3	−2.0 dB	0.0 dB	0.0 dB

• Not done yet: the comparison against true PEP from the transmitted IQ envelope. It needs a TUNE reference over, which this run did not capture. I will post it when it is run. No Nissei readings were recorded.

73, ON8ST

[on8st]

The keyed speech measurement is complete, against true PEP.

These figures replace the partial ones in my earlier comment. Those were measured against the highest coupler reading in each over, because the TUNE reference was missing then. Against true PEP the old meter reads slightly lower still.

Setup.

• This branch's build, on the repaired HL2, into a dummy load.
• 40 m LSB, RF power 100 %, mic 64.
• Three 8 s overs of the operator speaking, then one TUNE over as the full-scale reference.
• Both directions of the radio traffic were captured.
• True PEP = the TUNE over's coupler reading at |IQ| = 1 (5.68 W), multiplied by the maximum |IQ|² of each speech over's transmitted EP2 envelope.

over	true PEP	old meter (last value per window) at unkey	this PR, held peak (the app's own reading)
1	5.65 W	0.82 W, −8.4 dB	5.37 W, −0.2 dB
2	3.98 W	1.62 W, −3.9 dB	3.66 W, −0.4 dB
3	4.95 W	2.68 W, −2.7 dB	4.20 W, −0.7 dB

• The old-meter figures are reconstructed from the captured EP6 readings through the same fix(hl2): mic gain reached nothing, and the wattmeter read voice ~3.5 dB low #4696 hold, averaged over 10 window phases. The new figures are what this build displayed.
• The app ran the HL2 stream at 384 kHz here, so RADDR 1 arrived 1,524 times a second. The old coalesce kept about 1 in 150.
• The remaining 0.2–0.7 dB is the coupler's own sampling. Even at that rate the very top of a speech peak falls between readings. That is the limit the description already names under "what this does not fix".
• At the moment of unkey the new held value has already decayed by up to 2.4 dB through the existing ~2 s release. That is the hold, not this change.
• No Nissei readings were recorded, so the external meter is not part of this.

73, ON8ST

[ten9876]

We're updating this branch against main and landing it (maintainer pass); please don't push to it meanwhile. New commits go on top, with no rebase or force-push.

[ten9876]

Approving at d05a40dba (maintainer landing pass).

Protocol check against the HL2 gateware RTL (softerhardware/Hermes-Lite2 gateware/rtl, 3e467fd):

• control.v:473: response address 2'b01 carries {4'h0, temperature, 4'h0, fwd_pwr}, so RADDR 1 DATA[15:0] is forward power.
• control.v:269: fwd_pwr is slow_adc ain3.
• control.v:261: slow_adc_sample = run ? (resp_rqst & resp_cnt) : …, so the detector is re-sampled every other EP6 response.

That matches Hl2Telemetry::apply case 0x01 and ForwardPowerWindow::observe.

Hardware evidence (on8st's, not re-run here): keyed speech against true PEP from the transmitted IQ envelope, 40 m LSB into a dummy load. The old meter read −2.7 to −8.4 dB; this PR reads −0.2 to −0.7 dB (#6019 (comment)). On a steady carrier the shift is +0.03–0.05 dB on one radio (#issuecomment-5893694827). Nothing was keyed in this pass.

What this pass changed

• 8a6df22db, signed merge of origin/main (f2acec1). All five conflicts (Hl2Backend.{cpp,h}, Hl2TxLevelPolicy.h, MetisClient.cpp, MetisProtocol.h) were comment against comment: #6072's condensation against this branch's rewrites. I kept main's condensed form, restated for the window-maximum input. The branch's code is unchanged. git diff origin/main touches only the PR's own files.
• 5b145335b: condensed the PR's remaining comments to AGENTS.md § Comments, so the code carries no history. Also corrected the wiring test's note: RADDR 1 DATA[31:16] is temperature, not reverse power.
• d05a40dba: hl2_backend_seam_test now pins the keyed/unkeyed branch in publishTelemetry through the existing Hl2TxGateTestAccess friend. It sets only the m_keyed flag; nothing transmits.

Verified empirically (Linux, RelWithDebInfo):

• ctest: 550/550 pass, with socket-binding tests excluded per policy.
• Seven mutations, each built, run and restored, all caught:
  • observe() deleted
  • last value stamped instead of the peak
  • no clear at emit
  • clear before the stamp
  • leaf keeps the last value
  • backend uses the last value while keyed
  • backend uses the peak while unkeyed
• Static gates (check_engine_boundary, gen_touchpoint_manifest --check, check_capability_records, check_command_plane) are clean. No include changes.

Not verified: the reset in MetisClient::start() has no test, because start() binds the UDP socket. It is the same pattern as the adcSamples reset beside it.

Threads: all four review threads were answered with evidence and resolved.

CI freshness: this head's CI was created 2026-10-03T00:40:43Z. main's tip is f2acec1 (2026-10-02T23:27:17Z), the commit merged in, so there is no drift. Required checks are green.