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

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

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

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

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

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

https://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]

https://www.orolia.com/[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.

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

== Configuration Example

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

== Author

David L. Mills <mills@udel.edu>

== Additional Information

link:refclock.html[Reference Clock Drivers]

'''''

include::includes/footer.adoc[]