From e5548e974f42f2080a74ed2a30d1e2927fe0ad9f Mon Sep 17 00:00:00 2001 From: "Gary E. Miller" Date: Mon, 19 Nov 2018 19:56:24 -0800 Subject: man: Move man pages, source and result, into main/ part of cleaning up the root directory. --- SConstruct | 73 +- gps.xml | 321 ------- gps2udp.xml | 129 --- gpscat.xml | 134 --- gpsctl.xml | 284 ------ gpsd.xml | 905 ------------------- gpsd_json.xml | 2609 ----------------------------------------------------- gpsdctl.xml | 81 -- gpsdecode.xml | 147 --- gpsfake.xml | 264 ------ gpsinit.xml | 170 ---- gpsmon.xml | 428 --------- gpspipe.xml | 185 ---- gpsprof.xml | 291 ------ gpsrinex.xml | 195 ---- gpxlogger.xml | 149 --- libgps.xml | 393 -------- libgpsmm.xml | 83 -- man/gps.xml | 321 +++++++ man/gps2udp.xml | 129 +++ man/gpscat.xml | 134 +++ man/gpsctl.xml | 284 ++++++ man/gpsd.xml | 905 +++++++++++++++++++ man/gpsd_json.xml | 2609 +++++++++++++++++++++++++++++++++++++++++++++++++++++ man/gpsdctl.xml | 81 ++ man/gpsdecode.xml | 147 +++ man/gpsfake.xml | 264 ++++++ man/gpsinit.xml | 170 ++++ man/gpsmon.xml | 428 +++++++++ man/gpspipe.xml | 185 ++++ man/gpsprof.xml | 291 ++++++ man/gpsrinex.xml | 195 ++++ man/gpxlogger.xml | 149 +++ man/libgps.xml | 393 ++++++++ man/libgpsmm.xml | 83 ++ man/ntpshmmon.xml | 165 ++++ man/ppscheck.xml | 103 +++ man/srec.xml | 308 +++++++ man/ubxtool.xml | 458 ++++++++++ man/zerk.xml | 468 ++++++++++ ntpshmmon.xml | 165 ---- ppscheck.xml | 103 --- srec.xml | 308 ------- ubxtool.xml | 458 ---------- zerk.xml | 468 ---------- 45 files changed, 8308 insertions(+), 8305 deletions(-) delete mode 100644 gps.xml delete mode 100644 gps2udp.xml delete mode 100644 gpscat.xml delete mode 100644 gpsctl.xml delete mode 100644 gpsd.xml delete mode 100644 gpsd_json.xml delete mode 100644 gpsdctl.xml delete mode 100644 gpsdecode.xml delete mode 100644 gpsfake.xml delete mode 100644 gpsinit.xml delete mode 100644 gpsmon.xml delete mode 100644 gpspipe.xml delete mode 100644 gpsprof.xml delete mode 100644 gpsrinex.xml delete mode 100644 gpxlogger.xml delete mode 100644 libgps.xml delete mode 100644 libgpsmm.xml create mode 100644 man/gps.xml create mode 100644 man/gps2udp.xml create mode 100644 man/gpscat.xml create mode 100644 man/gpsctl.xml create mode 100644 man/gpsd.xml create mode 100644 man/gpsd_json.xml create mode 100644 man/gpsdctl.xml create mode 100644 man/gpsdecode.xml create mode 100644 man/gpsfake.xml create mode 100644 man/gpsinit.xml create mode 100644 man/gpsmon.xml create mode 100644 man/gpspipe.xml create mode 100644 man/gpsprof.xml create mode 100644 man/gpsrinex.xml create mode 100644 man/gpxlogger.xml create mode 100644 man/libgps.xml create mode 100644 man/libgpsmm.xml create mode 100644 man/ntpshmmon.xml create mode 100644 man/ppscheck.xml create mode 100644 man/srec.xml create mode 100644 man/ubxtool.xml create mode 100644 man/zerk.xml delete mode 100644 ntpshmmon.xml delete mode 100644 ppscheck.xml delete mode 100644 srec.xml delete mode 100644 ubxtool.xml delete mode 100644 zerk.xml diff --git a/SConstruct b/SConstruct index d4577f01..ff904d77 100644 --- a/SConstruct +++ b/SConstruct @@ -536,7 +536,7 @@ docbook_html_uri = docbook_url_stem + 'html/docbook.xsl' def CheckXsltproc(context): context.Message('Checking that xsltproc can make man pages... ') - ofp = open("xmltest.xml", "w") + ofp = open("man/xmltest.xml", "w") ofp.write(''' @@ -551,9 +551,9 @@ def CheckXsltproc(context): ''') ofp.close() - probe = "xsltproc --nonet --noout '%s' xmltest.xml" % (docbook_man_uri,) + probe = "xsltproc --nonet --noout '%s' man/xmltest.xml" % (docbook_man_uri,) ret = context.TryAction(probe)[0] - os.remove("xmltest.xml") + os.remove("man/xmltest.xml") if os.path.exists("foo.1"): os.remove("foo.1") context.Result(ret) @@ -1416,10 +1416,10 @@ else: python_deps['test_maidenhead.py'] = 'clienthelpers' python_manpages = { - "gegps.1": "gps.xml", - "gpscat.1": "gpscat.xml", - "gpsfake.1": "gpsfake.xml", - "gpsprof.1": "gpsprof.xml", + "man/gegps.1": "man/gps.xml", + "man/gpscat.1": "man/gpscat.xml", + "man/gpsfake.1": "man/gpsfake.xml", + "man/gpsprof.1": "man/gpsprof.xml", } # check for pyserial @@ -1427,8 +1427,8 @@ else: imp.find_module('serial') python_progs.extend(["ubxtool", "zerk"]) python_manpages.update({ - "ubxtool.1": "ubxtool.xml", - "zerk.1": "zerk.xml", + "man/ubxtool.1": "man/ubxtool.xml", + "man/zerk.1": "man/zerk.xml", }) except ImportError: # no pyserial, reduced functionality in ubxtool and zerk @@ -1457,8 +1457,8 @@ else: if env['xgps']: python_progs.extend(["xgps", "xgpsspeed"]) python_manpages.update({ - "xgps.1": "gps.xml", - "xgpsspeed.1": "gps.xml", + "man/xgps.1": "man/gps.xml", + "man/xgpsspeed.1": "man/gps.xml", }) python_deps['xgps'] = 'clienthelpers' @@ -1745,34 +1745,34 @@ for fn in templated: # Documentation base_manpages = { - "cgps.1": "gps.xml", - "gps.1": "gps.xml", - "gps2udp.1": "gps2udp.xml", - "gpsctl.1": "gpsctl.xml", - "gpsd.8": "gpsd.xml", - "gpsdctl.8": "gpsdctl.xml", - "gpsdecode.1": "gpsdecode.xml", - "gpsd_json.5": "gpsd_json.xml", - "gpsinit.8": "gpsinit.xml", - "gpsmon.1": "gpsmon.xml", - "gpspipe.1": "gpspipe.xml", - "gpsrinex.1": "gpsrinex.xml", - "gpxlogger.1": "gpxlogger.xml", - "lcdgps.1": "gps.xml", - "libgps.3": "libgps.xml", - "libgpsmm.3": "libgpsmm.xml", - "libQgpsmm.3": "libgpsmm.xml", - "srec.5": "srec.xml", + "man/cgps.1": "man/gps.xml", + "man/gps.1": "man/gps.xml", + "man/gps2udp.1": "man/gps2udp.xml", + "man/gpsctl.1": "man/gpsctl.xml", + "man/gpsd.8": "man/gpsd.xml", + "man/gpsdctl.8": "man/gpsdctl.xml", + "man/gpsdecode.1": "man/gpsdecode.xml", + "man/gpsd_json.5": "man/gpsd_json.xml", + "man/gpsinit.8": "man/gpsinit.xml", + "man/gpsmon.1": "man/gpsmon.xml", + "man/gpspipe.1": "man/gpspipe.xml", + "man/gpsrinex.1": "man/gpsrinex.xml", + "man/gpxlogger.1": "man/gpxlogger.xml", + "man/lcdgps.1": "man/gps.xml", + "man/libgps.3": "man/libgps.xml", + "man/libgpsmm.3": "man/libgpsmm.xml", + "man/libQgpsmm.3": "man/libgpsmm.xml", + "man/srec.5": "man/srec.xml", } if env['pps'] and (env["timeservice"] or env["gpsdclients"]): base_manpages.update({ - "ntpshmmon.1": "ntpshmmon.xml", + "man/ntpshmmon.1": "man/ntpshmmon.xml", }) if tiocmiwait: base_manpages.update({ - "ppscheck.8": "ppscheck.xml", + "man/ppscheck.8": "man/ppscheck.xml", }) all_manpages = list(base_manpages.keys()) @@ -1942,7 +1942,8 @@ for manpage in all_manpages: if not manbuilder and not os.path.exists(manpage): continue section = manpage.split(".")[1] - dest = os.path.join(installdir('mandir'), "man" + section, manpage) + dest = os.path.join(installdir('mandir'), "man" + section, + os.path.basename(manpage)) maninstall.append(env.InstallAs(source=manpage, target=dest)) install = env.Alias('install', binaryinstall + maninstall + python_install + pc_install + headerinstall) @@ -1992,7 +1993,7 @@ Utility("scan-build", ["gpsd.h", "packet_names.h"], # Check the documentation for bogons, too -Utility("xmllint", glob.glob("*.xml"), +Utility("xmllint", glob.glob("man/*.xml"), "for xml in $SOURCES; do xmllint --nonet --noout --valid $$xml; done") # Use deheader to remove headers not required. If the statistics line @@ -2414,8 +2415,8 @@ for fn in glob.glob("www/*.in"): if htmlbuilder: # Manual pages - for xml in glob.glob("*.xml"): - env.HTML('www/%s.html' % xml[:-4], xml) + for xml in glob.glob("man/*.xml"): + env.HTML('www/%s.html' % os.path.basename(xml[:-4]), xml) # DocBook documents for stem in ['writing-a-driver', 'performance/performance', @@ -2529,6 +2530,8 @@ env.Clean(clean_misc, glob.glob('*.gcno') + glob.glob('*.gcda')) env.Clean(clean_misc, glob.glob('.coverage*') + ['htmlcov/']) # Clean Qt stuff env.Clean(clean_misc, ['libQgpsmm.prl', 'Qgpsmm.pc']) +# Clean old and new location man page files +env.Clean(clean_misc, glob.glob('*.[0-8]') + glob.glob('man/*.[0-8]')) # Other misc items env.Clean(clean_misc, ['config.log', 'contrib/ppscheck', 'contrib/clock_test', 'TAGS']) diff --git a/gps.xml b/gps.xml deleted file mode 100644 index 5af9a4be..00000000 --- a/gps.xml +++ /dev/null @@ -1,321 +0,0 @@ - - - - -9 Aug 2004 - -gps -1 -The GPSD Project -GPSD Documentation - - -cgps -gegps -gps -lcdgps -xgps -xgpsspeed -test clients for gpsd - - - - - cgps - -D debug-level - -h - -l dms - -m - -s - -u inm - -V - - server - - :port - :device - - - - - gegps - -d directory - -h - -i - -V - - - lcdgps - -h - -j - -l dms - -s - -u inm - -V - - server - - :port - :device - - - - - xgps - -? - -D debug-level - -h - -l dms - -u inm - -V - - server - - :port - :device - - - - - xgpsspeed - --debug debug-level - --device device - -h - --host host - --landspeed - --maxspeed maxspeed - --nautical - --port port - --speedunits - - mphkphknots - - - -V - - server - - :port - :device - - - - - -DESCRIPTION - -These are the demonstration clients shipped with -gpsd. They have some common options: - -The option causes each client to emit a summary of its -options and then exit. - -The option causes each client to dump the package -version and exit. - - The 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. - -xgps, -cgps, and lcdgps -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: - - - 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 - -These preferences may be overridden by the -option. - -Where present, the 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). - - The option, when present, sets a debug -level; it is primarily for use by GPSD developers. It enables -various progress messages to standard error. - -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: - - - -localhost:/dev/ttyS1 -Look at the default port of localhost, trying both -IPv4 and IPv6 and watching output from serial device 1. - - -example.com:2317 -Look at port 2317 on example.com, trying both -IPv4 and IPv6. - - -71.162.241.5:2317:/dev/ttyS3 -Look at port 2317 at the specified IPv4 -address, collecting data from attached serial device 3. - - -[FEDC:BA98:7654:3210:FEDC:BA98:7654:3210]:2317:/dev/ttyS5 -Look at port 2317 at the specified IPv6 -address, collecting data from attached serial device 5. - - - -Not all clients shipped with GPSD are documented here. See also -the separate manual pages for -gpspipe1 -and -gpsmon1 -and -gpxlogger1 -. - -xgps - -xgps is a simple test client for -gpsd with an X interface. It displays -current GPS position/time/velocity information and (for GPSes that -support the feature) the locations of accessible satellites. - -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. - - -xgpsspeed - -xgpsspeed is a speedometer that uses -position information from the GPS. It accepts an -h option and -optional argument as for gps, or a -V -option to dump the package version and exit. - -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. - -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. - -In the nautical mode only, --maxspeed sets the maximum on the -speedometer. - - -cgps - -cgps is a client resembling -xgps, but without the pictorial -satellite display and able to run on a serial terminal or -terminal emulator. - - The option prevents -cgps from displaying the data coming from -the daemon. This display can also be toggled with the s -command. - -The 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. - -cgps 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' - - -lcdgps - -A client that passes gpsd data to -lcdproc, 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. - - - -gegps - -This program collects fixes from gpsd -and feeds them to a running instance of Google Earth for live location -tracking. - -The argument is the location of the Google -Earth installation directory. If not specified, it defaults to the -current directory. - -If you have the free (non-subscription) version, start by -running with the 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 gpsd in the normal way -after that. - - - -SEE ALSO - -gpsd8, -libgps3, -libgpsmm3, -gpsfake1, -gpsctl1, -gpscat1, -gpsprof1. -gpspipe1. -gpsmon1. -gpxlogger1. - - - -AUTHORS - - -Remco Treffcorn, Derrick Brashear, Russ Nelson & Eric S. Raymond, -Jeff Francis (cgps), Chen Wei weichen302@aol.com (gegps & xgpsspeed), -Robin Wittler real@the-real.org (xgpsspeed). - - -This manual page by Eric S. Raymond esr@thyrsus.com - - - - - diff --git a/gps2udp.xml b/gps2udp.xml deleted file mode 100644 index b222b138..00000000 --- a/gps2udp.xml +++ /dev/null @@ -1,129 +0,0 @@ - - - - -01 Marc 2013 - -gps2udp -1 -The GPSD Project -GPSD Documentation - - -gps2udp -feed the take from gpsd to one or more aggregation sites - - - - - gps2udp - -h - -n - -j - -a - -u hostname:udpport - -c count - -d 1|2 - -v - - server - :port - :device - - - - - -DESCRIPTION - -gps2udp is a tool to connect to -gpsd and output the received sentences to -one or many UDP host:port destinations. This makes the program useful -for feeding AIS information from gpsd to -aishub, marinetraffic, shipfinder,... - -gps2udp does not require root -privileges, and can be run concurrently with other tools connecting -to the local gpsd without causing problems. - -The output will consist of one or both of NMEA (-n option) or -JSON (-j option) gpsd sentences. The -output is sent to one or many destinations host through a UDP network -socket (-u host:port options) . - -Optionally a server, TCP/IP port number and remote device can be given. -If omitted, gps2udp connects to localhost on -the default port (2947) and watches all devices opened by -gpsd. - -gps2udp may be run as a daemon (-b -option). - -gps2udp is designed to run smoothly in -background; it reconnects automatically to -gpsd whenever it is restarted. For -debugging purporses, there is an option to exit gracefully after a given -count of packets (-c option). - - -OPTIONS - --h makes gps2udp print -a usage message and exit. - --n causes NMEA sentences to be output. --j causes JSON sentences to be output. --u host:port UDP destination for output sentenses (up to five -destinations). - --a output only AIS messages. --b causes gps2udp to run as a daemon. --c [count] causes [count] sentences to be output. -gps2udp will then exit gracefully. - --d 1 prints sent packet on stdout. --v prints the version, then exits. - - -EXAMPLE -With a running gpsd accessible on the -network - -gps2udp -d 1 -n -u data.aishub.net:2222 will -collect data from localhost:gpsd display them on stdout and send a -copy to test aishub in NMEA format. - -gps2udp -a -n -b -u data.aishub.net:2222 -u 5.9.207.224:5321 -u 109.200.19.151:4001 fridu.net:2947 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 - - -SEE ALSO - -gpsd8, -gps1, -libgps3, -libgpsmm3, -gpsprof1, -gpsfake1, -gpsctl1, -gpscat1. -gpsmon1. - - - -AUTHOR - -Fulup Ar Foll fulup@sinagot.net. - - - - - diff --git a/gpscat.xml b/gpscat.xml deleted file mode 100644 index a22b6a84..00000000 --- a/gpscat.xml +++ /dev/null @@ -1,134 +0,0 @@ - - - - -16 Nov 2006 - -gpscat -1 -The GPSD Project -GPSD Documentation - - -gpscat -dump the output from a GPS - - - - - gpscat - -s speed - -p - -t - -D debuglevel - file-or-serial-port - - - -DESCRIPTION - -gpscat 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. - -In raw mode (the default) gpscat -simply dumps its input to standard output. Nonprintable characters -other than ASCII whitespace are rendered as hexadecimal string escapes. - -In packetizing mode, gpscat uses the -same code as -gpsd8's -packet sniffer to break the input into packets. Packets are reported -one per line; line breaks in the packets themselves are -escaped. - -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. - -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. - -The program accepts the following options: - - - --p - -Invoke packetizer mode. - - - - --s - -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). - - - - --t - -Invoke packetizer mode, with the packet type and length (in -parentheses) reported before a colon and space on each line. - - - - --D - -In packetizer mode, enable progress messages from the packet -getter. Probably only of interest to developers testing packet -getter changes. - - - - --h - -Display program usage and exit. - - - - -Specifying -s 4800N1 is frequently helpful with unknown -devices. - - - -SEE ALSO - -gpsd8, -gps1, -libgps3, -libgpsmm3, -gpsfake1. -gpsprof1, -gpsctl1, -gpsdctl8, -gpsmon1. - - - -AUTHOR - -Eric S. Raymond esr@thyrsus.com. - - diff --git a/gpsctl.xml b/gpsctl.xml deleted file mode 100644 index b0f9f6c0..00000000 --- a/gpsctl.xml +++ /dev/null @@ -1,284 +0,0 @@ - - - - -29 Oct 2006 - -gpsctl -1 -The GPSD Project -GPSD Documentation - - -gpsctl -control the modes of a GPS - - - - - gpsctl - -h - - -b - -n - - -x control - -e - -f - -l - -s speed - -t devicetype - -R - -D debuglevel - -V - serial-port - - - -DESCRIPTION - -gpsctl 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. - -If you have only one GPS attached to your machine, and gpsd is -running, it is not necessary to specify the device; -gpsctl does its work through -gpsd, which will locate it for you. - -When gpsd 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'. - -The program accepts the following options: - - - --b - -Put the GPS into native (binary) mode. - - - - --c - -Change the GPS's cycle time. Units are seconds. Note, most -GPSes have a fixed cycle time of 1 second. - - - - --e - -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 without specifying a device. Note: -the packet data for a binary prototype will be raw, not ASCII-ized in -any way. - - - - --f - -Force low-level access (not through the daemon). - - - - --l - -List a table showing which option switches can be applied -to which device types, and exit. - - - - --n - -Put GPS into NMEA mode. - - - - --s - -Set the baud rate at which the GPS emits packets. - -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. - - - - --t - -Force the device type. - - - - --x - -Send a specified control string to the GPS; -gpsctl 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 . - - - - --T - -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. - - - - --R - -Remove the GPSD shared-memory segment used for SHM export. This -option will normally only be of interest to GPSD developers. - - - - --h - -Display program usage and exit. - - - - --D - -Set level of debug messages. - - - - --V - -Display program version and exit. - - - - -The argument of the forcing option, , should be a -string which is contained in exactly one of the known driver -names; for a list, do gpsctl -l. - -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, gpsctl exits with -a warning. (This may be useful in scripts.) - -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.) - -If no options are given, the program will display a message -identifying the GPS type of the selected device and exit. - -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. - - - -ENVIRONMENT VARIABLES - -By setting the environment variable GPSD_SHM_KEY, -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 gpsd from -production ones. - - - -EXAMPLES - - - -gpsctl /dev/ttyUSB0 - -Attempt to identify the device on USB serial device 0. Time out -after the default number of seconds. Adding the will -force low-level access and suppress the normal complaint when this -tool can't find a GPSD to work through. - - - - -gpsctl -f -n -s 9600 /dev/ttyUSB0 - -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. - - - - - - -BUGS - -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. - -Baud rate and mode changes work in direct mode but are not -reliable in client mode. This will be fixed in a future release. - - - -SEE ALSO - -gpsd8, -gpsdctl8, -gps1, -libgps3, -libgpsmm3, -gpsprof1, -gpsfake1. - - - -AUTHOR - -Eric S. Raymond esr@thyrsus.com. - - diff --git a/gpsd.xml b/gpsd.xml deleted file mode 100644 index 49489690..00000000 --- a/gpsd.xml +++ /dev/null @@ -1,905 +0,0 @@ - - - -]> - -9 Aug 2004 - -gpsd -8 -The GPSD Project -GPSD Documentation - - -gpsd -interface daemon for GPS receivers - - - - - - gpsd - -b - -D debuglevel - -F control-socket - -G - -h - -l - -n - -N - -P pidfile - -r - -S listener-port - -V - - source-name - - - - -QUICK START - -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: - - -gpsd /dev/ttyUSB0 - - -For the lowest-numbered serial port: - - -gpsd /dev/ttyS0 - - -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 (which see). - -On Linux systems supporting udev, gpsd -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. - -For your initial tests set your GPS hardware to speak NMEA, as -gpsd is guaranteed to be able to process -that. If your GPS has a native or binary mode with better performance -that gpsd knows how to speak, -gpsd will autoconfigure that mode. - -You can verify correct operation by first starting -gpsd and then -xgps, the X windows test client. - -If you have problems, the GPSD project maintains a FAQ to -assist troubleshooting. - - -DESCRIPTION - -gpsd 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 -gpsd 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, -gpsd discovers the correct port speed and -protocol for it. - -gpsd 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. - -The GPS reporting formats supported by your instance of -gpsd 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 gpsd -l - -gpsd 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 -gpsd as an intermediary, applications -avoid contention for serial devices. - -gpsd 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 gpsd 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 - and for discussion. - -Client applications will communicate with gpsd -via a TCP/IP port, 2947 by default). Both IPv4 and IPv6 connections -are supported and a client may connect via either. - -The program accepts the following options: - - --b -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 -gpsd cannot configure the receiver for -optimal performance, but it also means that -gpsd 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. - - --D - -Set debug level. At debug levels 2 and above, -gpsd reports incoming sentence and actions -to standard error if gpsd is in the foreground -(-N) or to syslog if in the background. - - - --F - -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. - - - --G -This flag causes gpsd 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. - - --h -Display help message and terminate. - - --l -List all drivers compiled into this -gpsd instance. The letters to the left of -each driver name are the gpsd -control commands supported by that driver. - - - --n - -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). - - - - --N -Don't daemonize; run in foreground. -This switch is mainly useful for debugging. - - - --r -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. - - --P - -Specify the name and path to record the daemon's process ID. - - - --S -Set TCP/IP port on which to listen for GPSD clients -(default is 2947). - - --V - -Dump version and exit. - - - - -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: - - - -Local serial or USB device - -A normal Unix device name of a serial or USB device to which a -sensor is attached. Example: -/dev/ttyUSB0. - - - -Local PPS device - -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: -/dev/pps0. - - - -TCP feed - -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: -tcp://data.aishub.net:4006. - - - -UDP feed - -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: -udp://127.0.0.1:5000. - - - -Ntrip caster - -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. - - - -DGPSIP server - -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: -dgpsip://dgps.wsrcc.com:2101. - - - -Remote gpsd feed - -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 gpsd port will be used). The daemon -will open a socket to the indicated address and port and emulate a -gpsd client, collecting JSON reports from -the remote gpsd instance that will be -passed to local clients. - - - -NMEA2000 CAN data - -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 gpsd can be started. If -there is more then one unit on the CAN bus that provides GPS data, -gpsd chooses the unit from which a GPS message -is first seen. Example: nmea2000://can0. - - - - - -(The "ais:://" source type supported in some older versions of -the daemon has been retired in favor of the more general -"tcp://".) - -Additionally, two serial device names have a side effect: - - -/dev/ttyAMA0 - -The UART device on a Raspberry Pi. Has the side effect of -opening /dev/pps0 for RFC2783 1PPS data. - - - -Generic GPS device 0. Has the side effect of -opening /dev/pps0 for RFC2783 1PPS data/ - - - - - - - -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 for -details on this). Daemon startup will abort with an error if neither -any devices nor a control socket are specified. - -When a device is activated (i.e. a client requests data from it), -gpsd attempts to execute a hook from -/etc/gpsd/device-hook with first command line argument -set to the pathname of the device and the second to -. On deactivation it does the same passing - for the second argument. - -gpsd 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. - - -THE SOCKET INTERFACE - -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 -libgps client library and take appropriate -care to conditionalize their code on the major and minor protocol -version symbols. - -The request-response protocol for the socket interface is fully -documented in -gpsd_json5. - - - -SHARED-MEMORY AND DBUS INTERFACES - -gpsd has two other (read-only) -interfaces. - -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 -libgps3. The -shared-memory interface is intended primarily for embedded deployments -in which gpsd 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. - -The daemon may be configured to emit a D-Bus signal each time an -attached device delivers a fix. The signal path is path -/org/gpsd, the signal interface is "org.gpsd", and the -signal name is "fix". The signal payload layout is as follows: - -Satellite object - - - - Type - Description - - - - - DBUS_TYPE_DOUBLE - Time (seconds since Unix epoch) - - - DBUS_TYPE_INT32 - mode - - - DBUS_TYPE_DOUBLE - Time uncertainty (seconds). - - - DBUS_TYPE_DOUBLE - Latitude in degrees. - - - DBUS_TYPE_DOUBLE - Longitude in degrees. - - - DBUS_TYPE_DOUBLE - Horizontal uncertainty in meters, 95% confidence. - - - DBUS_TYPE_DOUBLE - Altitude in meters. - - - DBUS_TYPE_DOUBLE - Altitude uncertainty in meters, 95% confidence. - - - DBUS_TYPE_DOUBLE - Course in degrees from true north. - - - DBUS_TYPE_DOUBLE - Course uncertainty in meters, 95% confidence. - - - DBUS_TYPE_DOUBLE - Speed, meters per second. - - - DBUS_TYPE_DOUBLE - Speed uncertainty in meters per second, - 95% confidence. - - - DBUS_TYPE_DOUBLE - Climb, meters per second. - - - DBUS_TYPE_DOUBLE - Climb uncertainty in meters per second, - 95% confidence. - - - DBUS_TYPE_STRING - Device name - - - -
- - - -GPS DEVICE MANAGEMENT - -gpsd 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. - -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. - -When gpsd is properly installed along -with hotplug notifier scripts feeding it device-add commands over the -control socket, gpsd should require no -configuration or user action to find devices. - -Sending SIGHUP to a running gpsd -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. - -When gpsd 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 after after some -devices have been seen, it shuts down gracefully. It is expected that -future device hotplug events will reactivate it. - -To point gpsd 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 -/dev/foo. 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 /dev/foo from the search -list, send "-/dev/foo\n". - -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. - -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. - -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 -gpsd's device pool. An ERROR response to a -! command means the daemon did not recognize the devicename -specified. - -The control socket is intended for use by hotplug scripts and -other device-discovery services. This control channel is separate -from the public gpsd service port, and only -locally accessible, in order to prevent remote denial-of-service and -spoofing attacks. - - -ACCURACY - -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 not rely on GPS altitude for -life-critical tasks such as landing an airplane. - -These errors are intrinsic to the design and physics of the GPS -system. gpsd does its internal -computations at sufficient accuracy that it will add no measurable -position error of its own. - -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. - -On a 4800bps connection, the time latency of fixes provided by -gpsd 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 gpsd 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. - -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. - -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 gpsd at -debug level 4 to see the chipset type and firmware revision -level. - -There are exactly two circumstances under which -gpsd relies on the host-system -clock: - -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. gpsd 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. - -If you are using an NMEA-only GPS (that is, not using SiRF or -Garmin or Zodiac binary mode), gpsd 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 -gpsd 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. - - -USE WITH NTP - -gpsd can provide reference clock information to -ntpd, to keep the system clock synchronized -to the time provided by the GPS receiver. - -On Linux, gpsd 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 -gpsd will use that for extra -accuracy. - -Detailed instructions for using GPSD to set up a high-quality -time service can be found among the documentation on the GPSD -website. - - -USE WITH D-BUS - -On operating systems that support D-BUS, -gpsd 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 -gpsd source code to learn more. - - -SECURITY AND PERMISSIONS ISSUES - -gpsd, 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. - -gpsd 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 /dev/ttyS0. - -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 gpsd. -It ensures that any such compromises cannot be used for privilege -elevation to root. - -The assumption behind gpsd'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, -gpsd may not be able to open GPS devices in -order to read them (such failures will be logged). - -In order to fend off inadvertent denial-of-service attacks by -port scanners (not to mention deliberate ones), -gpsd 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, -gpsd 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). - - -LIMITATIONS - -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. - -gpsd 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. - -When using SiRF chips, the VDOP/TDOP/GDOP figures and associated -error estimates are computed by gpsd rather -than reported by the chip. The computation does not exactly match -what SiRF chips do internally, which includes some satellite weighting -using parameters gpsd cannot see. - -Autobauding on the Trimble GPSes can take as long as 5 seconds -if the device speed is not matched to the GPS speed. - -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. - -AIDVM decoding of types 16-17, 22-23, and 25-26 is unverified. - -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. - -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. - -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. - -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 -gpsd 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 gpsd 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). - - -FILES - - - -/dev/ttyS0 - -Prototype TTY device. After startup, -gpsd sets its group ID to the owning group of this -device if no GPS device was specified on the command line does not -exist. - - - -/etc/gpsd/device-hook - -Optional file containing the device activation/deactivation script. -Note that while /etc/gpsd is the default system -configuration directory, it is possible to build the GPSD source code -with different assumptions. - - - - - - -ENVIRONMENT VARIABLES - -By setting the environment variable GPSD_SHM_KEY, -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 -gpsd from production ones. - - -APPLICABLE STANDARDS - -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 -gpsd 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. - -gpsd 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. - -Note that gpsd JSON returns pure decimal -degrees, not the hybrid degree/minute format described in the NMEA -standard. - -Differential-GPS corrections are conveyed by the RTCM -protocols. The applicable standard for RTCM-104 V2 is RTCM -Recommended Standards for Differential GNSS (Global Navigation -Satellite) Service RTCM Paper 136-2001/SC 104-STD. The -applicable standard for RTCM-104 V3 is RTCM Standard -10403.1 for Differential GNSS Services - Version 3 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". - -AIS is defined by ITU Recommendation M.1371, -Technical Characteristics for a Universal Shipborne -Automatic Identification System Using Time Division Multiple -Access. The AIVDM/AIVDO format understood by this program -is defined by IEC-PAS 61162-100, Maritime navigation and -radiocommunication equipment and systems. A more accessible -description of both can be found at AIVDM/AIVDO Protocol -Decoding, on the references page of the GPSD project -website. - -Subframe data is defined by IS-GPS-200E, GLOBAL -POSITIONING SYSTEM WING (GPSW) SYSTEMS ENGINEERING & INTEGRATION, -INTERFACE SPECIFICATION IS-GPS-200 Revision E. The format -understood by this program is defined in Section 20 (Appendix II) of -the IS-GPS-200E, GPS NAVIGATION DATA STRUCTURE FOR DATA, -D(t) - -JSON is specified by RFC 7159, The JavaScript Object -Notation (JSON) Data Interchange Format. - -The API for PPS time service is specified by RFC 2783, -Pulse-Per-Second API for UNIX-like Operating Systems, -Version 1.0 - - -SEE ALSO - -gpsdctl8, -gps1, -libgps3, -gpsd_json5, -libgpsmm3, -gpsprof1, -gpsfake1, -gpsctl1, -gpscat1, - - - -AUTHORS - -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 -esr@thyrsus.com. - - - diff --git a/gpsd_json.xml b/gpsd_json.xml deleted file mode 100644 index 1c868b61..00000000 --- a/gpsd_json.xml +++ /dev/null @@ -1,2609 +0,0 @@ - - - -]> - -17 Jun 2018 - -gpsd_json -5 -The GPSD Project -GPSD Documentation - - -gpsd_json -gpsd request/response protocol - - -OVERVIEW - -gpsd is a service daemon that can be used -to monitor GPSes, DGPS receivers, Marine AIS broadcasts, and various other -location-related and kinematic sensors. - -Clients may communicate with gpsd via -textual requests and responses over a socket. It is a bad idea for -applications to speak the protocol directly: rather, they should use -the libgps client library (for C; bindings -also exist for other languages) and take appropriate care to -conditionalize their code on the major and minor protocol version -symbols. - -The GPSD protocol is built on top of JSON, JavaScript Object -Notation, as specified in RFC 7159: The JavaScript Object -Notation (JSON) Data Interchange Format. GPSD's use of -JSON is restricted in some ways that make parsing it in fixed-extent -languages (such as C) easier. - -A request line is introduced by "?" and may include multiple -commands. Commands begin with a command identifier, followed either -by a terminating ';' or by an equal sign "=" and a JSON object treated -as an argument. Any ';' or newline indication (either LF or CR-LF) -after the end of a command is ignored. All request lines must be -composed of US-ASCII characters and may be no more than 80 characters -in length, exclusive of the trailing newline. - -Responses are JSON objects all of which have a "class" attribute -the value of which is either the name of the invoking command. There -are reports (including but not limited to as "TPV", "SKY", "DEVICE", -and "ERROR") which are not direct responses to commands. - - The order of JSON attributes within a response object is never -significant, and you may specify attributes in commands in any -order. Responses never contain the special JSON value null; instead, -attributes with empty or undefined values are omitted. The length -limit for responses and reports is 1536 characters, including trailing -newline; longer responses will be truncated, so client code must be -prepared for the possibility of invalid JSON fragments. - -In JSON reports, if an attribute is present only if the parent -attribute is present or has a particular range, then the parent -attribute is emitted first. - -There is one constraint on the order in which attributes will -be omitted. If an optional attribute is present only when a parent -attribute has a specified value or range of values, the parent -attribute will be emitted first to make parsing easier. - -The next subsection section documents the core GPSD protocol. -Extensions are documented in the following subsections. The extensions -may not be supported in your gpsd instance -if it has been compiled with a restricted feature set. - - -CORE SOCKET PROTOCOL - -Here are the core-protocol responses: - - - -TPV - -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. - -TPV object - - - - Name - Always? - Type - Description - - - - - class - Yes - string - Fixed: "TPV" - - - device - No - string - Name of originating device. - - - status - No - numeric - GPS status: %d, 2=DGPS fix, otherwise not present. - - - mode - Yes - numeric - NMEA mode: %d, 0=no mode value yet seen, 1=no fix, 2=2D, 3=3D. - - - time - No - string - 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. - - - ept - No - numeric - Estimated timestamp error (%f, seconds, 95% confidence). - Present if time is present. - - - lat - No - numeric - Latitude in degrees: +/- signifies North/South. Present - when mode is 2 or 3. - - - lon - No - numeric - Longitude in degrees: +/- signifies East/West. Present - when mode is 2 or 3. - - - alt - No - numeric - Altitude in meters. Present if mode is 3. - - - epx - No - numeric - Longitude error estimate in meters, 95% confidence. Present - if mode is 2 or 3 and DOPs can be calculated from the satellite - view. - - - epy - No - numeric - Latitude error estimate in meters, 95% confidence. Present - if mode is 2 or 3 and DOPs can be calculated from the satellite - view. - - - epv - No - numeric - Estimated vertical error in meters, 95% confidence. Present - if mode is 3 and DOPs can be calculated from the satellite - view. - - - track - No - numeric - Course over ground, degrees from true north. - - - magtrack - No - numeric - Course over ground, degrees magnetic. - - - speed - No - numeric - Speed over ground, meters per second. - - - climb - No - numeric - Climb (positive) or sink (negative) rate, meters per - second. - - - epd - No - numeric - Direction error estimate in degrees, 95% confidence. - - - eps - No - numeric - Speed error estinmate in meters/sec, 95% confidence. - - - epc - No - numeric - Climb/sink error estimate in meters/sec, 95% confidence. - - - ecefx - No - numeric - ECEF X position in meters. - - - ecefy - No - numeric - ECEF Y position in meters. - - - ecefz - No - numeric - ECEF Z position in meters. - - - ecefpAcc - No - numeric - ECEF position error in meters. - - - ecefvx - No - numeric - ECEF X velocity in meters/second. - - - ecefvy - No - numeric - ECEF Y velocity in meters/second. - - - ecefvz - No - numeric - ECEF Z velocity in meters/second. - - - ecefvAcc - No - numeric - ECEF velocity error in meters/second. - - - - -
- -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. - -Here's an example: - - -{"class":"TPV","device":"/dev/pts/1", - "time":"2005-06-08T10:34:48.283Z","ept":0.005, - "lat":46.498293369,"lon":7.567411672,"alt":1343.127, - "eph":36.000,"epv":32.321, - "track":10.3788,"speed":0.091,"climb":-0.085,"mode":3} - - - - - -SKY - -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. - -SKY object - - - - Name - Always? - Type - Description - - - - - class - Yes - string - Fixed: "SKY" - - - device - No - string - Name of originating device - - - time - No - string - Time/date stamp in ISO8601 format, UTC. May have a - fractional part of up to .001sec precision. - - - xdop - No - numeric - Longitudinal dilution of precision, a dimensionless - factor which should be multiplied by a base UERE to get an - error estimate. - - - ydop - No - numeric - Latitudinal dilution of precision, a dimensionless - factor which should be multiplied by a base UERE to get an - error estimate. - - - vdop - No - numeric - Altitude dilution of precision, a dimensionless - factor which should be multiplied by a base UERE to get an - error estimate. - - - tdop - No - numeric - Time dilution of precision, a dimensionless - factor which should be multiplied by a base UERE to get an - error estimate. - - - hdop - No - numeric - Horizontal dilution of precision, a dimensionless - factor which should be multiplied by a base UERE to get a - circular error estimate. - - - pdop - No - numeric - Spherical dilution of precision, a dimensionless - factor which should be multiplied by a base UERE to get an - error estimate. - - - gdop - No - numeric - Hyperspherical dilution of precision, a dimensionless - factor which should be multiplied by a base UERE to get an - error estimate. - - - satellites - Yes - list - List of satellite objects in skyview - - - - -
- -Many devices compute dilution of precision factors but do not -include them in their reports. Many that do report DOPs report only -HDOP, two-dimensional circular error. gpsd -always passes through whatever the device 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. - -The satellite list objects have the following elements: - -Satellite object - - - - Name - Always? - Type - Description - - - - - PRN - Yes - numeric - PRN ID of the satellite. 1-63 are GNSS satellites, - 64-96 are GLONASS satellites, 100-164 are SBAS satellites - - - az - Yes - numeric - Azimuth, degrees from true north. - - - el - Yes - numeric - Elevation in degrees. - - - ss - Yes - numeric - Signal strength in dB. - - - used - Yes - boolean - 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.) - - - -
- -Note that satellite objects do not have a "class" field, as -they are never shipped outside of a SKY object. - -When the C client library parses a SKY response, it -will assert the SATELLITE_SET bit in the top-level set member. - -Here's an example: - - -{"class":"SKY","device":"/dev/pts/1", - "time":"2005-07-08T11:28:07.114Z", - "xdop":1.55,"hdop":1.24,"pdop":1.99, - "satellites":[ - {"PRN":23,"el":6,"az":84,"ss":0,"used":false}, - {"PRN":28,"el":7,"az":160,"ss":0,"used":false}, - {"PRN":8,"el":66,"az":189,"ss":44,"used":true}, - {"PRN":29,"el":13,"az":273,"ss":0,"used":false}, - {"PRN":10,"el":51,"az":304,"ss":29,"used":true}, - {"PRN":4,"el":15,"az":199,"ss":36,"used":true}, - {"PRN":2,"el":34,"az":241,"ss":43,"used":true}, - {"PRN":27,"el":71,"az":76,"ss":43,"used":true}]} - - - - - - -GST - -A GST object is a pseudorange noise report. - -GST object - - - - Name - Always? - Type - Description - - - - - class - Yes - string - Fixed: "GST" - - - device - No - string - Name of originating device - - - time - No - string - Time/date stamp in ISO8601 format, UTC. May have a - fractional part of up to .001sec precision. - - - - rms - No - numeric - Value of the standard deviation of the range inputs to the -navigation process (range inputs include pseudoranges and DGPS -corrections). - - - - major - No - numeric - Standard deviation of semi-major axis of error ellipse, in meters. - - - - minor - No - numeric - Standard deviation of semi-minor axis of error ellipse, in meters. - - - - orient - No - numeric - Orientation of semi-major axis of error ellipse, in degrees from true north. - - - - lat - No - numeric - Standard deviation of latitude error, in meters. - - - - lon - No - numeric - Standard deviation of longitude error, in meters. - - - - alt - No - numeric - Standard deviation of altitude error, in meters. - - - - -
- -Here's an example: - - -{"class":"GST","device":"/dev/ttyUSB0", - "time":"2010-12-07T10:23:07.096Z","rms":2.440, - "major":1.660,"minor":1.120,"orient":68.989, - "lat":1.600,"lon":1.200,"alt":2.520} - - - - - -ATT - -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. - -The "class" and "mode" fields will reliably be present. Others -may be reported or not depending on the specific device type. - -ATT object - - - - Name - Always? - Type - Description - - - - - class - Yes - string - Fixed: "ATT" - - - device - Yes - string - Name of originating device - - - time - No - string - Time/date stamp in ISO8601 format, UTC. May have a - fractional part of up to .001sec precision. - - - heading - No - numeric - Heading, degrees from true north. - - - mag_st - No - string - Magnetometer status. - - - pitch - No - numeric - Pitch in degrees. - - - pitch_st - No - string - Pitch sensor status. - - - yaw - No - numeric - Yaw in degrees - - - yaw_st - No - string - Yaw sensor status. - - - roll - No - numeric - Roll in degrees. - - - roll_st - No - string - Roll sensor status. - - - dip - No - numeric - Local magnetic inclination, degrees, positive when the magnetic -field points downward (into the Earth). - - - mag_len - No - numeric - Scalar magnetic field strength. - - - mag_x - No - numeric - X component of magnetic field strength. - - - mag_y - No - numeric - Y component of magnetic field strength. - - - mag_z - No - numeric - Z component of magnetic field strength. - - - acc_len - No - numeric - Scalar acceleration. - - - acc_x - No - numeric - X component of acceleration. - - - acc_y - No - numeric - Y component of acceleration. - - - acc_z - No - numeric - Z component of acceleration. - - - gyro_x - No - numeric - X component of acceleration. - - - gyro_y - No - numeric - Y component of acceleration. - - - depth - No - numeric - Water depth in meters. - - - temp - No - numeric - Temperature at sensor, degrees centigrade. - - - - - -
- -The heading, pitch, and roll status codes (if present) vary by device. -For the TNT Revolution digital compasses, they are coded as follows: - -Device flags - - - - Code - Description - - - - - C - magnetometer calibration alarm - - - L - low alarm - - - M - low warning - - - N - normal - - - O - high warning - - - P - high alarm - - - V - magnetometer voltage level alarm - - - -
- - -When the C client library parses a response of this kind, it -will assert ATT_IS. - -Here's an example: - - -{"class":"ATT","time":1270938096.843, - "heading":14223.00,"mag_st":"N", - "pitch":169.00,"pitch_st":"N", "roll":-43.00,"roll_st":"N", - "dip":13641.000,"mag_x":2454.000} - - - - - - -And here are the commands: - - - - -?VERSION; -Returns an object with the following attributes: - -VERSION object - - - - Name - Always? - Type - Description - - - - - class - Yes - string - Fixed: "VERSION" - - - release - Yes - string - Public release level - - - rev - Yes - string - Internal revision-control level. - - - proto_major - Yes - numeric - API major revision level. - - - proto_minor - Yes - numeric - API minor revision level. - - - remote - No - string - URL of the remote daemon reporting this version. If - empty, this is the version of the local daemon. - - - -
- -The daemon ships a VERSION response to each client when the -client first connects to it. - -When the C client library parses a response of this kind, it -will assert the VERSION_SET bit in the top-level set member. - -Here's an example: - - -{"class":"VERSION","version":"2.40dev", - "rev":"06f62e14eae9886cde907dae61c124c53eb1101f", - "proto_major":3,"proto_minor":1 -} - - - - - - - -?DEVICES; -Returns a device list object with the -following elements: - -DEVICES object - - - - Name - Always? - Type - Description - - - - - class - Yes - string - Fixed: "DEVICES" - - - devices - Yes - list - List of device descriptions - - - remote - No - string - URL of the remote daemon reporting the device set. If - empty, this is a DEVICES response from the local daemon. - - - -
- -When the C client library parses a response of this kind, it -will assert the DEVICELIST_SET bit in the top-level set member. - -Here's an example: - - -{"class"="DEVICES","devices":[ - {"class":"DEVICE","path":"/dev/pts/1","flags":1,"driver":"SiRF binary"}, - {"class":"DEVICE","path":"/dev/pts/3","flags":4,"driver":"AIVDM"}]} - - -The daemon occasionally ships a bare DEVICE object to the client -(that is, one not inside a DEVICES wrapper). The data content of these -objects will be described later as a response to the ?DEVICE command. - - - - - -?WATCH; - - -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. - -A WATCH object has the following elements: - -WATCH object - - - - Name - Always? - Type - Description - - - - - class - Yes - string - Fixed: "WATCH" - - - enable - No - boolean - Enable (true) or disable (false) watcher mode. Default - is true. - - - json - No - boolean - Enable (true) or disable (false) dumping of JSON reports. - Default is false. - - - nmea - No - boolean - Enable (true) or disable (false) dumping of binary - packets as pseudo-NMEA. Default - is false. - - - raw - No - integer - - Controls 'raw' mode. When this attribute is set to 1 - for a channel, gpsd 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, - gpsd reports the received data verbatim - without hex-dumping. - - - scaled - No - boolean - If true, apply scaling divisors to output before - dumping; default is false. - - - split24 - No - boolean - 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. - - - pps - No - boolean - If true, emit the TOFF JSON message on each cycle and a - PPS JSON message when the device issues 1PPS. Default is false. - - - device - No - string - 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. - - - remote - No - string - URL of the remote daemon reporting the watch set. If - empty, this is a WATCH response from the local daemon. - - - -
- -There is an additional boolean "timing" attribute which is -undocumented because that portion of the interface is considered -unstable and for developer use only. - -In watcher mode, GPS reports are dumped as TPV and SKY -responses. AIS, Subframe and RTCM reporting is described in the next -section. - -When the C client library parses a response of this kind, it -will assert the POLICY_SET bit in the top-level set member. - -Here's an example: - - -{"class":"WATCH", "raw":1,"scaled":true} - - - - - - -?POLL; - - -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. - -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. - -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. - -POLL object - - - - Name - Always? - Type - Description - - - - - class - Yes - string - Fixed: "POLL" - - - time - Yes - Numeric - Timestamp in ISO 8601 format. May have a - fractional part of up to .001sec precision. - - - active - Yes - Numeric - Count of active devices. - - - tpv - Yes - JSON array - Comma-separated list of TPV objects. - - - sky - Yes - JSON array - Comma-separated list of SKY objects. - - - -
- -Here's an example of a POLL response: - - -{"class":"POLL","time":"2010-06-04T10:31:00.289Z","active":1, - "tpv":[{"class":"TPV","device":"/dev/ttyUSB0", - "time":"2010-09-08T13:33:06.095Z", - "ept":0.005,"lat":40.035093060, - "lon":-75.519748733,"track":99.4319,"speed":0.123,"mode":2}], - "sky":[{"class":"SKY","device":"/dev/ttyUSB0", - "time":1270517264.240,"hdop":9.20, - "satellites":[{"PRN":16,"el":55,"az":42,"ss":36,"used":true}, - {"PRN":19,"el":25,"az":177,"ss":0,"used":false}, - {"PRN":7,"el":13,"az":295,"ss":0,"used":false}, - {"PRN":6,"el":56,"az":135,"ss":32,"used":true}, - {"PRN":13,"el":47,"az":304,"ss":0,"used":false}, - {"PRN":23,"el":66,"az":259,"ss":0,"used":false}, - {"PRN":20,"el":7,"az":226,"ss":0,"used":false}, - {"PRN":3,"el":52,"az":163,"ss":32,"used":true}, - {"PRN":31,"el":16,"az":102,"ss":0,"used":false} -]}]} - - - -Client software should not assume the field inventory of the -POLL response is fixed for all time. As -gpsd collects and caches more data from -more sensor types, those data are likely to find their way -into this response. - - - - - - -TOFF - - -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). - -This message exactly mirrors the PPS message except for two -details. - -TOFF emits no NTP precision, this is assumed to be -2. See -the NTP documentation for their definition of precision. - - The TOFF message reports the GPS time as derived from the GPS -serial data stream. The PPS message reports the GPS time as derived -from the GPS PPS pulse. - -A TOFF object has the following elements: - -TOFF object - - - - Name - Always? - Type - Description - - - - - class - Yes - string - Fixed: "TOFF" - - - device - Yes - string - Name of originating device - - - real_sec - Yes - numeric - seconds from the GPS clock - - - real_nsec - Yes - numeric - nanoseconds from the GPS clock - - - clock_sec - Yes - numeric - seconds from the system clock - - - clock_nsec - Yes - numeric - nanoseconds from the system clock - - - -
- -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. - -The message contains two second/nanosecond pairs: real_sec and -real_nsec contain the time the GPS thinks it was at the start of the -current cycle; clock_sec and clock_nsec contain the time the system -clock thinks it was on receipt of the first timing message of the cycle. -real_nsec is always to nanosecond precision. clock_nsec is nanosecond -precision on most systems. - -Here's an example: - - -{"class":"TOFF","device":"/dev/ttyUSB0", - "real_sec":1330212592, "real_nsec":343182, - "clock_sec":1330212592,"clock_nsec":343184, - "precision":-2}} - - - - - - -PPS - - -This message is emitted each time the daemon sees a valid PPS (Pulse -Per Second) strobe from a device. - -This message exactly mirrors the TOFF message except for two -details. - -PPS emits the NTP precision. See the NTP documentation for their -definition of precision. - -The TOFF message reports the GPS time as derived from the GPS -serial data stream. The PPS message reports the GPS time as derived -from the GPS PPS pulse. - -There are various sources of error in the reported clock times. -The speed of the serial connection between the GPS and the system adds -a delay to 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. - -A PPS object has the following elements: - -PPS object - - - - Name - Always? - Type - Description - - - - - class - Yes - string - Fixed: "PPS" - - - device - Yes - string - Name of originating device - - - real_sec - Yes - numeric - seconds from the PPS source - - - real_nsec - Yes - numeric - nanoseconds from the PPS source - - - clock_sec - Yes - numeric - seconds from the system clock - - - clock_nsec - Yes - numeric - nanoseconds from the system clock - - - precision - Yes - numeric - NTP style estimate of PPS precision - - - -
- -This message is emitted once per second to watchers of a device -emitting PPS, and reports the time of the start of the GPS second (when -the 1PPS arrives) and seconds as reported by the system clock (which -may be NTP-corrected) at that moment. - -The message contains two second/nanosecond pairs: real_sec and -real_nsec contain the time the GPS thinks it was at the PPS edge; -clock_sec and clock_nsec contain the time the system clock thinks it was -at the PPS edge. real_nsec is always to nanosecond precision. clock_nsec -is nanosecond precision on most systems. - -There are various sources of error in the reported clock times. -For PPS delivered via a real serial-line strobe, serial-interrupt -latency plus processing time to the timer call should be bounded above -by about 10 microseconds; that can be reduced to less than 1 microsecond if -your kernel supports RFC 2783. USB1.1-to-serial control-line emulation is -limited to about 1 millisecond. seconds. - -Here's an example: - - -{"class":"PPS","device":"/dev/ttyUSB0", - "real_sec":1330212592, "real_nsec":343182, - "clock_sec":1330212592,"clock_nsec":343184, - "precision":-3} - - - - - - -OSC - - -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). - -An OSC object has the following elements: - -OSC object - - - - Name - Always? - Type - Description - - - - - class - Yes - string - Fixed: "OSC" - - - device - Yes - string - Name of originating device. - - - running - Yes - boolean - If true, the oscillator is currently running. Oscillators may require warm-up time at start of day. - - - reference - Yes - boolean - If true, the oscillator is receiving a GPS PPS signal. - - - disciplined - Yes - boolean - If true, the GPS PPS signal is sufficiently stable and is being used to discipline the local oscillator. - - - delta - Yes - numeric - The time difference (in nanoseconds) between the GPS-disciplined oscillator PPS output pulse and the most recent GPS PPS input pulse. - - - -
- -Here's an example: - - -{"class":"OSC","running":true,"device":"/dev/ttyUSB0", - "reference":true,"disciplined":true,"delta":67} - - - - - -?DEVICE - - -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. - -Pay attention to the response, because it is -possible for this command to fail if the GPS does not support a -speed-switching command or only supports some combinations of -serial modes. In case of failure, the daemon and GPS will -continue to communicate at the old speed. - -Use the parameter-setting form with caution. On USB and -Bluetooth GPSes it is also possible for serial mode setting to fail -either because the serial adaptor chip does not support non-8N1 modes -or because the device firmware does not properly synchronize the -serial adaptor chip with the UART on the GPS chipset when the speed -changes. These failures can hang your device, possibly requiring a GPS -power cycle or (in extreme cases) physically disconnecting the NVRAM -backup battery. - -A DEVICE object has the following elements: - -DEVICE object - - - - Name - Always? - Type - Description - - - - - class - Yes - string - Fixed: "DEVICE" - - - path - No - string - 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. - - - activated - No - string - Time the device was activated as an ISO8601 - timestamp. If the device is inactive this attribute is - absent. - - - flags - No - integer - 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 - gpsd has seen identifiable packets - from the device. - - - driver - No - string - GPSD's name for the device driver type. Won't be reported before - gpsd has seen identifiable packets - from the device. - - - subtype - When the daemon sees a delayed response to a probe for - subtype or firmware-version information. - string - Whatever version information the device returned. - - - bps - No - integer - Device speed in bits per second. - - - parity - No - string - N, O or E for no parity, odd, or even. - - - stopbits - Yes - string - Stop bits (1 or 2). - - - native - No - integer - 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. - - - cycle - No - real - Device cycle time in seconds. - - - mincycle - No - real - Device minimum cycle time in seconds. Reported from - ?DEVICE when (and only when) the rate is switchable. It is - read-only and not settable. - - - -
- -The serial parameters will (bps, parity, stopbits) be omitted in -a response describing a TCP/IP source such as an Ntrip, DGPSIP, or AIS -feed; on a serial device they will always be present. - -The contents of the flags field should be interpreted as follows: - -Device flags - - - - C #define - Value - Description - - - - - SEEN_GPS - 0x01 - GPS data has been seen on this device - - - SEEN_RTCM2 - 0x02 - RTCM2 data has been seen on this device - - - SEEN_RTCM3 - 0x04 - RTCM3 data has been seen on this device - - - SEEN_AIS - 0x08 - AIS data has been seen on this device - - - -
- - - -When the C client library parses a response of this kind, it -will assert the DEVICE_SET bit in the top-level set member. - -Here's an example: - - -{"class":"DEVICE","bps":4800,"parity":"N","stopbits":1,"native":0} - - - - - - - -When a client is in watcher mode, the daemon will ship it DEVICE -notifications when a device is added to the pool or -deactivated. - -When the C client library parses a response of this kind, it -will assert the DEVICE_SET bit in the top-level set member. - -Here's an example: - - -{"class":"DEVICE","path":"/dev/pts1","activated":0} - - -The daemon may ship an error object in response to a -syntactically invalid command line or unknown command. It has -the following elements: - -ERROR notification object - - - - Name - Always? - Type - Description - - - - - class - Yes - string - Fixed: "ERROR" - - - message - Yes - string - Textual error message - - - -
- -Here's an example: - - -{"class":"ERROR","message":"Unrecognized request '?FOO'"} - - -When the C client library parses a response of this kind, it -will assert the ERR_SET bit in the top-level set member. - - - -RTCM2 - -RTCM-104 is a family of serial protocols used for broadcasting pseudorange -corrections from differential-GPS reference stations. Many GPS receivers can -accept these corrections to improve their reporting accuracy. - -RTCM-104 comes in two major and incompatible flavors, 2.x and -3.x. Each major flavor has minor (compatible) revisions. - -The applicable standard for RTCM Version 2.x is RTCM -Recommended Standards for Differential NAVSTAR GPS Service -RTCM Paper 194-93/SC 104-STD. For RTCM 3.1 it is RTCM Paper -177-2006-SC104-STD. Ordering instructions for both -standards are accessible from the website of the Radio Technical Commission for Maritime -Services under "Publications". - -RTCM WIRE TRANSMISSIONS - -Differential-GPS correction stations consist of a GPS reference -receiver coupled to a low frequency (LF) transmitter. The GPS -reference receiver is a survey-grade GPS that does GPS carrier -tracking and can work out its own position to a few millimeters. It -generates range and range-rate corrections and encodes them into -RTCM104. It ships the RTCM104 to the LF transmitter over serial rs-232 -signal at 100 baud or 200 baud depending on the requirements of the -transmitter. - -The LF transmitter broadcasts the approximately 300khz radio -signal that differential-GPS radio receivers pick up. Transmitters -that are meant to have a higher range will need to transmit at the -slower rate. The higher the data rate the harder it will be for the -remote radio receiver to receive with a good signal-to-noise ration. -(Higher data rate signals can't be averaged over as long a time frame, -hence they appear noisier.) - - -RTCM WIRE FORMATS - -An RTCM 2.x message consists of a sequence of up to 33 30-bit -words. The 24 most significant bits of each word are data and the six -least significant bits are parity. The parity algorithm used is the -same ISGPS-2000 as that used on GPS satellite downlinks. Each RTCM -2.x message consists of two header words followed by zero or more data -words, depending upon message type. - -An RTCM 3.x message begins with a fixed leader byte 0xD3. That -is followed by six bits of version information and 10 bits of payload -length information. Following that is the payload; following the -payload is a 3-byte checksum of the payload using the Qualcomm CRC-24Q -algorithm. - - -RTCM2 JSON FORMAT - -Each RTCM2 message is dumped as a single JSON object per -message, with the message fields as attributes of that object. Arrays -of satellite, station, and constellation statistics become arrays of -JSON sub-objects. Each sentence will normally also have a "device" -field containing the pathname of the originating device. - -All attributes other than the device field are mandatory. Header -attributes are emitted before others. - -Header portion - -SKY object - - - - Name - Type - Description - - - - - class - string - Fixed: "RTCM2". - - - type - integer - Message type (1-9). - - - station_id - integer - The id of the GPS reference receiver. The - LF transmitters also have (different) id numbers. - - - zcount - real - 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 table of leap second - corrections). - - - seqnum - integer - Sequence number. Only 3 bits wide, wraps after 7. - - - length - integer - The number of words after the header that comprise the - message. - - - station_health - integer - 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. - - - -
- -<message type> is one of - - - -1 -full corrections - one message containing corrections for -all GPS satellites in view. This is not common. - - - -3 -reference station parameters - the position of the -reference station GPS antenna. - - - -4 -datum — the datum to which the DGPS data is -referred. - - - -5 -constellation health — information about the -satellites the beacon can see. - - - -6 -null message — just a filler. - - - -7 -radio beacon almanac — information about this or other beacons. - - - -9 -subset corrections — a message containing corrections -for only a subset of the GPS satellites in view. - - - -16 -special message — a text message from the beacon -operator. - - - -31 -GLONASS subset corrections — a message -containing corrections for a set of the GLONASS satellites in -view. - - - - - - -Type 1 and 9: Correction data - -One or more satellite objects follow the header for type 1 or type 9 -messages. Here is the format: - -Satellite object - - - - Name - Type - Description - - - - - ident - integer - The PRN number of the satellite for which this is - correction data. - - - udre - integer - User Differential Range Error (0-3). See the - table following for values. - - - iod - integer - 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. - - - prc - real - 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. - - - rrc - real - 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. - - - -
- -User Differential Range Error values are as follows: - -UDRE values - - -01-sigma error <= 1m -11-sigma error <= 4m -21-sigma error <= 8m -31-sigma error > 8m - - -
- -Here's an example: - - -{"class":"RTCM2","type":1, - "station_id":688,"zcount":843.0,"seqnum":5,"length":19,"station_health":6, - "satellites":[ - {"ident":10,"udre":0,"iod":46,"prc":-2.400,"rrc":0.000}, - {"ident":13,"udre":0,"iod":94,"prc":-4.420,"rrc":0.000}, - {"ident":7,"udre":0,"iod":22,"prc":-5.160,"rrc":0.002}, - {"ident":2,"udre":0,"iod":34,"prc":-6.480,"rrc":0.000}, - {"ident":4,"udre":0,"iod":47,"prc":-8.860,"rrc":0.000}, - {"ident":8,"udre":0,"iod":76,"prc":-7.980,"rrc":0.002}, - {"ident":5,"udre":0,"iod":99,"prc":-8.260,"rrc":0.002}, - {"ident":23,"udre":0,"iod":81,"prc":-8.060,"rrc":0.000}, - {"ident":16,"udre":0,"iod":70,"prc":-11.740,"rrc":0.000}, - {"ident":30,"udre":0,"iod":4,"prc":-18.960,"rrc":-0.006}, - {"ident":29,"udre":0,"iod":101,"prc":-24.960,"rrc":-0.002} -]} - - - -Type 3: Reference Station Parameters - -Here are the payload members of a type 3 (Reference Station -Parameters) message: - -Reference Station Parameters - - - - Name - Type - Description - - - - - x - real - ECEF X coordinate. - - - y - real - ECEF Y coordinate. - - - z - real - ECEF Z coordinate. - - - -
- -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. - -An invalid reference message is represented by a type 3 header -without payload fields. - -Here's an example: - - -{"class":"RTCM2","type":3, - "station_id":652,"zcount":1657.2,"seqnum":2,"length":4,"station_health":6, - "x":3878620.92,"y":670281.40,"z":5002093.59 -} - - - -Type 4: Datum - -Here are the payload members of a type 4 (Datum) message: - -Datum - - - - Name - Type - Description - - - - - dgnss_type - string - Either "GPS", "GLONASS", "GALILEO", or - "UNKNOWN". - - - dat - integer - 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. - - - datum_name - string - A standard name for the datum. - - - - dx - real - X offset. - - - dy - real - Y offset. - - - dz - real - Z offset. - - - -
- -<dx> <dy> <dz> are offsets to convert from -local datum to GNSS datum or vice versa. These fields are -optional. - -An invalid datum message is represented by a type 4 header -without payload fields. - - -Type 5: Constellation Health - -One or more of these follow the header for type 5 messages — one -for each satellite. - -Here is the format: - -Constellation health - - - - Name - Type - Description - - - - - ident - integer - The PRN number of the satellite. - - - iodl - bool - True indicates that this information relates to - the satellite information in an accompanying type 1 or type 9 - message. - - - health - integer - 0 indicates that the satellite is healthy. Any other value - indicates a problem (coding is not known). - - - snr - integer - The carrier/noise ratio of the received signal in - the range 25 to 55 dB(Hz). - - - health_en - bool - If set to True it indicates that the satellite is - healthy even if the satellite navigation data says it is - unhealthy. - - - new_data - bool - True indicates that the IOD for this satellite will - soon be updated in type 1 or 9 messages. - - - los_warning - bool - Line-of-sight warning. True indicates that the - satellite will shortly go unhealthy. - - - tou - integer - Healthy time remaining in seconds. - - - -
- - -Type 6: Null - -This just indicates a null message. There are no payload fields. - - -Unknown message - -This format is used to dump message words in hexadecimal when the -message type field doesn't match any of the known ones. - -Here is the format: - -Unknown Message - - - - Name - Type - Description - - - - - data - list - A list of strings. - - - -
- -Each string in the array is a hex literal representing 30 bits -of information, after parity checks and inversion. The high two bits -should be ignored. - - -Type 7: Radio Beacon Almanac - -Here is the format: - -Contellation health - - - - Name - Type - Description - - - - - lat - real - Latitude in degrees, of the LF transmitter - antenna for the station for which this is an almanac. North - is positive. - - - lon - real - Longitude in degrees, of the LF transmitter - antenna for the station for which this is an almanac. - East is positive. - - - range - integer - Published range of the station in km. - - - frequency - real - Station broadcast frequency in kHz. - - - health - integer - <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. - - - - - station_id - integer - 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. - - - bitrate - integer - The transmitted bitrate. - - - -
- -Here's an example: - - -{"class":"RTCM2","type":9,"station_id":268,"zcount":252.6, - "seqnum":4,"length":5,"station_health":0, - "satellites":[ - {"ident":13,"udre":0,"iod":3,"prc":-25.940,"rrc":0.066}, - {"ident":2,"udre":0,"iod":73,"prc":0.920,"rrc":-0.080}, - {"ident":8,"udre":0,"iod":22,"prc":23.820,"rrc":0.014} -]} - - - -Type 13: GPS Time of Week - -Here are the payload members of a type 13 (Groumf Tramitter Parameters) -message: - -Grund Transmitter Parameters - - - - Name - Type - Description - - - - - status - bool - If True, signals user to expect a type 16 explanatory - message associated with this station. Probably indicates some - sort of unusual event. - - - rangeflag - bool - 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. - - - lat - real - Degrees latitude, signed. - Positive is N, negative is S. - - - lon - real - Degrees longitude, signed. - Positive is E, negative is W. - - - range - integer - Transmission range in km (1-1024). - - - -
- -This message type replaces message type 3 (Reference Station Parameters) -in RTCM 2.3. - - -Type 14: GPS Time of Week - -Here are the payload members of a type 14 (GPS Time of Week) -message: - -Reference Station Parameters - - - - Name - Type - Description - - - - - week - integer - GPS week (0-123). - - - hour - integer - Hour of week (0-167). - - - leapsecs - integer - Leap Seconds (0-63). - - - -
- -Here's an example: - - -{"class":"RTCM2","type":14,"station_id":652,"zcount":1657.2, - "seqnum":3,"length":1,"station_health":6,"week":601,"hour":109, - "leapsecs":15} - - - -Type 16: Special Message - -Special Message - - - - Name - Type - Description - - - - - message - string - A text message sent by the beacon operator. - - - -
- - -Type 31: Correction data - -One or more GLONASS satellite objects follow the header for type -1 or type 9 messages. Here is the format: - -Satellite object - - - - Name - Type - Description - - - - - ident - integer - The PRN number of the satellite for which this is - correction data. - - - udre - integer - User Differential Range Error (0-3). See the - table following for values. - - - change - boolean - Change-of-ephemeris bit. - - - tod - uinteger - Count of 30-second periods since the top of the - hour. - - - prc - real - 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. - - - rrc - real - 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. - - - -
- -Here's an example: - - -{"class":"RTCM2","type":31,"station_id":652,"zcount":1642.2, - "seqnum":0,"length":14,"station_health":6, - "satellites":[ - {"ident":5,"udre":0,"change":false,"tod":0,"prc":132.360,"rrc":0.000}, - {"ident":15,"udre":0,"change":false,"tod":0,"prc":134.840,"rrc":0.002}, - {"ident":14,"udre":0,"change":false,"tod":0,"prc":141.520,"rrc":0.000}, - {"ident":6,"udre":0,"change":false,"tod":0,"prc":127.000,"rrc":0.000}, - {"ident":21,"udre":0,"change":false,"tod":0,"prc":128.780,"rrc":0.000}, - {"ident":22,"udre":0,"change":false,"tod":0,"prc":125.260,"rrc":0.002}, - {"ident":20,"udre":0,"change":false,"tod":0,"prc":117.280,"rrc":-0.004}, - {"ident":16,"udre":0,"change":false,"tod":17,"prc":113.460,"rrc":0.018} -]} - - - - - - -RTCM3 DUMP FORMAT - -The support for RTCM104v3 dumping is incomplete and buggy. Do not -attempt to use it for production! Anyone interested in it should read -the source code. - - -AIS DUMP FORMATS - -AIS support is an extension. It may not be present if your -instance of gpsd has been built with -a restricted feature set. - -AIS packets are dumped as JSON objects with class "AIS". Each -AIS report object contains a "type" field giving the AIS message type -and a "scaled" field telling whether the remainder of the fields are -dumped in scaled or unscaled form. (These will be emitted before any -type-specific fields.) It will also contain a "device" field naming -the data source. Other fields have names and types as specified in -the AIVDM/AIVDO Protocol Decoding document on -the GPSD project website; each message field table may be directly -interpreted as a specification for the members of the corresponding -JSON object type. - -By default, certain scaling and conversion operations are -performed for JSON output. Latitudes and longitudes are scaled to -decimal degrees rather than the native AIS unit of 1/10000th of a -minute of arc. Ship (but not air) speeds are scaled to knots rather -than tenth-of-knot units. Rate of turn may appear as "nan" if is -unavailable, or as one of the strings "fastright" or "fastleft" if it -is out of the AIS encoding range; otherwise it is quadratically mapped -back to the turn sensor number in degrees per minute. Vessel draughts -are converted to decimal meters rather than native AIS -decimeters. Various other scaling conversions are described in -"AIVDM/AIVDO Protocol Decoding". - - -SUBFRAME DUMP FORMATS - -Subframe support is always compiled into -gpsd but many GPSes do not output subframe data -or the gpsd driver may not support subframes. - - -Subframe packets are dumped as JSON objects with class "SUBFRAME". -Each subframe report object contains a "frame" field giving the subframe -number, a "tSV" field for the transmitting satellite number, a "TOW17" -field containing the 17 MSBs of the start of the next 12-second message -and a "scaled" field telling whether the remainder of the fields are -dumped in scaled or unscaled form. It will also contain a "device" field -naming the data source. Each SUBFRAME object will have a sub-object -specific to that subframe page type. Those sub-object fields have names -and types similar to those specified in the IS-GPS-200E document; each -message field table may be directly interpreted as a specification for -the members of the corresponding JSON object type. - - - -SEE ALSO - -gpsd8, -libgps3, - - - -AUTHOR - -The protocol was designed and documented by Eric S. Raymond. - - - diff --git a/gpsdctl.xml b/gpsdctl.xml deleted file mode 100644 index d47128c9..00000000 --- a/gpsdctl.xml +++ /dev/null @@ -1,81 +0,0 @@ - - - - -25 Jun 2011 - -gpsdctl -8 -The GPSD Project -GPSD Documentation - - -gpsdctl -tool for sending commands to gpsd over its control socket - - - - - gpdsctl - action - device - - - -DESCRIPTION - -This is a tool for sending an instance of -gpsd 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. - -The action argument may be "add" or "remove". If no daemon -instance is running when an add is requested, this program will launch -one. - -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. - -Two environment variables are -interpreted. GPSD_SOCKET sets the location of the -control socket. It defaults to -/var/run/gpsd.sock if the effective user ID of -this program is root, /tmp/gpsd.sock -otherwise. - -GPSD_OPTIONS -may be a list of options to be passed to gpsd -when this tool launches it. It defaults to an empty string. - - -RETURN VALUES - -1 if the action was unknown or the write to the control socket -failed, 0 otherwise - - - -SEE ALSO - -gpsd8, -gpsctl1, -gps1, -libgps3, -libgpsmm3, -gpsprof1, -gpsfake1. - - - -AUTHOR - -Eric S. Raymond esr@thyrsus.com. - - diff --git a/gpsdecode.xml b/gpsdecode.xml deleted file mode 100644 index b7368dc7..00000000 --- a/gpsdecode.xml +++ /dev/null @@ -1,147 +0,0 @@ - - - - -13 Jul 2005 - -gpsdecode -1 -The GPSD Project -GPSD Documentation - - -gpsdecode -decode GPS, RTCM or AIS streams into a readable format - - - - - gpsdecode - -c - -d - -e - -j - -m - -n - -s - -t typelist - -u - -v - -D debuglevel - -V - - - -DESCRIPTION - -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 -gpsd8; -this tool uses the same decoding logic as gpsd, but with a simpler -interface intended for batch processing of data files. - -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 -gpsd8 -for applicable standards and known limitations of the decoding -logic. - -You can use this tool with -nc1 -to examine AIS feeds from AIS pooling services, RTCM feeds from RTCM -receivers or NTRIP broadcasters. - - -OPTIONS - -The option tells the program to decode -packets presented on standard input to standard output. This is the -default behavior. - -The explicitly sets the output dump format -to JSON (the default behavior). - -With the option, dump minimum lengths for -each packet type in the input (ignoring comment packets). This is -probably of interest only to GSD developers. - -The enables dumping in generated -pseudo-NME0183. - -The 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. - -The option option tells the program to report -AIS Type 24 sentence halves separately rather than attempting to -aggregate them. - -The 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. - -The suppresses scaling of AIS data to float -quantities and text expansion of numeric codes. A dump with this -option is lossless. - -The enables dumping of textual packets -to output as they are received on input, immediately preceding -corresponding output. - -The 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 - -The option directs the program to emit its -version number, then exit. - -The option sets a debug verbosity level. It is -mainly of interest to developers. - - -AIS DSV FORMAT - -With the 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. - - -SEE ALSO - -gpsd8, -gpsctl1, -gpsdctl8, -gps1, -libgps3, -libgpsmm3, -gpsprof1, -gpsfake1, - - -AUTHOR - -Eric S. Raymond esr@thyrsus.com. - - - diff --git a/gpsfake.xml b/gpsfake.xml deleted file mode 100644 index e8331d47..00000000 --- a/gpsfake.xml +++ /dev/null @@ -1,264 +0,0 @@ - - - - -12 Feb 2005 - -gpsfake -1 -The GPSD Project -GPSD Documentation - - -gpsfake -test harness for gpsd, simulating a GPS - - - - - gpsfake - -1 - -h - -b - -c interval - -i - -D debuglevel - -l - -m monitor - -g - -n - -o options - -p - -P port - -q - -r initcmd - -s speed - -S - -u - -t - -T - -v - - logfile - - - - -DESCRIPTION - -gpsfake is a test harness for -gpsd and its clients. It opens a pty -(pseudo-TTY), launches a gpsd 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. - -gpsfake does not require root -privileges, and can be run concurrently with a production -gpsd instance without causing problems. - -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: - - - -a comment of the form #Date: yyyy-mm-dd (ISO8601 date format) may be -used to set the initial date for the log. - - - -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. - - - -a comment of the form #Transport: UDP may be used to fake a UDP source -rather than the normal pty. - - - -The gpsd instance is run in -foreground. The thread sending fake GPS data to the daemon -is run in background. - - -OPTIONS - -With the -1 option, the logfile is interpreted once only rather -than repeatedly. This option is intended to facilitate regression -testing. - -The enables a twirling-baton progress indicator -on standard error. At termination, it reports elapsed time. - -The sets the delay between sentences in -seconds. Fractional values of seconds are legal. The default is zero -(no delay). - -The 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. - -The 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 gpsd. - -The specifies a monitor program inside which the -daemon should be run. This option is intended to be used with -valgrind1, -gdb1 -and similar programs. - -The uses the monitor facility to run the -gpsd instance within gpsfake under control -of gdb. - -The 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 passes a -D -option to the daemon: thus -D 4 is shorthand for -o "-D 4". - -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. - -The -P ("port") option sets the daemon's listening port. - -The tells gpsfake to suppress normal progress -output and thus act in a quiet manner. - -The specifies an initialization command to use in pipe mode. -The default is ?WATCH={"enable":true,"json":true}. - -The sets the baud rate for the slave tty. The -default is 4800. - -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. - -The 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. - -The makes gpsfake print -some system information and then exits. - -The 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. - -The enables verbose progress reports to stderr. It is -mainly useful for debugging gpsfake -itself. - -The dumps packets as -gpsfake gathers them. It is mainly useful -for debugging gpsfake itself. - -The makes gpsfake print -a usage message and exit. - -The argument must be the name of a file containing the -data to be cycled at the device. gpsfake -will print a notification each time it cycles. - -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: tcpdump -s0 -n -A -i lo udp and port 5000. - - -MAGIC COMMENTS - -Certain magic comments in test load headers can change the -conditions of the test. These are: - - - -Serial: -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. - - -Transport: -Values 'TCP' and 'UDP' force the use of TCP and -UDP feeds respectively (the default is a pty). - - -Delay-Cookie: -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. - - - - - -CUSTOM TESTS - -gpsfake is a trivial wrapper around a -Python module, also named gpsfake, that can be used to fully script -sessions involving a gpsd instance, any -number of client sessions, and any number of fake GPSes feeding the -daemon instance with data from specified sentence logs. - -Source and embedded documentation for this module is shipped with the -gpsd development tools. You can use it to -torture-test either gpsd itself or any -gpsd-aware client application. - -Logfiles for the use with gpsfake can -be retrieved using gpspipe, -gpscat, or -gpsmon from the gpsd distribution, or any -other application which is able to create a compatible output. - -If gpsfake 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 - - -SEE ALSO - -gpsd8, -gps1, -libgps3, -libgpsmm3, -gpsctl1, -gpspipe1, -gpsprof1 -gpsmon1. - - - -AUTHOR - -Eric S. Raymond esr@thyrsus.com. - - - - - diff --git a/gpsinit.xml b/gpsinit.xml deleted file mode 100644 index a3750023..00000000 --- a/gpsinit.xml +++ /dev/null @@ -1,170 +0,0 @@ - - - - -18 Jan 2013 - -gpsinit -8 -The GPSD Project -GPSD Documentation - - -gpsinit -initialize CAN kernel modules for GPSD - - - - - gpsinit - -n control - -s speed - module_name - interface_name - - - gpsinit - -h - - - gpsinit - -v - - - -DESCRIPTION - -gpsinit 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. - -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. - -The program accepts the following options: - - - --h - -Display a brief help text. - - - - --v - -Display the version of gpsinit. - - - - --n - -Set the CAN network number. The default is 0. - - - - --s - -Set the baudrate to be used to communicate over the serial line -to the CAN hardware. The default is 38400 baud. - - - - -The parameter module_name is mandatory. The -socket CAN driver module module_name.ko will be -loaded. gpsinit recognize the following module -names: - - - -plx_pci -esd_usb2 -vcan -slcan - - -The parameter interface_name and -s -speed can used here. - - - -beaglebone - - The dcan module needed for the beaglebone is part of the Linux kernel, -so no module is loaded in this case. - - - - - -The parameter interface_name 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. - - - -EXAMPLES - - - -sudo gpsinit plx_pci - -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. - - - -sudo gpsinit -n 1 plx_pci - -As above, but use net 1. - - - -sudo gpsinit -s 38400 slcan /dev/ttyUSB0 - -Attempt to load the module slcan and talk to the hardware at -38400 baud connected to port /dev/ttyUSB0. - - - - -gpsinit -h - -Display a brief help message. - - - -gpsinit -v - -Display the version of gpsinit. - - - - - -SEE ALSO - -gpsd8, -gps1, -libgps3, -libgpsmm3. - - - -AUTHOR -Reinhard Arlt reinhard.arlt@t-online.de. - - diff --git a/gpsmon.xml b/gpsmon.xml deleted file mode 100644 index f33b5f15..00000000 --- a/gpsmon.xml +++ /dev/null @@ -1,428 +0,0 @@ - - - - -17 Feb 2009 - -gpsmon -1 -The GPSD Project -GPSD Documentation - - -gpsmon -real-time GPS packet monitor and control utility - - - - - gpsmon - -L - -V - -h - -n - -a - -l logfile - -t driver-prefix - - - - server - - :port - :device - - - device - - - -D debuglevel - - - -DESCRIPTION - -gpsmon 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. - -gpsmon 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. - -Unlike gpsd, -gpsmon 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 or -the t to work around this. - -gpsmon 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. - -gpsmon accepts an -h option that -displays a usage message, or a -V option to dump the package -version and exit. - -This program may be run in either of two modes, as a client for -the gpsd 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 gpsmon -will hunt for a correct baud rate and lock on to it -automatically. Possible cases look like this: - - - -localhost:/dev/ttyS1 -Look at the default port of localhost, trying both -IPv4 and IPv6 and watching output from serial device 1. - - -example.com:2317 -Look at port 2317 on example.com, trying both -IPv4 and IPv6. - - -71.162.241.5:2317:/dev/ttyS3 -Look at port 2317 at the specified IPv4 -address, collecting data from attached serial device 3. - - -[FEDC:BA98:7654:3210:FEDC:BA98:7654:3210]:2317:/dev/ttyS5 -Look at port 2317 at the specified IPv6 -address, collecting data from attached serial device 5. - - - -Unlike gpsd, -gpsmon 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. - -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. - -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. - -The -L option lists a table showing which GPS device types -gpsmon 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. - -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. - -The -n option forces gpsmon to request NMEA0183 packets instead of the -raw datastream from gpsd. - -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. - -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. - -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. - -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. - - -COMMANDS - -The following device-independent commands are available while -gpsmon is running: - - - - -i - -(Direct mode only.) Enable/disable subtype probing and -reinitialize the driver. In normal operation, -gpsmon 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 gpsd 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. - -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 n command. This is due to a -limitation in the SiRF firmware that we can't fix. - -This command will generally do nothing after the first time you -use it, because the device type will already have been discovered. - - - - -c - -(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. - - - - -l - -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. - - - - -n - -(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. - -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. - - - - -q - -Quit gpsmon. Control-C, or whatever -your current interrupt character is, works as well. - - - - -s - -(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. - -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. - - - - -t - -(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 -gpsmon support; -gpsmon 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 gpsmon. - - - - -x - -(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 of -gpsctl1. - - - - -X - -(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. - - - - -Ctrl-S - -Freeze display, suspend scrolling in debug window. - - - -Ctrl-Q - -Unfreeze display, resume normal operation. - - - - -NMEA support - -(These remarks apply to not just generic NMEA devices -but all extended NMEA devices for which -gpsmon presently has support.) - -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. - -There are no device-specific commands. Which generic -commands are available may vary by type: examine the output -of gpsmon -l to learn more. - - -SiRF support -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. - -The following commands are supported for SiRF GPSes only: - - - -A - -(Direct mode only.) Toggle reporting of 50BPS subframe data. - - - -M - -(Direct mode only.) Set (M1) or clear (M0) static -navigation. The SiRF documentation says 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. - -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. - - - -P - -(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. - - - - -To interpret what you see, you will need a copy of the -SiRF Binary Protocol Reference Manual. - - -u-blox support -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. - - - -BUGS AND LIMITATIONS - -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. - - - - -SEE ALSO - -gpsd8, -gpsdctl8, -gps1, -libgps3, -libgpsmm3, -gpsprof1, -gpsfake1, -gpsctl1, -gpscat1. -gpspipe1. - - - -AUTHOR - -Eric S. Raymond esr@thyrsus.com. - - - - diff --git a/gpspipe.xml b/gpspipe.xml deleted file mode 100644 index 9c5da4f3..00000000 --- a/gpspipe.xml +++ /dev/null @@ -1,185 +0,0 @@ - - - - - - 17 Jun 2018 - - - gpspipe - 1 - The GPSD Project - GPSD Documentation - - - gpspipe - tool to connect to gpsd and retrieve sentences - - - - gpspipe - -2 - -d - -D debug-level - - -h - -l - -n count - - -o filename - - -p - -r - -R - -S - -s serial-device - - -t - -T timestamp-format - - -u - -v - -w - -x - - server - - :port - - :device - - - - - - - DESCRIPTION - - gpspipe is a tool to connect -to gpsd and output the received -sentences to stdout. This makes the program useful as a pipe from -gpsd to another program or file. - - gpspipe does not require root -privileges, and can be run concurrently with other tools connecting -to the local gpsd without causing problems. - The output will consist of one or both of the raw NMEA or native -gpsd sentences. Each line can be optionally -time stamped. There is also an option to exit gracefully after a -given count of packets. - Optionally a server, TCP/IP port number and remote device can be given. -If omitted, gpspipe connects to localhost on -the default port (2947) and watches all devices opened by -gpsd. - - gpspipe may be run as a daemon, but -requires the -o flag for writing the output to a file. - - - OPTIONS - -2 sets the split24 flag on AIS reports. Note: this option -is experimental and may be changed or removed in a future release. - -d causes gpspipe to run as a daemon. - -h makes gpspipe print -a usage message and exit. - -l causes gpspipe 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. - -n [count] causes [count] sentences to be output. -gpspipe will then exit gracefully. - -o option causes the collected data to be written to the -specified file. Use of this option is mandatory -if gpspipe is run as a daemon. - -p enables dumping of profiling information in JSON. - -P enables dumping of PPS drift JSON in NMEA and raw modes. - -r causes raw NMEA sentences to be output. - -R causes super-raw (gps binary) data to be output. This overrides -NMEA and gpsd output modes. - -s option causes the collected data to be written to the -specified serial device with settings 4800 8N1. Thus -gpspipe can be used with -s and -r options -to emulate a serial port hardwired to a GPS that -gpsd is managing. - -S sets the scaled flag. - -t adds a timestamp to each sentence output. - -T sets the format of the timestamp. See - - strftime - 3 - -for the available placeholders. Setting this option implies -t. -Default setting is "%F %T" - -u usec resolution time stamp, implies -t. Use -uu to output sec.usec. - -v causes gpspipe 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. - -V prints the version, then exits. - -w causes native gpsd sentences to be -output. - -x [seconds] Exit after delay of [seconds]. - At least one of -R, -r or -w must be specified. - - - EXAMPLES - When gpsd is running, - gpspipe --r -n 100 will send one hundred raw NMEA sentences to -standard output, then exit. - When gpsd is running, gpspipe --x 5 -w|sed -n '/TPV/{p;q}' will wait at most 5 seconds for a -TPV message, print it to stdout, then exit. - - - SEE ALSO - - - gpsd - 8 - , - - gps - 1 - , - - libgps - 3 - , - - libgpsmm - 3 - , - - gpsprof - 1 - , - - gpsfake - 1 - , - - gpsctl - 1 - , - - gpscat - 1 - . - - gpsmon - 1 - . - - - - AUTHOR - Gary E. Miller gem@rellim.com. - - diff --git a/gpsprof.xml b/gpsprof.xml deleted file mode 100644 index bdc22691..00000000 --- a/gpsprof.xml +++ /dev/null @@ -1,291 +0,0 @@ - - - - -30 May 2018 - -gpsprof -1 -The GPSD Project -GPSD Documentation - - -gpsprof -profile a GPS and gpsd, plotting latency information - - - - - gpsprof - -D debuglevel - -d dumpfile - -f plot_type - -h - -l logfile - -m threshold - -n samplecount - -r - -S subtitle - -T terminal - -t title - [server[:port[:device]]] - - - -DESCRIPTION - -gpsprof 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. - -Information from the default spatial plot it provides can be -useful for characterizing position accuracy of a GPS. - -gpsprof uses instrumentation built -into gpsd. It can read data from a local -or remote running gpsd. Or it can read -data from a saved logfile. - -gpsprof is designed to be lightweight -and use minimal host resources. No graphics subsystem needs to be -installed on the host running gpsprof. Simply -copy the resultant plot file to another host to be rendered -with gnuplot. - - - -OPTIONS - -The -f option sets the plot type. Currently the following plot -types are defined: - - - -space - -Generate a scatterplot of fixes and plot probable error circles. -This data is only meaningful if the GPS is held stationary while -gpsprof is running. Various statistics about -the fixes are listed at the bottom. This is the default plot type. - - - -polar - -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. - - - - - -polarunused - -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. - - - - -polarused - -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. - - - - -time - -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 gpsd was -built with the timing (latency timing support) configure option -enabled. - - - - -instrumented - -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 gpsd was built -with the timing (latency timing support) configuration option enabled. - -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. - -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. - -The components of the instrumented plot are as follows: - - - -Fix latency - -Delta between GPS time and SORC. - - - -RS232 time - -RS232 transmission time for data shipped during the cycle -(computed from character volume and baud rate). - - - -Analysis time - -EORC, minus SORC, minus RS232 time. The amount of real time the daemon -spent on computation rather than I/O. - - - -Reception time - -Shipping time from -the daemon to when it was received by gpsprof. - - - - -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. - - - - -uninstrumented - -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. - - - - - -The -d option dumps the plot data, without attached gnuplot -code, to a specified file for post-analysis. - -The -D sets debug level. - -The -h option makes gpsprof print -a usage message and exit. - -The -l option dumps the raw JSON reports collected from the device -to a specified file. - -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. - -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. - -The -S option sets a text string to be included in the plot -as a subtitle. This will be below the title. - -The -t option sets a text string to be the plot title. This -will replace the default title. - -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. - Different installations of gnuplot 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. - - -SIGNALS -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. - - -EXAMPLES -To display the graph, use -gnuplot1. -Thus, for example, to display the default spatial scatter plot, do -this: - - -gpsprof | gnuplot -persist - - - -To generate an image file: - - -gpsprof -T png | gnuplot > image.png - - - -To generate a polar plot, and save the GPS data for further plots: - -gpsprof -f polar -T jpeg -l polar.json | gnuplot > polar.png - -Then to make the matching polarused and polarunused plots and pngs from -the just saved the GPS data: - -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 - - - - -SEE ALSO - -gpsd8, -gps1, -libgps3, -libgpsmm3, -gpsfake1, -gpsctl1, -gpscat1, -gnuplot1. - - - -AUTHOR - -Eric S. Raymond esr@thyrsus.com. - - - - - diff --git a/gpsrinex.xml b/gpsrinex.xml deleted file mode 100644 index 59632f5a..00000000 --- a/gpsrinex.xml +++ /dev/null @@ -1,195 +0,0 @@ - - - - - 09 Nov 2018 - - - gpsrinex - 1 - The GPSD Project - GPSD Documentation - - - gpsrinex - Read data from gpsd convert to RINEX3 and save to a file. - - - - gpsrinex - -D debuglevel - -f filename - -h - -i interval - -n count - -V - - server - - :port - - :device - - - - - - - DESCRIPTION - - gpsrinex is a tool to connect to -gpsd and output the received raw measurements -as a RINEX 3 observation file. This is useful for sending raw measurements -(pseudorange and carrierphase) from gpsd to -a Precise Point Positioning (PPP) program or service. - - gpsrinex does not require root -privileges, and can be run concurrently with other tools connecting -to a local or remote gpsd without causing -problems. - gpsrinex needs the GPS receiver to be sending raw measurements -to gpsd. Only a few GPS have this capability. -In addition, the gpsd 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 -ubxtool. - 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. - - gpsrinex 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. - 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. - Optionally a server, TCP/IP port number and remote device can -be given. If omitted, gpsrinex connects to -localhost on the default port (2947) and watches all devices opened by -gpsd. - - - OPTIONS - -D [debuglevel] set debug level to [debuglevel]. - -f [filename] save RINEX into [filename]. - -h makes gpsrinex print -a usage message and exit. - -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. - -n [count] causes [count] epochs to be output. OPUS requires a -minimum af 15 minutes, and a maximum of 48 hours, of data. - -V makes gpsrinex print -its version and exit. - - - EXAMPLES - Example 1: - Create a 4 hour .obs file. With a running -gpsd accessible on the localhost do all of -the following, in order. Order matters. - The raw measurement messages are long. Be sure your serial port -speed is high enough: - -gpsctl -s 115200 - - Disable all NMEA messages, and enable binary messages: - -ubxtool -d NMEA -ubxtool -e BINARY - - The NEO-M8N will only reliably output raw measurements -when only the GPS and QZSS constellations are enabled. -ubxtool, as recommended by u-blox, enables -the QZSS constellation in tandem with GPS. Disable all constellations, -except GPS (and QZSS): - - -ubxtool -d GLONASS -ubxtool -d BEIDOU -ubxtool -d GALILEO -ubxtool -d SBAS -ubxtool -e GPS - - Verify the constellations enabled: - -ubxtool -p GNSS - - Enable the good stuff, the raw measurement messages: - -ubxtool -e RAWX - - Verify raw data messages are being sent: - -ubxtool | fgrep RAWX - -You should see this output: - -UBX-RXM-RAWX: -UBX-RXM-RAWX: - - Collect 4 hours of samples at 30 second intervals, save then -RINEX 3 observations in the file today.obs: - -gpsrinex -i 30 -n 480 -f today.obs - - Wait 4 hours. Enjoy a meal, or do some exercise. When -gpsrinex finishes, upload the file today.obs -to your favorite PPP service. - Example 2: - Collect raw masurement data from a remote gpsd. The -process it later with gpsrinex and -gpsprof. - Ensure the GPS is configured properly, as shown in Example 1. - Grab 4 hours of raw live data from remote -gpsd at 10.168.1.2: - -gpspipe -x 14400 -R 10.168.1.2 > 4h-raw.ubx - - When gpspipe is complete, feed the -data to gpsfake: - -gpsfake -1 -P 3000 4h-raw.ubx - - In another window, feed the data to -gpsrinex. Use -n 10000000 so that -all the data from the raw file is used:: - -gpsrinex -i 30 -n 1000000 - - Repeat the process with -gpsfake to send the data to -gpsprof. - - - SEE ALSO - One service known to work with obsrinex output is at: -https://webapp.geod.nrcan.gc.ca/geod/tools-outils/ppp.php - OPUS requires 2 frequency observation files. -https://www.ngs.noaa.gov/OPUS/ - The curious can find the RINEX 3.03 format described here: -ftp://igs.org/pub/data/format/rinex303_update1.pdf - - - gpsd - 8 - , -gpsfake1, -ubxtool1. - - - - AUTHOR - Gary E. Miller gem@rellim.com. - - diff --git a/gpxlogger.xml b/gpxlogger.xml deleted file mode 100644 index 7d429941..00000000 --- a/gpxlogger.xml +++ /dev/null @@ -1,149 +0,0 @@ - - - - -05 Mar 2017 - -gpxlogger -1 -The GPSD Project -GPSD Documentation - - -gpxlogger -Tool to connect to gpsd and generate a GPX file - - - - - gpxlogger - -D debug-level - -d - -e export-method - -f filename - -l - -m minmove - -h - -V - -i track timeout - - server - - :port - :device - - - - - -DESCRIPTION -This program collects fixes from gpsd -and logs them to standard output in GPX, an XML profile for track -logging. - -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 - and defaulting to 5 seconds. - -gpxlogger can use any of the -export methods that gpsd supports. -For a list of these methods, use the . -To force the method, give the one of -the colon-terminated method names from the -table. - - -OPTIONS - -The option causes gpxlogger -to emit a summary of its options and then exit. - -The option causes gpxlogger -to dump the package version and exit. - - The option sets a debug level; -it is primarily for use by GPSD developers. -It enables various progress messages to standard error. - -The option tells -gpxlogger to run as a daemon in background. -It requires the option, which directs output to a -specified logfile. - -The option sets a minimum move distance in -meters (it may include a fractional decimal part). Motions shorter -than this will not be logged. - -The option tells -gpxlogger to retry when GPSd loses the fix. -Without , gpxlogger -would quit in this case. - -If D-Bus support is available on the host, GPSD is configured to -use it, and -e dbus is specified, this program -listens to DBUS broadcasts from -gpsd via org.gpsd.fix. - -With -e sockets, or if sockets is the method -defaulted to, you may give a server-port-device specification as -arguments. - -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: - - - -localhost:/dev/ttyS1 -Look at the default port of localhost, trying both -IPv4 and IPv6 and watching output from serial device 1. - - -example.com:2317 -Look at port 2317 on example.com, trying both -IPv4 and IPv6. - - -71.162.241.5:2317:/dev/ttyS3 -Look at port 2317 at the specified IPv4 -address, collecting data from attached serial device 3. - - -[FEDC:BA98:7654:3210:FEDC:BA98:7654:3210]:2317:/dev/ttyS5 -Look at port 2317 at the specified IPv6 -address, collecting data from attached serial device 5. - - - - - -SEE ALSO - -gpsd8, -gps1 -gpspipe1 - - - -AUTHORS - - - Amaury Jacquot sxpert@sxpert.org & - Petter Reinholdtsen pere@hungry.com & - Chris Kuethe chris.kuethe@gmail.com - - - - - diff --git a/libgps.xml b/libgps.xml deleted file mode 100644 index 7e850c3d..00000000 --- a/libgps.xml +++ /dev/null @@ -1,393 +0,0 @@ - - - - -14 Aug 2004 - -3 -3 -The GPSD Project -GPSD Documentation - - -libgps -C service library for communicating with the GPS daemon - - - - - -C: - -#include <gps.h> - - - -int gps_open - char *server - char * port - struct gps_data_t *gpsdata - - -int gps_send - struct gps_data_t *gpsdata - char *fmt... - - -int gps_read - struct gps_data_t *gpsdata - - -bool gps_waiting - const struct gps_data_t *gpsdata - int timeout - - -char *gps_data - const struct gps_data_t *gpsdata - - -int gps_unpack - char *buf - struct gps_data_t *gpsdata - - -int gps_close - struct gps_data_t *gpsdata - - -int gps_stream - struct gps_data_t *gpsdata - unsigned intflags - void *data - - -int gps_mainloop - struct gps_data_t *gpsdata - int timeout - void (*hook)(struct gps_data_t *gpsdata) - - -const char *gps_errstr - int err - - - -Python: - -import gps - -session = gps.gps(host="localhost", port="2947") - -session.stream(flags=gps.WATCH_JSON) - -for report in session: - process(report) - -del session - - - - - -DESCRIPTION - -libgps is a service library which -supports communicating with an instance of the -gpsd8 -; link it with the linker option -lgps. - -Take care to conditionalize your code on the major and -minor API version symbols in gps.h; 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. - -Calling gps_open() initializes a GPS-data -structure to hold the data collected by the GPS, and sets up access to -gpsd1 - -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. - -gps_open() 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 -gps.h for values and explanations; also see -gps_errstr(). The host address may be a DNS name, -an IPv4 dotted quad, an IPV6 address, or the special value -GPSD_SHARED_MEMORY referring to the -shared-memory export; the library will do the right thing for any of -these. - -gps_close() ends the session and should only be -called after a successful gps_open(). -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 close(). - -gps_send() 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 -gpsd1 -. -It may have % elements as for -sprintf3 -, -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 gps_stream() as a possible -alternative. - -gps_read() 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. - -gps_waiting() 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 -select2 - -call, and zeros errno on entry; you can test -errno after exit to get more information about -error conditions. Warning: under the shared-memory interface there is -a tiny race window between gps_waiting() and a -following gps_read(); in that context, because the -latter does not block, it is probably better to write a simple read -loop. - -gps_mainloop() 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. - - -gps_unpack() 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. - -gps_data() 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. - -gps_stream() asks -gpsd 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 -gps_stream() more than once with different flag -masks is allowed. - - - -WATCH_DISABLE - -Disable the reporting modes specified by the other WATCH_ flags. - - - -WATCH_ENABLE - -Disable the reporting modes specified by the other WATCH_ flags. -This is the default. - - - -WATCH_JSON - -Enable JSON reporting of data. If WATCH_ENABLE is set, and no -other WATCH flags are set, this is the default. - - - -WATCH_NMEA - -Enable generated pseudo-NMEA reporting on binary devices. - - - -WATCH_RARE - -Enable reporting of binary packets in encoded hex. - - - -WATCH_RAW - -Enable literal passthrough of binary packets. - - - -WATCH_SCALED - -When reporting AIS or Subframe data, scale integer quantities to -floats if they have a divisor or rendering formula associated with them. - - - -WATCH_NEWSTYLE - -Force issuing a JSON initialization and getting new-style -responses. This is the default. - - - -WATCH_OLDSTYLE - -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. - - - -WATCH_DEVICE - -Restrict watching to a specified device, path given as second -argument. - - - - -gps_errstr() returns an ASCII string (in -English) describing the error indicated by a nonzero return value from -gps_open(). - -Consult gps.h 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 gps_read(). -It is up to the client to zero that field when appropriate and to keep -an eye on the fix and sentence timestamps. - -The Python implementation supports the same facilities as the -socket-export calls in the C library; there is no shared-memory -interface. gps_open() 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. - - -ENVIRONMENT VARIABLES - -By setting the environment variable GPSD_SHM_KEY, -you can control the key value used to create shared-memory segment -used for communication with gpsd. This -will be useful mainly when isolating test instances of -gpsd from production ones. - - - -CODE EXAMPLE - -The following is an excerpted and simplified version of the -libgps interface code from -cgps1 -. - - - 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); - - - - -LIMITATIONS - -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. - -In the C API, incautious use of gps_send() -may lead to subtle bugs. In order to not bloat struct -gps_data_t 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. - -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 -struct gps_data_t before using -gps_send() to request any of these -responses. - - - -COMPATIBILITY - -The gps_query() 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. - -If you must send commands to the daemon explicitly, use -gps_send() but beware that this ties your code to -the GPSD wire protocol. It is not recommended. - -In earlier versions of the API gps_read() was -a blocking call and there was a POLL_NONBLOCK option to make it nonblocking. -gps_waiting() was added to reduce the number of -wrong ways to code a polling loop. - -See the comment above the symbol GPSD_API_MAJOR_VERSION -in gps.h for recent changes. - - -SEE ALSO - -gpsd8 -, -gps1 -, -libgpsmm3 -. - - - -AUTHOR -Eric S. Raymond <esr@thyrsus.com>, - C sample code Charles Curley <charlescurley@charlescurley.com> - - - diff --git a/libgpsmm.xml b/libgpsmm.xml deleted file mode 100644 index cfcc9d35..00000000 --- a/libgpsmm.xml +++ /dev/null @@ -1,83 +0,0 @@ - - - - -13 May 2005 - -libgpsmm -3 -The GPSD Project -GPSD Documentation - - -libgpsmm -libQgpsmm -C++ and QT class wrapper for the GPS daemon - - - - - -C++: - -#include <libgpsmm> - - - -struct gps_data_t *open - char *host - char *port - - -struct gps_data_t *open - void - - -struct gps_data_t *send - char *request - - -struct gps_data_t *read - void - - -struct gps_data_t *waiting - int - - -struct gps_data_t *stream - unsigned intflags - - - - -DESCRIPTION - -libgpsmm and libQgpsmm are mere wrappers over -libgps. The important difference between the libraries is that libgpsmm is targeted at C++ applications and contained in libgps, while libQgpsmm is platform independent by using QTcpSocket to connect to gpsd 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 -libgps3. -open() must be called after class constructor and before any other method -(open() is not inside the constructor since it may fail, however constructors have no return value). -The analogue of the C function gps_close() is in the destructor. - - -SEE ALSO - -gpsd8, -gps1, -libgps3. - - - -AUTHOR -Alfredo Pironti <alfredio@users.sourceforge.net>. - - - 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 @@ + + + + +9 Aug 2004 + +gps +1 +The GPSD Project +GPSD Documentation + + +cgps +gegps +gps +lcdgps +xgps +xgpsspeed +test clients for gpsd + + + + + cgps + -D debug-level + -h + -l dms + -m + -s + -u inm + -V + + server + + :port + :device + + + + + gegps + -d directory + -h + -i + -V + + + lcdgps + -h + -j + -l dms + -s + -u inm + -V + + server + + :port + :device + + + + + xgps + -? + -D debug-level + -h + -l dms + -u inm + -V + + server + + :port + :device + + + + + xgpsspeed + --debug debug-level + --device device + -h + --host host + --landspeed + --maxspeed maxspeed + --nautical + --port port + --speedunits + + mphkphknots + + + -V + + server + + :port + :device + + + + + +DESCRIPTION + +These are the demonstration clients shipped with +gpsd. They have some common options: + +The option causes each client to emit a summary of its +options and then exit. + +The option causes each client to dump the package +version and exit. + + The 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. + +xgps, +cgps, and lcdgps +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: + + + 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 + +These preferences may be overridden by the +option. + +Where present, the 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). + + The option, when present, sets a debug +level; it is primarily for use by GPSD developers. It enables +various progress messages to standard error. + +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: + + + +localhost:/dev/ttyS1 +Look at the default port of localhost, trying both +IPv4 and IPv6 and watching output from serial device 1. + + +example.com:2317 +Look at port 2317 on example.com, trying both +IPv4 and IPv6. + + +71.162.241.5:2317:/dev/ttyS3 +Look at port 2317 at the specified IPv4 +address, collecting data from attached serial device 3. + + +[FEDC:BA98:7654:3210:FEDC:BA98:7654:3210]:2317:/dev/ttyS5 +Look at port 2317 at the specified IPv6 +address, collecting data from attached serial device 5. + + + +Not all clients shipped with GPSD are documented here. See also +the separate manual pages for +gpspipe1 +and +gpsmon1 +and +gpxlogger1 +. + +xgps + +xgps is a simple test client for +gpsd with an X interface. It displays +current GPS position/time/velocity information and (for GPSes that +support the feature) the locations of accessible satellites. + +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. + + +xgpsspeed + +xgpsspeed is a speedometer that uses +position information from the GPS. It accepts an -h option and +optional argument as for gps, or a -V +option to dump the package version and exit. + +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. + +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. + +In the nautical mode only, --maxspeed sets the maximum on the +speedometer. + + +cgps + +cgps is a client resembling +xgps, but without the pictorial +satellite display and able to run on a serial terminal or +terminal emulator. + + The option prevents +cgps from displaying the data coming from +the daemon. This display can also be toggled with the s +command. + +The 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. + +cgps 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' + + +lcdgps + +A client that passes gpsd data to +lcdproc, 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. + + + +gegps + +This program collects fixes from gpsd +and feeds them to a running instance of Google Earth for live location +tracking. + +The argument is the location of the Google +Earth installation directory. If not specified, it defaults to the +current directory. + +If you have the free (non-subscription) version, start by +running with the 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 gpsd in the normal way +after that. + + + +SEE ALSO + +gpsd8, +libgps3, +libgpsmm3, +gpsfake1, +gpsctl1, +gpscat1, +gpsprof1. +gpspipe1. +gpsmon1. +gpxlogger1. + + + +AUTHORS + + +Remco Treffcorn, Derrick Brashear, Russ Nelson & Eric S. Raymond, +Jeff Francis (cgps), Chen Wei weichen302@aol.com (gegps & xgpsspeed), +Robin Wittler real@the-real.org (xgpsspeed). + + +This manual page by Eric S. Raymond esr@thyrsus.com + + + + + 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 @@ + + + + +01 Marc 2013 + +gps2udp +1 +The GPSD Project +GPSD Documentation + + +gps2udp +feed the take from gpsd to one or more aggregation sites + + + + + gps2udp + -h + -n + -j + -a + -u hostname:udpport + -c count + -d 1|2 + -v + + server + :port + :device + + + + + +DESCRIPTION + +gps2udp is a tool to connect to +gpsd and output the received sentences to +one or many UDP host:port destinations. This makes the program useful +for feeding AIS information from gpsd to +aishub, marinetraffic, shipfinder,... + +gps2udp does not require root +privileges, and can be run concurrently with other tools connecting +to the local gpsd without causing problems. + +The output will consist of one or both of NMEA (-n option) or +JSON (-j option) gpsd sentences. The +output is sent to one or many destinations host through a UDP network +socket (-u host:port options) . + +Optionally a server, TCP/IP port number and remote device can be given. +If omitted, gps2udp connects to localhost on +the default port (2947) and watches all devices opened by +gpsd. + +gps2udp may be run as a daemon (-b +option). + +gps2udp is designed to run smoothly in +background; it reconnects automatically to +gpsd whenever it is restarted. For +debugging purporses, there is an option to exit gracefully after a given +count of packets (-c option). + + +OPTIONS + +-h makes gps2udp print +a usage message and exit. + +-n causes NMEA sentences to be output. +-j causes JSON sentences to be output. +-u host:port UDP destination for output sentenses (up to five +destinations). + +-a output only AIS messages. +-b causes gps2udp to run as a daemon. +-c [count] causes [count] sentences to be output. +gps2udp will then exit gracefully. + +-d 1 prints sent packet on stdout. +-v prints the version, then exits. + + +EXAMPLE +With a running gpsd accessible on the +network + +gps2udp -d 1 -n -u data.aishub.net:2222 will +collect data from localhost:gpsd display them on stdout and send a +copy to test aishub in NMEA format. + +gps2udp -a -n -b -u data.aishub.net:2222 -u 5.9.207.224:5321 -u 109.200.19.151:4001 fridu.net:2947 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 + + +SEE ALSO + +gpsd8, +gps1, +libgps3, +libgpsmm3, +gpsprof1, +gpsfake1, +gpsctl1, +gpscat1. +gpsmon1. + + + +AUTHOR + +Fulup Ar Foll fulup@sinagot.net. + + + + + 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 @@ + + + + +16 Nov 2006 + +gpscat +1 +The GPSD Project +GPSD Documentation + + +gpscat +dump the output from a GPS + + + + + gpscat + -s speed + -p + -t + -D debuglevel + file-or-serial-port + + + +DESCRIPTION + +gpscat 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. + +In raw mode (the default) gpscat +simply dumps its input to standard output. Nonprintable characters +other than ASCII whitespace are rendered as hexadecimal string escapes. + +In packetizing mode, gpscat uses the +same code as +gpsd8's +packet sniffer to break the input into packets. Packets are reported +one per line; line breaks in the packets themselves are +escaped. + +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. + +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. + +The program accepts the following options: + + + +-p + +Invoke packetizer mode. + + + + +-s + +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). + + + + +-t + +Invoke packetizer mode, with the packet type and length (in +parentheses) reported before a colon and space on each line. + + + + +-D + +In packetizer mode, enable progress messages from the packet +getter. Probably only of interest to developers testing packet +getter changes. + + + + +-h + +Display program usage and exit. + + + + +Specifying -s 4800N1 is frequently helpful with unknown +devices. + + + +SEE ALSO + +gpsd8, +gps1, +libgps3, +libgpsmm3, +gpsfake1. +gpsprof1, +gpsctl1, +gpsdctl8, +gpsmon1. + + + +AUTHOR + +Eric S. Raymond esr@thyrsus.com. + + 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 @@ + + + + +29 Oct 2006 + +gpsctl +1 +The GPSD Project +GPSD Documentation + + +gpsctl +control the modes of a GPS + + + + + gpsctl + -h + + -b + -n + + -x control + -e + -f + -l + -s speed + -t devicetype + -R + -D debuglevel + -V + serial-port + + + +DESCRIPTION + +gpsctl 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. + +If you have only one GPS attached to your machine, and gpsd is +running, it is not necessary to specify the device; +gpsctl does its work through +gpsd, which will locate it for you. + +When gpsd 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'. + +The program accepts the following options: + + + +-b + +Put the GPS into native (binary) mode. + + + + +-c + +Change the GPS's cycle time. Units are seconds. Note, most +GPSes have a fixed cycle time of 1 second. + + + + +-e + +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 without specifying a device. Note: +the packet data for a binary prototype will be raw, not ASCII-ized in +any way. + + + + +-f + +Force low-level access (not through the daemon). + + + + +-l + +List a table showing which option switches can be applied +to which device types, and exit. + + + + +-n + +Put GPS into NMEA mode. + + + + +-s + +Set the baud rate at which the GPS emits packets. + +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. + + + + +-t + +Force the device type. + + + + +-x + +Send a specified control string to the GPS; +gpsctl 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 . + + + + +-T + +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. + + + + +-R + +Remove the GPSD shared-memory segment used for SHM export. This +option will normally only be of interest to GPSD developers. + + + + +-h + +Display program usage and exit. + + + + +-D + +Set level of debug messages. + + + + +-V + +Display program version and exit. + + + + +The argument of the forcing option, , should be a +string which is contained in exactly one of the known driver +names; for a list, do gpsctl -l. + +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, gpsctl exits with +a warning. (This may be useful in scripts.) + +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.) + +If no options are given, the program will display a message +identifying the GPS type of the selected device and exit. + +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. + + + +ENVIRONMENT VARIABLES + +By setting the environment variable GPSD_SHM_KEY, +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 gpsd from +production ones. + + + +EXAMPLES + + + +gpsctl /dev/ttyUSB0 + +Attempt to identify the device on USB serial device 0. Time out +after the default number of seconds. Adding the will +force low-level access and suppress the normal complaint when this +tool can't find a GPSD to work through. + + + + +gpsctl -f -n -s 9600 /dev/ttyUSB0 + +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. + + + + + + +BUGS + +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. + +Baud rate and mode changes work in direct mode but are not +reliable in client mode. This will be fixed in a future release. + + + +SEE ALSO + +gpsd8, +gpsdctl8, +gps1, +libgps3, +libgpsmm3, +gpsprof1, +gpsfake1. + + + +AUTHOR + +Eric S. Raymond esr@thyrsus.com. + + 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 @@ + + + +]> + +9 Aug 2004 + +gpsd +8 +The GPSD Project +GPSD Documentation + + +gpsd +interface daemon for GPS receivers + + + + + + gpsd + -b + -D debuglevel + -F control-socket + -G + -h + -l + -n + -N + -P pidfile + -r + -S listener-port + -V + + source-name + + + + +QUICK START + +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: + + +gpsd /dev/ttyUSB0 + + +For the lowest-numbered serial port: + + +gpsd /dev/ttyS0 + + +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 (which see). + +On Linux systems supporting udev, gpsd +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. + +For your initial tests set your GPS hardware to speak NMEA, as +gpsd is guaranteed to be able to process +that. If your GPS has a native or binary mode with better performance +that gpsd knows how to speak, +gpsd will autoconfigure that mode. + +You can verify correct operation by first starting +gpsd and then +xgps, the X windows test client. + +If you have problems, the GPSD project maintains a FAQ to +assist troubleshooting. + + +DESCRIPTION + +gpsd 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 +gpsd 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, +gpsd discovers the correct port speed and +protocol for it. + +gpsd 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. + +The GPS reporting formats supported by your instance of +gpsd 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 gpsd -l + +gpsd 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 +gpsd as an intermediary, applications +avoid contention for serial devices. + +gpsd 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 gpsd 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 + and for discussion. + +Client applications will communicate with gpsd +via a TCP/IP port, 2947 by default). Both IPv4 and IPv6 connections +are supported and a client may connect via either. + +The program accepts the following options: + + +-b +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 +gpsd cannot configure the receiver for +optimal performance, but it also means that +gpsd 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. + + +-D + +Set debug level. At debug levels 2 and above, +gpsd reports incoming sentence and actions +to standard error if gpsd is in the foreground +(-N) or to syslog if in the background. + + + +-F + +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. + + + +-G +This flag causes gpsd 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. + + +-h +Display help message and terminate. + + +-l +List all drivers compiled into this +gpsd instance. The letters to the left of +each driver name are the gpsd +control commands supported by that driver. + + + +-n + +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). + + + + +-N +Don't daemonize; run in foreground. +This switch is mainly useful for debugging. + + + +-r +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. + + +-P + +Specify the name and path to record the daemon's process ID. + + + +-S +Set TCP/IP port on which to listen for GPSD clients +(default is 2947). + + +-V + +Dump version and exit. + + + + +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: + + + +Local serial or USB device + +A normal Unix device name of a serial or USB device to which a +sensor is attached. Example: +/dev/ttyUSB0. + + + +Local PPS device + +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: +/dev/pps0. + + + +TCP feed + +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: +tcp://data.aishub.net:4006. + + + +UDP feed + +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: +udp://127.0.0.1:5000. + + + +Ntrip caster + +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. + + + +DGPSIP server + +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: +dgpsip://dgps.wsrcc.com:2101. + + + +Remote gpsd feed + +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 gpsd port will be used). The daemon +will open a socket to the indicated address and port and emulate a +gpsd client, collecting JSON reports from +the remote gpsd instance that will be +passed to local clients. + + + +NMEA2000 CAN data + +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 gpsd can be started. If +there is more then one unit on the CAN bus that provides GPS data, +gpsd chooses the unit from which a GPS message +is first seen. Example: nmea2000://can0. + + + + + +(The "ais:://" source type supported in some older versions of +the daemon has been retired in favor of the more general +"tcp://".) + +Additionally, two serial device names have a side effect: + + +/dev/ttyAMA0 + +The UART device on a Raspberry Pi. Has the side effect of +opening /dev/pps0 for RFC2783 1PPS data. + + + +Generic GPS device 0. Has the side effect of +opening /dev/pps0 for RFC2783 1PPS data/ + + + + + + + +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 for +details on this). Daemon startup will abort with an error if neither +any devices nor a control socket are specified. + +When a device is activated (i.e. a client requests data from it), +gpsd attempts to execute a hook from +/etc/gpsd/device-hook with first command line argument +set to the pathname of the device and the second to +. On deactivation it does the same passing + for the second argument. + +gpsd 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. + + +THE SOCKET INTERFACE + +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 +libgps client library and take appropriate +care to conditionalize their code on the major and minor protocol +version symbols. + +The request-response protocol for the socket interface is fully +documented in +gpsd_json5. + + + +SHARED-MEMORY AND DBUS INTERFACES + +gpsd has two other (read-only) +interfaces. + +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 +libgps3. The +shared-memory interface is intended primarily for embedded deployments +in which gpsd 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. + +The daemon may be configured to emit a D-Bus signal each time an +attached device delivers a fix. The signal path is path +/org/gpsd, the signal interface is "org.gpsd", and the +signal name is "fix". The signal payload layout is as follows: + +Satellite object + + + + Type + Description + + + + + DBUS_TYPE_DOUBLE + Time (seconds since Unix epoch) + + + DBUS_TYPE_INT32 + mode + + + DBUS_TYPE_DOUBLE + Time uncertainty (seconds). + + + DBUS_TYPE_DOUBLE + Latitude in degrees. + + + DBUS_TYPE_DOUBLE + Longitude in degrees. + + + DBUS_TYPE_DOUBLE + Horizontal uncertainty in meters, 95% confidence. + + + DBUS_TYPE_DOUBLE + Altitude in meters. + + + DBUS_TYPE_DOUBLE + Altitude uncertainty in meters, 95% confidence. + + + DBUS_TYPE_DOUBLE + Course in degrees from true north. + + + DBUS_TYPE_DOUBLE + Course uncertainty in meters, 95% confidence. + + + DBUS_TYPE_DOUBLE + Speed, meters per second. + + + DBUS_TYPE_DOUBLE + Speed uncertainty in meters per second, + 95% confidence. + + + DBUS_TYPE_DOUBLE + Climb, meters per second. + + + DBUS_TYPE_DOUBLE + Climb uncertainty in meters per second, + 95% confidence. + + + DBUS_TYPE_STRING + Device name + + + +
+ + + +GPS DEVICE MANAGEMENT + +gpsd 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. + +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. + +When gpsd is properly installed along +with hotplug notifier scripts feeding it device-add commands over the +control socket, gpsd should require no +configuration or user action to find devices. + +Sending SIGHUP to a running gpsd +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. + +When gpsd 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 after after some +devices have been seen, it shuts down gracefully. It is expected that +future device hotplug events will reactivate it. + +To point gpsd 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 +/dev/foo. 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 /dev/foo from the search +list, send "-/dev/foo\n". + +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. + +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. + +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 +gpsd's device pool. An ERROR response to a +! command means the daemon did not recognize the devicename +specified. + +The control socket is intended for use by hotplug scripts and +other device-discovery services. This control channel is separate +from the public gpsd service port, and only +locally accessible, in order to prevent remote denial-of-service and +spoofing attacks. + + +ACCURACY + +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 not rely on GPS altitude for +life-critical tasks such as landing an airplane. + +These errors are intrinsic to the design and physics of the GPS +system. gpsd does its internal +computations at sufficient accuracy that it will add no measurable +position error of its own. + +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. + +On a 4800bps connection, the time latency of fixes provided by +gpsd 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 gpsd 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. + +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. + +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 gpsd at +debug level 4 to see the chipset type and firmware revision +level. + +There are exactly two circumstances under which +gpsd relies on the host-system +clock: + +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. gpsd 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. + +If you are using an NMEA-only GPS (that is, not using SiRF or +Garmin or Zodiac binary mode), gpsd 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 +gpsd 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. + + +USE WITH NTP + +gpsd can provide reference clock information to +ntpd, to keep the system clock synchronized +to the time provided by the GPS receiver. + +On Linux, gpsd 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 +gpsd will use that for extra +accuracy. + +Detailed instructions for using GPSD to set up a high-quality +time service can be found among the documentation on the GPSD +website. + + +USE WITH D-BUS + +On operating systems that support D-BUS, +gpsd 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 +gpsd source code to learn more. + + +SECURITY AND PERMISSIONS ISSUES + +gpsd, 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. + +gpsd 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 /dev/ttyS0. + +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 gpsd. +It ensures that any such compromises cannot be used for privilege +elevation to root. + +The assumption behind gpsd'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, +gpsd may not be able to open GPS devices in +order to read them (such failures will be logged). + +In order to fend off inadvertent denial-of-service attacks by +port scanners (not to mention deliberate ones), +gpsd 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, +gpsd 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). + + +LIMITATIONS + +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. + +gpsd 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. + +When using SiRF chips, the VDOP/TDOP/GDOP figures and associated +error estimates are computed by gpsd rather +than reported by the chip. The computation does not exactly match +what SiRF chips do internally, which includes some satellite weighting +using parameters gpsd cannot see. + +Autobauding on the Trimble GPSes can take as long as 5 seconds +if the device speed is not matched to the GPS speed. + +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. + +AIDVM decoding of types 16-17, 22-23, and 25-26 is unverified. + +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. + +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. + +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. + +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 +gpsd 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 gpsd 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). + + +FILES + + + +/dev/ttyS0 + +Prototype TTY device. After startup, +gpsd sets its group ID to the owning group of this +device if no GPS device was specified on the command line does not +exist. + + + +/etc/gpsd/device-hook + +Optional file containing the device activation/deactivation script. +Note that while /etc/gpsd is the default system +configuration directory, it is possible to build the GPSD source code +with different assumptions. + + + + + + +ENVIRONMENT VARIABLES + +By setting the environment variable GPSD_SHM_KEY, +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 +gpsd from production ones. + + +APPLICABLE STANDARDS + +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 +gpsd 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. + +gpsd 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. + +Note that gpsd JSON returns pure decimal +degrees, not the hybrid degree/minute format described in the NMEA +standard. + +Differential-GPS corrections are conveyed by the RTCM +protocols. The applicable standard for RTCM-104 V2 is RTCM +Recommended Standards for Differential GNSS (Global Navigation +Satellite) Service RTCM Paper 136-2001/SC 104-STD. The +applicable standard for RTCM-104 V3 is RTCM Standard +10403.1 for Differential GNSS Services - Version 3 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". + +AIS is defined by ITU Recommendation M.1371, +Technical Characteristics for a Universal Shipborne +Automatic Identification System Using Time Division Multiple +Access. The AIVDM/AIVDO format understood by this program +is defined by IEC-PAS 61162-100, Maritime navigation and +radiocommunication equipment and systems. A more accessible +description of both can be found at AIVDM/AIVDO Protocol +Decoding, on the references page of the GPSD project +website. + +Subframe data is defined by IS-GPS-200E, GLOBAL +POSITIONING SYSTEM WING (GPSW) SYSTEMS ENGINEERING & INTEGRATION, +INTERFACE SPECIFICATION IS-GPS-200 Revision E. The format +understood by this program is defined in Section 20 (Appendix II) of +the IS-GPS-200E, GPS NAVIGATION DATA STRUCTURE FOR DATA, +D(t) + +JSON is specified by RFC 7159, The JavaScript Object +Notation (JSON) Data Interchange Format. + +The API for PPS time service is specified by RFC 2783, +Pulse-Per-Second API for UNIX-like Operating Systems, +Version 1.0 + + +SEE ALSO + +gpsdctl8, +gps1, +libgps3, +gpsd_json5, +libgpsmm3, +gpsprof1, +gpsfake1, +gpsctl1, +gpscat1, + + + +AUTHORS + +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 +esr@thyrsus.com. + + + 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 @@ + + + +]> + +17 Jun 2018 + +gpsd_json +5 +The GPSD Project +GPSD Documentation + + +gpsd_json +gpsd request/response protocol + + +OVERVIEW + +gpsd is a service daemon that can be used +to monitor GPSes, DGPS receivers, Marine AIS broadcasts, and various other +location-related and kinematic sensors. + +Clients may communicate with gpsd via +textual requests and responses over a socket. It is a bad idea for +applications to speak the protocol directly: rather, they should use +the libgps client library (for C; bindings +also exist for other languages) and take appropriate care to +conditionalize their code on the major and minor protocol version +symbols. + +The GPSD protocol is built on top of JSON, JavaScript Object +Notation, as specified in RFC 7159: The JavaScript Object +Notation (JSON) Data Interchange Format. GPSD's use of +JSON is restricted in some ways that make parsing it in fixed-extent +languages (such as C) easier. + +A request line is introduced by "?" and may include multiple +commands. Commands begin with a command identifier, followed either +by a terminating ';' or by an equal sign "=" and a JSON object treated +as an argument. Any ';' or newline indication (either LF or CR-LF) +after the end of a command is ignored. All request lines must be +composed of US-ASCII characters and may be no more than 80 characters +in length, exclusive of the trailing newline. + +Responses are JSON objects all of which have a "class" attribute +the value of which is either the name of the invoking command. There +are reports (including but not limited to as "TPV", "SKY", "DEVICE", +and "ERROR") which are not direct responses to commands. + + The order of JSON attributes within a response object is never +significant, and you may specify attributes in commands in any +order. Responses never contain the special JSON value null; instead, +attributes with empty or undefined values are omitted. The length +limit for responses and reports is 1536 characters, including trailing +newline; longer responses will be truncated, so client code must be +prepared for the possibility of invalid JSON fragments. + +In JSON reports, if an attribute is present only if the parent +attribute is present or has a particular range, then the parent +attribute is emitted first. + +There is one constraint on the order in which attributes will +be omitted. If an optional attribute is present only when a parent +attribute has a specified value or range of values, the parent +attribute will be emitted first to make parsing easier. + +The next subsection section documents the core GPSD protocol. +Extensions are documented in the following subsections. The extensions +may not be supported in your gpsd instance +if it has been compiled with a restricted feature set. + + +CORE SOCKET PROTOCOL + +Here are the core-protocol responses: + + + +TPV + +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. + +TPV object + + + + Name + Always? + Type + Description + + + + + class + Yes + string + Fixed: "TPV" + + + device + No + string + Name of originating device. + + + status + No + numeric + GPS status: %d, 2=DGPS fix, otherwise not present. + + + mode + Yes + numeric + NMEA mode: %d, 0=no mode value yet seen, 1=no fix, 2=2D, 3=3D. + + + time + No + string + 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. + + + ept + No + numeric + Estimated timestamp error (%f, seconds, 95% confidence). + Present if time is present. + + + lat + No + numeric + Latitude in degrees: +/- signifies North/South. Present + when mode is 2 or 3. + + + lon + No + numeric + Longitude in degrees: +/- signifies East/West. Present + when mode is 2 or 3. + + + alt + No + numeric + Altitude in meters. Present if mode is 3. + + + epx + No + numeric + Longitude error estimate in meters, 95% confidence. Present + if mode is 2 or 3 and DOPs can be calculated from the satellite + view. + + + epy + No + numeric + Latitude error estimate in meters, 95% confidence. Present + if mode is 2 or 3 and DOPs can be calculated from the satellite + view. + + + epv + No + numeric + Estimated vertical error in meters, 95% confidence. Present + if mode is 3 and DOPs can be calculated from the satellite + view. + + + track + No + numeric + Course over ground, degrees from true north. + + + magtrack + No + numeric + Course over ground, degrees magnetic. + + + speed + No + numeric + Speed over ground, meters per second. + + + climb + No + numeric + Climb (positive) or sink (negative) rate, meters per + second. + + + epd + No + numeric + Direction error estimate in degrees, 95% confidence. + + + eps + No + numeric + Speed error estinmate in meters/sec, 95% confidence. + + + epc + No + numeric + Climb/sink error estimate in meters/sec, 95% confidence. + + + ecefx + No + numeric + ECEF X position in meters. + + + ecefy + No + numeric + ECEF Y position in meters. + + + ecefz + No + numeric + ECEF Z position in meters. + + + ecefpAcc + No + numeric + ECEF position error in meters. + + + ecefvx + No + numeric + ECEF X velocity in meters/second. + + + ecefvy + No + numeric + ECEF Y velocity in meters/second. + + + ecefvz + No + numeric + ECEF Z velocity in meters/second. + + + ecefvAcc + No + numeric + ECEF velocity error in meters/second. + + + + +
+ +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. + +Here's an example: + + +{"class":"TPV","device":"/dev/pts/1", + "time":"2005-06-08T10:34:48.283Z","ept":0.005, + "lat":46.498293369,"lon":7.567411672,"alt":1343.127, + "eph":36.000,"epv":32.321, + "track":10.3788,"speed":0.091,"climb":-0.085,"mode":3} + + + + + +SKY + +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. + +SKY object + + + + Name + Always? + Type + Description + + + + + class + Yes + string + Fixed: "SKY" + + + device + No + string + Name of originating device + + + time + No + string + Time/date stamp in ISO8601 format, UTC. May have a + fractional part of up to .001sec precision. + + + xdop + No + numeric + Longitudinal dilution of precision, a dimensionless + factor which should be multiplied by a base UERE to get an + error estimate. + + + ydop + No + numeric + Latitudinal dilution of precision, a dimensionless + factor which should be multiplied by a base UERE to get an + error estimate. + + + vdop + No + numeric + Altitude dilution of precision, a dimensionless + factor which should be multiplied by a base UERE to get an + error estimate. + + + tdop + No + numeric + Time dilution of precision, a dimensionless + factor which should be multiplied by a base UERE to get an + error estimate. + + + hdop + No + numeric + Horizontal dilution of precision, a dimensionless + factor which should be multiplied by a base UERE to get a + circular error estimate. + + + pdop + No + numeric + Spherical dilution of precision, a dimensionless + factor which should be multiplied by a base UERE to get an + error estimate. + + + gdop + No + numeric + Hyperspherical dilution of precision, a dimensionless + factor which should be multiplied by a base UERE to get an + error estimate. + + + satellites + Yes + list + List of satellite objects in skyview + + + + +
+ +Many devices compute dilution of precision factors but do not +include them in their reports. Many that do report DOPs report only +HDOP, two-dimensional circular error. gpsd +always passes through whatever the device 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. + +The satellite list objects have the following elements: + +Satellite object + + + + Name + Always? + Type + Description + + + + + PRN + Yes + numeric + PRN ID of the satellite. 1-63 are GNSS satellites, + 64-96 are GLONASS satellites, 100-164 are SBAS satellites + + + az + Yes + numeric + Azimuth, degrees from true north. + + + el + Yes + numeric + Elevation in degrees. + + + ss + Yes + numeric + Signal strength in dB. + + + used + Yes + boolean + 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.) + + + +
+ +Note that satellite objects do not have a "class" field, as +they are never shipped outside of a SKY object. + +When the C client library parses a SKY response, it +will assert the SATELLITE_SET bit in the top-level set member. + +Here's an example: + + +{"class":"SKY","device":"/dev/pts/1", + "time":"2005-07-08T11:28:07.114Z", + "xdop":1.55,"hdop":1.24,"pdop":1.99, + "satellites":[ + {"PRN":23,"el":6,"az":84,"ss":0,"used":false}, + {"PRN":28,"el":7,"az":160,"ss":0,"used":false}, + {"PRN":8,"el":66,"az":189,"ss":44,"used":true}, + {"PRN":29,"el":13,"az":273,"ss":0,"used":false}, + {"PRN":10,"el":51,"az":304,"ss":29,"used":true}, + {"PRN":4,"el":15,"az":199,"ss":36,"used":true}, + {"PRN":2,"el":34,"az":241,"ss":43,"used":true}, + {"PRN":27,"el":71,"az":76,"ss":43,"used":true}]} + + + + + + +GST + +A GST object is a pseudorange noise report. + +GST object + + + + Name + Always? + Type + Description + + + + + class + Yes + string + Fixed: "GST" + + + device + No + string + Name of originating device + + + time + No + string + Time/date stamp in ISO8601 format, UTC. May have a + fractional part of up to .001sec precision. + + + + rms + No + numeric + Value of the standard deviation of the range inputs to the +navigation process (range inputs include pseudoranges and DGPS +corrections). + + + + major + No + numeric + Standard deviation of semi-major axis of error ellipse, in meters. + + + + minor + No + numeric + Standard deviation of semi-minor axis of error ellipse, in meters. + + + + orient + No + numeric + Orientation of semi-major axis of error ellipse, in degrees from true north. + + + + lat + No + numeric + Standard deviation of latitude error, in meters. + + + + lon + No + numeric + Standard deviation of longitude error, in meters. + + + + alt + No + numeric + Standard deviation of altitude error, in meters. + + + + +
+ +Here's an example: + + +{"class":"GST","device":"/dev/ttyUSB0", + "time":"2010-12-07T10:23:07.096Z","rms":2.440, + "major":1.660,"minor":1.120,"orient":68.989, + "lat":1.600,"lon":1.200,"alt":2.520} + + + + + +ATT + +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. + +The "class" and "mode" fields will reliably be present. Others +may be reported or not depending on the specific device type. + +ATT object + + + + Name + Always? + Type + Description + + + + + class + Yes + string + Fixed: "ATT" + + + device + Yes + string + Name of originating device + + + time + No + string + Time/date stamp in ISO8601 format, UTC. May have a + fractional part of up to .001sec precision. + + + heading + No + numeric + Heading, degrees from true north. + + + mag_st + No + string + Magnetometer status. + + + pitch + No + numeric + Pitch in degrees. + + + pitch_st + No + string + Pitch sensor status. + + + yaw + No + numeric + Yaw in degrees + + + yaw_st + No + string + Yaw sensor status. + + + roll + No + numeric + Roll in degrees. + + + roll_st + No + string + Roll sensor status. + + + dip + No + numeric + Local magnetic inclination, degrees, positive when the magnetic +field points downward (into the Earth). + + + mag_len + No + numeric + Scalar magnetic field strength. + + + mag_x + No + numeric + X component of magnetic field strength. + + + mag_y + No + numeric + Y component of magnetic field strength. + + + mag_z + No + numeric + Z component of magnetic field strength. + + + acc_len + No + numeric + Scalar acceleration. + + + acc_x + No + numeric + X component of acceleration. + + + acc_y + No + numeric + Y component of acceleration. + + + acc_z + No + numeric + Z component of acceleration. + + + gyro_x + No + numeric + X component of acceleration. + + + gyro_y + No + numeric + Y component of acceleration. + + + depth + No + numeric + Water depth in meters. + + + temp + No + numeric + Temperature at sensor, degrees centigrade. + + + + + +
+ +The heading, pitch, and roll status codes (if present) vary by device. +For the TNT Revolution digital compasses, they are coded as follows: + +Device flags + + + + Code + Description + + + + + C + magnetometer calibration alarm + + + L + low alarm + + + M + low warning + + + N + normal + + + O + high warning + + + P + high alarm + + + V + magnetometer voltage level alarm + + + +
+ + +When the C client library parses a response of this kind, it +will assert ATT_IS. + +Here's an example: + + +{"class":"ATT","time":1270938096.843, + "heading":14223.00,"mag_st":"N", + "pitch":169.00,"pitch_st":"N", "roll":-43.00,"roll_st":"N", + "dip":13641.000,"mag_x":2454.000} + + + + + + +And here are the commands: + + + + +?VERSION; +Returns an object with the following attributes: + +VERSION object + + + + Name + Always? + Type + Description + + + + + class + Yes + string + Fixed: "VERSION" + + + release + Yes + string + Public release level + + + rev + Yes + string + Internal revision-control level. + + + proto_major + Yes + numeric + API major revision level. + + + proto_minor + Yes + numeric + API minor revision level. + + + remote + No + string + URL of the remote daemon reporting this version. If + empty, this is the version of the local daemon. + + + +
+ +The daemon ships a VERSION response to each client when the +client first connects to it. + +When the C client library parses a response of this kind, it +will assert the VERSION_SET bit in the top-level set member. + +Here's an example: + + +{"class":"VERSION","version":"2.40dev", + "rev":"06f62e14eae9886cde907dae61c124c53eb1101f", + "proto_major":3,"proto_minor":1 +} + + + + + + + +?DEVICES; +Returns a device list object with the +following elements: + +DEVICES object + + + + Name + Always? + Type + Description + + + + + class + Yes + string + Fixed: "DEVICES" + + + devices + Yes + list + List of device descriptions + + + remote + No + string + URL of the remote daemon reporting the device set. If + empty, this is a DEVICES response from the local daemon. + + + +
+ +When the C client library parses a response of this kind, it +will assert the DEVICELIST_SET bit in the top-level set member. + +Here's an example: + + +{"class"="DEVICES","devices":[ + {"class":"DEVICE","path":"/dev/pts/1","flags":1,"driver":"SiRF binary"}, + {"class":"DEVICE","path":"/dev/pts/3","flags":4,"driver":"AIVDM"}]} + + +The daemon occasionally ships a bare DEVICE object to the client +(that is, one not inside a DEVICES wrapper). The data content of these +objects will be described later as a response to the ?DEVICE command. + + + + + +?WATCH; + + +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. + +A WATCH object has the following elements: + +WATCH object + + + + Name + Always? + Type + Description + + + + + class + Yes + string + Fixed: "WATCH" + + + enable + No + boolean + Enable (true) or disable (false) watcher mode. Default + is true. + + + json + No + boolean + Enable (true) or disable (false) dumping of JSON reports. + Default is false. + + + nmea + No + boolean + Enable (true) or disable (false) dumping of binary + packets as pseudo-NMEA. Default + is false. + + + raw + No + integer + + Controls 'raw' mode. When this attribute is set to 1 + for a channel, gpsd 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, + gpsd reports the received data verbatim + without hex-dumping. + + + scaled + No + boolean + If true, apply scaling divisors to output before + dumping; default is false. + + + split24 + No + boolean + 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. + + + pps + No + boolean + If true, emit the TOFF JSON message on each cycle and a + PPS JSON message when the device issues 1PPS. Default is false. + + + device + No + string + 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. + + + remote + No + string + URL of the remote daemon reporting the watch set. If + empty, this is a WATCH response from the local daemon. + + + +
+ +There is an additional boolean "timing" attribute which is +undocumented because that portion of the interface is considered +unstable and for developer use only. + +In watcher mode, GPS reports are dumped as TPV and SKY +responses. AIS, Subframe and RTCM reporting is described in the next +section. + +When the C client library parses a response of this kind, it +will assert the POLICY_SET bit in the top-level set member. + +Here's an example: + + +{"class":"WATCH", "raw":1,"scaled":true} + + + + + + +?POLL; + + +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. + +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. + +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. + +POLL object + + + + Name + Always? + Type + Description + + + + + class + Yes + string + Fixed: "POLL" + + + time + Yes + Numeric + Timestamp in ISO 8601 format. May have a + fractional part of up to .001sec precision. + + + active + Yes + Numeric + Count of active devices. + + + tpv + Yes + JSON array + Comma-separated list of TPV objects. + + + sky + Yes + JSON array + Comma-separated list of SKY objects. + + + +
+ +Here's an example of a POLL response: + + +{"class":"POLL","time":"2010-06-04T10:31:00.289Z","active":1, + "tpv":[{"class":"TPV","device":"/dev/ttyUSB0", + "time":"2010-09-08T13:33:06.095Z", + "ept":0.005,"lat":40.035093060, + "lon":-75.519748733,"track":99.4319,"speed":0.123,"mode":2}], + "sky":[{"class":"SKY","device":"/dev/ttyUSB0", + "time":1270517264.240,"hdop":9.20, + "satellites":[{"PRN":16,"el":55,"az":42,"ss":36,"used":true}, + {"PRN":19,"el":25,"az":177,"ss":0,"used":false}, + {"PRN":7,"el":13,"az":295,"ss":0,"used":false}, + {"PRN":6,"el":56,"az":135,"ss":32,"used":true}, + {"PRN":13,"el":47,"az":304,"ss":0,"used":false}, + {"PRN":23,"el":66,"az":259,"ss":0,"used":false}, + {"PRN":20,"el":7,"az":226,"ss":0,"used":false}, + {"PRN":3,"el":52,"az":163,"ss":32,"used":true}, + {"PRN":31,"el":16,"az":102,"ss":0,"used":false} +]}]} + + + +Client software should not assume the field inventory of the +POLL response is fixed for all time. As +gpsd collects and caches more data from +more sensor types, those data are likely to find their way +into this response. + + + + + + +TOFF + + +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). + +This message exactly mirrors the PPS message except for two +details. + +TOFF emits no NTP precision, this is assumed to be -2. See +the NTP documentation for their definition of precision. + + The TOFF message reports the GPS time as derived from the GPS +serial data stream. The PPS message reports the GPS time as derived +from the GPS PPS pulse. + +A TOFF object has the following elements: + +TOFF object + + + + Name + Always? + Type + Description + + + + + class + Yes + string + Fixed: "TOFF" + + + device + Yes + string + Name of originating device + + + real_sec + Yes + numeric + seconds from the GPS clock + + + real_nsec + Yes + numeric + nanoseconds from the GPS clock + + + clock_sec + Yes + numeric + seconds from the system clock + + + clock_nsec + Yes + numeric + nanoseconds from the system clock + + + +
+ +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. + +The message contains two second/nanosecond pairs: real_sec and +real_nsec contain the time the GPS thinks it was at the start of the +current cycle; clock_sec and clock_nsec contain the time the system +clock thinks it was on receipt of the first timing message of the cycle. +real_nsec is always to nanosecond precision. clock_nsec is nanosecond +precision on most systems. + +Here's an example: + + +{"class":"TOFF","device":"/dev/ttyUSB0", + "real_sec":1330212592, "real_nsec":343182, + "clock_sec":1330212592,"clock_nsec":343184, + "precision":-2}} + + + + + + +PPS + + +This message is emitted each time the daemon sees a valid PPS (Pulse +Per Second) strobe from a device. + +This message exactly mirrors the TOFF message except for two +details. + +PPS emits the NTP precision. See the NTP documentation for their +definition of precision. + +The TOFF message reports the GPS time as derived from the GPS +serial data stream. The PPS message reports the GPS time as derived +from the GPS PPS pulse. + +There are various sources of error in the reported clock times. +The speed of the serial connection between the GPS and the system adds +a delay to 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. + +A PPS object has the following elements: + +PPS object + + + + Name + Always? + Type + Description + + + + + class + Yes + string + Fixed: "PPS" + + + device + Yes + string + Name of originating device + + + real_sec + Yes + numeric + seconds from the PPS source + + + real_nsec + Yes + numeric + nanoseconds from the PPS source + + + clock_sec + Yes + numeric + seconds from the system clock + + + clock_nsec + Yes + numeric + nanoseconds from the system clock + + + precision + Yes + numeric + NTP style estimate of PPS precision + + + +
+ +This message is emitted once per second to watchers of a device +emitting PPS, and reports the time of the start of the GPS second (when +the 1PPS arrives) and seconds as reported by the system clock (which +may be NTP-corrected) at that moment. + +The message contains two second/nanosecond pairs: real_sec and +real_nsec contain the time the GPS thinks it was at the PPS edge; +clock_sec and clock_nsec contain the time the system clock thinks it was +at the PPS edge. real_nsec is always to nanosecond precision. clock_nsec +is nanosecond precision on most systems. + +There are various sources of error in the reported clock times. +For PPS delivered via a real serial-line strobe, serial-interrupt +latency plus processing time to the timer call should be bounded above +by about 10 microseconds; that can be reduced to less than 1 microsecond if +your kernel supports RFC 2783. USB1.1-to-serial control-line emulation is +limited to about 1 millisecond. seconds. + +Here's an example: + + +{"class":"PPS","device":"/dev/ttyUSB0", + "real_sec":1330212592, "real_nsec":343182, + "clock_sec":1330212592,"clock_nsec":343184, + "precision":-3} + + + + + + +OSC + + +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). + +An OSC object has the following elements: + +OSC object + + + + Name + Always? + Type + Description + + + + + class + Yes + string + Fixed: "OSC" + + + device + Yes + string + Name of originating device. + + + running + Yes + boolean + If true, the oscillator is currently running. Oscillators may require warm-up time at start of day. + + + reference + Yes + boolean + If true, the oscillator is receiving a GPS PPS signal. + + + disciplined + Yes + boolean + If true, the GPS PPS signal is sufficiently stable and is being used to discipline the local oscillator. + + + delta + Yes + numeric + The time difference (in nanoseconds) between the GPS-disciplined oscillator PPS output pulse and the most recent GPS PPS input pulse. + + + +
+ +Here's an example: + + +{"class":"OSC","running":true,"device":"/dev/ttyUSB0", + "reference":true,"disciplined":true,"delta":67} + + + + + +?DEVICE + + +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. + +Pay attention to the response, because it is +possible for this command to fail if the GPS does not support a +speed-switching command or only supports some combinations of +serial modes. In case of failure, the daemon and GPS will +continue to communicate at the old speed. + +Use the parameter-setting form with caution. On USB and +Bluetooth GPSes it is also possible for serial mode setting to fail +either because the serial adaptor chip does not support non-8N1 modes +or because the device firmware does not properly synchronize the +serial adaptor chip with the UART on the GPS chipset when the speed +changes. These failures can hang your device, possibly requiring a GPS +power cycle or (in extreme cases) physically disconnecting the NVRAM +backup battery. + +A DEVICE object has the following elements: + +DEVICE object + + + + Name + Always? + Type + Description + + + + + class + Yes + string + Fixed: "DEVICE" + + + path + No + string + 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. + + + activated + No + string + Time the device was activated as an ISO8601 + timestamp. If the device is inactive this attribute is + absent. + + + flags + No + integer + 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 + gpsd has seen identifiable packets + from the device. + + + driver + No + string + GPSD's name for the device driver type. Won't be reported before + gpsd has seen identifiable packets + from the device. + + + subtype + When the daemon sees a delayed response to a probe for + subtype or firmware-version information. + string + Whatever version information the device returned. + + + bps + No + integer + Device speed in bits per second. + + + parity + No + string + N, O or E for no parity, odd, or even. + + + stopbits + Yes + string + Stop bits (1 or 2). + + + native + No + integer + 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. + + + cycle + No + real + Device cycle time in seconds. + + + mincycle + No + real + Device minimum cycle time in seconds. Reported from + ?DEVICE when (and only when) the rate is switchable. It is + read-only and not settable. + + + +
+ +The serial parameters will (bps, parity, stopbits) be omitted in +a response describing a TCP/IP source such as an Ntrip, DGPSIP, or AIS +feed; on a serial device they will always be present. + +The contents of the flags field should be interpreted as follows: + +Device flags + + + + C #define + Value + Description + + + + + SEEN_GPS + 0x01 + GPS data has been seen on this device + + + SEEN_RTCM2 + 0x02 + RTCM2 data has been seen on this device + + + SEEN_RTCM3 + 0x04 + RTCM3 data has been seen on this device + + + SEEN_AIS + 0x08 + AIS data has been seen on this device + + + +
+ + + +When the C client library parses a response of this kind, it +will assert the DEVICE_SET bit in the top-level set member. + +Here's an example: + + +{"class":"DEVICE","bps":4800,"parity":"N","stopbits":1,"native":0} + + + + + + + +When a client is in watcher mode, the daemon will ship it DEVICE +notifications when a device is added to the pool or +deactivated. + +When the C client library parses a response of this kind, it +will assert the DEVICE_SET bit in the top-level set member. + +Here's an example: + + +{"class":"DEVICE","path":"/dev/pts1","activated":0} + + +The daemon may ship an error object in response to a +syntactically invalid command line or unknown command. It has +the following elements: + +ERROR notification object + + + + Name + Always? + Type + Description + + + + + class + Yes + string + Fixed: "ERROR" + + + message + Yes + string + Textual error message + + + +
+ +Here's an example: + + +{"class":"ERROR","message":"Unrecognized request '?FOO'"} + + +When the C client library parses a response of this kind, it +will assert the ERR_SET bit in the top-level set member. + + + +RTCM2 + +RTCM-104 is a family of serial protocols used for broadcasting pseudorange +corrections from differential-GPS reference stations. Many GPS receivers can +accept these corrections to improve their reporting accuracy. + +RTCM-104 comes in two major and incompatible flavors, 2.x and +3.x. Each major flavor has minor (compatible) revisions. + +The applicable standard for RTCM Version 2.x is RTCM +Recommended Standards for Differential NAVSTAR GPS Service +RTCM Paper 194-93/SC 104-STD. For RTCM 3.1 it is RTCM Paper +177-2006-SC104-STD. Ordering instructions for both +standards are accessible from the website of the Radio Technical Commission for Maritime +Services under "Publications". + +RTCM WIRE TRANSMISSIONS + +Differential-GPS correction stations consist of a GPS reference +receiver coupled to a low frequency (LF) transmitter. The GPS +reference receiver is a survey-grade GPS that does GPS carrier +tracking and can work out its own position to a few millimeters. It +generates range and range-rate corrections and encodes them into +RTCM104. It ships the RTCM104 to the LF transmitter over serial rs-232 +signal at 100 baud or 200 baud depending on the requirements of the +transmitter. + +The LF transmitter broadcasts the approximately 300khz radio +signal that differential-GPS radio receivers pick up. Transmitters +that are meant to have a higher range will need to transmit at the +slower rate. The higher the data rate the harder it will be for the +remote radio receiver to receive with a good signal-to-noise ration. +(Higher data rate signals can't be averaged over as long a time frame, +hence they appear noisier.) + + +RTCM WIRE FORMATS + +An RTCM 2.x message consists of a sequence of up to 33 30-bit +words. The 24 most significant bits of each word are data and the six +least significant bits are parity. The parity algorithm used is the +same ISGPS-2000 as that used on GPS satellite downlinks. Each RTCM +2.x message consists of two header words followed by zero or more data +words, depending upon message type. + +An RTCM 3.x message begins with a fixed leader byte 0xD3. That +is followed by six bits of version information and 10 bits of payload +length information. Following that is the payload; following the +payload is a 3-byte checksum of the payload using the Qualcomm CRC-24Q +algorithm. + + +RTCM2 JSON FORMAT + +Each RTCM2 message is dumped as a single JSON object per +message, with the message fields as attributes of that object. Arrays +of satellite, station, and constellation statistics become arrays of +JSON sub-objects. Each sentence will normally also have a "device" +field containing the pathname of the originating device. + +All attributes other than the device field are mandatory. Header +attributes are emitted before others. + +Header portion + +SKY object + + + + Name + Type + Description + + + + + class + string + Fixed: "RTCM2". + + + type + integer + Message type (1-9). + + + station_id + integer + The id of the GPS reference receiver. The + LF transmitters also have (different) id numbers. + + + zcount + real + 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 table of leap second + corrections). + + + seqnum + integer + Sequence number. Only 3 bits wide, wraps after 7. + + + length + integer + The number of words after the header that comprise the + message. + + + station_health + integer + 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. + + + +
+ +<message type> is one of + + + +1 +full corrections - one message containing corrections for +all GPS satellites in view. This is not common. + + + +3 +reference station parameters - the position of the +reference station GPS antenna. + + + +4 +datum — the datum to which the DGPS data is +referred. + + + +5 +constellation health — information about the +satellites the beacon can see. + + + +6 +null message — just a filler. + + + +7 +radio beacon almanac — information about this or other beacons. + + + +9 +subset corrections — a message containing corrections +for only a subset of the GPS satellites in view. + + + +16 +special message — a text message from the beacon +operator. + + + +31 +GLONASS subset corrections — a message +containing corrections for a set of the GLONASS satellites in +view. + + + + + + +Type 1 and 9: Correction data + +One or more satellite objects follow the header for type 1 or type 9 +messages. Here is the format: + +Satellite object + + + + Name + Type + Description + + + + + ident + integer + The PRN number of the satellite for which this is + correction data. + + + udre + integer + User Differential Range Error (0-3). See the + table following for values. + + + iod + integer + 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. + + + prc + real + 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. + + + rrc + real + 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. + + + +
+ +User Differential Range Error values are as follows: + +UDRE values + + +01-sigma error <= 1m +11-sigma error <= 4m +21-sigma error <= 8m +31-sigma error > 8m + + +
+ +Here's an example: + + +{"class":"RTCM2","type":1, + "station_id":688,"zcount":843.0,"seqnum":5,"length":19,"station_health":6, + "satellites":[ + {"ident":10,"udre":0,"iod":46,"prc":-2.400,"rrc":0.000}, + {"ident":13,"udre":0,"iod":94,"prc":-4.420,"rrc":0.000}, + {"ident":7,"udre":0,"iod":22,"prc":-5.160,"rrc":0.002}, + {"ident":2,"udre":0,"iod":34,"prc":-6.480,"rrc":0.000}, + {"ident":4,"udre":0,"iod":47,"prc":-8.860,"rrc":0.000}, + {"ident":8,"udre":0,"iod":76,"prc":-7.980,"rrc":0.002}, + {"ident":5,"udre":0,"iod":99,"prc":-8.260,"rrc":0.002}, + {"ident":23,"udre":0,"iod":81,"prc":-8.060,"rrc":0.000}, + {"ident":16,"udre":0,"iod":70,"prc":-11.740,"rrc":0.000}, + {"ident":30,"udre":0,"iod":4,"prc":-18.960,"rrc":-0.006}, + {"ident":29,"udre":0,"iod":101,"prc":-24.960,"rrc":-0.002} +]} + + + +Type 3: Reference Station Parameters + +Here are the payload members of a type 3 (Reference Station +Parameters) message: + +Reference Station Parameters + + + + Name + Type + Description + + + + + x + real + ECEF X coordinate. + + + y + real + ECEF Y coordinate. + + + z + real + ECEF Z coordinate. + + + +
+ +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. + +An invalid reference message is represented by a type 3 header +without payload fields. + +Here's an example: + + +{"class":"RTCM2","type":3, + "station_id":652,"zcount":1657.2,"seqnum":2,"length":4,"station_health":6, + "x":3878620.92,"y":670281.40,"z":5002093.59 +} + + + +Type 4: Datum + +Here are the payload members of a type 4 (Datum) message: + +Datum + + + + Name + Type + Description + + + + + dgnss_type + string + Either "GPS", "GLONASS", "GALILEO", or + "UNKNOWN". + + + dat + integer + 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. + + + datum_name + string + A standard name for the datum. + + + + dx + real + X offset. + + + dy + real + Y offset. + + + dz + real + Z offset. + + + +
+ +<dx> <dy> <dz> are offsets to convert from +local datum to GNSS datum or vice versa. These fields are +optional. + +An invalid datum message is represented by a type 4 header +without payload fields. + + +Type 5: Constellation Health + +One or more of these follow the header for type 5 messages — one +for each satellite. + +Here is the format: + +Constellation health + + + + Name + Type + Description + + + + + ident + integer + The PRN number of the satellite. + + + iodl + bool + True indicates that this information relates to + the satellite information in an accompanying type 1 or type 9 + message. + + + health + integer + 0 indicates that the satellite is healthy. Any other value + indicates a problem (coding is not known). + + + snr + integer + The carrier/noise ratio of the received signal in + the range 25 to 55 dB(Hz). + + + health_en + bool + If set to True it indicates that the satellite is + healthy even if the satellite navigation data says it is + unhealthy. + + + new_data + bool + True indicates that the IOD for this satellite will + soon be updated in type 1 or 9 messages. + + + los_warning + bool + Line-of-sight warning. True indicates that the + satellite will shortly go unhealthy. + + + tou + integer + Healthy time remaining in seconds. + + + +
+ + +Type 6: Null + +This just indicates a null message. There are no payload fields. + + +Unknown message + +This format is used to dump message words in hexadecimal when the +message type field doesn't match any of the known ones. + +Here is the format: + +Unknown Message + + + + Name + Type + Description + + + + + data + list + A list of strings. + + + +
+ +Each string in the array is a hex literal representing 30 bits +of information, after parity checks and inversion. The high two bits +should be ignored. + + +Type 7: Radio Beacon Almanac + +Here is the format: + +Contellation health + + + + Name + Type + Description + + + + + lat + real + Latitude in degrees, of the LF transmitter + antenna for the station for which this is an almanac. North + is positive. + + + lon + real + Longitude in degrees, of the LF transmitter + antenna for the station for which this is an almanac. + East is positive. + + + range + integer + Published range of the station in km. + + + frequency + real + Station broadcast frequency in kHz. + + + health + integer + <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. + + + + + station_id + integer + 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. + + + bitrate + integer + The transmitted bitrate. + + + +
+ +Here's an example: + + +{"class":"RTCM2","type":9,"station_id":268,"zcount":252.6, + "seqnum":4,"length":5,"station_health":0, + "satellites":[ + {"ident":13,"udre":0,"iod":3,"prc":-25.940,"rrc":0.066}, + {"ident":2,"udre":0,"iod":73,"prc":0.920,"rrc":-0.080}, + {"ident":8,"udre":0,"iod":22,"prc":23.820,"rrc":0.014} +]} + + + +Type 13: GPS Time of Week + +Here are the payload members of a type 13 (Groumf Tramitter Parameters) +message: + +Grund Transmitter Parameters + + + + Name + Type + Description + + + + + status + bool + If True, signals user to expect a type 16 explanatory + message associated with this station. Probably indicates some + sort of unusual event. + + + rangeflag + bool + 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. + + + lat + real + Degrees latitude, signed. + Positive is N, negative is S. + + + lon + real + Degrees longitude, signed. + Positive is E, negative is W. + + + range + integer + Transmission range in km (1-1024). + + + +
+ +This message type replaces message type 3 (Reference Station Parameters) +in RTCM 2.3. + + +Type 14: GPS Time of Week + +Here are the payload members of a type 14 (GPS Time of Week) +message: + +Reference Station Parameters + + + + Name + Type + Description + + + + + week + integer + GPS week (0-123). + + + hour + integer + Hour of week (0-167). + + + leapsecs + integer + Leap Seconds (0-63). + + + +
+ +Here's an example: + + +{"class":"RTCM2","type":14,"station_id":652,"zcount":1657.2, + "seqnum":3,"length":1,"station_health":6,"week":601,"hour":109, + "leapsecs":15} + + + +Type 16: Special Message + +Special Message + + + + Name + Type + Description + + + + + message + string + A text message sent by the beacon operator. + + + +
+ + +Type 31: Correction data + +One or more GLONASS satellite objects follow the header for type +1 or type 9 messages. Here is the format: + +Satellite object + + + + Name + Type + Description + + + + + ident + integer + The PRN number of the satellite for which this is + correction data. + + + udre + integer + User Differential Range Error (0-3). See the + table following for values. + + + change + boolean + Change-of-ephemeris bit. + + + tod + uinteger + Count of 30-second periods since the top of the + hour. + + + prc + real + 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. + + + rrc + real + 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. + + + +
+ +Here's an example: + + +{"class":"RTCM2","type":31,"station_id":652,"zcount":1642.2, + "seqnum":0,"length":14,"station_health":6, + "satellites":[ + {"ident":5,"udre":0,"change":false,"tod":0,"prc":132.360,"rrc":0.000}, + {"ident":15,"udre":0,"change":false,"tod":0,"prc":134.840,"rrc":0.002}, + {"ident":14,"udre":0,"change":false,"tod":0,"prc":141.520,"rrc":0.000}, + {"ident":6,"udre":0,"change":false,"tod":0,"prc":127.000,"rrc":0.000}, + {"ident":21,"udre":0,"change":false,"tod":0,"prc":128.780,"rrc":0.000}, + {"ident":22,"udre":0,"change":false,"tod":0,"prc":125.260,"rrc":0.002}, + {"ident":20,"udre":0,"change":false,"tod":0,"prc":117.280,"rrc":-0.004}, + {"ident":16,"udre":0,"change":false,"tod":17,"prc":113.460,"rrc":0.018} +]} + + + + + + +RTCM3 DUMP FORMAT + +The support for RTCM104v3 dumping is incomplete and buggy. Do not +attempt to use it for production! Anyone interested in it should read +the source code. + + +AIS DUMP FORMATS + +AIS support is an extension. It may not be present if your +instance of gpsd has been built with +a restricted feature set. + +AIS packets are dumped as JSON objects with class "AIS". Each +AIS report object contains a "type" field giving the AIS message type +and a "scaled" field telling whether the remainder of the fields are +dumped in scaled or unscaled form. (These will be emitted before any +type-specific fields.) It will also contain a "device" field naming +the data source. Other fields have names and types as specified in +the AIVDM/AIVDO Protocol Decoding document on +the GPSD project website; each message field table may be directly +interpreted as a specification for the members of the corresponding +JSON object type. + +By default, certain scaling and conversion operations are +performed for JSON output. Latitudes and longitudes are scaled to +decimal degrees rather than the native AIS unit of 1/10000th of a +minute of arc. Ship (but not air) speeds are scaled to knots rather +than tenth-of-knot units. Rate of turn may appear as "nan" if is +unavailable, or as one of the strings "fastright" or "fastleft" if it +is out of the AIS encoding range; otherwise it is quadratically mapped +back to the turn sensor number in degrees per minute. Vessel draughts +are converted to decimal meters rather than native AIS +decimeters. Various other scaling conversions are described in +"AIVDM/AIVDO Protocol Decoding". + + +SUBFRAME DUMP FORMATS + +Subframe support is always compiled into +gpsd but many GPSes do not output subframe data +or the gpsd driver may not support subframes. + + +Subframe packets are dumped as JSON objects with class "SUBFRAME". +Each subframe report object contains a "frame" field giving the subframe +number, a "tSV" field for the transmitting satellite number, a "TOW17" +field containing the 17 MSBs of the start of the next 12-second message +and a "scaled" field telling whether the remainder of the fields are +dumped in scaled or unscaled form. It will also contain a "device" field +naming the data source. Each SUBFRAME object will have a sub-object +specific to that subframe page type. Those sub-object fields have names +and types similar to those specified in the IS-GPS-200E document; each +message field table may be directly interpreted as a specification for +the members of the corresponding JSON object type. + + + +SEE ALSO + +gpsd8, +libgps3, + + + +AUTHOR + +The protocol was designed and documented by Eric S. Raymond. + + + 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 @@ + + + + +25 Jun 2011 + +gpsdctl +8 +The GPSD Project +GPSD Documentation + + +gpsdctl +tool for sending commands to gpsd over its control socket + + + + + gpdsctl + action + device + + + +DESCRIPTION + +This is a tool for sending an instance of +gpsd 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. + +The action argument may be "add" or "remove". If no daemon +instance is running when an add is requested, this program will launch +one. + +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. + +Two environment variables are +interpreted. GPSD_SOCKET sets the location of the +control socket. It defaults to +/var/run/gpsd.sock if the effective user ID of +this program is root, /tmp/gpsd.sock +otherwise. + +GPSD_OPTIONS +may be a list of options to be passed to gpsd +when this tool launches it. It defaults to an empty string. + + +RETURN VALUES + +1 if the action was unknown or the write to the control socket +failed, 0 otherwise + + + +SEE ALSO + +gpsd8, +gpsctl1, +gps1, +libgps3, +libgpsmm3, +gpsprof1, +gpsfake1. + + + +AUTHOR + +Eric S. Raymond esr@thyrsus.com. + + 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 @@ + + + + +13 Jul 2005 + +gpsdecode +1 +The GPSD Project +GPSD Documentation + + +gpsdecode +decode GPS, RTCM or AIS streams into a readable format + + + + + gpsdecode + -c + -d + -e + -j + -m + -n + -s + -t typelist + -u + -v + -D debuglevel + -V + + + +DESCRIPTION + +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 +gpsd8; +this tool uses the same decoding logic as gpsd, but with a simpler +interface intended for batch processing of data files. + +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 +gpsd8 +for applicable standards and known limitations of the decoding +logic. + +You can use this tool with +nc1 +to examine AIS feeds from AIS pooling services, RTCM feeds from RTCM +receivers or NTRIP broadcasters. + + +OPTIONS + +The option tells the program to decode +packets presented on standard input to standard output. This is the +default behavior. + +The explicitly sets the output dump format +to JSON (the default behavior). + +With the option, dump minimum lengths for +each packet type in the input (ignoring comment packets). This is +probably of interest only to GSD developers. + +The enables dumping in generated +pseudo-NME0183. + +The 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. + +The option option tells the program to report +AIS Type 24 sentence halves separately rather than attempting to +aggregate them. + +The 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. + +The suppresses scaling of AIS data to float +quantities and text expansion of numeric codes. A dump with this +option is lossless. + +The enables dumping of textual packets +to output as they are received on input, immediately preceding +corresponding output. + +The 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 + +The option directs the program to emit its +version number, then exit. + +The option sets a debug verbosity level. It is +mainly of interest to developers. + + +AIS DSV FORMAT + +With the 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. + + +SEE ALSO + +gpsd8, +gpsctl1, +gpsdctl8, +gps1, +libgps3, +libgpsmm3, +gpsprof1, +gpsfake1, + + +AUTHOR + +Eric S. Raymond esr@thyrsus.com. + + + 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 @@ + + + + +12 Feb 2005 + +gpsfake +1 +The GPSD Project +GPSD Documentation + + +gpsfake +test harness for gpsd, simulating a GPS + + + + + gpsfake + -1 + -h + -b + -c interval + -i + -D debuglevel + -l + -m monitor + -g + -n + -o options + -p + -P port + -q + -r initcmd + -s speed + -S + -u + -t + -T + -v + + logfile + + + + +DESCRIPTION + +gpsfake is a test harness for +gpsd and its clients. It opens a pty +(pseudo-TTY), launches a gpsd 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. + +gpsfake does not require root +privileges, and can be run concurrently with a production +gpsd instance without causing problems. + +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: + + + +a comment of the form #Date: yyyy-mm-dd (ISO8601 date format) may be +used to set the initial date for the log. + + + +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. + + + +a comment of the form #Transport: UDP may be used to fake a UDP source +rather than the normal pty. + + + +The gpsd instance is run in +foreground. The thread sending fake GPS data to the daemon +is run in background. + + +OPTIONS + +With the -1 option, the logfile is interpreted once only rather +than repeatedly. This option is intended to facilitate regression +testing. + +The enables a twirling-baton progress indicator +on standard error. At termination, it reports elapsed time. + +The sets the delay between sentences in +seconds. Fractional values of seconds are legal. The default is zero +(no delay). + +The 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. + +The 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 gpsd. + +The specifies a monitor program inside which the +daemon should be run. This option is intended to be used with +valgrind1, +gdb1 +and similar programs. + +The uses the monitor facility to run the +gpsd instance within gpsfake under control +of gdb. + +The 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 passes a -D +option to the daemon: thus -D 4 is shorthand for -o "-D 4". + +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. + +The -P ("port") option sets the daemon's listening port. + +The tells gpsfake to suppress normal progress +output and thus act in a quiet manner. + +The specifies an initialization command to use in pipe mode. +The default is ?WATCH={"enable":true,"json":true}. + +The sets the baud rate for the slave tty. The +default is 4800. + +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. + +The 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. + +The makes gpsfake print +some system information and then exits. + +The 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. + +The enables verbose progress reports to stderr. It is +mainly useful for debugging gpsfake +itself. + +The dumps packets as +gpsfake gathers them. It is mainly useful +for debugging gpsfake itself. + +The makes gpsfake print +a usage message and exit. + +The argument must be the name of a file containing the +data to be cycled at the device. gpsfake +will print a notification each time it cycles. + +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: tcpdump -s0 -n -A -i lo udp and port 5000. + + +MAGIC COMMENTS + +Certain magic comments in test load headers can change the +conditions of the test. These are: + + + +Serial: +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. + + +Transport: +Values 'TCP' and 'UDP' force the use of TCP and +UDP feeds respectively (the default is a pty). + + +Delay-Cookie: +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. + + + + + +CUSTOM TESTS + +gpsfake is a trivial wrapper around a +Python module, also named gpsfake, that can be used to fully script +sessions involving a gpsd instance, any +number of client sessions, and any number of fake GPSes feeding the +daemon instance with data from specified sentence logs. + +Source and embedded documentation for this module is shipped with the +gpsd development tools. You can use it to +torture-test either gpsd itself or any +gpsd-aware client application. + +Logfiles for the use with gpsfake can +be retrieved using gpspipe, +gpscat, or +gpsmon from the gpsd distribution, or any +other application which is able to create a compatible output. + +If gpsfake 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 + + +SEE ALSO + +gpsd8, +gps1, +libgps3, +libgpsmm3, +gpsctl1, +gpspipe1, +gpsprof1 +gpsmon1. + + + +AUTHOR + +Eric S. Raymond esr@thyrsus.com. + + + + + 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 @@ + + + + +18 Jan 2013 + +gpsinit +8 +The GPSD Project +GPSD Documentation + + +gpsinit +initialize CAN kernel modules for GPSD + + + + + gpsinit + -n control + -s speed + module_name + interface_name + + + gpsinit + -h + + + gpsinit + -v + + + +DESCRIPTION + +gpsinit 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. + +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. + +The program accepts the following options: + + + +-h + +Display a brief help text. + + + + +-v + +Display the version of gpsinit. + + + + +-n + +Set the CAN network number. The default is 0. + + + + +-s + +Set the baudrate to be used to communicate over the serial line +to the CAN hardware. The default is 38400 baud. + + + + +The parameter module_name is mandatory. The +socket CAN driver module module_name.ko will be +loaded. gpsinit recognize the following module +names: + + + +plx_pci +esd_usb2 +vcan +slcan + + +The parameter interface_name and -s +speed can used here. + + + +beaglebone + + The dcan module needed for the beaglebone is part of the Linux kernel, +so no module is loaded in this case. + + + + + +The parameter interface_name 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. + + + +EXAMPLES + + + +sudo gpsinit plx_pci + +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. + + + +sudo gpsinit -n 1 plx_pci + +As above, but use net 1. + + + +sudo gpsinit -s 38400 slcan /dev/ttyUSB0 + +Attempt to load the module slcan and talk to the hardware at +38400 baud connected to port /dev/ttyUSB0. + + + + +gpsinit -h + +Display a brief help message. + + + +gpsinit -v + +Display the version of gpsinit. + + + + + +SEE ALSO + +gpsd8, +gps1, +libgps3, +libgpsmm3. + + + +AUTHOR +Reinhard Arlt reinhard.arlt@t-online.de. + + 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 @@ + + + + +17 Feb 2009 + +gpsmon +1 +The GPSD Project +GPSD Documentation + + +gpsmon +real-time GPS packet monitor and control utility + + + + + gpsmon + -L + -V + -h + -n + -a + -l logfile + -t driver-prefix + + + + server + + :port + :device + + + device + + + -D debuglevel + + + +DESCRIPTION + +gpsmon 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. + +gpsmon 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. + +Unlike gpsd, +gpsmon 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 or +the t to work around this. + +gpsmon 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. + +gpsmon accepts an -h option that +displays a usage message, or a -V option to dump the package +version and exit. + +This program may be run in either of two modes, as a client for +the gpsd 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 gpsmon +will hunt for a correct baud rate and lock on to it +automatically. Possible cases look like this: + + + +localhost:/dev/ttyS1 +Look at the default port of localhost, trying both +IPv4 and IPv6 and watching output from serial device 1. + + +example.com:2317 +Look at port 2317 on example.com, trying both +IPv4 and IPv6. + + +71.162.241.5:2317:/dev/ttyS3 +Look at port 2317 at the specified IPv4 +address, collecting data from attached serial device 3. + + +[FEDC:BA98:7654:3210:FEDC:BA98:7654:3210]:2317:/dev/ttyS5 +Look at port 2317 at the specified IPv6 +address, collecting data from attached serial device 5. + + + +Unlike gpsd, +gpsmon 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. + +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. + +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. + +The -L option lists a table showing which GPS device types +gpsmon 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. + +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. + +The -n option forces gpsmon to request NMEA0183 packets instead of the +raw datastream from gpsd. + +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. + +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. + +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. + +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. + + +COMMANDS + +The following device-independent commands are available while +gpsmon is running: + + + + +i + +(Direct mode only.) Enable/disable subtype probing and +reinitialize the driver. In normal operation, +gpsmon 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 gpsd 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. + +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 n command. This is due to a +limitation in the SiRF firmware that we can't fix. + +This command will generally do nothing after the first time you +use it, because the device type will already have been discovered. + + + + +c + +(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. + + + + +l + +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. + + + + +n + +(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. + +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. + + + + +q + +Quit gpsmon. Control-C, or whatever +your current interrupt character is, works as well. + + + + +s + +(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. + +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. + + + + +t + +(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 +gpsmon support; +gpsmon 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 gpsmon. + + + + +x + +(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 of +gpsctl1. + + + + +X + +(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. + + + + +Ctrl-S + +Freeze display, suspend scrolling in debug window. + + + +Ctrl-Q + +Unfreeze display, resume normal operation. + + + + +NMEA support + +(These remarks apply to not just generic NMEA devices +but all extended NMEA devices for which +gpsmon presently has support.) + +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. + +There are no device-specific commands. Which generic +commands are available may vary by type: examine the output +of gpsmon -l to learn more. + + +SiRF support +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. + +The following commands are supported for SiRF GPSes only: + + + +A + +(Direct mode only.) Toggle reporting of 50BPS subframe data. + + + +M + +(Direct mode only.) Set (M1) or clear (M0) static +navigation. The SiRF documentation says 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. + +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. + + + +P + +(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. + + + + +To interpret what you see, you will need a copy of the +SiRF Binary Protocol Reference Manual. + + +u-blox support +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. + + + +BUGS AND LIMITATIONS + +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. + + + + +SEE ALSO + +gpsd8, +gpsdctl8, +gps1, +libgps3, +libgpsmm3, +gpsprof1, +gpsfake1, +gpsctl1, +gpscat1. +gpspipe1. + + + +AUTHOR + +Eric S. Raymond esr@thyrsus.com. + + + + 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 @@ + + + + + + 17 Jun 2018 + + + gpspipe + 1 + The GPSD Project + GPSD Documentation + + + gpspipe + tool to connect to gpsd and retrieve sentences + + + + gpspipe + -2 + -d + -D debug-level + + -h + -l + -n count + + -o filename + + -p + -r + -R + -S + -s serial-device + + -t + -T timestamp-format + + -u + -v + -w + -x + + server + + :port + + :device + + + + + + + DESCRIPTION + + gpspipe is a tool to connect +to gpsd and output the received +sentences to stdout. This makes the program useful as a pipe from +gpsd to another program or file. + + gpspipe does not require root +privileges, and can be run concurrently with other tools connecting +to the local gpsd without causing problems. + The output will consist of one or both of the raw NMEA or native +gpsd sentences. Each line can be optionally +time stamped. There is also an option to exit gracefully after a +given count of packets. + Optionally a server, TCP/IP port number and remote device can be given. +If omitted, gpspipe connects to localhost on +the default port (2947) and watches all devices opened by +gpsd. + + gpspipe may be run as a daemon, but +requires the -o flag for writing the output to a file. + + + OPTIONS + -2 sets the split24 flag on AIS reports. Note: this option +is experimental and may be changed or removed in a future release. + -d causes gpspipe to run as a daemon. + -h makes gpspipe print +a usage message and exit. + -l causes gpspipe 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. + -n [count] causes [count] sentences to be output. +gpspipe will then exit gracefully. + -o option causes the collected data to be written to the +specified file. Use of this option is mandatory +if gpspipe is run as a daemon. + -p enables dumping of profiling information in JSON. + -P enables dumping of PPS drift JSON in NMEA and raw modes. + -r causes raw NMEA sentences to be output. + -R causes super-raw (gps binary) data to be output. This overrides +NMEA and gpsd output modes. + -s option causes the collected data to be written to the +specified serial device with settings 4800 8N1. Thus +gpspipe can be used with -s and -r options +to emulate a serial port hardwired to a GPS that +gpsd is managing. + -S sets the scaled flag. + -t adds a timestamp to each sentence output. + -T sets the format of the timestamp. See + + strftime + 3 + +for the available placeholders. Setting this option implies -t. +Default setting is "%F %T" + -u usec resolution time stamp, implies -t. Use -uu to output sec.usec. + -v causes gpspipe 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. + -V prints the version, then exits. + -w causes native gpsd sentences to be +output. + -x [seconds] Exit after delay of [seconds]. + At least one of -R, -r or -w must be specified. + + + EXAMPLES + When gpsd is running, + gpspipe +-r -n 100 will send one hundred raw NMEA sentences to +standard output, then exit. + When gpsd is running, gpspipe +-x 5 -w|sed -n '/TPV/{p;q}' will wait at most 5 seconds for a +TPV message, print it to stdout, then exit. + + + SEE ALSO + + + gpsd + 8 + , + + gps + 1 + , + + libgps + 3 + , + + libgpsmm + 3 + , + + gpsprof + 1 + , + + gpsfake + 1 + , + + gpsctl + 1 + , + + gpscat + 1 + . + + gpsmon + 1 + . + + + + AUTHOR + Gary E. Miller gem@rellim.com. + + 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 @@ + + + + +30 May 2018 + +gpsprof +1 +The GPSD Project +GPSD Documentation + + +gpsprof +profile a GPS and gpsd, plotting latency information + + + + + gpsprof + -D debuglevel + -d dumpfile + -f plot_type + -h + -l logfile + -m threshold + -n samplecount + -r + -S subtitle + -T terminal + -t title + [server[:port[:device]]] + + + +DESCRIPTION + +gpsprof 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. + +Information from the default spatial plot it provides can be +useful for characterizing position accuracy of a GPS. + +gpsprof uses instrumentation built +into gpsd. It can read data from a local +or remote running gpsd. Or it can read +data from a saved logfile. + +gpsprof is designed to be lightweight +and use minimal host resources. No graphics subsystem needs to be +installed on the host running gpsprof. Simply +copy the resultant plot file to another host to be rendered +with gnuplot. + + + +OPTIONS + +The -f option sets the plot type. Currently the following plot +types are defined: + + + +space + +Generate a scatterplot of fixes and plot probable error circles. +This data is only meaningful if the GPS is held stationary while +gpsprof is running. Various statistics about +the fixes are listed at the bottom. This is the default plot type. + + + +polar + +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. + + + + + +polarunused + +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. + + + + +polarused + +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. + + + + +time + +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 gpsd was +built with the timing (latency timing support) configure option +enabled. + + + + +instrumented + +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 gpsd was built +with the timing (latency timing support) configuration option enabled. + +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. + +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. + +The components of the instrumented plot are as follows: + + + +Fix latency + +Delta between GPS time and SORC. + + + +RS232 time + +RS232 transmission time for data shipped during the cycle +(computed from character volume and baud rate). + + + +Analysis time + +EORC, minus SORC, minus RS232 time. The amount of real time the daemon +spent on computation rather than I/O. + + + +Reception time + +Shipping time from +the daemon to when it was received by gpsprof. + + + + +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. + + + + +uninstrumented + +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. + + + + + +The -d option dumps the plot data, without attached gnuplot +code, to a specified file for post-analysis. + +The -D sets debug level. + +The -h option makes gpsprof print +a usage message and exit. + +The -l option dumps the raw JSON reports collected from the device +to a specified file. + +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. + +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. + +The -S option sets a text string to be included in the plot +as a subtitle. This will be below the title. + +The -t option sets a text string to be the plot title. This +will replace the default title. + +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. + Different installations of gnuplot 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. + + +SIGNALS +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. + + +EXAMPLES +To display the graph, use +gnuplot1. +Thus, for example, to display the default spatial scatter plot, do +this: + + +gpsprof | gnuplot -persist + + + +To generate an image file: + + +gpsprof -T png | gnuplot > image.png + + + +To generate a polar plot, and save the GPS data for further plots: + +gpsprof -f polar -T jpeg -l polar.json | gnuplot > polar.png + +Then to make the matching polarused and polarunused plots and pngs from +the just saved the GPS data: + +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 + + + + +SEE ALSO + +gpsd8, +gps1, +libgps3, +libgpsmm3, +gpsfake1, +gpsctl1, +gpscat1, +gnuplot1. + + + +AUTHOR + +Eric S. Raymond esr@thyrsus.com. + + + + + 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 @@ + + + + + 09 Nov 2018 + + + gpsrinex + 1 + The GPSD Project + GPSD Documentation + + + gpsrinex + Read data from gpsd convert to RINEX3 and save to a file. + + + + gpsrinex + -D debuglevel + -f filename + -h + -i interval + -n count + -V + + server + + :port + + :device + + + + + + + DESCRIPTION + + gpsrinex is a tool to connect to +gpsd and output the received raw measurements +as a RINEX 3 observation file. This is useful for sending raw measurements +(pseudorange and carrierphase) from gpsd to +a Precise Point Positioning (PPP) program or service. + + gpsrinex does not require root +privileges, and can be run concurrently with other tools connecting +to a local or remote gpsd without causing +problems. + gpsrinex needs the GPS receiver to be sending raw measurements +to gpsd. Only a few GPS have this capability. +In addition, the gpsd 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 +ubxtool. + 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. + + gpsrinex 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. + 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. + Optionally a server, TCP/IP port number and remote device can +be given. If omitted, gpsrinex connects to +localhost on the default port (2947) and watches all devices opened by +gpsd. + + + OPTIONS + -D [debuglevel] set debug level to [debuglevel]. + -f [filename] save RINEX into [filename]. + -h makes gpsrinex print +a usage message and exit. + -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. + -n [count] causes [count] epochs to be output. OPUS requires a +minimum af 15 minutes, and a maximum of 48 hours, of data. + -V makes gpsrinex print +its version and exit. + + + EXAMPLES + Example 1: + Create a 4 hour .obs file. With a running +gpsd accessible on the localhost do all of +the following, in order. Order matters. + The raw measurement messages are long. Be sure your serial port +speed is high enough: + +gpsctl -s 115200 + + Disable all NMEA messages, and enable binary messages: + +ubxtool -d NMEA +ubxtool -e BINARY + + The NEO-M8N will only reliably output raw measurements +when only the GPS and QZSS constellations are enabled. +ubxtool, as recommended by u-blox, enables +the QZSS constellation in tandem with GPS. Disable all constellations, +except GPS (and QZSS): + + +ubxtool -d GLONASS +ubxtool -d BEIDOU +ubxtool -d GALILEO +ubxtool -d SBAS +ubxtool -e GPS + + Verify the constellations enabled: + +ubxtool -p GNSS + + Enable the good stuff, the raw measurement messages: + +ubxtool -e RAWX + + Verify raw data messages are being sent: + +ubxtool | fgrep RAWX + +You should see this output: + +UBX-RXM-RAWX: +UBX-RXM-RAWX: + + Collect 4 hours of samples at 30 second intervals, save then +RINEX 3 observations in the file today.obs: + +gpsrinex -i 30 -n 480 -f today.obs + + Wait 4 hours. Enjoy a meal, or do some exercise. When +gpsrinex finishes, upload the file today.obs +to your favorite PPP service. + Example 2: + Collect raw masurement data from a remote gpsd. The +process it later with gpsrinex and +gpsprof. + Ensure the GPS is configured properly, as shown in Example 1. + Grab 4 hours of raw live data from remote +gpsd at 10.168.1.2: + +gpspipe -x 14400 -R 10.168.1.2 > 4h-raw.ubx + + When gpspipe is complete, feed the +data to gpsfake: + +gpsfake -1 -P 3000 4h-raw.ubx + + In another window, feed the data to +gpsrinex. Use -n 10000000 so that +all the data from the raw file is used:: + +gpsrinex -i 30 -n 1000000 + + Repeat the process with +gpsfake to send the data to +gpsprof. + + + SEE ALSO + One service known to work with obsrinex output is at: +https://webapp.geod.nrcan.gc.ca/geod/tools-outils/ppp.php + OPUS requires 2 frequency observation files. +https://www.ngs.noaa.gov/OPUS/ + The curious can find the RINEX 3.03 format described here: +ftp://igs.org/pub/data/format/rinex303_update1.pdf + + + gpsd + 8 + , +gpsfake1, +ubxtool1. + + + + AUTHOR + Gary E. Miller gem@rellim.com. + + 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 @@ + + + + +05 Mar 2017 + +gpxlogger +1 +The GPSD Project +GPSD Documentation + + +gpxlogger +Tool to connect to gpsd and generate a GPX file + + + + + gpxlogger + -D debug-level + -d + -e export-method + -f filename + -l + -m minmove + -h + -V + -i track timeout + + server + + :port + :device + + + + + +DESCRIPTION +This program collects fixes from gpsd +and logs them to standard output in GPX, an XML profile for track +logging. + +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 + and defaulting to 5 seconds. + +gpxlogger can use any of the +export methods that gpsd supports. +For a list of these methods, use the . +To force the method, give the one of +the colon-terminated method names from the +table. + + +OPTIONS + +The option causes gpxlogger +to emit a summary of its options and then exit. + +The option causes gpxlogger +to dump the package version and exit. + + The option sets a debug level; +it is primarily for use by GPSD developers. +It enables various progress messages to standard error. + +The option tells +gpxlogger to run as a daemon in background. +It requires the option, which directs output to a +specified logfile. + +The option sets a minimum move distance in +meters (it may include a fractional decimal part). Motions shorter +than this will not be logged. + +The option tells +gpxlogger to retry when GPSd loses the fix. +Without , gpxlogger +would quit in this case. + +If D-Bus support is available on the host, GPSD is configured to +use it, and -e dbus is specified, this program +listens to DBUS broadcasts from +gpsd via org.gpsd.fix. + +With -e sockets, or if sockets is the method +defaulted to, you may give a server-port-device specification as +arguments. + +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: + + + +localhost:/dev/ttyS1 +Look at the default port of localhost, trying both +IPv4 and IPv6 and watching output from serial device 1. + + +example.com:2317 +Look at port 2317 on example.com, trying both +IPv4 and IPv6. + + +71.162.241.5:2317:/dev/ttyS3 +Look at port 2317 at the specified IPv4 +address, collecting data from attached serial device 3. + + +[FEDC:BA98:7654:3210:FEDC:BA98:7654:3210]:2317:/dev/ttyS5 +Look at port 2317 at the specified IPv6 +address, collecting data from attached serial device 5. + + + + + +SEE ALSO + +gpsd8, +gps1 +gpspipe1 + + + +AUTHORS + + + Amaury Jacquot sxpert@sxpert.org & + Petter Reinholdtsen pere@hungry.com & + Chris Kuethe chris.kuethe@gmail.com + + + + + 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 @@ + + + + +14 Aug 2004 + +3 +3 +The GPSD Project +GPSD Documentation + + +libgps +C service library for communicating with the GPS daemon + + + + + +C: + +#include <gps.h> + + + +int gps_open + char *server + char * port + struct gps_data_t *gpsdata + + +int gps_send + struct gps_data_t *gpsdata + char *fmt... + + +int gps_read + struct gps_data_t *gpsdata + + +bool gps_waiting + const struct gps_data_t *gpsdata + int timeout + + +char *gps_data + const struct gps_data_t *gpsdata + + +int gps_unpack + char *buf + struct gps_data_t *gpsdata + + +int gps_close + struct gps_data_t *gpsdata + + +int gps_stream + struct gps_data_t *gpsdata + unsigned intflags + void *data + + +int gps_mainloop + struct gps_data_t *gpsdata + int timeout + void (*hook)(struct gps_data_t *gpsdata) + + +const char *gps_errstr + int err + + + +Python: + +import gps + +session = gps.gps(host="localhost", port="2947") + +session.stream(flags=gps.WATCH_JSON) + +for report in session: + process(report) + +del session + + + + + +DESCRIPTION + +libgps is a service library which +supports communicating with an instance of the +gpsd8 +; link it with the linker option -lgps. + +Take care to conditionalize your code on the major and +minor API version symbols in gps.h; 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. + +Calling gps_open() initializes a GPS-data +structure to hold the data collected by the GPS, and sets up access to +gpsd1 + +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. + +gps_open() 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 +gps.h for values and explanations; also see +gps_errstr(). The host address may be a DNS name, +an IPv4 dotted quad, an IPV6 address, or the special value +GPSD_SHARED_MEMORY referring to the +shared-memory export; the library will do the right thing for any of +these. + +gps_close() ends the session and should only be +called after a successful gps_open(). +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 close(). + +gps_send() 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 +gpsd1 +. +It may have % elements as for +sprintf3 +, +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 gps_stream() as a possible +alternative. + +gps_read() 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. + +gps_waiting() 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 +select2 + +call, and zeros errno on entry; you can test +errno after exit to get more information about +error conditions. Warning: under the shared-memory interface there is +a tiny race window between gps_waiting() and a +following gps_read(); in that context, because the +latter does not block, it is probably better to write a simple read +loop. + +gps_mainloop() 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. + + +gps_unpack() 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. + +gps_data() 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. + +gps_stream() asks +gpsd 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 +gps_stream() more than once with different flag +masks is allowed. + + + +WATCH_DISABLE + +Disable the reporting modes specified by the other WATCH_ flags. + + + +WATCH_ENABLE + +Disable the reporting modes specified by the other WATCH_ flags. +This is the default. + + + +WATCH_JSON + +Enable JSON reporting of data. If WATCH_ENABLE is set, and no +other WATCH flags are set, this is the default. + + + +WATCH_NMEA + +Enable generated pseudo-NMEA reporting on binary devices. + + + +WATCH_RARE + +Enable reporting of binary packets in encoded hex. + + + +WATCH_RAW + +Enable literal passthrough of binary packets. + + + +WATCH_SCALED + +When reporting AIS or Subframe data, scale integer quantities to +floats if they have a divisor or rendering formula associated with them. + + + +WATCH_NEWSTYLE + +Force issuing a JSON initialization and getting new-style +responses. This is the default. + + + +WATCH_OLDSTYLE + +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. + + + +WATCH_DEVICE + +Restrict watching to a specified device, path given as second +argument. + + + + +gps_errstr() returns an ASCII string (in +English) describing the error indicated by a nonzero return value from +gps_open(). + +Consult gps.h 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 gps_read(). +It is up to the client to zero that field when appropriate and to keep +an eye on the fix and sentence timestamps. + +The Python implementation supports the same facilities as the +socket-export calls in the C library; there is no shared-memory +interface. gps_open() 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. + + +ENVIRONMENT VARIABLES + +By setting the environment variable GPSD_SHM_KEY, +you can control the key value used to create shared-memory segment +used for communication with gpsd. This +will be useful mainly when isolating test instances of +gpsd from production ones. + + + +CODE EXAMPLE + +The following is an excerpted and simplified version of the +libgps interface code from +cgps1 +. + + + 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); + + + + +LIMITATIONS + +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. + +In the C API, incautious use of gps_send() +may lead to subtle bugs. In order to not bloat struct +gps_data_t 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. + +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 +struct gps_data_t before using +gps_send() to request any of these +responses. + + + +COMPATIBILITY + +The gps_query() 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. + +If you must send commands to the daemon explicitly, use +gps_send() but beware that this ties your code to +the GPSD wire protocol. It is not recommended. + +In earlier versions of the API gps_read() was +a blocking call and there was a POLL_NONBLOCK option to make it nonblocking. +gps_waiting() was added to reduce the number of +wrong ways to code a polling loop. + +See the comment above the symbol GPSD_API_MAJOR_VERSION +in gps.h for recent changes. + + +SEE ALSO + +gpsd8 +, +gps1 +, +libgpsmm3 +. + + + +AUTHOR +Eric S. Raymond <esr@thyrsus.com>, + C sample code Charles Curley <charlescurley@charlescurley.com> + + + 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 @@ + + + + +13 May 2005 + +libgpsmm +3 +The GPSD Project +GPSD Documentation + + +libgpsmm +libQgpsmm +C++ and QT class wrapper for the GPS daemon + + + + + +C++: + +#include <libgpsmm> + + + +struct gps_data_t *open + char *host + char *port + + +struct gps_data_t *open + void + + +struct gps_data_t *send + char *request + + +struct gps_data_t *read + void + + +struct gps_data_t *waiting + int + + +struct gps_data_t *stream + unsigned intflags + + + + +DESCRIPTION + +libgpsmm and libQgpsmm are mere wrappers over +libgps. The important difference between the libraries is that libgpsmm is targeted at C++ applications and contained in libgps, while libQgpsmm is platform independent by using QTcpSocket to connect to gpsd 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 +libgps3. +open() must be called after class constructor and before any other method +(open() is not inside the constructor since it may fail, however constructors have no return value). +The analogue of the C function gps_close() is in the destructor. + + +SEE ALSO + +gpsd8, +gps1, +libgps3. + + + +AUTHOR +Alfredo Pironti <alfredio@users.sourceforge.net>. + + + 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 @@ + + + + +25 Jan 2015 + +ntpshmmon +1 +The GPSD Project +GPSD Documentation + + +ntpshmmon +capture samples from GPS or other ntpd refclock sources + + + + + ntpshmmon + -h + -n nsamples + -s + -t seconds + -v + -V + + + +DESCRIPTION + +This program monitors the shared-memory segments updated by +gpsd8 +(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. + +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. + +Here is an example of the beginning of a report file: + + +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 + + +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. + +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. + +The fields of a sample line are as follows: + + +The keyword "sample" + +The NTP unit from which it was collected. + +Collection time of day, seconds. + +Receiver time of day, seconds. + +Clock time of day, seconds. + +Leap-second notification status. + +Source precision (log(2) of source jitter). + + + +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. + + + +-v + +Enable verbose status messages. + + + + +-c + +Device poll interval in fractional seconds - defaults to 1. + + + + +-n + +Set maximum number of samples to collect. + + + + +-s + +Remove all SHM segments used by GPSD. This +option will normally only be of interest to GPSD developers. + + + + +-t + +Set maximum time to collect samples in seconds. + + + + +-h + +Display program usage and exit. + + + + +-V + +Display program version and exit. + + + + + + +SEE ALSO + +gpsd8, +gpsdctl8, +gps1, +libgps3, +libgpsmm3, +gpsprof1, +gpsfake1. + + + +AUTHOR + +Eric S. Raymond esr@thyrsus.com. + + 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 @@ + + + + +28 Jul 2016 + +ppscheck +8 +The GPSD Project +GPSD Documentation + + +ppscheck +tool to check a serial port for PPS + + + + + ppscheck + -h + -V + device + + + +DESCRIPTION + +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. + +To check the first serial port do this: + + +ppscheck /dev/ttyS0 + + +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. + + +The program accepts the following options: + + +-h +Display help message and terminate. + + +-V + +Dump version and exit. + + + + +The "device" argument should be the pathname of a device. It will +be the device monitored. + +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. + +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. + +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! + +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. + + + + +RETURN VALUES + +1 if the device counld not be opened. 0 otherwise + + + +SEE ALSO + +gpsd8. + + + +AUTHOR + +Eric S. Raymond esr@thyrsus.com. + + 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 @@ + + + + +15 Jul 2005 + +srec +5 +The GPSD Project +GPSD Documentation + + +srec +Motorola S-record record and file format + +DESCRIPTION + +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. + +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. + +The order of S-records within a file is of no significance and +no particular order may be assumed. + +The general format of an S-record follows: + + ++-------------------//------------------//-----------------------+ +| type | count | address | data | checksum | ++-------------------//------------------//-----------------------+ + + + + +type +A char[2] field. These characters +describe the type of record (S0, S1, S2, S3, S5, S7, S8, or +S9). + + + +count +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. + + + +address +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. + + + +data +A char [0-64] field. These characters when paired and +interpreted as hexadecimal values represent the memory loadable data +or descriptive information. + + + +checksum +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. + + + +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. + +There are 9 record types, as follows: + + + +S0 + +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. + + +mname is char[20] and is the module name. +ver is char[2] and is the version number. +rev is char[2] and is the revision number. +description is char[0-36] and is a text comment. + + +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. + + + + +S1 +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. + + + +S2 +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. + + + +S3 +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. + + + +S5 +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. + + + +S7 +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. + + + +S8 +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. + + + +S9 +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. + + + + +EXAMPLE + +Shown below is a typical S-record format file. + + + S00600004844521B + S1130000285F245F2212226A000424290008237C2A + S11300100002000800082629001853812341001813 + S113002041E900084E42234300182342000824A952 + S107003000144ED492 + S5030004F8 + S9030000FC + + +The file consists of one S0 record, four S1 records, one S5 +record and an S9 record. + +The S0 record is comprised as follows: + + +S0 S-record type S0, indicating it is a header +record. + +06 Hexadecimal 06 (decimal 6), indicating that six +character pairs (or ASCII bytes) follow. + +00 00 Four character 2-byte address field, zeroes in +this example. + +48 44 52 ASCII H, D, and R - "HDR". + +1B The checksum. + + + The first S1 record is comprised as follows: + + +S1 S-record type S1, indicating it is a data record to +be loaded at a 2-byte address. + +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. + +00 00 Four character 2-byte address field; hexidecimal +address 0x0000, where the data which follows is to be +loaded. + +28 5F 24 5F 22 12 22 6A 00 04 24 29 00 08 23 7C +Sixteen character pairs representing the actual binary data. + + +2A The checksum. + + +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. + +The S5 record is comprised as follows: + + +S5 S-record type S5, indicating it is a count record +indicating the number of S1 records + +03 Hexadecimal 03 (decimal 3), indicating that three +character pairs follow. + +00 04 Hexadecimal 0004 (decimal 4), indicating that +there are four data records previous to this record. + +F8 The checksum. + + + +The S9 record is comprised as follows: + + +S9 S-record type S9, indicating it is a termination +record. + +03 Hexadecimal 03 (decimal 3), indicating that three +character pairs follow. + +00 00 The address field, hexadecimal 0 (decimal 0) +indicating the starting execution address. + +FC The checksum. + + + +NOTES + + + 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. + +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. + + 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 + pairs, including checksum. + + 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. + + + +SEE ALSO + +gpsd8, +gps1, +libgps3, +libgpsmm3, +gpsfake1. +gpsprof1. + + + +AUTHOR + +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. + + + 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 @@ + + + + + + 24 Sep 2018 + + + ubxtool + 1 + The GPSD Project + GPSD Documentation + + + ubxtool + u-blox tool + + + + ubxtool + -? + -c command + + -d disable + + -e enable + + -f file/device + + -h + -m mode + -P protver + -p preset + -R rawfile + -r + -S setspeed + -s speed + -V + -v verbosity + -w wait + [server[:port[:device]]] + + + + DESCRIPTION + + ubxtool is a tool for u-blox GPS. +If you do not have a u-blox GPS then can stop reading now. + This tool operates with your u-blox GPS at a very low level. +To understand ubxtool 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. + + + ubxtool 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. + + + OPTIONS + The program accepts the following options: + + + -c COMMAND + + 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. + + + + + -d OPTION + + Disable an option in the GPS. Accepts one parameter, OPTION, +the option to disable. + + + + BEIDOU + + Disable use of the BeiDou (COMPASS) constellation. + + + + BINARY + + Disable sending of the basic binary messages. + + + + ECEF + + Disable sending of ECEF binary messages. + + + + GALILEO + + Disable use of the GALILEO constellation. + + + + GLONASS + + Disable use of the GLONASS constellation. + + + + GPS + + Disable use of the GPS and QZSS constellations. + + + + NMEA + + Disable sending basic NMEA messages. The messages are +GBS, GGA, GSA, GGL, GST, GSV, RMC, VTG, and ZDA. + + + + RAWX + + Disable sending of the UBX-RXM-RAWX messages. + + + + SBAS + + Disable use of the SBAS constellation. + + + + TMODE2 + + Disable sending TMODE2. + + + + TP + + Disable sending UBX-TIM-TP. + + + + + + + -e OPTION + + 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. + + + + + -f FILE + + 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. + + + + + -h + + Makes ubxtool print +a usage message and exit. + + + + -m mode + + Sets optional mode parameter to a -p PRESET command. + + + + + -P protver + + Sets the protocol version to use for sending commands. Minimum +10 (ublox 5). Maximum 27 (u-blox 9) + + + + + -p PRESET + + Send a preset command the GPS. Accepts one parameter, PRESET, +the name of the command to send. ubxtool will exit +after the GPS acknowledges the command, unless the -W is given. + + + + ANT + + Poll the antenna configuration (UBX-CFG-ANT). + + + + COLDBOOT + + Coldboot the GPS (UBX-CFG-RST). + + + + GNSS + + Poll the enabled constellations (UBX-CFG-GNSS). + + + + HOTBOOT + + Hotboot the GPS (UBX-CFG-RST). + + + + MODEL + + Configure the Dynamic Platform Model. (UBX-CFG-NAV5). + + + + + NAV5 + + Poll the Nav Engines settings (UBX-CFG-NAV6. + + + + RXM-RAWX + + Poll UBX-RXM-RAWX message. + + + + RESET + + Reset configuration to defaults (UBX-CFG-CFG). + + + + SAVE + + Save current configuration (UBX-CFG-CFG). + + + + SVIN + + Poll survey in data (UBX-CFG-SVIN). + + + + TMODE2 + + Poll Time Mode 2 configuration (UBX-CFG-TMODE2). + + + + TP + + Poll time pulse timedata (UBX-TIM-TP). + + + + TP5 + + Get Time Pulse decodes (UBX-TIM-TP5). + + + + VER + + Poll GPS version. + + + + WARMBOOT + + Warmboot the GPS (UBX-CFG-RST). + + + + + + + -R RAW + + Save all raw data from the GPS into the file RAW. + + + + -r + + Read only. Do not send anything to the GPS. + + + + -S SPEED + + Set the GPS serial port speed to SPEED bps. + + + + -s SPEED + + Set local serial port speed to SPEED bps. Default 115,200 bps. + + + + -V + + Print ubxtool version and exit. + + + + -v VERBOSITY + + Set verbosity level to VERBOSITY. Verbosity can be from 0 + (very quiet), to 4 (very noisy). Default 2. + + + + -v VERBOSITY + + Set verbosity level to VERBOSITY. Verbosity can be from 0 + (very quiet), 2 (decode messages), to 4 (very noisy). Default 1. + + + + -w WAIT + + 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. + + + + -? + + Makes ubxtool print +a usage message and exit. + + + + [server[:port[:device]]] + + + By default, ubxtool 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 + + gps + 1 + man page. + + + + + + + ENVIRONMENT + Options can be placed in the UBXOPTS environment variable. +UBXOPTS is processed before the CLI options. + + + EXAMPLES + +Decode raw log file: + +ubxtool -r -f ublox-neo-m8n.log + + + +Change GPS port speed of device on /dev/ttyAMA0 to 230,400 bps:: + +ubxtool -S 230400 -f /dev/ttyAMA0 + + + +Watch entire GPS reset cycle, include $GPTXT messages: + +ubxtool -p COLDBOOT -w 20 -v 2 + + + +Poll Enabled Constellations: + +ubxtool -p GNSS + +Dump gpsd data from remote server: + +ubxtool -w 5 server + + + + + SEE ALSO + + ubxtool is written to conform to the official +u-blox documentation for the u-blox binary protocol. + + + + gpsd + 8 + , + + gps + 1 + , + + cgps + 1 + , + + xgps + 1 + , + + gpsfake + 1 + , + + gpsctl + 1 + , + + gpscat + 1 + , + + gnuplot + 1 + . + + + + AUTHOR + Gary E. Millergem@rellim.com + + + 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 @@ + + + + + + 18 Sep 2018 + + + zerk + 1 + The GPSD Project + GPSD Documentation + + + zerk + All purpose GREIS fitting + + + + zerk + -? + -c command + + -d disable + + -e enable + + -f file/device + + -h + -O oaf + + -p preset + -R rawfile + + -r + -S setspeed + + -s speed + + -V + -v verbosity + + -W + -w wait + + [server[:port[:device]]] + + + + DESCRIPTION + + zerk 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. + This tool operates with your Javad GPS at a very low level. +To understand zerk you must first be familiar +with your Javad GPS and the documentation for the GREIS protocol. +GREIS (GNSS Receiver External Interface Specification) Guide. + + + zerk 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. + + + OPTIONS + The program accepts the following options: + + + -c COMMAND + + 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. + + + + + -d OPTION + + Disable an option in the GPS. Accepts one parameter, OPTION, +the option to disable. zerk will exit after +the GPS acknowledges the command, unless the -W is given. + + + + 4HZ + + Disable basic GREIS messages at 4Hz. The messages are: +[RT], [UO], [GT], [PV], [SG], [DP], [SI], [EL], [AZ], [EC], [SS], and +[ET] + + + + COMPASS + + Disable use of the COMPASS (BeiDou) constellation. + + + + CONS + + Disable use of all constellations. + + + + DEFMSG + + Disable the default message set (/dev/msg) at 1Hz. + + + + GALILEO + + Disable use of the GALILEO constellation. + + + + GLONASS + + Disable use of the GLONASS constellation. + + + + GPS + + Disable use of the GPS constellation. + + + + IPR + + Disable all Integer Pseudo Range messages. These are + [rx], [rc], [r1], [r2], [r3], [r5], [rl]. + + + + IRNSS + + Disable use of the IRNSS constellation. + + + + NMEA + + Disable basic NMEA 4.1e messages at 4Hz. The messages are +GBS, GGA, GSA, GST, GSV, RMC, VTG, and ZDA. + + + + QZSS + + Disable use of the QZSS constellation. + + + + SBAS + + Disable use of the SBAS constellation. + + + + SNR + + Disable all SNR messages, except [EC]. The messages +disabled are: [E1], [E2], [E3], [E5], [El]. + + + + + + + -e OPTION + + Enable an option in the GPS. Accepts one parameter, OPTION, +the option to enable. zerk 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. + + + + + -f FILE + + 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. + + + + + -h + + Makes zerk print +a usage message and exit. + + + + -O OAF + + 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. + + + + + -p PRESET + + Send a preset command the GPS. Accepts one parameter, PRESET, +the name of the command to send. zerk will exit after +the GPS acknowledges the command, unless the -W is given. + + + + COLDBOOT + + Coldboot the GPS. + + + + CONS + + Poll the enabled constellations. + + + + DM + + Disable all periodic GREIS messages.. + + + + ID + + Poll the receiver ID. + + + + IPR + + Poll all Integer Pseudo Range messages. These are + [rx], [rc], [r1], [r2], [r3], [r5], [rl]. + + + + OAF + + Poll all OAF options. + + + + RESET + + Reset (reboot) the GPS. + + + + SERIAL + + Poll receiver serial number. + + + + SNR + + Poll all Signal to Noise Ratio (SNR) messages. +[EC], [E1], [E2], [E3], [E5], [El]. + + + + VENDOR + + Poll GPS vendor. + + + + VER + + Poll GPS version. + + + + + + + -r + + Read only. Do not send anything to the GPS. + + + + -R RAW + + Save all raw data from the GPS into the file RAW. + + + + -S SPEED + + Configure the GPS serial speed to SPEED bps. + + + + -s SPEED + + Set local serial port speed to SPEED bps. Default 115,200 bps. + + + + -V + + Print zerk version and exit. + + + + -v VERBOSITY + + Set verbosity level to VERBOSITY. Verbosity can be from 0 + (very quiet), to 4 (very noisy). Default 2. + + + + -v VERBOSITY + + Set verbosity level to VERBOSITY. Verbosity can be from 0 + (very quiet), 2 (decode messages), to 4 (very noisy). Default 1. + + + + -W + + Force waiting the entire wait time. No early exit for completion +of -d, -e or -p command. + + + + -w WAIT + + 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. + + + + [server[:port[:device]]] + + + By default, zerk 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 + + gps + 1 + man page. + + + + + -? + + Makes zerk print +a usage message and exit. + + + + + + ENVIRONMENT + Options can be placed in the ZERKOPTS environment variable. +ZERKOPTS is processed before the CLI options. + + + EXAMPLES + +Print current Javad serial portC of GPS connected to local running gpsd:: + + zerk -c "print,/cur/term" + + + +Decode raw log file: + +zerk -r -f greis-binary.log -v 2 + + + +Change GPS port speed of device on /dev/ttyAMA0 to 230,400 bps:: + +zerk -S 230400 -f /dev/ttyAMA0 + + + +Watch entire GPS reset cycle: + +zerk -p RESET -v 2 -w 20 -W + + + +Poll SVs Status: + +zerk -W -w 2 -v 2 -c "out,,jps/{CS,ES,GS,Is,WS,QS}" + +Dump gpsd data from remote server: + +zerk -v 2 -w 5 server + + + + + SEE ALSO + + zerk is written to conform to the official +Javad documentation for the GREIS protocol. +GREIS (GNSS Receiver External Interface Specification) Guide. + + + + gpsd + 8 + , + + gps + 1 + , + + cgps + 1 + , + + xgps + 1 + , + + gpsfake + 1 + , + + gpsctl + 1 + , + + gpscat + 1 + , + + gnuplot + 1 + . + + + + AUTHOR + Gary E. Millergem@rellim.com + + + diff --git a/ntpshmmon.xml b/ntpshmmon.xml deleted file mode 100644 index bcb083a3..00000000 --- a/ntpshmmon.xml +++ /dev/null @@ -1,165 +0,0 @@ - - - - -25 Jan 2015 - -ntpshmmon -1 -The GPSD Project -GPSD Documentation - - -ntpshmmon -capture samples from GPS or other ntpd refclock sources - - - - - ntpshmmon - -h - -n nsamples - -s - -t seconds - -v - -V - - - -DESCRIPTION - -This program monitors the shared-memory segments updated by -gpsd8 -(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. - -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. - -Here is an example of the beginning of a report file: - - -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 - - -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. - -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. - -The fields of a sample line are as follows: - - -The keyword "sample" - -The NTP unit from which it was collected. - -Collection time of day, seconds. - -Receiver time of day, seconds. - -Clock time of day, seconds. - -Leap-second notification status. - -Source precision (log(2) of source jitter). - - - -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. - - - --v - -Enable verbose status messages. - - - - --c - -Device poll interval in fractional seconds - defaults to 1. - - - - --n - -Set maximum number of samples to collect. - - - - --s - -Remove all SHM segments used by GPSD. This -option will normally only be of interest to GPSD developers. - - - - --t - -Set maximum time to collect samples in seconds. - - - - --h - -Display program usage and exit. - - - - --V - -Display program version and exit. - - - - - - -SEE ALSO - -gpsd8, -gpsdctl8, -gps1, -libgps3, -libgpsmm3, -gpsprof1, -gpsfake1. - - - -AUTHOR - -Eric S. Raymond esr@thyrsus.com. - - diff --git a/ppscheck.xml b/ppscheck.xml deleted file mode 100644 index 8a5bdc12..00000000 --- a/ppscheck.xml +++ /dev/null @@ -1,103 +0,0 @@ - - - - -28 Jul 2016 - -ppscheck -8 -The GPSD Project -GPSD Documentation - - -ppscheck -tool to check a serial port for PPS - - - - - ppscheck - -h - -V - device - - - -DESCRIPTION - -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. - -To check the first serial port do this: - - -ppscheck /dev/ttyS0 - - -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. - - -The program accepts the following options: - - --h -Display help message and terminate. - - --V - -Dump version and exit. - - - - -The "device" argument should be the pathname of a device. It will -be the device monitored. - -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. - -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. - -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! - -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. - - - - -RETURN VALUES - -1 if the device counld not be opened. 0 otherwise - - - -SEE ALSO - -gpsd8. - - - -AUTHOR - -Eric S. Raymond esr@thyrsus.com. - - diff --git a/srec.xml b/srec.xml deleted file mode 100644 index 0e4e5be8..00000000 --- a/srec.xml +++ /dev/null @@ -1,308 +0,0 @@ - - - - -15 Jul 2005 - -srec -5 -The GPSD Project -GPSD Documentation - - -srec -Motorola S-record record and file format - -DESCRIPTION - -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. - -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. - -The order of S-records within a file is of no significance and -no particular order may be assumed. - -The general format of an S-record follows: - - -+-------------------//------------------//-----------------------+ -| type | count | address | data | checksum | -+-------------------//------------------//-----------------------+ - - - - -type -A char[2] field. These characters -describe the type of record (S0, S1, S2, S3, S5, S7, S8, or -S9). - - - -count -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. - - - -address -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. - - - -data -A char [0-64] field. These characters when paired and -interpreted as hexadecimal values represent the memory loadable data -or descriptive information. - - - -checksum -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. - - - -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. - -There are 9 record types, as follows: - - - -S0 - -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. - - -mname is char[20] and is the module name. -ver is char[2] and is the version number. -rev is char[2] and is the revision number. -description is char[0-36] and is a text comment. - - -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. - - - - -S1 -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. - - - -S2 -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. - - - -S3 -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. - - - -S5 -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. - - - -S7 -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. - - - -S8 -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. - - - -S9 -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. - - - - -EXAMPLE - -Shown below is a typical S-record format file. - - - S00600004844521B - S1130000285F245F2212226A000424290008237C2A - S11300100002000800082629001853812341001813 - S113002041E900084E42234300182342000824A952 - S107003000144ED492 - S5030004F8 - S9030000FC - - -The file consists of one S0 record, four S1 records, one S5 -record and an S9 record. - -The S0 record is comprised as follows: - - -S0 S-record type S0, indicating it is a header -record. - -06 Hexadecimal 06 (decimal 6), indicating that six -character pairs (or ASCII bytes) follow. - -00 00 Four character 2-byte address field, zeroes in -this example. - -48 44 52 ASCII H, D, and R - "HDR". - -1B The checksum. - - - The first S1 record is comprised as follows: - - -S1 S-record type S1, indicating it is a data record to -be loaded at a 2-byte address. - -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. - -00 00 Four character 2-byte address field; hexidecimal -address 0x0000, where the data which follows is to be -loaded. - -28 5F 24 5F 22 12 22 6A 00 04 24 29 00 08 23 7C -Sixteen character pairs representing the actual binary data. - - -2A The checksum. - - -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. - -The S5 record is comprised as follows: - - -S5 S-record type S5, indicating it is a count record -indicating the number of S1 records - -03 Hexadecimal 03 (decimal 3), indicating that three -character pairs follow. - -00 04 Hexadecimal 0004 (decimal 4), indicating that -there are four data records previous to this record. - -F8 The checksum. - - - -The S9 record is comprised as follows: - - -S9 S-record type S9, indicating it is a termination -record. - -03 Hexadecimal 03 (decimal 3), indicating that three -character pairs follow. - -00 00 The address field, hexadecimal 0 (decimal 0) -indicating the starting execution address. - -FC The checksum. - - - -NOTES - - - 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. - -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. - - 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 - pairs, including checksum. - - 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. - - - -SEE ALSO - -gpsd8, -gps1, -libgps3, -libgpsmm3, -gpsfake1. -gpsprof1. - - - -AUTHOR - -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. - - - diff --git a/ubxtool.xml b/ubxtool.xml deleted file mode 100644 index 493f72ab..00000000 --- a/ubxtool.xml +++ /dev/null @@ -1,458 +0,0 @@ - - - - - - 24 Sep 2018 - - - ubxtool - 1 - The GPSD Project - GPSD Documentation - - - ubxtool - u-blox tool - - - - ubxtool - -? - -c command - - -d disable - - -e enable - - -f file/device - - -h - -m mode - -P protver - -p preset - -R rawfile - -r - -S setspeed - -s speed - -V - -v verbosity - -w wait - [server[:port[:device]]] - - - - DESCRIPTION - - ubxtool is a tool for u-blox GPS. -If you do not have a u-blox GPS then can stop reading now. - This tool operates with your u-blox GPS at a very low level. -To understand ubxtool 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. - - - ubxtool 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. - - - OPTIONS - The program accepts the following options: - - - -c COMMAND - - 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. - - - - - -d OPTION - - Disable an option in the GPS. Accepts one parameter, OPTION, -the option to disable. - - - - BEIDOU - - Disable use of the BeiDou (COMPASS) constellation. - - - - BINARY - - Disable sending of the basic binary messages. - - - - ECEF - - Disable sending of ECEF binary messages. - - - - GALILEO - - Disable use of the GALILEO constellation. - - - - GLONASS - - Disable use of the GLONASS constellation. - - - - GPS - - Disable use of the GPS and QZSS constellations. - - - - NMEA - - Disable sending basic NMEA messages. The messages are -GBS, GGA, GSA, GGL, GST, GSV, RMC, VTG, and ZDA. - - - - RAWX - - Disable sending of the UBX-RXM-RAWX messages. - - - - SBAS - - Disable use of the SBAS constellation. - - - - TMODE2 - - Disable sending TMODE2. - - - - TP - - Disable sending UBX-TIM-TP. - - - - - - - -e OPTION - - 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. - - - - - -f FILE - - 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. - - - - - -h - - Makes ubxtool print -a usage message and exit. - - - - -m mode - - Sets optional mode parameter to a -p PRESET command. - - - - - -P protver - - Sets the protocol version to use for sending commands. Minimum -10 (ublox 5). Maximum 27 (u-blox 9) - - - - - -p PRESET - - Send a preset command the GPS. Accepts one parameter, PRESET, -the name of the command to send. ubxtool will exit -after the GPS acknowledges the command, unless the -W is given. - - - - ANT - - Poll the antenna configuration (UBX-CFG-ANT). - - - - COLDBOOT - - Coldboot the GPS (UBX-CFG-RST). - - - - GNSS - - Poll the enabled constellations (UBX-CFG-GNSS). - - - - HOTBOOT - - Hotboot the GPS (UBX-CFG-RST). - - - - MODEL - - Configure the Dynamic Platform Model. (UBX-CFG-NAV5). - - - - - NAV5 - - Poll the Nav Engines settings (UBX-CFG-NAV6. - - - - RXM-RAWX - - Poll UBX-RXM-RAWX message. - - - - RESET - - Reset configuration to defaults (UBX-CFG-CFG). - - - - SAVE - - Save current configuration (UBX-CFG-CFG). - - - - SVIN - - Poll survey in data (UBX-CFG-SVIN). - - - - TMODE2 - - Poll Time Mode 2 configuration (UBX-CFG-TMODE2). - - - - TP - - Poll time pulse timedata (UBX-TIM-TP). - - - - TP5 - - Get Time Pulse decodes (UBX-TIM-TP5). - - - - VER - - Poll GPS version. - - - - WARMBOOT - - Warmboot the GPS (UBX-CFG-RST). - - - - - - - -R RAW - - Save all raw data from the GPS into the file RAW. - - - - -r - - Read only. Do not send anything to the GPS. - - - - -S SPEED - - Set the GPS serial port speed to SPEED bps. - - - - -s SPEED - - Set local serial port speed to SPEED bps. Default 115,200 bps. - - - - -V - - Print ubxtool version and exit. - - - - -v VERBOSITY - - Set verbosity level to VERBOSITY. Verbosity can be from 0 - (very quiet), to 4 (very noisy). Default 2. - - - - -v VERBOSITY - - Set verbosity level to VERBOSITY. Verbosity can be from 0 - (very quiet), 2 (decode messages), to 4 (very noisy). Default 1. - - - - -w WAIT - - 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. - - - - -? - - Makes ubxtool print -a usage message and exit. - - - - [server[:port[:device]]] - - - By default, ubxtool 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 - - gps - 1 - man page. - - - - - - - ENVIRONMENT - Options can be placed in the UBXOPTS environment variable. -UBXOPTS is processed before the CLI options. - - - EXAMPLES - -Decode raw log file: - -ubxtool -r -f ublox-neo-m8n.log - - - -Change GPS port speed of device on /dev/ttyAMA0 to 230,400 bps:: - -ubxtool -S 230400 -f /dev/ttyAMA0 - - - -Watch entire GPS reset cycle, include $GPTXT messages: - -ubxtool -p COLDBOOT -w 20 -v 2 - - - -Poll Enabled Constellations: - -ubxtool -p GNSS - -Dump gpsd data from remote server: - -ubxtool -w 5 server - - - - - SEE ALSO - - ubxtool is written to conform to the official -u-blox documentation for the u-blox binary protocol. - - - - gpsd - 8 - , - - gps - 1 - , - - cgps - 1 - , - - xgps - 1 - , - - gpsfake - 1 - , - - gpsctl - 1 - , - - gpscat - 1 - , - - gnuplot - 1 - . - - - - AUTHOR - Gary E. Millergem@rellim.com - - - diff --git a/zerk.xml b/zerk.xml deleted file mode 100644 index e82d5c71..00000000 --- a/zerk.xml +++ /dev/null @@ -1,468 +0,0 @@ - - - - - - 18 Sep 2018 - - - zerk - 1 - The GPSD Project - GPSD Documentation - - - zerk - All purpose GREIS fitting - - - - zerk - -? - -c command - - -d disable - - -e enable - - -f file/device - - -h - -O oaf - - -p preset - -R rawfile - - -r - -S setspeed - - -s speed - - -V - -v verbosity - - -W - -w wait - - [server[:port[:device]]] - - - - DESCRIPTION - - zerk 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. - This tool operates with your Javad GPS at a very low level. -To understand zerk you must first be familiar -with your Javad GPS and the documentation for the GREIS protocol. -GREIS (GNSS Receiver External Interface Specification) Guide. - - - zerk 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. - - - OPTIONS - The program accepts the following options: - - - -c COMMAND - - 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. - - - - - -d OPTION - - Disable an option in the GPS. Accepts one parameter, OPTION, -the option to disable. zerk will exit after -the GPS acknowledges the command, unless the -W is given. - - - - 4HZ - - Disable basic GREIS messages at 4Hz. The messages are: -[RT], [UO], [GT], [PV], [SG], [DP], [SI], [EL], [AZ], [EC], [SS], and -[ET] - - - - COMPASS - - Disable use of the COMPASS (BeiDou) constellation. - - - - CONS - - Disable use of all constellations. - - - - DEFMSG - - Disable the default message set (/dev/msg) at 1Hz. - - - - GALILEO - - Disable use of the GALILEO constellation. - - - - GLONASS - - Disable use of the GLONASS constellation. - - - - GPS - - Disable use of the GPS constellation. - - - - IPR - - Disable all Integer Pseudo Range messages. These are - [rx], [rc], [r1], [r2], [r3], [r5], [rl]. - - - - IRNSS - - Disable use of the IRNSS constellation. - - - - NMEA - - Disable basic NMEA 4.1e messages at 4Hz. The messages are -GBS, GGA, GSA, GST, GSV, RMC, VTG, and ZDA. - - - - QZSS - - Disable use of the QZSS constellation. - - - - SBAS - - Disable use of the SBAS constellation. - - - - SNR - - Disable all SNR messages, except [EC]. The messages -disabled are: [E1], [E2], [E3], [E5], [El]. - - - - - - - -e OPTION - - Enable an option in the GPS. Accepts one parameter, OPTION, -the option to enable. zerk 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. - - - - - -f FILE - - 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. - - - - - -h - - Makes zerk print -a usage message and exit. - - - - -O OAF - - 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. - - - - - -p PRESET - - Send a preset command the GPS. Accepts one parameter, PRESET, -the name of the command to send. zerk will exit after -the GPS acknowledges the command, unless the -W is given. - - - - COLDBOOT - - Coldboot the GPS. - - - - CONS - - Poll the enabled constellations. - - - - DM - - Disable all periodic GREIS messages.. - - - - ID - - Poll the receiver ID. - - - - IPR - - Poll all Integer Pseudo Range messages. These are - [rx], [rc], [r1], [r2], [r3], [r5], [rl]. - - - - OAF - - Poll all OAF options. - - - - RESET - - Reset (reboot) the GPS. - - - - SERIAL - - Poll receiver serial number. - - - - SNR - - Poll all Signal to Noise Ratio (SNR) messages. -[EC], [E1], [E2], [E3], [E5], [El]. - - - - VENDOR - - Poll GPS vendor. - - - - VER - - Poll GPS version. - - - - - - - -r - - Read only. Do not send anything to the GPS. - - - - -R RAW - - Save all raw data from the GPS into the file RAW. - - - - -S SPEED - - Configure the GPS serial speed to SPEED bps. - - - - -s SPEED - - Set local serial port speed to SPEED bps. Default 115,200 bps. - - - - -V - - Print zerk version and exit. - - - - -v VERBOSITY - - Set verbosity level to VERBOSITY. Verbosity can be from 0 - (very quiet), to 4 (very noisy). Default 2. - - - - -v VERBOSITY - - Set verbosity level to VERBOSITY. Verbosity can be from 0 - (very quiet), 2 (decode messages), to 4 (very noisy). Default 1. - - - - -W - - Force waiting the entire wait time. No early exit for completion -of -d, -e or -p command. - - - - -w WAIT - - 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. - - - - [server[:port[:device]]] - - - By default, zerk 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 - - gps - 1 - man page. - - - - - -? - - Makes zerk print -a usage message and exit. - - - - - - ENVIRONMENT - Options can be placed in the ZERKOPTS environment variable. -ZERKOPTS is processed before the CLI options. - - - EXAMPLES - -Print current Javad serial portC of GPS connected to local running gpsd:: - - zerk -c "print,/cur/term" - - - -Decode raw log file: - -zerk -r -f greis-binary.log -v 2 - - - -Change GPS port speed of device on /dev/ttyAMA0 to 230,400 bps:: - -zerk -S 230400 -f /dev/ttyAMA0 - - - -Watch entire GPS reset cycle: - -zerk -p RESET -v 2 -w 20 -W - - - -Poll SVs Status: - -zerk -W -w 2 -v 2 -c "out,,jps/{CS,ES,GS,Is,WS,QS}" - -Dump gpsd data from remote server: - -zerk -v 2 -w 5 server - - - - - SEE ALSO - - zerk is written to conform to the official -Javad documentation for the GREIS protocol. -GREIS (GNSS Receiver External Interface Specification) Guide. - - - - gpsd - 8 - , - - gps - 1 - , - - cgps - 1 - , - - xgps - 1 - , - - gpsfake - 1 - , - - gpsctl - 1 - , - - gpscat - 1 - , - - gnuplot - 1 - . - - - - AUTHOR - Gary E. Millergem@rellim.com - - - -- cgit v1.2.1