GPSD Client HOWTO

This document is a guide to interfacing client applications with GPSD. It surveys the available bindings and their use cases. It also explains some sharp edges in the client API which, unfortunately, are fundamental results of the way GPS sensor devices operate, and suggests tactics for avoiding being cut.

GPSD handles two main kinds of sensors: GPS receivers and AIS receivers. It has rudimentary support for some other kinds of specialized geolocation-related sensors as well, notably compass and yaw/pitch/roll, but those sensors are usually combined with GPS/AIS receivers and behave like them.

In an ideal world, GPS/AIS sensors would be oracles that you could poll at any time to get clean data. But despite the existence of some vendor-specific query and control strings on some devices, a GPS/AIS sensor is not a synchronous device you can query for specified data and count on getting a response back from in a fixed period of time. It gets radio data on its own schedule (usually once per second for a GPS), and emits the reports it feels like reporting asynchronously with variable lag during the following second. If it supports query strings, reports from these are intermixed with the regular reports, and usually scheduled at a lower priority (often with a lag of more than a second).

A GPS/AIS receiver, or any sensor that behaves like one, is in effect a datagram emitter similar to a UDP data source; you get no guarantees about sequence or timing at finer resolution than "TPV roughly once per second" (or whatever the main type of report and report interval is).

The only way to simulate synchronous querying of such a sensor is to have an agent between you and it that caches the data coming out of the device; you can then query the agent and expect a reasonably synchronous response from the cache (we support this for GPSs). However, note that this doesn’t work for a freshly opened device - there’s no cached data.

Consider what this implies for GPses, in particular:

Time to fix after a power-on matters because in many use cases for GPSs they’re running off a battery, and you can’t afford to keep them powered when you don’t actually need location data. This is why GPS sensors are sometimes designed to go to a low-power mode when you close the serial port they’re attached to.

AIS receivers have a simpler set of constraints. They report navigational and ID information from any AIS transmitter in line of sight; there are no skyview issues, and they’re ready instantly when powered up. Furthermore, they’re not normally battery constrained. However, you don’t poll them either; they receive information packets over the air and ship them to you at unpredictable intervals over a serial port.

The design of the GPSD reporting protocol surrenders to reality. Its data packets translate the GPS’s stream of datagrams into device-type-independent datagrams, but it can’t impose timing and sequencing regularities on them that the underlying device doesn’t already obey.

GPSD solves some of the problems with GPS/AIS sensors. First: multiplexing; it allows multiple applications to get sensor data without having to contend for a single serial device. Second: coping with the hideous gallimaufry of badly-designed protocols these devices use — regardless of device type, you will get data in a single well-documented format. Third: on operating systems with a hotplug facility (like Linux udev), GPSD will handle all the device management as USB devices are plugged in and unplugged.

What GPSD can’t do is pull fix data out of thin air when your device hasn’t reported any. Nor is it a magic power supply, so its device management has to be designed around keeping the attached sensors open only when a client application actually needs a fix.

As you’ll see, these constraints explain most of the design of the GPSD wire protocol, and of the library APIs your client application will be using.

While GPSD project ships several library bindings that will hide the details of the wire protocol from you, you’ll understand the library APIs better by knowing what a wire-protocol session looks like. After reading this section, you can forget the details about commands and responses and attributes as long as you hold on to the basic logical flow of a session.

Your client library’s open function is going to connect a socket to port 2947 on the host your sensors are attached to, usually localhost. On connection, the gpsd daemon will ship a banner that looks something like this:

There’s nothing mysterious here. Your server daemon is identifying itself with information that may allow a client library to work around bugs or potential incompatibilities produced by upgrades.

To get data from the attached sensors, you need to explicitly tell the daemon you want it. (Remember that it’s trying to minimize the amount of time the devices are held open and in a fully powered state.) You do this by issuing a WATCH command:

This tells the daemon to watch all devices and to issue reports in JSON. It can ship some other protocols as well (notably, NMEA 0183) but JSON is the most capable and usually what you want.

A side effect of the WATCH command is that the daemon will ship you back some information on available devices.

The DEVICES response tells you what devices are available to the daemon; this list is maintained in a way you as the application designer don’t have to care about. The WATCH response will immediately follow and tells you what all your watch request settings are.

Up to this point, nothing has been dependent on the state of the sensors. At this time, it may well be that none of those devices is fully powered up yet. In fact, they won’t be, unless another GPSD-enabled application is already watching when you open your connection. If that’s the case, you will start seeing data immediately.

For now, though, let’s go back to the case where gpsd has to fire up the sensors. After issuing the WATCH response, the daemon opens all of them and watches for incoming packets that it can recognize. After a variable delay, it will ship a notification that looks something like this:

This is the daemon telling you that it has recognized a SiRF binary GPS on /dev/ttyUSB0 shipping report packets at 4800 bits per second. This notification is not delayed by the time it takes to achieve satellite lock; the GPS will cheerfully ship packets before that. But it will be delayed by the time required for the daemon to sync up with the GPS.

The GPSD daemon is designed so it doesn’t have to know anything about the sensor in advance - not which of a dozen reporting protocols it uses, and not even the baud rate of the serial device. The reason for this agnosticism is so the daemon can adapt properly to anything a hotplug event night throw at it. If you unplug your GPS while your application is running, and then plug in one of a different type, the daemon will cope. Your application won’t know the difference unless you have told it to notice device types.

You can even start your application, have it issue a WATCH, realize you forgot to plug in a GPS, and do that. The hotplug event will tell gpsd, which will add the new device to the watched-devices list of every client that has issued a ?WATCH.

In order to make this work, gpsd has a packet sniffer inside it that does autobauding and packet-protocol detection. Normally the packet sniffer will achieve sync in well under a second (my measured times range from 0.10 to 0.53 sec at 4800bps), but it can take longer if your serial traffic is degraded by dodgy cables or electrical noise, or if the GPS is configured to run at an unusual speed/parity/stopbit configuration.

The real point here is that the delay is variable. The client library, and your application, can’t assume a neat lockstep of request and instant response.

Once you do get your device(s) synced, things become more predictable. The sensor will start shipping fix reports at a constant interval, usually every second, and the daemon will massage them into JSON and pass them up the client to your application.

However, until the sensor achieves satellite lock, those fixes will be "mode 1" - no valid data (mode 2 is a 2D fix, mode 3 is a 3D fix). Here’s what that looks like:

Occasionally you’ll get another kind of sentence, SKY, that reports a satellite skyview. But TPV is the important one. Here’s what it looks like when the sensor has a fix to report:

Note the "mode":3 at the end. This is how you tell that the GPS is reporting a full 3D fix with altitude.

If you have an AIS receiver attached, it too will have been opened and autobauded and protocol-sniffed after your WATCH. The stream of JSON objects will then include things like this:

When your application shuts down, it can cancel its watch:

This will enable the daemon to close devices and conserve power. Supposing you don’t do this, the daemon will time out devices with no listeners, so canceling your watch is not strictly necessary. But it is good manners.

Another way to use the daemon is with the ?POLL command To do this, issue

This activates all devices without enabling streaming of reports. You can then say "?POLL;" to poll gpsd’s recorded data.

This interface is intended for use with applications like CGI scripts that cannot wait on output from the daemon but must poke it into responding.

If you’re a clever sort, you’re already wondering what the daemon does if the application at the other end of the client socket doesn’t read data out of it as fast as gpsd is shipping it upwards. And the answer is this: eventually the socket buffer fills up, a write from the daemon throws an error, and the daemon shuts down that client socket.

From the point of view of the application, it reads all the buffered data and then gets a read return indicating the socket shutdown. We’ll return to this in the discussion of client libraries, but the thing for you to know right now is that this edge case is actually quite difficult to fall afoul of. Total data volume on these sockets is not high. As long as your application checks for and reads socket data no less often than once a second, you won’t — and a second is a lot of time in which to come back around your main loop.

The gpsd daemon exports data in three different ways: via a sockets interface, via DBUS broadcasts, and via a shared-memory interface, It is possible one or more of these may be configured out in your installation.

The source distribution includes two example clients in C; gpxlogger.c and cgps.c.

gpxlogger.c illustrates the simplest possible program flow; open, followed by stream, followed by the library main loop.

cgps.c shows what an interactive application using the library and also hw processing user commands works. Note the use of the curses nodelay function to ensure that wgetch() does not block the GPS polling loop.

The following code skeleton implements a C++ client:

Note the absence of explicit open and close methods. The object interface is designed on the RAII (Resource Acquisition Is Initialization) model; you close it by deallocating it.

Look at test_gpsmm.cpp in the distribution for a full example.

There’s a very simple Python example analogous to gpxlogger attached to the source code for the gps.py library.

The heart of it is this code:

If you need to intersperse other processing in a main event loop, like this:

Each call to session.read() will fill session.response with the message just received from gpsd. If that message was gpsd JSON then the JSON fields are decoded into session.data. When the daemon terminates, session.read() will return non-zero, and then the loop will terminate.

The session.data object can be accessed either as a dictionary or as an object. As a dictionary, it is the raw contents of the last JSON response re-encoded in plain ASCII. For convenience, you may also access it as an object with members for each attribute in the dictionary. It is especially useful to know that the object will always have a "class" member giving the response type (TPV, SKY, DEVICE, etc.) as a string.

See "Gpsd Client Example Code" for more client code examples.

For more interesting examples integrated with X and GTK, see xgps and xgpsspeed.

There are a couple of client bindings for GPSD that are maintained separately from the GPSD distribution. We don’t try to document their APIs here, but just provide pointers to them.

There is a Java binding, described at http://gpsd4java.forge.hoegergroup.de/ This binding is available at maven central. See that web page for how to use it in a maven build.

There’s a Perl client library at http://search.cpan.org/dist/Net-GPSD3/

The C/C++ binding makes available two preprocessor symbols, GPSD_API_MAJOR_VERSION and GPSD_API_MINOR_VERSION, in gps.h. The Python module has corresponding symbols.

In major versions before 5: