diff --git a/doc/hardware.md b/doc/hardware.md index 814fec29..f794e20e 100644 --- a/doc/hardware.md +++ b/doc/hardware.md @@ -3,6 +3,56 @@ The hardware infomation and status is handled by the YANG model [IETF hardware][1], with deviations and augmentations in _infix-hardware_. +## GPS/GNSS Receivers + +Infix supports GPS/GNSS receivers for hardware status monitoring and NTP +time synchronization. USB GPS receivers using the USB ACM interface are +supported (e.g., u-blox). When connected, devices are automatically +discovered and named `gps0`, `gps1`, etc. + +### Current status + +
admin@example:/> show hardware
+HARDWARE COMPONENTS
+──────────────────────────────────────────────────────────────
+GPS/GNSS Receivers
+Name : gps0
+Device : /dev/gps0
+Driver : u-blox
+Status : Active
+Fix : 3D
+Satellites : 10/15 (used/visible)
+Position : 59.334567N 18.063456E 42.3m
+PPS : Available
+
+
+Available information per receiver:
+
+| Field | Description |
+|------------|---------------------------------------------------|
+| Name | Component name (`gps0`, `gps1`, ...) |
+| Device | Device path (`/dev/gps0`) |
+| Driver | Protocol driver (e.g., `u-blox`, `NMEA`, `SiRF`) |
+| Status | `Active` or `Inactive` |
+| Fix | `NONE`, `2D`, or `3D` |
+| Satellites | Used/visible count |
+| Position | Latitude, longitude, altitude (when fix acquired) |
+| PPS | Pulse Per Second signal availability |
+
+### Configure GPS receiver
+
+GPS receivers are hardware components with class `gps`. The class is
+auto-inferred from the component name, similar to WiFi radios (`radioN`):
+
+admin@example:/> configure
+admin@example:/config/> set hardware component gps0
+admin@example:/config/> leave
+
+
+To use a GPS receiver as an NTP reference clock source, see
+[NTP — GPS Reference Clock](ntp.md#gps-reference-clock).
+
+
## USB Ports
For Infix to be able to control USB port(s), a device tree modification
diff --git a/doc/ntp.md b/doc/ntp.md
index 67ea2bbc..100e955e 100644
--- a/doc/ntp.md
+++ b/doc/ntp.md
@@ -28,6 +28,70 @@ admin@example:/config/ntp/> set refclock-master master-stratum 10
admin@example:/config/ntp/> leave
+## GPS Reference Clock
+
+A GPS/GNSS receiver can be used as an NTP reference clock source,
+providing stratum 1 time derived from the GPS satellite constellation.
+This requires a GPS hardware component to be configured first, see
+[Hardware — GPS/GNSS Receivers](hardware.md#gpsgnss-receivers).
+
+### Basic setup
+
+Add a GPS receiver as a reference clock source:
+
+admin@example:/config/> edit ntp
+admin@example:/config/ntp/> edit refclock-master source gps0
+admin@example:/config/ntp/refclock-master/source/gps0/> set poll 2
+admin@example:/config/ntp/refclock-master/source/gps0/> set precision 0.1
+admin@example:/config/ntp/refclock-master/source/gps0/> end
+admin@example:/config/ntp/> leave
+
+
+Tunable parameters:
+
+| Parameter | Default | Description |
+|-------------|--------:|----------------------------------------------------|
+| `poll` | `2` | Polling interval in log2 seconds (2 = 4s) |
+| `precision` | `0.1` | Assumed precision in seconds (0.1 = 100ms) |
+| `refid` | `"GPS"`| Reference identifier (e.g., `GPS`, `GNSS`, `GLO`) |
+| `prefer` | `false` | Prefer this source over other reference clocks |
+| `pps` | `false` | Enable PPS for microsecond-level accuracy |
+| `offset` | `0.0` | Constant offset correction in seconds |
+| `delay` | `0.0` | Assumed maximum delay from the receiver |
+
+### PPS (Pulse Per Second)
+
+When the GPS receiver provides a PPS signal, enable the `pps` option for
+microsecond-level accuracy. With PPS, the GPS time provides the initial
+lock and the PPS edges discipline the clock:
+
+admin@example:/config/ntp/> edit refclock-master source gps0
+admin@example:/config/ntp/refclock-master/source/gps0/> set pps true
+admin@example:/config/ntp/refclock-master/source/gps0/> set precision 0.000001
+admin@example:/config/ntp/refclock-master/source/gps0/> end
+admin@example:/config/ntp/> leave
+
+
+### Monitoring
+
+The `show ntp` command shows the GPS receiver as the reference clock source:
+
+admin@example:/> show ntp
+Mode : Server (GPS reference clock: gps0)
+Port : 123
+Stratum : 1
+Ref time (UTC) : Sun Feb 08 19:44:36 2026
+
+
+Use `show ntp source` to see GPS reference clock details:
+
+admin@example:/> show ntp source
+Reference Clock : gps0 (u-blox)
+Status : selected
+Fix Mode : 3D
+Satellites : 9/17 (used/visible)
+
+
## Server Mode
Synchronize from upstream NTP servers while serving time to clients: