Table 1. TPV object

When the C client library parses a response of this kind, it will assert validity bits in the top-level set member for each field actually received; see gps.h for bitmask names and values.

Here's an example:

{"class":"TPV","device":"/dev/pts/1",


    "time":"2005-06-08T10:34:48.283Z","ept":0.005,


    "lat":46.498293369,"lon":7.567411672,"alt":1343.127,


    "eph":36.000,"epv":32.321,


    "track":10.3788,"speed":0.091,"climb":-0.085,"mode":3}

Table 2. SKY object

Many devices compute dilution of precision factors but do not include them in their reports. Many that do report DOPs report only HDOP, two-dimensional circular error.
gpsd always passes through whatever the device actually reports, then attempts to fill in other DOPs by calculating the appropriate determinants in a covariance matrix based on the satellite view. DOPs may be missing if some of these determinants are singular. It can even happen that the device reports an error estimate in meters when the corresponding DOP is unavailable; some devices use more sophisticated error modeling than the covariance calculation.

The satellite list objects have the following elements:

Table 3. Satellite object

Note that satellite objects do not have a "class" field, as they are never shipped outside of a SKY object.

When the C client library parses a SKY response, it will assert the SATELLITE_SET bit in the top-level set member.

Here's an example:

{"class":"SKY","device":"/dev/pts/1",


    "time":"2005-07-08T11:28:07.114Z",


    "xdop":1.55,"hdop":1.24,"pdop":1.99,


    "satellites":[


        {"PRN":23,"el":6,"az":84,"ss":0,"used":false},


        {"PRN":28,"el":7,"az":160,"ss":0,"used":false},


        {"PRN":8,"el":66,"az":189,"ss":44,"used":true},


        {"PRN":29,"el":13,"az":273,"ss":0,"used":false},


        {"PRN":10,"el":51,"az":304,"ss":29,"used":true},


        {"PRN":4,"el":15,"az":199,"ss":36,"used":true},


        {"PRN":2,"el":34,"az":241,"ss":43,"used":true},


        {"PRN":27,"el":71,"az":76,"ss":43,"used":true}]}

Table 4. GST object

Here's an example:

{"class":"GST","device":"/dev/ttyUSB0",


        "time":"2010-12-07T10:23:07.096Z","rms":2.440,


        "major":1.660,"minor":1.120,"orient":68.989,


        "lat":1.600,"lon":1.200,"alt":2.520}

The "class" and "mode" fields will reliably be present. Others may be reported or not depending on the specific device type.

Table 5. ATT object

The heading, pitch, and roll status codes (if present) vary by device. For the TNT Revolution digital compasses, they are coded as follows:

Table 6. Device flags

When the C client library parses a response of this kind, it will assert ATT_IS.

Here's an example:

{"class":"ATT","time":1270938096.843,


    "heading":14223.00,"mag_st":"N",


    "pitch":169.00,"pitch_st":"N", "roll":-43.00,"roll_st":"N",


    "dip":13641.000,"mag_x":2454.000}

Table 7. VERSION object

The daemon ships a VERSION response to each client when the client first connects to it.

When the C client library parses a response of this kind, it will assert the VERSION_SET bit in the top-level set member.

Here's an example:

{"class":"VERSION","version":"2.40dev",


    "rev":"06f62e14eae9886cde907dae61c124c53eb1101f",


    "proto_major":3,"proto_minor":1
}

Table 8. DEVICES object

When the C client library parses a response of this kind, it will assert the DEVICELIST_SET bit in the top-level set member.

Here's an example:

{"class"="DEVICES","devices":[


    {"class":"DEVICE","path":"/dev/pts/1","flags":1,"driver":"SiRF binary"},


    {"class":"DEVICE","path":"/dev/pts/3","flags":4,"driver":"AIVDM"}]}

The daemon occasionally ships a bare DEVICE object to the client (that is, one not inside a DEVICES wrapper). The data content of these objects will be described later as a response to the ?DEVICE command.

A WATCH object has the following elements:

Table 9. WATCH object

There is an additional boolean "timing" attribute which is undocumented because that portion of the interface is considered unstable and for developer use only.

In watcher mode, GPS reports are dumped as TPV and SKY responses. AIS, Subframe and RTCM reporting is described in the next section.

When the C client library parses a response of this kind, it will assert the POLICY_SET bit in the top-level set member.

Here's an example:

{"class":"WATCH", "raw":1,"scaled":true}

Polling can lead to possibly surprising results when it is used on a device such as an NMEA GPS for which a complete fix has to be accumulated from several sentences. If you poll while those sentences are being emitted, the response will contain the last complete fix data and may be as much as one cycle time (typically 1 second) stale.

The POLL response will contain a timestamped list of TPV objects describing cached data, and a timestamped list of SKY objects describing satellite configuration. If a device has not seen fixes, it will be reported with a mode field of zero.

Table 10. POLL object

Here's an example of a POLL response:

{"class":"POLL","time":"2010-06-04T10:31:00.289Z","active":1,


    "tpv":[{"class":"TPV","device":"/dev/ttyUSB0",


            "time":"2010-09-08T13:33:06.095Z",
	    "ept":0.005,"lat":40.035093060,


            "lon":-75.519748733,"track":99.4319,"speed":0.123,"mode":2}],


    "sky":[{"class":"SKY","device":"/dev/ttyUSB0",


            "time":1270517264.240,"hdop":9.20,


            "satellites":[{"PRN":16,"el":55,"az":42,"ss":36,"used":true},


                          {"PRN":19,"el":25,"az":177,"ss":0,"used":false},


                          {"PRN":7,"el":13,"az":295,"ss":0,"used":false},


                          {"PRN":6,"el":56,"az":135,"ss":32,"used":true},


                          {"PRN":13,"el":47,"az":304,"ss":0,"used":false},


                          {"PRN":23,"el":66,"az":259,"ss":0,"used":false},


                          {"PRN":20,"el":7,"az":226,"ss":0,"used":false},


                          {"PRN":3,"el":52,"az":163,"ss":32,"used":true},


                          {"PRN":31,"el":16,"az":102,"ss":0,"used":false}
]}]}

This message exactly mirrors the PPS message except for two details.

TOFF emits no NTP precision, this is assumed to be -2. See the NTP documentation for their definition of precision.

The TOFF message reports the GPS time as derived from the GPS serial data stream. The PPS message reports the GPS time as derived from the GPS PPS pulse.

A TOFF object has the following elements:

Table 11. TOFF object

This message is emitted once per second to watchers of a device and is intended to report the time stamps of the in-band report of the GPS and seconds as reported by the system clock (which may be NTP-corrected) when the first valid timestamp of the reporting cycle was seen.

The message contains two second/nanosecond pairs: real_sec and real_nsec contain the time the GPS thinks it was at the start of the current cycle; clock_sec and clock_nsec contain the time the system clock thinks it was on receipt of the first timing message of the cycle. real_nsec is always to nanosecond precision. clock_nsec is nanosecond precision on most systems.

Here's an example:

{"class":"TOFF","device":"/dev/ttyUSB0",


     "real_sec":1330212592, "real_nsec":343182,


     "clock_sec":1330212592,"clock_nsec":343184,


     "precision":-2}}

This message exactly mirrors the TOFF message except for two details.

PPS emits the NTP precision. See the NTP documentation for their definition of precision.

The TOFF message reports the GPS time as derived from the GPS serial data stream. The PPS message reports the GPS time as derived from the GPS PPS pulse.

There are various sources of error in the reported clock times. The speed of the serial connection between the GPS and the system adds a delay to start of cycle detection. An even bigger error is added by the variable computation time inside the GPS. Taken together the time derived from the start of the GPS cycle can have offsets of 10 millisecond to 700 milliseconds and combined jjitter and wander of 100 to 300 millisecond.

A PPS object has the following elements:

Table 12. PPS object

This message is emitted once per second to watchers of a device emitting PPS, and reports the time of the start of the GPS second (when the 1PPS arrives) and seconds as reported by the system clock (which may be NTP-corrected) at that moment.

The message contains two second/nanosecond pairs: real_sec and real_nsec contain the time the GPS thinks it was at the PPS edge; clock_sec and clock_nsec contain the time the system clock thinks it was at the PPS edge. real_nsec is always to nanosecond precision. clock_nsec is nanosecond precision on most systems.

There are various sources of error in the reported clock times. For PPS delivered via a real serial-line strobe, serial-interrupt latency plus processing time to the timer call should be bounded above by about 10 microseconds; that can be reduced to less than 1 microsecond if your kernel supports RFC 2783. USB1.1-to-serial control-line emulation is limited to about 1 millisecond. seconds.

Here's an example:

{"class":"PPS","device":"/dev/ttyUSB0",


     "real_sec":1330212592, "real_nsec":343182,


     "clock_sec":1330212592,"clock_nsec":343184,


     "precision":-3}

An OSC object has the following elements:

Table 13. OSC object

Here's an example:

{"class":"OSC","running":true,"device":"/dev/ttyUSB0",


    "reference":true,"disciplined":true,"delta":67}

Pay attention to the response, because it is possible for this command to fail if the GPS does not support a speed-switching command or only supports some combinations of serial modes. In case of failure, the daemon and GPS will continue to communicate at the old speed.

Use the parameter-setting form with caution. On USB and Bluetooth GPSes it is also possible for serial mode setting to fail either because the serial adaptor chip does not support non-8N1 modes or because the device firmware does not properly synchronize the serial adaptor chip with the UART on the GPS chipset when the speed changes. These failures can hang your device, possibly requiring a GPS power cycle or (in extreme cases) physically disconnecting the NVRAM backup battery.

A DEVICE object has the following elements:

Table 14. DEVICE object

The serial parameters will (bps, parity, stopbits) be omitted in a response describing a TCP/IP source such as an Ntrip, DGPSIP, or AIS feed; on a serial device they will always be present.

The contents of the flags field should be interpreted as follows:

Table 15. Device flags

When the C client library parses a response of this kind, it will assert the DEVICE_SET bit in the top-level set member.

Here's an example:

{"class":"DEVICE","bps":4800,"parity":"N","stopbits":1,"native":0}

{"class":"DEVICE","path":"/dev/pts1","activated":0}

{"class":"ERROR","message":"Unrecognized request '?FOO'"}