doc: add section on GPS receivers and GPS reference clock

Signed-off-by: Joachim Wiberg <troglobit@gmail.com>

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
+
+<pre class="cli"><code>admin@example:/> <b>show hardware</b>
+<span class="header">HARDWARE COMPONENTS                                           </span>
+──────────────────────────────────────────────────────────────
+<span class="title">GPS/GNSS Receivers                                           </span>
+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
+</code></pre>
+
+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`):
+
+<pre class="cli"><code>admin@example:/> <b>configure</b>
+admin@example:/config/> <b>set hardware component gps0</b>
+admin@example:/config/> <b>leave</b>
+</code></pre>
+
+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

doc/ntp.md

@@ -28,6 +28,70 @@ admin@example:/config/ntp/> <b>set refclock-master master-stratum 10</b>
 admin@example:/config/ntp/> <b>leave</b>
 </code></pre>
 
+## 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:
+
+<pre class="cli"><code>admin@example:/config/> <b>edit ntp</b>
+admin@example:/config/ntp/> <b>edit refclock-master source gps0</b>
+admin@example:/config/ntp/refclock-master/source/gps0/> <b>set poll 2</b>
+admin@example:/config/ntp/refclock-master/source/gps0/> <b>set precision 0.1</b>
+admin@example:/config/ntp/refclock-master/source/gps0/> <b>end</b>
+admin@example:/config/ntp/> <b>leave</b>
+</code></pre>
+
+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:
+
+<pre class="cli"><code>admin@example:/config/ntp/> <b>edit refclock-master source gps0</b>
+admin@example:/config/ntp/refclock-master/source/gps0/> <b>set pps true</b>
+admin@example:/config/ntp/refclock-master/source/gps0/> <b>set precision 0.000001</b>
+admin@example:/config/ntp/refclock-master/source/gps0/> <b>end</b>
+admin@example:/config/ntp/> <b>leave</b>
+</code></pre>
+
+### Monitoring
+
+The `show ntp` command shows the GPS receiver as the reference clock source:
+
+<pre class="cli"><code>admin@example:/> <b>show ntp</b>
+Mode                : Server (GPS reference clock: gps0)
+Port                : 123
+Stratum             : 1
+Ref time (UTC)      : Sun Feb 08 19:44:36 2026
+</code></pre>
+
+Use `show ntp source` to see GPS reference clock details:
+
+<pre class="cli"><code>admin@example:/> <b>show ntp source</b>
+Reference Clock     : gps0 (u-blox)
+Status              : selected
+Fix Mode            : 3D
+Satellites          : 9/17 (used/visible)
+</code></pre>
+
 ## Server Mode
 
 Synchronize from upstream NTP servers while serving time to clients: