docs/driver_hpgps.adoc

   1 = Hewlett Packard GPS Receivers -  HP 58503A and HP Z3801A
   2 include::include-html.ad[]
   3
   4 == Synopsis
   5
   6 ["verse",subs="normal"]
   7 Name: hpgps
   8 Reference ID: GPS
   9 Driver ID: GPS_HP
  10 Serial Port: /dev/hpgps__u__; 9600 bps 8N1, 19200 bps 7N2 for the HP Z3801A
  11
  12 == Warning
  13
  14 As of September 2017 we have reports that the internal clock on a
  15 Z3801A was observed to roll over to 1998 (see
  16 link:rollover.html[Rollover issues in time sources]). Users should
  17 audit for rollover before deploying any of these devices. One or more "g"
  18 suffixes on your 'time1' option may be useful as a workaround if
  19 your device does not support setting the era date.
  20
  21 == Description
  22
  23 This driver supports the HP 58503A Time and Frequency Reference Receiver
  24 and HP Z3801A GPS Receiver. It will probably work with other Z38xx models.
  25 Two-unit pairs of these are sometimes known as a KS-24361. All of
  26 these product are well past end-of-life.
  27
  28 These receivers are very old designs, dating from around 1990, so
  29 their GPS receiver stages are not very sensitive by modern
  30 standards. On the other hand, lots of them are available cheap,
  31 because they used to be standard kit on cell towers and were surplussed
  32 off in the thousands.
  33
  34 They use HP SmartClock (TM) to implement an Enhanced GPS receiver. The
  35 receiver accuracy when locked to GPS in normal operation is better
  36 than 1 µs. The accuracy when operating in holdover is typically
  37 better than 10 µs per day. The receiver should be operated with
  38 factory default settings. Initial driver operation: expects the
  39 receiver to be already locked to GPS, configured and able to output
  40 timecode format 2 messages.
  41
  42 The driver uses the poll sequence +:PTIME:TCODE?+ to get a response from
  43 the receiver. The receiver responds with a timecode string of ASCII
  44 printing characters, followed by a <cr><lf>, followed by a prompt string
  45 issued by the receiver, in the following format:
  46
  47 -------------------------------------
  48 T#yyyymmddhhmmssMFLRVcc<cr><lf>scpi >
  49 -------------------------------------
  50
  51 The driver processes the response at the <cr> and <lf>, so what the
  52 driver sees is the prompt from the previous poll, followed by this
  53 timecode. The prompt from the current poll is (usually) left unread
  54 until the next poll. So (except on the very first poll) the driver sees
  55 this:
  56
  57 -------------------------------------
  58 scpi >T#yyyymmddhhmmssMFLRVcc<cr><lf>
  59 -------------------------------------
  60
  61 The T is the on-time character, at 980 ms before the next 1PPS edge.
  62 The # is the timecode format type. We look for format 2. Without any of
  63 the CLK or PPS stuff, then, the receiver buffer timestamp at the <cr> is
  64 24 characters later, which is about 25 ms. at 9600 bps, so the first
  65 approximation for the +time1+ option is nominally -0.955 s. This number
  66 probably needs adjusting for each machine / OS type, so far: -0.955000 s
  67 on an HP 9000 Model 712/80 HP-UX 9.05 -0.953175 s on an HP 9000 Model 370
  68 HP-UX 9.10
  69
  70 This driver will probably work with the 58503B and 59551A if they are
  71 set up appropriately.
  72
  73 To use an HP Z3801A, specify +subtype 1+ on the server config line to setup
  74 the right line parameters.
  75
  76 The timekeeping portion of HP's business was sold to Symmetricom; Symmetricom
  77 was later acquired by https://www.microsemi.com/[Microsemi].
  78
  79 == Rollover compensation
  80
  81 Some devices in this product line have a front-panel display of
  82 date-time and controls to manipulate it.  On these, it is possible to
  83 reset the device's hidden base date for your current era. Consult
  84 your documentation for details.
  85
  86 == Driver Options
  87
  88 +unit+ 'number'::
  89   The driver unit number, defaulting to 0. Used as a distinguishing
  90   suffix in the driver device name.
  91 +time1+ 'time'::
  92    Specifies the time offset calibration factor, in seconds and fraction,
  93    with default 0.0.
  94 +time2+ 'time'::
  95    Not used by this driver.
  96 +stratum+ 'number'::
  97    Specifies the driver stratum, in decimal from 0 to 15, with default 0.
  98 +refid+ 'string'::
  99    Specifies the driver reference identifier, an ASCII string from one to
 100    four characters, with default +GPS+.
 101 +flag1 {0 | 1}+::
 102    Not used by this driver.
 103 +flag2 {0 | 1}+::
 104    Not used by this driver.
 105 +flag3 {0 | 1}+::
 106    Not used by this driver.
 107 +flag4 {0 | 1}+::
 108    Not used by this driver.
 109 +subtype+::
 110    Setting mode 1 configures for the HP Z3801A.
 111 +mode+::
 112   Synonym for subtype, retained for backward compatibility.
 113 +path+ 'filename'::
 114   Overrides the default device path.
 115 +ppspath+ 'filename'::
 116   Not used by this driver.
 117 +baud+ 'number'::
 118   Overrides the default baud rate.
 119
 120 == Configuration Example
 121
 122 ----------------------------------------------------------------------------
 123 refclock hpgps
 124 ----------------------------------------------------------------------------
 125
 126 '''''
 127
 128 include::includes/footer.adoc[]