GPSDO Time

This repository is experimental and the focus/purpose of this tool may change with time. Currently there is a desire to support a local NTP service that may also offer other time-base protocols for different interfaces such as BLE.

This project is designed around the use of a GPSDO from Leo-Bodnar that supports PPS via the Virtual-COM's DTR signal. Support for other GPS hardware may be supported in the future (at the expense of precise time tracking).

Description

A cross-platform CLI/TUI for displaying sub-microsecond precise UTC time from a GPS-Disciplined Oscillator (GPSDO) over a serial port. The tool reads NMEA sentences and PPS (pulse-per-second) signals to combine whole-second GPS time with high-resolution stopwatch offsets, delivering precise time information.

Checklist / Features

• Built on .NET 10 for cross-platform support.
• CLI supported
  • One-shot mode: waits for GPS lock, prints time/position/satellites/NMEA, then exits. Ideal for scripting.
  • Normal-style and JSON-style output for human readability and tool integration.
• Text-UI (TUI) supported
  • Full-screen interactive display at ~66fps with toggleable panels.
• Sub-microsecond time precision
  • Combines NMEA time-of-day with high-resolution PPS edge timestamps via Stopwatch.GetTimestamp().
• PPS statistics
  • Windowed (16-sample) average plus all-time min/max/mean PPS period error.
• NMEA sentence parsing
  • RMC, GGA, GLL, GSA, VTG, GSV sentences with checksum validation.
• Satellite constellation display
  • Per-satellite PRN, elevation, azimuth, and SNR from GSV sentences.
• Privacy redaction mode
  • --redact flag masks position-sensitive fields in both the TUI and NMEA log.
• JSON output
  • Structured JSON for easy integration with other tooling.
• Automatic port discovery
  • When --com is omitted, a selection prompt lists available serial ports with device descriptions (WMI on Windows, sysfs on Linux).

Software Requirements

Windows

• .NET 10 SDK
  • winget install Microsoft.DotNet.SDK.10
    • NOTE: A system reboot is recommended after install.

Linux

• .NET 10 SDK
  • sudo apt install dotnet-sdk-10.0
• User-level serial port access typically requires adding your user to the dialout group:

sudo usermod -aG dialout $USER

Then log out and back in for the change to take effect.

Hardware Requirements

A GPS-Disciplined Oscillator (GPSDO) or GPS module that provides:

• NMEA output over a serial (UART/USB-serial) connection.
• PPS signal exposed on the serial port's DCD (Data Carrier Detect) pin.

The PPS signal on the DCD line is required for sub-microsecond time precision. Without it, only NMEA-level (1-second) time resolution is available.

Initial Setup

Clone the repository:

git clone https://github.com/jjcarrier/gpsdo-time.git
cd gpsdo-time

Build the project:

dotnet build

Run the following command for help documentation:

gpsdo-time --help

CLI Options

Option	Description
--com	Serial port name (e.g. COM20, /dev/ttyUSB0). If omitted, an interactive selection prompt is shown.
--baud	Baud rate (default: 115200).
--pos	Include position info in output.
--sat	Include satellite info in output.
--nmea	Include raw NMEA sentences in output.
--interactive, -i	Launch the interactive TUI instead of one-shot output.
--json	Output as JSON (one-shot mode only).
--redact	Redact sensitive location information.

CLI Examples

One-Shot Time Query

Wait for a GPS lock and print the current precise UTC time, then exit:

gpsdo-time --com COM20

One-Shot with Position and Satellites (JSON)

gpsdo-time --com COM20 --pos --sat --json

{"time":"2026-04-19T12:34:56.0001234Z","position":{"fix":"GPS (3D)","fixMode":"3D","latitude":0.0,"longitude":0.0,"altitude":0.0,"satellites":12,"pdop":1.6,"hdop":0.8,"vdop":1.4},"satellites":[...]}

One-Shot with NMEA Dump

Print the precise time along with the raw NMEA sentences received:

gpsdo-time --com COM20 --nmea

Interactive Mode (TUI)

A full-featured text user interface is available via the --interactive option:

gpsdo-time --interactive

TUI Panels

The TUI is composed of several panels that can be toggled via keyboard:

Panel	Description
Time	Always visible. Shows UTC Date, UTC Time, SYS Time, SYS Error (µs), PPS Error (µs), and windowed PPS error.
Positioning Info	GPS fix status, quality, latitude, longitude, altitude, speed, course, satellite count, and DOP values.
Satellites In View	Per-satellite table with constellation (GPS/GLO/etc.), PRN, elevation, azimuth, and SNR.
NMEA Log	Auto-scrolling log of raw NMEA sentences received from the device.

Keyboard Controls

Key	Action
p	Toggle positioning info panel
s	Toggle satellite info panel
n	Toggle NMEA log panel
r	Toggle redaction of location data
?	Show/hide help overlay
q	Quit

License

Copyright © Jon Carrier

This project is licensed under the MIT license. For more details please refer to LICENSE. This software depends on the following third party components:

• Spectre.Console (https://github.com/spectreconsole/spectre.console/blob/main/LICENSE.md)