= Motorola Oncore GPS receiver =

== Synopsis ==

["verse",subs="normal"]
Name: oncore
Reference ID: GPS
Serial Port: /dev/oncore.serial._u_; 9600bps 8N1.
PPS Port: /dev/oncore.pps._u_

== Deprecation warning ==

This refclock is deprecated and obsolete; the entire Oncore line has
been end-of-lifed. The NTPsec maintainers plan to remove it in a
future release.  If you have a requirement for it, please make this
known to us.

This driver reports only two-digit years, and is thus reliant on the
system clock to be near correct before samples will be processed
properly. You will not be able to use it to run autonomously, nor will
it reliably recover from a trashed or zeroed system clock.

== Description ==

This driver supports most models of the
https://web.archive.org/web/19990427102123/http://www.mot.com/AECS/PNSB/products/produt.html[Motorola Oncore GPS receivers]
(Basic, PVT6, VP, UT, UT+, GT, GT+, SL, M12, M12+T), as long as they
support the _Motorola Binary Protocol_.

The (formerly) interesting versions of the Oncore were the VP, the
UT+, the "Remote" which is a prepackaged UT+, and the M12 Timing. The
Motorola evaluation kit can be recommended. It interfaces to a PC
straightaway, using the serial (DCD) or parallel port for PPS input
and packs the receiver in a nice and sturdy box. Less expensive
interface kits are available from http://www.tapr.org[TAPR].

[width="100%",cols="<34%,<33%,<33%",align="center",frame="none",grid="none"]
|==========================================================================
|image:pic/oncore_utplusbig.gif[]|image:pic/oncore_evalbig.gif[]|image:pic/oncore_remoteant.jpg[gif]
|UT+ oncore                      |Evaluation kit                |Oncore Remote
|==========================================================================

The driver requires a standard +PPS+ interface for the pulse-per-second
output from the receiver. The serial data stream alone does not provide
precision time stamps (0-50msec variance, according to the manual),
whereas the PPS output is precise down to 50 nsec (1 sigma) for the
VP/UT models and 25 nsec for the M12 Timing. If you do not have the PPS
signal available, then you should probably be using the NMEA driver
rather than the Oncore driver. Most of these are available on-line

The driver will use the "position hold" mode with user provided
coordinates, the receivers built-in site-survey, or a similar algorithm
implemented in this driver to determine the antenna position.

== Monitor Data ==

The driver always puts a lot of useful information on the clockstats
file, and when run with debugging can be quite chatty on stdout. When
first starting to use the driver you should definitely review the
information written to the clockstats file to verify that the driver is
running correctly.

In addition, on platforms supporting Shared Memory, all of the messages
received from the Oncore receiver are made available in shared memory
for use by other programs. See the link:oncore-shmem.html[Oncore-SHMEM]
manual page for information on how to use this option. For either
debugging or using the SHMEM option, an Oncore Reference Manual for the
specific receiver in use will be required.

== Driver Options ==

+unit+ 'number'::
  The driver unit number, defaulting to 0. Used as a distinguishing
  suffix in the driver device name. 
+time1+ 'time'::
   Specifies the time offset calibration factor, in seconds and fraction,
   with default 0.0.
+time2+ 'time'::
   Not used by this driver.
+stratum+ 'number'::
   Specifies the driver stratum, in decimal from 0 to 15, with default 0.
+refid+ 'string'::
   Specifies the driver reference identifier, an ASCII string from one to
   four characters, with default +GPS+.
+flag1 {0 | 1}+::
   Not used by this driver.
+flag2 {0 | 1}+::
   Not used by this driver.
+flag3 {0 | 1}+::
   Not used by this driver.
+flag4 {0 | 1}+::
   Not used by this driver.
+subtype+::
   Not used by this driver.
+mode+::
   Not used by this driver.
+path+::
   Not used by this driver.
+ppspath+::
   Not used by this driver.
+baud+ 'number'::
   Not used by this driver.

== Configuration Example ==

----------------------------------------------------------------------------
refclock oncore
----------------------------------------------------------------------------

== Additional Information ==

The driver was initially developed on FreeBSD, and has since been tested
on Linux, SunOS and Solaris.

=== Configuration ===

There is a driver specific configuration file +ntp.oncore+ (or
+ntp.oncore.+'u' or +ntp.oncore+'u' if you must distinguish between more
than one Oncore receiver _unit_) that contains information on the startup mode,
the location of the GPS receiver, an offset of the PPS signal from zero,
and the cable delay. The offset shifts the PPS signal to avoid interrupt
pileups `on' the second, and adjusts the timestamp accordingly. See the
driver source for information on this file. The default with no file is:
no delay, no offset, and a site survey is done to get the location of
the gps receiver.

The following three options can be set in the driver specific
configuration file only if the driver is using the PPSAPI. The edge of
the PPS signal that is `on-time' can be set with the keywords
[ASSERT/CLEAR] and the word HARDPPS will cause the PPS signal to control
the kernel PLL.

=== Performance ===

Even the newest of these variants, the M12+T with firmware dated 9 Jun
2004 now reports bad dates due to era rollover.

Performance is really good, other than the rollover issue. With the
VP/UT+, the generated PPS pulse is referenced to UTC(GPS) with better
than 50 nsec (1 sigma) accuracy. The limiting factor will be the
timebase of the computer and the precision with which you can
timestamp the rising flank of the PPS signal. Using FreeBSD, a FPGA
based Timecounter/PPS interface, and an ovenized quartz oscillator,
that performance has been reproduced. For more details on this aspect:
https://web.archive.org/web/19990221121441/http://phk.freebsd.dk/rover.html[Sub-Microsecond
timekeeping under FreeBSD].

'''''

include::includes/footer.txt[]
