= Arbiter 1088A/B GPS Receiver
include::include-html.ad[]

== Synopsis

["verse",subs="normal"]
Name: arbiter
Reference ID: GPS
Driver ID: GPS_ARBITER
Serial Port: /dev/gps__u__; 9600 bps 8N1
Features: tty_clk

== Deprecation warning

This refclock is deprecated and obsolete. 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.

It is likely any surving instances of this hardware will have
era-rollover issues when reporting dates. One or more "g" suffixes
on your 'time1' option may be useful as a workaround.

== Description

This driver supports the Arbiter 1088A/B Satellite Controlled Clock. The
claimed accuracy of this clock is 100 ns relative to the PPS output when
receiving four or more satellites.

The receiver should be configured before starting the NTP daemon, in
order to establish reliable position and operating conditions. It does
not initiate surveying or hold mode. For use with NTP, the daylight
savings time feature should be disables (+D0+ command) and the broadcast
mode set to operate in UTC (+BU+ command).

The timecode format supported by this driver is selected by the poll
sequence +B5+, which initiates a line in the following format to be
repeated once per second until turned off by the +B0+ command.

Format +B5+ (24 ASCII printing characters):

-------------------------------------------------------
<cr><lf>i yy ddd hh:mm:ss.000bbb

on-time = <cr>
i = synchronization flag (' ' = locked, '?' = unlocked)
yy = year of century
ddd = day of year
hh:mm:ss = hours, minutes, seconds
.000 = fraction of second (not used)
bbb = tailing spaces for fill
-------------------------------------------------------

The alarm condition is indicated by a \'?' at i, which indicates the
receiver is not synchronized. In normal operation, a line consisting of
the timecode followed by the time quality character (TQ) followed by the
receiver status string (SR) is written to the clockstats file.

The time quality character is encoded in IEEE P1344 standard:

Format +TQ+ (IEEE P1344 estimated worst-case time quality)

-----------------------------------------
0       clock locked, maximum accuracy
F       clock failure, time not reliable
4       clock unlocked, accuracy < 1 us
5       clock unlocked, accuracy < 10 us
6       clock unlocked, accuracy < 100 us
7       clock unlocked, accuracy < 1 ms
8       clock unlocked, accuracy < 10 ms
9       clock unlocked, accuracy < 100 ms
A       clock unlocked, accuracy < 1 s
B       clock unlocked, accuracy < 10 s
-----------------------------------------

The status string is encoded as follows:

Format +SR+ (25 ASCII printing characters)

----------------------------------------------
V=vv S=ss T=t P=pdop E=ee

vv = satellites visible
ss = relative signal strength
t = satellites tracked
pdop = position dilution of precision (meters)
ee = hardware errors
----------------------------------------------

A three-stage median filter is used to reduce jitter and provide a
dispersion measure. The driver makes no attempt to correct for the
intrinsic jitter of the radio itself.

== Monitor Data

When enabled by the +flag4+ option, an additional line containing
the latitude, longitude, elevation and optional deviation data is
written to the +clockstats+ file. The deviation data operates with an
external pulse-per-second (PPS) input, such as a cesium oscillator or
another radio clock. The PPS input should be connected to the B event
channel and the radio initialized for deviation data on that channel.
The deviation data consists of the mean offset and standard deviation of
the external PPS signal relative the GPS signal, both in microseconds
over the last 16 seconds.

== 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}+::
  Enable verbose +clockstats+ recording if set.
+subtype+::
  Not used by this driver.
+mode+::
  Not used by this driver.
+path+ 'filename'::
  Overrides the default device path.
+ppspath+ 'filename'::
  Not used by this driver.
+baud+ 'number'::
  Overrides the default baud rate.

== Configuration Example

----------------------------------------------------------------------------
refclock arbiter
----------------------------------------------------------------------------

== Author

David L. Mills <mills@udel.edu>

== Additional Information

link:refclock.html[Reference Clock Drivers]

== Known bugs

If your Arbiter has firmware made more than 1024 weeks (19 years and 36
weeks) in the past, its internal date counter may wrap around
and generate spurious timestamps.

This problem is fundamental and cannot be compensated for in code
without relying on the accuracy of the local system clock, which
is exactly what an NTP implementation may not do without risking
perverse failure modes (especially at startup time).

The only sure remedy is to be sure the Arbiter's firmware has been
updated within the current GPS era.

'''''

include::includes/footer.adoc[]
