/contrib/ntp/ntpd/refclock_heath.c

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