GPSD-NG client driver

### GPSD NG client driver

Last update: 1-Mar-2014 03:48 UTC

#### Synopsis

Address: 127.127.46.u
Reference ID: `GPSD`
Driver ID: `GPSD_JSON`
Serial Port: `/dev/gpsu` as symlink to the true device (not used directly; see below)
Features: ``

#### Description

This driver is a client driver to the GPSD daemon, which over the time became increasingly popular for UN*Xish platforms. GPSD can manage several devices in parallel, aggregate information, and acts as a data hub for client applications. GPSD can also auto-detect and handle PPS hardware signals on serial ports. Have a look at the GPSD project page.

It is important to understand that this driver works best using a GPS device with PPS support.

The GPSD-NG protocol is text based, using JSON notation to transfer records in form of JSON objects. The driver uses a TCP/IP connection to `localhost:gpsd` to connect to the daemon and then requests the GPS device `/dev/gpsu` to be watched. (Different clock units use different devices, and GPSD is able to give only the relevant information to a clock instance.)

This driver does not expect GPSD to be running or the clock device to be present a priori; it will try to re-establish a lost or hitherto unsuccessful connection and will wait for device to come up in GPSD. There is an initial 10 seconds delay between a connection loss or failed attempt and the next reconnect attempt; this makes sure that there is no thrashing on the network layer. If the connection fails again, an exponential back off is used with an upper limit of approximately 10 minutes.

The overall accuracy depends on the receiver used. The driver uses the error estimations (95% probability limits) provided by GPSD to set the clock precision dynamically according to these readings.

The driver needs the VERSION, TPV, PPS and WATCH objects of the GPSD protocol. (Others are quietly ignored.)

#### Naming a Device

The GPSD driver uses the same name as the NMEA driver, namely `/dev/gpsu`. There is a simple reason for that: While the NMEA driver and the GPSD driver can be active at the same time for different devices, they cannot access the same device at a time. Having the same name helps on that. It also eases migration from using NMEA directly to using GPSD, as no new links etc need to be created.

GPSD is normally started with the device name to access; it can also be instructed by hot-plug scripts to add or remove devices from its device pool. Luckily, the symlinks used by the NMEA driver are happily accepted and used by GPSD; this makes it possible to use the symlink names as device identification. This makes the migration from the built-in NMEA driver a bit easier.

Note: GPSD (as of version 3.10) cannot use kernel mode PPS on devices that are hot-plugged. This would require to attach the PPS line discipline to the file, which is not possible when running with root privileges dropped. This is not likely to change in the future.

#### The 'mode' byte

A few operation modes can be selected with the mode word.

The Mode Word
Bits | Value | Description
0..1 | 0 | Uses TPV to get absolute time stamps for full synchronization. If PPS is available , it is used to improve the precision, but the clock can work without it.
1 | Require TPV and PPS to work.
2 | Ignore PPS data, run on TPV only. This is not a recommended mode unless the serial timing is very stable and GPSD provides an information element in TPV that indicates the receive time of the fix data.
3 | PPS-only mode. Ignores TPV and does only the PPS phase correction. This means that some other source must get NTPD close to synchronisation; only after that happened and the phase shift between the system clock and the PPS pulse is less than 125msec the PPS lock will be engaged.
IMPORTANT: work in progress, mode word ignored right now. Fixed mode '0' operation.

#### Syslog flood throttle

This driver can create a lot of syslog messages when things go wrong, and cluttering the log files is frowned upon. So we attempt to log persistent or recurring errors only once per hour. On the other hand, when tracking a problem the syslog flood throttle can get into the way.

Therefore, fudge flag3 can be used to disable the flood throttle at any time; the throttle is engaged by default. Running with the syslog flood throttle disabled for lengthy time is not recommended unless the log files are closely monitored.

#### Fudge Factors

`time1 time`
  Specifies the PPS time offset calibration factor, in seconds and fraction, with default 0.0.
`time2 time`
  Specifies the TPV 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 `GPSD`.
`flag1 0 | 1`
  (not used)
`flag2 0 | 1`
  (not used)
`flag3 0 | 1`
  If set, disable the log throttle. Useful when tracking problems in the interaction between GPSD and NTPD, since now all error events are logged. Persistent/recurrent errors can easily fill up the log, so this should only be enabled during bug hunts.
`flag4 0 | 1`
  If set, write a clock stats line on every poll cycle.

Additional Information

Reference Clock Drivers