= NIST/USNO/PTB Modem Time Services =
include::html.include[]

== Synopsis ==

["verse",subs="normal"]
Name: modem
Reference ID: NIST | USNO | PTB | GPS
Serial Port: /dev/modem__u__; 9600 8N1
Features: tty_clk
Requires: a dial-out device.

== Warning ==

The ACTS mode of this driver reports 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.

== 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 9600 bps 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
"modem_setup" via ntpq.

There are three modes of operation selected by the +mode+ keyword in the
+server+ configuration command. In auto mode (0) +flag1+ is set at each poll
event. In backup mode (1) +flag1+ is set at each poll event, but only if
no other synchronization sources are available. 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.

== 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.

https://www.nist.gov/pml/time-and-frequency-division/services/automated-computer-time-service-acts[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.

http://www.usno.navy.mil/USNO/time/telephone-time[US Naval Observatory (USNO)]

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

http://tycho.usno.navy.mil/modem_time.html[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
----------------------------------------------------

link:tf582_4.html[European Phone Numbers and Formats]

http://www.spectracomcorp.com[Spectracom GPS Receivers]

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.

== 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.

== 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+::
  Not used by this driver.
+path+ 'filename'::
  Overrides the default device path.
+ppspath+ 'filename'::
  Not used by this driver.
+baud+ 'number'::
  Overrides the default baud rate.

== Configuration Example ==

----------------------------------------------------------------------------
refclock modem
----------------------------------------------------------------------------

== Author ==

David L. Mills <mills@udel.edu>

== Additional Information ==

link:refclock.html[Reference Clock Drivers]

'''''

include::includes/footer.adoc[]
