NAME¶

gpsd_json - gpsd request/response protocol

OVERVIEW¶

gpsd is a service daemon that can be used to monitor GPSes, DGPS receivers, Marine AIS broadcasts, and various other location-related and kinematic sensors. Clients may communicate with gpsd via textual requests and responses over a socket. It is a bad idea for applications to speak the protocol directly: rather, they should use the libgps client library (for C; bindings also exist for other languages) and take appropriate care to conditionalize their code on the major and minor protocol version symbols. The GPSD protocol is built on top of JSON, JavaScript Object Notation, as specified in RFC 7159: The JavaScript Object Notation (JSON) Data Interchange Format. GPSD's use of JSON is restricted in some ways that make parsing it in fixed-extent languages (such as C) easier. A request line is introduced by "?" and may include multiple commands. Commands begin with a command identifier, followed either by a terminating ';' or by an equal sign "=" and a JSON object treated as an argument. Any ';' or newline indication (either LF or CR-LF) after the end of a command is ignored. All request lines must be composed of US-ASCII characters and may be no more than 80 characters in length, exclusive of the trailing newline. Responses are JSON objects all of which have a "class" attribute the value of which is either the name of the invoking command. There are reports (including but not limited to as "TPV", "SKY", "DEVICE", and "ERROR") which are not direct responses to commands. The order of JSON attributes within a response object is never significant, and you may specify attributes in commands in any order. Responses never contain the special JSON value null; instead, attributes with empty or undefined values are omitted. The length limit for responses and reports is 1536 characters, including trailing newline; longer responses will be truncated, so client code must be prepared for the possibility of invalid JSON fragments. In JSON reports, if an attribute is present only if the parent attribute is present or has a particular range, then the parent attribute is emitted first. There is one constraint on the order in which attributes will be omitted. If an optional attribute is present only when a parent attribute has a specified value or range of values, the parent attribute will be emitted first to make parsing easier. The next subsection section documents the core GPSD protocol. Extensions are documented in the following subsections. The extensions may not be supported in your gpsd instance if it has been compiled with a restricted feature set.

CORE SOCKET PROTOCOL¶

Here are the core-protocol responses: TPV SKY GST ATT And here are the commands: ?VERSION; ?DEVICES; ?WATCH; ?POLL; TOFF PPS ?DEVICE 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: The daemon may ship an error object in response to a syntactically invalid command line or unknown command. It has the following elements: Table 15. ERROR notification object

Name	Always?	Type	Description
class	Yes	string	Fixed: "ERROR"
message	Yes	string	Textual error message

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

RTCM2¶

RTCM-104 is a family of serial protocols used for broadcasting pseudorange corrections from differential-GPS reference stations. Many GPS receivers can accept these corrections to improve their reporting accuracy. RTCM-104 comes in two major and incompatible flavors, 2.x and 3.x. Each major flavor has minor (compatible) revisions. The applicable standard for RTCM Version 2.x is RTCM Recommended Standards for Differential NAVSTAR GPS Service RTCM Paper 194-93/SC 104-STD. For RTCM 3.1 it is RTCM Paper 177-2006-SC104-STD. Ordering instructions for both standards are accessible from the website of the Radio Technical Commission for Maritime Services[1] under "Publications".

RTCM WIRE TRANSMISSIONS¶

Differential-GPS correction stations consist of a GPS reference receiver coupled to a low frequency (LF) transmitter. The GPS reference receiver is a survey-grade GPS that does GPS carrier tracking and can work out its own position to a few millimeters. It generates range and range-rate corrections and encodes them into RTCM104. It ships the RTCM104 to the LF transmitter over serial rs-232 signal at 100 baud or 200 baud depending on the requirements of the transmitter. 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 the 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 2.x message consists of a sequence of up to 33 30-bit words. The 24 most significant bits of each word are data and the six least significant bits are parity. The parity algorithm used is the same ISGPS-2000 as that used on GPS satellite downlinks. Each RTCM 2.x message consists of two header words followed by zero or more data words, depending upon message type. 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¶

Each RTCM2 message is dumped as a single JSON object per message, with the message fields as attributes of that object. Arrays of satellite, station, and constellation statistics become arrays of JSON sub-objects. Each sentence will normally also have a "device" field containing the pathname of the originating device. All attributes other than the device field are mandatory. Header attributes are emitted before others. Header portion Type 1 and 9: Correction data Type 3: Reference Station Parameters Type 4: Datum Type 5: Constellation Health Type 6: Null Unknown message Type 7: Radio Beacon Almanac Type 13: GPS Time of Week Type 14: GPS Time of Week Type 16: Special Message Type 31: Correction data

RTCM3 DUMP FORMAT¶

The support for RTCM104v3 dumping is incomplete and buggy. Do not attempt to use it for production! Anyone interested in it should read the source code.

AIS DUMP FORMATS¶

AIS support is an extension. It may not be present if your instance of gpsd has been built with a restricted feature set. AIS packets are dumped as JSON objects with class "AIS". Each AIS report object contains a "type" field giving the AIS message type and a "scaled" field telling whether the remainder of the fields are dumped in scaled or unscaled form. (These will be emitted before any type-specific fields.) It will also contain a "device" field naming the data source. Other fields have names and types as specified in the AIVDM/AIVDO Protocol Decoding document on the GPSD project website; each message field table may be directly interpreted as a specification for the members of the corresponding JSON object type. By default, certain scaling and conversion operations are performed for JSON output. Latitudes and longitudes are scaled to decimal degrees rather than the native AIS unit of 1/10000th of a minute of arc. Ship (but not air) speeds are scaled to knots rather than tenth-of-knot units. Rate of turn may appear as "nan" if is unavailable, or as one of the strings "fastright" or "fastleft" if it is out of the AIS encoding range; otherwise it is quadratically mapped back to the turn sensor number in degrees per minute. Vessel draughts are converted to decimal meters rather than native AIS decimeters. Various other scaling conversions are described in "AIVDM/AIVDO Protocol Decoding".

SUBFRAME DUMP FORMATS¶

Subframe support is always compiled into gpsd but many GPSes do not output subframe data or the gpsd driver may not support subframes. Subframe packets are dumped as JSON objects with class "SUBFRAME". Each subframe report object contains a "frame" field giving the subframe number, a "tSV" field for the transmitting satellite number, a "TOW17" field containing the 17 MSBs of the start of the next 12-second message and a "scaled" field telling whether the remainder of the fields are dumped in scaled or unscaled form. It will also contain a "device" field naming the data source. Each SUBFRAME object will have a sub-object specific to that subframe page type. Those sub-object fields have names and types similar to those specified in the IS-GPS-200E document; each message field table may be directly interpreted as a specification for the members of the corresponding JSON object type.

SEE ALSO¶

gpsd(8), libgps(3),

AUTHOR¶

The protocol was designed and documented by Eric S. Raymond.

NOTES¶

1.

Radio Technical Commission for Maritime Services

2.

table of leap second corrections