# PPS Clock Discipline

## 1. Synopsis

    Name: pps
    Reference ID: PPS
    Driver ID: PPS
    Serial or Parallel Port: /dev/ppsu
    Requires: PPSAPI Interface for Precision Time Signals

## 2. Description

This driver furnishes an interface for the pulse-per-second (PPS) signal produced by a cesium clock, radio clock or related devices. It can be used to augment the serial timecode generated by a GPS receiver, for example. It can be used to remove accumulated jitter and re-time a secondary server when synchronized to a primary server over a congested, wide-area network and before redistributing the time to local clients. The driver includes extensive signal sanity checks and grooming algorithms. A range gate and frequency discriminator reject noise and signals with incorrect frequency. A multiple-stage median filter rejects jitter due to hardware interrupt and operating system latencies. A trimmed-mean algorithm determines the best time samples. With typical workstations and processing loads, the incidental jitter can be reduced to a few microseconds.

While this driver can discipline the time and frequency relative to the PPS source, it cannot number the seconds. For this purpose an auxiliary source is required; ordinarily a radio clock operated as a primary reference (stratum 1) source; however, another NTP time server can be used as well. For this purpose, the auxiliary source must be specified as the prefer peer, as described in the Mitigation Rules and the `prefer` Keyword page.

The driver requires the PPSAPI interface, which is documented in RFC 2783. The interface consists of the `timepps.h` header file and associated kernel support. Support for this interface is included in current versions of Solaris, FreeBSD, and Linux. See the Pulse-Per-second (PPS) Signal Interfacing page for further information.

The PPS source can be connected via a serial or parallel port, depending on the hardware and operating system. A serial port can be dedicated to the PPS source or shared with another device; however, if dedicated the data leads should not be connected, as noise or unexpected signals can cause `ntpd` to exit.

A radio clock is usually connected via a serial port and the PPS source connected via a level converter to the data carrier detect (DCD) pin (DB-9 pin 1, DB-25 pin 8) of the same connector. In some systems where a parallel port and driver are available, the PPS signal can be connected directly to the ACK pin (DB25 pin 10) of the connector. Whether the PPS signal is connected via a dedicated port or shared with another device, the driver opens the device `/dev/pps%d`, where `%d` is the unit number. As with other drivers, links can be used to redirect the logical name to the actual physical device.

The driver normally operates like any other driver and uses the same mitigation algorithms and PLL/FLL clock discipline incorporated in the daemon. If kernel PLL/FLL support is available, the kernel PLL/FLL clock discipline can be used instead. The default behavior is not to use the kernel PPS clock discipline, even if present. This driver incorporates a good deal of signal processing to reduce jitter using the median filter algorithm in the driver. As the result, performance with `minpoll` configured at 4 (16 s) is generally better than the kernel PPS discipline. However, the `flag 3` option can be used to enable the kernel PPS discipline if necessary.

This driver is enabled only under one of two conditions (a) a prefer peer other than this driver is among the survivors of the mitigation algorithms or (b) there are no survivors and the `minsane` option of the `tos` command is 0. In typical usage, the prefer peer designates another source that can reliably number the seconds when available.

A scenario where the latter behavior can be most useful is a planetary orbiter fleet, for instance in the vicinity of Mars, where contact between orbiters and Earth occurs only one or two times per Sol (Mars day). These orbiters have a precise timing reference based on an Ultra Stable Oscillator (USO) with accuracy on the order of a Cesium oscillator. A PPS signal is derived from the USO and can be disciplined from Earth on rare occasion or from another orbiter via NTP. In the above scenario the PPS signal disciplines the spacecraft clock between NTP updates.

In a similar scenario a PPS signal can be used to discipline the clock between updates produced by the modem driver. This would provide precise synchronization without needing the Internet at all.

## 3. Driver Options

`unit` number

  The driver unit number, defaulting to 0. Used as a distinguishing suffix in the driver device name.

`time1` time

  Specifies the time offset calibration factor, in seconds and fraction, with default 0.0.

`time2` time

  Not used by this driver.

`stratum` number

  Specifies the driver stratum, in decimal from 0 to 15, with default 0.

`refid` string

  Specifies the driver reference identifier, an ASCII string from one to four characters, with default `PPS`.

`flag1 {0 | 1}`

  Not used by this driver.

`flag2 {0 | 1}`

  Specifies PPS capture on the rising (assert) pulse edge if 0 (default) or falling (clear) pulse edge if 1.

`flag3 {0 | 1}`

  Controls the kernel PPS discipline: 0 for disable (default), 1 for enable.

`flag4 {0 | 1}`

  Record a timestamp once for each second if 1. Useful for constructing Allan deviation plots.

`subtype`

  Not used by this driver.

`mode`

  Not used by this driver.

`path`

  Not used by this driver.

`ppspath`

  Overrides the default PPS device path.

`baud` number

  Not used by this driver.

## 4. Configuration Example

    refclock pps unit 0 flag2 1	# Capture PPS on trailing edge of pps0

This driver does not need to be configured explicitly in order to be active; thus no "refclock pps" is required unless you need to set a driver option. It is initialized by whatever other driver is using it, which will be one of generic, nmea, or spectracom.

## 5. Clockstats

If clockstats is enabled, the driver will log a few counters. Examples:

    57378 3313.351 PPS(0) 423681 64 0 0 0
    57378 3377.352 PPS(0) 423745 64 0 0 0
    57378 3441.352 PPS(0) 423809 64 0 0 0
    57378 3505.351 PPS(0) 423873 64 0 0 0

Table 1. Clockstats
Column | Sample | Meaning
--- | --- | ---
1 | 57378 | MJD
2 | 3505.351 | Time of day in seconds
3 | PPS(0) | Clock identification
4 | 423873 | Total number of PPS pulses the kernel has seen
5 | 64 | Number of PPS pulses the driver processed This should be the difference between col 4 and col 4 from the previous line
6 | 0 | ntpd doesn’t know the time yet
7 | 0 | Error from Kernel
8 | 0 | Number of times there was no pulse ready

The clock identification is normally the driver type and unit, but if your ntpd was built in strict Classic compatibility mode it will be a magic clock address expressing the same information in a more opaque way.

## 6. Additional Information

Reference Clock Drivers

## 7. Reference

RFC 2783

  Mogul, J., D. Mills, J. Brittenson, J. Stone and U. Windl, Pulse-Per-Second API for Unix-like Operating Systems, Version 1.0, RFC 2783

## 8. Author

David L. Mills <mills@udel.edu>

Home Page | Site Map | Contacts