Add rtl88x2eu Spectrum Scanner screen (System > Receiver)

[Lupinixx]

Reimplements tipoman9/Spectrum's 8812eu.py channel-utilization scanner in C/C++ (no Python/pip dependency) as a native LVGL screen, for GS-side rtl88x2eu-family USB WiFi adapters used for the video link.

What's new

• src/spectrum_scanner.{hpp,cpp} — background scanner:

  • Enumerates /proc/net/rtl*/<iface>/chan_info (any rtl88x2eu-family adapter exposing it).
  • Drives iw <iface> scan passive via fork/execlp (no shell, no Python).
  • Maps channel → frequency via iw dev <iface> info + iw phy <phy> info.
  • Each discovered adapter gets its own scan thread, so one adapter's multi-second scan round doesn't freeze another adapter's display.
  • Re-reads chan_info every ~150ms while a scan is in flight, so channels update progressively as the radio visits them (matching how a full passive scan is inherently sequential per-channel) instead of only refreshing once the whole scan finishes.
  • Exposes a thread-safe snapshot API (spectrum_scanner_snapshot()) — the caller always gets a copy, never a pointer into data the worker thread could mutate concurrently.

• src/gsmenu/spectrum_screen.{h,c} — a dedicated full-screen LVGL view, reached from System → Receiver → Spectrum Scanner:

  • Single-screen, no-scroll bar graph — the GS only has a 4-way joystick, so nothing here requires scrolling.
  • 5GHz channels only (2.4GHz is rarely usable for FPV video and was dropped to keep every channel visible at once).
  • One color-coded bar per channel (green/yellow/red by utilization%), plus a small quality-tier dot and the channel's frequency.
  • A "recommended channel" line (lowest utilization, tie-broken by highest quality).
  • "Next Adapter" button to cycle between multiple rtl88x2eu-family cards.

Testing

• Standalone compiles of the new files (gcc/g++) and full cmake --build (both -DUSE_SIMULATOR=ON and the real target's LIB_SOURCE_FILES list).
• Live runs in the SDL simulator (SDL_VIDEODRIVER=x11 + synthetic xdotool keypresses) navigating System → Receiver → Spectrum Scanner — stable across the empty-adapter state and general navigation.
• Iterated on layout/behavior against a real rtl88x2eu adapter (wlxdc840328d590) on an actual ground station with feedback from screenshots.

[qodo-free-for-open-source-projects]

PR Summary by Qodo

Add Native rtl88x2eu Spectrum Scanner Screen

✨ Enhancement 🐞 Bug fix 🕐 40+ Minutes

AI Description

• Adds native multi-adapter rtl88x2eu channel-utilization scanning without Python dependencies.
• Adds a joystick-friendly 5GHz LVGL graph with recommendations and adapter switching.
• Integrates navigation and updates LVGL for simulator keypad safety.

Diagram

graph TD
  MENU["Receiver Menu"] -->|opens| SCREEN["Spectrum Screen"] -->|start and snapshot| API["Scanner API"] -->|manages| SUP["Worker Supervisor"] -->|spawns| WORKERS["Adapter Workers"] -->|executes| IW["iw Utility"] -->|scans| DRIVER["Realtek Driver"] -->|publishes| PROC["/proc chan_info"]
  WORKERS -->|reads| PROC
  WORKERS -->|publishes copies| API

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Direct nl80211 integration

• ➕ Avoids spawning and monitoring external iw processes
• ➕ Provides structured scan events instead of parsing command output
• ➕ Could offer tighter cancellation and error reporting
• ➖ Adds libnl or custom netlink implementation complexity
• ➖ Still requires parsing the driver-specific chan_info interface
• ➖ Increases dependency and compatibility burden for embedded targets

2. Standalone scanner daemon

• ➕ Isolates scanning privileges and process management from the LVGL application
• ➕ Allows scanner results to be reused by other consumers
• ➖ Introduces IPC, service packaging, and deployment complexity
• ➖ Complicates screen-driven start and stop behavior
• ➖ Is excessive for a single local UI consumer

Recommendation: Keep the in-process scanner and direct iw execution for this scoped embedded feature: it removes Python without introducing another library or service, while per-interface workers preserve responsiveness. Direct nl80211 would become preferable only if scanning expands into a shared subsystem or stronger cancellation and structured error handling justify the added complexity.

Files changed (8) +763 / -2

Enhancement (6) +754 / -1

colmenu_pages.cAdd Spectrum Scanner receiver menu action +16/-1

Add Spectrum Scanner receiver menu action

• Adds the Spectrum Scanner under System → Receiver. The action switches screens, preserves the previous input group, and focuses the scanner controls.

src/gsmenu/colmenu_pages.c

spectrum_screen.cImplement the LVGL spectrum visualization +300/-0

Implement the LVGL spectrum visualization

• Introduces a no-scroll 5GHz utilization graph with quality indicators, frequency labels, best-channel recommendations, empty states, and multi-adapter switching. Screen lifecycle callbacks start and stop scanning while a timer refreshes thread-safe snapshots.

src/gsmenu/spectrum_screen.c

spectrum_screen.hDeclare the spectrum screen initializer +14/-0

Declare the spectrum screen initializer

• Defines the C-compatible initialization entry point for constructing the dedicated LVGL screen.

src/gsmenu/spectrum_screen.h

menu.cCreate the dedicated spectrum screen +6/-0

Create the dedicated spectrum screen

• Declares and initializes the Spectrum Scanner as a standalone LVGL screen alongside DVR and TX Profiles.

src/menu.c

spectrum_scanner.cppImplement concurrent Realtek spectrum scanning +367/-0

Implement concurrent Realtek spectrum scanning

• Discovers compatible procfs interfaces, resolves channel frequencies through iw, and runs one progressive passive-scan worker per adapter. A hotplug supervisor manages workers while mutex-protected state is copied through the public snapshot API.

src/spectrum_scanner.cpp

spectrum_scanner.hppDefine the scanner data model and C API +51/-0

Define the scanner data model and C API

• Defines bounded interface and channel snapshot structures plus idempotent scanner lifecycle and thread-safe snapshot functions for C callers.

src/spectrum_scanner.hpp

Other (2) +9 / -1

CMakeLists.txtBuild spectrum scanner for simulator and target +8/-0

Build spectrum scanner for simulator and target

• Adds the scanner backend and LVGL screen sources to both simulator and target source lists.

CMakeLists.txt

lvglAdvance LVGL to simulator keypad safety fix +1/-1

Advance LVGL to simulator keypad safety fix

• Updates the LVGL submodule revision to include a NULL driver-data guard in the SDL keyboard handler, preventing crashes with the application's custom keypad input device.

lvgl

[qodo-free-for-open-source-projects]

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📎 Requirement gaps (0) 🎨 UX issues (0) 🔗 Cross-repo conflicts (0) 📜 Skill insights (0)

1. The first channel never appears ✓ Resolved 🐞 Bug ≡ Correctness

Description

parse_chan_info consumes the first numeric row with the break in its header-detection loop
before the row-parsing loop starts. Every valid report loses its first channel, so that channel is
absent from the graph and cannot be selected as the recommendation, while a single-row report
appears empty.

Code

src/spectrum_scanner.cpp[160]

+        break;  /* row parsing continues below, after the header line */

Evidence

The documented format places channel rows immediately after the Index header. Header detection
continues after finding that header, and the next iteration reads and discards the first row at
break; only subsequent lines reach the parser and then the UI's filter and recommendation logic.

src/spectrum_scanner.cpp[130-166]
src/gsmenu/spectrum_screen.c[168-193]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`parse_chan_info` consumes and discards the first data row after the `Index` header before entering its row-parsing loop.
## Fix Focus Areas
- src/spectrum_scanner.cpp[145-166]
## Recommended Fix
Break out of the header-search loop immediately when the `Index` header is found, so the following `getline` in the row-parsing loop reads the first numeric channel row. Add parser coverage for both single-row and multi-row reports.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

2. Closing the scanner leaves scans running ✓ Resolved 🐞 Bug ☼ Reliability

Description

run_iface exits its polling loop when either running flag is cleared without terminating or
reaping the active scan_pid. Closing the screen or unplugging an adapter can therefore leave iw
scanning after shutdown and later leave an unreaped child, while reopening can launch an overlapping
scan for the same radio.

Code

src/spectrum_scanner.cpp[R284-286]

+            waited_pid = waitpid(scan_pid, &status, WNOHANG);
+            if (waited_pid == 0) std::this_thread::sleep_for(std::chrono::milliseconds(150));
+        } while (waited_pid == 0 && iface_running->load() && g_running.load());

