# NIST/USNO/PTB Modem Time Services

## 1. Synopsis

    Name: modem
    Reference ID: NIST | USNO | PTB | GPS
    Serial Port: /dev/modemu; 9600 8N1
    Features: tty_clk
    Requires: a dial-out device.

## 2. Warning

The ACTS and USNO modes of this driver report only two-digit years, and is thus reliant on the system clock to be near correct before samples will be processed properly. You will not be able to use it to run autonomously, nor will it reliably recover from a trashed or zeroed system clock.

## 3. Description

This driver supports the US (NIST and USNO) and European (PTB (Germany), NPL (UK), etc.) modem time services, as well as Spectracom GPS receivers connected via a modem. The driver periodically dials a number from a telephone list, receives the timecode data and calculates the local clock correction. It is designed primarily for backup when neither a radio clock nor connectivity to Internet time servers are available. It can also be configured to operate full period.

For best results the indicated time must be corrected for the modem and telephone circuit propagation delays, which can reach 200 ms or more. For the NIST service, corrections are determined automatically by measuring the roundtrip delay of echoed characters. With this service, the absolute accuracy is typically a millisecond or two. Determining corrections for the other services must be by other means. With these services variations from call to call and between messages during a call are typically a few milliseconds, occasionally higher.

This driver requires a 1200 bps or faster modem with a Hayes-compatible command set and control over the modem data terminal ready (DTR) control line. The actual line speed ranges from 1200 bps with USNO to 14,400 bps with NIST. The modem setup string is hard-coded in the driver and may require changes for nonstandard modems or special circumstances. It can be overridden by setting the extended system variable "modemsetup" via ntpq.

There are three modes of operation selected by the `mode` keyword in the `server` configuration command. In backup mode (0) `flag1` is set at each poll event, but only if no other synchronization sources are available. In auto mode (1) `flag1` is set at each poll event. In manual mode (2) the calling program is initiated by setting the `flag1` option. This can be done manually using `ntpq`, or by a cron job.

When `flag1` is set, the calling program dials the first number in the list specified by the `phone` command. If the call fails for any reason, the program dials the second number and so on. The phone number is specified by the Hayes ATDT prefix followed by the number itself, including the prefix and long-distance digits and delay code, if necessary. The `flag1` is reset and the calling program terminated if (a) valid clock update has been determined, (b) no more numbers remain in the list, (c) a device fault or timeout occurs or (d) the `flag1` option is reset manually using `ntpq`.

The driver automatically recognizes the message format of each modem time service. It selects the parsing algorithm depending on the message length. There is some hazard should the message be corrupted. However, the data format is checked carefully and only if all checks succeed is the message accepted. Corrupted lines are discarded without complaint. Once the service is known, the reference identifier for the driver is set to NIST, USNO, PTB or GPS as appropriate.

The Spectracom receiver can be connected via a modem if the radio is configured to send time codes continuously at 1 s intervals. In principle, the `flag2` option enables port locking, allowing the modem to be shared when not in use by this driver. On Solaris with the current NTP I/O routines, this results in lots of ugly error messages.

The `minpoll` and `maxpoll` keywords of the server configuration command can be used to limit the intervals between calls. The recommended settings are 12 (1.1 hours) for `minpoll` and 17 (36 hours) for `maxpoll`. Ordinarily, the poll interval will start at `minpoll` and ramp up to `maxpoll` in a day or two.

## 4. US Phone Numbers and Formats

Note: Phone numbers include the entire Hayes modem command, including the `ATDT` and other control codes as may be necessary. For most cases only the `ATDT` may be necessary.

National Institute of Science and Technology (NIST)

Phone: (303) 494-4774 (Boulder, CO); (808) 335-4721 (Hawaii)

    National Institute of Standards and Technology
    Telephone Time Service, Generator 3B
    Enter question mark "?" for HELP
    MJD YR MO DA H M S ST S UT1 msADV <OTM>
    47999 90-04-18 21:39:15 50 0 +.1 045.0 UTC(NIST) *
    47999 90-04-18 21:39:16 50 0 +.1 045.0 UTC(NIST) #
    ...

`MJD`, `YR`, `ST`, `UT1` and `UTC(NIST)` are not used by this driver. The `<OTM>` on-time character "`*`" changes to "`#`" when the delay correction is valid.

US Naval Observatory (USNO)

Phone: (202) 762-1594 (Washington, DC); (719) 567-6743 (Colorado Springs, CO)

Data Format (two lines, repeating at one-second intervals)

    jjjjj nnn hhmmss UTC

    * on-time character for previous timecode message
    jjjjj modified Julian day number (not used)
    nnn day of year
    hhmmss second of day

European Phone Numbers and Formats

Orolia GPS Receivers (formerly Spectracom)

If a modem is connected to a Spectracom receiver, this driver will call it and retrieve the time in one of two formats, 0 and 2. Ordinarily, the receiver requires a `T` in order to return the timecode. As this driver does not send data via the modem, it must either be configured in continuous mode or be polled by another local driver.

## 5. Monitor Data

The received timecode is written as-is to the `clockstats` file along with the Hayes connection and hang-up commands and result codes.

## 6. 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

  Set by the driver to (one of) `NIST`, `USNO`, `PTB` or `GPS`.

`flag1 {0 | 1}`

  Initiate a call if 1. Automatically reset by program.

`flag2 {0 | 1}`

  Enables port locking if 1, disables if 0 (default).

`flag3 {0 | 1}`

  Not used by this driver.

`flag4 {0 | 1}`

  Not used by this driver.

`subtype`

  Not used by this driver.

`mode`

  Controls when `flag1` is set to initiate a call: as last resort (backup) if 0 (default), each poll cycle (auto) if 1, never (manual) if 2.

`path` filename

  Overrides the default device path.

`ppspath` filename

  Not used by this driver.

`baud` number

  Overrides the default baud rate.

## 7. Configuration Example

    refclock modem mode 1 minpoll 12 maxpoll 17
    phone ATDT13034944774 # NIST

## 8. Author

David L. Mills <mills@udel.edu>

## 9. Additional Information

Reference Clock Drivers

Home Page | Site Map | Contacts