GPSD

This feature is only available on certain products and models (not available with all devices).

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.

Using gpsd with the gpsd python library

The gpsd python library is contained in the following package:

python-pygps

This library is provided on the mLinux image, and from the Downloads page, the item named Pre-built Packages.

Using the library in a python script will require the following import statement:

from gps import *

You can download an example here:

testgps.txt

Note: You need to rename  the file as testgps.py.

Output of testgps.py:

$ testgps.py
fix          3
longitude    -93.196113443
latitude     45.099362019
time utc     2017-11-28T20:41:00.000Z
altitude     285.846
epv          8.74
ept          0.005
speed        0.101
climb        -0.025

Satellites (total of 14  in view)
PRN:   1  E:  18  Az: 319  Ss:  37  Used: y
PRN:  10  E:  67  Az: 117  Ss:  23  Used: n
PRN:  11  E:  19  Az: 303  Ss:  36  Used: y
PRN:  12  E:  18  Az:  79  Ss:  16  Used: n
PRN:  14  E:  59  Az: 268  Ss:  45  Used: y
PRN:  18  E:  35  Az: 125  Ss:  17  Used: n
PRN:  22  E:   5  Az: 303  Ss:  26  Used: n
PRN:  24  E:  20  Az:  46  Ss:  21  Used: y
PRN:  25  E:  15  Az: 117  Ss:  21  Used: n
PRN:  31  E:  25  Az: 197  Ss:  38  Used: y
PRN:  32  E:  76  Az: 305  Ss:  41  Used: y
PRN: 131  E:  33  Az: 212  Ss:  40  Used: n
PRN: 135  E:  25  Az: 230  Ss:  37  Used: y
PRN: 138  E:  36  Az: 200  Ss:  36  Used: y

The python library contains a test program.  To execute the test program:

$ /usr/lib/python2.7/site-packages/gps/gps.py
<dictwrapper: {u'release': u'3.16', u'proto_major': 3, u'rev': u'3.16', u'class': u'VERSION', u'proto_minor': 11}>
<dictwrapper: {u'class': u'DEVICES', u'devices': [{u'parity': u'N', u'activated': u'2017-11-28T20:44:46.191Z', u'driver': u'u-blox', u'subtype': u'SW ROM CORE 3.01 (107888),HW 00080000,FWVER=SPG 3.01,PROTVER=18', u'bps': 115200, u'flags': 1, u'stopbits': 1, u'path': u'/dev/ttyXRUSB2', u'cycle': 1.0, u'class': u'DEVICE', u'mincycle': 0.25, u'native': 1}, {u'path': u'/dev/pps0', u'driver': u'PPS', u'class': u'DEVICE', u'activated': u'2017-11-28T20:44:46.145Z'}]}>
<dictwrapper: {u'pps': False, u'enable': True, u'scaled': False, u'raw': 0, u'json': True, u'nmea': False, u'timing': False, u'class': u'WATCH', u'split24': False}>
<dictwrapper: {u'clock_sec': 1511901887, u'class': u'PPS', u'precision': -20, u'device': u'/dev/pps0', u'real_sec': 1511901883, u'clock_nsec': 144284282, u'real_nsec': 0}>
<dictwrapper: {u'clock_sec': 1511901887, u'class': u'PPS', u'precision': -20, u'device': u'/dev/pps0', u'real_sec': 1511901883, u'clock_nsec': 144284282, u'real_nsec': 0}>

 

There is a gpsd library for C++, C, Java, and perl.  For more information see:

http://catb.org/gpsd/client-howto.html