= Spectracom
include::include-html.ad[]

== Synopsis

["verse",subs="normal"]
Name: spectracom
Reference ID: GPS
Serial Port: +/dev/spectracom+'u'; 9600 bps 8N1
Features: Optional PPS signal processing, +tty_clk+
Requires: Optional PPS signal processing requires the PPSAPI signal interface.

== 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 "Type 2" format emitted by Spectracom time
servers including the 9483, 9489, and SecureSync.

In former times this driver supported the Spectracom 9300 (now
end-of-lifed) and several models of Spectracom radio clocks that were
obsolesced by the WWVB modulation change at 2012-10-29T15:00:00Z.

There are two timecode formats used by these clocks. Format 0, which is
available with all clocks, and format 2, which is available with all
clocks except the obsolete Model 8170. Consult your vendor documentation
for information on how to enable these formats.

 Format 0 (22 ASCII printing characters):
 <cr><lf>i ddd hh:mm:ss TZ=zz<cr><lf>

 on-time = first <cr>
 i = synchronization flag (' ' = in synch, '?' = out synch)
 hh:mm:ss = hours, minutes, seconds

The alarm condition is indicated by other than ' ' at +i+, which occurs
during initial synchronization and when received signal is lost for
about ten hours.

 Format 2 (24 ASCII printing characters):
 <cr>lf>iqyy ddd hh:mm:ss.fff ld

 on-time = <cr>
 i = synchronization flag (' ' = in synch, '?' = out synch)
 q = quality indicator (' ' = locked, 'A'...'D' = unlocked)
 yy = year (as broadcast)
 ddd = day of year
 hh:mm:ss.fff = hours, minutes, seconds, milliseconds

The alarm condition is indicated by other than ' ' at +i+, which occurs
during initial synchronization and when received signal is lost for
about ten hours. The unlock condition is indicated by other than ' ' at
+q+.

The +q+ is normally ' ' when the time error is less than 1 ms and a
character in the set +A...D+ when the time error is less than 10, 100,
500 and greater than 500 ms respectively. The +l+ is normally ' ', but
is set to +L+ early in the month of an upcoming UTC leap second and
reset to ' ' on the first day of the following month. The +d+ is set to
+S+ for standard time +S+, +I+ on the day preceding a switch to daylight
time, +D+ for daylight time and +O+ on the day preceding a switch to
standard time. The start bit of the first <cr> is synchronized to the
indicated time as returned.

This driver does not need to be told which format is in use - it figures
out which one from the length of the message. 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, which is a known problem with the older radios.

== PPS Signal Processing

When PPS signal processing is enabled; and when the system clock has
been set by this or another driver; and the PPS signal offset is within
0.4 s of the system clock offset; then the  PPS signal replaces the timecode
for as long as the PPS signal is active. If for some reason the PPS
signal fails for one or more poll intervals, the driver reverts to the
timecode. If the timecode fails for one or more poll intervals, the PPS
signal is disconnected.

== Monitor Data

The driver writes each timecode as received to the +clockstats+ file.
When enabled by the +flag4+ option, a table of quality data
maintained internally by the Netclock/2 is retrieved and written to the
+clockstats+ file when the first timecode message of a new day is
received.

== 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 PPS time offset calibration factor, in seconds and
  fraction, with default 0.0.
+time2+ 'time'::
  Specifies the serial time offset calibration factor, in seconds and
  fraction, with default 0.0.
+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}+::
  Disable PPS signal processing if 0 (default); enable PPS signal
  processing if 1.
+flag2 {0 | 1}+::
  If PPS signal processing is enabled, capture the pulse on the rising
  edge if 0 (default); capture on the falling edge if 1.
+flag3 {0 | 1}+::
  If PPS signal processing is enabled, use the +ntpd+ clock discipline
  if 0 (default); use the kernel discipline if 1.
+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 spectracom
----------------------------------------------------------------------------

== Author

David L. Mills <mills@udel.edu>

'''''

include::includes/footer.adoc[]
