Generic Reference Driver

refclock_generic - multidevice parse driver for generic time radios and GPSDOs.

Most modes of this driver report only two-digit years, and are thus reliant on the system clock to be near correct before samples will be processed properly. You will not be able to use these modes to run autonomously, nor will they reliably recover from a trashed or zeroed system clock. The only exceptions are the Schweitzer 240x and the Trimble TAIP/TSIP modes.

The generic driver supports many different clock types/configurations by plugging type-specific packet-parsing routines into a generic driver framework.

Note that some of these subtypes below are to support equipment that has not been commercially available for a long time, report only 2-digit years (thus being subject to lingering Y2K problems and possible future issues near century boundaries), and may be removed in a future release. See Feature removals for a discussion of this issue.

The actual receiver status is mapped into various synchronization states generally used by receivers. The driver is configured to interpret the time codes of Meinberg DCF77 AM receivers, DCF77 FM receivers, Meinberg GPS16x/17x receivers, Trimble SV6 GPS, ELV DCF7000, Schmid, Wharton 400A and various low-cost receivers.

The reference clock support in NTP contains the necessary configuration tables for those receivers. In addition to supporting several different clock types and multiple devices, the processing of a PPS signal is also provided as a configuration option. The PPS configuration option uses the receiver-generated time stamps for feeding the PPS loopfilter control for much finer clock synchronization.

The use of the PPS option requires receivers with an accuracy of better than 1ms.

The ntpq program can read and display several clock variables. These hold the following information:

If PPS information is present, additional variables are available:

Twenty-five clock types are supported by the GENERIC driver and any number of these clocks may be operational at any one time.

Note: Under NTPsec, you must use the new configuration syntax (refclock generic subtype N) to declare generic clocks, rather than the old-style syntax with a magic address, unless the software has been built with the --enable-classic-mode option in which case only the old-style syntax will work.

A note on the implementations:

Actual data formats and setup requirements of the various clocks can be found in NTP GENERIC clock data formats.

The reference clock support software carefully monitors the state transitions of the receiver. All state changes and exceptional events (such as loss of time code transmission) are logged via the syslog facility. Every hour a summary of the accumulated times for the clock states is listed via syslog.

PPS support is only available when the receiver is completely synchronized. The receiver is believed to deliver correct time for an additional period of time after losing synchronization, unless a disruption in time code transmission is detected (possible power loss). The trust period is dependent on the receiver oscillator and thus is a function of clock type.

Raw DCF77 pulses can be fed via a level converter to the RXD pin of an RS-232 serial port (pin 3 of a 25-pin connector or pin 2 of a 9-pin connector). The telegrams are decoded and used for synchronization. DCF77 AM receivers can be bought for as little as $25. The accuracy is dependent on the receiver and is somewhere between 2 ms (expensive) and 10 ms (cheap). Synchronization ceases when reception of the DCF77 signal deteriorates, since no backup oscillator is available as usually found in other reference clock receivers. So it is important to have a good place for the DCF77 antenna. During transmitter shutdowns you are out of luck unless you have other NTP servers with alternate time sources available.

In addition to the PPS loopfilter control, a true PPS hardware signal can be utilized via the PPSAPI interface. PPS pulses are usually fed via a level converter to the DCD pin of an RS-232 serial port (pin 8 of a 25-pin connector or pin 1 of a 9-pin connector), where one edge of the pulse — often the leading edge, but in many cases not — provides the reference. NTPsec uses the edge of the pulse specified by the driver for the particular hardware used. To select PPS support, the subtype parameter is the subtype value as above plus 128. If 128 is not added to the subtype value, PPS will be detected to be available but will not be used.

For PPS to be used, add 128 to the subtype parameter.

If the PPS signal is fed in from a device different from the device providing the serial communication (/dev/refclock-\{0..3}), this device is configured as /dev/refclockpps-\{0..3}. This allows the PPS information to be fed in e.g. via the parallel port (if supported by the underlying operation system) and the date/time telegrams to be handled via the serial port.

Clock state statistics are written hourly to the syslog service. Online information can be found by examining the clock variables via the ntpq cv command.

Some devices have quite extensive additional information (GPS16x/GPS17x, Trimble). The driver reads out much of the internal GPS data and makes it accessible via clock variables. To find out about additional variable names, query for the clock_var_list variable on a specific clock association as shown below.

First let ntpq display the table of associations:

Then switch to raw output. This may be required because of display limitations in ntpq/ntpd - so large lists need to be retrieved in several queries.

Use the cv command to read the list of clock variables of a selected association:

The long output of the command above looks similar to:

Then use the cv command again to list selected clock variables. The following command must be entered as a single line:

The output of the command above is wrapped around depending on the screen width and looks similar to:

See the examples above under "Supported devices"

The generic clock mechanism deviates from the way other NTP reference clocks work. For a short description of how to build generic reference clocks, see making generic clocks.

Additional Information

Reference Clock Drivers