docs/driver_arbiter.adoc

   1 = Arbiter 1088A/B GPS Receiver
   2 include::include-html.ad[]
   3
   4 == Synopsis
   5
   6 ["verse",subs="normal"]
   7 Name: arbiter
   8 Reference ID: GPS
   9 Driver ID: GPS_ARBITER
  10 Serial Port: /dev/gps__u__; 9600 bps 8N1
  11 Features: tty_clk
  12
  13 == Deprecation warning
  14
  15 This refclock is deprecated and obsolete. The NTPsec maintainers plan
  16 to remove it in a future release.  If you have a requirement for it,
  17 please make this known to us.
  18
  19 This driver reports only two-digit years, and is thus reliant on the
  20 system clock to be near correct before samples will be processed
  21 properly. You will not be able to use it to run autonomously, nor will
  22 it reliably recover from a trashed or zeroed system clock.
  23
  24 It is likely any surving instances of this hardware will have
  25 era-rollover issues when reporting dates. One or more "g" suffixes
  26 on your 'time1' option may be useful as a workaround.
  27
  28 == Description
  29
  30 This driver supports the Arbiter 1088A/B Satellite Controlled Clock. The
  31 claimed accuracy of this clock is 100 ns relative to the PPS output when
  32 receiving four or more satellites.
  33
  34 The receiver should be configured before starting the NTP daemon, in
  35 order to establish reliable position and operating conditions. It does
  36 not initiate surveying or hold mode. For use with NTP, the daylight
  37 savings time feature should be disables (+D0+ command) and the broadcast
  38 mode set to operate in UTC (+BU+ command).
  39
  40 The timecode format supported by this driver is selected by the poll
  41 sequence +B5+, which initiates a line in the following format to be
  42 repeated once per second until turned off by the +B0+ command.
  43
  44 Format +B5+ (24 ASCII printing characters):
  45
  46 -------------------------------------------------------
  47 <cr><lf>i yy ddd hh:mm:ss.000bbb
  48
  49 on-time = <cr>
  50 i = synchronization flag (' ' = locked, '?' = unlocked)
  51 yy = year of century
  52 ddd = day of year
  53 hh:mm:ss = hours, minutes, seconds
  54 .000 = fraction of second (not used)
  55 bbb = tailing spaces for fill
  56 -------------------------------------------------------
  57
  58 The alarm condition is indicated by a \'?' at i, which indicates the
  59 receiver is not synchronized. In normal operation, a line consisting of
  60 the timecode followed by the time quality character (TQ) followed by the
  61 receiver status string (SR) is written to the clockstats file.
  62
  63 The time quality character is encoded in IEEE P1344 standard:
  64
  65 Format +TQ+ (IEEE P1344 estimated worst-case time quality)
  66
  67 -----------------------------------------
  68 0       clock locked, maximum accuracy
  69 F       clock failure, time not reliable
  70 4       clock unlocked, accuracy < 1 us
  71 5       clock unlocked, accuracy < 10 us
  72 6       clock unlocked, accuracy < 100 us
  73 7       clock unlocked, accuracy < 1 ms
  74 8       clock unlocked, accuracy < 10 ms
  75 9       clock unlocked, accuracy < 100 ms
  76 A       clock unlocked, accuracy < 1 s
  77 B       clock unlocked, accuracy < 10 s
  78 -----------------------------------------
  79
  80 The status string is encoded as follows:
  81
  82 Format +SR+ (25 ASCII printing characters)
  83
  84 ----------------------------------------------
  85 V=vv S=ss T=t P=pdop E=ee
  86
  87 vv = satellites visible
  88 ss = relative signal strength
  89 t = satellites tracked
  90 pdop = position dilution of precision (meters)
  91 ee = hardware errors
  92 ----------------------------------------------
  93
  94 A three-stage median filter is used to reduce jitter and provide a
  95 dispersion measure. The driver makes no attempt to correct for the
  96 intrinsic jitter of the radio itself.
  97
  98 == Monitor Data
  99
 100 When enabled by the +flag4+ option, an additional line containing
 101 the latitude, longitude, elevation and optional deviation data is
 102 written to the +clockstats+ file. The deviation data operates with an
 103 external pulse-per-second (PPS) input, such as a cesium oscillator or
 104 another radio clock. The PPS input should be connected to the B event
 105 channel and the radio initialized for deviation data on that channel.
 106 The deviation data consists of the mean offset and standard deviation of
 107 the external PPS signal relative the GPS signal, both in microseconds
 108 over the last 16 seconds.
 109
 110 == Driver Options
 111
 112 +unit+ 'number'::
 113   The driver unit number, defaulting to 0. Used as a distinguishing
 114   suffix in the driver device name.
 115 +time1+ 'time'::
 116   Specifies the time offset calibration factor, in seconds and fraction,
 117   with default 0.0.
 118 +time2+ 'time'::
 119   Not used by this driver.
 120 +stratum+ 'number'::
 121   Specifies the driver stratum, in decimal from 0 to 15, with default 0.
 122 +refid+ 'string'::
 123   Specifies the driver reference identifier, an ASCII string from one to
 124   four characters, with default +GPS+.
 125 +flag1 {0 | 1}+::
 126   Not used by this driver.
 127 +flag2 {0 | 1}+::
 128   Not used by this driver.
 129 +flag3 {0 | 1}+::
 130   Not used by this driver.
 131 +flag4 {0 | 1}+::
 132   Enable verbose +clockstats+ recording if set.
 133 +subtype+::
 134   Not used by this driver.
 135 +mode+::
 136   Not used by this driver.
 137 +path+ 'filename'::
 138   Overrides the default device path.
 139 +ppspath+ 'filename'::
 140   Not used by this driver.
 141 +baud+ 'number'::
 142   Overrides the default baud rate.
 143
 144 == Configuration Example
 145
 146 ----------------------------------------------------------------------------
 147 refclock arbiter
 148 ----------------------------------------------------------------------------
 149
 150 == Author
 151
 152 David L. Mills <mills@udel.edu>
 153
 154 == Additional Information
 155
 156 link:refclock.html[Reference Clock Drivers]
 157
 158 == Known bugs
 159
 160 If your Arbiter has firmware made more than 1024 weeks (19 years and 36
 161 weeks) in the past, its internal date counter may wrap around
 162 and generate spurious timestamps.
 163
 164 This problem is fundamental and cannot be compensated for in code
 165 without relying on the accuracy of the local system clock, which
 166 is exactly what an NTP implementation may not do without risking
 167 perverse failure modes (especially at startup time).
 168
 169 The only sure remedy is to be sure the Arbiter's firmware has been
 170 updated within the current GPS era.
 171
 172 '''''
 173
 174 include::includes/footer.adoc[]