ChroGPS Dash is engineered with a “zero-dependency” philosophy, ensuring maximum performance and long-term maintainability. This page details the internal architecture, data processing logic, and technical design decisions that power the dashboard.

Architecture Overview

ChroGPS Dash is a 100% self-contained application, packaged as a single index.php file. This includes all backend logic, CSS (supporting 21 themes), and frontend JavaScript.

• Backend: Pure PHP (8.2+).
• Frontend: Vanilla JavaScript (ES6+) and CSS3.
• Dependencies: None. No external charting libraries (e.g., Chart.js), no external fonts (Google Fonts), and no trackers.
• Minification: Built-in server-side minifier that strips whitespace and comments from the HTML/CSS/JS buffer before it is sent to the client, reducing payload size by ~27%.

Data Acquisition & Processing

The dashboard interacts with system services using a combination of low-level sockets and command-line utilities.

GPSd Interaction

Data is retrieved from gpsd via a JSON-RPC socket connection (localhost:2947). The dashboard uses the ?WATCH and ?POLL commands to gather:

• SKY/TPV messages: For satellite positions (azimuth/elevation), signal strength (SNR), and time-position-velocity data.
• Satellite Batching: Logic is implemented to merge incremental SKY messages into a complete GNSS epoch, preventing “ghosting” when receivers report constellations in staggered batches.
• Persistent Cache: A local JSON cache (/var/tmp/cgpsd-sat-cache.json) preserves satellite metadata across connections to maintain a stable skyview.

Chrony Integration

NTP metrics are gathered using chronyc commands (executed via sudo with scoped permissions):

• chronyc tracking: For core sync metrics (Offset, RMS Offset, Frequency).
• chronyc sources: For real-time peer status and reachability.
• chronyc serverstats: For infrastructure monitoring.
• Configuration Parsing: The dashboard directly parses /etc/chrony/chrony.conf to display active maxdrift, makestep, and refclock directives.

Performance Algorithms

Efficient Log Traversal (Binary Search)

To handle 24-hour history windows without significant CPU or memory overhead, ChroGPS Dash uses a specialized Binary Search algorithm on its log files.

• O(log n) Seeks: Instead of reading full log files (which can grow to thousands of lines), the engine “seeks” to the exact timestamp cutoff.
• Convergence: The algorithm typically finds the correct starting point in ~20 iterations, regardless of log file size.

Custom SVG Graphing Engine

Graphs are generated entirely on the server as raw SVG paths. This eliminates the need for heavy client-side JavaScript libraries.

• Dual-Axis Support: Allows simultaneous plotting of unrelated metrics (e.g., Offset vs. Frequency).
• Automatic Scaling: The engine automatically scales units (ns → µs → ms → s) based on the data range.
• Subtle Fills & Zero-Lines: Dynamic detection of zero-crossings for accurate visual representation of offset drift.

Internal Logic & Heuristics

Antenna Health Score

A proprietary heuristic calculates a 0-100% “Signal Integrity” score.

• Logic: It analyzes the SNR (dBHz) of active satellites, applying weights based on signal strength.
• Noise Filtering: Low-horizon satellites (prone to multipath interference) are automatically filtered out to ensure the score reflects the actual quality of the antenna installation.

Sync Precision Score

A logarithmic score that quantifies server timing quality. It normalizes the range from sub-microsecond PPS (Pulse-Per-Second) precision to standard millisecond-level WAN peer synchronization.

Solar Tracking

Calculates the Sun’s current Azimuth and Elevation using pure client-side JavaScript. This allows users to correlate SNR drops with solar interference (e.g., the sun passing behind a satellite) without external API dependencies.

Security & Operations

• Admin Panel: Token-protected configuration management.
• Pi Throttling Diagnostics: For Raspberry Pi hardware, the dashboard performs deep bitmask parsing of vcgencmd get_throttled. This distinguishes between current issues (Under-voltage, Throttling) and historical events that occurred since the last boot - critical for diagnosing frequency instability in Stratum 1 environments.
• One-Click Updates: Real-time progress streaming using Server-Sent Events (SSE) and atomic file replacement.
• Privacy: Optional IP masking for connected NTP clients (masking octets of IPv4 and hextets of IPv6).
• Binary Utilities: Uses scoped helper scripts in /usr/local/bin/ to allow the web user (www-data) to restart services or purge logs safely without full root access. me progress streaming using Server-Sent Events (SSE) and atomic file replacement.
• Privacy: Optional IP masking for connected NTP clients (masking octets of IPv4 and hextets of IPv6).
• Binary Utilities: Uses scoped helper scripts in /usr/local/bin/ to allow the web user (www-data) to restart services or purge logs safely without full root access.