diff options
Diffstat (limited to 'man')
-rw-r--r-- | man/gps.xml | 321 | ||||
-rw-r--r-- | man/gps2udp.xml | 129 | ||||
-rw-r--r-- | man/gpscat.xml | 134 | ||||
-rw-r--r-- | man/gpsctl.xml | 284 | ||||
-rw-r--r-- | man/gpsd.xml | 905 | ||||
-rw-r--r-- | man/gpsd_json.xml | 2609 | ||||
-rw-r--r-- | man/gpsdctl.xml | 81 | ||||
-rw-r--r-- | man/gpsdecode.xml | 147 | ||||
-rw-r--r-- | man/gpsfake.xml | 264 | ||||
-rw-r--r-- | man/gpsinit.xml | 170 | ||||
-rw-r--r-- | man/gpsmon.xml | 428 | ||||
-rw-r--r-- | man/gpspipe.xml | 185 | ||||
-rw-r--r-- | man/gpsprof.xml | 291 | ||||
-rw-r--r-- | man/gpsrinex.xml | 195 | ||||
-rw-r--r-- | man/gpxlogger.xml | 149 | ||||
-rw-r--r-- | man/libgps.xml | 393 | ||||
-rw-r--r-- | man/libgpsmm.xml | 83 | ||||
-rw-r--r-- | man/ntpshmmon.xml | 165 | ||||
-rw-r--r-- | man/ppscheck.xml | 103 | ||||
-rw-r--r-- | man/srec.xml | 308 | ||||
-rw-r--r-- | man/ubxtool.xml | 458 | ||||
-rw-r--r-- | man/zerk.xml | 468 |
22 files changed, 8270 insertions, 0 deletions
diff --git a/man/gps.xml b/man/gps.xml new file mode 100644 index 00000000..5af9a4be --- /dev/null +++ b/man/gps.xml @@ -0,0 +1,321 @@ +<?xml version="1.0" encoding="ISO-8859-1"?> +<!-- +This file is Copyright (c) 2010 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"> +<refentry id='gps.1'> +<refentryinfo><date>9 Aug 2004</date></refentryinfo> +<refmeta> +<refentrytitle>gps</refentrytitle> +<manvolnum>1</manvolnum> +<refmiscinfo class="source">The GPSD Project</refmiscinfo> +<refmiscinfo class="manual">GPSD Documentation</refmiscinfo> +</refmeta> +<refnamediv id='name'> +<refname>cgps</refname> +<refname>gegps</refname> +<refname>gps</refname> +<refname>lcdgps</refname> +<refname>xgps</refname> +<refname>xgpsspeed</refname> +<refpurpose>test clients for gpsd</refpurpose> +</refnamediv> +<refsynopsisdiv id='synopsis'> + +<cmdsynopsis> + <command>cgps</command> + <arg choice='opt'>-D <replaceable>debug-level</replaceable></arg> + <arg choice='opt'>-h </arg> + <arg choice='opt'>-l <group><arg>d</arg><arg>m</arg><arg>s</arg></group></arg> + <arg choice='opt'>-m </arg> + <arg choice='opt'>-s </arg> + <arg choice='opt'>-u <group><arg>i</arg><arg>n</arg><arg>m</arg></group></arg> + <arg choice='opt'>-V </arg> + <group> + <replaceable>server</replaceable> + <group> + <replaceable>:port</replaceable> + <group><replaceable>:device</replaceable></group> + </group> + </group> +</cmdsynopsis> +<cmdsynopsis> + <command>gegps</command> + <arg choice='opt'>-d <replaceable>directory</replaceable></arg> + <arg choice='opt'>-h </arg> + <arg choice='opt'>-i </arg> + <arg choice='opt'>-V </arg> +</cmdsynopsis> +<cmdsynopsis> + <command>lcdgps</command> + <arg choice='opt'>-h </arg> + <arg choice='opt'>-j </arg> + <arg choice='opt'>-l <group><arg>d</arg><arg>m</arg><arg>s</arg></group></arg> + <arg choice='opt'>-s </arg> + <arg choice='opt'>-u <group><arg>i</arg><arg>n</arg><arg>m</arg></group></arg> + <arg choice='opt'>-V </arg> + <group> + <replaceable>server</replaceable> + <group> + <replaceable>:port</replaceable> + <group><replaceable>:device</replaceable></group> + </group> + </group> +</cmdsynopsis> +<cmdsynopsis> + <command>xgps</command> + <arg choice='opt'>-? </arg> + <arg choice='opt'>-D <replaceable>debug-level</replaceable></arg> + <arg choice='opt'>-h </arg> + <arg choice='opt'>-l <group><arg>d</arg><arg>m</arg><arg>s</arg></group></arg> + <arg choice='opt'>-u <group><arg>i</arg><arg>n</arg><arg>m</arg></group></arg> + <arg choice='opt'>-V </arg> + <group> + <replaceable>server</replaceable> + <group> + <replaceable>:port</replaceable> + <group><replaceable>:device</replaceable></group> + </group> + </group> +</cmdsynopsis> +<cmdsynopsis> + <command>xgpsspeed</command> + <arg choice='opt'>--debug <replaceable>debug-level</replaceable></arg> + <arg choice='opt'>--device <replaceable>device</replaceable></arg> + <arg choice='opt'>-h </arg> + <arg choice='opt'>--host <replaceable>host</replaceable></arg> + <arg choice='opt'>--landspeed </arg> + <arg choice='opt'>--maxspeed <replaceable>maxspeed</replaceable></arg> + <arg choice='opt'>--nautical </arg> + <arg choice='opt'>--port <replaceable>port</replaceable></arg> + <arg choice='opt'>--speedunits + <group choice='req'> + <arg>mph</arg><arg>kph</arg><arg>knots</arg> + </group> + </arg> + <arg choice='opt'>-V </arg> + <group> + <replaceable>server</replaceable> + <group> + <replaceable>:port</replaceable> + <group><replaceable>:device</replaceable></group> + </group> + </group> +</cmdsynopsis> +</refsynopsisdiv> + +<refsect1 id='description'><title>DESCRIPTION</title> + +<para>These are the demonstration clients shipped with +<application>gpsd</application>. They have some common options:</para> + +<para>The <option>-h</option> option causes each client to emit a summary of its +options and then exit.</para> + +<para>The <option>-V</option> option causes each client to dump the package +version and exit.</para> + +<para> The <option>-l</option> option, when present, sets the format +of latitude and longitude reports. The value 'd' produces decimal +degrees and is the default. The value 'm' produces degrees and +decimal minutes. The value 's' produces degrees, minutes, and decimal +seconds.</para> + +<para><application>xgps</application>, +<application>cgps</application>, and <application>lcdgps</application> +look at variables in the environment to figure out what units they +should default to using for display — imperial, nautical, or +metric. Here are the variables and values they check:</para> + +<screen> + GPSD_UNITS one of: + imperial = miles/feet + nautical = knots/feet + metric = km/meters + LC_MEASUREMENT + en_US = miles/feet + C = miles/feet + POSIX = miles/feet + [other] = km/meters + LANG + en_US = miles/feet + C = miles/feet + POSIX = miles/feet + [other] = km/meters +</screen> +<para>These preferences may be overridden by the <option>-u</option> +option.</para> + +<para>Where present, the <option>-u</option> option can be used to set +the system units for display; follow the keyword with 'i' for +'imperial' for American units (feet in altitude and error estimates, +miles per hour in speeds), 'n' for 'nautical' (feet in altitude and +error estimates, knots in speed) or 'm' for 'metric' (meters in +altitude and error estimates, kilometers per hour in speeds). </para> + +<para> The <option>-D</option> option, when present, sets a debug +level; it is primarily for use by GPSD developers. It enables +various progress messages to standard error.</para> + +<para>By default, clients collect data from all compatible devices on +localhost, using the default GPSD port 2947. An optional argument to any +client may specify a server to get data from. A colon-separated suffix +is taken as a port number. If there is a second colon-separated +suffix, that is taken as a specific device name to be +watched. However, if the server specification contains square +brackets, the part inside them is taken as an IPv6 address and +port/device suffixes are only parsed after the trailing bracket. +Possible cases look like this:</para> + +<variablelist> +<varlistentry> +<term>localhost:/dev/ttyS1</term> +<listitem><para>Look at the default port of localhost, trying both +IPv4 and IPv6 and watching output from serial device 1.</para></listitem> +</varlistentry> +<varlistentry> +<term>example.com:2317</term> +<listitem><para>Look at port 2317 on example.com, trying both +IPv4 and IPv6.</para></listitem> +</varlistentry> +<varlistentry> +<term>71.162.241.5:2317:/dev/ttyS3</term> +<listitem><para>Look at port 2317 at the specified IPv4 +address, collecting data from attached serial device 3.</para></listitem> +</varlistentry> +<varlistentry> +<term>[FEDC:BA98:7654:3210:FEDC:BA98:7654:3210]:2317:/dev/ttyS5</term> +<listitem><para>Look at port 2317 at the specified IPv6 +address, collecting data from attached serial device 5.</para></listitem> +</varlistentry> +</variablelist> + +<para>Not all clients shipped with GPSD are documented here. See also +the separate manual pages for +<citerefentry><refentrytitle>gpspipe</refentrytitle><manvolnum>1</manvolnum></citerefentry> +and +<citerefentry><refentrytitle>gpsmon</refentrytitle><manvolnum>1</manvolnum></citerefentry> +and +<citerefentry><refentrytitle>gpxlogger</refentrytitle><manvolnum>1</manvolnum></citerefentry> +.</para> + +<refsect2><title>xgps</title> + +<para><application>xgps</application> is a simple test client for +<application>gpsd</application> with an X interface. It displays +current GPS position/time/velocity information and (for GPSes that +support the feature) the locations of accessible satellites.</para> + +<para>In the sky view, satellites are color-coded to indicate quality +of signal; consult the data display to the left for exact figures in +dB. Square icons indicate WAAS/EGNOS satellites, circles indicate +ordinary GPS satellites. Filled icons were used in the last fix, +outline icons were not.</para> + +</refsect2> +<refsect2><title>xgpsspeed</title> + +<para><application>xgpsspeed</application> is a speedometer that uses +position information from the GPS. It accepts an -h option and +optional argument as for <application>gps</application>, or a -V +option to dump the package version and exit.</para> + +<para>The default display mode is a speed and track presentation +modeled after a marine navigation display; for backward compatibility +the --nautical option forces this mode. The --landspeed option produces +a simple speedometer.</para> + +<para>The -speedunits option can be used to set the speed units for +display; follow the keyword with knots for nautical miles per hour, +kph for kilometres per hour, or mph for miles per hour. The default +is miles per hour. </para> + +<para>In the nautical mode only, --maxspeed sets the maximum on the +speedometer.</para> + +</refsect2> +<refsect2><title>cgps</title> + +<para><application>cgps</application> is a client resembling +<application>xgps</application>, but without the pictorial +satellite display and able to run on a serial terminal or +terminal emulator.</para> + +<para> The <option>-s</option> option prevents +<application>cgps</application> from displaying the data coming from +the daemon. This display can also be toggled with the s +command.</para> + +<para>The <option>-m</option> option will display your magnetic +heading (as opposed to your true heading). This is a calculated +value, not a measured value, and is subject to a potential error of up +to two degrees in the areas for which the calculation is valid +(currently Western Europe, Alaska, and Lower 48 in the USA). The +formulas used are those found in the Aviation Formulary v1.43.</para> + +<para><application>cgps</application> terminates when you send it a +SIGHUP or SIGINT; given default terminal settings this will happen +when you type Ctrl-C at it. It will also terminate on 'q'</para> + +</refsect2> +<refsect2><title>lcdgps</title> + +<para>A client that passes <application>gpsd</application> data to +<application>lcdproc</application>, turning your car computer into a +very expensive and nearly feature-free GPS receiver. Currently +assumes a 4x40 LCD and writes data formatted to fit that size screen. +Also displays 4- or 6-character Maidenhead grid square output.</para> + +</refsect2> + +<refsect2><title>gegps</title> + +<para>This program collects fixes from <application>gpsd</application> +and feeds them to a running instance of Google Earth for live location +tracking.</para> + +<para>The <option>-d</option> argument is the location of the Google +Earth installation directory. If not specified, it defaults to the +current directory.</para> + +<para>If you have the free (non-subscription) version, start by +running with the <option>-i</option> option to drop a clue in the +Google Earth installation directory, as +'Open_in_Google_Earth_RT_GPS.kml', then open that file in Places (File +> Open...). Run <application>gpsd</application> in the normal way +after that.</para> + +</refsect2> +</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>, +<citerefentry><refentrytitle>libgpsmm</refentrytitle><manvolnum>3</manvolnum></citerefentry>, +<citerefentry><refentrytitle>gpsfake</refentrytitle><manvolnum>1</manvolnum></citerefentry>, +<citerefentry><refentrytitle>gpsctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, +<citerefentry><refentrytitle>gpscat</refentrytitle><manvolnum>1</manvolnum></citerefentry>, +<citerefentry><refentrytitle>gpsprof</refentrytitle><manvolnum>1</manvolnum></citerefentry>. +<citerefentry><refentrytitle>gpspipe</refentrytitle><manvolnum>1</manvolnum></citerefentry>. +<citerefentry><refentrytitle>gpsmon</refentrytitle><manvolnum>1</manvolnum></citerefentry>. +<citerefentry><refentrytitle>gpxlogger</refentrytitle><manvolnum>1</manvolnum></citerefentry>. +</para> +</refsect1> + +<refsect1 id='maintainer'><title>AUTHORS</title> + +<para> +Remco Treffcorn, Derrick Brashear, Russ Nelson & Eric S. Raymond, +Jeff Francis (cgps), Chen Wei <email>weichen302@aol.com</email> (gegps & xgpsspeed), +Robin Wittler <email>real@the-real.org</email> (xgpsspeed). +</para> + +<para>This manual page by Eric S. Raymond <email>esr@thyrsus.com</email></para> + +</refsect1> + +</refentry> + diff --git a/man/gps2udp.xml b/man/gps2udp.xml new file mode 100644 index 00000000..b222b138 --- /dev/null +++ b/man/gps2udp.xml @@ -0,0 +1,129 @@ +<?xml version="1.0" encoding="ISO-8859-1"?> +<!-- +This file is Copyright (c) 2013 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"> +<refentry id='gps2udp.1'> +<refentryinfo><date>01 Marc 2013</date></refentryinfo> +<refmeta> +<refentrytitle>gps2udp</refentrytitle> +<manvolnum>1</manvolnum> +<refmiscinfo class="source">The GPSD Project</refmiscinfo> +<refmiscinfo class="manual">GPSD Documentation</refmiscinfo> +</refmeta> +<refnamediv id='name'> +<refname>gps2udp</refname> +<refpurpose>feed the take from gpsd to one or more aggregation sites</refpurpose> +</refnamediv> +<refsynopsisdiv id='synopsis'> + +<cmdsynopsis> + <command>gps2udp</command> + <arg choice='opt'>-h</arg> + <arg choice='opt'>-n</arg> + <arg choice='opt'>-j</arg> + <arg choice='opt'>-a</arg> + <arg choice='opt'>-u <replaceable>hostname:udpport</replaceable></arg> + <arg choice='opt'>-c <replaceable>count</replaceable></arg> + <arg choice='opt'>-d <replaceable>1|2</replaceable></arg> + <arg choice='opt'>-v</arg> + <group> + <replaceable>server</replaceable> + <group><replaceable>:port</replaceable> + <group><replaceable>:device</replaceable></group> + </group> + </group> +</cmdsynopsis> +</refsynopsisdiv> + +<refsect1 id='description'><title>DESCRIPTION</title> + +<para><application>gps2udp</application> is a tool to connect to +<application>gpsd</application> and output the received sentences to +one or many UDP host:port destinations. This makes the program useful +for feeding AIS information from <application>gpsd</application> to +aishub, marinetraffic, shipfinder,... </para> + +<para><application>gps2udp</application> does not require root +privileges, and can be run concurrently with other tools connecting +to the local <application>gpsd</application> without causing problems.</para> + +<para>The output will consist of one or both of NMEA (-n option) or +JSON (-j option) <application>gpsd</application> sentences. The +output is sent to one or many destinations host through a UDP network +socket (-u host:port options) .</para> + +<para>Optionally a server, TCP/IP port number and remote device can be given. +If omitted, <application>gps2udp</application> connects to localhost on +the default port (2947) and watches all devices opened by +<application>gpsd</application>.</para> + +<para><application>gps2udp</application> may be run as a daemon (-b +option).</para> + +<para><application>gps2udp</application> is designed to run smoothly in +background; it reconnects automatically to +<application>gpsd</application> whenever it is restarted. For +debugging purporses, there is an option to exit gracefully after a given +count of packets (-c option).</para> + +</refsect1> +<refsect1 id='options'><title>OPTIONS</title> + +<para>-h makes <application>gps2udp</application> print +a usage message and exit.</para> + +<para>-n causes NMEA sentences to be output.</para> +<para>-j causes JSON sentences to be output.</para> +<para>-u host:port UDP destination for output sentenses (up to five +destinations).</para> + +<para>-a output only AIS messages.</para> +<para>-b causes <application>gps2udp</application> to run as a daemon.</para> +<para>-c [count] causes [count] sentences to be output. +<application>gps2udp</application> will then exit gracefully.</para> + +<para>-d 1 prints sent packet on stdout.</para> +<para>-v prints the version, then exits.</para> +</refsect1> + +<refsect1 id='exampletitle'><title>EXAMPLE</title> +<para>With a running <application>gpsd accessible on the +network</application> </para> + +<para><command>gps2udp -d 1 -n -u data.aishub.net:2222 </command> will +collect data from localhost:gpsd display them on stdout and send a +copy to test aishub in NMEA format.</para> + +<para><command>gps2udp -a -n -b -u data.aishub.net:2222 -u 5.9.207.224:5321 -u 109.200.19.151:4001 fridu.net:2947</command> will collect +data from a remote gpsd located on fridu.net host, will filter AIS +messages and send them to 3 destination (aishub, marinetraffic, +shipfinder) in NMEA format, command is running in background +mode</para> +</refsect1> + +<refsect1 id='see_also'><title>SEE ALSO</title> +<para> +<citerefentry><refentrytitle>gpsd</refentrytitle><manvolnum>8</manvolnum></citerefentry>, +<citerefentry><refentrytitle>gps</refentrytitle><manvolnum>1</manvolnum></citerefentry>, +<citerefentry><refentrytitle>libgps</refentrytitle><manvolnum>3</manvolnum></citerefentry>, +<citerefentry><refentrytitle>libgpsmm</refentrytitle><manvolnum>3</manvolnum></citerefentry>, +<citerefentry><refentrytitle>gpsprof</refentrytitle><manvolnum>1</manvolnum></citerefentry>, +<citerefentry><refentrytitle>gpsfake</refentrytitle><manvolnum>1</manvolnum></citerefentry>, +<citerefentry><refentrytitle>gpsctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, +<citerefentry><refentrytitle>gpscat</refentrytitle><manvolnum>1</manvolnum></citerefentry>. +<citerefentry><refentrytitle>gpsmon</refentrytitle><manvolnum>1</manvolnum></citerefentry>. +</para> +</refsect1> + +<refsect1 id='maintainer'><title>AUTHOR</title> + +<para>Fulup Ar Foll <email>fulup@sinagot.net</email>.</para> + +</refsect1> + +</refentry> + diff --git a/man/gpscat.xml b/man/gpscat.xml new file mode 100644 index 00000000..a22b6a84 --- /dev/null +++ b/man/gpscat.xml @@ -0,0 +1,134 @@ +<?xml version="1.0" encoding="ISO-8859-1"?> +<!-- +This file is Copyright (c) 2010 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"> +<refentry id='gpscat.1'> +<refentryinfo><date>16 Nov 2006</date></refentryinfo> +<refmeta> +<refentrytitle>gpscat</refentrytitle> +<manvolnum>1</manvolnum> +<refmiscinfo class="source">The GPSD Project</refmiscinfo> +<refmiscinfo class="manual">GPSD Documentation</refmiscinfo> +</refmeta> +<refnamediv id='name'> +<refname>gpscat</refname> +<refpurpose>dump the output from a GPS</refpurpose> +</refnamediv> +<refsynopsisdiv id='synopsis'> + +<cmdsynopsis> + <command>gpscat</command> + <arg choice='opt'>-s <replaceable>speed</replaceable></arg> + <arg choice='opt'>-p</arg> + <arg choice='opt'>-t</arg> + <arg choice='opt'>-D <replaceable>debuglevel</replaceable></arg> + <arg choice='plain'><replaceable>file-or-serial-port</replaceable></arg> +</cmdsynopsis> +</refsynopsisdiv> + +<refsect1 id='description'><title>DESCRIPTION</title> + +<para><application>gpscat</application> is a simple program for +logging and packetizing GPS data streams. It takes input from a +specified file or serial device (presumed to have a GPS attached) and +reports to standard output. The program runs until end of input or it is +interrupted by ^C or other means. It does not terminate on a bad +backet; this is intentional.</para> + +<para>In raw mode (the default) <application>gpscat</application> +simply dumps its input to standard output. Nonprintable characters +other than ASCII whitespace are rendered as hexadecimal string escapes.</para> + +<para>In packetizing mode, <application>gpscat</application> uses the +same code as +<citerefentry><refentrytitle>gpsd</refentrytitle><manvolnum>8</manvolnum></citerefentry>'s +packet sniffer to break the input into packets. Packets are reported +one per line; line breaks in the packets themselves are +escaped.</para> + +<para>This program is useful as a sanity checker when examining a new +device. It can be used as a primitive NMEA logger, but beware that +(a) interrupting it likely to cut off output in mid-sentence, and (b) +to avoid displaying incomplete NMEA sentences right up next to shell +prompts that often contain a $, raw mode always emits an extra final +linefeed.</para> + +<para>Also, be aware that packetizing mode will produce useless +results — probably consuming the entirety of input and appearing +to hang — if it is fed data that is not a sequence of packets +of one of the known types.</para> + +<para>The program accepts the following options:</para> +<variablelist remap='TP'> + +<varlistentry> +<term>-p</term> +<listitem> +<para>Invoke packetizer mode.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>-s</term> +<listitem> +<para>Set the port's baud rate (and optionally its parity and stop +bits) before reading. Argument should begin with one of the normal integer +baud rates (300, 1200, 4800, 9600, 19200, 38400, etc.). It may be +followed by an optional suffix [NOE][12] to set parity (None, Even, +Odd) and stop bits (1 or 2).</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>-t</term> +<listitem> +<para>Invoke packetizer mode, with the packet type and length (in +parentheses) reported before a colon and space on each line.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>-D</term> +<listitem> +<para>In packetizer mode, enable progress messages from the packet +getter. Probably only of interest to developers testing packet +getter changes.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>-h</term> +<listitem> +<para>Display program usage and exit.</para> +</listitem> +</varlistentry> +</variablelist> + +<para>Specifying -s 4800N1 is frequently helpful with unknown +devices.</para> + +</refsect1> + +<refsect1 id='see_also'><title>SEE ALSO</title> +<para> +<citerefentry><refentrytitle>gpsd</refentrytitle><manvolnum>8</manvolnum></citerefentry>, +<citerefentry><refentrytitle>gps</refentrytitle><manvolnum>1</manvolnum></citerefentry>, +<citerefentry><refentrytitle>libgps</refentrytitle><manvolnum>3</manvolnum></citerefentry>, +<citerefentry><refentrytitle>libgpsmm</refentrytitle><manvolnum>3</manvolnum></citerefentry>, +<citerefentry><refentrytitle>gpsfake</refentrytitle><manvolnum>1</manvolnum></citerefentry>. +<citerefentry><refentrytitle>gpsprof</refentrytitle><manvolnum>1</manvolnum></citerefentry>, +<citerefentry><refentrytitle>gpsctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, +<citerefentry><refentrytitle>gpsdctl</refentrytitle><manvolnum>8</manvolnum></citerefentry>, +<citerefentry><refentrytitle>gpsmon</refentrytitle><manvolnum>1</manvolnum></citerefentry>. +</para> +</refsect1> + +<refsect1 id='maintainer'><title>AUTHOR</title> + +<para>Eric S. Raymond <email>esr@thyrsus.com</email>.</para> +</refsect1> +</refentry> diff --git a/man/gpsctl.xml b/man/gpsctl.xml new file mode 100644 index 00000000..b0f9f6c0 --- /dev/null +++ b/man/gpsctl.xml @@ -0,0 +1,284 @@ +<?xml version="1.0" encoding="ISO-8859-1"?> +<!-- +This file is Copyright (c) 2010 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"> +<refentry id='gpsctl.1'> +<refentryinfo><date>29 Oct 2006</date></refentryinfo> +<refmeta> +<refentrytitle>gpsctl</refentrytitle> +<manvolnum>1</manvolnum> +<refmiscinfo class="source">The GPSD Project</refmiscinfo> +<refmiscinfo class="manual">GPSD Documentation</refmiscinfo> +</refmeta> +<refnamediv id='name'> +<refname>gpsctl</refname> +<refpurpose>control the modes of a GPS</refpurpose> +</refnamediv> +<refsynopsisdiv id='synopsis'> + +<cmdsynopsis> + <command>gpsctl</command> + <arg choice='opt'>-h </arg> + <group> + <arg choice='plain'>-b</arg> + <arg choice='plain'>-n</arg> + </group> + <arg choice='opt'>-x <replaceable>control</replaceable></arg> + <arg choice='opt'>-e </arg> + <arg choice='opt'>-f </arg> + <arg choice='opt'>-l </arg> + <arg choice='opt'>-s <replaceable>speed</replaceable></arg> + <arg choice='opt'>-t <replaceable>devicetype</replaceable></arg> + <arg choice='opt'>-R </arg> + <arg choice='opt'>-D <replaceable>debuglevel</replaceable></arg> + <arg choice='opt'>-V </arg> + <arg choice='opt'><replaceable>serial-port</replaceable></arg> +</cmdsynopsis> +</refsynopsisdiv> + +<refsect1 id='description'><title>DESCRIPTION</title> + +<para><application>gpsctl</application> can switch a dual-mode GPS +between NMEA and vendor-binary modes. It can also be used to set the +device baudrate. Note: Not all devices have these capabilities.</para> + +<para>If you have only one GPS attached to your machine, and gpsd is +running, it is not necessary to specify the device; +<application>gpsctl</application> does its work through +<application>gpsd</application>, which will locate it for you.</para> + +<para>When <application>gpsd</application> is not running, the device +specification is required, and you will need to be running as root or +be a member of the device's owning group in order to have write access +to the device. On many Unix variants the owning group will be named +'dialout'.</para> + +<para>The program accepts the following options:</para> +<variablelist remap='TP'> + +<varlistentry> +<term>-b</term> +<listitem> +<para>Put the GPS into native (binary) mode.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>-c</term> +<listitem> +<para>Change the GPS's cycle time. Units are seconds. Note, most +GPSes have a fixed cycle time of 1 second.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>-e</term> +<listitem> +<para>Generate the packet from any other arguments specified and ship +it to standard output instead of the device. This switch can be used +with the <option>-t</option> option without specifying a device. Note: +the packet data for a binary prototype will be raw, not ASCII-ized in +any way.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>-f</term> +<listitem> +<para>Force low-level access (not through the daemon).</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>-l</term> +<listitem> +<para>List a table showing which option switches can be applied +to which device types, and exit.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>-n</term> +<listitem> +<para>Put GPS into NMEA mode.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>-s</term> +<listitem> +<para>Set the baud rate at which the GPS emits packets.</para> + +<para>Use this option 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> +</listitem> +</varlistentry> + +<varlistentry> +<term>-t</term> +<listitem> +<para>Force the device type.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>-x</term> +<listitem> +<para>Send a specified control string to the GPS; +<application>gpsctl</application> will provide packet headers and +trailers and checksum as appropriate for binary packet types, and +whatever checksum and trailer is required for text packet types. (You +must include the leading $ for NMEA packets.) When sending to a UBX +device, the first two bytes of the string supplied will become the +message class and type, and the remainder the payload. When sending to +a Navcom NCT or Trimble TSIP device, the first byte is interpreted as +the command ID and the rest as payload. When sending to a Zodiac +device, the first two bytes are used as a message ID of type +little-endian short, and the remainder as payload in byte pairs +interpreted as little-endian short. For all other supported binary +GPSes (notably including SiRF) the string is taken as the entire +message payload and wrapped with appropriate header, trailer and +checksum bytes. C-style backslash escapes in the string, notably \xNN +for hex, will be interpreted; additionally, \e will be replaced with +ESC. This switch implies <option>-f</option>.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>-T</term> +<listitem> +<para>Change the sampling timeout. Defaults to 8 seconds, which should +always be sufficient to get an identifying packet from a device +emitting at the normal rate of 1 per second.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>-R</term> +<listitem> +<para>Remove the GPSD shared-memory segment used for SHM export. This +option will normally only be of interest to GPSD developers.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>-h</term> +<listitem> +<para>Display program usage and exit.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>-D</term> +<listitem> +<para>Set level of debug messages.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>-V</term> +<listitem> +<para>Display program version and exit.</para> +</listitem> +</varlistentry> +</variablelist> + +<para>The argument of the forcing option, <option>-t</option>, should be a +string which is contained in exactly one of the known driver +names; for a list, do <command>gpsctl -l</command>.</para> + +<para>Forcing the device type behaves somewhat differently depending +on whether this tool is going through the daemon or not. In high-level +mode, if the device that daemon selects for you doesn't match the +driver you specified, <application>gpsctl</application> exits with +a warning. (This may be useful in scripts.)</para> + +<para>In low-level mode, if the device identifies as a Generic NMEA, +use the selected driver instead. This will be useful if you have a +GPS device of known type that is in NMEA mode and not responding to +probes. (This option was originally implemented for talking to +SiRFStar I chips, which don't respond to the normal SiRF ID +probe.)</para> + +<para>If no options are given, the program will display a message +identifying the GPS type of the selected device and exit.</para> + +<para>Reset (-r) operations must stand alone; others can be combined. +Multiple options will be executed in this order: mode changes (-b and +-n) first, speed changes (-s) second, and control-string sends (-c) +last.</para> + +</refsect1> + +<refsect1 id='environment'><title>ENVIRONMENT VARIABLES</title> + +<para>By setting the environment variable <envar>GPSD_SHM_KEY</envar>, +you can control the key value used to designate the shared-memory +segment removed with the -R option. This will be useful mainly when +isolating test instances of <application>gpsd</application> from +production ones.</para> + +</refsect1> + +<refsect1 id='examples'><title>EXAMPLES</title> + +<variablelist> +<varlistentry> +<term><command>gpsctl /dev/ttyUSB0</command></term> +<listitem> +<para>Attempt to identify the device on USB serial device 0. Time out +after the default number of seconds. Adding the <option>-f</option> will +force low-level access and suppress the normal complaint when this +tool can't find a GPSD to work through.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>gpsctl -f -n -s 9600 /dev/ttyUSB0</term> +<listitem> +<para>Use low-level operations (not going through a gpsd instance) to +switch a GPS to NMEA mode at 9600bps. The tool will identify the +GPS type itself.</para> +</listitem> +</varlistentry> +</variablelist> + +</refsect1> + +<refsect1 id='bugs'><title>BUGS</title> + +<para>SiRF GPSes can only be identified by the success of an attempt +to flip them into SiRF binary mode. Thus, the process of probing one of +these running in NMEA will change its behavior.</para> + +<para>Baud rate and mode changes work in direct mode but are not +reliable in client mode. This will be fixed in a future release.</para> + +</refsect1> + +<refsect1 id='see_also'><title>SEE ALSO</title> +<para> +<citerefentry><refentrytitle>gpsd</refentrytitle><manvolnum>8</manvolnum></citerefentry>, +<citerefentry><refentrytitle>gpsdctl</refentrytitle><manvolnum>8</manvolnum></citerefentry>, +<citerefentry><refentrytitle>gps</refentrytitle><manvolnum>1</manvolnum></citerefentry>, +<citerefentry><refentrytitle>libgps</refentrytitle><manvolnum>3</manvolnum></citerefentry>, +<citerefentry><refentrytitle>libgpsmm</refentrytitle><manvolnum>3</manvolnum></citerefentry>, +<citerefentry><refentrytitle>gpsprof</refentrytitle><manvolnum>1</manvolnum></citerefentry>, +<citerefentry><refentrytitle>gpsfake</refentrytitle><manvolnum>1</manvolnum></citerefentry>. +</para> +</refsect1> + +<refsect1 id='maintainer'><title>AUTHOR</title> + +<para>Eric S. Raymond <email>esr@thyrsus.com</email>.</para> +</refsect1> +</refentry> diff --git a/man/gpsd.xml b/man/gpsd.xml new file mode 100644 index 00000000..49489690 --- /dev/null +++ b/man/gpsd.xml @@ -0,0 +1,905 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- +This file is Copyright (c) 2010 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.8'> +<refentryinfo><date>9 Aug 2004</date></refentryinfo> +<refmeta> +<refentrytitle>gpsd</refentrytitle> +<manvolnum>8</manvolnum> +<refmiscinfo class="source">The GPSD Project</refmiscinfo> +<refmiscinfo class="manual">GPSD Documentation</refmiscinfo> +</refmeta> +<refnamediv id='name'> +<refname>gpsd</refname> +<refpurpose>interface daemon for GPS receivers</refpurpose> +</refnamediv> + +<refsynopsisdiv id='synopsis'> + +<cmdsynopsis> + <command>gpsd</command> + <arg choice='opt'>-b </arg> + <arg choice='opt'>-D <replaceable>debuglevel</replaceable></arg> + <arg choice='opt'>-F <replaceable>control-socket</replaceable></arg> + <arg choice='opt'>-G </arg> + <arg choice='opt'>-h </arg> + <arg choice='opt'>-l </arg> + <arg choice='opt'>-n </arg> + <arg choice='opt'>-N </arg> + <arg choice='opt'>-P <replaceable>pidfile</replaceable></arg> + <arg choice='opt'>-r </arg> + <arg choice='opt'>-S <replaceable>listener-port</replaceable></arg> + <arg choice='opt'>-V </arg> + <arg rep='repeat'> + <group><replaceable>source-name</replaceable></group> + </arg> +</cmdsynopsis> +</refsynopsisdiv> + +<refsect1 id='quickstart'><title>QUICK START</title> + +<para>If you have a GPS attached on the lowest-numbered USB port of a +Linux system, and want to read reports from it on TCP/IP port 2947, it +will normally suffice to do this:</para> + +<programlisting> +gpsd /dev/ttyUSB0 +</programlisting> + +<para>For the lowest-numbered serial port:</para> + +<programlisting> +gpsd /dev/ttyS0 +</programlisting> + +<para>Change the device number as appropriate if you need to use a +different port. Command-line flags enable verbose logging, a control +port, and other optional extras but should not be needed for basic +operation; the one exception, on very badly designed hardware, might +be <option>-b</option> (which see).</para> + +<para>On Linux systems supporting udev, <application>gpsd</application> +is normally started automatically when a USB plugin event fires (if it +is not already running) and is handed the name of the newly active +device. In that case no invocation is required at all.</para> + +<para>For your initial tests set your GPS hardware to speak NMEA, as +<application>gpsd</application> is guaranteed to be able to process +that. If your GPS has a native or binary mode with better performance +that <application>gpsd</application> knows how to speak, +<application>gpsd</application> will autoconfigure that mode.</para> + +<para>You can verify correct operation by first starting +<application>gpsd</application> and then +<application>xgps</application>, the X windows test client.</para> + +<para>If you have problems, the GPSD project maintains a FAQ to +assist troubleshooting.</para> + +</refsect1> +<refsect1 id='description'><title>DESCRIPTION</title> + +<para><application>gpsd</application> is a monitor daemon that collects +information from GPSes, differential-GPS radios, or AIS receivers +attached to the host machine. Each GPS, DGPS radio, or AIS receiver +is expected to be direct-connected to the host via a USB or RS232C +serial device. The serial device may be specified to +<application>gpsd</application> at startup, or it may be set via a +command shipped down a local control socket (e.g. by a USB hotplug +script). Given a GPS device by either means, +<application>gpsd</application> discovers the correct port speed and +protocol for it.</para> + +<para><application>gpsd</application> should be able to query any GPS +that speaks either the standard textual NMEA 0183 protocol, or the +(differing) extended NMEA dialects used by MKT-3301, iTrax, Motorola +OnCore, Sony CXD2951, and Ashtech/Thales devices. It can also +interpret the binary protocols used by EverMore, Garmin, Navcom, +Rockwell/Zodiac, SiRF, Trimble, and u-blox ANTARIS devices. Under Linux +it can read NMEA2000 packets through the kernel CAN socket. It can read +heading and attitude information from the Oceanserver 5000 or TNT +Revolution digital compasses.</para> + +<para>The GPS reporting formats supported by your instance of +<application>gpsd</application> may differ depending on how it was +compiled; general-purpose versions support many, but it can be built +with protocol subsets down to a singleton for use in constrained +environments. For a list of the GPS protocols supported by your +instance, see the output of <command>gpsd -l</command></para> + +<para><application>gpsd</application> effectively hides the +differences among the GPS types it supports. It also knows about and +uses commands that tune these GPSes for lower latency. By using +<application>gpsd</application> as an intermediary, applications +avoid contention for serial devices.</para> + +<para><application>gpsd</application> can use differential-GPS +corrections from a DGPS radio or over the net, from a ground station +running a DGPSIP server or a Ntrip broadcaster that reports RTCM-104 +data; this will shrink position errors by roughly a factor of four. +When <application>gpsd</application> opens a serial device emitting +RTCM-104, it automatically recognizes this and uses the device as a +correction source for all connected GPSes that accept RTCM corrections +(this is dependent on the type of the GPS; not all GPSes have the +firmware capability to accept RTCM correction packets). See +<xref linkend='accuracy'/> and <xref linkend='files'/> for discussion.</para> + +<para>Client applications will communicate with <application>gpsd</application> +via a TCP/IP port, 2947 by default). Both IPv4 and IPv6 connections +are supported and a client may connect via either.</para> + +<para>The program accepts the following options:</para> +<variablelist remap='TP'> +<varlistentry> +<term>-b</term> +<listitem><para>Broken-device-safety mode, otherwise known as +read-only mode. A few bluetooth and USB receivers lock up or become +totally inaccessible when probed or reconfigured; see the hardware +compatibility list on the GPSD project website for details. This +switch prevents gpsd from writing to a receiver. This means that +<application>gpsd</application> cannot configure the receiver for +optimal performance, but it also means that +<application>gpsd</application> cannot break the receiver. A better +solution would be for Bluetooth to not be so fragile. A platform +independent method to identify serial-over-Bluetooth devices would +also be nice.</para></listitem> +</varlistentry> +<varlistentry> +<term>-D</term> +<listitem> +<para>Set debug level. At debug levels 2 and above, +<application>gpsd</application> reports incoming sentence and actions +to standard error if <application>gpsd</application> is in the foreground +(-N) or to syslog if in the background.</para> +</listitem> +</varlistentry> +<varlistentry> +<term>-F</term> +<listitem> +<para>Create a control socket for device addition and removal +commands. You must specify a valid pathname on your local filesystem; +this will be created as a Unix-domain socket to which you can write +commands that edit the daemon's internal device list.</para> +</listitem> +</varlistentry> +<varlistentry> +<term>-G</term> +<listitem><para>This flag causes <application>gpsd</application> to +listen on all addresses (INADDR_ANY) rather than just the loop back +(INADDR_LOOPBACK) address. For the sake of privacy and security, TPV +information is now private to the local machine until the user makes +an effort to expose this to the world.</para></listitem> +</varlistentry> +<varlistentry> +<term>-h</term> +<listitem><para>Display help message and terminate.</para></listitem> +</varlistentry> +<varlistentry> +<term>-l</term> +<listitem><para>List all drivers compiled into this +<application>gpsd</application> instance. The letters to the left of +each driver name are the <application>gpsd</application> +control commands supported by that driver.</para> +</listitem> +</varlistentry> +<varlistentry> +<term>-n</term> +<listitem> +<para>Don't wait for a client to connect before polling whatever GPS +is associated with it. Some RS232 GPSes wait in a standby mode +(drawing less power) when the host machine is not asserting DTR, and +some cellphone and handheld embedded GPSes have similar behaviors. +Accordingly, waiting for a watch request to open the device may save +battery power. (This capability is rare in consumer-grade devices). +</para> +</listitem> +</varlistentry> +<varlistentry> +<term>-N</term> +<listitem><para>Don't daemonize; run in foreground. +This switch is mainly useful for debugging.</para> +</listitem> +</varlistentry> +<varlistentry> +<term>-r</term> +<listitem><para>Use GPS time even with no current fix. Some GPS's have +battery powered Real Time Clocks (RTC's) built in, makeing them a valid time +source even before a fix is acquired. This can be useful on a Raspberry Pi, +or other device that has no battery powered RTC, and thus has no valid +time at startup.</para></listitem> +</varlistentry> +<varlistentry> +<term>-P</term> +<listitem> +<para>Specify the name and path to record the daemon's process ID.</para> +</listitem> +</varlistentry> +<varlistentry> +<term>-S</term> +<listitem><para>Set TCP/IP port on which to listen for GPSD clients +(default is 2947).</para></listitem> +</varlistentry> +<varlistentry> +<term>-V</term> +<listitem> +<para>Dump version and exit.</para> +</listitem> +</varlistentry> +</variablelist> + +<para>Arguments are interpreted as the names of data sources. +Normally, a data source is the device pathname of a local device from +which the daemon may expect GPS data. But there are three other +special source types recognized, for a total of four:</para> + +<variablelist> +<varlistentry> +<term>Local serial or USB device</term> +<listitem> +<para>A normal Unix device name of a serial or USB device to which a +sensor is attached. Example: +<filename>/dev/ttyUSB0</filename>.</para> +</listitem> +</varlistentry> +<varlistentry> +<term>Local PPS device</term> +<listitem> +<para>A normal Unix device name of a PPS device to which a PPS source +is attached. The device name must start with "/dev/pps" and a local +serial or USB GPS device must also be available. Example: +<filename>/dev/pps0</filename>.</para> +</listitem> +</varlistentry> +<varlistentry> +<term>TCP feed</term> +<listitem> +<para>A URI with the prefix "tcp://", followed by a hostname, a +colon, and a port number. The daemon will open a socket to the +indicated address and port and read data packets from it, which will +be interpreted as though they had been issued by a serial device. Example: +<filename>tcp://data.aishub.net:4006</filename>.</para> +</listitem> +</varlistentry> +<varlistentry> +<term>UDP feed</term> +<listitem> +<para>A URI with the prefix "udp://", followed by a hostname, a +colon, and a port number. The daemon will open a socket listening for +UDP datagrams arriving on the indicated address and port, which will +be interpreted as though they had been issued by a serial device. Example: +<filename>udp://127.0.0.1:5000</filename>.</para> +</listitem> +</varlistentry> +<varlistentry> +<term>Ntrip caster</term> +<listitem> +<para>A URI with the prefix "ntrip://" followed by the name of an +Ntrip caster (Ntrip is a protocol for broadcasting differential-GPS +fixes over the net). For Ntrip services that require authentication, a +prefix of the form "username:password@" can be added before the name +of the Ntrip broadcaster. For Ntrip service, you must specify which +stream to use; the stream is given in the form "/streamname". An +example DGPSIP URI could be "dgpsip://dgpsip.example.com" and a Ntrip +URI could be +"ntrip://foo:bar@ntrip.example.com:80/example-stream". Corrections +from the caster will be send to each attached GPS with the capability +to accept them.</para> +</listitem> +</varlistentry> +<varlistentry> +<term>DGPSIP server</term> +<listitem> +<para>A URI with the prefix "dgpsip://" followed by a hostname, a +colon, and an optional colon-separated port number (defaulting to +2101). The daemon will handshake with the DGPSIP server and +read RTCM2 correction data from it. Corrections +from the server will be set to each attached GPS with the capability +to accept them. Example: +<filename>dgpsip://dgps.wsrcc.com:2101</filename>.</para> +</listitem> +</varlistentry> +<varlistentry> +<term>Remote gpsd feed</term> +<listitem> +<para>A URI with the prefix "gpsd://", followed by a hostname and +optionally a colony and a port number (if the port is absent the +default <application>gpsd</application> port will be used). The daemon +will open a socket to the indicated address and port and emulate a +<application>gpsd</application> client, collecting JSON reports from +the remote <application>gpsd</application> instance that will be +passed to local clients.</para> +</listitem> +</varlistentry> +<varlistentry> +<term>NMEA2000 CAN data</term> +<listitem> +<para>A URI with the prefix "nmea2000://", followed by a CAN +devicename. Only Linux socket CAN interfaces are supported. The +interface must be configured to receive CAN messages +before <application>gpsd</application> can be started. If +there is more then one unit on the CAN bus that provides GPS data, +<application>gpsd</application> chooses the unit from which a GPS message +is first seen. Example: <filename>nmea2000://can0</filename>. +</para> +</listitem> +</varlistentry> +</variablelist> + +<para>(The "ais:://" source type supported in some older versions of +the daemon has been retired in favor of the more general +"tcp://".)</para> + +<para>Additionally, two serial device names have a side effect: +<variablelist> +<varlistentry> +<term>/dev/ttyAMA0</term> +<listitem> +<para>The UART device on a Raspberry Pi. Has the side effect of +opening /dev/pps0 for RFC2783 1PPS data.</para> +</listitem> +</varlistentry> +<varlistentry> +<term>Generic GPS device 0. Has the side effect of +opening /dev/pps0 for RFC2783 1PPS data/</term> +<listitem> +<para> </para> +</listitem> +</varlistentry> +</variablelist> +</para> + +<para>Internally, the daemon maintains a device pool holding the +pathnames of devices and remote servers known to the +daemon. Initially, this list is the list of device-name arguments +specified on the command line. That list may be empty, in which case +the daemon will have no devices on its search list until they are +added by a control-socket command (see <xref linkend='devices'/> for +details on this). Daemon startup will abort with an error if neither +any devices nor a control socket are specified.</para> + +<para>When a device is activated (i.e. a client requests data from it), +gpsd attempts to execute a hook from +<filename>/etc/gpsd/device-hook</filename> with first command line argument +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><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='shm'><title>SHARED-MEMORY AND DBUS INTERFACES</title> + +<para><application>gpsd</application> has two other (read-only) +interfaces.</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 sockets interface loses a significant +amount of runtime weight.</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="2" align="left" colsep="1" rowsep="1"> +<thead> +<row> + <entry>Type</entry> + <entry><para>Description</para></entry> +</row> +</thead> +<tbody> +<row> + <entry>DBUS_TYPE_DOUBLE</entry> + <entry><para>Time (seconds since Unix epoch)</para></entry> +</row> +<row> + <entry>DBUS_TYPE_INT32</entry> + <entry><para>mode</para></entry> +</row> +<row> + <entry>DBUS_TYPE_DOUBLE</entry> + <entry><para>Time uncertainty (seconds).</para></entry> +</row> +<row> + <entry>DBUS_TYPE_DOUBLE</entry> + <entry><para>Latitude in degrees.</para></entry> +</row> +<row> + <entry>DBUS_TYPE_DOUBLE</entry> + <entry><para>Longitude in degrees.</para></entry> +</row> +<row> + <entry>DBUS_TYPE_DOUBLE</entry> + <entry><para>Horizontal uncertainty in meters, 95% confidence.</para></entry> +</row> +<row> + <entry>DBUS_TYPE_DOUBLE</entry> + <entry><para>Altitude in meters.</para></entry> +</row> +<row> + <entry>DBUS_TYPE_DOUBLE</entry> + <entry><para>Altitude uncertainty in meters, 95% confidence.</para></entry> +</row> +<row> + <entry>DBUS_TYPE_DOUBLE</entry> + <entry><para>Course in degrees from true north.</para></entry> +</row> +<row> + <entry>DBUS_TYPE_DOUBLE</entry> + <entry><para>Course uncertainty in meters, 95% confidence.</para></entry> +</row> +<row> + <entry>DBUS_TYPE_DOUBLE</entry> + <entry><para>Speed, meters per second.</para></entry> +</row> +<row> + <entry>DBUS_TYPE_DOUBLE</entry> + <entry><para>Speed uncertainty in meters per second, + 95% confidence.</para></entry> +</row> +<row> + <entry>DBUS_TYPE_DOUBLE</entry> + <entry><para>Climb, meters per second.</para></entry> +</row> +<row> + <entry>DBUS_TYPE_DOUBLE</entry> + <entry><para>Climb uncertainty in meters per second, + 95% confidence.</para></entry> +</row> +<row> + <entry>DBUS_TYPE_STRING</entry> + <entry><para>Device name</para></entry> +</row> +</tbody> +</tgroup> +</table> + +</refsect1> + +<refsect1 id='devices'><title>GPS DEVICE MANAGEMENT</title> + +<para><application>gpsd</application> maintains an internal list of +GPS devices (the "device pool"). If you specify devices on the +command line, the list is initialized with those pathnames; otherwise +the list starts empty. Commands to add and remove GPS device paths +from the daemon's device list must be written to a local Unix-domain +socket which will be accessible only to programs running as root. +This control socket will be located wherever the -F option specifies +it.</para> + +<para>A device may will also be dropped from the pool if GPSD gets a zero +length read from it. This end-of-file condition indicates that the' +device has been disconnected.</para> + +<para>When <application>gpsd</application> is properly installed along +with hotplug notifier scripts feeding it device-add commands over the +control socket, <application>gpsd</application> should require no +configuration or user action to find devices.</para> + +<para>Sending SIGHUP to a running <application>gpsd</application> +forces it to close all GPSes and all client connections. It will then +attempt to reconnect to any GPSes on its device list and resume +listening for client connections. This may be useful if your GPS +enters a wedged or confused state but can be soft-reset by pulling +down DTR.</para> + +<para>When <application>gpsd</application> is called with no initial +devices (thus, expecting devices to be passed to it by notifications to +the control socket), and reaches a state where there are no devices +connected and no subscribers <emphasis>after</emphasis> after some +devices have been seen, it shuts down gracefully. It is expected that +future device hotplug events will reactivate it.</para> + +<para>To point <application>gpsd</application> at a device that may be +a GPS, write to the control socket a plus sign ('+') followed by the +device name followed by LF or CR-LF. Thus, to point the daemon at +<filename>/dev/foo</filename>. send "+/dev/foo\n". To tell the daemon +that a device has been disconnected and is no longer available, send a +minus sign ('-') followed by the device name followed by LF or +CR-LF. Thus, to remove <filename>/dev/foo</filename> from the search +list, send "-/dev/foo\n".</para> + +<para>To send a control string to a specified device, write to the +control socket a '!', followed by the device name, followed by '=', +followed by the control string.</para> + +<para>To send a binary control string to a specified device, write to the +control socket a '&', followed by the device name, followed by '=', +followed by the control string in paired hex digits.</para> + +<para>Your client may await a response, which will be a line beginning +with either "OK" or "ERROR". An ERROR response to an add command means +the device did not emit data recognizable as GPS packets; an ERROR +response to a remove command means the specified device was not in +<application>gpsd</application>'s device pool. An ERROR response to a +! command means the daemon did not recognize the devicename +specified.</para> + +<para>The control socket is intended for use by hotplug scripts and +other device-discovery services. This control channel is separate +from the public <application>gpsd</application> service port, and only +locally accessible, in order to prevent remote denial-of-service and +spoofing attacks.</para> + +</refsect1> +<refsect1 id='accuracy'><title>ACCURACY</title> + +<para>The base User Estimated Range Error (UERE) of GPSes is 8 meters +or less at 66% confidence, 15 meters or less at 95% confidence. Actual +horizontal error will be UERE times a dilution factor dependent on current +satellite position. Altitude determination is more sensitive to +variability in ionospheric signal lag than latitude/longitude is, and is +also subject to errors in the estimation of local mean sea level; base +error is 12 meters at 66% confidence, 23 meters at 95% confidence. +Again, this will be multiplied by a vertical dilution of precision +(VDOP) dependent on satellite geometry, and VDOP is typically larger +than HDOP. Users should <emphasis>not</emphasis> rely on GPS altitude for +life-critical tasks such as landing an airplane.</para> + +<para>These errors are intrinsic to the design and physics of the GPS +system. <application>gpsd</application> does its internal +computations at sufficient accuracy that it will add no measurable +position error of its own.</para> + +<para>DGPS correction will reduce UERE by a factor of 4, provided you +are within about 100mi (160km) of a DGPS ground station from which you +are receiving corrections.</para> + +<para>On a 4800bps connection, the time latency of fixes provided by +<application>gpsd</application> will be one second or less 95% of the +time. Most of this lag is due to the fact that GPSes normally emit +fixes once per second, thus expected latency is 0.5sec. On the +personal-computer hardware available in 2005 and later, computation +lag induced by <application>gpsd</application> will be negligible, on +the order of a millisecond. Nevertheless, latency can introduce +significant errors for vehicles in motion; at 50km/h (31mi/h) of speed +over ground, 1 second of lag corresponds to 13.8 meters change in +position between updates.</para> + +<para>The time reporting of the GPS system itself has an intrinsic +accuracy limit of 14 nanoseconds, but this can only be approximated by +specialized receivers using that send the high-accuracy PPS +(Pulse-Per-Second) over RS232 to cue a clock crystal. Most GPS +receivers only report time to a precision of 0.01s or 0.001s, +and with no accuracy guarantees below 1sec.</para> + +<para>If your GPS uses a SiRF chipset at firmware level 231, reported +UTC time may be off by the difference between whatever default +leap-second offset has been compiled in and whatever leap-second +correction is currently applicable, from startup until complete +subframe information is received. Firmware levels 232 and up don't +have this problem. You may run <application>gpsd</application> at +debug level 4 to see the chipset type and firmware revision +level.</para> + +<para>There are exactly two circumstances under which +<application>gpsd</application> relies on the host-system +clock:</para> + +<para>In the GPS broadcast signal, GPS time is represented using a +week number that rolls over after 2^10 or 2^13 weeks (about 19.6 +years, or 157 years), depending on the spacecraft. Receivers are +required to disambiguate this to the correct date, but may have +difficulty due to not knowing time to within half this interval, or +may have bugs. Users have reported incorrect dates which appear to be +due to this issue. <application>gpsd</application> uses the startup +time of the daemon detect and compensate for rollovers while it is +running, but otherwise reports the date as it is reported by the +receiver without attempting to correct it.</para> + +<para>If you are using an NMEA-only GPS (that is, not using SiRF or +Garmin or Zodiac binary mode), <application>gpsd</application> relies +on the system clock to tell it the current century. If the system clock +returns an invalid value near zero, and the GPS does not emit GPZDA at +the start of its update cycle (which most consumer-grade NMEA GPSes do +not) then the century part of the dates +<application>gpsd</application> delivers may be wrong. Additionally, +near the century turnover, a range of dates as wide in seconds as the +accuracy of your system clock may be referred to the wrong +century.</para> +</refsect1> + +<refsect1 id='ntp'><title>USE WITH NTP</title> + +<para>gpsd can provide reference clock information to +<application>ntpd</application>, to keep the system clock synchronized +to the time provided by the GPS receiver.</para> + +<para>On Linux, <application>gpsd</application> includes support for +interpreting the PPS pulses emitted at the start of every clock second +on the carrier-detect lines of some serial GPSes; this pulse can be +used to update NTP at much higher accuracy than message time provides. +You can determine whether your GPS emits this pulse by running at -D 5 +and watching for carrier-detect state change messages in the logfile. +In addition, if your kernel provides the RFC 2783 kernel PPS API then +<application>gpsd</application> will use that for extra +accuracy.</para> + +<para>Detailed instructions for using GPSD to set up a high-quality +time service can be found among the documentation on the GPSD +website.</para> +</refsect1> + +<refsect1 id='dbus'><title>USE WITH D-BUS</title> + +<para>On operating systems that support D-BUS, +<application>gpsd</application> can be built to broadcast GPS fixes to +D-BUS-aware applications. As D-BUS is still at a pre-1.0 stage, we +will not attempt to document this interface here. Read the +<application>gpsd</application> source code to learn more.</para> + +</refsect1> +<refsect1 id='security'><title>SECURITY AND PERMISSIONS ISSUES</title> + +<para><application>gpsd</application>, if given the -G flag, will +listen for connections from any reachable host, and then disclose the +current position. Before using the -G flag, consider whether you +consider your computer's location to be sensitive data to be kept +private or something that you wish to publish.</para> + +<para><application>gpsd</application> must start up as root in order +to open the NTPD shared-memory segment, open its logfile, and create +its local control socket. Before doing any processing of GPS data, it +tries to drop root privileges by setting its UID to "nobody" (or another +configured userid) and its group ID to the group of the initial +GPS passed on the command line — or, if that device doesn't exist, +to the group of <filename>/dev/ttyS0</filename>.</para> + +<para>Privilege-dropping is a hedge against the possibility that +carefully crafted data, either presented from a client socket or from +a subverted serial device posing as a GPS, could be used to induce +misbehavior in the internals of <application>gpsd</application>. +It ensures that any such compromises cannot be used for privilege +elevation to root.</para> + +<para>The assumption behind <application>gpsd</application>'s +particular behavior is that all the tty devices to which a GPS might +be connected are owned by the same non-root group and allow group +read/write, though the group may vary because of distribution-specific +or local administrative practice. If this assumption is false, +<application>gpsd</application> may not be able to open GPS devices in +order to read them (such failures will be logged).</para> + +<para>In order to fend off inadvertent denial-of-service attacks by +port scanners (not to mention deliberate ones), +<application>gpsd</application> will time out inactive client +connections. Before the client has issued a command that requests a +channel assignment, a short timeout (60 seconds) applies. There is no +timeout for clients in watcher or raw modes; rather, +<application>gpsd</application> drops these clients if they fail to +read data long enough for the outbound socket write buffer to fill. +Clients with an assigned device in polling mode are subject to a +longer timeout (15 minutes).</para> + +</refsect1> +<refsect1 id='limitations'><title>LIMITATIONS</title> + +<para>If multiple NMEA talkers are feeding RMC, GLL, and GGA sentences +to the same serial device (possible with an RS422 adapter hooked up to +some marine-navigation systems), a 'TPV' response may mix an altitude +from one device's GGA with latitude/longitude from another's RMC/GLL +after the second sentence has arrived.</para> + +<para><application>gpsd</application> may change control settings on +your GPS (such as the emission frequency of various sentences or +packets) and not restore the original settings on exit. This is a +result of inadequacies in NMEA and the vendor binary GPS protocols, +which often do not give clients any way to query the values of control +settings in order to be able to restore them later.</para> + +<para>When using SiRF chips, the VDOP/TDOP/GDOP figures and associated +error estimates are computed by <application>gpsd</application> rather +than reported by the chip. The computation does not exactly match +what SiRF chips do internally, which includes some satellite weighting +using parameters <application>gpsd</application> cannot see.</para> + +<para>Autobauding on the Trimble GPSes can take as long as 5 seconds +if the device speed is not matched to the GPS speed.</para> + +<para>Generation of position error estimates (eph, epv, epd, eps, epc) +from the incomplete data handed back by GPS reporting protocols +involves both a lot of mathematical black art and fragile +device-dependent assumptions. This code has been bug-prone in tbe +past and problems may still lurk there.</para> + +<para>AIDVM decoding of types 16-17, 22-23, and 25-26 is unverified.</para> + +<para>GPSD presently fully recognizes only the 2.1 level of RTCM2 +(message types 1, 3, 4, 5, 6, 7, 9, 16). The 2.3 message types 13, 14, +and 31 are recognized and reported. Message types 8, 10-12, 15-27, +28-30 (undefined), 31-37, 38-58 (undefined), and 60-63 are not yet +supported.</para> + +<para>The ISGPS used for RTCM2 and subframes decoder logic is +sufficiently convoluted to confuse some compiler optimizers, notably +in GCC 3.x at -O2, into generating bad code.</para> + +<para>Devices meant to use PPS for high-precision timekeeping may +fail if they are specified after startup by a control-socket command, +as opposed to on the daemon's original command line. Root privileges +are dropped early, and some Unix variants require them in order to set +the PPS line discipline. Under Linux the POSIX capability to set the +line discipline is retained, but other platforms cannot use this +code.</para> + +<para>USB GPS devices often do not identify themselves through the USB +subsystem; they typically present as the class 00h (undefined) or +class FFh (vendor-specific) of USB-to-serial adapters. Because of +this, the Linux hotplug scripts must tell +<application>gpsd</application> to sniff data from every USB-to-serial +adapter that goes active and is known to be of a type used in +GPSes. No such device is sent configuration strings until after it has +been identified as a GPS, and <application>gpsd</application> never +opens a device that is opened by another process. But there is a tiny +window for non-GPS devices not opened; if the application that wants +them loses a race with GPSD its device open will fail and have to be +retried after GPSD sniffs the device (normally less than a second +later).</para> + +</refsect1> +<refsect1 id='files'><title>FILES</title> + +<variablelist> +<varlistentry> +<term><filename>/dev/ttyS0</filename></term> +<listitem> +<para>Prototype TTY device. After startup, +<application>gpsd</application> sets its group ID to the owning group of this +device if no GPS device was specified on the command line does not +exist.</para> +</listitem> +</varlistentry> +<varlistentry> +<term><filename>/etc/gpsd/device-hook</filename></term> +<listitem> +<para>Optional file containing the device activation/deactivation script. +Note that while <filename>/etc/gpsd</filename> is the default system +configuration directory, it is possible to build the GPSD source code +with different assumptions.</para> +</listitem> +</varlistentry> +<!-- +<varlistentry> +<term><filename>/usr/share/gpsd/dgpsip-servers</filename></term> +<listitem> +<para>A text file listing DGPSIP servers worldwide. If no DGPSIP +server is specified at startup (via the -d option) +<application>gpsd</application> will look here to find the +nearest one. Each line has three space-separated fields: +latitude (decimal degrees), longitude (decimal degrees) and +a server name (optionally followed by a colon and a port number). +Text following # on a line is ignored. Blank lines are ignored.</para> +</listitem> +</varlistentry> +--> +</variablelist> + +</refsect1> +<refsect1 id='environment'><title>ENVIRONMENT VARIABLES</title> + +<para>By setting the environment variable <envar>GPSD_SHM_KEY</envar>, +you can control the key value used to create the shared-memory segment +used for communication with the client library. This will be useful +mainly when isolating test instances of +<application>gpsd</application> from production ones.</para> + +</refsect1> +<refsect1 id='standards'><title>APPLICABLE STANDARDS</title> + +<para>The official NMEA protocol standards for NMEA0183 and NMEA2000 +are available from the National Marine Electronics Association, but are +proprietary and expensive; the maintainers of +<application>gpsd</application> have made a point of not looking at +them. The GPSD project website links to several documents that collect +publicly disclosed information about the protocol.</para> + +<para><application>gpsd</application> parses the following NMEA +sentences: RMC, GGA, GLL, GSA, GSV, VTG, ZDA, GBS, HDT, DBT, GST. It +recognizes these with either the normal GP talker-ID prefix, or with +the GN prefix used by GLONASS, or with the II prefix emitted by +Seahawk Autohelm marine navigation systems, or with the IN prefix +emitted by some Garmin units, or with the EC prefix emitted by ECDIS +units, or with the SD prefix emitted by depth sounders, or with the HC +and TI prefix emitted by some Airmar equipment. It recognizes some +vendor extensions: the PGRME emitted by some Garmin GPS models, the +OHPR emitted by Oceanserver digital compasses, the PTNTHTM emitted by +True North digital compasses, the PMTK omitted by some San Jose +Navigation GPSes, and the PASHR sentences emitted by some Ashtech +GPSes.</para> + +<para>Note that <application>gpsd</application> JSON returns pure decimal +degrees, not the hybrid degree/minute format described in the NMEA +standard.</para> + +<para>Differential-GPS corrections are conveyed by the RTCM +protocols. The applicable standard for RTCM-104 V2 is <citetitle>RTCM +Recommended Standards for Differential GNSS (Global Navigation +Satellite) Service</citetitle> RTCM Paper 136-2001/SC 104-STD. The +applicable standard for RTCM-104 V3 is <citetitle>RTCM Standard +10403.1 for Differential GNSS Services - Version 3</citetitle> RTCM +Paper 177-2006-SC104-STD. Ordering instructions for the RTCM standards +are accessible from the website of the Radio Technical Commission for Maritime +Services under "Publications".</para> + +<para>AIS is defined by ITU Recommendation M.1371, +<citetitle>Technical Characteristics for a Universal Shipborne +Automatic Identification System Using Time Division Multiple +Access</citetitle>. The AIVDM/AIVDO format understood by this program +is defined by IEC-PAS 61162-100, <citetitle>Maritime navigation and +radiocommunication equipment and systems</citetitle>. A more accessible +description of both can be found at <citetitle>AIVDM/AIVDO Protocol +Decoding</citetitle>, on the references page of the GPSD project +website.</para> + +<para>Subframe data is defined by IS-GPS-200E, <citetitle>GLOBAL +POSITIONING SYSTEM WING (GPSW) SYSTEMS ENGINEERING & INTEGRATION, +INTERFACE SPECIFICATION IS-GPS-200 Revision E</citetitle>. The format +understood by this program is defined in Section 20 (Appendix II) of +the IS-GPS-200E, <citetitle>GPS NAVIGATION DATA STRUCTURE FOR DATA, +D(t)</citetitle></para> + +<para>JSON is specified by RFC 7159, <citetitle>The JavaScript Object +Notation (JSON) Data Interchange Format</citetitle>.</para> + +<para>The API for PPS time service is specified by RFC 2783, +<citetitle>Pulse-Per-Second API for UNIX-like Operating Systems, +Version 1.0</citetitle></para> + +</refsect1> +<refsect1 id='see_also'><title>SEE ALSO</title> +<para> +<citerefentry><refentrytitle>gpsdctl</refentrytitle><manvolnum>8</manvolnum></citerefentry>, +<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>libgpsmm</refentrytitle><manvolnum>3</manvolnum></citerefentry>, +<citerefentry><refentrytitle>gpsprof</refentrytitle><manvolnum>1</manvolnum></citerefentry>, +<citerefentry><refentrytitle>gpsfake</refentrytitle><manvolnum>1</manvolnum></citerefentry>, +<citerefentry><refentrytitle>gpsctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, +<citerefentry><refentrytitle>gpscat</refentrytitle><manvolnum>1</manvolnum></citerefentry>, +</para> +</refsect1> + +<refsect1 id='maintainer'><title>AUTHORS</title> + +<para>Authors: Eric S. Raymond, Chris Kuethe, Gary Miller. Former +authors whose bits have been plowed under by code turnover: Remco +Treffcorn, Derrick Brashear, Russ Nelson. This manual page by Eric S. Raymond +<email>esr@thyrsus.com</email>.</para> +</refsect1> + +</refentry> 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> diff --git a/man/gpsdctl.xml b/man/gpsdctl.xml new file mode 100644 index 00000000..d47128c9 --- /dev/null +++ b/man/gpsdctl.xml @@ -0,0 +1,81 @@ +<?xml version="1.0" encoding="ISO-8859-1"?> +<!-- +This file is Copyright (c) 2010 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"> +<refentry id='gpsdctl.8'> +<refentryinfo><date>25 Jun 2011</date></refentryinfo> +<refmeta> +<refentrytitle>gpsdctl</refentrytitle> +<manvolnum>8</manvolnum> +<refmiscinfo class="source">The GPSD Project</refmiscinfo> +<refmiscinfo class="manual">GPSD Documentation</refmiscinfo> +</refmeta> +<refnamediv id='name'> +<refname>gpsdctl</refname> +<refpurpose>tool for sending commands to gpsd over its control socket</refpurpose> +</refnamediv> +<refsynopsisdiv id='synopsis'> + +<cmdsynopsis> + <command>gpdsctl</command> + <arg choice='plain'><replaceable>action</replaceable></arg> + <arg choice='plain'><replaceable>device</replaceable></arg> +</cmdsynopsis> +</refsynopsisdiv> + +<refsect1 id='description'><title>DESCRIPTION</title> + +<para>This is a tool for sending an instance of +<application>gpsd</application> commands over its control socket to +add or remove devices from the daemon's device list. It is not +intended to be called by users, but rather by the Linux hotplug +system and similar facilities.</para> + +<para>The action argument may be "add" or "remove". If no daemon +instance is running when an add is requested, this program will launch +one.</para> + +<para>The "device" argument should be the pathname of a device. A +device on the list will be opened to read sensor data whenever a +client requests a watch.</para> + +<para>Two environment variables are +interpreted. <envar>GPSD_SOCKET</envar> sets the location of the +control socket. It defaults to +<filename>/var/run/gpsd.sock</filename> if the effective user ID of +this program is root, <filename>/tmp/gpsd.sock</filename> +otherwise.</para> + +<para><envar>GPSD_OPTIONS</envar> +may be a list of options to be passed to <application>gpsd</application> +when this tool launches it. It defaults to an empty string.</para> +</refsect1> + +<refsect1 id='exit_status'><title>RETURN VALUES</title> + +<para>1 if the action was unknown or the write to the control socket +failed, 0 otherwise</para> + +</refsect1> + +<refsect1 id='see_also'><title>SEE ALSO</title> +<para> +<citerefentry><refentrytitle>gpsd</refentrytitle><manvolnum>8</manvolnum></citerefentry>, +<citerefentry><refentrytitle>gpsctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, +<citerefentry><refentrytitle>gps</refentrytitle><manvolnum>1</manvolnum></citerefentry>, +<citerefentry><refentrytitle>libgps</refentrytitle><manvolnum>3</manvolnum></citerefentry>, +<citerefentry><refentrytitle>libgpsmm</refentrytitle><manvolnum>3</manvolnum></citerefentry>, +<citerefentry><refentrytitle>gpsprof</refentrytitle><manvolnum>1</manvolnum></citerefentry>, +<citerefentry><refentrytitle>gpsfake</refentrytitle><manvolnum>1</manvolnum></citerefentry>. +</para> +</refsect1> + +<refsect1 id='maintainer'><title>AUTHOR</title> + +<para>Eric S. Raymond <email>esr@thyrsus.com</email>.</para> +</refsect1> +</refentry> diff --git a/man/gpsdecode.xml b/man/gpsdecode.xml new file mode 100644 index 00000000..b7368dc7 --- /dev/null +++ b/man/gpsdecode.xml @@ -0,0 +1,147 @@ +<?xml version="1.0" encoding="ISO-8859-1"?> +<!-- +This file is Copyright (c) 2010 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"> +<refentry id='gpsdecode.1'> +<refentryinfo><date>13 Jul 2005</date></refentryinfo> +<refmeta> +<refentrytitle>gpsdecode</refentrytitle> +<manvolnum>1</manvolnum> +<refmiscinfo class="source">The GPSD Project</refmiscinfo> +<refmiscinfo class="manual">GPSD Documentation</refmiscinfo> +</refmeta> +<refnamediv id='name'> +<refname>gpsdecode</refname> +<refpurpose>decode GPS, RTCM or AIS streams into a readable format</refpurpose> +</refnamediv> +<refsynopsisdiv id='synopsis'> + +<cmdsynopsis> + <command>gpsdecode</command> + <arg choice='opt'>-c</arg> + <arg choice='opt'>-d</arg> + <arg choice='opt'>-e</arg> + <arg choice='opt'>-j</arg> + <arg choice='opt'>-m</arg> + <arg choice='opt'>-n</arg> + <arg choice='opt'>-s</arg> + <arg choice='opt'>-t <replaceable>typelist</replaceable></arg> + <arg choice='opt'>-u</arg> + <arg choice='opt'>-v</arg> + <arg choice='opt'>-D <replaceable>debuglevel</replaceable></arg> + <arg choice='opt'>-V</arg> +</cmdsynopsis> +</refsynopsisdiv> + +<refsect1 id='description'><title>DESCRIPTION</title> + +<para>This tool is a batch-mode decoder for NMEA and various binary +packet formats associated with GPS, AIS, and differential-correction +services. It produces a JSON dump on standard output from binary on +standard input. The JSON is the same format documented in +<citerefentry><refentrytitle>gpsd</refentrytitle><manvolnum>8</manvolnum></citerefentry>; +this tool uses the same decoding logic as gpsd, but with a simpler +interface intended for batch processing of data files.</para> + +<para>All sensor-input formats known to the GPSD project can be +decoded by this tool. These include: NMEA, AIVDM (the NMEA-derived +sentence format used by AIS, the marine Automatic Identification +System), RTCM2, and all supported GPS binary formats (notably +including SiRF). See +<citerefentry><refentrytitle>gpsd</refentrytitle><manvolnum>8</manvolnum></citerefentry> +for applicable standards and known limitations of the decoding +logic.</para> + +<para>You can use this tool with +<citerefentry><refentrytitle>nc</refentrytitle><manvolnum>1</manvolnum></citerefentry> +to examine AIS feeds from AIS pooling services, RTCM feeds from RTCM +receivers or NTRIP broadcasters.</para> + +</refsect1> +<refsect1 id='options'><title>OPTIONS</title> + +<para>The <option>-d</option> option tells the program to decode +packets presented on standard input to standard output. This is the +default behavior.</para> + +<para>The <option>-j</option> explicitly sets the output dump format +to JSON (the default behavior).</para> + +<para>With the <option>-m</option> option, dump minimum lengths for +each packet type in the input (ignoring comment packets). This is +probably of interest only to GSD developers.</para> + +<para>The <option>-n</option> enables dumping in generated +pseudo-NME0183.</para> + +<para>The <option>-e</option> option option tells the program to +encode JSON on standard input to JSON on standard output. This option +is only useful for regression-testing of the JSON dumping and parsing +code.</para> + +<para>The <option>-s</option> option option tells the program to report +AIS Type 24 sentence halves separately rather than attempting to +aggregate them.</para> + +<para>The <option>-t</option> accepts a comma-separated list of +numeric types. Packets with a numeric AIS, RTCM2, or RTCM3 type are +passed through and output only if they match a type in the +list. Packets of other kinds (in particular GPS packets) are +passed through unconditionally.</para> + +<para>The <option>-u</option> suppresses scaling of AIS data to float +quantities and text expansion of numeric codes. A dump with this +option is lossless.</para> + +<para>The <option>-v</option> enables dumping of textual packets +to output as they are received on input, immediately preceding +corresponding output.</para> + +<para>The <option>-c</option> sets the AIS dump format to separate +fields with an ASCII pipe symbol. Fields are dumped in the order they +occur in the AIS packet. Numerics are not scaled (-u is +forced). Strings are unpacked from six-bit to full ASCII</para> + +<para>The <option>-V</option> option directs the program to emit its +version number, then exit.</para> + +<para>The <option>-D</option> option sets a debug verbosity level. It is +mainly of interest to developers.</para> + +</refsect1> +<refsect1 id='json_ais'><title>AIS DSV FORMAT</title> + +<para>With the <option>-c</option> option, dump lines are values of AIS +payload fields, pipe-separated, in the order that they occur in the +payload. Spans of fields expressing a date are emitted as an ISO8601 +timestamp (look for colons and the trailing Z indicating Zulu/UTC +time), and the 19-bit group of TDMA status fields found at the end of +message types 1-4 are are dumped as a single unsigned integer (in hex +preceded by "0x"). Unused regional-authority fields are also dumped +(in hex preceded by "0x"). Variable-length binary fields are dumped as +an integer bit length, followed by a colon, followed by a hex +dump.</para> + +</refsect1> +<refsect1 id='see_also'><title>SEE ALSO</title> +<para> +<citerefentry><refentrytitle>gpsd</refentrytitle><manvolnum>8</manvolnum></citerefentry>, +<citerefentry><refentrytitle>gpsctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, +<citerefentry><refentrytitle>gpsdctl</refentrytitle><manvolnum>8</manvolnum></citerefentry>, +<citerefentry><refentrytitle>gps</refentrytitle><manvolnum>1</manvolnum></citerefentry>, +<citerefentry><refentrytitle>libgps</refentrytitle><manvolnum>3</manvolnum></citerefentry>, +<citerefentry><refentrytitle>libgpsmm</refentrytitle><manvolnum>3</manvolnum></citerefentry>, +<citerefentry><refentrytitle>gpsprof</refentrytitle><manvolnum>1</manvolnum></citerefentry>, +<citerefentry><refentrytitle>gpsfake</refentrytitle><manvolnum>1</manvolnum></citerefentry>, +</para> +</refsect1> +<refsect1 id='maintainer'><title>AUTHOR</title> + +<para>Eric S. Raymond <email>esr@thyrsus.com</email>.</para> +</refsect1> + +</refentry> diff --git a/man/gpsfake.xml b/man/gpsfake.xml new file mode 100644 index 00000000..e8331d47 --- /dev/null +++ b/man/gpsfake.xml @@ -0,0 +1,264 @@ +<?xml version="1.0" encoding="ISO-8859-1"?> +<!-- +This file is Copyright (c) 2010 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"> +<refentry id='gpsfake.1'> +<refentryinfo><date>12 Feb 2005</date></refentryinfo> +<refmeta> +<refentrytitle>gpsfake</refentrytitle> +<manvolnum>1</manvolnum> +<refmiscinfo class="source">The GPSD Project</refmiscinfo> +<refmiscinfo class="manual">GPSD Documentation</refmiscinfo> +</refmeta> +<refnamediv id='name'> +<refname>gpsfake</refname> +<refpurpose>test harness for gpsd, simulating a GPS</refpurpose> +</refnamediv> +<refsynopsisdiv id='synopsis'> + +<cmdsynopsis> + <command>gpsfake</command> + <arg choice='opt'>-1</arg> + <arg choice='opt'>-h</arg> + <arg choice='opt'>-b</arg> + <arg choice='opt'>-c <replaceable>interval</replaceable></arg> + <arg choice='opt'>-i</arg> + <arg choice='opt'>-D <replaceable>debuglevel</replaceable></arg> + <arg choice='opt'>-l</arg> + <arg choice='opt'>-m <replaceable>monitor</replaceable></arg> + <arg choice='opt'>-g</arg> + <arg choice='opt'>-n</arg> + <arg choice='opt'>-o <replaceable>options</replaceable></arg> + <arg choice='opt'>-p</arg> + <arg choice='opt'>-P <replaceable>port</replaceable></arg> + <arg choice='opt'>-q</arg> + <arg choice='opt'>-r <replaceable>initcmd</replaceable></arg> + <arg choice='opt'>-s <replaceable>speed</replaceable></arg> + <arg choice='opt'>-S</arg> + <arg choice='opt'>-u</arg> + <arg choice='opt'>-t</arg> + <arg choice='opt'>-T</arg> + <arg choice='opt'>-v</arg> + <arg rep='repeat'> + <arg choice='plain'><replaceable>logfile</replaceable></arg> + </arg> +</cmdsynopsis> +</refsynopsisdiv> + +<refsect1 id='description'><title>DESCRIPTION</title> + +<para><application>gpsfake</application> is a test harness for +<application>gpsd</application> and its clients. It opens a pty +(pseudo-TTY), launches a <application>gpsd</application> instance that +thinks the slave side of the pty is its GPS device, and repeatedly +feeds the contents of one or more test logfiles through the master side to the +GPS. If there are multiple logfiles, sentences from them are +interleaved in the order the files are specified.</para> + +<para><application>gpsfake</application> does not require root +privileges, and can be run concurrently with a production +<application>gpsd</application> instance without causing problems.</para> + +<para>The logfiles may contain packets in any supported format, +including in particular NMEA, SiRF, TSIP, or Zodiac. Leading lines +beginning with # will be treated as comments and ignored, except in +the following special cases:</para> + +<itemizedlist> +<listitem><para> +a comment of the form #Date: yyyy-mm-dd (ISO8601 date format) may be +used to set the initial date for the log. +</para></listitem> + +<listitem><para> +a comment of the form #Serial: [0-9]* [78][NOE][12] may be used to set +serial parameters for the log - baud rate, word length, stop bits. +</para></listitem> + +<listitem><para> +a comment of the form #Transport: UDP may be used to fake a UDP source +rather than the normal pty. +</para></listitem> +</itemizedlist> + +<para>The <application>gpsd</application> instance is run in +foreground. The thread sending fake GPS data to the daemon +is run in background.</para> + +</refsect1> +<refsect1 id='options'><title>OPTIONS</title> + +<para>With the -1 option, the logfile is interpreted once only rather +than repeatedly. This option is intended to facilitate regression +testing.</para> + +<para>The <option>-b</option> enables a twirling-baton progress indicator +on standard error. At termination, it reports elapsed time.</para> + +<para>The <option>-c</option> sets the delay between sentences in +seconds. Fractional values of seconds are legal. The default is zero +(no delay).</para> + +<para>The <option>-l</option> makes the program dump a line or packet number +just before each sentence is fed to the daemon. If the sentence is +textual (e.g. NMEA), the text is dumped as well. If not, the packet +will be dumped in hexadecimal (except for RTCM packets, which aren't +dumped at all). This option is useful for checking that gpsfake is +getting packet boundaries right.</para> + +<para>The <option>-i</option> is for single-stepping through logfiles. It dumps +the line or packet number (and the sentence if the protocol is +textual) followed by "? ". Only when the user keys Enter is the line +actually fed to <application>gpsd</application>.</para> + +<para>The <option>-m</option> specifies a monitor program inside which the +daemon should be run. This option is intended to be used with +<citerefentry><refentrytitle>valgrind</refentrytitle><manvolnum>1</manvolnum></citerefentry>, +<citerefentry><refentrytitle>gdb</refentrytitle><manvolnum>1</manvolnum></citerefentry> +and similar programs.</para> + +<para>The <option>-g</option> uses the monitor facility to run the +<application>gpsd</application> instance within gpsfake under control +of gdb.</para> + +<para>The <option>-o</option> specifies options to pass to the daemon. The -n +option passes -n to start the daemon reading the GPS without waiting +for a client (equivalent to -o "-n"). The <option>-D</option> passes a -D +option to the daemon: thus -D 4 is shorthand for -o "-D 4".</para> + +<para>The -p ("pipe") option sets watcher mode and dumps the NMEA and GPSD +notifications generated by the log to standard output. This is useful +for regression-testing.</para> + +<para>The -P ("port") option sets the daemon's listening port.</para> + +<para>The <option>-q</option> tells gpsfake to suppress normal progress +output and thus act in a quiet manner.</para> + +<para>The <option>-r</option> specifies an initialization command to use in pipe mode. +The default is <command>?WATCH={"enable":true,"json":true}</command>.</para> + +<para>The <option>-s</option> sets the baud rate for the slave tty. The +default is 4800.</para> + +<para>The option -S tells gpsfake to insert realistic delays in the +test input rather than trying to stuff it through the daemon as fast +as possible. This will make the test(s) run much slower, but avoids +flaky failures due to machine lode and possible race conditions in +the pty layer.</para> + +<para>The <option>-t</option> forces the test framework to use TCP +rather than pty devices. Besides being a test of TCP source handling, +this may be useful for testing from within chroot jails where access +to pty devices is locked out.</para> + +<para>The <option>-T</option> makes <application>gpsfake</application> print +some system information and then exits.</para> + +<para>The <option>-u</option> forces the test framework to use UDP +rather than pty devices. Besides being a test of UDP source handling, +this may be useful for testing from within chroot jails where access +to pty devices is locked out.</para> + +<para>The <option>-v</option> enables verbose progress reports to stderr. It is +mainly useful for debugging <application>gpsfake</application> +itself.</para> + +<para>The <option>-x</option> dumps packets as +<application>gpsfake</application> gathers them. It is mainly useful +for debugging <application>gpsfake</application> itself.</para> + +<para>The <option>-h</option> makes <application>gpsfake</application> print +a usage message and exit.</para> + +<para>The argument must be the name of a file containing the +data to be cycled at the device. <application>gpsfake</application> +will print a notification each time it cycles.</para> + +<para>Normally, gpsfake creates a pty for each logfile and passes the +slave side of the device to the daemon. If the header comment in the +logfile contains the string "UDP", packets are instead shipped via UDP +port 5000 to the address 192.168.0.1.255. You can monitor them with +this: <command>tcpdump -s0 -n -A -i lo udp and port 5000</command>.</para> + +</refsect1> +<refsect1 id='magic'><title>MAGIC COMMENTS</title> + +<para>Certain magic comments in test load headers can change the +conditions of the test. These are:</para> + +<variablelist> +<varlistentry> +<term>Serial:</term> +<listitem><para>May contain a serial-port setting such as 4800 7N2 - +baud rate followed by 7 or 8 for byte length, N or O or E for parity +and 1 or 2 for stop bits. The test is run with those settings on the +slave port that the daemon sees.</para></listitem> +</varlistentry> +<varlistentry> +<term>Transport:</term> +<listitem><para>Values 'TCP' and 'UDP' force the use of TCP and +UDP feeds respectively (the default is a pty).</para></listitem> +</varlistentry> +<varlistentry> +<term>Delay-Cookie:</term> +<listitem><para>Must be followed by two whitespace-separated fields, a +delimiter character and a numeric delay in seconds. Instead of being +broken up by packet boundaries, the test load is split on the +delimiters. The delay is performed after each feed. Can be useful +for imposing write boundaries in the middle of packets. +</para></listitem> +</varlistentry> +</variablelist> + +</refsect1> +<refsect1 id='custom'><title>CUSTOM TESTS</title> + +<para><application>gpsfake</application> is a trivial wrapper around a +Python module, also named gpsfake, that can be used to fully script +sessions involving a <application>gpsd</application> instance, any +number of client sessions, and any number of fake GPSes feeding the +daemon instance with data from specified sentence logs.</para> + +<para>Source and embedded documentation for this module is shipped with the +<application>gpsd</application> development tools. You can use it to +torture-test either <application>gpsd</application> itself or any +<application>gpsd</application>-aware client application.</para> + +<para>Logfiles for the use with <application>gpsfake</application> can +be retrieved using <application>gpspipe</application>, +<application>gpscat</application>, or +<application>gpsmon</application> from the gpsd distribution, or any +other application which is able to create a compatible output.</para> + +<para>If <application>gpsfake</application> exits with "Cannot execute +gpsd: executable not found." the environment variable GPSD_HOME can be +set to the path where gpsd can be found. (instead of adding that folder +to the PATH environment variable</para> + +</refsect1> +<refsect1 id='see_also'><title>SEE ALSO</title> +<para> +<citerefentry><refentrytitle>gpsd</refentrytitle><manvolnum>8</manvolnum></citerefentry>, +<citerefentry><refentrytitle>gps</refentrytitle><manvolnum>1</manvolnum></citerefentry>, +<citerefentry><refentrytitle>libgps</refentrytitle><manvolnum>3</manvolnum></citerefentry>, +<citerefentry><refentrytitle>libgpsmm</refentrytitle><manvolnum>3</manvolnum></citerefentry>, +<citerefentry><refentrytitle>gpsctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, +<citerefentry><refentrytitle>gpspipe</refentrytitle><manvolnum>1</manvolnum></citerefentry>, +<citerefentry><refentrytitle>gpsprof</refentrytitle><manvolnum>1</manvolnum></citerefentry> +<citerefentry><refentrytitle>gpsmon</refentrytitle><manvolnum>1</manvolnum></citerefentry>. +</para> +</refsect1> + +<refsect1 id='maintainer'><title>AUTHOR</title> + +<para>Eric S. Raymond <email>esr@thyrsus.com</email>.</para> + +</refsect1> + +</refentry> + diff --git a/man/gpsinit.xml b/man/gpsinit.xml new file mode 100644 index 00000000..a3750023 --- /dev/null +++ b/man/gpsinit.xml @@ -0,0 +1,170 @@ +<?xml version="1.0" encoding="ISO-8859-1"?> +<!-- +This file is Copyright (c) 2010 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"> +<refentry id='gpsinit.8'> +<refentryinfo><date>18 Jan 2013</date></refentryinfo> +<refmeta> +<refentrytitle>gpsinit</refentrytitle> +<manvolnum>8</manvolnum> +<refmiscinfo class="source">The GPSD Project</refmiscinfo> +<refmiscinfo class="manual">GPSD Documentation</refmiscinfo> +</refmeta> +<refnamediv id='name'> +<refname>gpsinit</refname> +<refpurpose>initialize CAN kernel modules for GPSD</refpurpose> +</refnamediv> +<refsynopsisdiv id='synopsis'> + +<cmdsynopsis> + <command>gpsinit</command> + <arg choice='opt'>-n <replaceable>control</replaceable></arg> + <arg choice='opt'>-s <replaceable>speed</replaceable></arg> + <arg choice='plain'><replaceable>module_name</replaceable></arg> + <arg choice='opt'><replaceable>interface_name</replaceable></arg> +</cmdsynopsis> +<cmdsynopsis> + <command>gpsinit</command> + <arg choice='plain'>-h </arg> +</cmdsynopsis> +<cmdsynopsis> + <command>gpsinit</command> + <arg choice='plain'>-v </arg> +</cmdsynopsis> +</refsynopsisdiv> + +<refsect1 id='description'><title>DESCRIPTION</title> + +<para><application>gpsinit</application> initializes whatever +kernel-level modules are needed to enable special non-serial hardware +to communicate with a gpsd instance. Note: it will need root permissions +to load modules and perform other special operations, such as changing +kernel-interface baudrates.</para> + +<para>At present, all modes of this tool are concerned with setting up +kernel-level interfaces to hardware on a CAN (Control Area Network) speaking +NMEA2000.</para> + +<para>The program accepts the following options:</para> +<variablelist remap='TP'> + +<varlistentry> +<term>-h</term> +<listitem> +<para>Display a brief help text.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>-v</term> +<listitem> +<para>Display the version of <application>gpsinit</application>.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>-n</term> +<listitem> +<para>Set the CAN network number. The default is 0.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>-s</term> +<listitem> +<para>Set the baudrate to be used to communicate over the serial line +to the CAN hardware. The default is 38400 baud.</para> +</listitem> +</varlistentry> +</variablelist> + +<para>The parameter <parameter>module_name</parameter> is mandatory. The +socket CAN driver module <parameter>module_name</parameter>.ko will be +loaded. <command>gpsinit</command> recognize the following module +names: + +<variablelist> +<varlistentry> +<term>plx_pci</term> +<term>esd_usb2</term> +<term>vcan</term> +<term>slcan</term> +<listitem> +<para> +The parameter <parameter>interface_name</parameter> and <parameter>-s +<replaceable>speed</replaceable></parameter> can used here. +</para> +</listitem> +</varlistentry> +<varlistentry><term>beaglebone</term> +<listitem> +<para> The dcan module needed for the beaglebone is part of the Linux kernel, +so no module is loaded in this case.</para> +</listitem> +</varlistentry> +</variablelist> +</para> + +<para>The parameter <parameter>interface_name</parameter> is needed for +slcan hardware only. It gives the name of the serial device to which the SL +CAN hardware is connected. The default is /dev/ttyUSB0. +</para> +</refsect1> + +<refsect1 id='examples'><title>EXAMPLES</title> + +<variablelist> +<varlistentry> +<term><command>sudo gpsinit plx_pci</command></term> +<listitem> +<para>Attempt to load the module plx_pci and initialize net 0 for the +connection to a NMEA2000 network. It will set the baudrate to +250kBits.</para> +</listitem> +</varlistentry> +<varlistentry> +<term><command>sudo gpsinit -n 1 plx_pci</command></term> +<listitem> +<para>As above, but use net 1.</para> +</listitem> +</varlistentry> +<varlistentry> +<term><command>sudo gpsinit -s 38400 slcan /dev/ttyUSB0</command></term> +<listitem> +<para>Attempt to load the module slcan and talk to the hardware at +38400 baud connected to port /dev/ttyUSB0.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><command>gpsinit -h </command></term> +<listitem> +<para>Display a brief help message.</para> +</listitem> +</varlistentry> +<varlistentry> +<term><command>gpsinit -v </command></term> +<listitem> +<para>Display the version of gpsinit.</para> +</listitem> +</varlistentry> +</variablelist> +</refsect1> + +<refsect1 id='see_also'><title>SEE ALSO</title> +<para> +<citerefentry><refentrytitle>gpsd</refentrytitle><manvolnum>8</manvolnum></citerefentry>, +<citerefentry><refentrytitle>gps</refentrytitle><manvolnum>1</manvolnum></citerefentry>, +<citerefentry><refentrytitle>libgps</refentrytitle><manvolnum>3</manvolnum></citerefentry>, +<citerefentry><refentrytitle>libgpsmm</refentrytitle><manvolnum>3</manvolnum></citerefentry>. +</para> +</refsect1> + +<refsect1 id='maintainer'><title>AUTHOR</title> +<para>Reinhard Arlt <email>reinhard.arlt@t-online.de</email>.</para> +</refsect1> +</refentry> diff --git a/man/gpsmon.xml b/man/gpsmon.xml new file mode 100644 index 00000000..f33b5f15 --- /dev/null +++ b/man/gpsmon.xml @@ -0,0 +1,428 @@ +<?xml version="1.0" encoding="ISO-8859-1"?> +<!-- +This file is Copyright (c) 2010-2019 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"> +<refentry id='gpsmon.1'> +<refentryinfo><date>17 Feb 2009</date></refentryinfo> +<refmeta> +<refentrytitle>gpsmon</refentrytitle> +<manvolnum>1</manvolnum> +<refmiscinfo class="source">The GPSD Project</refmiscinfo> +<refmiscinfo class="manual">GPSD Documentation</refmiscinfo> +</refmeta> +<refnamediv id='name'> +<refname>gpsmon</refname> +<refpurpose>real-time GPS packet monitor and control utility</refpurpose> +</refnamediv> +<refsynopsisdiv id='synopsis'> + +<cmdsynopsis> + <command>gpsmon</command> + <arg choice='opt'>-L </arg> + <arg choice='opt'>-V </arg> + <arg choice='opt'>-h </arg> + <arg choice='opt'>-n </arg> + <arg choice='opt'>-a </arg> + <arg choice='opt'>-l <replaceable>logfile</replaceable></arg> + <arg choice='opt'>-t <replaceable>driver-prefix</replaceable></arg> + <arg choice='opt'> + <group> + <arg choice='plain'> + <replaceable>server</replaceable> + <group> + <replaceable>:port</replaceable> + <group><replaceable>:device</replaceable></group> + </group> + </arg> + <arg choice='plain'><replaceable>device</replaceable></arg> + </group> + </arg> + <arg choice='opt'>-D <replaceable>debuglevel</replaceable></arg> +</cmdsynopsis> +</refsynopsisdiv> + +<refsect1 id='description'><title>DESCRIPTION</title> + +<para><application>gpsmon</application> is a monitor that watches +packets coming from a GPS and displays them along with diagnostic +information. It supports commands that can be used to tweak GPS +settings in various ways; some are device-independent, some vary with +the GPS chipset type. It will behave sanely, just dumping packets, +when connected to a GPS type it knows nothing about.</para> + +<para><application>gpsmon</application> differs from a navigation +client in that it mostly dumps raw data from the GPS, with only enough +data-massaging to allow checks against expected output. In +particular, this tool does not do any interpolation or modeling +to derive climb/sink or error estimates. Nor does it discard +altitude reports when the fix quality is too low.</para> + +<para>Unlike <application>gpsd</application>, +<application>gpsmon</application> never writes control or probe +strings to the device unless you explicitly tell it to. Thus, while +it will auto-sync to binary packet types, it won't automatically +recognize a device shipping an extended NMEA protocol as anything +other than a plain NMEA device. Use the <option>-t</option> option or +the <command>t</command> to work around this.</para> + +<para><application>gpsmon</application> is a designed to run in a +terminal emulator with a minimum 25x80 size; the non-GUI interface is +a design choice made to accommodate users operating in constrained +environments and over telnet or ssh connections. If run in a larger +window, the size of the packet-log window will be increased to +fit.</para> + +<para><application>gpsmon</application> accepts an -h option that +displays a usage message, or a -V option to dump the package +version and exit.</para> + +<para>This program may be run in either of two modes, as a client for +the <application>gpsd</application> daemon (and its associated control +socket) or directly connected to a specified serial device. When run +with no argument, it attempts to connect to the daemon. If the +argument begins with a server:port specification it will also attempt +to connect to the daemon. If the argument looks like a bare server +name it will attempt to connect to a daemon running on the default +gpsd port on that server. Only if the device argument contains +slashes but no colons will it be treated as a serial device for direct +connection. In direct-connect mode <application>gpsmon</application> +will hunt for a correct baud rate and lock on to it +automatically. Possible cases look like this:</para> + +<variablelist> +<varlistentry> +<term>localhost:/dev/ttyS1</term> +<listitem><para>Look at the default port of localhost, trying both +IPv4 and IPv6 and watching output from serial device 1.</para></listitem> +</varlistentry> +<varlistentry> +<term>example.com:2317</term> +<listitem><para>Look at port 2317 on example.com, trying both +IPv4 and IPv6.</para></listitem> +</varlistentry> +<varlistentry> +<term>71.162.241.5:2317:/dev/ttyS3</term> +<listitem><para>Look at port 2317 at the specified IPv4 +address, collecting data from attached serial device 3.</para></listitem> +</varlistentry> +<varlistentry> +<term>[FEDC:BA98:7654:3210:FEDC:BA98:7654:3210]:2317:/dev/ttyS5</term> +<listitem><para>Look at port 2317 at the specified IPv6 +address, collecting data from attached serial device 5.</para></listitem> +</varlistentry> +</variablelist> + +<para>Unlike <application>gpsd</application>, +<application>gpsmon</application> run in direct mode does not do its +own device probing. Thus, in particular, if you point it at a +GPS with a native binary mode that happens to be emitting NMEA, it +won't identify the actual type unless the device emits a recognizable +NMEA trigger sentence. The -t and -i options may help you.</para> + +<para>The -F option is only valid in client mode; it specifies a +control socket to which the program should send device control +strings. You must specify a valid pathname of a Unix-domain socket on +your local filesystem.</para> + +<para>The -D option enables packet-getter debugging output and is +probably only useful to developers of the GPSD code. Consult the +packet-getter source code for relevant values.</para> + +<para>The -L option lists a table showing which GPS device types +<application>gpsmon</application> has built-in support for, and which +generic commands can be applied to which GPS types, and then +exits. Note that this does not list type-specific commands associated +with individual GPS types.</para> + +<para>The -l option sets up logging to a specified file to start +immediately on device open. This may be useful is, for example, +you want to capture the startup message from a device that displays +firmware version information there.</para> + +<para>The -n option forces gpsmon to request NMEA0183 packets instead of the +raw datastream from gpsd.</para> + +<para>The -t option sets up a fallback type. Give it a string that +is a distinguishing prefix of exactly one driver type name; this will +be used for mode, speed, and rate switching if the driver selected +by the packet type lacks those capabilities. Most useful when the +packet type is NMEA but the device is known to have a binary mode, +such as SiRF binary.</para> + +<para>The -a option enables a special debugging mode that does not +use screen painting. Packets are dumped normally; any character +typed suspends packet dumping and brings up a command prompt. This +feature will mainly be of interest to GPSD developers.</para> + +<para>After startup (without -a), the top part of the screen reports +the contents of several especially interesting packet types. The +"PPS" field, if nonempty, is the delta between the last 1PPS top of +second and the system clock at that time.</para> + +<para>The bottom half of the screen is a scrolling hex dump of all +packets the GPS is issuing. If the packet type is textual, any +trailing CR/LF is omitted. Dump lines beginning >>> represent +control packets sent to the GPS. Lines consisting of "PPS" surrounded +by dashes, if present, indicate 1PPS and the start of the reporting +cycle.</para> + +</refsect1> +<refsect1 id='commands'><title>COMMANDS</title> + +<para>The following device-independent commands are available while +<application>gpsmon</application> is running:</para> + +<variablelist> + +<varlistentry> +<term>i</term> +<listitem> +<para>(Direct mode only.) Enable/disable subtype probing and +reinitialize the driver. In normal operation, +<application>gpsmon</application> does not send configuration strings +to the device (except for wakeup strings needed to get it to send +data, if any). The command 'i1' causes it to send the same sequence of +subtype probes that <application>gpsd</application> would. The +command 'i0' turns off probing; 'i' alone toggles the bit. In either +case, the current driver is re-selected; if the probe bit is enabled, +probes will begin to be issued immediately.</para> + +<para>Note that enabling probing might flip the device into another +mode; in particular, it will flip a SiRF chip into binary mode as if +you had used the <quote>n</quote> command. This is due to a +limitation in the SiRF firmware that we can't fix.</para> + +<para>This command will generally do nothing after the first time you +use it, because the device type will already have been discovered.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>c</term> +<listitem> +<para>(Direct mode only.) Change cycle time. Follow it with a number +interpreted as a cycle time in seconds. Most devices have a fixed +cycle time of 1 second, so this command may fail with a +message.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>l</term> +<listitem> +<para>Toggle packet logging. If packet logging is on, it will be +turned off and the log closed. If it is off, logging to the filename +following the l will be enabled. Differs from simply capturing the +data from the GPS device in that only whole packets are logged. +The logfile is opened for append, so you can log more than one +portion of the packet stream and they will be stitched together +correctly.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>n</term> +<listitem> +<para>(Direct mode only.) With an argument of 0, switch device to NMEA +mode at current speed; with an argument of 1, change to binary +(native) mode. With no argument, toggle the setting. Will show an +error if the device doesn't have such modes.</para> + +<para>After you switch a dual-protocol GPS to NMEA mode with this +command, it retains the information about the original type and its +control capabilities. That is why the device type listed before the +prompt doesn't change.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>q</term> +<listitem> +<para>Quit <application>gpsmon</application>. Control-C, or whatever +your current interrupt character is, works as well.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>s</term> +<listitem> +<para>(Direct mode only.) Change baud rate. Follow it with a number +interpreted as bits per second, for example "s9600". The speed number +may optionally be followed by a colon and a wordlength-parity-stopbits +specification in the traditional style, e.g 8N1 (the default), 7E1, +etc. Some devices don't support serial modes other than their +default, so this command may fail with a message.</para> + +<para>Use this command 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> +</listitem> +</varlistentry> + +<varlistentry> +<term>t</term> +<listitem> +<para>(Direct mode only.) Force a switch of monitoring type. Follow it +with a string that is unique to the name of a gpsd driver with +<application>gpsmon</application> support; +<application>gpsmon</application> will switch to using that driver and +display code. Will show an error message if there is no matching gpsd +driver, or multiple matches, or the unique match has no display +support in <application>gpsmon</application>.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>x</term> +<listitem> +<para>(Direct mode only.) Send hex payload to device. Following the +command letter you may type hex digit pairs; end with a newline. +These will become the payload of a control packet shipped to the +device. The packet will be wrapped with headers, trailers, and +checksum appropriate for the current driver type. The first one or two +bytes of the payload may be specially interpreted, see the description +of the <option>-x</option> of +<citerefentry><refentrytitle>gpsctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>X</term> +<listitem> +<para>(Direct mode only.) Send raw hex bytes to device. Following the +command letter you may type hex digit pairs; end with a newline. +These will be shipped to the device.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>Ctrl-S</term> +<listitem> +<para>Freeze display, suspend scrolling in debug window.</para> +</listitem> +</varlistentry> +<varlistentry> +<term>Ctrl-Q</term> +<listitem> +<para>Unfreeze display, resume normal operation.</para> +</listitem> +</varlistentry> +</variablelist> + +<refsect2><title>NMEA support</title> + +<para>(These remarks apply to not just generic NMEA devices +but all extended NMEA devices for which +<application>gpsmon</application> presently has support.)</para> + +<para>All fields are raw data from the GPS except (a) the "Cooked PVT" +window near top of screen, provided as a check and (b) the "PPS +offset" field.</para> + +<para>There are no device-specific commands. Which generic +commands are available may vary by type: examine the output +of <command>gpsmon -l</command> to learn more.</para> +</refsect2> + +<refsect2><title>SiRF support</title> +<para>Most information is raw from the GPS. Underlined fields are +derived by translation from ECEF coordinates or application of +leap-second and local time-zone offsets. 1PPS is the clock lag as +usual.</para> + +<para>The following commands are supported for SiRF GPSes only:</para> + +<variablelist> +<varlistentry> +<term>A</term> +<listitem> +<para>(Direct mode only.) Toggle reporting of 50BPS subframe data.</para> +</listitem> +</varlistentry> +<varlistentry> +<term>M</term> +<listitem> +<para>(Direct mode only.) Set (M1) or clear (M0) static +navigation. The SiRF documentation says <quote>Static navigation is a +position filter designed to be used with motor vehicles. When the +vehicle's velocity falls below a threshold, the position and heading +are frozen, and velocity is set to zero. This condition will continue +until the computed velocity rises above 1.2 times the threshold or +until the computed position is at least a set distance from the frozen +place. The threshold velocity and set distance may vary with software +versions.</quote></para> + +<para>Non-static mode is designed for use with road navigation +software, which often snaps the reported position to the nearest road +within some uncertainty radius. You probably want to turn static +navigation off for pedestrian use, as it is likely to report speed +zero and position changing in large jumps.</para> +</listitem> +</varlistentry> +<varlistentry> +<term>P</term> +<listitem> +<para>(Direct mode only.) Toggle navigation-parameter display mode. +Toggles between normal display and one that shows selected navigation +parameters from MID 19, including the Static Navigation bit toggled by +the 'M' command.</para> +</listitem> +</varlistentry> +</variablelist> + +<para>To interpret what you see, you will need a copy of the +<citetitle>SiRF Binary Protocol Reference Manual</citetitle>.</para> + +</refsect2> +<refsect2><title>u-blox support</title> +<para>Most information is raw from the GPS. Underlined fields are +derived by translation from ECEF coordinates. 1PPS is the clock lag as +usual. There are no per-type special commands.</para> + +</refsect2> +</refsect1> +<refsect1 id='bugs'><title>BUGS AND LIMITATIONS</title> + +<para>The PPS Offset field will never be updated when running in +client mode, even if you can see PPS events in the packet window. +This limitation may be fixed in a future release.</para> + +<!-- +Debug window dumps of control message sends to the GPS (preceded +by '>>>') are only supported for the following drivers: NMEA, SiRF, +EverMore, Navcom, UBX, TSIP, iTalk, Garmintxt. This feature will not +work for Zodiacs and not always work for Garmins in binary +mode. +--> + +</refsect1> +<refsect1 id='see_also'><title>SEE ALSO</title> +<para> +<citerefentry><refentrytitle>gpsd</refentrytitle><manvolnum>8</manvolnum></citerefentry>, +<citerefentry><refentrytitle>gpsdctl</refentrytitle><manvolnum>8</manvolnum></citerefentry>, +<citerefentry><refentrytitle>gps</refentrytitle><manvolnum>1</manvolnum></citerefentry>, +<citerefentry><refentrytitle>libgps</refentrytitle><manvolnum>3</manvolnum></citerefentry>, +<citerefentry><refentrytitle>libgpsmm</refentrytitle><manvolnum>3</manvolnum></citerefentry>, +<citerefentry><refentrytitle>gpsprof</refentrytitle><manvolnum>1</manvolnum></citerefentry>, +<citerefentry><refentrytitle>gpsfake</refentrytitle><manvolnum>1</manvolnum></citerefentry>, +<citerefentry><refentrytitle>gpsctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, +<citerefentry><refentrytitle>gpscat</refentrytitle><manvolnum>1</manvolnum></citerefentry>. +<citerefentry><refentrytitle>gpspipe</refentrytitle><manvolnum>1</manvolnum></citerefentry>. +</para> +</refsect1> + +<refsect1 id='maintainer'><title>AUTHOR</title> + +<para>Eric S. Raymond <email>esr@thyrsus.com</email>.</para> +</refsect1> + +</refentry> + diff --git a/man/gpspipe.xml b/man/gpspipe.xml new file mode 100644 index 00000000..9c5da4f3 --- /dev/null +++ b/man/gpspipe.xml @@ -0,0 +1,185 @@ +<?xml version="1.0" encoding="ISO-8859-1"?> +<!-- +This file is Copyright (c) 2010 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"> +<refentry id='gpspipe.1'> + <refentryinfo> + <date>17 Jun 2018</date> + </refentryinfo> + <refmeta> + <refentrytitle>gpspipe</refentrytitle> + <manvolnum>1</manvolnum> + <refmiscinfo class="source">The GPSD Project</refmiscinfo> + <refmiscinfo class="manual">GPSD Documentation</refmiscinfo> + </refmeta> + <refnamediv id='name'> + <refname>gpspipe</refname> + <refpurpose>tool to connect to gpsd and retrieve sentences</refpurpose> + </refnamediv> + <refsynopsisdiv id='synopsis'> + <cmdsynopsis> + <command>gpspipe</command> + <arg choice='opt'>-2</arg> + <arg choice='opt'>-d</arg> + <arg choice='opt'>-D <replaceable>debug-level</replaceable> + </arg> + <arg choice='opt'>-h</arg> + <arg choice='opt'>-l</arg> + <arg choice='opt'>-n <replaceable>count</replaceable> + </arg> + <arg choice='opt'>-o <replaceable>filename</replaceable> + </arg> + <arg choice='opt'>-p</arg> + <arg choice='opt'>-r</arg> + <arg choice='opt'>-R</arg> + <arg choice='opt'>-S</arg> + <arg choice='opt'>-s <replaceable>serial-device</replaceable> + </arg> + <arg choice='opt'>-t</arg> + <arg choice='opt'>-T <replaceable>timestamp-format</replaceable> + </arg> + <arg choice='opt'>-u</arg> + <arg choice='opt'>-v</arg> + <arg choice='opt'>-w</arg> + <arg choice='opt'>-x</arg> + <group> + <replaceable>server</replaceable> + <group> + <replaceable>:port</replaceable> + <group> + <replaceable>:device</replaceable> + </group> + </group> + </group> + </cmdsynopsis> + </refsynopsisdiv> + <refsect1 id='description'> + <title>DESCRIPTION</title> + <para> + <application>gpspipe</application> is a tool to connect +to <application>gpsd</application> and output the received +sentences to stdout. This makes the program useful as a pipe from +<application>gpsd</application> to another program or file. </para> + <para> + <application>gpspipe</application> does not require root +privileges, and can be run concurrently with other tools connecting +to the local <application>gpsd</application> without causing problems.</para> + <para>The output will consist of one or both of the raw NMEA or native +<application>gpsd</application> sentences. Each line can be optionally +time stamped. There is also an option to exit gracefully after a +given count of packets.</para> + <para>Optionally a server, TCP/IP port number and remote device can be given. +If omitted, <application>gpspipe</application> connects to localhost on +the default port (2947) and watches all devices opened by +<application>gpsd</application>.</para> + <para> + <application>gpspipe</application> may be run as a daemon, but +requires the -o flag for writing the output to a file.</para> + </refsect1> + <refsect1 id='options'> + <title>OPTIONS</title> + <para>-2 sets the split24 flag on AIS reports. Note: this option +is experimental and may be changed or removed in a future release.</para> + <para>-d causes <application>gpspipe</application> to run as a daemon.</para> + <para>-h makes <application>gpspipe</application> print +a usage message and exit.</para> + <para>-l causes <application>gpspipe</application> to sleep for ten +seconds before attempting to connect to gpsd. This is very useful +when running as a daemon, giving gpsd time to start before +attempting a connection.</para> + <para>-n [count] causes [count] sentences to be output. +<application>gpspipe</application> will then exit gracefully.</para> + <para>-o option causes the collected data to be written to the +specified file. Use of this option is mandatory +if <application>gpspipe</application> is run as a daemon.</para> + <para>-p enables dumping of profiling information in JSON.</para> + <para>-P enables dumping of PPS drift JSON in NMEA and raw modes.</para> + <para>-r causes raw NMEA sentences to be output.</para> + <para>-R causes super-raw (gps binary) data to be output. This overrides +NMEA and gpsd output modes.</para> + <para>-s option causes the collected data to be written to the +specified serial device with settings 4800 8N1. Thus +<application>gpspipe</application> can be used with -s and -r options +to emulate a serial port hardwired to a GPS that +<application>gpsd</application> is managing.</para> + <para>-S sets the scaled flag.</para> + <para>-t adds a timestamp to each sentence output.</para> + <para>-T sets the format of the timestamp. See +<citerefentry> + <refentrytitle>strftime</refentrytitle> + <manvolnum>3</manvolnum> + </citerefentry> +for the available placeholders. Setting this option implies -t. +Default setting is "%F %T"</para> + <para>-u usec resolution time stamp, implies -t. Use -uu to output sec.usec.</para> + <para>-v causes <application>gpspipe</application> to show a spinning +activity indicator on stderr. This is useful if stdout is redirected +into a file or a pipe. By default the spinner is advanced with every +messages written; specifying -v more than once will double the number +of messages required to rotate the spinner.</para> + <para>-V prints the version, then exits.</para> + <para>-w causes native <application>gpsd</application> sentences to be +output.</para> + <para>-x [seconds] Exit after delay of [seconds].</para> + <para>At least one of -R, -r or -w must be specified.</para> + </refsect1> + <refsect1 id='exampletitle'> + <title>EXAMPLES</title> + <para>When <application>gpsd</application> is running, + <command>gpspipe +-r -n 100</command> will send one hundred raw NMEA sentences to +standard output, then exit.</para> + <para>When <application>gpsd</application> is running, <command>gpspipe +-x 5 -w|sed -n '/TPV/{p;q}'</command> will wait at most 5 seconds for a +TPV message, print it to stdout, then exit.</para> + </refsect1> + <refsect1 id='see_also'> + <title>SEE ALSO</title> + <para> + <citerefentry> + <refentrytitle>gpsd</refentrytitle> + <manvolnum>8</manvolnum> + </citerefentry>, +<citerefentry> + <refentrytitle>gps</refentrytitle> + <manvolnum>1</manvolnum> + </citerefentry>, +<citerefentry> + <refentrytitle>libgps</refentrytitle> + <manvolnum>3</manvolnum> + </citerefentry>, +<citerefentry> + <refentrytitle>libgpsmm</refentrytitle> + <manvolnum>3</manvolnum> + </citerefentry>, +<citerefentry> + <refentrytitle>gpsprof</refentrytitle> + <manvolnum>1</manvolnum> + </citerefentry>, +<citerefentry> + <refentrytitle>gpsfake</refentrytitle> + <manvolnum>1</manvolnum> + </citerefentry>, +<citerefentry> + <refentrytitle>gpsctl</refentrytitle> + <manvolnum>1</manvolnum> + </citerefentry>, +<citerefentry> + <refentrytitle>gpscat</refentrytitle> + <manvolnum>1</manvolnum> + </citerefentry>. +<citerefentry> + <refentrytitle>gpsmon</refentrytitle> + <manvolnum>1</manvolnum> + </citerefentry>. +</para> + </refsect1> + <refsect1 id='maintainer'> + <title>AUTHOR</title> + <para>Gary E. Miller <email>gem@rellim.com</email>.</para> + </refsect1> +</refentry> diff --git a/man/gpsprof.xml b/man/gpsprof.xml new file mode 100644 index 00000000..bdc22691 --- /dev/null +++ b/man/gpsprof.xml @@ -0,0 +1,291 @@ +<?xml version="1.0" encoding="ISO-8859-1"?> +<!-- +This file is Copyright (c) 2010 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"> +<refentry id='gpsprof.1'> +<refentryinfo><date>30 May 2018</date></refentryinfo> +<refmeta> +<refentrytitle>gpsprof</refentrytitle> +<manvolnum>1</manvolnum> +<refmiscinfo class="source">The GPSD Project</refmiscinfo> +<refmiscinfo class="manual">GPSD Documentation</refmiscinfo> +</refmeta> +<refnamediv id='name'> +<refname>gpsprof</refname> +<refpurpose>profile a GPS and gpsd, plotting latency information</refpurpose> +</refnamediv> +<refsynopsisdiv id='synopsis'> + +<cmdsynopsis> + <command>gpsprof</command> + <arg choice='opt'>-D <replaceable>debuglevel</replaceable></arg> + <arg choice='opt'>-d <replaceable>dumpfile</replaceable></arg> + <arg choice='opt'>-f <replaceable>plot_type</replaceable></arg> + <arg choice='opt'>-h </arg> + <arg choice='opt'>-l <replaceable>logfile</replaceable></arg> + <arg choice='opt'>-m <replaceable>threshold</replaceable></arg> + <arg choice='opt'>-n <replaceable>samplecount</replaceable></arg> + <arg choice='opt'>-r </arg> + <arg choice='opt'>-S <replaceable>subtitle</replaceable></arg> + <arg choice='opt'>-T <replaceable>terminal</replaceable></arg> + <arg choice='opt'>-t <replaceable>title</replaceable></arg> + <arg choice='opt'>[server[:port[:device]]]</arg> +</cmdsynopsis> +</refsynopsisdiv> + +<refsect1 id='description'><title>DESCRIPTION</title> + +<para><application>gpsprof</application> performs accuracy, latency, +skyview, and time drift profiling on a GPS. It emits to standard output +a GNUPLOT program that draws one of several illustrative graphs. It can +also be told to emit the raw profile data.</para> + +<para>Information from the default spatial plot it provides can be +useful for characterizing position accuracy of a GPS.</para> + +<para><application>gpsprof</application> uses instrumentation built +into <application>gpsd</application>. It can read data from a local +or remote running <application>gpsd</application>. Or it can read +data from a saved logfile.</para> + +<para><application>gpsprof</application> is designed to be lightweight +and use minimal host resources. No graphics subsystem needs to be +installed on the host running <application>gpsprof</application>. Simply +copy the resultant plot file to another host to be rendered +with <application>gnuplot</application>. +</para> + +</refsect1> +<refsect1 id='options'><title>OPTIONS</title> + +<para>The -f option sets the plot type. Currently the following plot +types are defined:</para> + +<variablelist> +<varlistentry> +<term>space</term> +<listitem> +<para>Generate a scatterplot of fixes and plot probable error circles. +This data is only meaningful if the GPS is held stationary while +<application>gpsprof</application> is running. Various statistics about +the fixes are listed at the bottom. This is the default plot type.</para> +</listitem> +</varlistentry> +<varlistentry> +<term>polar</term> +<listitem> +<para>Generate a heat map of reported satellite Signal to Noise Ratio +(SNR) using polar coordinates. A colored dot is plotted for +each satellite seen by the GPS. The color of dot corresponds to the +SNR of the satellite. The dots are plotted by azimuth and +elevation. North, azimuth 0 degrees, is at the top of the plot. +Directly overhead, elevation of 90 degrees, is plotted at the center. +Useful for analyzing the quality of the skyview as seen by the GPS. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>polarunused</term> +<listitem> +<para>Similar to the polar plot, but only unused satellites +are plotted. Useful for seeing which parts of the antenna skyview +are obstructed, degraded, below the GPS elevation mask, or otherwise +rejected.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>polarused</term> +<listitem> +<para>Similar to the polar plot, but only satellites used to compute +fixs are plotted. Useful for seeing which parts of the antenna +skyview are being used in fixes.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>time</term> +<listitem> +<para>Plot delta of system clock (NTP corrected time) against GPS time +as reported in PPS messages. The X axis is sample time in seconds +from the start of the plot. The Y axis is the system clock delta from +GPS time. This plot only works if <application>gpsd</application> was +built with the timing (latency timing support) configure option +enabled.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>instrumented</term> +<listitem> +<para>Plot instrumented profile. Plots various components of the total +latency between the GPS's fix time and when the client receives the +fix. This plot only works if <application>gpsd</application> was built +with the timing (latency timing support) configuration option enabled. +</para> +<para>For purposes of the description, below, start-of-reporting-cycle +(SORC) is when a device's reporting cycle begins. This time is +detected by watching to see when data availability follows a long +enough amount of quiet time that we can be sure we've seen the gap at +the end of the sensor's previous report-transmission cycle. Detecting +this gap requires a device running at 9600bps or faster.</para> + +<para>Similarly, EORC is end-of-reporting-cycle; when the daemon has +seen the last sentence it needs in the reporting cycle and ready to ship +a fix to the client.</para> + +<para>The components of the instrumented plot are as follows:</para> + +<variablelist> +<varlistentry> +<term>Fix latency</term> +<listitem> +<para>Delta between GPS time and SORC.</para> +</listitem> +</varlistentry> +<varlistentry> +<term>RS232 time</term> +<listitem> +<para>RS232 transmission time for data shipped during the cycle +(computed from character volume and baud rate).</para> +</listitem> +</varlistentry> +<varlistentry> +<term>Analysis time</term> +<listitem> +<para>EORC, minus SORC, minus RS232 time. The amount of real time the daemon +spent on computation rather than I/O.</para> +</listitem> +</varlistentry> +<varlistentry> +<term>Reception time</term> +<listitem> +<para>Shipping time from +the daemon to when it was received by <application>gpsprof</application>.</para> +</listitem> +</varlistentry> +</variablelist> + +<para>Because of RS232 buffering effects, the profiler sometimes +generates reports of ridiculously high latencies right at the +beginning of a session. The -m option lets you set a latency +threshold, in multiples of the cycle time, above which reports are +discarded.</para> + +</listitem> +</varlistentry> +<varlistentry> +<term>uninstrumented</term> +<listitem> +<para>Plot total latency without instrumentation. Useful mainly as a +check that the instrumentation is not producing significant distortion. +The X axis is sample time in seconds from the start of the plot. The Y +axs is latency in seconds.It only plots times for reports that contain +fixes; staircase-like artifacts in the plot are created when elapsed +time from reports without fixes is lumped in.</para> +</listitem> +</varlistentry> +</variablelist> + + +<para>The -d option dumps the plot data, without attached gnuplot +code, to a specified file for post-analysis.</para> + +<para>The -D sets debug level.</para> + +<para>The -h option makes <application>gpsprof</application> print +a usage message and exit.</para> + +<para>The -l option dumps the raw JSON reports collected from the device +to a specified file.</para> + +<para>The -n option sets the number of packets to sample. The default +is 100. Most GPS are configured to emit one fix per second, so 100 +samples would then span 100 seconds.</para> + +<para>The -r option replots from a JSON logfile (such as -l produces) +on standard input. Both -n and -l options are ignored when this +one is selected.</para> + +<para>The -S option sets a text string to be included in the plot +as a subtitle. This will be below the title.</para> + +<para>The -t option sets a text string to be the plot title. This +will replace the default title.</para> + +<para>The -T option generates a terminal type setting into the gnuplot +code. Typical usage is "-T png", or "-T pngcairo" telling gnuplot to +write a PNG file. Without this option gnuplot will call its X11 display +code.</para> +<para> Different installations of <application>gnuplot</application> will +support different terminal types. Different terminal types may work better +for you than other ones. "-T png" will generate PNG images. Use "-T jpeg" +to generate JPEG images. "-T pngcairo" often works best, but is not +supported by some distributions.</para> + +</refsect1> +<refsect1 id='signals'><title>SIGNALS</title> +<para>Sending SIGUSR1 to a running instance causes it to write a +completion message to standard error and resume processing. The +first number in the startup message is the process ID to signal.</para> +</refsect1> + +<refsect1 id='examples'><title>EXAMPLES</title> +<para>To display the graph, use +<citerefentry><refentrytitle>gnuplot</refentrytitle><manvolnum>1</manvolnum></citerefentry>. +Thus, for example, to display the default spatial scatter plot, do +this: + +<programlisting> +gpsprof | gnuplot -persist +</programlisting> +</para> + +<para>To generate an image file: + +<programlisting> +gpsprof -T png | gnuplot > image.png +</programlisting> +</para> +<para> +To generate a polar plot, and save the GPS data for further plots: +<programlisting> +gpsprof -f polar -T jpeg -l polar.json | gnuplot > polar.png +</programlisting> +Then to make the matching polarused and polarunused plots and pngs from +the just saved the GPS data: +<programlisting> +gpsprof -f polarused -T jpeg -r < polar.json > polarused.plot +gnuplot < polarused.plot > polarused.png +gpsprof -f polarunused -T jpeg -r < polar.json > polarunused.plot +gnuplot < polarunused.plot > polarunused.png +</programlisting> +</para> + +</refsect1> +<refsect1 id='see_also'><title>SEE ALSO</title> +<para> +<citerefentry><refentrytitle>gpsd</refentrytitle><manvolnum>8</manvolnum></citerefentry>, +<citerefentry><refentrytitle>gps</refentrytitle><manvolnum>1</manvolnum></citerefentry>, +<citerefentry><refentrytitle>libgps</refentrytitle><manvolnum>3</manvolnum></citerefentry>, +<citerefentry><refentrytitle>libgpsmm</refentrytitle><manvolnum>3</manvolnum></citerefentry>, +<citerefentry><refentrytitle>gpsfake</refentrytitle><manvolnum>1</manvolnum></citerefentry>, +<citerefentry><refentrytitle>gpsctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, +<citerefentry><refentrytitle>gpscat</refentrytitle><manvolnum>1</manvolnum></citerefentry>, +<citerefentry><refentrytitle>gnuplot</refentrytitle><manvolnum>1</manvolnum></citerefentry>. +</para> +</refsect1> + +<refsect1 id='maintainer'><title>AUTHOR</title> + +<para>Eric S. Raymond <email>esr@thyrsus.com</email>.</para> + +</refsect1> + +</refentry> + diff --git a/man/gpsrinex.xml b/man/gpsrinex.xml new file mode 100644 index 00000000..59632f5a --- /dev/null +++ b/man/gpsrinex.xml @@ -0,0 +1,195 @@ +<?xml version="1.0" encoding="ISO-8859-1"?> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"> +<!-- +This file is Copyright (c) 2018 by the GPSD project +SPDX-License-Identifier: BSD-2-clause +--><refentry id="gpsrinex.1"> + <refentryinfo> + <date>09 Nov 2018</date> + </refentryinfo> + <refmeta> + <refentrytitle>gpsrinex</refentrytitle> + <manvolnum>1</manvolnum> + <refmiscinfo class="source">The GPSD Project</refmiscinfo> + <refmiscinfo class="manual">GPSD Documentation</refmiscinfo> + </refmeta> + <refnamediv id="name"> + <refname>gpsrinex</refname> + <refpurpose>Read data from gpsd convert to RINEX3 and save to a file.</refpurpose> + </refnamediv> + <refsynopsisdiv id="synopsis"> + <cmdsynopsis> + <command>gpsrinex</command> + <arg choice="opt">-D <replaceable>debuglevel</replaceable></arg> + <arg choice="opt">-f <replaceable>filename</replaceable></arg> + <arg choice="opt">-h</arg> + <arg choice="opt">-i <replaceable>interval</replaceable></arg> + <arg choice="opt">-n <replaceable>count</replaceable></arg> + <arg choice="opt">-V</arg> + <group> + <replaceable>server</replaceable> + <group> + <replaceable>:port</replaceable> + <group> + <replaceable>:device</replaceable> + </group> + </group> + </group> + </cmdsynopsis> + </refsynopsisdiv> + <refsect1 id="description"> + <title>DESCRIPTION</title> + <para> + <application>gpsrinex</application> is a tool to connect to +<application>gpsd</application> and output the received raw measurements +as a RINEX 3 observation file. This is useful for sending raw measurements +(pseudorange and carrierphase) from <application>gpsd</application> to +a Precise Point Positioning (PPP) program or service.</para> + <para> + <application>gpsrinex</application> does not require root +privileges, and can be run concurrently with other tools connecting +to a local or remote <application>gpsd</application> without causing +problems.</para> + <para>gpsrinex needs the GPS receiver to be sending raw measurements +to <application>gpsd</application>. Only a few GPS have this capability. +In addition, the <application>gpsd</application> driver for that GPS +must support raw mode. Currently only the u-blox driver has this support. +Only a few u-blox 8 GPS implment the required UBX-RXM-RAWX message. The +NEO-M8T is known to work, but requires configuration with +<application>ubxtool</application>.</para> + <para>RINEX has its own definitions and abbreviations. Be +sure to consult their documentation. An observation file (.obs) +contains data sets, called epochs, that contain the pseudorange +and carrierphase for each satellite seen.</para> + <para> + <application>gpsrinex</application> by default will acquire +20 epochs spaced apart by 30 seconds. That will take 10 minutes to +complete. Most users consider the 30 second interval to be optimal. +Many PPP programs require at least 1 or 2 hours data, but no more than +24 or 48 hours of data. Most users consider 4 to 6 hours of data +as a minimum for good accuracy. Additional hours will not yield much +improvement. </para> + <para>The output will consist of one RINEX 3 observation file that +is ready to be read by your PPP program. The default filename will be +in the form: gpsrinexYYYYJJJHHMMSS.obs. You can override this filename +with the -f option.</para> + <para>Optionally a server, TCP/IP port number and remote device can +be given. If omitted, <application>gpsrinex</application> connects to +localhost on the default port (2947) and watches all devices opened by +<application>gpsd</application>.</para> + </refsect1> + <refsect1 id="options"> + <title>OPTIONS</title> + <para>-D [debuglevel] set debug level to [debuglevel].</para> + <para>-f [filename] save RINEX into [filename].</para> + <para>-h makes <application>gpsrinex</application> print +a usage message and exit.</para> + <para>-i [interval] wait [interval] seconds between epochs. OPUS +accepts intervals of 1, 2, 3, 5, 10, 15 or,30 seconds. OPUS then +reduces the data to 30 second intervals.</para> + <para>-n [count] causes [count] epochs to be output. OPUS requires a +minimum af 15 minutes, and a maximum of 48 hours, of data.</para> + <para>-V makes <application>gpsrinex</application> print +its version and exit.</para> + </refsect1> + <refsect1 id="exampletitle"> + <title>EXAMPLES</title> + <para>Example 1:</para> + <para>Create a 4 hour .obs file. With a running +<application>gpsd</application> accessible on the localhost do all of +the following, in order. Order matters.</para> + <para>The raw measurement messages are long. Be sure your serial port +speed is high enough: +<programlisting> +gpsctl -s 115200 +</programlisting></para> + <para>Disable all NMEA messages, and enable binary messages: +<programlisting> +ubxtool -d NMEA +ubxtool -e BINARY +</programlisting></para> + <para>The NEO-M8N will only reliably output raw measurements +when only the GPS and QZSS constellations are enabled. +<application>ubxtool</application>, as recommended by u-blox, enables +the QZSS constellation in tandem with GPS. Disable all constellations, +except GPS (and QZSS): + +<programlisting> +ubxtool -d GLONASS +ubxtool -d BEIDOU +ubxtool -d GALILEO +ubxtool -d SBAS +ubxtool -e GPS +</programlisting></para> + <para>Verify the constellations enabled: +<programlisting> +ubxtool -p GNSS +</programlisting></para> + <para>Enable the good stuff, the raw measurement messages: +<programlisting> +ubxtool -e RAWX +</programlisting></para> + <para>Verify raw data messages are being sent: +<programlisting> +ubxtool | fgrep RAWX +</programlisting> +You should see this output: +<programlisting> +UBX-RXM-RAWX: +UBX-RXM-RAWX: +</programlisting></para> + <para>Collect 4 hours of samples at 30 second intervals, save then +RINEX 3 observations in the file today.obs: +<programlisting> +gpsrinex -i 30 -n 480 -f today.obs +</programlisting></para> + <para>Wait 4 hours. Enjoy a meal, or do some exercise. When +<application>gpsrinex</application> finishes, upload the file today.obs +to your favorite PPP service.</para> + <para>Example 2:</para> + <para>Collect raw masurement data from a remote gpsd. The +process it later with <application>gpsrinex</application> and +<application>gpsprof</application>.</para> + <para>Ensure the GPS is configured properly, as shown in Example 1.</para> + <para>Grab 4 hours of raw live data from remote +<application>gpsd</application> at 10.168.1.2: +<programlisting> +gpspipe -x 14400 -R 10.168.1.2 > 4h-raw.ubx +</programlisting></para> + <para>When <application>gpspipe</application> is complete, feed the +data to <application>gpsfake</application>: +<programlisting> +gpsfake -1 -P 3000 4h-raw.ubx +</programlisting></para> + <para>In another window, feed the data to +<application>gpsrinex</application>. Use -n 10000000 so that +all the data from the raw file is used:: +<programlisting> +gpsrinex -i 30 -n 1000000 +</programlisting></para> + <para>Repeat the process with +<application>gpsfake</application> to send the data to +<application>gpsprof</application>.</para> + </refsect1> + <refsect1 id="see_also"> + <title>SEE ALSO</title> + <para>One service known to work with obsrinex output is at: +https://webapp.geod.nrcan.gc.ca/geod/tools-outils/ppp.php</para> + <para>OPUS requires 2 frequency observation files. +https://www.ngs.noaa.gov/OPUS/</para> + <para>The curious can find the RINEX 3.03 format described here: +ftp://igs.org/pub/data/format/rinex303_update1.pdf</para> + <para> + <citerefentry> + <refentrytitle>gpsd</refentrytitle> + <manvolnum>8</manvolnum> + </citerefentry>, +<citerefentry><refentrytitle>gpsfake</refentrytitle><manvolnum>1</manvolnum></citerefentry>, +<citerefentry><refentrytitle>ubxtool</refentrytitle><manvolnum>1</manvolnum></citerefentry>. +</para> + </refsect1> + <refsect1 id="maintainer"> + <title>AUTHOR</title> + <para>Gary E. Miller <email>gem@rellim.com</email>.</para> + </refsect1> +</refentry> diff --git a/man/gpxlogger.xml b/man/gpxlogger.xml new file mode 100644 index 00000000..7d429941 --- /dev/null +++ b/man/gpxlogger.xml @@ -0,0 +1,149 @@ +<?xml version="1.0" encoding="ISO-8859-1"?> +<!-- +This file is Copyright (c) 2017 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"> +<refentry id='gpxlogger.1'> +<refentryinfo><date>05 Mar 2017</date></refentryinfo> +<refmeta> +<refentrytitle>gpxlogger</refentrytitle> +<manvolnum>1</manvolnum> +<refmiscinfo class="source">The GPSD Project</refmiscinfo> +<refmiscinfo class="manual">GPSD Documentation</refmiscinfo> +</refmeta> +<refnamediv id='name'> +<refname>gpxlogger</refname> +<refpurpose>Tool to connect to gpsd and generate a GPX file</refpurpose> +</refnamediv> +<refsynopsisdiv id='synopsis'> + +<cmdsynopsis> + <command>gpxlogger</command> + <arg choice='opt'>-D <replaceable>debug-level</replaceable></arg> + <arg choice='opt'>-d </arg> + <arg choice='opt'>-e <replaceable>export-method</replaceable></arg> + <arg choice='opt'>-f <replaceable>filename</replaceable></arg> + <arg choice='opt'>-l </arg> + <arg choice='opt'>-m <replaceable>minmove</replaceable></arg> + <arg choice='opt'>-h </arg> + <arg choice='opt'>-V </arg> + <arg choice='opt'>-i <replaceable>track timeout</replaceable></arg> + <group> + <replaceable>server</replaceable> + <group> + <replaceable>:port</replaceable> + <group><replaceable>:device</replaceable></group> + </group> + </group> +</cmdsynopsis> +</refsynopsisdiv> + +<refsect1 id='description'><title>DESCRIPTION</title> +<para>This program collects fixes from <application>gpsd</application> +and logs them to standard output in GPX, an XML profile for track +logging.</para> + +<para>The output may be composed of multiple tracks. A new track is +created if there's no fix written for an interval specified by the +<option>-i</option> and defaulting to 5 seconds.</para> + +<para><application>gpxlogger</application> can use any of the +export methods that <application>gpsd</application> supports. +For a list of these methods, use the <option>-l</option>. +To force the method, give the <option>-e</option> one of +the colon-terminated method names from the <option>-l</option> +table.</para> +</refsect1> + +<refsect1 id='options'><title>OPTIONS</title> + +<para>The <option>-h</option> option causes <application>gpxlogger</application> +to emit a summary of its options and then exit.</para> + +<para>The <option>-V</option> option causes <application>gpxlogger</application> +to dump the package version and exit.</para> + +<para> The <option>-D</option> option sets a debug level; +it is primarily for use by GPSD developers. +It enables various progress messages to standard error.</para> + +<para>The <option>-d</option> option tells +<application>gpxlogger</application> to run as a daemon in background. +It requires the <option>-f</option> option, which directs output to a +specified logfile.</para> + +<para>The <option>-m</option> option sets a minimum move distance in +meters (it may include a fractional decimal part). Motions shorter +than this will not be logged.</para> + +<para>The <option>-r</option> option tells +<application>gpxlogger</application> to retry when GPSd loses the fix. +Without <option>-r</option>, <application>gpxlogger</application> +would quit in this case.</para> + +<para>If D-Bus support is available on the host, GPSD is configured to +use it, and <command>-e dbus</command> is specified, this program +listens to DBUS broadcasts from +<application>gpsd</application> via org.gpsd.fix.</para> + +<para>With <command>-e sockets</command>, or if sockets is the method +defaulted to, you may give a server-port-device specification as +arguments.</para> + +<para>The sockets default is to all devices on the localhost, +using the default GPSD port 2947. An optional argument to any +client may specify a server to get data from. A colon-separated suffix +is taken as a port number. If there is a second colon-separated +suffix, that is taken as a specific device name to be +watched. However, if the server specification contains square +brackets, the part inside them is taken as an IPv6 address and +port/device suffixes are only parsed after the trailing bracket. +Possible cases look like this:</para> + +<variablelist> +<varlistentry> +<term>localhost:/dev/ttyS1</term> +<listitem><para>Look at the default port of localhost, trying both +IPv4 and IPv6 and watching output from serial device 1.</para></listitem> +</varlistentry> +<varlistentry> +<term>example.com:2317</term> +<listitem><para>Look at port 2317 on example.com, trying both +IPv4 and IPv6.</para></listitem> +</varlistentry> +<varlistentry> +<term>71.162.241.5:2317:/dev/ttyS3</term> +<listitem><para>Look at port 2317 at the specified IPv4 +address, collecting data from attached serial device 3.</para></listitem> +</varlistentry> +<varlistentry> +<term>[FEDC:BA98:7654:3210:FEDC:BA98:7654:3210]:2317:/dev/ttyS5</term> +<listitem><para>Look at port 2317 at the specified IPv6 +address, collecting data from attached serial device 5.</para></listitem> +</varlistentry> +</variablelist> + +</refsect1> + +<refsect1 id='see_also'><title>SEE ALSO</title> +<para> +<citerefentry><refentrytitle>gpsd</refentrytitle><manvolnum>8</manvolnum></citerefentry>, +<citerefentry><refentrytitle>gps</refentrytitle><manvolnum>1</manvolnum></citerefentry> +<citerefentry><refentrytitle>gpspipe</refentrytitle><manvolnum>1</manvolnum></citerefentry> +</para> +</refsect1> + +<refsect1 id='maintainer'><title>AUTHORS</title> + +<para> + Amaury Jacquot <email>sxpert@sxpert.org</email> & + Petter Reinholdtsen <email>pere@hungry.com</email> & + Chris Kuethe <email>chris.kuethe@gmail.com</email> +</para> + +</refsect1> + +</refentry> diff --git a/man/libgps.xml b/man/libgps.xml new file mode 100644 index 00000000..7e850c3d --- /dev/null +++ b/man/libgps.xml @@ -0,0 +1,393 @@ +<?xml version="1.0" encoding="ISO-8859-1"?> +<!-- +This file is Copyright (c) 2010 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"> +<refentry> +<refentryinfo><date>14 Aug 2004</date></refentryinfo> +<refmeta> +<refentrytitle>3</refentrytitle> +<manvolnum>3</manvolnum> +<refmiscinfo class="source">The GPSD Project</refmiscinfo> +<refmiscinfo class="manual">GPSD Documentation</refmiscinfo> +</refmeta> +<refnamediv id='name'> +<refname>libgps</refname> +<refpurpose>C service library for communicating with the GPS daemon</refpurpose> +</refnamediv> +<refsynopsisdiv id='synopsis'> +<funcsynopsis> +<funcsynopsisinfo> + +C: + +#include <gps.h> + +</funcsynopsisinfo> +<funcprototype> +<funcdef>int <function>gps_open</function></funcdef> + <paramdef>char *<parameter>server</parameter></paramdef> + <paramdef>char * <parameter>port</parameter></paramdef> + <paramdef>struct gps_data_t *<parameter>gpsdata</parameter></paramdef> +</funcprototype> +<funcprototype> +<funcdef>int <function>gps_send</function></funcdef> + <paramdef>struct gps_data_t *<parameter>gpsdata</parameter></paramdef> + <paramdef>char *<parameter>fmt</parameter>...</paramdef> +</funcprototype> +<funcprototype> +<funcdef>int <function>gps_read</function></funcdef> + <paramdef>struct gps_data_t *<parameter>gpsdata</parameter></paramdef> +</funcprototype> +<funcprototype> +<funcdef>bool <function>gps_waiting</function></funcdef> + <paramdef>const struct gps_data_t *<parameter>gpsdata</parameter></paramdef> + <paramdef>int <parameter>timeout</parameter></paramdef> +</funcprototype> +<funcprototype> +<funcdef>char *<function>gps_data</function></funcdef> + <paramdef>const struct gps_data_t *<parameter>gpsdata</parameter></paramdef> +</funcprototype> +<funcprototype> +<funcdef>int <function>gps_unpack</function></funcdef> + <paramdef>char *<parameter>buf</parameter></paramdef> + <paramdef>struct gps_data_t *<parameter>gpsdata</parameter></paramdef> +</funcprototype> +<funcprototype> +<funcdef>int <function>gps_close</function></funcdef> + <paramdef>struct gps_data_t *<parameter>gpsdata</parameter></paramdef> +</funcprototype> +<funcprototype> +<funcdef>int <function>gps_stream</function></funcdef> + <paramdef>struct gps_data_t *<parameter>gpsdata</parameter></paramdef> + <paramdef>unsigned int<parameter>flags</parameter></paramdef> + <paramdef>void *<parameter>data</parameter></paramdef> +</funcprototype> +<funcprototype> +<funcdef>int <function>gps_mainloop</function></funcdef> + <paramdef>struct gps_data_t *<parameter>gpsdata</parameter></paramdef> + <paramdef>int <parameter>timeout</parameter></paramdef> + <paramdef>void (*<parameter>hook</parameter>)(struct gps_data_t *gpsdata)</paramdef> +</funcprototype> +<funcprototype> +<funcdef>const char *<function>gps_errstr</function></funcdef> + <paramdef>int <parameter>err</parameter></paramdef> +</funcprototype> +<funcsynopsisinfo> + +Python: + +import gps + +session = gps.gps(host="localhost", port="2947") + +session.stream(flags=gps.WATCH_JSON) + +for report in session: + process(report) + +del session + +</funcsynopsisinfo> +</funcsynopsis> +</refsynopsisdiv> + +<refsect1 id='description'><title>DESCRIPTION</title> + +<para><emphasis remap='B'>libgps</emphasis> is a service library which +supports communicating with an instance of the +<citerefentry><refentrytitle>gpsd</refentrytitle><manvolnum>8</manvolnum> +</citerefentry>; link it with the linker option -lgps.</para> + +<warning><para>Take care to conditionalize your code on the major and +minor API version symbols in <filename>gps.h</filename>; ideally, +force a compilation failure if GPSD_API_MAJOR_VERSION is not a version +you recognize. See the GPSD project website for more information on +the protocol and API changes.</para></warning> + +<para>Calling <function>gps_open()</function> initializes a GPS-data +structure to hold the data collected by the GPS, and sets up access to +<citerefentry><refentrytitle>gpsd</refentrytitle><manvolnum>1</manvolnum> +</citerefentry> +via either the socket or shared-memory export. The shared-memory +export is faster, but does not carry information about device +activation and deactivation events and will not allow you to monitor +device packet traffic.</para> + +<para><function>gps_open()</function> returns 0 on success, -1 on +errors and is re-entrant. errno is set depending on the error +returned from the socket or shared-memory interface; see +<filename>gps.h</filename> for values and explanations; also see +<function>gps_errstr()</function>. The host address may be a DNS name, +an IPv4 dotted quad, an IPV6 address, or the special value +<constant>GPSD_SHARED_MEMORY</constant> referring to the +shared-memory export; the library will do the right thing for any of +these.</para> + +<para><function>gps_close()</function> ends the session and should only be +called after a successful <function>gps_open()</function>. +It returns 0 on success, -1 on errors. The shared-memory interface +close always returns 0, whereas a socket close can result in an error. +For a socket close error it will have set an errno from the call to the +system's <function>close()</function>. </para> + +<para><function>gps_send()</function> writes a command to the daemon. +It does nothing when using the shared-memory export. +The second argument must be a format string containing elements from +the command set documented at +<citerefentry><refentrytitle>gpsd</refentrytitle><manvolnum>1</manvolnum> +</citerefentry>. +It may have % elements as for +<citerefentry><refentrytitle>sprintf</refentrytitle><manvolnum>3</manvolnum> +</citerefentry>, +which will be filled in from any following arguments. This function +returns a -1 if there was a Unix-level write error, otherwise +0. Please read the LIMITATIONS section for additional information and +cautions. See <function>gps_stream()</function> as a possible +alternative.</para> + +<para><function>gps_read()</function> accepts a response, or sequence +of responses, from the daemon and interprets. This function does +either a nonblocking read for data from the daemon or a fetch from +shared memory; it returns a count of bytes read for success, -1 with +errno set on a Unix-level read error, -1 with errno not set if the +socket to the daemon has closed or if the shared-memory segment was +unavailable, and 0 if no data is available.</para> + +<para><function>gps_waiting()</function> can be used to check whether +there is new data from the daemon. The second argument is the maximum +amount of time to wait (in microseconds) on input before returning. +It returns true if there is input waiting, false on timeout (no data +waiting) or error condition. When using the socket export, this +function is a convenience wrapper around a +<citerefentry><refentrytitle>select</refentrytitle><manvolnum>2</manvolnum> +</citerefentry> +call, and zeros <varname>errno</varname> on entry; you can test +<varname>errno</varname> after exit to get more information about +error conditions. Warning: under the shared-memory interface there is +a tiny race window between <function>gps_waiting()</function> and a +following <function>gps_read()</function>; in that context, because the +latter does not block, it is probably better to write a simple read +loop.</para> + +<para><function>gps_mainloop()</function> enables the provided hook +function to be continually called whenever there is gpsd data. +The second argument is the maximum amount of time to wait (in microseconds) +on input before exiting the loop (and return a value of -1). +It will also return a negative value on various errors. +</para> + +<para><function>gps_unpack()</function> parses JSON from the argument +buffer into the target of the session structure pointer argument. +Included in case your application wishes to manage socket I/O +itself.</para> + +<para><function>gps_data()</function> returns the contents of the +client data buffer (it returns NULL when using the shared-memory +export). Use with care; this may fail to be a NUL-terminated string if +WATCH_RAW is enabled.</para> + +<para><function>gps_stream()</function> asks +<application>gpsd</application> to stream the reports it has at you, +to be made available when you poll (not available when using the +shared-memory export). The second argument is a flag mask that sets +various policy bits; see the list below. Calling +<function>gps_stream()</function> more than once with different flag +masks is allowed.</para> + +<variablelist> +<varlistentry> +<term>WATCH_DISABLE</term> +<listitem> +<para>Disable the reporting modes specified by the other WATCH_ flags.</para> +</listitem> +</varlistentry> +<varlistentry> +<term>WATCH_ENABLE</term> +<listitem> +<para>Disable the reporting modes specified by the other WATCH_ flags. +This is the default.</para> +</listitem> +</varlistentry> +<varlistentry> +<term>WATCH_JSON</term> +<listitem> +<para>Enable JSON reporting of data. If WATCH_ENABLE is set, and no +other WATCH flags are set, this is the default.</para> +</listitem> +</varlistentry> +<varlistentry> +<term>WATCH_NMEA</term> +<listitem> +<para>Enable generated pseudo-NMEA reporting on binary devices.</para> +</listitem> +</varlistentry> +<varlistentry> +<term>WATCH_RARE</term> +<listitem> +<para>Enable reporting of binary packets in encoded hex.</para> +</listitem> +</varlistentry> +<varlistentry> +<term>WATCH_RAW</term> +<listitem> +<para>Enable literal passthrough of binary packets.</para> +</listitem> +</varlistentry> +<varlistentry> +<term>WATCH_SCALED</term> +<listitem> +<para>When reporting AIS or Subframe data, scale integer quantities to +floats if they have a divisor or rendering formula associated with them.</para> +</listitem> +</varlistentry> +<varlistentry> +<term>WATCH_NEWSTYLE</term> +<listitem> +<para>Force issuing a JSON initialization and getting new-style +responses. This is the default. </para> +</listitem> +</varlistentry> +<varlistentry> +<term>WATCH_OLDSTYLE</term> +<listitem> +<para>Force issuing a W or R command and getting old-style +responses. Warning: this flag (and the capability) will be removed +in a future release.</para> +</listitem> +</varlistentry> +<varlistentry> +<term>WATCH_DEVICE</term> +<listitem> +<para>Restrict watching to a specified device, path given as second +argument.</para> +</listitem> +</varlistentry> +</variablelist> + +<para><function>gps_errstr()</function> returns an ASCII string (in +English) describing the error indicated by a nonzero return value from +<function>gps_open()</function>.</para> + +<para>Consult <filename>gps.h</filename> to learn more about the data +members and associated timestamps. Note that information will +accumulate in the session structure over time, and the 'valid' field +is not automatically zeroed by each <function>gps_read()</function>. +It is up to the client to zero that field when appropriate and to keep +an eye on the fix and sentence timestamps.</para> + +<para>The Python implementation supports the same facilities as the +socket-export calls in the C library; there is no shared-memory +interface. <function>gps_open()</function> is replaced by the +initialization of a gps session object; the other calls are methods of +that object, and have the same names as the corresponding C functions. +However, it is simpler just to use the session object as an iterator, +as in the example given below. Resources within the session object +will be properly released when it is garbage-collected.</para> +</refsect1> + +<refsect1 id='environment'><title>ENVIRONMENT VARIABLES</title> + +<para>By setting the environment variable <envar>GPSD_SHM_KEY</envar>, +you can control the key value used to create shared-memory segment +used for communication with <application>gpsd</application>. This +will be useful mainly when isolating test instances of +<application>gpsd</application> from production ones.</para> + +</refsect1> + +<refsect1 id='example'><title>CODE EXAMPLE</title> + +<para>The following is an excerpted and simplified version of the +libgps interface code from +<citerefentry><refentrytitle>cgps</refentrytitle><manvolnum>1</manvolnum> +</citerefentry>.</para> + +<programlisting> + struct gps_data_t gps_data; + + ret = gps_open(hostName, hostPort, &gps_data); + + (void) gps_stream(&gps_data, WATCH_ENABLE | WATCH_JSON, NULL); + + /* Put this in a loop with a call to a high resolution sleep () in it. */ + if (gps_waiting (&gps_data, 500)) { + errno = 0; + if (gps_read (&gps_data) == -1) { + ... + } else { + /* Display data from the GPS receiver. */ + if (gps_data.set & ... + } + } + + /* When you are done... */ + (void) gps_stream(&gps_data, WATCH_DISABLE, NULL); + (void) gps_close (&gps_data); +</programlisting> + +</refsect1> + +<refsect1 id='limitations'><title>LIMITATIONS</title> + +<para>On some systems (those which do not support implicit linking in +libraries) you may need to add -lm to your link line when you link libgps. +It is always safe to do this.</para> + +<para>In the C API, incautious use of <function>gps_send()</function> +may lead to subtle bugs. In order to not bloat <structname>struct +gps_data_t</structname> with space used by responses that are not +expected to be shipped in close sequence with each other, the storage +for fields associated with certain responses are combined in a +union.</para> + +<para>The risky set of responses includes VERSION, DEVICELIST, RTCM2, +RTCM3, SUBFRAME, AIS, GST, and ERROR; it may not be limited to that +set. The logic of the daemon's watcher mode is careful to avoid +dangerous sequences, but you should read and understand the layout of +<structname>struct gps_data_t</structname> before using +<function>gps_send()</function> to request any of these +responses.</para> + +</refsect1> + +<refsect1 id='compatibility'><title>COMPATIBILITY</title> + +<para>The <function>gps_query()</function> supported in major versions +1 and 2 of this library has been removed. With the new +streaming-oriented wire protocol behind this library, it is extremely +unwise to assume that the first transmission from the daemon after a +command is shipped to it will be the response to command.</para> + +<para>If you must send commands to the daemon explicitly, use +<function>gps_send()</function> but beware that this ties your code to +the GPSD wire protocol. It is not recommended.</para> + +<para>In earlier versions of the API <function>gps_read()</function> was +a blocking call and there was a POLL_NONBLOCK option to make it nonblocking. +<function>gps_waiting()</function> was added to reduce the number of +wrong ways to code a polling loop.</para> + +<para>See the comment above the symbol GPSD_API_MAJOR_VERSION +in <filename>gps.h</filename> for recent changes.</para> +</refsect1> + +<refsect1 id='see_also'><title>SEE ALSO</title> +<para> +<citerefentry><refentrytitle>gpsd</refentrytitle><manvolnum>8</manvolnum> +</citerefentry>, +<citerefentry><refentrytitle>gps</refentrytitle><manvolnum>1</manvolnum> +</citerefentry>, +<citerefentry><refentrytitle>libgpsmm</refentrytitle><manvolnum>3</manvolnum> +</citerefentry>. +</para> +</refsect1> + +<refsect1 id='author'><title>AUTHOR</title> +<para>Eric S. Raymond <esr@thyrsus.com>, + C sample code Charles Curley <charlescurley@charlescurley.com></para> +</refsect1> +</refentry> + diff --git a/man/libgpsmm.xml b/man/libgpsmm.xml new file mode 100644 index 00000000..cfcc9d35 --- /dev/null +++ b/man/libgpsmm.xml @@ -0,0 +1,83 @@ +<?xml version="1.0" encoding="ISO-8859-1"?> +<!-- +This file is Copyright (c) 2010 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"> +<refentry> +<refentryinfo><date>13 May 2005</date></refentryinfo> +<refmeta> +<refentrytitle>libgpsmm</refentrytitle> +<manvolnum>3</manvolnum> +<refmiscinfo class="source">The GPSD Project</refmiscinfo> +<refmiscinfo class="manual">GPSD Documentation</refmiscinfo> +</refmeta> +<refnamediv id='name'> +<refname>libgpsmm</refname> +<refname>libQgpsmm</refname> +<refpurpose>C++ and QT class wrapper for the GPS daemon</refpurpose> +</refnamediv> +<refsynopsisdiv id='synopsis'> +<funcsynopsis> +<funcsynopsisinfo> + +C++: + +#include <libgpsmm> + +</funcsynopsisinfo> +<funcprototype> +<funcdef>struct gps_data_t *<function>open</function></funcdef> + <paramdef>char *<parameter>host</parameter></paramdef> + <paramdef>char *<parameter>port</parameter></paramdef> +</funcprototype> +<funcprototype> +<funcdef>struct gps_data_t *<function>open</function></funcdef> + <paramdef>void</paramdef> +</funcprototype> +<funcprototype> +<funcdef>struct gps_data_t *<function>send</function></funcdef> + <paramdef>char *<parameter>request</parameter></paramdef> +</funcprototype> +<funcprototype> +<funcdef>struct gps_data_t *<function>read</function></funcdef> + <paramdef>void</paramdef> +</funcprototype> +<funcprototype> +<funcdef>struct gps_data_t *<function>waiting</function></funcdef> + <paramdef>int</paramdef> +</funcprototype> +<funcprototype> +<funcdef>struct gps_data_t *<function>stream</function></funcdef> + <paramdef>unsigned int<parameter>flags</parameter></paramdef> +</funcprototype> +</funcsynopsis> +</refsynopsisdiv> + +<refsect1 id='description'><title>DESCRIPTION</title> + +<para><emphasis remap='B'>libgpsmm and libQgpsmm</emphasis> are mere wrappers over +<emphasis remap='B'>libgps</emphasis>. The important difference between the libraries is that libgpsmm is targeted at C++ applications and contained in <emphasis remap='B'>libgps</emphasis>, while libQgpsmm is platform independent by using QTcpSocket to connect to <emphasis remap='B'>gpsd</emphasis> and shipped as an additional library due to the necessary linking to QT. +Method names are the same as +the analogue C functions. For a detailed description of the functions +please read +<citerefentry><refentrytitle>libgps</refentrytitle><manvolnum>3</manvolnum></citerefentry>. +<function>open()</function> must be called after class constructor and before any other method +(<function>open()</function> is not inside the constructor since it may fail, however constructors have no return value). +The analogue of the C function <function>gps_close()</function> is in the destructor.</para> +</refsect1> + +<refsect1 id='see_also'><title>SEE ALSO</title> +<para> +<citerefentry><refentrytitle>gpsd</refentrytitle><manvolnum>8</manvolnum></citerefentry>, +<citerefentry><refentrytitle>gps</refentrytitle><manvolnum>1</manvolnum></citerefentry>, +<citerefentry><refentrytitle>libgps</refentrytitle><manvolnum>3</manvolnum></citerefentry>. +</para> +</refsect1> + +<refsect1 id='author'><title>AUTHOR</title> +<para>Alfredo Pironti <alfredio@users.sourceforge.net>.</para> +</refsect1> +</refentry> + diff --git a/man/ntpshmmon.xml b/man/ntpshmmon.xml new file mode 100644 index 00000000..bcb083a3 --- /dev/null +++ b/man/ntpshmmon.xml @@ -0,0 +1,165 @@ +<?xml version="1.0" encoding="ISO-8859-1"?> +<!-- +This file is Copyright (c) 2010 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"> +<refentry id='ntpshmmon.1'> +<refentryinfo><date>25 Jan 2015</date></refentryinfo> +<refmeta> +<refentrytitle>ntpshmmon</refentrytitle> +<manvolnum>1</manvolnum> +<refmiscinfo class="source">The GPSD Project</refmiscinfo> +<refmiscinfo class="manual">GPSD Documentation</refmiscinfo> +</refmeta> +<refnamediv id='name'> +<refname>ntpshmmon</refname> +<refpurpose>capture samples from GPS or other ntpd refclock sources</refpurpose> +</refnamediv> +<refsynopsisdiv id='synopsis'> + +<cmdsynopsis> + <command>ntpshmmon</command> + <arg choice='opt'>-h </arg> + <arg choice='opt'>-n <replaceable>nsamples</replaceable></arg> + <arg choice='opt'>-s </arg> + <arg choice='opt'>-t <replaceable>seconds</replaceable></arg> + <arg choice='opt'>-v </arg> + <arg choice='opt'>-V </arg> +</cmdsynopsis> +</refsynopsisdiv> + +<refsect1 id='description'><title>DESCRIPTION</title> + +<para>This program monitors the shared-memory segments updated by +<citerefentry><refentrytitle>gpsd</refentrytitle><manvolnum>8</manvolnum></citerefentry> +(and possibly other refclock sources) as a way of communicating with +ntpd, the Network Time Protocol daemon. It reads these in exactly the way an +ntpd instance does. It can be run concurrently with ntpd without +interfering with ntpd's normal operation.</para> + +<para>This program runs forever, or until a termination option is +matched, or until interrupted, generating sample reports to standard +output. Each line consists of whitespace-separated textual +fields.</para> + +<para>Here is an example of the beginning of a report file: + +<screen> +ntpshmmon version 1 +# Name Seen@ Clock Real L Prec +sample NTP2 1424926256.443030206 1424926256.115869233 1424926256.000000000 0 -1 +sample NTP3 1424926256.443060517 1424926255.995430821 1424926256.000000000 0 -20 +sample NTP3 1424926256.995747347 1424926256.995422728 1424926257.000000000 0 -20 +sample NTP2 1424926257.112433572 1424926257.111936726 1424926257.000000000 0 -1 +sample NTP3 1424926257.996221153 1424926257.995410232 1424926258.000000000 0 -20 +sample NTP2 1424926258.107769409 1424926258.107451006 1424926258.000000000 0 -1 +sample NTP3 1424926258.995647636 1424926258.995406476 1424926259.000000000 0 -20 +</screen></para> + +<para>The output always begins with a header line expressing the +version of the output format; the version line begins with "ntpshmmon +version" and is followed by a numeric version field.</para> + +<para>The remainder of the file is either commments or sample lines. A +comment line begins with a # and should ignored by programs that +interpret this format.</para> + +<para>The fields of a sample line are as follows: + +<orderedlist> +<listitem><para>The keyword "sample"</para></listitem> + +<listitem><para>The NTP unit from which it was collected.</para></listitem> + +<listitem><para>Collection time of day, seconds.</para></listitem> + +<listitem><para>Receiver time of day, seconds.</para></listitem> + +<listitem><para>Clock time of day, seconds.</para></listitem> + +<listitem><para>Leap-second notification status.</para></listitem> + +<listitem><para>Source precision (log(2) of source jitter).</para></listitem> +</orderedlist> +</para> + +<para>In these fields, "clock time" is the high-precision time +measured by the source and "receiver time" is Unix UTC time at the +receiver. It is normal for the seconds part of receiver time to +coincide with the seconds part of collection time and for the +nanoseconds part of receiver time to be zero.</para> + +<variablelist> +<varlistentry> +<term>-v</term> +<listitem> +<para>Enable verbose status messages.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>-c</term> +<listitem> +<para>Device poll interval in fractional seconds - defaults to 1.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>-n</term> +<listitem> +<para>Set maximum number of samples to collect.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>-s</term> +<listitem> +<para>Remove all SHM segments used by GPSD. This +option will normally only be of interest to GPSD developers.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>-t</term> +<listitem> +<para>Set maximum time to collect samples in seconds.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>-h</term> +<listitem> +<para>Display program usage and exit.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>-V</term> +<listitem> +<para>Display program version and exit.</para> +</listitem> +</varlistentry> +</variablelist> + +</refsect1> + +<refsect1 id='see_also'><title>SEE ALSO</title> +<para> +<citerefentry><refentrytitle>gpsd</refentrytitle><manvolnum>8</manvolnum></citerefentry>, +<citerefentry><refentrytitle>gpsdctl</refentrytitle><manvolnum>8</manvolnum></citerefentry>, +<citerefentry><refentrytitle>gps</refentrytitle><manvolnum>1</manvolnum></citerefentry>, +<citerefentry><refentrytitle>libgps</refentrytitle><manvolnum>3</manvolnum></citerefentry>, +<citerefentry><refentrytitle>libgpsmm</refentrytitle><manvolnum>3</manvolnum></citerefentry>, +<citerefentry><refentrytitle>gpsprof</refentrytitle><manvolnum>1</manvolnum></citerefentry>, +<citerefentry><refentrytitle>gpsfake</refentrytitle><manvolnum>1</manvolnum></citerefentry>. +</para> +</refsect1> + +<refsect1 id='maintainer'><title>AUTHOR</title> + +<para>Eric S. Raymond <email>esr@thyrsus.com</email>.</para> +</refsect1> +</refentry> diff --git a/man/ppscheck.xml b/man/ppscheck.xml new file mode 100644 index 00000000..8a5bdc12 --- /dev/null +++ b/man/ppscheck.xml @@ -0,0 +1,103 @@ +<?xml version="1.0" encoding="ISO-8859-1"?> +<!-- +This file is Copyright (c) 2016 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"> +<refentry id='ppscheck.8'> +<refentryinfo><date>28 Jul 2016</date></refentryinfo> +<refmeta> +<refentrytitle>ppscheck</refentrytitle> +<manvolnum>8</manvolnum> +<refmiscinfo class="source">The GPSD Project</refmiscinfo> +<refmiscinfo class="manual">GPSD Documentation</refmiscinfo> +</refmeta> +<refnamediv id='name'> +<refname>ppscheck</refname> +<refpurpose>tool to check a serial port for PPS</refpurpose> +</refnamediv> +<refsynopsisdiv id='synopsis'> + +<cmdsynopsis> + <command>ppscheck</command> + <arg choice='opt'>-h </arg> + <arg choice='opt'>-V </arg> + <arg choice='plain'><replaceable>device</replaceable></arg> +</cmdsynopsis> +</refsynopsisdiv> + +<refsect1 id='description'><title>DESCRIPTION</title> + +<para>ppscheck watches a specified serial port for transitions that +might be PPS. It looks for changes in handshake lines CD, RI, and CTS +by running ioctl(...., TIOCMIWAIT, ...) in a loop. When it sees a state +change it emits a timestamped line of output dumping the state of the +handshake signals. It's useful for checking whether a device is emitting +PPS.</para> + +<para>To check the first serial port do this:</para> + +<programlisting> +ppscheck /dev/ttyS0 +</programlisting> + +<para>ppscheck is not intended for routine use, but rather for +diagnostic purposes. Once you have verified a particular device can +output PPS signals you will never need to use it again on that device. +</para> + +<para>The program accepts the following options:</para> +<variablelist remap='TP'> +<varlistentry> +<term>-h</term> +<listitem><para>Display help message and terminate.</para></listitem> +</varlistentry> +<varlistentry> +<term>-V</term> +<listitem> +<para>Dump version and exit.</para> +</listitem> +</varlistentry> +</variablelist> + +<para>The "device" argument should be the pathname of a device. It will +be the device monitored. </para> + +<para>Each output line is the second and nanosecond parts of a timestamp +followed by the names of the handshake signals then asserted. Off +transitions may generate lines with no signals aserted. </para> + +<para>If you don't see output within a second, use gpsmon or some other +equivalent tool to check that your device has a satellite lock and is +getting 3D fixes before giving up on the possibility of PPS. </para> + +<para>Check your cable. Cheap DB9 to DB9 cables such as those issued +with UPSes often carry TXD/RXD/GND only, omitting handshake lines such +as DCD. Suspect this especially if the cable jacket looks too skinny to +hold more than three leads! </para> + +<para>Most GPS that have built in USB do not support PPS. When in doubt, +contact the vendor for confirmation that your device does supply PPS. +</para> + +</refsect1> + +<refsect1 id='exit_status'><title>RETURN VALUES</title> + +<para>1 if the device counld not be opened. 0 otherwise</para> + +</refsect1> + +<refsect1 id='see_also'><title>SEE ALSO</title> +<para> +<citerefentry><refentrytitle>gpsd</refentrytitle><manvolnum>8</manvolnum></citerefentry>. +</para> +</refsect1> + +<refsect1 id='maintainer'><title>AUTHOR</title> + +<para>Eric S. Raymond <email>esr@thyrsus.com</email>.</para> +</refsect1> +</refentry> diff --git a/man/srec.xml b/man/srec.xml new file mode 100644 index 00000000..0e4e5be8 --- /dev/null +++ b/man/srec.xml @@ -0,0 +1,308 @@ +<?xml version="1.0" encoding="ISO-8859-1"?> +<!-- +This file is Copyright (c) 2010 by the GPSD project +BSD terms apply: see the file COPYING in the distribution root for -details. +--> +<!DOCTYPE refentry PUBLIC + "-//OASIS//DTD DocBook XML V4.1.2//EN" + "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"> +<refentry id='srec.5'> +<refentryinfo><date>15 Jul 2005</date></refentryinfo> +<refmeta> +<refentrytitle>srec</refentrytitle> +<manvolnum>5</manvolnum> +<refmiscinfo class="source">The GPSD Project</refmiscinfo> +<refmiscinfo class="manual">GPSD Documentation</refmiscinfo> +</refmeta> +<refnamediv id='name'> +<refname>srec</refname> +<refpurpose>Motorola S-record record and file format</refpurpose> +</refnamediv> +<refsect1 id='description'><title>DESCRIPTION</title> + +<para>Motorola S-records are a form of simple ASCII encoding for +binary data. This format is commonly used for firmware uploads to +GPSes, industrial robots, and other kinds of microcontroller-driven +hardware. It has several convenient properties, including +inspectability, easy editing with any text editor, and checksumming +for verification of transmission across noisy serial lines.</para> + +<para>An S-record file consists of a sequence of specially formatted +ASCII character strings. An S-record will be less than or equal to 78 +bytes in length.</para> + +<para>The order of S-records within a file is of no significance and +no particular order may be assumed.</para> + +<para>The general format of an S-record follows:</para> + +<screen> ++-------------------//------------------//-----------------------+ +| type | count | address | data | checksum | ++-------------------//------------------//-----------------------+ +</screen> + +<variablelist> +<varlistentry> +<term>type</term> +<listitem><para>A char[2] field. These characters +describe the type of record (S0, S1, S2, S3, S5, S7, S8, or +S9).</para></listitem> +</varlistentry> + +<varlistentry> +<term>count</term> +<listitem><para>A char[2] field. These characters when paired and +interpreted as a big-endian hexadecimal integer, display the count of remaining +character pairs in the record.</para></listitem> +</varlistentry> + +<varlistentry> +<term>address</term> +<listitem><para>A char[4,6, or 8] field. These characters grouped and +interpreted as a big-endian hexadecimal integer, display the address +at which the data field is to be loaded into memory. The length of the +field depends on the number of bytes necessary to hold the address. A +2-byte address uses 4 characters, a 3-byte address uses 6 characters, +and a 4-byte address uses 8 characters.</para></listitem> +</varlistentry> + +<varlistentry> +<term>data</term> +<listitem><para>A char [0-64] field. These characters when paired and +interpreted as hexadecimal values represent the memory loadable data +or descriptive information.</para></listitem> +</varlistentry> + +<varlistentry> +<term>checksum</term> +<listitem><para>A char[2] field. These characters when paired and +interpreted as a big-endian hexadecimal integer display the least +significant byte of the ones complement of the sum of the byte values +represented by the pairs of characters making up the count, the +address, and the data fields.</para></listitem> +</varlistentry> +</variablelist> + +<para>Each record is terminated with a line feed. If any additional or +different record terminator(s) or delay characters are needed during +transmission to the target system it is the responsibility of the +transmitting program to provide them.</para> + +<para>There are 9 record types, as follows:</para> + +<variablelist> +<varlistentry> +<term>S0</term> +<listitem> +<para>The type of record is 'S0' (0x5330). The address field +is unused and will be filled with zeros (0x0000). The header +information within the data field is divided into the following +subfields.</para> + +<orderedlist> +<listitem><para>mname is char[20] and is the module name.</para></listitem> +<listitem><para>ver is char[2] and is the version number.</para></listitem> +<listitem><para>rev is char[2] and is the revision number.</para></listitem> +<listitem><para>description is char[0-36] and is a text comment.</para></listitem> +</orderedlist> + +<para>Each of the subfields is composed of ASCII bytes whose +associated characters, when paired, represent one byte hexadecimal +values in the case of the version and revision numbers, or represent +the hexadecimal values of the ASCII characters comprising the module +name and description.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>S1</term> +<listitem><para>The type of record field is 'S1' (0x5331). The address +field is interpreted as a 2-byte big-endian address. The data field is +composed of memory loadable data.</para></listitem> +</varlistentry> + +<varlistentry> +<term>S2</term> +<listitem><para>The type of record field is 'S2' (0x5332). The address +field is interpreted as a 3-byte big-endian address. The data field is +composed of memory loadable data.</para></listitem> +</varlistentry> + +<varlistentry> +<term>S3</term> +<listitem><para>The type of record field is 'S3' (0x5333). The address +field is interpreted as a 4-byte big-endian address. The data field is +composed of memory loadable data.</para></listitem> +</varlistentry> + +<varlistentry> +<term>S5</term> +<listitem><para>The type of record field is 'S5' (0x5335). The address +field is interpreted as a 2-byte big-endian value and contains the +count of S1, S2, and S3 records previously transmitted. There is no +data field.</para></listitem> +</varlistentry> + +<varlistentry> +<term>S7</term> +<listitem><para>The type of record field is 'S7' (0x5337). The address +field contains the starting execution address and is interpreted as a +4-byte big-endian address. There is no data field.</para></listitem> +</varlistentry> + +<varlistentry> +<term>S8</term> +<listitem><para>The type of record field is 'S8' (0x5338). The address +field contains the starting execution address and is interpreted as a +3-byte big-endian address. There is no data field.</para></listitem> +</varlistentry> + +<varlistentry> +<term>S9</term> +<listitem><para>The type of record field is 'S9' (0x5339). The address +field contains the starting execution address and is interpreted as a +2-byte big-endian address. There is no data field.</para></listitem> +</varlistentry> +</variablelist> + +</refsect1> +<refsect1 id='example'><title>EXAMPLE</title> + +<para>Shown below is a typical S-record format file.</para> + +<programlisting> + S00600004844521B + S1130000285F245F2212226A000424290008237C2A + S11300100002000800082629001853812341001813 + S113002041E900084E42234300182342000824A952 + S107003000144ED492 + S5030004F8 + S9030000FC +</programlisting> + +<para>The file consists of one S0 record, four S1 records, one S5 +record and an S9 record.</para> + +<para>The S0 record is comprised as follows:</para> + +<itemizedlist> +<listitem><para>S0 S-record type S0, indicating it is a header +record.</para></listitem> + +<listitem><para>06 Hexadecimal 06 (decimal 6), indicating that six +character pairs (or ASCII bytes) follow.</para></listitem> + +<listitem><para>00 00 Four character 2-byte address field, zeroes in +this example.</para></listitem> + +<listitem><para>48 44 52 ASCII H, D, and R - "HDR".</para></listitem> + +<listitem><para>1B The checksum.</para></listitem> +</itemizedlist> + +<para> The first S1 record is comprised as follows:</para> + +<itemizedlist> +<listitem><para>S1 S-record type S1, indicating it is a data record to +be loaded at a 2-byte address.</para></listitem> + +<listitem><para>13 Hexadecimal 13 (decimal 19), indicating that +nineteen character pairs, representing a 2 byte address, 16 bytes of +binary data, and a 1 byte checksum, follow. </para></listitem> + +<listitem><para>00 00 Four character 2-byte address field; hexidecimal +address 0x0000, where the data which follows is to be +loaded.</para></listitem> + +<listitem><para>28 5F 24 5F 22 12 22 6A 00 04 24 29 00 08 23 7C +Sixteen character pairs representing the actual binary data. +</para></listitem> + +<listitem><para>2A The checksum.</para></listitem> +</itemizedlist> + +<para>The second and third S1 records each contain 0x13 (19) character +pairs and are ended with checksums of 13 and 52, respectively. The +fourth S1 record contains 07 character pairs and has a checksum of +92.</para> + +<para>The S5 record is comprised as follows:</para> + +<itemizedlist> +<listitem><para>S5 S-record type S5, indicating it is a count record +indicating the number of S1 records </para></listitem> + +<listitem><para>03 Hexadecimal 03 (decimal 3), indicating that three +character pairs follow.</para></listitem> + +<listitem><para>00 04 Hexadecimal 0004 (decimal 4), indicating that +there are four data records previous to this record.</para></listitem> + +<listitem><para>F8 The checksum.</para></listitem> +</itemizedlist> + + +<para>The S9 record is comprised as follows:</para> + +<itemizedlist> +<listitem><para>S9 S-record type S9, indicating it is a termination +record.</para></listitem> + +<listitem><para>03 Hexadecimal 03 (decimal 3), indicating that three +character pairs follow. </para></listitem> + +<listitem><para>00 00 The address field, hexadecimal 0 (decimal 0) +indicating the starting execution address. </para></listitem> + +<listitem><para>FC The checksum.</para></listitem> +</itemizedlist> + +</refsect1> +<refsect1 id='notes'><title>NOTES</title> + +<itemizedlist> + <listitem><para> There isn't any evidence that Motorola ever + made use of the header information within the data field of the S0 + record, as described above. This may have been used by some third + party vendors.</para></listitem> + +<listitem><para>The Unix manual page on S-records is the only place that a + 78-byte limit on total record length or 64-byte limit on data + length is documented. These values shouldn't be trusted for the + general case.</para></listitem> + +<listitem><para> The count field can have values in the range of 0x3 + (2 bytes of address + 1 byte checksum = 3, a not very useful + record) to 0xff; this is the count of remaining character + <emphasis>pairs</emphasis>, including checksum. </para></listitem> + +<listitem><para> If you write code to convert S-Records, you should + always assume that a record can be as long as 514 (decimal) + characters in length (255 * 2 = 510, plus 4 characters for the + type and count fields), plus any terminating character(s). That + is, in establishing an input buffer in C, you would declare it to + be an array of 515 chars, thus leaving room for the terminating + null character. </para></listitem> +</itemizedlist> + +</refsect1> +<refsect1 id='see_also'><title>SEE ALSO</title> +<para> +<citerefentry><refentrytitle>gpsd</refentrytitle><manvolnum>8</manvolnum></citerefentry>, +<citerefentry><refentrytitle>gps</refentrytitle><manvolnum>1</manvolnum></citerefentry>, +<citerefentry><refentrytitle>libgps</refentrytitle><manvolnum>3</manvolnum></citerefentry>, +<citerefentry><refentrytitle>libgpsmm</refentrytitle><manvolnum>3</manvolnum></citerefentry>, +<citerefentry><refentrytitle>gpsfake</refentrytitle><manvolnum>1</manvolnum></citerefentry>. +<citerefentry><refentrytitle>gpsprof</refentrytitle><manvolnum>1</manvolnum></citerefentry>. +</para> +</refsect1> + +<refsect1 id='maintainer'><title>AUTHOR</title> + +<para>From an anonymous web page, itself claiming to have been derived +from an old Unix manual page. Now maintained by the GPSD +project, which added endianness clarifications.</para> + +</refsect1> +</refentry> diff --git a/man/ubxtool.xml b/man/ubxtool.xml new file mode 100644 index 00000000..493f72ab --- /dev/null +++ b/man/ubxtool.xml @@ -0,0 +1,458 @@ +<?xml version="1.0" encoding="ISO-8859-1"?> +<!-- +This file is Copyright (c) 2018 by the GPSD project +BSD terms apply: see the file COPYING in the distribution root for details. +--> +<!DOCTYPE refentry PUBLIC + "-//OASIS//DTD DocBook XML V4.1.2//EN" + "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"> +<refentry id='ubxtool.1'> + <refentryinfo> + <date>24 Sep 2018</date> + </refentryinfo> + <refmeta> + <refentrytitle>ubxtool</refentrytitle> + <manvolnum>1</manvolnum> + <refmiscinfo class="source">The GPSD Project</refmiscinfo> + <refmiscinfo class="manual">GPSD Documentation</refmiscinfo> + </refmeta> + <refnamediv id='name'> + <refname>ubxtool</refname> + <refpurpose>u-blox tool</refpurpose> + </refnamediv> + <refsynopsisdiv id='synopsis'> + <cmdsynopsis> + <command>ubxtool</command> + <arg choice='opt'>-? </arg> + <arg choice='opt'>-c <replaceable>command</replaceable> + </arg> + <arg choice='opt'>-d <replaceable>disable</replaceable> + </arg> + <arg choice='opt'>-e <replaceable>enable</replaceable> + </arg> + <arg choice='opt'>-f <replaceable>file/device</replaceable> + </arg> + <arg choice='opt'>-h </arg> + <arg choice='opt'>-m <replaceable>mode</replaceable></arg> + <arg choice='opt'>-P <replaceable>protver</replaceable></arg> + <arg choice='opt'>-p <replaceable>preset</replaceable></arg> + <arg choice='opt'>-R <replaceable>rawfile</replaceable></arg> + <arg choice='opt'>-r </arg> + <arg choice='opt'>-S <replaceable>setspeed</replaceable></arg> + <arg choice='opt'>-s <replaceable>speed</replaceable></arg> + <arg choice='opt'>-V </arg> + <arg choice='opt'>-v <replaceable>verbosity</replaceable></arg> + <arg choice='opt'>-w <replaceable>wait</replaceable></arg> + <arg choice='opt'>[server[:port[:device]]]</arg> + </cmdsynopsis> + </refsynopsisdiv> + <refsect1 id='description'> + <title>DESCRIPTION</title> + <para> + <application>ubxtool</application> is a tool for u-blox GPS. +If you do not have a u-blox GPS then can stop reading now.</para> + <para>This tool operates with your u-blox GPS at a very low level. +To understand <application>ubxtool</application> you must first be familiar +with your u-blox GPS and the documentation for the u-blox binary protocol. +The u-blox protocol varies greatly depending o GPS model and firmware +revision. +</para> + <para> + <application>ubxtool</application> can decode common u-blox binary + messages, poll the GPS status, enable and disable GPS features, and send user +generated commands to the GPS. It can read binary messages from a file. It +can read and write directly through a serial device, or through a +running gpsd instance.</para> + </refsect1> + <refsect1 id='options'> + <title>OPTIONS</title> + <para>The program accepts the following options:</para> + <variablelist remap='TP'> + <varlistentry> + <term>-c COMMAND</term> + <listitem> + <para>Send a text string to the GPS. Accepts one parameter, COMMAND, +the command string to send to the GPS. The string is sent verbatim, except +a newline is appended. +</para> + </listitem> + </varlistentry> + <varlistentry> + <term>-d OPTION</term> + <listitem> + <para>Disable an option in the GPS. Accepts one parameter, OPTION, +the option to disable. +</para> + <variablelist> + <varlistentry> + <term>BEIDOU</term> + <listitem> + <para>Disable use of the BeiDou (COMPASS) constellation.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>BINARY</term> + <listitem> + <para>Disable sending of the basic binary messages.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>ECEF</term> + <listitem> + <para>Disable sending of ECEF binary messages.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>GALILEO</term> + <listitem> + <para>Disable use of the GALILEO constellation.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>GLONASS</term> + <listitem> + <para>Disable use of the GLONASS constellation.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>GPS</term> + <listitem> + <para>Disable use of the GPS and QZSS constellations.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>NMEA</term> + <listitem> + <para>Disable sending basic NMEA messages. The messages are +GBS, GGA, GSA, GGL, GST, GSV, RMC, VTG, and ZDA.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>RAWX</term> + <listitem> + <para>Disable sending of the UBX-RXM-RAWX messages.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>SBAS</term> + <listitem> + <para>Disable use of the SBAS constellation.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>TMODE2</term> + <listitem> + <para>Disable sending TMODE2.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>TP</term> + <listitem> + <para>Disable sending UBX-TIM-TP.</para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + <varlistentry> + <term>-e OPTION</term> + <listitem> + <para>Enable an option in the GPS. Accepts one parameter, OPTION, +the option to enable. -e accepts the same OPTIONs as -d, except the action +is to enable the option. +</para> + </listitem> + </varlistentry> + <varlistentry> + <term>-f FILE</term> + <listitem> + <para>Connect to a file or device. Accepts one parameter, FILE, +the file or device to open. Files are opened read-only. Character +devices are opened red/write, unless the -r parameter is given. +</para> + </listitem> + </varlistentry> + <varlistentry> + <term>-h</term> + <listitem> + <para>Makes <application>ubxtool</application> print +a usage message and exit.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>-m mode</term> + <listitem> + <para>Sets optional mode parameter to a -p PRESET command. +</para> + </listitem> + </varlistentry> + <varlistentry> + <term>-P protver</term> + <listitem> + <para>Sets the protocol version to use for sending commands. Minimum +10 (ublox 5). Maximum 27 (u-blox 9) +</para> + </listitem> + </varlistentry> + <varlistentry> + <term>-p PRESET</term> + <listitem> + <para>Send a preset command the GPS. Accepts one parameter, PRESET, +the name of the command to send. <application>ubxtool</application> will exit +after the GPS acknowledges the command, unless the -W is given. +</para> + <variablelist> + <varlistentry> + <term>ANT</term> + <listitem> + <para>Poll the antenna configuration (UBX-CFG-ANT).</para> + </listitem> + </varlistentry> + <varlistentry> + <term>COLDBOOT</term> + <listitem> + <para>Coldboot the GPS (UBX-CFG-RST).</para> + </listitem> + </varlistentry> + <varlistentry> + <term>GNSS</term> + <listitem> + <para>Poll the enabled constellations (UBX-CFG-GNSS).</para> + </listitem> + </varlistentry> + <varlistentry> + <term>HOTBOOT</term> + <listitem> + <para>Hotboot the GPS (UBX-CFG-RST).</para> + </listitem> + </varlistentry> + <varlistentry> + <term>MODEL</term> + <listitem> + <para>Configure the Dynamic Platform Model. (UBX-CFG-NAV5). +</para> + </listitem> + </varlistentry> + <varlistentry> + <term>NAV5</term> + <listitem> + <para>Poll the Nav Engines settings (UBX-CFG-NAV6.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>RXM-RAWX</term> + <listitem> + <para>Poll UBX-RXM-RAWX message.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>RESET</term> + <listitem> + <para>Reset configuration to defaults (UBX-CFG-CFG).</para> + </listitem> + </varlistentry> + <varlistentry> + <term>SAVE</term> + <listitem> + <para>Save current configuration (UBX-CFG-CFG).</para> + </listitem> + </varlistentry> + <varlistentry> + <term>SVIN</term> + <listitem> + <para>Poll survey in data (UBX-CFG-SVIN).</para> + </listitem> + </varlistentry> + <varlistentry> + <term>TMODE2</term> + <listitem> + <para>Poll Time Mode 2 configuration (UBX-CFG-TMODE2).</para> + </listitem> + </varlistentry> + <varlistentry> + <term>TP</term> + <listitem> + <para>Poll time pulse timedata (UBX-TIM-TP).</para> + </listitem> + </varlistentry> + <varlistentry> + <term>TP5</term> + <listitem> + <para>Get Time Pulse decodes (UBX-TIM-TP5).</para> + </listitem> + </varlistentry> + <varlistentry> + <term>VER</term> + <listitem> + <para>Poll GPS version.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>WARMBOOT</term> + <listitem> + <para>Warmboot the GPS (UBX-CFG-RST).</para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + <varlistentry> + <term>-R RAW</term> + <listitem> + <para>Save all raw data from the GPS into the file RAW.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>-r</term> + <listitem> + <para>Read only. Do not send anything to the GPS.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>-S SPEED</term> + <listitem> + <para>Set the GPS serial port speed to SPEED bps.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>-s SPEED</term> + <listitem> + <para>Set local serial port speed to SPEED bps. Default 115,200 bps.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>-V</term> + <listitem> + <para>Print <application>ubxtool</application> version and exit.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>-v VERBOSITY</term> + <listitem> + <para>Set verbosity level to VERBOSITY. Verbosity can be from 0 + (very quiet), to 4 (very noisy). Default 2.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>-v VERBOSITY</term> + <listitem> + <para>Set verbosity level to VERBOSITY. Verbosity can be from 0 + (very quiet), 2 (decode messages), to 4 (very noisy). Default 1.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>-w WAIT</term> + <listitem> + <para>Wait for WAIT seconds before exiting. Will exit early on command +completion of -d, -e or -p command, unless -W is given. Default 2.0 second.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>-?</term> + <listitem> + <para>Makes <application>ubxtool</application> print +a usage message and exit.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>[server[:port[:device]]]</term> + <listitem> + <para> + By default, <application>ubxtool</application> collects data + from all compatible devices on localhost, using the default GPSD + port 2947. An optional argument may specify a server to get data + from. A colon-separated suffix is taken as a port number. If + there is a second colon-separated suffix, that is taken as a + specific device name to be watched. Further details on the +<citerefentry> + <refentrytitle>gps</refentrytitle> + <manvolnum>1</manvolnum> + </citerefentry> man page. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + <refsect1 id='environment'> + <title>ENVIRONMENT</title> + <para>Options can be placed in the UBXOPTS environment variable. +UBXOPTS is processed before the CLI options.</para> + </refsect1> + <refsect1 id='examples'> + <title>EXAMPLES</title> + <para> +Decode raw log file: +<programlisting> +ubxtool -r -f ublox-neo-m8n.log +</programlisting> + </para> + <para> +Change GPS port speed of device on /dev/ttyAMA0 to 230,400 bps:: +<programlisting> +ubxtool -S 230400 -f /dev/ttyAMA0 +</programlisting> + </para> + <para> +Watch entire GPS reset cycle, include $GPTXT messages: +<programlisting> +ubxtool -p COLDBOOT -w 20 -v 2 +</programlisting> + </para> + <para> +Poll Enabled Constellations: +<programlisting> +ubxtool -p GNSS +</programlisting> +Dump gpsd data from remote server: +<programlisting> +ubxtool -w 5 server +</programlisting> + </para> + </refsect1> + <refsect1 id='see_also'> + <title>SEE ALSO</title> + <para> + <application>ubxtool</application> is written to conform to the official +u-blox documentation for the u-blox binary protocol. +<ulink url="https://www.u-blox.com/en/product-resources"></ulink></para> + <para> + <citerefentry> + <refentrytitle>gpsd</refentrytitle> + <manvolnum>8</manvolnum> + </citerefentry>, +<citerefentry> + <refentrytitle>gps</refentrytitle> + <manvolnum>1</manvolnum> + </citerefentry>, +<citerefentry> + <refentrytitle>cgps</refentrytitle> + <manvolnum>1</manvolnum> + </citerefentry>, +<citerefentry> + <refentrytitle>xgps</refentrytitle> + <manvolnum>1</manvolnum> + </citerefentry>, +<citerefentry> + <refentrytitle>gpsfake</refentrytitle> + <manvolnum>1</manvolnum> + </citerefentry>, +<citerefentry> + <refentrytitle>gpsctl</refentrytitle> + <manvolnum>1</manvolnum> + </citerefentry>, +<citerefentry> + <refentrytitle>gpscat</refentrytitle> + <manvolnum>1</manvolnum> + </citerefentry>, +<citerefentry> + <refentrytitle>gnuplot</refentrytitle> + <manvolnum>1</manvolnum> + </citerefentry>. +</para> + </refsect1> + <refsect1 id='maintainer'> + <title>AUTHOR</title> + <para>Gary E. Miller<email>gem@rellim.com</email> + </para> + </refsect1> +</refentry> diff --git a/man/zerk.xml b/man/zerk.xml new file mode 100644 index 00000000..e82d5c71 --- /dev/null +++ b/man/zerk.xml @@ -0,0 +1,468 @@ +<?xml version="1.0" encoding="ISO-8859-1"?> +<!-- +This file is Copyright (c) 2018 by the GPSD project +BSD terms apply: see the file COPYING in the distribution root for details. +--> +<!DOCTYPE refentry PUBLIC + "-//OASIS//DTD DocBook XML V4.1.2//EN" + "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"> +<refentry id='zerk.1'> + <refentryinfo> + <date>18 Sep 2018</date> + </refentryinfo> + <refmeta> + <refentrytitle>zerk</refentrytitle> + <manvolnum>1</manvolnum> + <refmiscinfo class="source">The GPSD Project</refmiscinfo> + <refmiscinfo class="manual">GPSD Documentation</refmiscinfo> + </refmeta> + <refnamediv id='name'> + <refname>zerk</refname> + <refpurpose>All purpose GREIS fitting</refpurpose> + </refnamediv> + <refsynopsisdiv id='synopsis'> + <cmdsynopsis> + <command>zerk</command> + <arg choice='opt'>-? </arg> + <arg choice='opt'>-c <replaceable>command</replaceable> + </arg> + <arg choice='opt'>-d <replaceable>disable</replaceable> + </arg> + <arg choice='opt'>-e <replaceable>enable</replaceable> + </arg> + <arg choice='opt'>-f <replaceable>file/device</replaceable> + </arg> + <arg choice='opt'>-h </arg> + <arg choice='opt'>-O <replaceable>oaf</replaceable> + </arg> + <arg choice='opt'>-p <replaceable>preset</replaceable></arg> + <arg choice='opt'>-R <replaceable>rawfile</replaceable> + </arg> + <arg choice='opt'>-r </arg> + <arg choice='opt'>-S <replaceable>setspeed</replaceable> + </arg> + <arg choice='opt'>-s <replaceable>speed</replaceable> + </arg> + <arg choice='opt'>-V </arg> + <arg choice='opt'>-v <replaceable>verbosity</replaceable> + </arg> + <arg choice='opt'>-W </arg> + <arg choice='opt'>-w <replaceable>wait</replaceable> + </arg> + <arg choice='opt'>[server[:port[:device]]]</arg> + </cmdsynopsis> + </refsynopsisdiv> + <refsect1 id='description'> + <title>DESCRIPTION</title> + <para> + <application>zerk</application> is an all purpose GREIS fitting. +If you do not have a Javad GPS that speaks the GREIS protocol then you +can stop reading now.</para> + <para>This tool operates with your Javad GPS at a very low level. +To understand <application>zerk</application> you must first be familiar +with your Javad GPS and the documentation for the GREIS protocol. +<ulink url="http://www.javad.com/downloads/javadgnss/manuals/GREIS/GREIS_Reference_Guide.pdf">GREIS (GNSS Receiver External Interface Specification) Guide</ulink>. +</para> + <para> + <application>zerk</application> can decode common GREIS messages, +poll the GPS status, enable and disable GPS features, and send user +generated commands to the GPS. It can read GREIS messages from a file. It +can read and write directly through a serial device, or through a +running gpsd instance.</para> + </refsect1> + <refsect1 id='options'> + <title>OPTIONS</title> + <para>The program accepts the following options:</para> + <variablelist remap='TP'> + <varlistentry> + <term>-c COMMAND</term> + <listitem> + <para>Send a text string to the GPS. Accepts one parameter, COMMAND, +the command string to send to the GPS. The string is sent verbatim, except +a newline is appended. +</para> + </listitem> + </varlistentry> + <varlistentry> + <term>-d OPTION</term> + <listitem> + <para>Disable an option in the GPS. Accepts one parameter, OPTION, +the option to disable. <application>zerk</application> will exit after +the GPS acknowledges the command, unless the -W is given. +</para> + <variablelist> + <varlistentry> + <term>4HZ</term> + <listitem> + <para>Disable basic GREIS messages at 4Hz. The messages are: +[RT], [UO], [GT], [PV], [SG], [DP], [SI], [EL], [AZ], [EC], [SS], and +[ET]</para> + </listitem> + </varlistentry> + <varlistentry> + <term>COMPASS</term> + <listitem> + <para>Disable use of the COMPASS (BeiDou) constellation.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>CONS</term> + <listitem> + <para>Disable use of all constellations.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>DEFMSG</term> + <listitem> + <para>Disable the default message set (/dev/msg) at 1Hz.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>GALILEO</term> + <listitem> + <para>Disable use of the GALILEO constellation.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>GLONASS</term> + <listitem> + <para>Disable use of the GLONASS constellation.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>GPS</term> + <listitem> + <para>Disable use of the GPS constellation.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>IPR</term> + <listitem> + <para>Disable all Integer Pseudo Range messages. These are + [rx], [rc], [r1], [r2], [r3], [r5], [rl].</para> + </listitem> + </varlistentry> + <varlistentry> + <term>IRNSS</term> + <listitem> + <para>Disable use of the IRNSS constellation.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>NMEA</term> + <listitem> + <para>Disable basic NMEA 4.1e messages at 4Hz. The messages are +GBS, GGA, GSA, GST, GSV, RMC, VTG, and ZDA.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>QZSS</term> + <listitem> + <para>Disable use of the QZSS constellation.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>SBAS</term> + <listitem> + <para>Disable use of the SBAS constellation.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>SNR</term> + <listitem> + <para>Disable all SNR messages, except [EC]. The messages +disabled are: [E1], [E2], [E3], [E5], [El].</para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + <varlistentry> + <term>-e OPTION</term> + <listitem> + <para>Enable an option in the GPS. Accepts one parameter, OPTION, +the option to enable. <application>zerk</application> will exit after +the GPS acknowledges the command, unless the -W is given. -e accepts the +same OPTIONs as -d, except the action is to enable the option. +</para> + </listitem> + </varlistentry> + <varlistentry> + <term>-f FILE</term> + <listitem> + <para>Connect to a file or device. Accepts one parameter, FILE, +the file or device to open. Files are opened read-only. Character +devices are opened red/write, unless the -r parameter is given. +</para> + </listitem> + </varlistentry> + <varlistentry> + <term>-h</term> + <listitem> + <para>Makes <application>zerk</application> print +a usage message and exit.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>-O OAF</term> + <listitem> + <para>Load an Option Authorization File (OAF) into the GPS. Accepts +one parameter, OAF, command file to read. The OAF is just a special case +of a .jpo (GREIS command file). -O will send any valid .jpo file to +the GPS. +</para> + </listitem> + </varlistentry> + <varlistentry> + <term>-p PRESET</term> + <listitem> + <para>Send a preset command the GPS. Accepts one parameter, PRESET, +the name of the command to send. <application>zerk</application> will exit after +the GPS acknowledges the command, unless the -W is given. +</para> + <variablelist> + <varlistentry> + <term>COLDBOOT</term> + <listitem> + <para>Coldboot the GPS.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>CONS</term> + <listitem> + <para>Poll the enabled constellations.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>DM</term> + <listitem> + <para>Disable all periodic GREIS messages..</para> + </listitem> + </varlistentry> + <varlistentry> + <term>ID</term> + <listitem> + <para>Poll the receiver ID.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>IPR</term> + <listitem> + <para>Poll all Integer Pseudo Range messages. These are + [rx], [rc], [r1], [r2], [r3], [r5], [rl].</para> + </listitem> + </varlistentry> + <varlistentry> + <term>OAF</term> + <listitem> + <para>Poll all OAF options.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>RESET</term> + <listitem> + <para>Reset (reboot) the GPS.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>SERIAL</term> + <listitem> + <para>Poll receiver serial number.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>SNR</term> + <listitem> + <para>Poll all Signal to Noise Ratio (SNR) messages. +[EC], [E1], [E2], [E3], [E5], [El].</para> + </listitem> + </varlistentry> + <varlistentry> + <term>VENDOR</term> + <listitem> + <para>Poll GPS vendor.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>VER</term> + <listitem> + <para>Poll GPS version.</para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + <varlistentry> + <term>-r</term> + <listitem> + <para>Read only. Do not send anything to the GPS.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>-R RAW</term> + <listitem> + <para>Save all raw data from the GPS into the file RAW.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>-S SPEED</term> + <listitem> + <para>Configure the GPS serial speed to SPEED bps.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>-s SPEED</term> + <listitem> + <para>Set local serial port speed to SPEED bps. Default 115,200 bps.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>-V</term> + <listitem> + <para>Print <application>zerk</application> version and exit.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>-v VERBOSITY</term> + <listitem> + <para>Set verbosity level to VERBOSITY. Verbosity can be from 0 + (very quiet), to 4 (very noisy). Default 2.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>-v VERBOSITY</term> + <listitem> + <para>Set verbosity level to VERBOSITY. Verbosity can be from 0 + (very quiet), 2 (decode messages), to 4 (very noisy). Default 1.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>-W</term> + <listitem> + <para>Force waiting the entire wait time. No early exit for completion +of -d, -e or -p command.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>-w WAIT</term> + <listitem> + <para>Wait for WAIT seconds before exiting. Will exit early on command +completion of -d, -e or -p command, unless -W is given. Default 2.0 second.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>[server[:port[:device]]]</term> + <listitem> + <para> + By default, <application>zerk</application> collects data from all compatible devices on + localhost, using the default GPSD port 2947. An optional argument + may specify a server to get data from. A + colon-separated suffix is taken as a port number. If there is a + second colon-separated suffix, that is taken as a specific device + name to be watched. Further details on the +<citerefentry> + <refentrytitle>gps</refentrytitle> + <manvolnum>1</manvolnum> + </citerefentry> man page. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>-?</term> + <listitem> + <para>Makes <application>zerk</application> print +a usage message and exit.</para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + <refsect1 id='environment'> + <title>ENVIRONMENT</title> + <para>Options can be placed in the ZERKOPTS environment variable. +ZERKOPTS is processed before the CLI options.</para> + </refsect1> + <refsect1 id='examples'> + <title>EXAMPLES</title> + <para> +Print current Javad serial portC of GPS connected to local running gpsd:: +<programlisting> + zerk -c "print,/cur/term" +</programlisting> + </para> + <para> +Decode raw log file: +<programlisting> +zerk -r -f greis-binary.log -v 2 +</programlisting> + </para> + <para> +Change GPS port speed of device on /dev/ttyAMA0 to 230,400 bps:: +<programlisting> +zerk -S 230400 -f /dev/ttyAMA0 +</programlisting> + </para> + <para> +Watch entire GPS reset cycle: +<programlisting> +zerk -p RESET -v 2 -w 20 -W +</programlisting> + </para> + <para> +Poll SVs Status: +<programlisting> +zerk -W -w 2 -v 2 -c "out,,jps/{CS,ES,GS,Is,WS,QS}" +</programlisting> +Dump gpsd data from remote server: +<programlisting> +zerk -v 2 -w 5 server +</programlisting> + </para> + </refsect1> + <refsect1 id='see_also'> + <title>SEE ALSO</title> + <para> + <application>zerk</application> is written to conform to the official +Javad documentation for the GREIS protocol. +<ulink url="http://www.javad.com/downloads/javadgnss/manuals/GREIS/GREIS_Reference_Guide.pdf">GREIS (GNSS Receiver External Interface Specification) Guide</ulink>. +</para> + <para> + <citerefentry> + <refentrytitle>gpsd</refentrytitle> + <manvolnum>8</manvolnum> + </citerefentry>, +<citerefentry> + <refentrytitle>gps</refentrytitle> + <manvolnum>1</manvolnum> + </citerefentry>, +<citerefentry> + <refentrytitle>cgps</refentrytitle> + <manvolnum>1</manvolnum> + </citerefentry>, +<citerefentry> + <refentrytitle>xgps</refentrytitle> + <manvolnum>1</manvolnum> + </citerefentry>, +<citerefentry> + <refentrytitle>gpsfake</refentrytitle> + <manvolnum>1</manvolnum> + </citerefentry>, +<citerefentry> + <refentrytitle>gpsctl</refentrytitle> + <manvolnum>1</manvolnum> + </citerefentry>, +<citerefentry> + <refentrytitle>gpscat</refentrytitle> + <manvolnum>1</manvolnum> + </citerefentry>, +<citerefentry> + <refentrytitle>gnuplot</refentrytitle> + <manvolnum>1</manvolnum> + </citerefentry>. +</para> + </refsect1> + <refsect1 id='maintainer'> + <title>AUTHOR</title> + <para>Gary E. Miller<email>gem@rellim.com</email> + </para> + </refsect1> +</refentry> |