option-tester: Add many changes
[ntpsec.git] / docs / driver_modem.adoc
bloba6f8e5ae938ffe2e7f98ce59fdb7ddc81b7e8961
1 = NIST/USNO/PTB Modem Time Services
2 include::include-html.ad[]
4 == Synopsis
6 ["verse",subs="normal"]
7 Name: modem
8 Reference ID: NIST | USNO | PTB | GPS
9 Serial Port: /dev/modem__u__; 9600 8N1
10 Features: tty_clk
11 Requires: a dial-out device.
13 == Warning
15 The ACTS and USNO modes of this driver report only two-digit years, and is thus
16 reliant on the system clock to be near correct before samples will be
17 processed properly. You will not be able to use it to run
18 autonomously, nor will it reliably recover from a trashed or zeroed
19 system clock.
21 == Description
23 This driver supports the US (NIST and USNO) and European (PTB (Germany),
24 NPL (UK), etc.) modem time services, as well as Spectracom GPS receivers
25 connected via a modem. The driver periodically dials a number from a
26 telephone list, receives the timecode data and calculates the local
27 clock correction. It is designed primarily for backup when neither a
28 radio clock nor connectivity to Internet time servers are available. It
29 can also be configured to operate full period.
31 For best results the indicated time must be corrected for the modem
32 and telephone circuit propagation delays, which can reach 200 ms or
33 more.  For the NIST service, corrections are determined automatically
34 by measuring the roundtrip delay of echoed characters. With this
35 service, the absolute accuracy is typically a millisecond or
36 two. Determining corrections for the other services must be by other
37 means. With these services variations from call to call and between
38 messages during a call are typically a few milliseconds, occasionally
39 higher.
41 This driver requires a 1200 bps or faster modem with a Hayes-compatible
42 command set and control over the modem data terminal ready (DTR) control
43 line. The actual line speed ranges from 1200 bps with USNO to 14,400 bps
44 with NIST. The modem setup string is hard-coded in the driver and may
45 require changes for nonstandard modems or special circumstances. It
46 can be overridden by setting the extended system variable
47 "modemsetup" via ntpq.
49 There are three modes of operation selected by the +mode+ keyword in the
50 +server+ configuration command. In backup mode (0) +flag1+ is set at each
51 poll event, but only if no other synchronization sources are available. In
52 auto mode (1) +flag1+ is set at each poll event. In manual mode (2) the
53 calling program is initiated by setting the +flag1+ option. This can be done
54 manually using +ntpq+, or by a cron job.
56 When +flag1+ is set, the calling program dials the first number in the
57 list specified by the +phone+ command. If the call fails for any reason,
58 the program dials the second number and so on. The phone number is
59 specified by the Hayes ATDT prefix followed by the number itself,
60 including the prefix and long-distance digits and delay code, if
61 necessary. The +flag1+ is reset and the calling program terminated if
62 (a) valid clock update has been determined, (b) no more numbers remain
63 in the list, (c) a device fault or timeout occurs or (d) the +flag1+
64 option is reset manually using +ntpq+.
66 The driver automatically recognizes the message format of each modem
67 time service. It selects the parsing algorithm depending on the message
68 length. There is some hazard should the message be corrupted. However,
69 the data format is checked carefully and only if all checks succeed is
70 the message accepted. Corrupted lines are discarded without complaint.
71 Once the service is known, the reference identifier for the driver is
72 set to NIST, USNO, PTB or GPS as appropriate.
74 The Spectracom receiver can be connected via a modem if the radio is
75 configured to send time codes continuously at 1 s intervals. In
76 principle, the +flag2+ option enables port locking, allowing the modem
77 to be shared when not in use by this driver. On Solaris with
78 the current NTP I/O routines, this results in lots of ugly error
79 messages.
81 The +minpoll+ and +maxpoll+ keywords of the server configuration command
82 can be used to limit the intervals between calls. The recommended
83 settings are 12 (1.1 hours) for +minpoll+ and 17 (36 hours) for
84 +maxpoll+. Ordinarily, the poll interval will start at +minpoll+ and
85 ramp up to +maxpoll+ in a day or two.
87 == US Phone Numbers and Formats
89 Note: Phone numbers include the entire Hayes modem command, including
90 the +ATDT+ and other control codes as may be necessary. For most cases
91 only the +ATDT+ may be necessary.
93 https://www.nist.gov/pml/time-and-frequency-division/services/automated-computer-time-service-acts[National
94 Institute of Science and Technology (NIST)]
96 Phone: (303) 494-4774 (Boulder, CO); (808) 335-4721 (Hawaii)
98 ----------------------------------------------------
99 National Institute of Standards and Technology
100 Telephone Time Service, Generator 3B
101 Enter question mark "?" for HELP
102 MJD YR MO DA H M S ST S UT1 msADV <OTM>
103 47999 90-04-18 21:39:15 50 0 +.1 045.0 UTC(NIST) *
104 47999 90-04-18 21:39:16 50 0 +.1 045.0 UTC(NIST) #
106 ----------------------------------------------------
108 +MJD+, +YR+, +ST+, +UT1+ and +UTC(NIST)+ are not used by this driver.
109 The +<OTM>+ on-time character "+*+" changes to "+#+" when the delay
110 correction is valid.
112 https://www.usno.navy.mil/USNO/time/telephone-time[US Naval Observatory (USNO)]
114 Phone: (202) 762-1594 (Washington, DC); (719) 567-6743 (Colorado Springs, CO)
116 https://tycho.usno.navy.mil/modem_time.html[Data Format] (two lines,
117 repeating at one-second intervals)
119 ----------------------------------------------------
120 jjjjj nnn hhmmss UTC
122 * on-time character for previous timecode message
123 jjjjj modified Julian day number (not used)
124 nnn day of year
125 hhmmss second of day
126 ----------------------------------------------------
128 link:tf582_4.html[European Phone Numbers and Formats]
130 https://www.orolia.com/[Orolia GPS Receivers] (formerly Spectracom)
132 If a modem is connected to a Spectracom receiver, this driver will call
133 it and retrieve the time in one of two formats, 0 and 2. Ordinarily, the
134 receiver requires a +T+ in order to return the timecode. As this driver
135 does not send data via the modem, it must either be configured in
136 continuous mode or be polled by another local driver.
138 == Monitor Data
140 The received timecode is written as-is to the +clockstats+ file along
141 with the Hayes connection and hang-up commands and result codes.
143 == Driver Options
145 +unit+ 'number'::
146   The driver unit number, defaulting to 0. Used as a distinguishing
147   suffix in the driver device name.
148 +time1+ 'time'::
149   Specifies the time offset calibration factor, in seconds and fraction,
150   with default 0.0.
151 +time2+ 'time'::
152   Not used by this driver.
153 +stratum+ 'number'::
154   Specifies the driver stratum, in decimal from 0 to 15, with default 0.
155 +refid+ 'string'::
156   Set by the driver to (one of) +NIST+, +USNO+, +PTB+ or +GPS+.
157 +flag1 {0 | 1}+::
158   Initiate a call if 1. Automatically reset by program.
159 +flag2 {0 | 1}+::
160   Enables port locking if 1, disables if 0 (default).
161 +flag3 {0 | 1}+::
162   Not used by this driver.
163 +flag4 {0 | 1}+::
164   Not used by this driver.
165 +subtype+::
166   Not used by this driver.
167 +mode+::
168   Controls when +flag1+ is set to initiate a call: as last resort (backup) if
169   0 (default), each poll cycle (auto) if 1, never (manual) if 2.
170 +path+ 'filename'::
171   Overrides the default device path.
172 +ppspath+ 'filename'::
173   Not used by this driver.
174 +baud+ 'number'::
175   Overrides the default baud rate.
177 == Configuration Example
179 ----------------------------------------------------------------------------
180 refclock modem mode 1 minpoll 12 maxpoll 17
181 phone ATDT13034944774 # NIST
182 ----------------------------------------------------------------------------
184 == Author
186 David L. Mills <mills@udel.edu>
188 == Additional Information
190 link:refclock.html[Reference Clock Drivers]
192 '''''
194 include::includes/footer.adoc[]