/contrib/ntp/ntpd/refclock_arbiter.c

  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 */
103struct 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 */
114static	int	arb_start	P((int, struct peer *));
115static	void	arb_shutdown	P((int, struct peer *));
116static	void	arb_receive	P((struct recvbuf *));
117static	void	arb_poll	P((int, struct peer *));
118
119/*
120 * Transfer vector
121 */
122struct	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 */
136static int
137arb_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 */
188static void
189arb_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 */
207static void
208arb_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 */
410static void
411arb_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
452int refclock_arbiter_bs;
453#endif /* REFCLOCK */