diff options
| author | Eric S. Raymond <esr@thyrsus.com> | 2011-03-28 07:35:52 -0400 |
|---|---|---|
| committer | Eric S. Raymond <esr@thyrsus.com> | 2011-03-28 07:35:52 -0400 |
| commit | bfe1438f7bc8a525b8791b18d60dfe13510a5935 (patch) | |
| tree | 611ef2fa302b0ad3b83668159c3a291652dbfad5 /gpsd.xml | |
| parent | 66e1a41db58c6374fc92a5dc6ca12a5367a15355 (diff) | |
| download | gpsd-bfe1438f7bc8a525b8791b18d60dfe13510a5935.tar.gz | |
Split the JSON protocol dcumentation out of gpsd(8).
Also, fully document the DBUS and shared-memory interfaces.
Diffstat (limited to 'gpsd.xml')
| -rw-r--r-- | gpsd.xml | 2223 |
1 files changed, 64 insertions, 2159 deletions
@@ -310,2221 +310,125 @@ set to the pathname of the device and the second to <option>ACTIVATE</option>. On deactivation it does the same passing <option>DEACTIVATE</option> for the second argument.</para> -<para>Clients communicate with the daemon via textual request and -responses. It is a bad idea for applications to speak the protocol +<para><application>gpsd</application> can export data to client applications +in three ways: via a sockets interface, via a shared-memory segment, and +via D-Bus. The next three major sections describe these interfaces.</para> + +</refsect1> +<refsect1 id='sockets'><title>THE SOCKET INTERFACE</title> + +<para>Clients may communicate with the daemon via textual request and +responses over a socket. It is a bad idea for applications to speak the protocol directly: rather, they should use the <application>libgps</application> client library and take appropriate care to conditionalize their code on the major and minor protocol version symbols.</para> +<para>The request-response protocol for the socket interface is fully +documented in +<citerefentry><refentrytitle>gpsd_json</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> + </refsect1> -<refsect1 id='protocol'><title>REQUEST/RESPONSE PROTOCOL</title> - -<para>The GPSD protocol is built on top of JSON, JavaScript -Object Notation. GPSD's use of JSON is restricted in some ways -that make parsing it in fixed-extent languages (such as C) easier.</para> - -<para>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.</para> - -<para>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.</para> - -<para> 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.</para> - -<para>In JSON reports, if an attribute is present only if the parent -attribute is present or has a particular range, yjen the parent -attribute is emitted first.</para> - -<para>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.</para> - -<para>The remainder of this section documents the core GPSD protocol. -Extensions are documented in the following sections. The extensions -may not be supported in your <application>gpsd</application> instance -if it has been compiled with a restricted feature set.</para> - -<para>Here are the core-protocol responses:</para> - -<variablelist> -<varlistentry> -<term>TPV</term> -<listitem> -<para>A TPV object is a time-position-velocity report. The "class" and "mode" -fields will reliably be present. The "mode" field will be emitted -before optional fields that may be absent when there is no fix. Error -estimates will be emitted after the fix components they're associated with. -Others may be reported or not depending on the fix quality.</para> - -<table frame="all" pgwide="0"><title>TPV object</title> -<tgroup cols="3" align="left" colsep="1" rowsep="1"> -<thead> -<row> - <entry>Name</entry> - <entry>Always?</entry> - <entry>Type</entry> - <entry>Description</entry> -</row> -</thead> -<tbody> -<row> - <entry>class</entry> - <entry>Yes</entry> - <entry>string</entry> - <entry>Fixed: "TPV"</entry> -</row> -<row> - <entry>tag</entry> - <entry>No</entry> - <entry>string</entry> - <entry>Type tag associated with this GPS sentence; from an NMEA - device this is just the NMEA sentence type..</entry> -</row> -<row> - <entry>device</entry> - <entry>No</entry> - <entry>string</entry> - <entry>Name of originating device.</entry> -</row> -<row> - <entry>mode</entry> - <entry>Yes</entry> - <entry>numeric</entry> - <entry>NMEA mode: %d, 0=no mode value yet seen, 1=no fix, 2=2D, 3=3D.</entry> -</row> -<row> - <entry>time</entry> - <entry>No</entry> - <entry>string</entry> - <entry>Time/date stamp in ISO8601 format, UTC. May have a - fractional part of up to .01sec precision. May be absent if mode - is not 2 or 3.</entry> -</row> -<row> - <entry>ept</entry> - <entry>No</entry> - <entry>numeric</entry> - <entry>Estimated timestamp error (%f, seconds, 95% confidence). - Present if time is present.</entry> -</row> -<row> - <entry>lat</entry> - <entry>No</entry> - <entry>numeric</entry> - <entry>Latitude in degrees: +/- signifies West/East. Present - when mode is 2 or 3.</entry> -</row> -<row> - <entry>lon</entry> - <entry>No</entry> - <entry>numeric</entry> - <entry>Longitude in degrees: +/- signifies North/South. Present - when mode is 2 or 3.</entry> -</row> -<row> - <entry>alt</entry> - <entry>No</entry> - <entry>numeric</entry> - <entry>Altitude in meters. Present if mode is 3.</entry> -</row> -<row> - <entry>epx</entry> - <entry>No</entry> - <entry>numeric</entry> - <entry>Longitude error estimate in meters, 95% confidence. Present - if mode is 2 or 3 and DOPs can be calculated from the satellite - view.</entry> -</row> -<row> - <entry>epy</entry> - <entry>No</entry> - <entry>numeric</entry> - <entry>Latitude error estimate in meters, 95% confidence. Present - if mode is 2 or 3 and DOPs can be calculated from the satellite - view.</entry> -</row> -<row> - <entry>epv</entry> - <entry>No</entry> - <entry>numeric</entry> - <entry>Estimated vertical error in meters, 95% confidence. Present - if mode is 3 and DOPs can be calculated from the satellite - view.</entry> -</row> -<row> - <entry>track</entry> - <entry>No</entry> - <entry>numeric</entry> - <entry>Course over ground, degrees from true north.</entry> -</row> -<row> - <entry>speed</entry> - <entry>No</entry> - <entry>numeric</entry> - <entry>Speed over ground, meters per second.</entry> -</row> -<row> - <entry>climb</entry> - <entry>No</entry> - <entry>numeric</entry> - <entry>Climb (positive) or sink (negative) rate, meters per - second.</entry> -</row> -<row> - <entry>epd</entry> - <entry>No</entry> - <entry>numeric</entry> - <entry>Direction error estimate in degrees, 95% confifdence.</entry> -</row> -<row> - <entry>eps</entry> - <entry>No</entry> - <entry>numeric</entry> - <entry>Speed error estinmate in meters/sec, 95% confifdence.</entry> -</row> -<row> - <entry>epc</entry> - <entry>No</entry> - <entry>numeric</entry> - <entry>Climb/sink error estinmate in meters/sec, 95% confifdence.</entry> -</row> - -</tbody> -</tgroup> -</table> - -<para>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.</para> - -<para>Here's an example:</para> - -<programlisting> -{"class":"TPV","tag":"MID2","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} -</programlisting> -</listitem> -</varlistentry> - -<varlistentry> -<term>SKY</term> -<listitem> -<para>A SKY object reports a sky view of the GPS satellite positions. -If there is no GPS device available, or no skyview has been reported -yet, only the "class" field will reliably be present.</para> -<table frame="all" pgwide="0"><title>SKY object</title> -<tgroup cols="3" align="left" colsep="1" rowsep="1"> -<thead> -<row> - <entry>Name</entry> - <entry>Always?</entry> - <entry>Type</entry> - <entry>Description</entry> -</row> -</thead> -<tbody> -<row> - <entry>class</entry> - <entry>Yes</entry> - <entry>string</entry> - <entry>Fixed: "SKY"</entry> -</row> -<row> - <entry>tag</entry> - <entry>No</entry> - <entry>string</entry> - <entry>Type tag associated with this GPS sentence; from an NMEA - device this is just the NMEA sentence type..</entry> -</row> -<row> - <entry>device</entry> - <entry>No</entry> - <entry>string</entry> - <entry>Name of originating device</entry> -</row> -<row> - <entry>time</entry> - <entry>No</entry> - <entry>numeric</entry> - <entry>Time/date stamp in ISO8601 format, UTC. May have a - fractional part of up to .01sec precision.</entry> -</row> -<row> - <entry>xdop</entry> - <entry>No</entry> - <entry>numeric</entry> - <entry>Longitudinal dilution of precision, a dimensionless - factor which should be multiplied by a base UERE to get an - error estimate.</entry> -</row> -<row> - <entry>ydop</entry> - <entry>No</entry> - <entry>numeric</entry> - <entry>Latitudinal dilution of precision, a dimensionless - factor which should be multiplied by a base UERE to get an - error estimate.</entry> -</row> -<row> - <entry>vdop</entry> - <entry>No</entry> - <entry>numeric</entry> - <entry>Altitude dilution of precision, a dimensionless - factor which should be multiplied by a base UERE to get an - error estimate.</entry> -</row> -<row> - <entry>tdop</entry> - <entry>No</entry> - <entry>numeric</entry> - <entry>Time dilution of precision, a dimensionless - factor which should be multiplied by a base UERE to get an - error estimate.</entry> -</row> -<row> - <entry>hdop</entry> - <entry>No</entry> - <entry>numeric</entry> - <entry>Horizontal dilution of precision, a dimensionless - factor which should be multiplied by a base UERE to get a - circular error estimate.</entry> -</row> -<row> - <entry>pdop</entry> - <entry>No</entry> - <entry>numeric</entry> - <entry>Spherical dilution of precision, a dimensionless - factor which should be multiplied by a base UERE to get an - error estimate.</entry> -</row> -<row> - <entry>gdop</entry> - <entry>No</entry> - <entry>numeric</entry> - <entry>Hyperspherical dilution of precision, a dimensionless - factor which should be multiplied by a base UERE to get an - error estimate.</entry> -</row> -<row> - <entry>xdop</entry> - <entry>No</entry> - <entry>numeric</entry> - <entry>Longitudinal dilution of precision, a dimensionless - factor which should be multiplied by a base UERE to get an - error estimate.</entry> -</row> -<row> - <entry>satellites</entry> - <entry>Yes</entry> - <entry>list</entry> - <entry>List of satellite objects in skyview</entry> -</row> +<refsect1 id='shm'><title>SHARED-MEMORY AND DBUS INTERFACES</title> -</tbody> -</tgroup> -</table> +<para><application>gpsd</application> has two other (read-only) +interfaces.</para> -<para>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. <application>gpsd</application> -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.</para> +<para>Whenever the daemon recognizes a packet from any attached +device, it writes the accumulated state from that device to a shared +memory segment. The C and C++ client libraries shipped with GPSD can +read this segment. Client methods, and various restrictions associated +with the read-only nature of this interface, are documented at +<citerefentry><refentrytitle>libgps</refentrytitle><manvolnum>3</manvolnum></citerefentry>. The +shared-memory interface is intended primarily for embedded deployments +in which <application>gpsd</application> monitors a single device, and +its principal advantage is that a daemon instance configured with +shared memory but without the soickets interface loses a significant +amount of runtime weight.</para> -<para>The satellite list objects have the following elements:</para> +<para>The daemon may be configured to emit a D-Bus signal each time an +attached device delivers a fix. The signal path is <filename>path +/org/gpsd</filename>, the signal interface is "org.gpsd", and the +signal name is "fix". The signal payload layout is as follows:</para> <table frame="all" pgwide="0"><title>Satellite object</title> -<tgroup cols="3" align="left" colsep="1" rowsep="1"> -<thead> -<row> - <entry>Name</entry> - <entry>Always?</entry> - <entry>Type</entry> - <entry>Description</entry> -</row> -</thead> -<tbody> -<row> - <entry>PRN</entry> - <entry>Yes</entry> - <entry>numeric</entry> - <entry>PRN ID of the satellite</entry> -</row> -<row> - <entry>az</entry> - <entry>Yes</entry> - <entry>numeric</entry> - <entry>Azimuth, degrees from true north.</entry> -</row> -<row> - <entry>el</entry> - <entry>Yes</entry> - <entry>numeric</entry> - <entry>Elevation in degrees.</entry> -</row> -<row> - <entry>ss</entry> - <entry>Yes</entry> - <entry>numeric</entry> - <entry>Signal strength in dB.</entry> -</row> -<row> - <entry>used</entry> - <entry>Yes</entry> - <entry>boolean</entry> - <entry>Used in current solution?</entry> -</row> -</tbody> -</tgroup> -</table> - -<para>Note that satellite objects do not have a "class" field, as -they are never shipped outside of a SKY object.</para> - -<para>When the C client library parses a SKY response, it -will assert the SATELLITE_SET bit in the top-level set member.</para> - -<para>Here's an example:</para> - -<programlisting> -{"class":"SKY","tag":"MID2","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}]} -</programlisting> - -</listitem> -</varlistentry> - -<varlistentry> -<term>GST</term> -<listitem> -<para>A GST object is a pseudorange noise report.</para> - -<table frame="all" pgwide="0"><title>GST object</title> -<tgroup cols="3" align="left" colsep="1" rowsep="1"> -<thead> -<row> - <entry>Name</entry> - <entry>Always?</entry> - <entry>Type</entry> - <entry>Description</entry> -</row> -</thead> -<tbody> -<row> - <entry>class</entry> - <entry>Yes</entry> - <entry>string</entry> - <entry>Fixed: "GST"</entry> -</row> -<row> - <entry>tag</entry> - <entry>No</entry> - <entry>string</entry> - <entry>Type tag associated with this GPS sentence; from an NMEA -device this is just the NMEA sentence type.</entry> -</row> -<row> - <entry>device</entry> - <entry>No</entry> - <entry>string</entry> - <entry>Name of originating device</entry> -</row> -<row> - <entry>time</entry> - <entry>No</entry> - <entry>numeric</entry> - <entry>Seconds since the Unix epoch, UTC. May have a -fractional part of up to .01sec precision.</entry> -</row> - -<row> - <entry>rms</entry> - <entry>No</entry> - <entry>numeric</entry> - <entry>Value of the standard deviation of the range inputs to the -navigation process (range inputs include pseudoranges and DGPS -corrections).</entry> -</row> - -<row> - <entry>major</entry> - <entry>No</entry> - <entry>numeric</entry> - <entry>Standard deviation of semi-major axis of error ellipse, in meters.</entry> -</row> - -<row> - <entry>minor</entry> - <entry>No</entry> - <entry>numeric</entry> - <entry>Standard deviation of semi-minor axis of error ellipse, in meters.</entry> -</row> - -<row> - <entry>orient</entry> - <entry>No</entry> - <entry>numeric</entry> - <entry>Orientation of semi-major axis of error ellipse, in degrees from true north.</entry> -</row> - -<row> - <entry>lat</entry> - <entry>No</entry> - <entry>numeric</entry> - <entry>Standard deviation of latitude error, in meters.</entry> -</row> - -<row> - <entry>lon</entry> - <entry>No</entry> - <entry>numeric</entry> - <entry>Standard deviation of longitude error, in meters.</entry> -</row> - -<row> - <entry>alt</entry> - <entry>No</entry> - <entry>numeric</entry> - <entry>Standard deviation of altitude error, in meters.</entry> -</row> - -</tbody> -</tgroup> -</table> - -<para>Here's an example:</para> - -<programlisting> -{"class":"GST","tag":"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} -</programlisting> -</listitem> -</varlistentry> - -<varlistentry> -<term>ATT</term> -<listitem> -<para>An ATT object is a vehicle-attitude report. It is returned by -digital-compass and gyroscope sensors; depending on device, it may -include: heading, pitch, roll, yaw, gyroscope, and magnetic-field -readings. Because such sensors are often bundled as part of -marine-navigation systems, the ATT response may also include -water depth.</para> - -<para>The "class", "mode", and "tag" fields will reliably be present. Others -may be reported or not depending on the specific device type.</para> - -<table frame="all" pgwide="0"><title>ATT object</title> -<tgroup cols="3" align="left" colsep="1" rowsep="1"> -<thead> -<row> - <entry>Name</entry> - <entry>Always?</entry> - <entry>Type</entry> - <entry>Description</entry> -</row> -</thead> -<tbody> -<row> - <entry>class</entry> - <entry>Yes</entry> - <entry>string</entry> - <entry>Fixed: "ATT"</entry> -</row> -<row> - <entry>tag</entry> - <entry>Yes</entry> - <entry>string</entry> - <entry>Type tag associated with this GPS sentence; from an NMEA - device this is just the NMEA sentence type..</entry> -</row> -<row> - <entry>device</entry> - <entry>Yes</entry> - <entry>string</entry> - <entry>Name of originating device</entry> -</row> -<row> - <entry>time</entry> - <entry>Yes</entry> - <entry>numeric</entry> - <entry>Seconds since the Unix epoch, UTC. May have a - fractional part of up to .01sec precision.</entry> -</row> -<row> - <entry>heading</entry> - <entry>No</entry> - <entry>numeric</entry> - <entry>Heading, degrees from true north.</entry> -</row> -<row> - <entry>mag_st</entry> - <entry>No</entry> - <entry>string</entry> - <entry>Magnetometer status.</entry> -</row> -<row> - <entry>pitch</entry> - <entry>No</entry> - <entry>numeric</entry> - <entry>Pitch in degrees.</entry> -</row> -<row> - <entry>pitch_st</entry> - <entry>No</entry> - <entry>string</entry> - <entry>Pitch sensor status.</entry> -</row> -<row> - <entry>yaw</entry> - <entry>No</entry> - <entry>numeric</entry> - <entry>Yaw in degrees</entry> -</row> -<row> - <entry>yaw_st</entry> - <entry>No</entry> - <entry>string</entry> - <entry>Yaw sensor status.</entry> -</row> -<row> - <entry>roll</entry> - <entry>No</entry> - <entry>numeric</entry> - <entry>Roll in degrees.</entry> -</row> -<row> - <entry>roll_st</entry> - <entry>No</entry> - <entry>string</entry> - <entry>Roll sensor status.</entry> -</row> -<row> - <entry>dip</entry> - <entry>No</entry> - <entry>numeric</entry> - <entry>Roll in degrees.</entry> -</row> -<row> - <entry>mag_len</entry> - <entry>No</entry> - <entry>numeric</entry> - <entry>Scalar magnetic field strength.</entry> -</row> -<row> - <entry>mag_x</entry> - <entry>No</entry> - <entry>numeric</entry> - <entry>X component of magnetic field strength.</entry> -</row> -<row> - <entry>mag_y</entry> - <entry>No</entry> - <entry>numeric</entry> - <entry>Y component of magnetic field strength..</entry> -</row> -<row> - <entry>mag_z</entry> - <entry>No</entry> - <entry>numeric</entry> - <entry>Z component of magnetic field strength..</entry> -</row> -<row> - <entry>mag_len</entry> - <entry>No</entry> - <entry>numeric</entry> - <entry>Scalar acceleration.</entry> -</row> -<row> - <entry>acc_x</entry> - <entry>No</entry> - <entry>numeric</entry> - <entry>X component of acceleration.</entry> -</row> -<row> - <entry>acc_y</entry> - <entry>No</entry> - <entry>numeric</entry> - <entry>Y component of acceleration.</entry> -</row> -<row> - <entry>acc_z</entry> - <entry>No</entry> - <entry>numeric</entry> - <entry>Z component of acceleration..</entry> -</row> -<row> - <entry>gyro_x</entry> - <entry>No</entry> - <entry>numeric</entry> - <entry>X component of acceleration.</entry> -</row> -<row> - <entry>gyro_y</entry> - <entry>No</entry> - <entry>numeric</entry> - <entry>Y component of acceleration.</entry> -</row> -<row> - <entry>depth</entry> - <entry>No</entry> - <entry>numeric</entry> - <entry>Water depth in meters.</entry> -</row> -<row> - <entry>temperature</entry> - <entry>No</entry> - <entry>numeric</entry> - <entry>Temperature at sensor, degrees centigrade.</entry> -</row> - - -</tbody> -</tgroup> -</table> - -<para>The heading, pitch, and roll status codes (if present) vary by device. -For the TNT Revolution digital compasses, they are coded as follows: </para> - -<table frame="all" pgwide="0"><title>Device flags</title> <tgroup cols="2" align="left" colsep="1" rowsep="1"> <thead> <row> - <entry>Code</entry> - <entry>Description</entry> -</row> -</thead> -<tbody> -<row> - <entry>C</entry> - <entry>magnetometer calibration alarm</entry> -</row> -<row> - <entry>L</entry> - <entry>low alarm</entry> -</row> -<row> - <entry>M</entry> - <entry>low warning</entry> -</row> -<row> - <entry>N</entry> - <entry>normal</entry> -</row> -<row> - <entry>O</entry> - <entry>high warning</entry> -</row> -<row> - <entry>P</entry> - <entry>high alarm</entry> -</row> -<row> - <entry>V</entry> - <entry>magnetometer voltage level alarm</entry> -</row> -</tbody> -</tgroup> -</table> - - -<para>When the C client library parses a response of this kind, it -will assert ATT_IS.</para> - -<para>Here's an example:</para> - -<programlisting> -{"class":"ATT","tag":"PTNTHTM","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,"temperature":0.000,"depth":0.000} -</programlisting> -</listitem> -</varlistentry> - -</variablelist> - -<para>And here are the commands:</para> - -<variablelist> - -<varlistentry> -<term>?VERSION;</term> -<listitem><para>Returns an object with the following attributes:</para> - -<table frame="all" pgwide="0"><title>VERSION object</title> -<tgroup cols="4" align="left" colsep="1" rowsep="1"> -<thead> -<row> - <entry>Name</entry> - <entry>Always?</entry> - <entry>Type</entry> - <entry>Description</entry> -</row> -</thead> -<tbody> -<row> - <entry>class</entry> - <entry>Yes</entry> - <entry>string</entry> - <entry>Fixed: "VERSION"</entry> -</row> -<row> - <entry>release</entry> - <entry>Yes</entry> - <entry>string</entry> - <entry>Public release level</entry> -</row> -<row> - <entry>rev</entry> - <entry>Yes</entry> - <entry>string</entry> - <entry>Internal revision-control level.</entry> -</row> -<row> - <entry>proto_major</entry> - <entry>Yes</entry> - <entry>numeric</entry> - <entry>API major revision level..</entry> -</row> -<row> - <entry>proto_minor</entry> - <entry>Yes</entry> - <entry>numeric</entry> - <entry>API minor revision level..</entry> -</row> -</tbody> -</tgroup> -</table> - -<para>The daemon ships a VERSION response to each client when the -client first connects to it.</para> - -<para>When the C client library parses a response of this kind, it -will assert the VERSION_SET bit in the top-level set member.</para> - -<para>Here's an example:</para> - -<programlisting> -{"class":"VERSION","version":"2.40dev","rev":"06f62e14eae9886cde907dae61c124c53eb1101f","proto_major":3,"proto_minor":1} -</programlisting> - - -</listitem> -</varlistentry> - -<varlistentry> -<term>?DEVICES;</term> -<listitem><para>Returns a device list object with the -following elements:</para> - -<table frame="all" pgwide="0"><title>DEVICES object</title> -<tgroup cols="3" align="left" colsep="1" rowsep="1"> -<thead> -<row> - <entry>Name</entry> - <entry>Always?</entry> - <entry>Type</entry> - <entry>Description</entry> -</row> -</thead> -<tbody> -<row> - <entry>class</entry> - <entry>Yes</entry> - <entry>string</entry> - <entry>Fixed: "DEVICES"</entry> -</row> -<row> - <entry>devices</entry> - <entry>Yes</entry> - <entry>list</entry> - <entry>List of device descriptions</entry> -</row> -</tbody> -</tgroup> -</table> - -<para>When the C client library parses a response of this kind, it -will assert the DEVICELIST_SET bit in the top-level set member.</para> - -<para>Here's an example:</para> - -<programlisting> -{"class"="DEVICES","devices":[ - {"class":"DEVICE","path":"/dev/pts/1","flags":1,"driver":"SiRF binary"}, - {"class":"DEVICE","path":"/dev/pts/3","flags":4,"driver":"AIVDM"}]} -</programlisting> - -<para>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.</para> - -</listitem> -</varlistentry> - -<varlistentry> -<term>?WATCH;</term> -<listitem> - -<para>This command sets watcher mode. It also sets or elicits a report -of per-subscriber policy and the raw bit. An argument WATCH object -changes the subscriber's policy. The response describes the -subscriber's policy. The response will also include a DEVICES -object.</para> - -<para>A WATCH object has the following elements:</para> - -<table frame="all" pgwide="0"><title>WATCH object</title> -<tgroup cols="4" align="left" colsep="1" rowsep="1"> -<thead> -<row> - <entry>Name</entry> - <entry>Always?</entry> - <entry>Type</entry> - <entry>Description</entry> -</row> -</thead> -<tbody> -<row> - <entry>class</entry> - <entry>Yes</entry> - <entry>string</entry> - <entry>Fixed: "WATCH"</entry> -</row> -<row> - <entry>enable</entry> - <entry>No</entry> - <entry>boolean</entry> - <entry>Enable (true) or disable (false) watcher mode. Default - is true.</entry> -</row> -<row> - <entry>json</entry> - <entry>No</entry> - <entry>boolean</entry> - <entry>Enable (true) or disable (false) dumping of JSON reports. - Default is false.</entry> -</row> -<row> - <entry>nmea</entry> - <entry>No</entry> - <entry>boolean</entry> - <entry>Enable (true) or disable (false) dumping of binary - packets as pseudo-NMEA. Default - is false.</entry> -</row> -<row> - <entry>raw</entry> - <entry>No</entry> - <entry>integer</entry> - - <entry>Controls 'raw' mode. When this attribute is set to 1 - for a channel, <application>gpsd</application> reports the - unprocessed NMEA or AIVDM data stream from whatever device is attached. - Binary GPS packets are hex-dumped. RTCM2 and RTCM3 - packets are not dumped in raw mode. When this attribute is set to - 2 for a channel that processes binary data, - <application>gpsd</application> reports the received data verbatim - without hex-dumping.</entry> -</row> -<row> - <entry>scaled</entry> - <entry>No</entry> - <entry>boolean</entry> - <entry>If true, apply scaling divisors to output before - dumping; default is false. Applies only to AIS and Subframe - reports.</entry> -</row> -<row> - <entry>device</entry> - <entry>No</entry> - <entry>string</entry> - <entry>If present, enable watching only of the specified device - rather than all devices. Useful with raw and NMEA modes - in which device responses aren't tagged. Has no effect when - used with enable:false.</entry> -</row> -</tbody> -</tgroup> -</table> - -<para>There is an additional boolean "timing" attribute which is -undocumented because that portion of the interface is considered -unstable and for developer use only.</para> - -<para>In watcher mode, GPS reports are dumped as TPV and SKY -responses. AIS, Subframe and RTCM reporting is described in the next -section.</para> - -<para>When the C client library parses a response of this kind, it -will assert the POLICY_SET bit in the top-level set member.</para> - -<para>Here's an example:</para> - -<programlisting> -{"class":"WATCH", "raw":1,"scaled":true} -</programlisting> - -</listitem> -</varlistentry> - -<varlistentry> -<term>?POLL;</term> -<listitem> - -<para>The POLL command requests data from the last-seen fixes on all -active GPS devices. Devices must previously have been activated by -?WATCH to be pollable, or have been specified on the GPSD command line -together with an <option>-n</option> option.</para> - -<para>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.</para> - -<para>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.</para> - -<table frame="all" pgwide="0"><title>POLL object</title> -<tgroup cols="3" align="left" colsep="1" rowsep="1"> -<thead> -<row> - <entry>Name</entry> - <entry>Always?</entry> - <entry>Type</entry> - <entry>Description</entry> -</row> -</thead> -<tbody> -<row> - <entry>class</entry> - <entry>Yes</entry> - <entry>string</entry> - <entry>Fixed: "POLL"</entry> -</row> -<row> - <entry>time</entry> - <entry>Yes</entry> - <entry>Numeric</entry> - <entry>Timestamp in ISO 8601 format. May have a - fractional part of up to .01sec precision.</entry> -</row> -<row> - <entry>active</entry> - <entry>Yes</entry> - <entry>Numeric</entry> - <entry>Count of active devices.</entry> -</row> -<row> - <entry>fixes</entry> - <entry>Yes</entry> - <entry>JSON array</entry> - <entry>Comma-separated list of TPV objects.</entry> -</row> -<row> - <entry>skyviews</entry> - <entry>Yes</entry> - <entry>JSON array</entry> - <entry>Comma-separated list of SKY objects.</entry> -</row> -</tbody> -</tgroup> -</table> - -<para>Here's an example of a POLL response:</para> - -<programlisting> -{"class":"POLL","time":"2010-06-04T10:31:00.289Z","active":1, - "tpv":[{"class":"TPV","tag":"MID41","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","tag":"MID41","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} -]}]} -</programlisting> - -<note> -<para>Client software should not assume the field inventory of the -POLL response is fixed for all time. As -<application>gpsd</application> collects and caches more data from -more sensor types, those data are likely to find their way -into this response.</para> -</note> - -</listitem> -</varlistentry> - -<varlistentry> -<term>?DEVICE</term> -<listitem> - -<para>This command reports (when followed by ';') the state of a -device, or sets (when followed by '=' and a DEVICE object) -device-specific control bits, notably the device's speed and serial -mode and the native-mode bit. The parameter-setting form will be rejected if -more than one client is attached to the channel.</para> - -<para>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.</para> - -<para>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.</para> - -<para>A DEVICE object has the following elements:</para> - -<table frame="all" pgwide="0"><title>CONFIGCHAN object</title> -<tgroup cols="4" align="left" colsep="1" rowsep="1"> -<thead> -<row> - <entry>Name</entry> - <entry>Always?</entry> - <entry>Type</entry> - <entry>Description</entry> -</row> -</thead> -<tbody> -<row> - <entry>class</entry> - <entry>Yes</entry> - <entry>string</entry> - <entry>Fixed: "DEVICE"</entry> -</row> -<row> - <entry>path</entry> - <entry>No</entry> - <entry>string</entry> - <entry>Name the device for which the control bits are - being reported, or for which they are to be applied. This - attribute may be omitted only when there is exactly one - subscribed channel.</entry> -</row> -<row> - <entry>activated</entry> - <entry>No</entry> - <entry>string</entry> - <entry>Time the device was activated as an ISO8601 - timestamp. If the device is inactive this attribute is - absent.</entry> -</row> -<row> - <entry>flags</entry> - <entry>No</entry> - <entry>integer</entry> - <entry>Bit vector of property flags. Currently defined flags are: - describe packet types seen so far (GPS, RTCM2, RTCM3, - AIS). Won't be reported if empty, e.g. before - <application>gpsd</application> has seen identifiable packets - from the device.</entry> -</row> -<row> - <entry>driver</entry> - <entry>No</entry> - <entry>string</entry> - <entry>GPSD's name for the device driver type. Won't be reported before - <application>gpsd</application> has seen identifiable packets - from the device.</entry> -</row> -<row> - <entry>subtype</entry> - <entry>When the daemon sees a delayed response to a probe for - subtype or firmware-version information.</entry> - <entry>string</entry> - <entry>Whatever version information the device returned.</entry> -</row> -<row> - <entry>bps</entry> - <entry>No</entry> - <entry>integer</entry> - <entry>Device speed in bits per second.</entry> -</row> -<row> - <entry>parity</entry> - <entry>Yes</entry> - <entry>string</entry> - <entry><para>N, O or E for no parity, odd, or even.</para></entry> -</row> -<row> - <entry>stopbits</entry> - <entry>Yes</entry> - <entry>string</entry> - <entry><para>Stop bits (1 or 2).</para></entry> -</row> -<row> - <entry>native</entry> - <entry>No</entry> - <entry>integer</entry> - <entry>0 means NMEA mode and 1 means - alternate mode (binary if it has one, for SiRF and Evermore chipsets - in particular). Attempting to set this mode on a non-GPS - device will yield an error.</entry> -</row> -<row> - <entry>cycle</entry> - <entry>No</entry> - <entry>real</entry> - <entry>Device cycle time in seconds.</entry> -</row> -<row> - <entry>mincycle</entry> - <entry>No</entry> - <entry>real</entry> - <entry>Device minimum cycle time in seconds. Reported from - ?CONFIGDEV when (and only when) the rate is switchable. It is - read-only and not settable.</entry> -</row> -</tbody> -</tgroup> -</table> - -<para>The serial parameters will be omitted in a response describing a -TCP/IP source such as an Ntrip, DGPSIP, or AIS feed.</para> - -<para>The contents of the flags field should be interpreted as follows:</para> - -<table frame="all" pgwide="0"><title>Device flags</title> -<tgroup cols="3" align="left" colsep="1" rowsep="1"> -<thead> -<row> - <entry>C #define</entry> - <entry>Value</entry> - <entry>Description</entry> -</row> -</thead> -<tbody> -<row> - <entry>SEEN_GPS</entry> - <entry>0x01</entry> - <entry>GPS data has been seen on this device</entry> -</row> -<row> - <entry>SEEN_RTCM2</entry> - <entry>0x02</entry> - <entry>RTCM2 data has been seen on this device</entry> -</row> -<row> - <entry>SEEN_RTCM3</entry> - <entry>0x04</entry> - <entry>RTCM3 data has been seen on this device</entry> -</row> -<row> - <entry>SEEN_AIS</entry> - <entry>0x08</entry> - <entry>AIS data has been seen on this device</entry> -</row> -</tbody> -</tgroup> -</table> - -<!-- -<para>The mincycle member may be 0, indicating no hard lower limit on the -cycle time. On an NMEA device of this kind it is possible to try to -push more characters through per cycle than the time to transmit will -allow. You must set the time high enough to let all sentences come -through. Here are the maxima to use for computation:</para> - -<table frame='all'> -<tgroup cols='2'> -<tbody> -<row><entry>ZDA </entry><entry>36</entry></row> -<row><entry>GLL </entry><entry>47</entry></row> -<row><entry>GGA </entry><entry>82</entry></row> -<row><entry>VTG </entry><entry>46</entry></row> -<row><entry>RMC </entry><entry>77</entry></row> -<row><entry>GSA </entry><entry>67</entry></row> -<row><entry>GSV </entry><entry>60 (per line, thus 180 for a set of 3)</entry> </row> -</tbody> -</tgroup> -</table> - -<para>The transmit time for a cycle (which must be less than 1 second) -is the total character count multiplied by 10 and divided by the baud -rate. A typical budget is GGA, RMC, GSA, 3*GSV = 82+75+67+(3*60) = -404.</para> ---> - -<para>When the C client library parses a response of this kind, it -will assert the DEVICE_SET bit in the top-level set member.</para> - -<para>Here's an example:</para> - -<programlisting> -{"class":"DEVICE", "speed":4800,"serialmode":"8N1","native":0} -</programlisting> - -</listitem> -</varlistentry> - -</variablelist> - -<para>When a client is in watcher mode, the daemon will ship it DEVICE -notifications when a device is added to the pool or -deactivated.</para> - -<para>When the C client library parses a response of this kind, it -will assert the DEVICE_SET bit in the top-level set member.</para> - -<para>Here's an example:</para> - -<programlisting> -{"class":"DEVICE","path":"/dev/pts1","activated":0} -</programlisting> - -<para>The daemon may ship an error object in response to a -syntactically invalid command line or unknown command. It has -the following elements:</para> - -<table frame="all" pgwide="0"><title>ERROR notification object</title> -<tgroup cols="4" align="left" colsep="1" rowsep="1"> -<thead> -<row> - <entry>Name</entry> - <entry>Always?</entry> - <entry>Type</entry> - <entry>Description</entry> -</row> -</thead> -<tbody> -<row> - <entry>class</entry> - <entry>Yes</entry> - <entry>string</entry> - <entry>Fixed: "ERROR"</entry> -</row> -<row> - <entry>message</entry> - <entry>Yes</entry> - <entry>string</entry> - <entry>Textual error message</entry> -</row> -</tbody> -</tgroup> -</table> - -<para>Here's an example:</para> - -<programlisting> -{"class":"ERROR","message":"Unrecognized request '?FOO'"} -</programlisting> - -<para>When the C client library parses a response of this kind, it -will assert the ERR_SET bit in the top-level set member.</para> - -</refsect1> - -<refsect1 id='overview'><title>RTCM2</title> - -<para>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.</para> - -<para>RTCM-104 comes in two major and incompatible flavors, 2.x and -3.x. Each major flavor has minor (compatible) revisions.</para> - -<para>The applicable standard for RTCM Version 2.x is <citetitle>RTCM -Recommended Standards for Differential NAVSTAR GPS Service</citetitle> -RTCM Paper 194-93/SC 104-STD. For RTCM 3.1 it is <citetitle>RTCM Paper -177-2006-SC104-STD</citetitle>. Ordering instructions for both -standards are accessible from the website of the <ulink -url='http://www.rtcm.org/'>Radio Technical Commission for Maritime -Services</ulink> under "Publications".</para> - -<refsect2 id='wire-format'><title>RTCM WIRE TRANSMISSIONS</title> - -<para>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.</para> - -<para>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.)</para> - -</refsect2> -<refsect2 id='rtcm-wire-format'><title>RTCM WIRE FORMATS</title> - -<para>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.</para> - -<para>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.</para> - -</refsect2> -<refsect2 id='rtcm2-dump-format2'><title>RTCM2 JSON FORMAT</title> - -<para>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.</para> - -<para>All attributes other than the device field are mandatory. Header -attributes are emitted before others.</para> - -<refsect3><title>Header portion</title> - -<table frame="all" pgwide="0"><title>SKY object</title> -<tgroup cols="3" align="left" colsep="1" rowsep="1"> -<thead> -<row> - <entry>Name</entry> <entry>Type</entry> <entry><para>Description</para></entry> </row> </thead> <tbody> <row> - <entry>class</entry> - <entry>string</entry> - <entry><para>Fixed: "RTCM2".</para></entry> + <entry>DBUS_TYPE_DOUBLE</entry> + <entry><para>Time (seconds since Unix epoch)</para></entry> </row> <row> - <entry>type</entry> - <entry>integer</entry> - <entry><para>Message type (1-9).</para></entry> + <entry>DBUS_TYPE_INT32</entry> + <entry><para>mode</para></entry> </row> <row> - <entry>station_id</entry> - <entry>integer</entry> - <entry><para>The id of the GPS reference receiver. The - LF transmitters also have (different) id numbers.</para></entry> + <entry>DBUS_TYPE_DOUBLE</entry> + <entry><para>Time uncertainty (seconds).</para></entry> </row> <row> - <entry>zcount</entry> - <entry>real</entry> - <entry><para>The reference time of the - corrections in the message in seconds within the current hour. Note - that it is in GPS time, which is some seconds ahead of UTC (see the - U.S. Naval Observatory's <ulink - url="ftp://maia.usno.navy.mil/ser7/tai-utc.dat">table of leap second - corrections</ulink>).</para></entry> + <entry>DBUS_TYPE_DOUBLE</entry> + <entry><para>Latitude in degrees.</para></entry> </row> <row> - <entry>seqnum</entry> - <entry>integer</entry> - <entry><para>Sequence number. Only 3 bits wide, wraps after 7.</para></entry> + <entry>DBUS_TYPE_DOUBLE</entry> + <entry><para>Longitude in degrees.</para></entry> </row> <row> - <entry>length</entry> - <entry>integer</entry> - <entry><para>The number of words after the header that comprise the - message.</para></entry> -</row> -<row> - <entry>station_health</entry> - <entry>integer</entry> - <entry><para>Station transmission status. Indicates the health of - the beacon as a reference source. Any nonzero value means the - satellite is probably transmitting bad data and should not be - used in a fix. 6 means the transmission is unmonitored. 7 - means the station is not working properly. Other values are - defined by the beacon operator.</para></entry> -</row> -</tbody> -</tgroup> -</table> - -<para><message type> is one of</para> - -<variablelist> -<varlistentry> -<term>1</term> -<listitem><para>full corrections - one message containing corrections for -all GPS satellites in view. This is not common.</para></listitem> -</varlistentry> - -<varlistentry> -<term>3</term> -<listitem><para>reference station parameters - the position of the -reference station GPS antenna.</para></listitem> -</varlistentry> - -<varlistentry> -<term>4</term> -<listitem><para>datum — the datum to which the DGPS data is -referred.</para></listitem> -</varlistentry> - -<varlistentry> -<term>5</term> -<listitem><para>constellation health — information about the -satellites the beacon can see.</para></listitem> -</varlistentry> - -<varlistentry> -<term>6</term> -<listitem><para>null message — just a filler.</para></listitem> -</varlistentry> - -<varlistentry> -<term>7</term> -<listitem><para>radio beacon almanac — information about this or other beacons.</para></listitem> -</varlistentry> - -<varlistentry> -<term>9</term> -<listitem><para>subset corrections — a message containing corrections -for only a subset of the GPS satellites in view.</para></listitem> -</varlistentry> - -<varlistentry> -<term>16</term> -<listitem><para>special message — a text message from the beacon -operator.</para></listitem> -</varlistentry> - -<varlistentry> -<term>31</term> -<listitem><para>GLONASS subset corrections — a message -containing corrections for a set of the GLONASS satellites in -view.</para></listitem> -</varlistentry> - - -</variablelist> - -</refsect3> -<refsect3><title>Type 1 and 9: Correction data</title> - -<para>One or more satellite objects follow the header for type 1 or type 9 -messages. Here is the format:</para> - -<table frame="all" pgwide="0"><title>Satellite object</title> -<tgroup cols="3" align="left" colsep="1" rowsep="1"> -<thead> -<row> - <entry>Name</entry> - <entry>Type</entry> - <entry><para>Description</para></entry> + <entry>DBUS_TYPE_DOUBLE</entry> + <entry><para>Horizontal uncertainty in meters, 95% confidence.</para></entry> </row> -</thead> -<tbody> <row> - <entry>ident</entry> - <entry>integer</entry> - <entry><para>The PRN number of the satellite for which this is - correction data.</para></entry> + <entry>DBUS_TYPE_DOUBLE</entry> + <entry><para>Altitude in meters.</para></entry> </row> <row> - <entry>udre</entry> - <entry>integer</entry> - <entry><para>User Differential Range Error (0-3). See the - table following for values.</para></entry> + <entry>DBUS_TYPE_DOUBLE</entry> + <entry><para>Altitude uncertainty in meters, 95% confidence.</para></entry> </row> <row> - <entry>iod</entry> - <entry>integer</entry> - <entry><para>Issue Of Data, matching the IOD for the current - ephemeris of this satellite, as transmitted by the satellite. - The IOD is a unique tag that identifies the ephemeris; the GPS - using the DGPS correction and the DGPS generating the data - must use the same orbital positions for the - satellite.</para></entry> + <entry>DBUS_TYPE_DOUBLE</entry> + <entry><para>Course in degrees from true north.</para></entry> </row> <row> - <entry>prc</entry> - <entry>real</entry> - <entry><para>The pseudorange error in meters for this - satellite as measured by the beacon reference receiver at the - epoch indicated by the z_count in the parent - record.</para></entry> + <entry>DBUS_TYPE_DOUBLE</entry> + <entry><para>Course uncertainty in meters, 95% confidence.</para></entry> </row> <row> - <entry>rrc</entry> - <entry>real</entry> - <entry><para>The rate of change of pseudorange error in - meters/sec for this satellite as measured by the beacon - reference receiver at the epoch indicated by the z_count field - in the parent record. This is used to calculate pseudorange - errors at other epochs, if required by the GPS - receiver.</para></entry> + <entry>DBUS_TYPE_DOUBLE</entry> + <entry><para>Speed, meters per second.</para></entry> </row> -</tbody> -</tgroup> -</table> - -<para>User Differential Range Error values are as follows:</para> - -<table frame="all" pgwide="0"><title>UDRE values</title> -<tgroup cols="2" align="left" colsep="1" rowsep="1"> -<tbody> -<row><entry>0</entry><entry>1-sigma error <= 1m</entry></row> -<row><entry>1</entry><entry>1-sigma error <= 4m</entry></row> -<row><entry>2</entry><entry>1-sigma error <= 8m</entry></row> -<row><entry>3</entry><entry>1-sigma error > 8m</entry></row> -</tbody> -</tgroup> -</table> - -<para>Here's an example:</para> - -<programlisting> -{"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} -]} -</programlisting> - -</refsect3> -<refsect3><title>Type 3: Reference Station Parameters</title> - -<para>Here are the payload members of a type 3 (Reference Station -Parameters) message:</para> - -<table frame="all" pgwide="0"><title>Reference Station Parameters</title> -<tgroup cols="3" align="left" colsep="1" rowsep="1"> -<thead> <row> - <entry>Name</entry> - <entry>Type</entry> - <entry><para>Description</para></entry> + <entry>DBUS_TYPE_DOUBLE</entry> + <entry><para>Speed uncertainty in meters per second, + 95% confidence.</para></entry> </row> -</thead> -<tbody> <row> - <entry>x</entry> - <entry>real</entry> - <entry><para>ECEF X coordinate.</para></entry> + <entry>DBUS_TYPE_DOUBLE</entry> + <entry><para>Climb, meters per second.</para></entry> </row> <row> - <entry>y</entry> - <entry>real</entry> - <entry><para>ECEF Y coordinate.</para></entry> + <entry>DBUS_TYPE_DOUBLE</entry> + <entry><para>Climb uncertainty in meters per second, + 95% confidence.</para></entry> </row> <row> - <entry>z</entry> - <entry>real</entry> - <entry><para>ECEF Z coordinate.</para></entry> + <entry>DBUS_TYPE_STRING</entry> + <entry><para>Device name</para></entry> </row> </tbody> </tgroup> </table> -<para>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 to some other reference frame in other -parts of the world.</para> - -<para>An invalid reference message is represented by a type 3 header -without payload fields.</para> - -<para>Here's an example:</para> - -<programlisting> -{"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}
-</programlisting> - -</refsect3> -<refsect3><title>Type 4: Datum</title> - -<para>Here are the payload members of a type 4 (Datum) message:</para> - -<table frame="all" pgwide="0"><title>Datum</title> -<tgroup cols="3" align="left" colsep="1" rowsep="1"> -<thead> -<row> - <entry>Name</entry> - <entry>Type</entry> - <entry><para>Description</para></entry> -</row> -</thead> -<tbody> -<row> - <entry>dgnss_type</entry> - <entry>string</entry> - <entry><para>Either "GPS", "GLONASS", "GALILEO", or - "UNKNOWN".</para></entry> -</row> -<row> - <entry>dat</entry> - <entry>integer</entry> - <entry><para>0 or 1 and indicates the sense of the offset - shift given by dx, dy, dz. dat = 0 means that the station - coordinates (in the reference message) are referred to a local - datum and that adding dx, dy, dz to that position will render - it in GNSS coordinates (WGS84 for GPS). If dat = 1 then the - ref station position is in GNSS coordinates and adding dx, dy, - dz will give it referred to the local datum.</para></entry> -</row> -<row> - <entry>datum_name</entry> - <entry>string</entry> - <entry><para>A standard name for the datum.</para></entry> -</row> - -<row> - <entry>dx</entry> - <entry>real</entry> - <entry><para>X offset.</para></entry> -</row> -<row> - <entry>dy</entry> - <entry>real</entry> - <entry><para>Y offset.</para></entry> -</row> -<row> - <entry>dz</entry> - <entry>real</entry> - <entry><para>Z offset.</para></entry> -</row> -</tbody> -</tgroup> -</table> - -<para><dx> <dy> <dz> are offsets to convert from -local datum to GNSS datum or vice versa. These fields are -optional.</para> - -<para>An invalid datum message is represented by a type 4 header -without payload fields.</para> - -</refsect3> -<refsect3><title>Type 5: Constellation Health</title> - -<para>One or more of these follow the header for type 5 messages — one -for each satellite.</para> - -<para>Here is the format:</para> - -<table frame="all" pgwide="0"><title>Constellation health</title> -<tgroup cols="3" align="left" colsep="1" rowsep="1"> -<thead> -<row> - <entry>Name</entry> - <entry>Type</entry> - <entry><para>Description</para></entry> -</row> -</thead> -<tbody> -<row> - <entry>ident</entry> - <entry>integer</entry> - <entry><para>The PRN number of the satellite.</para></entry> -</row> -<row> - <entry>iodl</entry> - <entry>bool</entry> - <entry><para>True indicates that this information relates to - the satellite information in an accompanying type 1 or type 9 - message.</para></entry> -</row> -<row> - <entry>health</entry> - <entry>integer</entry> - <entry>0 indicates that the satellite is healthy. Any other value - indicates a problem (coding is not known).<para></para></entry> -</row> -<row> - <entry>snr</entry> - <entry>integer</entry> - <entry><para>The carrier/noise ratio of the received signal in - the range 25 to 55 dB(Hz).</para></entry> -</row> -<row> - <entry>health_en</entry> - <entry>bool</entry> - <entry><para>If set to Teue it indicates that the satellite is - healthy even if the satellite navigation data says it is - unhealthy.</para></entry> -</row> -<row> - <entry>new_data</entry> - <entry>bool</entry> - <entry>True indicates that the IOD for this satellite will - soon be updated in type 1 or 9 messages.<para></para></entry> -</row> -<row> - <entry>los_warning</entry> - <entry>bool</entry> - <entry><para>Line-of-sight warning. True indicates that the - satellite will shortly go unhealthy.</para></entry> -</row> -<row> - <entry>tou</entry> - <entry>integer</entry> - <entry><para>Healthy time remaining in seconds.</para></entry> -</row> -</tbody> -</tgroup> -</table> - -</refsect3> -<refsect3><title>Type 6: Null</title> - -<para>This just indicates a null message. There are no payload fields.</para> -</refsect3> - -<refsect3><title>Unknown message</title> - -<para>This format is used to dump message words in hexadecimal when the -message type field doesn't match any of the known ones.</para> - -<para>Here is the format:</para> - -<table frame="all" pgwide="0"><title>Unknown Message</title> -<tgroup cols="3" align="left" colsep="1" rowsep="1"> -<thead> -<row> - <entry>Name</entry> - <entry>Type</entry> - <entry><para>Description</para></entry> -</row> -</thead> -<tbody> -<row> - <entry>data</entry> - <entry>list</entry> - <entry><para>A list of strings.</para></entry> -</row> -</tbody> -</tgroup> -</table> - -<para>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.</para> - -</refsect3> -<refsect3><title>Type 7: Radio Beacon Almanac</title> - -<para>Here is the format:</para> - -<table frame="all" pgwide="0"><title>Contellation health</title> -<tgroup cols="3" align="left" colsep="1" rowsep="1"> -<thead> -<row> - <entry>Name</entry> - <entry>Type</entry> - <entry><para>Description</para></entry> -</row> -</thead> -<tbody> -<row> - <entry>lat</entry> - <entry>real</entry> - <entry><para>Latitude in degrees, of the LF transmitter - antenna for the station for which this is an almanac. North - is positive.</para></entry> -</row> -<row> - <entry>lon</entry> - <entry>real</entry> - <entry><para>Longitude in degrees, of the LF transmitter - antenna for the station for which this is an almanac. - East is positive.</para></entry> -</row> -<row> - <entry>range</entry> - <entry>integer</entry> - <entry>Published range of the station in km.<para></para></entry> -</row> -<row> - <entry>frequency</entry> - <entry>real</entry> - <entry><para>Station broadcast frequency in kHz.</para></entry> -</row> -<row> - <entry>health</entry> - <entry>integer</entry> - <entry><para><health> is the health of the station for - which this is an almanac. If it is non-zero, the station is - issuing suspect data and should not be used for fixes. The - ITU and RTCM104 standards differ about the mode detailed - interpretation of the <health> field and even about its - bit width. -<!-- -From itu p.9 just under the type7 msg figure: - - *** Radiobeacon health: - 00 (0) Radiobeacon operation normal - 01 (1) No integrity monitor operating - 10 (2) No information available - 11 (3) Do not use this radiobeacon -RTCM104, in the other hand, makes it 3 bits wide. - -The Sager documentation said health has the same meaning as in the header. -but this cannot be true unless the field is 3 bits wide. ---> - </para></entry> -</row> -<row> - <entry>station_id</entry> - <entry>integer</entry> - <entry><para>The id of the transmitter. This is not the same - as the reference id in the header, the latter being the id of - the reference receiver. <!-- John Sager noted: "However I know - of at least one stationthat gets it wrong." --></para></entry> -</row> -<row> - <entry>bitrate</entry> - <entry>integer</entry> - <entry><para>The transmitted bitrate.</para></entry> -</row> -</tbody> -</tgroup> -</table> - -<para>Here's an example:</para> - -<programlisting> -{"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} -]} -</programlisting> - -</refsect3> -<refsect3><title>Type 13: GPS Time of Week</title> - -<para>Here are the payload members of a type 13 (Groumf Tramitter Parameters) -message:</para> - -<table frame="all" pgwide="0"><title>Grund Transmitter Parameters</title> -<tgroup cols="3" align="left" colsep="1" rowsep="1"> -<thead> -<row> - <entry>Name</entry> - <entry>Type</entry> - <entry><para>Description</para></entry> -</row> -</thead> -<tbody> -<row> - <entry>status</entry> - <entry>bool</entry> - <entry><para>If True, signals user to expect a type 16 explanatory - message associated with this station. Probably indicates some - sort of unusual event.</para></entry> -</row> -<row> - <entry>rangeflag</entry> - <entry>bool</entry> - <entry><para>If True, indicates that the estimated range is - different from that found in the Type 7 message (which contains the - beacon's listed range). Generally indicates a range reduction due to - causes such as poor ionospheric conditions or reduced transmission - power.</para></entry> -</row> -<row> - <entry>lat</entry> - <entry>real</entry> - <entry><para>Degrees latitude, signed. - Positive is N, negative is S.</para></entry> -</row> -<row> - <entry>lon</entry> - <entry>real</entry> - <entry><para>Degrees longitude, signed. - Positive is E, negative is W.</para></entry> -</row> -<row> - <entry>range</entry> - <entry>integer</entry> - <entry><para>Transmission range in km (1-1024).</para></entry> -</row> -</tbody> -</tgroup> -</table> - -<para>This message type replaces message type 3 (Reference Station Parameters) -in RTCM 2.3.</para> - -</refsect3> -<refsect3><title>Type 14: GPS Time of Week</title> - -<para>Here are the payload members of a type 14 (GPS Time of Week) -message:</para> - -<table frame="all" pgwide="0"><title>Reference Station Parameters</title> -<tgroup cols="3" align="left" colsep="1" rowsep="1"> -<thead> -<row> - <entry>Name</entry> - <entry>Type</entry> - <entry><para>Description</para></entry> -</row> -</thead> -<tbody> -<row> - <entry>week</entry> - <entry>integer</entry> - <entry><para>GPS week (0-123).</para></entry> -</row> -<row> - <entry>hour</entry> - <entry>integer</entry> - <entry><para>Hour of week (0-167).</para></entry> -</row> -<row> - <entry>leapsecs</entry> - <entry>integer</entry> - <entry><para>Leap Seconds (0-63).</para></entry> -</row> -</tbody> -</tgroup> -</table> - -<para>Here's an example:</para> - -<programlisting> -{"class":"RTCM2","type":14,"station_id":652,"zcount":1657.2, - "seqnum":3,"length":1,"station_health":6,"week":601,"hour":109, - "leapsecs":15}
-</programlisting> - -</refsect3> -<refsect3><title>Type 16: Special Message</title> - -<table frame="all" pgwide="0"><title>Special Message</title> -<tgroup cols="3" align="left" colsep="1" rowsep="1"> -<thead> -<row> - <entry>Name</entry> - <entry>Type</entry> - <entry><para>Description</para></entry> -</row> -</thead> -<tbody> -<row> - <entry>message</entry> - <entry>string</entry> - <entry><para>A text message sent by the beacon operator.</para></entry> -</row> -</tbody> -</tgroup> -</table> - -</refsect3> -<refsect3><title>Type 31: Correction data</title> - -<para>One or more GLONASS satellite objects follow the header for type -1 or type 9 messages. Here is the format:</para> - -<table frame="all" pgwide="0"><title>Satellite object</title> -<tgroup cols="3" align="left" colsep="1" rowsep="1"> -<thead> -<row> - <entry>Name</entry> - <entry>Type</entry> - <entry><para>Description</para></entry> -</row> -</thead> -<tbody> -<row> - <entry>ident</entry> - <entry>integer</entry> - <entry><para>The PRN number of the satellite for which this is - correction data.</para></entry> -</row> -<row> - <entry>udre</entry> - <entry>integer</entry> - <entry><para>User Differential Range Error (0-3). See the - table following for values.</para></entry> -</row> -<row> - <entry>change</entry> - <entry>boolean</entry> - <entry><para>Change-of-ephemeris bit.</para></entry> -</row> -<row> - <entry>tod</entry> - <entry>uinteger</entry> - <entry><para>Count of 30-second periods since the top of the - hour.</para></entry> -</row> -<row> - <entry>prc</entry> - <entry>real</entry> - <entry><para>The pseudorange error in meters for this - satellite as measured by the beacon reference receiver at the - epoch indicated by the z_count in the parent - record.</para></entry> -</row> -<row> - <entry>rrc</entry> - <entry>real</entry> - <entry><para>The rate of change of pseudorange error in - meters/sec for this satellite as measured by the beacon - reference receiver at the epoch indicated by the z_count field - in the parent record. This is used to calculate pseudorange - errors at other epochs, if required by the GPS - receiver.</para></entry> -</row> -</tbody> -</tgroup> -</table> - -<para>Here's an example:</para> - -<programlisting> -{"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} -]} -</programlisting> - -</refsect3> -</refsect2> -<refsect2 id='dump-format3'><title>RTCM3 DUMP FORMAT</title> - -<para>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.</para> -</refsect2> -</refsect1> - -<refsect1 id='ais'><title>AIS DUMP FORMATS</title> - -<para>AIS support is an extension. It may not be present if your -instance of <application>gpsd</application> has been built with -a restricted feature set.</para> - -<para>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 <ulink -url="http://gpsd.berlios.de/AIVDM.html">"AIVDM/AIVDO Protocol -Decoding"</ulink> document; each message field table may be directly -interpreted as a specification for the members of the corresponding -JSON object type.</para> - -<para>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. Navigation status and positioning-system -type are dumped as text strings rather than IAS numeric codes. 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 IAS 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 <ulink -url="http://gpsd.berlios.de/AIVDM.html">"AIVDM/AIVDO Protocol -Decoding"</ulink>.</para> - </refsect1> -<refsect1 id='subframe'><title>SUBFRAME DUMP FORMATS</title> - -<para>Subframe support is always compiled into -<application>gpsd</application> but many GPS do not output Subframe data -or the <application>gpsd</application> driver may not support Subframes. -</para> - -<para>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.</para> -</refsect1> <refsect1 id='devices'><title>GPS DEVICE MANAGEMENT</title> <para><application>gpsd</application> maintains an internal list of @@ -2977,6 +881,7 @@ D(t)</citetitle></para> <para> <citerefentry><refentrytitle>gps</refentrytitle><manvolnum>1</manvolnum></citerefentry>, <citerefentry><refentrytitle>libgps</refentrytitle><manvolnum>3</manvolnum></citerefentry>, +<citerefentry><refentrytitle>gpsd_json</refentrytitle><manvolnum>5</manvolnum></citerefentry>, <citerefentry><refentrytitle>libgpsd</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>gpsprof</refentrytitle><manvolnum>1</manvolnum></citerefentry>, <citerefentry><refentrytitle>gpsfake</refentrytitle><manvolnum>1</manvolnum></citerefentry>, |