GPSD

GPSD Overview

GPSD is the server that monitors the GPS (if included with your device) and makes time and position information available to client programs, such as gpsmon and NTPD.  GPSD communicates with NTPD via shared memory to provide the GPS time.  The server allows multiple programs to use the GPS.  It also detects leap second and tells NTPD of an upcoming leap second and its direction on the day of the leap second.

The script /usr/sbin/gpsd_ubx_fixed has no parameters, but uses the file /etc/default/gpsd which contains the parameter, GPSFIX, as a criteria to determine if the GPS currently has a fix (lock) on the satellites. If there is a fix, it creates a file /var/run/gpsfix, with the contents equal to the actual GPS fix value found. Otherwise the file is deleted. The script /usr/sbin/gpsd_ubx_settime checks for a GPS fix. If so, it sets the system clock to the GPS time, first using the GPS, in case there is a huge change, then using ntpd -gq to get it much closer.

NTP/NTPD ultimately manages the time based reliability and availability of time sources (with top priority going to the GPS time). For more information on NTPD and how it manages time, see the NTPD page.

Here are the key files for setup of the GPSD on the device:

  • GPSD configuration file is located in /etc/default/gpsd. This file is set up for u-Blox, the proprietary communications protocol for the u-Blox chip used on the device.
  • GPSD init script is located in /etc/init.d/gpsd. This file can be used to start GPSD manually.
  • mtsio configuration file is located in /etc/default/mts-io. This determines whether or not the GPS is reset during boot. After a reset, the GPS takes some time to acquire the satellite information.
  • gpsfix file is created after the GPS has a fix on the satellites indicating that the GPS now has valid data.

GPSD configuration file

Here is the default configuration file, /etc/default/gpsd:

ENABLED="yes"
GPSD_SOCKET="/var/run/gpsd.sock"
GPSD_OPTIONS="-n -D 1"

# Conduit 0.1 GPS devices
GPS_LINE=/dev/ttyXRUSB2

# Highest speed permitted by uBlox.
GPS_BAUD=115200
GPS_DEVICES="$GPS_LINE /dev/pps0"

GPS_FIXFILE=/var/run/gpsfix

# GPSD/UBlox Lock requirement
# Create GPS_FIXFILE when reached.
# UBlox NAV SOL (0x01 0x06) at gpsFix value
# and above
# 00 No Fix
# 01 Dead reckoning only
# 02 2D fix
# 03 3D fix
# 04 GPS + dead reckoning combined
# 05 Time only fix
GPSFIX="03 05"

The GPSD program uses the uBlox proprietary binary message mode to communicate with the GPS as the most efficient method.

Here are the major elements of the GPSD configuration file:.

  • GPSD_SOCKET can be used to communicate with GPSD.
  • GPSD_OPTIONS for the program include:
    • -D specifies the debug level. We use 1 in the example file above.
    • -n causes the GPSD daemon to immediately start communicating with the GPS.
    • GPS_LINE indicates the Serial driver name for the GPS.
    • GPS_BAUD shows baud rate set to 115200. At a baud rate of 9600, the device does not get the GPS messages quickly enough.
    • GPS_FIXFILE contains GPSFIX level as contents. This file indicates the GPS is ready to use.
    • GPSFIX assigns the valid FIX values that should be found in the NAV SOL message from the GPS. The values indicate the GPS is ready to use.

gpsmon utility

The GPS output may be observed using the gpsmon utility. gpsmon works best using ssh and ethernet with the device.

To run the utility, enter the following command:

mtcdt: gpsmon

The resulting output displays:

Notice the box with the label NAV_SOL at the bottom. In this box, the bottom line is Fix 0×03. This is one of the acceptable values mentioned in /etc/default/gpsd for GPSFIX.

With the value of GPSFIX set to 03 05 in the configuration file, either 0×03 or 0×05 is acceptable in the gpsmon output.

Bash script to check GPS status

This bash script is located in  /usr/sbin/gpsd_ubx_fixed on the device. It uses the utility, gpsmon, to determine when the GPS fix field in the UBX NAV SOL message indicates a fix matching one of the fixes of the GPSFIX variables specified in the configuration file (/etc/default/gpsd). The fix choices in the GPSFIX variable are space separated and the values are in hex, but no value over 05 is allowed.

Here is how the bash script works:

1. To execute the bash script, enter the command:

mtcdt: /usr/sbin/gpsd_ubx_fixed

2. The script returns an exit status of 0 if one of the fixes specified is achieved.

3. One of the following occurs next:

a. If the script executes and one of the GPSFIX values is achieved, the GPS fix field value is placed in the file GPS_FIXFILE, as specified in /etc/default/gpsd.

OR

b. If the fix value is not one of the values specified in GPSFIX, the file GPS_FIXFILE is removed. The GPS is not ready yet. Wait and try again.

4. From powerup, it takes six to ten minutes before the GPS fix reaches 0×03, which is a 3D fix.

Bash script to set the system clock

This bash script sets the system clock using gpsmon output if /usr/sbin/gpsd_ubx_fixed indicates the GPS fix.

To execute this script, enter the following:

mtcdt:/usr/sbin/gpsd_ubx_settime

This is needed prior to starting NTPD to prevent the GPS from being marked as a falseticker.