docs/driver_oncore.adoc

   1 = Motorola Oncore GPS receiver
   2 include::include-html.ad[]
   3
   4 == Synopsis
   5
   6 ["verse",subs="normal"]
   7 Name: oncore
   8 Reference ID: GPS
   9 Serial Port: /dev/oncore.serial._u_; 9600 bps 8N1.
  10 PPS Port: /dev/oncore.pps._u_
  11
  12 == Deprecation warning
  13
  14 This refclock is deprecated and obsolete; the entire Oncore line has
  15 been end-of-lifed. The NTPsec maintainers plan to remove it in a
  16 future release.  If you have a requirement for it, please make this
  17 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 most models of the
  31 https://web.archive.org/web/19990427102123/http://www.mot.com/AECS/PNSB/products/produt.html[Motorola Oncore GPS receivers]
  32 (Basic, PVT6, VP, UT, UT+, GT, GT+, SL, M12, M12+T), as long as they
  33 support the _Motorola Binary Protocol_. All are long end-of-lifed as of 2019.
  34
  35 The (formerly) interesting versions of the Oncore were the VP, the
  36 UT+, the "Remote" which is a prepackaged UT+, and the M12 Timing
  37 variant.
  38
  39 However, there is one current hardware product that is reported good
  40 with this driver; the
  41 https://www.cnssys.com/cnsclock/CNSClockII.php[CNS Clock II].  It
  42 ships 1PPS on the DCD line of its RS232 port or as a DCD priority
  43 packet on USB.  Older revisions of the product used M12 hardware,
  44 newer ones use a u-blox engine but emulate OnCore behavior.  Future
  45 versions will drop OnCore reporting entirely, at which time the
  46 possibility of removing this driver will be revisited.
  47
  48 See the CNS Clock vendor product page for specifications.
  49
  50 We expect this should also work with the Furuno line of
  51 M12 compatibles, including the GT8736 and (now discontinued) GT8536,
  52 but we don't yet have confirmation from the field.
  53
  54 The driver can use use the "position hold" mode with user provided
  55 coordinates, the receiver's built-in site-survey, or a similar algorithm
  56 implemented in this driver to determine the antenna position.
  57
  58 == Monitor Data
  59
  60 The driver always puts a lot of useful information in the clockstats
  61 file, and when run with debugging can be quite chatty on stdout. When
  62 first starting to use the driver you should definitely review the
  63 information written to the clockstats file to verify that the driver is
  64 running correctly.
  65
  66 In addition, on platforms supporting Shared Memory, all of the messages
  67 received from the Oncore receiver are made available in shared memory
  68 for use by other programs. See the link:oncore-shmem.html[Oncore-SHMEM]
  69 manual page for information on how to use this option. For either
  70 debugging or using the SHMEM option, an Oncore Reference Manual for the
  71 specific receiver in use will be required.
  72
  73 == Driver Options
  74
  75 +unit+ 'number'::
  76   The driver unit number, defaulting to 0. Used as a distinguishing
  77   suffix in the driver device name.
  78 +time1+ 'time'::
  79    Specifies the time offset calibration factor, in seconds and fraction,
  80    with default 0.0.
  81 +time2+ 'time'::
  82    Not used by this driver.
  83 +stratum+ 'number'::
  84    Specifies the driver stratum, in decimal from 0 to 15, with default 0.
  85 +refid+ 'string'::
  86    Specifies the driver reference identifier, an ASCII string from one to
  87    four characters, with default +GPS+.
  88 +flag1 {0 | 1}+::
  89    Not used by this driver.
  90 +flag2 {0 | 1}+::
  91    Not used by this driver.
  92 +flag3 {0 | 1}+::
  93    Not used by this driver.
  94 +flag4 {0 | 1}+::
  95    Not used by this driver.
  96 +subtype+::
  97    Not used by this driver.
  98 +mode+::
  99    Not used by this driver.
 100 +path+::
 101    Not used by this driver.
 102 +ppspath+::
 103    Not used by this driver.
 104 +baud+ 'number'::
 105    Not used by this driver.
 106
 107 == Configuration Example
 108
 109 ----------------------------------------------------------------------------
 110 refclock oncore
 111 ----------------------------------------------------------------------------
 112
 113 == Additional Information
 114
 115 The driver was initially developed on FreeBSD, and has since been tested
 116 on Linux, SunOS and Solaris.
 117
 118 === Configuration
 119
 120 There is a driver specific configuration file +ntp.oncore+ (or
 121 +ntp.oncore.+'u' or +ntp.oncore+'u' if you must distinguish between more
 122 than one Oncore receiver _unit_) that contains information on the startup mode,
 123 the location of the GPS receiver, an offset of the PPS signal from zero,
 124 and the cable delay. The offset shifts the PPS signal to avoid interrupt
 125 pileups `on' the second, and adjusts the timestamp accordingly. See the
 126 driver source for information on this file. The default with no file is:
 127 no delay, no offset, and a site survey is done to get the location of
 128 the gps receiver.
 129
 130 The following three options can be set in the driver specific
 131 configuration file only if the driver is using the PPSAPI. The edge of
 132 the PPS signal that is `on-time' can be set with the keywords
 133 [ASSERT/CLEAR] and the word HARDPPS will cause the PPS signal to control
 134 the kernel PLL.
 135
 136 === Performance
 137
 138 Even the newest of the Motorola variants, the M12+T with firmware dated 9 Jun
 139 2004 now reports bad dates due to era rollover.
 140
 141 Performance is really good, other than the rollover issue. With the
 142 VP/UT+, the generated PPS pulse is referenced to UTC(GPS) with better
 143 than 50 ns (1 sigma) accuracy. The limiting factor will be the
 144 timebase of the computer and the precision with which you can
 145 timestamp the rising flank of the PPS signal. Using FreeBSD, a FPGA
 146 based Timecounter/PPS interface, and an ovenized quartz oscillator,
 147 that performance has been reproduced. For more details on this aspect:
 148 https://web.archive.org/web/19990221121441/http://phk.freebsd.dk/rover.html[Sub-Microsecond
 149 timekeeping under FreeBSD].
 150
 151 '''''
 152
 153 include::includes/footer.adoc[]