diff options
Diffstat (limited to 'man/gpsd_json.xml')
| -rw-r--r-- | man/gpsd_json.xml | 2609 |
1 files changed, 2609 insertions, 0 deletions
diff --git a/man/gpsd_json.xml b/man/gpsd_json.xml new file mode 100644 index 00000000..1c868b61 --- /dev/null +++ b/man/gpsd_json.xml @@ -0,0 +1,2609 @@ +<?xml version="1.0" encoding="ISO-8859-1"?> +<!-- +This file is Copyright (c) 2010-2018 by the GPSD project +SPDX-License-Identifier: BSD-2-clause +--> +<!DOCTYPE refentry PUBLIC + "-//OASIS//DTD DocBook XML V4.1.2//EN" + "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [ +<!ENTITY gpsdsock "/var/run/gpsd.sock"> +]> +<refentry id='gpsd_json.5'> +<refentryinfo><date>17 Jun 2018</date></refentryinfo> +<refmeta> +<refentrytitle>gpsd_json</refentrytitle> +<manvolnum>5</manvolnum> +<refmiscinfo class="source">The GPSD Project</refmiscinfo> +<refmiscinfo class="manual">GPSD Documentation</refmiscinfo> +</refmeta> +<refnamediv id='name'> +<refname>gpsd_json</refname> +<refpurpose>gpsd request/response protocol</refpurpose> +</refnamediv> + +<refsect1 id='overview'><title>OVERVIEW</title> + +<para><application>gpsd</application> is a service daemon that can be used +to monitor GPSes, DGPS receivers, Marine AIS broadcasts, and various other +location-related and kinematic sensors.</para> + +<para>Clients may communicate with <application>gpsd</application> 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 <application>libgps</application> 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.</para> + +<para>The GPSD protocol is built on top of JSON, JavaScript Object +Notation, as specified in RFC 7159: <citetitle>The JavaScript Object +Notation (JSON) Data Interchange Format</citetitle>. 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, then 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 next subsection section documents the core GPSD protocol. +Extensions are documented in the following subsections. The extensions +may not be supported in your <application>gpsd</application> instance +if it has been compiled with a restricted feature set.</para> + +</refsect1> +<refsect1 id='core-protocol'><title>CORE SOCKET PROTOCOL</title> + +<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>device</entry> + <entry>No</entry> + <entry>string</entry> + <entry>Name of originating device.</entry> +</row> +<row> + <entry>status</entry> + <entry>No</entry> + <entry>numeric</entry> + <entry>GPS status: %d, 2=DGPS fix, otherwise not present.</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 .001sec 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 North/South. Present + when mode is 2 or 3.</entry> +</row> +<row> + <entry>lon</entry> + <entry>No</entry> + <entry>numeric</entry> + <entry>Longitude in degrees: +/- signifies East/West. 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>magtrack</entry> + <entry>No</entry> + <entry>numeric</entry> + <entry>Course over ground, degrees magnetic.</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% confidence.</entry> +</row> +<row> + <entry>eps</entry> + <entry>No</entry> + <entry>numeric</entry> + <entry>Speed error estinmate in meters/sec, 95% confidence.</entry> +</row> +<row> + <entry>epc</entry> + <entry>No</entry> + <entry>numeric</entry> + <entry>Climb/sink error estimate in meters/sec, 95% confidence.</entry> +</row> +<row> + <entry>ecefx</entry> + <entry>No</entry> + <entry>numeric</entry> + <entry>ECEF X position in meters.</entry> +</row> +<row> + <entry>ecefy</entry> + <entry>No</entry> + <entry>numeric</entry> + <entry>ECEF Y position in meters.</entry> +</row> +<row> + <entry>ecefz</entry> + <entry>No</entry> + <entry>numeric</entry> + <entry>ECEF Z position in meters.</entry> +</row> +<row> + <entry>ecefpAcc</entry> + <entry>No</entry> + <entry>numeric</entry> + <entry>ECEF position error in meters.</entry> +</row> +<row> + <entry>ecefvx</entry> + <entry>No</entry> + <entry>numeric</entry> + <entry>ECEF X velocity in meters/second.</entry> +</row> +<row> + <entry>ecefvy</entry> + <entry>No</entry> + <entry>numeric</entry> + <entry>ECEF Y velocity in meters/second.</entry> +</row> +<row> + <entry>ecefvz</entry> + <entry>No</entry> + <entry>numeric</entry> + <entry>ECEF Z velocity in meters/second.</entry> +</row> +<row> + <entry>ecefvAcc</entry> + <entry>No</entry> + <entry>numeric</entry> + <entry>ECEF velocity error in meters/second.</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","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>device</entry> + <entry>No</entry> + <entry>string</entry> + <entry>Name of originating device</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 .001sec 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>satellites</entry> + <entry>Yes</entry> + <entry>list</entry> + <entry>List of satellite objects in skyview</entry> +</row> + +</tbody> +</tgroup> +</table> + +<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>The satellite list objects have the following elements:</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. 1-63 are GNSS satellites, + 64-96 are GLONASS satellites, 100-164 are SBAS satellites</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? (SBAS/WAAS/EGNOS satellites + may be flagged used if the solution has corrections from them, + but not all drivers make this information available.)</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","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>device</entry> + <entry>No</entry> + <entry>string</entry> + <entry>Name of originating device</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 .001sec 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","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" and "mode" 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>device</entry> + <entry>Yes</entry> + <entry>string</entry> + <entry>Name of originating device</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 .001sec 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>Local magnetic inclination, degrees, positive when the magnetic +field points downward (into the Earth).</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>acc_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>temp</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","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} +</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> +<row> + <entry>remote</entry> + <entry>No</entry> + <entry>string</entry> + <entry>URL of the remote daemon reporting this version. If + empty, this is the version of the local daemon.</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> +<row> + <entry>remote</entry> + <entry>No</entry> + <entry>string</entry> + <entry>URL of the remote daemon reporting the device set. If + empty, this is a DEVICES response from the local daemon.</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.</entry> +</row> +<row> + <entry>split24</entry> + <entry>No</entry> + <entry>boolean</entry> + <entry>If true, aggregate AIS type24 sentence parts. If false, + report each part as a separate JSON object, leaving the + client to match MMSIs and aggregate. Default is + false. Applies only to AIS reports.</entry> +</row> +<row> + <entry>pps</entry> + <entry>No</entry> + <entry>boolean</entry> + <entry>If true, emit the TOFF JSON message on each cycle and a + PPS JSON message when the device issues 1PPS. Default is false.</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> +<row> + <entry>remote</entry> + <entry>No</entry> + <entry>string</entry> + <entry>URL of the remote daemon reporting the watch set. If + empty, this is a WATCH response from the local daemon.</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.</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 .001sec precision.</entry> +</row> +<row> + <entry>active</entry> + <entry>Yes</entry> + <entry>Numeric</entry> + <entry>Count of active devices.</entry> +</row> +<row> + <entry>tpv</entry> + <entry>Yes</entry> + <entry>JSON array</entry> + <entry>Comma-separated list of TPV objects.</entry> +</row> +<row> + <entry>sky</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","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} +]}]} +</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>TOFF</term> +<listitem> + +<para>This message is emitted on each cycle and reports the offset +between the host's clock time and the GPS time at top of second +(actually, when the first data for the reporting cycle is received).</para> + +<para>This message exactly mirrors the PPS message except for two +details.</para> + +<para>TOFF emits no NTP precision, this is assumed to be -2. See +the NTP documentation for their definition of precision.</para> + +<para> 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.</para> + +<para>A TOFF object has the following elements:</para> + +<table frame="all" pgwide="0"><title>TOFF 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: "TOFF"</entry> +</row> +<row> + <entry>device</entry> + <entry>Yes</entry> + <entry>string</entry> + <entry>Name of originating device</entry> +</row> +<row> + <entry>real_sec</entry> + <entry>Yes</entry> + <entry>numeric</entry> + <entry>seconds from the GPS clock</entry> +</row> +<row> + <entry>real_nsec</entry> + <entry>Yes</entry> + <entry>numeric</entry> + <entry>nanoseconds from the GPS clock</entry> +</row> +<row> + <entry>clock_sec</entry> + <entry>Yes</entry> + <entry>numeric</entry> + <entry>seconds from the system clock</entry> +</row> +<row> + <entry>clock_nsec</entry> + <entry>Yes</entry> + <entry>numeric</entry> + <entry>nanoseconds from the system clock</entry> +</row> +</tbody> +</tgroup> +</table> + +<para>This message is emitted once per second to watchers of a device +and is intended to report the time stamps of the in-band report of the +GPS and seconds as reported by the system clock (which may be +NTP-corrected) when the first valid timestamp of the reporting cycle +was seen.</para> + +<para>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.</para> + +<para>Here's an example:</para> + +<programlisting> +{"class":"TOFF","device":"/dev/ttyUSB0", + "real_sec":1330212592, "real_nsec":343182, + "clock_sec":1330212592,"clock_nsec":343184, + "precision":-2}} +</programlisting> + +</listitem> +</varlistentry> + +<varlistentry> +<term>PPS</term> +<listitem> + +<para>This message is emitted each time the daemon sees a valid PPS (Pulse +Per Second) strobe from a device.</para> + +<para>This message exactly mirrors the TOFF message except for two +details.</para> + +<para>PPS emits the NTP precision. See the NTP documentation for their +definition of precision.</para> + +<para>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.</para> + +<para>There are various sources of error in the reported clock times. +The speed of the serial connection between the GPS and the system adds +a delay to start of cycle detection. An even bigger error is added +by the variable computation time inside the GPS. Taken together the +time derived from the start of the GPS cycle can have offsets of +10 millisecond to 700 milliseconds and combined jjitter and wander of +100 to 300 millisecond.</para> + +<para>A PPS object has the following elements:</para> + +<table frame="all" pgwide="0"><title>PPS 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: "PPS"</entry> +</row> +<row> + <entry>device</entry> + <entry>Yes</entry> + <entry>string</entry> + <entry>Name of originating device</entry> +</row> +<row> + <entry>real_sec</entry> + <entry>Yes</entry> + <entry>numeric</entry> + <entry>seconds from the PPS source</entry> +</row> +<row> + <entry>real_nsec</entry> + <entry>Yes</entry> + <entry>numeric</entry> + <entry>nanoseconds from the PPS source</entry> +</row> +<row> + <entry>clock_sec</entry> + <entry>Yes</entry> + <entry>numeric</entry> + <entry>seconds from the system clock</entry> +</row> +<row> + <entry>clock_nsec</entry> + <entry>Yes</entry> + <entry>numeric</entry> + <entry>nanoseconds from the system clock</entry> +</row> +<row> + <entry>precision</entry> + <entry>Yes</entry> + <entry>numeric</entry> + <entry>NTP style estimate of PPS precision</entry> +</row> +</tbody> +</tgroup> +</table> + +<para>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.</para> + +<para>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.</para> + +<para>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.</para> + +<para>Here's an example:</para> + +<programlisting> +{"class":"PPS","device":"/dev/ttyUSB0", + "real_sec":1330212592, "real_nsec":343182, + "clock_sec":1330212592,"clock_nsec":343184, + "precision":-3} +</programlisting> + +</listitem> +</varlistentry> + +<varlistentry> +<term>OSC</term> +<listitem> + +<para>This message reports the status of a GPS-disciplined oscillator +(GPSDO). The GPS PPS output (which has excellent long-term stability) +is typically used to discipline a local oscillator with much better +short-term stability (such as a rubidium atomic clock).</para> + +<para>An OSC object has the following elements:</para> + +<table frame="all" pgwide="0"><title>OSC 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: "OSC"</entry> +</row> +<row> + <entry>device</entry> + <entry>Yes</entry> + <entry>string</entry> + <entry>Name of originating device.</entry> +</row> +<row> + <entry>running</entry> + <entry>Yes</entry> + <entry>boolean</entry> + <entry>If true, the oscillator is currently running. Oscillators may require warm-up time at start of day.</entry> +</row> +<row> + <entry>reference</entry> + <entry>Yes</entry> + <entry>boolean</entry> + <entry>If true, the oscillator is receiving a GPS PPS signal.</entry> +</row> +<row> + <entry>disciplined</entry> + <entry>Yes</entry> + <entry>boolean</entry> + <entry>If true, the GPS PPS signal is sufficiently stable and is being used to discipline the local oscillator.</entry> +</row> +<row> + <entry>delta</entry> + <entry>Yes</entry> + <entry>numeric</entry> + <entry>The time difference (in nanoseconds) between the GPS-disciplined oscillator PPS output pulse and the most recent GPS PPS input pulse.</entry> +</row> +</tbody> +</tgroup> +</table> + +<para>Here's an example:</para> + +<programlisting> +{"class":"OSC","running":true,"device":"/dev/ttyUSB0", + "reference":true,"disciplined":true,"delta":67} +</programlisting> +</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>DEVICE 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>No</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 + ?DEVICE 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 (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.</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","bps":4800,"parity":"N","stopbits":1,"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='rtcm2'><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> +</row> +<row> + <entry>type</entry> + <entry>integer</entry> + <entry><para>Message type (1-9).</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> +</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> +</row> +<row> + <entry>seqnum</entry> + <entry>integer</entry> + <entry><para>Sequence number. Only 3 bits wide, wraps after 7.</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> +</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>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> +</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>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> +</row> +</thead> +<tbody> +<row> + <entry>x</entry> + <entry>real</entry> + <entry><para>ECEF X coordinate.</para></entry> +</row> +<row> + <entry>y</entry> + <entry>real</entry> + <entry><para>ECEF Y coordinate.</para></entry> +</row> +<row> + <entry>z</entry> + <entry>real</entry> + <entry><para>ECEF Z coordinate.</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 True 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 station that 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> +</refsect1> + +<refsect1 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> +</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 <citetitle>AIVDM/AIVDO Protocol Decoding</citetitle> 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.</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. 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 +<citetitle>"AIVDM/AIVDO Protocol Decoding"</citetitle>.</para> + +</refsect1> +<refsect1 id='subframe'><title>SUBFRAME DUMP FORMATS</title> + +<para>Subframe support is always compiled into +<application>gpsd</application> but many GPSes 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='see_also'><title>SEE ALSO</title> +<para> +<citerefentry><refentrytitle>gpsd</refentrytitle><manvolnum>8</manvolnum></citerefentry>, +<citerefentry><refentrytitle>libgps</refentrytitle><manvolnum>3</manvolnum></citerefentry>, +</para> +</refsect1> + +<refsect1 id='maintainer'><title>AUTHOR</title> + +<para>The protocol was designed and documented by Eric S. Raymond.</para> +</refsect1> + +</refentry> |