feat(bandplan): segment usage notes; fix all-modes rows painted digi-only (#4667). Principle IV.

[NF0T]

Summary

Implements RFC #4667. The RFC has been open since 2026-08-01 with no maintainer decision, so this PR carries both parts as one reviewable change. Maintainers can accept, trim or reject it as a whole.

The IARU Region 1 HF chart (effective 16 Oct 2020) gives each row two columns, preferred mode and usage. Our band-plan JSON had a single label. Every row reading "All modes" with "Digimodes" usage was therefore transcribed as digi-only and painted narrow-band red. #4610 reported one such row and #4635 fixed exactly that one. The rest are fixed here, and the schema gains the column that was missing.

Part 1 — data. I re-checked every row against both charts on 2026-10-18 (pdftotext -raw).

Segment	iaru-region1.json	ssa-sweden.json
1.840–1.843	DIGI → ALL	DIGI → ALLA
3.600–3.620	(ALL since #4635) + usage	DIGI → ALLA — #4635 never touched this file
7.050–7.060	DIGI → ALL, split at 7.053 per the chart	DIGI → ALLA (SSA has one row)
14.101–14.112	DIGI → ALL	DIGI → ALLA
18.111–18.120	DIGI → ALL	DIGI → ALLA
21.110–21.120	stays DIGI, usage says "All modes except SSB"	stays DIGI, usage says "Alla moder utom SSB"
24.931–24.940	DIGI → ALL	DIGI → ALLA
29.200–29.300	DIGI → ALL	DIGI → ALLA

All changed rows also move from #c03030 to #ff8000, the colour #4635 used. SSA usage text is in Swedish, transcribed from SSA Bandplan Kortvåg v2.61, to match the file's existing Swedish labels. As the RFC said, only rows where SSA v2.61 agrees with the 2020 R1 chart are changed. The 3.570 boundary is untouched.

Why 21.110 keeps DIGI: the chart's mode column there is "All modes … (not SSB)". A label that says so, such as NOT SSB, contains the token SSB, and isVoiceSegmentLabel() would then add the segment to the S-History voice mask (see the correction on the RFC). Keeping the label and putting the restriction in usage avoids that.

Part 2 — schema. BandPlanManager::Segment gains an optional QString usage, parsed from a "usage" key. It is last in the struct, so the existing positional initialisers in spectrum_overlay_band_highlight_test and kat500_tx_controls_test stay valid. Plans without the key behave exactly as before.

Hover. In SpectrumWidget::mouseMoveEvent, the band-row block gains a third fallback after band-plan spots and KiwiSDR spots. If the segment under the cursor has usage, it shows low–high MHz — label with the usage note below. There is no new interaction or widget, and no change to clicks. It honours band-plan size Off, as the KiwiSDR fallback does. Segments without usage still get hideText().

Voice detection is unchanged. usage never reaches isVoiceSegmentLabel(). DIGI → ALL/ALLA changes no voice-mask membership, because neither label matches a voice token. A separate pre-existing defect in that mask came up during this work: on IARU R1, R3 and SSA, voice detection never fires on HF. It's filed as #6572, with a live A/B on a FLEX-8400, and is outside this PR's scope.

Closes #4667.

Constitution principle honored

Principle IV — the data is transcribed from public documents: the IARU R1 HF band plan (eff. 16 Oct 2020) and SSA Bandplan Kortvåg v2.61. No proprietary sources.

Principle VIII — every claim below comes with the command that checks it, including a control showing the new test fails on main's data.

Test plan

Built with MSVC 2022 / Qt 6.12.0 on Windows 11, RelWithDebInfo, in a separate worktree and build dir.

• Local build passes. Full build green.

• New bandplan_usage_resource_test: 92/92 pass. It loads both shipped plans through BandPlanManager::loadPlans() and setActivePlan(), so the parser and the resource are checked together. It checks label, colour and usage on every corrected row. It fails on any red DIGI row other than the 21.110 exception, and checks that ARRL (US) parses with no usage. Settings are isolated with AETHER_SETTINGS_DIR plus Qt test mode.

• Control: the new test fails on main's data. With main's two plan files put back and only the test rebuilt, it reports 56 of 85 checks failed, each on a row this PR changes.

• Existing tests pass: bandplan_voice_labels_test, band_plan_license_filter_test, spectrum_overlay_band_highlight_test, kat500_tx_controls_test.

• The hover was checked on a real SpectrumWidget, offscreen. I added a case to the opt-in spectrum_confirmed_geometry_test (-DAETHER_BUILD_SPECTRUM_GESTURE_TEST=ON). It loads IARU R1, sends a real QMouseEvent to the band row, and reads QToolTip:

  • Control: the existing spot tooltip at 14.100 shows 14.100 MHz — IBP/NCDXF beacons.
  • 14.105 shows 14.101–14.112 MHz — ALL / Digimodes, automatically controlled data stations (unattended).
  • 14.120 (14.112–14.125, no usage): no tooltip.
  • Band strip Off: no tooltip.

  I could not run that test on this machine. It also covers the RTL-SDR backend, and RTL-SDR is compiled out here because librtlsdr isn't installed. It fails to link the same way on main. I compiled the test file to check the new case, and ran the identical case in a temporary probe built from the same app sources, which is where the results above come from. The probe is not committed.

  One thing the probe showed: off-screen there is no QRhi, so right after show() the PanadapterMessageOverlay "Spectrum renderer unavailable" notice covers the band row, and mouseMoveEvent gives way to any child under the pointer. Without waiting for it to clear, the existing spot tooltip fails too. The committed case waits for it and checks the spot-tooltip control first. This is a test-environment artefact, not a user-facing behaviour.

• All 12 Static checks scripts pass locally with --strict, and check_a11y.py reports 0 findings on SpectrumWidget.cpp.

• The docs site builds: cd docs/user && npm ci && npm run build.

• Behaviour verified on a real radio — n/a. This is advisory display data plus a hover tooltip, with no radio interaction.

To reproduce the chart reading:

curl -sL -o r1.pdf https://www.iaru-r1.org/wp-content/uploads/2021/06/hf_r1_bandplan.pdf
pdftotext -raw r1.pdf - | grep -E "^(1840|3600|7050|7053|14101|18111|21110|24931|29200) "

Checklist

• Commits are signed (docs/COMMIT-SIGNING.md)
• No new flat-key AppSettings calls — none added
• Code is clean-room — not decompiled, disassembled, or reverse-engineered from a proprietary binary (Principle IV)
• All meter UI uses MeterSmoother — n/a, no meter UI
• Documentation updated: docs/user/docs/panadapter-controls.md (Band plan overlay). No CHANGELOG.md entry.
• Security-sensitive changes reference a GHSA if applicable — n/a

Not in scope: IARU Region 2 and 3, ARRL (US) and RAC (Canada) are governed by their own charts and get no usage yet. They fall back to today's behaviour.

73,
Ryan NF0T

---

👨🏼‍💻 Co-authored by Claude Opus 5.5

🤖 Generated with Claude Code