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: