TPV

A TPV object will usually be sent at least once for every measurement epoch as determined by the "time" field. Unless the receiver has a solid fix, and knows the current leap second, the time may be random.

Multiple TPV objects are often sent per epoch. When the receiver dribbles data to gpsd, then gpsd has no choice but to dribble it to the client in multiple TPV messages.

The optional "status" field (aka fix type), is a modifier (adjective) to mode. It is not a replacement for, or superset of, the "mode" field. It is almost, but not quite, the same as the NMEA 4.x xxGGA GPS Quality Indicator Values. Many GNSS receivers do not supply it. Those that do interpret the specification in various incompatible ways.

All error estimates (epc, epd, epe, eph, ept, epv, epx, epy) are guessed to be 95% confidence, may also be 50%, one sigma, or two sigma confidence. Many GNSS receivers do not specify a confidence level. None specify how the value is calculated. Use error estimates with caution, and only as relative "goodness" indicators. If the GPS reports a value to gpsd, then gpsd will report that value. Otherwise gpsd will try to compute the value from the skyview.

See the file include/gps.h, especially struct gps_data_t, for expanded notes on the items and values in the TPV message.

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 received; see gps.h for bitmask names and values.

Invalid or unknown floating-point values will be set to NAN. Always check floating point values with isfinite() before use. isnan() is not sufficient.

Here’s an example TPV sentence:

{"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}

SKY

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 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}]}

GST

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}

ATT

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

The ATT object is synchronous to the GNSS epoch. Some devices report attitude information with arbitrary, even out of order, time scales. gpsd reports those in an IMU object. The ATT and IMU objects have the same fields, but IMU objects are output as soon as possible. Some devices output both types with arbitrary interleaving.

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}

IMU

The ATT and IMU objects have the same fields, but IMU objects are output as soon as possible.

Seee the ATT onject description for field details.

TOFF

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 7. TOFF object

This message is emitted once per second to watchers of a device and is
intended to report the timestamps 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 time stamp 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}

PPS

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 the 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 milliseconds to 700 milliseconds and combined jitter and wander of 100 to 300 milliseconds.

A PPS object has the following elements:

Table 8. 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}

OSC

An OSC object has the following elements:

Table 9. OSC object

Here’s an example:

{"class":"OSC","running":true,"device":"/dev/ttyUSB0",
    "reference":true,"disciplined":true,"delta":67}

?VERSION;

Table 10. 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
}

?DEVICES;

Table 11. 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.

?WATCH;

A WATCH object has the following elements:

Table 12. 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}

?POLL;

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 only the fix data collected so far in the current epoch. It 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 13. 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}
]}]}

?DEVICE; ?DEVICE=

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}

When a client is in watcher mode, the daemon will ship it DEVICE notifications when a device is added to the pool or deactivated.

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","path":"/dev/pts1","activated":0}

ERROR

Table 16. ERROR notification object

Here’s an example:

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

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

RTCM WIRE TRANSMISSIONS

The LF transmitter broadcasts the approximately 300khz radio signal that differential-GPS radio receivers pick up. Transmitters that are meant to have a higher range will need to transmit at a slower rate. The higher the data rate the harder it will be for the remote radio receiver to receive with a good signal-to-noise ration. (Higher data rate signals can’t be averaged over as long a time frame, hence they appear noisier.)

RTCM WIRE FORMATS

An RTCM 3.x message begins with a fixed leader byte 0xD3. That is followed by six bits of version information and 10 bits of payload length information. Following that is the payload; following the payload is a 3-byte checksum of the payload using the Qualcomm CRC-24Q algorithm.

RTCM2 JSON FORMAT

All attributes other than the device field are mandatory. Header attributes are emitted before others.

Header portion

<message type> is one of

1

3

4

5

6

7

9

16

31

Type 1 and 9: Correction data

Table 18. Satellite object

User Differential Range Error values are as follows:

Table 19. UDRE values

Here’s an example:

{"class":"RTCM2","type":1,
    "station_id":688,"zcount":843.0,"seqnum":5,"length":19,"station_health":6,
    "satellites":[
        {"ident":10,"udre":0,"iod":46,"prc":-2.400,"rrc":0.000},
        {"ident":13,"udre":0,"iod":94,"prc":-4.420,"rrc":0.000},
        {"ident":7,"udre":0,"iod":22,"prc":-5.160,"rrc":0.002},
        {"ident":2,"udre":0,"iod":34,"prc":-6.480,"rrc":0.000},
        {"ident":4,"udre":0,"iod":47,"prc":-8.860,"rrc":0.000},
        {"ident":8,"udre":0,"iod":76,"prc":-7.980,"rrc":0.002},
        {"ident":5,"udre":0,"iod":99,"prc":-8.260,"rrc":0.002},
        {"ident":23,"udre":0,"iod":81,"prc":-8.060,"rrc":0.000},
        {"ident":16,"udre":0,"iod":70,"prc":-11.740,"rrc":0.000},
        {"ident":30,"udre":0,"iod":4,"prc":-18.960,"rrc":-0.006},
        {"ident":29,"udre":0,"iod":101,"prc":-24.960,"rrc":-0.002}
]}

Type 3: Reference Station Parameters

Table 20. Reference Station Parameters

The coordinates are the position of the station, in meters to two
decimal places, in Earth Centred Earth Fixed coordinates. These are usually referred to the WGS84 reference frame, but may be referred to NAD83 in the US (essentially identical to WGS84 for all except geodesists), or some other reference frame in other parts of the world.

An invalid reference message is represented by a type 3 header without payload fields.

Here’s an example:

{"class":"RTCM2","type":3,
    "station_id":652,"zcount":1657.2,"seqnum":2,"length":4,"station_health":6,
    "x":3878620.92,"y":670281.40,"z":5002093.59
}

Type 4: Datum

Table 21. Datum

<dx> <dy> <dz> are offsets to convert from local datum to GNSS datum or
vice versa. These fields are optional.

An invalid datum message is represented by a type 4 header without payload fields.

Type 5: Constellation Health

Here is the format:

Table 22. Constellation health

Type 6: Null

Unknown message

Here is the format:

Table 23. Unknown Message

Each string in the array is a hex literal representing 30 bits of
information, after parity checks and inversion. The high two bits should be ignored.

Type 7: Radio Beacon Almanac

Table 24. Constellation health

Here’s an example:

{"class":"RTCM2","type":9,"station_id":268,"zcount":252.6,
        "seqnum":4,"length":5,"station_health":0,
        "satellites":[
            {"ident":13,"udre":0,"iod":3,"prc":-25.940,"rrc":0.066},
            {"ident":2,"udre":0,"iod":73,"prc":0.920,"rrc":-0.080},
            {"ident":8,"udre":0,"iod":22,"prc":23.820,"rrc":0.014}
]}

Type 13: GPS Time of Week

Table 25. Ground Transmitter Parameters

This message type replaces message type 3 (Reference Station Parameters)
in RTCM 2.3.

Type 14: GPS Time of Week

Table 26. Reference Station Parameters

Here’s an example:

{"class":"RTCM2","type":14,"station_id":652,"zcount":1657.2,
        "seqnum":3,"length":1,"station_health":6,"week":601,"hour":109,
        "leapsecs":15}

Type 16: Special Message

Type 31: Correction data

Table 28. Satellite object

Here’s an example:

{"class":"RTCM2","type":31,"station_id":652,"zcount":1642.2,
    "seqnum":0,"length":14,"station_health":6,
    "satellites":[
        {"ident":5,"udre":0,"change":false,"tod":0,"prc":132.360,"rrc":0.000},
        {"ident":15,"udre":0,"change":false,"tod":0,"prc":134.840,"rrc":0.002},
        {"ident":14,"udre":0,"change":false,"tod":0,"prc":141.520,"rrc":0.000},
        {"ident":6,"udre":0,"change":false,"tod":0,"prc":127.000,"rrc":0.000},
        {"ident":21,"udre":0,"change":false,"tod":0,"prc":128.780,"rrc":0.000},
        {"ident":22,"udre":0,"change":false,"tod":0,"prc":125.260,"rrc":0.002},
        {"ident":20,"udre":0,"change":false,"tod":0,"prc":117.280,"rrc":-0.004},
        {"ident":16,"udre":0,"change":false,"tod":17,"prc":113.460,"rrc":0.018}
]}