xref: /freebsd/contrib/ntp/ntpd/refclock_arbiter.c (revision 3a92d97ff0f22d21608e1c19b83104c4937523b6)
1 /*
2  * refclock_arbiter - clock driver for Arbiter 1088A/B Satellite
3  *	Controlled Clock
4  */
5 
6 #ifdef HAVE_CONFIG_H
7 #include <config.h>
8 #endif
9 
10 #if defined(REFCLOCK) && defined(CLOCK_ARBITER)
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 /*
21  * This driver supports the Arbiter 1088A/B Satellite Controlled Clock.
22  * The claimed accuracy of this clock is 100 ns relative to the PPS
23  * output when receiving four or more satellites.
24  *
25  * The receiver should be configured before starting the NTP daemon, in
26  * order to establish reliable position and operating conditions. It
27  * does not initiate surveying or hold mode. For use with NTP, the
28  * daylight savings time feature should be disables (D0 command) and the
29  * broadcast mode set to operate in UTC (BU command).
30  *
31  * The timecode format supported by this driver is selected by the poll
32  * sequence "B5", which initiates a line in the following format to be
33  * repeated once per second until turned off by the "B0" poll sequence.
34  *
35  * Format B5 (24 ASCII printing characters):
36  *
37  * <cr><lf>i yy ddd hh:mm:ss.000bbb
38  *
39  *	on-time = <cr>
40  *	i = synchronization flag (' ' = locked, '?' = unlocked)
41  *	yy = year of century
42  *	ddd = day of year
43  *	hh:mm:ss = hours, minutes, seconds
44  *	.000 = fraction of second (not used)
45  *	bbb = tailing spaces for fill
46  *
47  * The alarm condition is indicated by a '?' at i, which indicates the
48  * receiver is not synchronized. In normal operation, a line consisting
49  * of the timecode followed by the time quality character (TQ) followed
50  * by the receiver status string (SR) is written to the clockstats file.
51  * The time quality character is encoded in IEEE P1344 standard:
52  *
53  * Format TQ (IEEE P1344 estimated worst-case time quality)
54  *
55  *	0	clock locked, maximum accuracy
56  *	F	clock failure, time not reliable
57  *	4	clock unlocked, accuracy < 1 us
58  *	5	clock unlocked, accuracy < 10 us
59  *	6	clock unlocked, accuracy < 100 us
60  *	7	clock unlocked, accuracy < 1 ms
61  *	8	clock unlocked, accuracy < 10 ms
62  *	9	clock unlocked, accuracy < 100 ms
63  *	A	clock unlocked, accuracy < 1 s
64  *	B	clock unlocked, accuracy < 10 s
65  *
66  * The status string is encoded as follows:
67  *
68  * Format SR (25 ASCII printing characters)
69  *
70  *	V=vv S=ss T=t P=pdop E=ee
71  *
72  *	vv = satellites visible
73  *	ss = relative signal strength
74  *	t = satellites tracked
75  *	pdop = position dilution of precision (meters)
76  *	ee = hardware errors
77  *
78  * If flag4 is set, an additional line consisting of the receiver
79  * latitude (LA), longitude (LO), elevation (LH) (meters), and data
80  * buffer (DB) is written to this file. If channel B is enabled for
81  * deviation mode and connected to a 1-PPS signal, the last two numbers
82  * on the line are the deviation and standard deviation averaged over
83  * the last 15 seconds.
84  *
85  * PPS calibration fudge time1 .001240
86  */
87 
88 /*
89  * Interface definitions
90  */
91 #define	DEVICE		"/dev/gps%d" /* device name and unit */
92 #define	SPEED232	B9600	/* uart speed (9600 baud) */
93 #define	PRECISION	(-20)	/* precision assumed (about 1 us) */
94 #define	REFID		"GPS "	/* reference ID */
95 #define	DESCRIPTION	"Arbiter 1088A/B GPS Receiver" /* WRU */
96 #define	LENARB		24	/* format B5 timecode length */
97 #define MAXSTA		40	/* max length of status string */
98 #define MAXPOS		80	/* max length of position string */
99 
100 /*
101  * ARB unit control structure
102  */
103 struct arbunit {
104 	l_fp	laststamp;	/* last receive timestamp */
105 	int	tcswitch;	/* timecode switch/counter */
106 	char	qualchar;	/* IEEE P1344 quality (TQ command) */
107 	char	status[MAXSTA];	/* receiver status (SR command) */
108 	char	latlon[MAXPOS];	/* receiver position (lat/lon/alt) */
109 };
110 
111 /*
112  * Function prototypes
113  */
114 static	int	arb_start	P((int, struct peer *));
115 static	void	arb_shutdown	P((int, struct peer *));
116 static	void	arb_receive	P((struct recvbuf *));
117 static	void	arb_poll	P((int, struct peer *));
118 
119 /*
120  * Transfer vector
121  */
122 struct	refclock refclock_arbiter = {
123 	arb_start,		/* start up driver */
124 	arb_shutdown,		/* shut down driver */
125 	arb_poll,		/* transmit poll message */
126 	noentry,		/* not used (old arb_control) */
127 	noentry,		/* initialize driver (not used) */
128 	noentry,		/* not used (old arb_buginfo) */
129 	NOFLAGS			/* not used */
130 };
131 
132 
133 /*
134  * arb_start - open the devices and initialize data for processing
135  */
136 static int
137 arb_start(
138 	int unit,
139 	struct peer *peer
140 	)
141 {
142 	register struct arbunit *up;
143 	struct refclockproc *pp;
144 	int fd;
145 	char device[20];
146 
147 	/*
148 	 * Open serial port. Use CLK line discipline, if available.
149 	 */
150 	(void)sprintf(device, DEVICE, unit);
151 	if (!(fd = refclock_open(device, SPEED232, LDISC_CLK)))
152 		return (0);
153 
154 	/*
155 	 * Allocate and initialize unit structure
156 	 */
157 	if (!(up = (struct arbunit *)emalloc(sizeof(struct arbunit)))) {
158 		(void) close(fd);
159 		return (0);
160 	}
161 	memset((char *)up, 0, sizeof(struct arbunit));
162 	pp = peer->procptr;
163 	pp->io.clock_recv = arb_receive;
164 	pp->io.srcclock = (caddr_t)peer;
165 	pp->io.datalen = 0;
166 	pp->io.fd = fd;
167 	if (!io_addclock(&pp->io)) {
168 		(void) close(fd);
169 		free(up);
170 		return (0);
171 	}
172 	pp->unitptr = (caddr_t)up;
173 
174 	/*
175 	 * Initialize miscellaneous variables
176 	 */
177 	peer->precision = PRECISION;
178 	pp->clockdesc = DESCRIPTION;
179 	memcpy((char *)&pp->refid, REFID, 4);
180 	write(pp->io.fd, "B0", 2);
181 	return (1);
182 }
183 
184 
185 /*
186  * arb_shutdown - shut down the clock
187  */
188 static void
189 arb_shutdown(
190 	int unit,
191 	struct peer *peer
192 	)
193 {
194 	register struct arbunit *up;
195 	struct refclockproc *pp;
196 
197 	pp = peer->procptr;
198 	up = (struct arbunit *)pp->unitptr;
199 	io_closeclock(&pp->io);
200 	free(up);
201 }
202 
203 
204 /*
205  * arb_receive - receive data from the serial interface
206  */
207 static void
208 arb_receive(
209 	struct recvbuf *rbufp
210 	)
211 {
212 	register struct arbunit *up;
213 	struct refclockproc *pp;
214 	struct peer *peer;
215 	l_fp trtmp;
216 	int temp;
217 	u_char	syncchar;		/* synch indicator */
218 	char	tbuf[BMAX];		/* temp buffer */
219 
220 	/*
221 	 * Initialize pointers and read the timecode and timestamp
222 	 */
223 	peer = (struct peer *)rbufp->recv_srcclock;
224 	pp = peer->procptr;
225 	up = (struct arbunit *)pp->unitptr;
226 	temp = refclock_gtlin(rbufp, tbuf, BMAX, &trtmp);
227 
228 	/*
229 	 * Note we get a buffer and timestamp for both a <cr> and <lf>,
230 	 * but only the <cr> timestamp is retained. The program first
231 	 * sends a TQ and expects the echo followed by the time quality
232 	 * character. It then sends a B5 starting the timecode broadcast
233 	 * and expects the echo followed some time later by the on-time
234 	 * character <cr> and then the <lf> beginning the timecode
235 	 * itself. Finally, at the <cr> beginning the next timecode at
236 	 * the next second, the program sends a B0 shutting down the
237 	 * timecode broadcast.
238 	 *
239 	 * If flag4 is set, the program snatches the latitude, longitude
240 	 * and elevation and writes it to the clockstats file.
241 	 */
242 	if (temp == 0)
243 		return;
244 
245 	pp->lastrec = up->laststamp;
246 	up->laststamp = trtmp;
247 	if (temp < 3)
248 		return;
249 
250 	if (up->tcswitch == 0) {
251 
252 		/*
253 		 * Collect statistics. If nothing is recogized, just
254 		 * ignore; sometimes the clock doesn't stop spewing
255 		 * timecodes for awhile after the B0 command.
256 		 *
257 		 * If flag4 is not set, send TQ, SR, B5. If flag4 is
258 		 * sset, send TQ, SR, LA, LO, LH, DB, B5. When the
259 		 * median filter is full, send B0.
260 		 */
261 		if (!strncmp(tbuf, "TQ", 2)) {
262 			up->qualchar = tbuf[2];
263 			write(pp->io.fd, "SR", 2);
264 			return;
265 
266 		} else if (!strncmp(tbuf, "SR", 2)) {
267 			strcpy(up->status, tbuf + 2);
268 			if (pp->sloppyclockflag & CLK_FLAG4)
269 				write(pp->io.fd, "LA", 2);
270 			else
271 				write(pp->io.fd, "B5", 2);
272 			return;
273 
274 		} else if (!strncmp(tbuf, "LA", 2)) {
275 			strcpy(up->latlon, tbuf + 2);
276 			write(pp->io.fd, "LO", 2);
277 			return;
278 
279 		} else if (!strncmp(tbuf, "LO", 2)) {
280 			strcat(up->latlon, " ");
281 			strcat(up->latlon, tbuf + 2);
282 			write(pp->io.fd, "LH", 2);
283 			return;
284 
285 		} else if (!strncmp(tbuf, "LH", 2)) {
286 			strcat(up->latlon, " ");
287 			strcat(up->latlon, tbuf + 2);
288 			write(pp->io.fd, "DB", 2);
289 			return;
290 
291 		} else if (!strncmp(tbuf, "DB", 2)) {
292 			strcat(up->latlon, " ");
293 			strcat(up->latlon, tbuf + 2);
294 			record_clock_stats(&peer->srcadr, up->latlon);
295 #ifdef DEBUG
296 			if (debug)
297 				printf("arbiter: %s\n", up->latlon);
298 #endif
299 			write(pp->io.fd, "B5", 2);
300 		}
301 	}
302 
303 	/*
304 	 * We get down to business, check the timecode format and decode
305 	 * its contents. If the timecode has valid length, but not in
306 	 * proper format, we declare bad format and exit. If the
307 	 * timecode has invalid length, which sometimes occurs when the
308 	 * B0 amputates the broadcast, we just quietly steal away. Note
309 	 * that the time quality character and receiver status string is
310 	 * tacked on the end for clockstats display.
311 	 */
312 	up->tcswitch++;
313 	if (up->tcswitch <= 1 || temp < LENARB)
314 		return;
315 
316 	/*
317 	 * Timecode format B5: "i yy ddd hh:mm:ss.000   "
318 	 */
319 	strncpy(pp->a_lastcode, tbuf, BMAX);
320 	pp->a_lastcode[LENARB - 2] = up->qualchar;
321 	strcat(pp->a_lastcode, up->status);
322 	pp->lencode = strlen(pp->a_lastcode);
323 	syncchar = ' ';
324 	if (sscanf(pp->a_lastcode, "%c%2d %3d %2d:%2d:%2d",
325 	    &syncchar, &pp->year, &pp->day, &pp->hour,
326 	    &pp->minute, &pp->second) != 6) {
327 		refclock_report(peer, CEVNT_BADREPLY);
328 		write(pp->io.fd, "B0", 2);
329 		return;
330 	}
331 
332 	/*
333 	 * We decode the clock dispersion from the time quality
334 	 * character.
335 	 */
336 	switch (up->qualchar) {
337 
338 	    case '0':		/* locked, max accuracy */
339 		pp->disp = 1e-7;
340 		pp->lastref = pp->lastrec;
341 		break;
342 
343 	    case '4':		/* unlock accuracy < 1 us */
344 		pp->disp = 1e-6;
345 		break;
346 
347 	    case '5':		/* unlock accuracy < 10 us */
348 		pp->disp = 1e-5;
349 		break;
350 
351 	    case '6':		/* unlock accuracy < 100 us */
352 		pp->disp = 1e-4;
353 		break;
354 
355 	    case '7':		/* unlock accuracy < 1 ms */
356 		pp->disp = .001;
357 		break;
358 
359 	    case '8':		/* unlock accuracy < 10 ms */
360 		pp->disp = .01;
361 		break;
362 
363 	    case '9':		/* unlock accuracy < 100 ms */
364 		pp->disp = .1;
365 		break;
366 
367 	    case 'A':		/* unlock accuracy < 1 s */
368 		pp->disp = 1;
369 		break;
370 
371 	    case 'B':		/* unlock accuracy < 10 s */
372 		pp->disp = 10;
373 		break;
374 
375 	    case 'F':		/* clock failure */
376 		pp->disp = MAXDISPERSE;
377 		refclock_report(peer, CEVNT_FAULT);
378 		write(pp->io.fd, "B0", 2);
379 		return;
380 
381 	    default:
382 		pp->disp = MAXDISPERSE;
383 		refclock_report(peer, CEVNT_BADREPLY);
384 		write(pp->io.fd, "B0", 2);
385 		return;
386 	}
387 	if (syncchar != ' ')
388 		pp->leap = LEAP_NOTINSYNC;
389 	else
390 		pp->leap = LEAP_NOWARNING;
391 
392 	/*
393 	 * Process the new sample in the median filter and determine the
394 	 * timecode timestamp.
395 	 */
396 	if (!refclock_process(pp))
397 		refclock_report(peer, CEVNT_BADTIME);
398 	else if (peer->disp > MAXDISTANCE)
399 		refclock_receive(peer);
400 
401 	if (up->tcswitch >= MAXSTAGE) {
402 		write(pp->io.fd, "B0", 2);
403 	}
404 }
405 
406 
407 /*
408  * arb_poll - called by the transmit procedure
409  */
410 static void
411 arb_poll(
412 	int unit,
413 	struct peer *peer
414 	)
415 {
416 	register struct arbunit *up;
417 	struct refclockproc *pp;
418 
419 	/*
420 	 * Time to poll the clock. The Arbiter clock responds to a "B5"
421 	 * by returning a timecode in the format specified above.
422 	 * Transmission occurs once per second, unless turned off by a
423 	 * "B0". Note there is no checking on state, since this may not
424 	 * be the only customer reading the clock. Only one customer
425 	 * need poll the clock; all others just listen in.
426 	 */
427 	pp = peer->procptr;
428 	up = (struct arbunit *)pp->unitptr;
429 	pp->polls++;
430 	up->tcswitch = 0;
431 	if (write(pp->io.fd, "TQ", 2) != 2)
432 		refclock_report(peer, CEVNT_FAULT);
433 
434 	/*
435 	 * Process median filter samples. If none received, declare a
436 	 * timeout and keep going.
437 	 */
438 	if (pp->coderecv == pp->codeproc) {
439 		refclock_report(peer, CEVNT_TIMEOUT);
440 		return;
441 	}
442 	refclock_receive(peer);
443 	record_clock_stats(&peer->srcadr, pp->a_lastcode);
444 #ifdef DEBUG
445 	if (debug)
446 		printf("arbiter: timecode %d %s\n",
447 		   pp->lencode, pp->a_lastcode);
448 #endif
449 }
450 
451 #else
452 int refclock_arbiter_bs;
453 #endif /* REFCLOCK */
454