Evidence

The scan PID exists only as a local variable, and the sole wait is nonblocking inside a loop
conditioned on the worker flags. Both screen unload and hotplug clear those flags and join only the
worker thread, with no child cleanup before a later start may create another worker.

src/spectrum_scanner.cpp[227-239]
src/spectrum_scanner.cpp[268-293]
src/spectrum_scanner.cpp[303-346]
src/gsmenu/spectrum_screen.c[214-225]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
Worker shutdown abandons an in-flight `iw scan passive` child because the polling loop exits without terminating or reaping its PID.
## Fix Focus Areas
- src/spectrum_scanner.cpp[268-293]
- src/spectrum_scanner.cpp[303-333]
## Recommended Fix
Ensure every scan PID is reaped on every exit path. When shutdown or interface removal interrupts an active scan, terminate the child, escalate after a bounded timeout if necessary, and call `waitpid` before allowing the worker to finish.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

3. Scan failures trigger a process storm ✓ Resolved 🐞 Bug ☼ Reliability

Description

run_iface immediately starts another iteration after a fork failure or a child that exits promptly
because the outer loop has no failure delay. A missing iw executable, rejected scan, unavailable
radio, or transient fork failure consequently makes every adapter repeatedly fork and parse as fast
as the system permits.

Code

src/spectrum_scanner.cpp[R283-286]

+            if (scan_pid < 0) break;  /* fork failed; still show whatever chan_info has */
+            waited_pid = waitpid(scan_pid, &status, WNOHANG);
+            if (waited_pid == 0) std::this_thread::sleep_for(std::chrono::milliseconds(150));
+        } while (waited_pid == 0 && iface_running->load() && g_running.load());

Evidence

A fork failure breaks only the inner polling loop, after which the still-true outer loop immediately
calls start_scan_async again. Prompt child failures are reaped by waitpid and follow the same
immediate restart path because no status check or delay exists between rounds.

src/spectrum_scanner.cpp[227-239]
src/spectrum_scanner.cpp[265-287]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
Failed or immediately rejected scan attempts return directly to the unthrottled outer loop, causing rapid process creation and file parsing.
## Fix Focus Areas
- src/spectrum_scanner.cpp[268-287]
## Recommended Fix
Inspect fork and child exit results and apply an interruptible bounded backoff after failures, including executable-not-found and nonzero scan exits. Keep shutdown responsive by checking both running flags during the delay, and reset the backoff after a normal scan round.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

Tip of the day

💡 Did you know, you can group findings by type and pick your Finding display, from Minimal to Full

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗

[Lupinixx]

WIN_20260915_21_47_36_Pro.mp4

Reference video, while running the scan starting a speedtest on my phone.