contrib/ntp/ntpd/refclock_heath.c

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