1 /* $NetBSD: refclock_heath.c,v 1.10 2024/08/18 20:47:18 christos Exp $ */
2
3 /*
4 * refclock_heath - clock driver for Heath GC-1000
5 * (but no longer the GC-1001 Model II, which apparently never worked)
6 */
7
8 #ifdef HAVE_CONFIG_H
9 # include <config.h>
10 #endif
11
12 #if defined(REFCLOCK) && defined(CLOCK_HEATH)
13
14 #include "ntpd.h"
15 #include "ntp_io.h"
16 #include "ntp_refclock.h"
17 #include "ntp_stdlib.h"
18
19 #include <stdio.h>
20 #include <ctype.h>
21
22 #ifdef HAVE_SYS_IOCTL_H
23 # include <sys/ioctl.h>
24 #endif /* not HAVE_SYS_IOCTL_H */
25
26 /*
27 * This driver supports the Heath GC-1000 Most Accurate Clock, with
28 * RS232C Output Accessory. This is a WWV/WWVH receiver somewhat less
29 * robust than other supported receivers. Its claimed accuracy is 100 ms
30 * when actually synchronized to the broadcast signal, but this doesn't
31 * happen even most of the time, due to propagation conditions, ambient
32 * noise sources, etc. When not synchronized, the accuracy is at the
33 * whim of the internal clock oscillator, which can wander into the
34 * sunset without warning. Since the indicated precision is 100 ms,
35 * expect a host synchronized only to this thing to wander to and fro,
36 * occasionally being rudely stepped when the offset exceeds the default
37 * clock_max of 128 ms.
38 *
39 * There were two GC-1000 versions supported by this driver. The original
40 * GC-1000 with RS-232 output first appeared in 1983, but dissapeared
41 * from the market a few years later. The GC-1001 II with RS-232 output
42 * first appeared circa 1990, but apparently is no longer manufactured.
43 * The two models differ considerably, both in interface and commands.
44 * The GC-1000 has a pseudo-bipolar timecode output triggered by a RTS
45 * transition. The timecode includes both the day of year and time of
46 * day. The GC-1001 II has a true bipolar output and a complement of
47 * single character commands. The timecode includes only the time of
48 * day.
49 *
50 * The GC-1001 II was apparently never tested and, based on a Coverity
51 * scan, apparently never worked [Bug 689]. Related code has been disabled.
52 *
53 * GC-1000
54 *
55 * The internal DIPswitches should be set to operate in MANUAL mode. The
56 * external DIPswitches should be set to GMT and 24-hour format.
57 *
58 * In MANUAL mode the clock responds to a rising edge of the request to
59 * send (RTS) modem control line by sending the timecode. Therefore, it
60 * is necessary that the operating system implement the TIOCMBIC and
61 * TIOCMBIS ioctl system calls and TIOCM_RTS control bit. Present
62 * restrictions require the use of a POSIX-compatible programming
63 * interface, although other interfaces may work as well.
64 *
65 * A simple hardware modification to the clock can be made which
66 * prevents the clock hearing the request to send (RTS) if the HI SPEC
67 * lamp is out. Route the HISPEC signal to the tone decoder board pin
68 * 19, from the display, pin 19. Isolate pin 19 of the decoder board
69 * first, but maintain connection with pin 10. Also isolate pin 38 of
70 * the CPU on the tone board, and use half an added 7400 to gate the
71 * original signal to pin 38 with that from pin 19.
72 *
73 * The clock message consists of 23 ASCII printing characters in the
74 * following format:
75 *
76 * hh:mm:ss.f AM dd/mm/yr<cr>
77 *
78 * hh:mm:ss.f = hours, minutes, seconds
79 * f = deciseconds ('?' when out of spec)
80 * AM/PM/bb = blank in 24-hour mode
81 * dd/mm/yr = day, month, year
82 *
83 * The alarm condition is indicated by '?', rather than a digit, at f.
84 * Note that 0?:??:??.? is displayed before synchronization is first
85 * established and hh:mm:ss.? once synchronization is established and
86 * then lost again for about a day.
87 *
88 * GC-1001 II
89 *
90 * Commands consist of a single letter and are case sensitive. When
91 * enterred in lower case, a description of the action performed is
92 * displayed. When enterred in upper case the action is performed.
93 * Following is a summary of descriptions as displayed by the clock:
94 *
95 * The clock responds with a command The 'A' command returns an ASCII
96 * local time string: HH:MM:SS.T xx<CR>, where
97 *
98 * HH = hours
99 * MM = minutes
100 * SS = seconds
101 * T = tenths-of-seconds
102 * xx = 'AM', 'PM', or ' '
103 * <CR> = carriage return
104 *
105 * The 'D' command returns 24 pairs of bytes containing the variable
106 * divisor value at the end of each of the previous 24 hours. This
107 * allows the timebase trimming process to be observed. UTC hour 00 is
108 * always returned first. The first byte of each pair is the high byte
109 * of (variable divisor * 16); the second byte is the low byte of
110 * (variable divisor * 16). For example, the byte pair 3C 10 would be
111 * returned for a divisor of 03C1 hex (961 decimal).
112 *
113 * The 'I' command returns: | TH | TL | ER | DH | DL | U1 | I1 | I2 | ,
114 * where
115 *
116 * TH = minutes since timebase last trimmed (high byte)
117 * TL = minutes since timebase last trimmed (low byte)
118 * ER = last accumulated error in 1.25 ms increments
119 * DH = high byte of (current variable divisor * 16)
120 * DL = low byte of (current variable divisor * 16)
121 * U1 = UT1 offset (/.1 s): | + | 4 | 2 | 1 | 0 | 0 | 0 | 0 |
122 * I1 = information byte 1: | W | C | D | I | U | T | Z | 1 | ,
123 * where
124 *
125 * W = set by WWV(H)
126 * C = CAPTURE LED on
127 * D = TRIM DN LED on
128 * I = HI SPEC LED on
129 * U = TRIM UP LED on
130 * T = DST switch on
131 * Z = UTC switch on
132 * 1 = UT1 switch on
133 *
134 * I2 = information byte 2: | 8 | 8 | 4 | 2 | 1 | D | d | S | ,
135 * where
136 *
137 * 8, 8, 4, 2, 1 = TIME ZONE switch settings
138 * D = DST bit (#55) in last-received frame
139 * d = DST bit (#2) in last-received frame
140 * S = clock is in simulation mode
141 *
142 * The 'P' command returns 24 bytes containing the number of frames
143 * received without error during UTC hours 00 through 23, providing an
144 * indication of hourly propagation. These bytes are updated each hour
145 * to reflect the previous 24 hour period. UTC hour 00 is always
146 * returned first.
147 *
148 * The 'T' command returns the UTC time: | HH | MM | SS | T0 | , where
149 * HH = tens-of-hours and hours (packed BCD)
150 * MM = tens-of-minutes and minutes (packed BCD)
151 * SS = tens-of-seconds and seconds (packed BCD)
152 * T = tenths-of-seconds (BCD)
153 *
154 * Fudge Factors
155 *
156 * A fudge time1 value of .04 s appears to center the clock offset
157 * residuals. The fudge time2 parameter is the local time offset east of
158 * Greenwich, which depends on DST. Sorry about that, but the clock
159 * gives no hint on what the DIPswitches say.
160 */
161
162 /*
163 * Interface definitions
164 */
165 #define DEVICE "/dev/heath%d" /* device name and unit */
166 #define PRECISION (-4) /* precision assumed (about 100 ms) */
167 #define REFID "WWV\0" /* reference ID */
168 #define DESCRIPTION "Heath GC-1000 Most Accurate Clock" /* WRU */
169
170 #define LENHEATH1 23 /* min timecode length */
171 #if 0 /* BUG 689 */
172 #define LENHEATH2 13 /* min timecode length */
173 #endif
174
175 /*
176 * Tables to compute the ddd of year form icky dd/mm timecode. Viva la
177 * leap.
178 */
179 static int day1tab[] = {31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31};
180 static int day2tab[] = {31, 29, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31};
181
182 /*
183 * Baud rate table. The GC-1000 supports 1200, 2400 and 4800; the
184 * GC-1001 II supports only 9600.
185 */
186 static int speed[] = {B1200, B2400, B4800, B9600};
187
188 /*
189 * Function prototypes
190 */
191 static int heath_start (int, struct peer *);
192 static void heath_shutdown (int, struct peer *);
193 static void heath_receive (struct recvbuf *);
194 static void heath_poll (int, struct peer *);
195
196 /*
197 * Transfer vector
198 */
199 struct refclock refclock_heath = {
200 heath_start, /* start up driver */
201 heath_shutdown, /* shut down driver */
202 heath_poll, /* transmit poll message */
203 noentry, /* not used (old heath_control) */
204 noentry, /* initialize driver */
205 noentry, /* not used (old heath_buginfo) */
206 NOFLAGS /* not used */
207 };
208
209
210 /*
211 * heath_start - open the devices and initialize data for processing
212 */
213 static int
heath_start(int unit,struct peer * peer)214 heath_start(
215 int unit,
216 struct peer *peer
217 )
218 {
219 struct refclockproc *pp;
220 int fd;
221 char device[20];
222
223 /*
224 * Open serial port
225 */
226 snprintf(device, sizeof(device), DEVICE, unit);
227 fd = refclock_open(&peer->srcadr, device, speed[peer->ttl & 0x3],
228 LDISC_REMOTE);
229 if (fd <= 0)
230 return (0);
231 pp = peer->procptr;
232 pp->io.clock_recv = heath_receive;
233 pp->io.srcclock = peer;
234 pp->io.datalen = 0;
235 pp->io.fd = fd;
236 if (!io_addclock(&pp->io)) {
237 close(fd);
238 pp->io.fd = -1;
239 return (0);
240 }
241
242 /*
243 * Initialize miscellaneous variables
244 */
245 peer->precision = PRECISION;
246 pp->clockdesc = DESCRIPTION;
247 memcpy(&pp->refid, REFID, 4);
248 return (1);
249 }
250
251
252 /*
253 * heath_shutdown - shut down the clock
254 */
255 static void
heath_shutdown(int unit,struct peer * peer)256 heath_shutdown(
257 int unit,
258 struct peer *peer
259 )
260 {
261 struct refclockproc *pp;
262
263 pp = peer->procptr;
264 if (-1 != pp->io.fd)
265 io_closeclock(&pp->io);
266 }
267
268
269 /*
270 * heath_receive - receive data from the serial interface
271 */
272 static void
heath_receive(struct recvbuf * rbufp)273 heath_receive(
274 struct recvbuf *rbufp
275 )
276 {
277 struct refclockproc *pp;
278 struct peer *peer;
279 l_fp trtmp;
280 int month, day;
281 int i;
282 char dsec, a[5];
283
284 /*
285 * Initialize pointers and read the timecode and timestamp
286 */
287 peer = rbufp->recv_peer;
288 pp = peer->procptr;
289 pp->lencode = refclock_gtlin(rbufp, pp->a_lastcode, BMAX,
290 &trtmp);
291
292 /*
293 * We get down to business, check the timecode format and decode
294 * its contents. If the timecode has invalid length or is not in
295 * proper format, we declare bad format and exit.
296 */
297 switch (pp->lencode) {
298
299 /*
300 * GC-1000 timecode format: "hh:mm:ss.f AM mm/dd/yy"
301 * GC-1001 II timecode format: "hh:mm:ss.f "
302 */
303 case LENHEATH1:
304 if (sscanf(pp->a_lastcode,
305 "%2d:%2d:%2d.%c%5c%2d/%2d/%2d", &pp->hour,
306 &pp->minute, &pp->second, &dsec, a, &month, &day,
307 &pp->year) != 8) {
308 refclock_report(peer, CEVNT_BADREPLY);
309 return;
310 }
311 break;
312
313 #if 0 /* BUG 689 */
314 /*
315 * GC-1001 II timecode format: "hh:mm:ss.f "
316 */
317 case LENHEATH2:
318 if (sscanf(pp->a_lastcode, "%2d:%2d:%2d.%c", &pp->hour,
319 &pp->minute, &pp->second, &dsec) != 4) {
320 refclock_report(peer, CEVNT_BADREPLY);
321 return;
322 } else {
323 struct tm *tm_time_p;
324 time_t now;
325
326 time(&now); /* we should grab 'now' earlier */
327 tm_time_p = gmtime(&now);
328 /*
329 * There is a window of time around midnight
330 * where this will Do The Wrong Thing.
331 */
332 if (tm_time_p) {
333 month = tm_time_p->tm_mon + 1;
334 day = tm_time_p->tm_mday;
335 } else {
336 refclock_report(peer, CEVNT_FAULT);
337 return;
338 }
339 }
340 break;
341 #endif
342
343 default:
344 refclock_report(peer, CEVNT_BADREPLY);
345 return;
346 }
347
348 /*
349 * We determine the day of the year from the DIPswitches. This
350 * should be fixed, since somebody might forget to set them.
351 * Someday this hazard will be fixed by a fiendish scheme that
352 * looks at the timecode and year the radio shows, then computes
353 * the residue of the seconds mod the seconds in a leap cycle.
354 * If in the third year of that cycle and the third and later
355 * months of that year, add one to the day. Then, correct the
356 * timecode accordingly. Icky pooh. This bit of nonsense could
357 * be avoided if the engineers had been required to write a
358 * device driver before finalizing the timecode format.
359 */
360 if (month < 1 || month > 12 || day < 1) {
361 refclock_report(peer, CEVNT_BADTIME);
362 return;
363 }
364 if (pp->year % 4) {
365 if (day > day1tab[month - 1]) {
366 refclock_report(peer, CEVNT_BADTIME);
367 return;
368 }
369 for (i = 0; i < month - 1; i++)
370 day += day1tab[i];
371 } else {
372 if (day > day2tab[month - 1]) {
373 refclock_report(peer, CEVNT_BADTIME);
374 return;
375 }
376 for (i = 0; i < month - 1; i++)
377 day += day2tab[i];
378 }
379 pp->day = day;
380
381 /*
382 * Determine synchronization and last update
383 */
384 if (!isdigit((unsigned char)dsec))
385 pp->leap = LEAP_NOTINSYNC;
386 else {
387 pp->nsec = (dsec - '0') * 100000000;
388 pp->leap = LEAP_NOWARNING;
389 }
390 if (!refclock_process(pp))
391 refclock_report(peer, CEVNT_BADTIME);
392 }
393
394
395 /*
396 * heath_poll - called by the transmit procedure
397 */
398 static void
heath_poll(int unit,struct peer * peer)399 heath_poll(
400 int unit,
401 struct peer *peer
402 )
403 {
404 struct refclockproc *pp;
405 int bits = TIOCM_RTS;
406
407 /*
408 * At each poll we check for timeout and toggle the RTS modem
409 * control line, then take a timestamp. Presumably, this is the
410 * event the radio captures to generate the timecode.
411 * Apparently, the radio takes about a second to make up its
412 * mind to send a timecode, so the receive timestamp is
413 * worthless.
414 */
415 pp = peer->procptr;
416
417 /*
418 * We toggle the RTS modem control lead (GC-1000) and sent a T
419 * (GC-1001 II) to kick a timecode loose from the radio. This
420 * code works only for POSIX and SYSV interfaces. With bsd you
421 * are on your own. We take a timestamp between the up and down
422 * edges to lengthen the pulse, which should be about 50 usec on
423 * a Sun IPC. With hotshot CPUs, the pulse might get too short.
424 * Later.
425 *
426 * Bug 689: Even though we no longer support the GC-1001 II,
427 * I'm leaving the 'T' write in for timing purposes.
428 */
429 if (ioctl(pp->io.fd, TIOCMBIC, (char *)&bits) < 0)
430 refclock_report(peer, CEVNT_FAULT);
431 get_systime(&pp->lastrec);
432 if (refclock_write(peer, "T", 1, "T") != 1)
433 refclock_report(peer, CEVNT_FAULT);
434 ioctl(pp->io.fd, TIOCMBIS, (char *)&bits);
435 if (pp->coderecv == pp->codeproc) {
436 refclock_report(peer, CEVNT_TIMEOUT);
437 return;
438 }
439 pp->lastref = pp->lastrec;
440 refclock_receive(peer);
441 record_clock_stats(&peer->srcadr, pp->a_lastcode);
442 #ifdef DEBUG
443 if (debug)
444 printf("heath: timecode %d %s\n", pp->lencode,
445 pp->a_lastcode);
446 #endif
447 pp->polls++;
448 }
449
450 #else
451 NONEMPTY_TRANSLATION_UNIT
452 #endif /* REFCLOCK */
453