NmeaClient/conversation_recap.md

GNSS Monitor GUI — Conversation Recap

Date: 2026-05-24

Goal

Build a PyQt5 frontend (gui/) on top of the existing nmea_client pipeline (NetworkBackend / Transceiver / NmeaPacketizer / UbxPacketizer) with three tabs: Connection, Sky, Plot.

---

Files Created

File	Purpose
gui/main.py	QApplication, MainWindow, QTabWidget with 3 tabs
gui/data_model.py	ReceiverManager (QObject), SatelliteData, ConnectionConfig, GNSS constants, LRU persistence
gui/listeners.py	NavSatQtListener (UBX NAV-SAT → SatelliteData), GsaQtListener (NMEA GSA → pDOP)
gui/backends.py	SerialBackend (ABackend over pyserial)
gui/connection_tab.py	ConnectionTab + ConnectionRow, TCP/serial config, LRU history combo
gui/sky_widget.py	SkyPlotWidget — off-thread QPainter renderer via SkyRenderThread
gui/sky_tab.py	SkyTab — sky plot + satellite table + source selector + info bar + trails
gui/plot_widget.py	SinglePlotWidget — custom QPainter canvas, 6 y-axis modes, settings persistence
gui/plot_tab.py	PlotTab — 8 SinglePlotWidgets in a 2-column scrollable grid

---

Connection Tab

• Each row: ID field, TCP/Serial switcher (QStackedWidget), host/port or serial/baud fields, status dot, Connect/Disconnect, Remove
• LRU history combo bottom-left, Add button next to it — user picks from history then hits Add
• Host field accepts both IP addresses and hostnames
• LRU persisted to ~/.nmea_client_gui.json (max 20 entries)

---

Sky Tab

• Sky plot: polar projection, concentric rings at 0°/30°/60°, cardinal labels, satellites sized by C/N₀, filled = used in fix, dashed outline = not used
• Off-thread rendering: SkyRenderThread (QThread + Queue(maxsize=1)) renders to QImage; paintEvent does only drawImage — main thread never blocks
• Trails: per-satellite deque(maxlen=86400) (24 h at 1 Hz); global Show Trails checkbox + depth spinbox (0–24 h); subsampled to ≤120 points in render thread; alpha fades 15→200 oldest→newest
• Satellite table: columns GNSS / SV / Elev° / Az° / C/N₀ / Fix / Receiver / Msg; sorted by GNSS then SV; in-place cell updates preserve scroll position; full rebuild only when satellite set changes
• Msg column: fixed 36 px width; shows ✓ for _MSG_HIGHLIGHT_MS = 10 000 ms after a message is received; clears and evicts satellite from store/sky when timer fires (not seen for 10 s)
• Info bar: one card per receiver showing pDOP / Visible / Used counts
• Source selector: per-receiver checkboxes to include/exclude from plot and table

---

Plot Tab

• 8 independent plots, 2-column scrollable layout
• Y-axis modes: C/N₀, Azimuth, Elevation (satellite-specific); pDOP, Visible Sats, Used Sats (global/per-receiver)
• Off-thread rendering: same QThread+QImage pattern as sky widget
• Custom QPainter canvas: grid, axis ticks, curves, legend — no pyqtgraph dependency
• _nice_ticks(lo, hi): math.floor for first tick (≤ lo), math.ceil for last tick (≥ hi), with 5 % padding
• Settings persistence: y-axis mode, satellite selection, point count saved to ~/.nmea_client_plots.json keyed by plot index 0–7
• Right-click context menu: Save as PNG, Copy to clipboard
• All GNSS sources default to checked (enabled)

---

Key Architectural Decisions

• Qt cross-thread safety: listener callbacks emit signals from backend threads; Qt queues delivery to main thread automatically — no explicit locking needed
• Off-thread rendering pattern: QPainter on QImage is thread-safe; Queue(maxsize=1) ensures only the latest data is rendered, stale frames discarded
• _GNSS_QCOLORS dict pre-built in main thread; render thread reads it as read-only
• In-place table cell updates: _table_keys list tracks row identity; setText only when structure unchanged; setRowCount/setSortingEnabled avoided to preserve scroll position

---

Notable Fixes & Iterations

Issue	Fix
Sky plot slow, table scrolling laggy	QTimer throttle (500 ms) + in-place cell updates + viewport().setUpdatesEnabled(False/True)
Y-axis clipping data at top	math.floor for first tick; loop extended to cover ceil of max
Plot satellite combo always empty	Source checkboxes defaulted to Qt.Checked
Msg column showing two sub-columns	QHeaderView.Fixed + explicit setColumnWidth
Row background highlight rejected	Replaced with dedicated Msg column + ✓ symbol
Host field rejecting hostnames	QLineEdit with setPlaceholderText instead of IP-only validator

---

GNSS Systems Supported

ID	Name	Short	Color
0	GPS	G	#2196F3 blue
1	SBAS	S	#9E9E9E gray
2	Galileo	E	#4CAF50 green
3	BeiDou	C	#FF9800 orange
4	IMES	I	#607D8B blue-gray
5	QZSS	J	#9C27B0 purple
6	GLONASS	R	#F44336 red
7	NavIC	N	#F4A0A0 rose