1 /* $NetBSD: refclock_wwvb.c,v 1.8 2024/08/18 20:47:19 christos Exp $ */
2
3 /*
4 * refclock_wwvb - clock driver for Spectracom WWVB and GPS receivers
5 */
6
7 #ifdef HAVE_CONFIG_H
8 #include <config.h>
9 #endif
10
11 #if defined(REFCLOCK) && defined(CLOCK_SPECTRACOM)
12
13 #include "ntpd.h"
14 #include "ntp_io.h"
15 #include "ntp_refclock.h"
16 #include "ntp_calendar.h"
17 #include "ntp_stdlib.h"
18
19 #include <stdio.h>
20 #include <ctype.h>
21
22 #ifdef HAVE_PPSAPI
23 #include "ppsapi_timepps.h"
24 #include "refclock_atom.h"
25 #endif /* HAVE_PPSAPI */
26
27 /*
28 * This driver supports the Spectracom Model 8170 and Netclock/2 WWVB
29 * Synchronized Clocks and the Netclock/GPS Master Clock. Both the WWVB
30 * and GPS clocks have proven reliable sources of time; however, the
31 * WWVB clocks have proven vulnerable to high ambient conductive RF
32 * interference. The claimed accuracy of the WWVB clocks is 100 us
33 * relative to the broadcast signal, while the claimed accuracy of the
34 * GPS clock is 50 ns; however, in most cases the actual accuracy is
35 * limited by the resolution of the timecode and the latencies of the
36 * serial interface and operating system.
37 *
38 * The WWVB and GPS clocks should be configured for 24-hour display,
39 * AUTO DST off, time zone 0 (UTC), data format 0 or 2 (see below) and
40 * baud rate 9600. If the clock is to used as the source for the IRIG
41 * Audio Decoder (refclock_irig.c in this distribution), it should be
42 * configured for AM IRIG output and IRIG format 1 (IRIG B with
43 * signature control). The GPS clock can be configured either to respond
44 * to a 'T' poll character or left running continuously.
45 *
46 * There are two timecode formats used by these clocks. Format 0, which
47 * is available with both the Netclock/2 and 8170, and format 2, which
48 * is available only with the Netclock/2, specially modified 8170 and
49 * GPS.
50 *
51 * Format 0 (22 ASCII printing characters):
52 *
53 * <cr><lf>i ddd hh:mm:ss TZ=zz<cr><lf>
54 *
55 * on-time = first <cr>
56 * hh:mm:ss = hours, minutes, seconds
57 * i = synchronization flag (' ' = in synch, '?' = out of synch)
58 *
59 * The alarm condition is indicated by other than ' ' at i, which occurs
60 * during initial synchronization and when received signal is lost for
61 * about ten hours.
62 *
63 * Format 2 (24 ASCII printing characters):
64 *
65 * <cr><lf>iqyy ddd hh:mm:ss.fff ld
66 *
67 * on-time = <cr>
68 * i = synchronization flag (' ' = in synch, '?' = out of synch)
69 * q = quality indicator (' ' = locked, 'A'...'D' = unlocked)
70 * yy = year (as broadcast)
71 * ddd = day of year
72 * hh:mm:ss.fff = hours, minutes, seconds, milliseconds
73 *
74 * The alarm condition is indicated by other than ' ' at i, which occurs
75 * during initial synchronization and when received signal is lost for
76 * about ten hours. The unlock condition is indicated by other than ' '
77 * at q.
78 *
79 * The q is normally ' ' when the time error is less than 1 ms and a
80 * character in the set 'A'...'D' when the time error is less than 10,
81 * 100, 500 and greater than 500 ms respectively. The l is normally ' ',
82 * but is set to 'L' early in the month of an upcoming UTC leap second
83 * and reset to ' ' on the first day of the following month. The d is
84 * set to 'S' for standard time 'I' on the day preceding a switch to
85 * daylight time, 'D' for daylight time and 'O' on the day preceding a
86 * switch to standard time. The start bit of the first <cr> is
87 * synchronized to the indicated time as returned.
88 *
89 * This driver does not need to be told which format is in use - it
90 * figures out which one from the length of the message. The driver
91 * makes no attempt to correct for the intrinsic jitter of the radio
92 * itself, which is a known problem with the older radios.
93 *
94 * PPS Signal Processing
95 *
96 * When PPS signal processing is enabled, and when the system clock has
97 * been set by this or another driver and the PPS signal offset is
98 * within 0.4 s of the system clock offset, the PPS signal replaces the
99 * timecode for as long as the PPS signal is active. If for some reason
100 * the PPS signal fails for one or more poll intervals, the driver
101 * reverts to the timecode. If the timecode fails for one or more poll
102 * intervals, the PPS signal is disconnected.
103 *
104 * Fudge Factors
105 *
106 * This driver can retrieve a table of quality data maintained
107 * internally by the Netclock/2 clock. If flag4 of the fudge
108 * configuration command is set to 1, the driver will retrieve this
109 * table and write it to the clockstats file when the first timecode
110 * message of a new day is received.
111 *
112 * PPS calibration fudge time 1: format 0 .003134, format 2 .004034
113 */
114 /*
115 * Interface definitions
116 */
117 #define DEVICE "/dev/wwvb%d" /* device name and unit */
118 #define SPEED232 B9600 /* uart speed (9600 baud) */
119 #define PRECISION (-13) /* precision assumed (about 100 us) */
120 #define PPS_PRECISION (-13) /* precision assumed (about 100 us) */
121 #define REFID "WWVB" /* reference ID */
122 #define DESCRIPTION "Spectracom WWVB/GPS Receiver" /* WRU */
123
124 #define LENWWVB0 22 /* format 0 timecode length */
125 #define LENWWVB2 24 /* format 2 timecode length */
126 #define LENWWVB3 29 /* format 3 timecode length */
127 #define MONLIN 15 /* number of monitoring lines */
128
129 /*
130 * WWVB unit control structure
131 */
132 struct wwvbunit {
133 #ifdef HAVE_PPSAPI
134 struct refclock_atom atom; /* PPSAPI structure */
135 int ppsapi_tried; /* attempt PPSAPI once */
136 int ppsapi_lit; /* time_pps_create() worked */
137 int tcount; /* timecode sample counter */
138 int pcount; /* PPS sample counter */
139 #endif /* HAVE_PPSAPI */
140 l_fp laststamp; /* last <CR> timestamp */
141 int prev_eol_cr; /* was last EOL <CR> (not <LF>)? */
142 u_char lasthour; /* last hour (for monitor) */
143 u_char linect; /* count ignored lines (for monitor */
144 };
145
146 /*
147 * Function prototypes
148 */
149 static int wwvb_start (int, struct peer *);
150 static void wwvb_shutdown (int, struct peer *);
151 static void wwvb_receive (struct recvbuf *);
152 static void wwvb_poll (int, struct peer *);
153 static void wwvb_timer (int, struct peer *);
154 #ifdef HAVE_PPSAPI
155 static void wwvb_control (int, const struct refclockstat *,
156 struct refclockstat *, struct peer *);
157 #define WWVB_CONTROL wwvb_control
158 #else
159 #define WWVB_CONTROL (void)(*)
160 noentry
161 #endif /* HAVE_PPSAPI */
162
163 /*
164 * Transfer vector
165 */
166 struct refclock refclock_wwvb = {
167 wwvb_start, /* start up driver */
168 wwvb_shutdown, /* shut down driver */
169 wwvb_poll, /* transmit poll message */
170 WWVB_CONTROL, /* fudge set/change notification */
171 noentry, /* initialize driver (not used) */
172 noentry, /* not used (old wwvb_buginfo) */
173 wwvb_timer /* called once per second */
174 };
175
176
177 /*
178 * wwvb_start - open the devices and initialize data for processing
179 */
180 static int
wwvb_start(int unit,struct peer * peer)181 wwvb_start(
182 int unit,
183 struct peer *peer
184 )
185 {
186 register struct wwvbunit *up;
187 struct refclockproc *pp;
188 int fd;
189 char device[20];
190
191 /*
192 * Open serial port. Use CLK line discipline, if available.
193 */
194 snprintf(device, sizeof(device), DEVICE, unit);
195 fd = refclock_open(&peer->srcadr, device, SPEED232, LDISC_CLK);
196 if (fd <= 0)
197 return (0);
198
199 /*
200 * Allocate and initialize unit structure
201 */
202 up = emalloc_zero(sizeof(*up));
203 pp = peer->procptr;
204 pp->io.clock_recv = wwvb_receive;
205 pp->io.srcclock = peer;
206 pp->io.datalen = 0;
207 pp->io.fd = fd;
208 if (!io_addclock(&pp->io)) {
209 close(fd);
210 pp->io.fd = -1;
211 free(up);
212 return (0);
213 }
214 pp->unitptr = up;
215
216 /*
217 * Initialize miscellaneous variables
218 */
219 peer->precision = PRECISION;
220 pp->clockdesc = DESCRIPTION;
221 memcpy(&pp->refid, REFID, 4);
222 return (1);
223 }
224
225
226 /*
227 * wwvb_shutdown - shut down the clock
228 */
229 static void
wwvb_shutdown(int unit,struct peer * peer)230 wwvb_shutdown(
231 int unit,
232 struct peer *peer
233 )
234 {
235 struct refclockproc * pp;
236 struct wwvbunit * up;
237
238 pp = peer->procptr;
239 up = pp->unitptr;
240 if (-1 != pp->io.fd)
241 io_closeclock(&pp->io);
242 if (NULL != up)
243 free(up);
244 }
245
246
247 /*
248 * wwvb_receive - receive data from the serial interface
249 */
250 static void
wwvb_receive(struct recvbuf * rbufp)251 wwvb_receive(
252 struct recvbuf *rbufp
253 )
254 {
255 struct wwvbunit *up;
256 struct refclockproc *pp;
257 struct peer *peer;
258
259 l_fp trtmp; /* arrival timestamp */
260 int tz; /* time zone */
261 int day, month; /* ddd conversion */
262 int temp; /* int temp */
263 char syncchar; /* synchronization indicator */
264 char qualchar; /* quality indicator */
265 char leapchar; /* leap indicator */
266 char dstchar; /* daylight/standard indicator */
267 char tmpchar; /* trashbin */
268
269 /*
270 * Initialize pointers and read the timecode and timestamp
271 */
272 peer = rbufp->recv_peer;
273 pp = peer->procptr;
274 up = pp->unitptr;
275 temp = refclock_gtlin(rbufp, pp->a_lastcode, BMAX, &trtmp);
276
277 /*
278 * Note we get a buffer and timestamp for both a <cr> and <lf>,
279 * but only the <cr> timestamp is retained. Note: in format 0 on
280 * a Netclock/2 or upgraded 8170 the start bit is delayed 100
281 * +-50 us relative to the pps; however, on an unmodified 8170
282 * the start bit can be delayed up to 10 ms. In format 2 the
283 * reading precision is only to the millisecond. Thus, unless
284 * you have a PPS gadget and don't have to have the year, format
285 * 0 provides the lowest jitter.
286 * Save the timestamp of each <CR> in up->laststamp. Lines with
287 * no characters occur for every <LF>, and for some <CR>s when
288 * format 0 is used. Format 0 starts and ends each cycle with a
289 * <CR><LF> pair, format 2 starts each cycle with its only pair.
290 * The preceding <CR> is the on-time character for both formats.
291 * The timestamp provided with non-empty lines corresponds to
292 * the <CR> following the timecode, which is ultimately not used
293 * with format 0 and is used for the following timecode for
294 * format 2.
295 */
296 if (temp == 0) {
297 if (up->prev_eol_cr) {
298 DPRINTF(2, ("wwvb: <LF> @ %s\n",
299 prettydate(&trtmp)));
300 } else {
301 up->laststamp = trtmp;
302 DPRINTF(2, ("wwvb: <CR> @ %s\n",
303 prettydate(&trtmp)));
304 }
305 up->prev_eol_cr = !up->prev_eol_cr;
306 return;
307 }
308 pp->lencode = temp;
309 pp->lastrec = up->laststamp;
310 up->laststamp = trtmp;
311 up->prev_eol_cr = TRUE;
312 DPRINTF(2, ("wwvb: code @ %s\n"
313 " using %s minus one char\n",
314 prettydate(&trtmp), prettydate(&pp->lastrec)));
315 if (L_ISZERO(&pp->lastrec))
316 return;
317
318 /*
319 * We get down to business, check the timecode format and decode
320 * its contents. This code uses the timecode length to determine
321 * format 0, 2 or 3. If the timecode has invalid length or is
322 * not in proper format, we declare bad format and exit.
323 */
324 syncchar = qualchar = leapchar = dstchar = ' ';
325 tz = 0;
326 switch (pp->lencode) {
327
328 case LENWWVB0:
329
330 /*
331 * Timecode format 0: "I ddd hh:mm:ss DTZ=nn"
332 */
333 if (sscanf(pp->a_lastcode,
334 "%c %3d %2d:%2d:%2d%c%cTZ=%2d",
335 &syncchar, &pp->day, &pp->hour, &pp->minute,
336 &pp->second, &tmpchar, &dstchar, &tz) == 8) {
337 pp->nsec = 0;
338 break;
339 }
340 goto bad_format;
341
342 case LENWWVB2:
343
344 /*
345 * Timecode format 2: "IQyy ddd hh:mm:ss.mmm LD" */
346 if (sscanf(pp->a_lastcode,
347 "%c%c %2d %3d %2d:%2d:%2d.%3ld %c",
348 &syncchar, &qualchar, &pp->year, &pp->day,
349 &pp->hour, &pp->minute, &pp->second, &pp->nsec,
350 &leapchar) == 9) {
351 pp->nsec *= 1000000;
352 break;
353 }
354 goto bad_format;
355
356 case LENWWVB3:
357
358 /*
359 * Timecode format 3: "0003I yyyymmdd hhmmss+0000SL#"
360 * WARNING: Undocumented, and the on-time character # is
361 * not yet handled correctly by this driver. It may be
362 * as simple as compensating for an additional 1/960 s.
363 */
364 if (sscanf(pp->a_lastcode,
365 "0003%c %4d%2d%2d %2d%2d%2d+0000%c%c",
366 &syncchar, &pp->year, &month, &day, &pp->hour,
367 &pp->minute, &pp->second, &dstchar, &leapchar) == 8)
368 {
369 pp->day = ymd2yd(pp->year, month, day);
370 pp->nsec = 0;
371 break;
372 }
373 goto bad_format;
374
375 default:
376 bad_format:
377
378 /*
379 * Unknown format: If dumping internal table, record
380 * stats; otherwise, declare bad format.
381 */
382 if (up->linect > 0) {
383 up->linect--;
384 record_clock_stats(&peer->srcadr,
385 pp->a_lastcode);
386 } else {
387 refclock_report(peer, CEVNT_BADREPLY);
388 }
389 return;
390 }
391
392 /*
393 * Decode synchronization, quality and leap characters. If
394 * unsynchronized, set the leap bits accordingly and exit.
395 * Otherwise, set the leap bits according to the leap character.
396 * Once synchronized, the dispersion depends only on the
397 * quality character.
398 */
399 switch (qualchar) {
400
401 case ' ':
402 pp->disp = .001;
403 pp->lastref = pp->lastrec;
404 break;
405
406 case 'A':
407 pp->disp = .01;
408 break;
409
410 case 'B':
411 pp->disp = .1;
412 break;
413
414 case 'C':
415 pp->disp = .5;
416 break;
417
418 case 'D':
419 pp->disp = MAXDISPERSE;
420 break;
421
422 default:
423 pp->disp = MAXDISPERSE;
424 refclock_report(peer, CEVNT_BADREPLY);
425 break;
426 }
427 if (syncchar != ' ')
428 pp->leap = LEAP_NOTINSYNC;
429 else if (leapchar == 'L')
430 pp->leap = LEAP_ADDSECOND;
431 else
432 pp->leap = LEAP_NOWARNING;
433
434 /*
435 * Process the new sample in the median filter and determine the
436 * timecode timestamp, but only if the PPS is not in control.
437 */
438 #ifdef HAVE_PPSAPI
439 up->tcount++;
440 if (peer->flags & FLAG_PPS)
441 return;
442
443 #endif /* HAVE_PPSAPI */
444 if (!refclock_process_f(pp, pp->fudgetime2))
445 refclock_report(peer, CEVNT_BADTIME);
446 }
447
448
449 /*
450 * wwvb_timer - called once per second by the transmit procedure
451 */
452 static void
wwvb_timer(int unit,struct peer * peer)453 wwvb_timer(
454 int unit,
455 struct peer *peer
456 )
457 {
458 register struct wwvbunit *up;
459 struct refclockproc *pp;
460 char pollchar; /* character sent to clock */
461 #ifdef DEBUG
462 l_fp now;
463 #endif
464
465 /*
466 * Time to poll the clock. The Spectracom clock responds to a
467 * 'T' by returning a timecode in the format(s) specified above.
468 * Note there is no checking on state, since this may not be the
469 * only customer reading the clock. Only one customer need poll
470 * the clock; all others just listen in.
471 */
472 pp = peer->procptr;
473 up = pp->unitptr;
474 if (up->linect > 0)
475 pollchar = 'R';
476 else
477 pollchar = 'T';
478 if (write(pp->io.fd, &pollchar, 1) != 1)
479 refclock_report(peer, CEVNT_FAULT);
480 #ifdef DEBUG
481 get_systime(&now);
482 if (debug)
483 printf("%c poll at %s\n", pollchar, prettydate(&now));
484 #endif
485 #ifdef HAVE_PPSAPI
486 if (up->ppsapi_lit &&
487 refclock_pps(peer, &up->atom, pp->sloppyclockflag) > 0) {
488 up->pcount++,
489 peer->flags |= FLAG_PPS;
490 peer->precision = PPS_PRECISION;
491 }
492 #endif /* HAVE_PPSAPI */
493 }
494
495
496 /*
497 * wwvb_poll - called by the transmit procedure
498 */
499 static void
wwvb_poll(int unit,struct peer * peer)500 wwvb_poll(
501 int unit,
502 struct peer *peer
503 )
504 {
505 register struct wwvbunit *up;
506 struct refclockproc *pp;
507
508 /*
509 * Sweep up the samples received since the last poll. If none
510 * are received, declare a timeout and keep going.
511 */
512 pp = peer->procptr;
513 up = pp->unitptr;
514 pp->polls++;
515
516 /*
517 * If the monitor flag is set (flag4), we dump the internal
518 * quality table at the first timecode beginning the day.
519 */
520 if (pp->sloppyclockflag & CLK_FLAG4 && pp->hour <
521 (int)up->lasthour)
522 up->linect = MONLIN;
523 up->lasthour = (u_char)pp->hour;
524
525 /*
526 * Process median filter samples. If none received, declare a
527 * timeout and keep going.
528 */
529 #ifdef HAVE_PPSAPI
530 if (up->pcount == 0) {
531 peer->flags &= ~FLAG_PPS;
532 peer->precision = PRECISION;
533 }
534 if (up->tcount == 0) {
535 pp->coderecv = pp->codeproc;
536 refclock_report(peer, CEVNT_TIMEOUT);
537 return;
538 }
539 up->pcount = up->tcount = 0;
540 #else /* HAVE_PPSAPI */
541 if (pp->coderecv == pp->codeproc) {
542 refclock_report(peer, CEVNT_TIMEOUT);
543 return;
544 }
545 #endif /* HAVE_PPSAPI */
546 refclock_receive(peer);
547 record_clock_stats(&peer->srcadr, pp->a_lastcode);
548 #ifdef DEBUG
549 if (debug)
550 printf("wwvb: timecode %d %s\n", pp->lencode,
551 pp->a_lastcode);
552 #endif
553 }
554
555
556 /*
557 * wwvb_control - fudge parameters have been set or changed
558 */
559 #ifdef HAVE_PPSAPI
560 static void
wwvb_control(int unit,const struct refclockstat * in_st,struct refclockstat * out_st,struct peer * peer)561 wwvb_control(
562 int unit,
563 const struct refclockstat *in_st,
564 struct refclockstat *out_st,
565 struct peer *peer
566 )
567 {
568 register struct wwvbunit *up;
569 struct refclockproc *pp;
570
571 pp = peer->procptr;
572 up = pp->unitptr;
573
574 if (!(pp->sloppyclockflag & CLK_FLAG1)) {
575 if (!up->ppsapi_tried)
576 return;
577 up->ppsapi_tried = 0;
578 if (!up->ppsapi_lit)
579 return;
580 peer->flags &= ~FLAG_PPS;
581 peer->precision = PRECISION;
582 time_pps_destroy(up->atom.handle);
583 up->atom.handle = 0;
584 up->ppsapi_lit = 0;
585 return;
586 }
587
588 if (up->ppsapi_tried)
589 return;
590 /*
591 * Light up the PPSAPI interface.
592 */
593 up->ppsapi_tried = 1;
594 if (refclock_ppsapi(pp->io.fd, &up->atom)) {
595 up->ppsapi_lit = 1;
596 return;
597 }
598
599 msyslog(LOG_WARNING, "%s flag1 1 but PPSAPI fails",
600 refnumtoa(&peer->srcadr));
601 }
602 #endif /* HAVE_PPSAPI */
603
604 #else
605 NONEMPTY_TRANSLATION_UNIT
606 #endif /* REFCLOCK */
607