<?xml version="1.0" encoding="ISO-8859-1"?><!DOCTYPE refentry PUBLIC    "-//OASIS//DTD DocBook XML V4.1.2//EN"   "docbook/docbookx.dtd"><refentry id='gpsd.1'><refmeta><refentrytitle>gpsd</refentrytitle><manvolnum>1</manvolnum><refmiscinfo class='date'>9 Aug 2004</refmiscinfo></refmeta><refnamediv id='name'><refname>gpsd</refname><refname>gps</refname><refname>xgpsspeed</refname><refpurpose>interface daemon for GPS receivers, test client,and speedometer</refpurpose></refnamediv><refsynopsisdiv id='synopsis'><cmdsynopsis>  <command>gpsd</command>        <arg choice='opt'>-T <replaceable>GPS-type</replaceable></arg>      <arg choice='opt'>-p <replaceable>GPS-devicename</replaceable></arg>      <arg choice='opt'>-S <replaceable>listener-port</replaceable></arg>      <arg choice='opt'>-s <replaceable>baudrate</replaceable></arg>      <arg choice='opt'>-d <replaceable>DGPS-server</replaceable></arg>      <arg choice='opt'>-i <replaceable>initial-position</replaceable></arg>      <arg choice='opt'>-n </arg>            <arg choice='opt'>-h </arg>      <arg choice='opt'>-D <replaceable>debuglevel</replaceable></arg></cmdsynopsis><cmdsynopsis>  <command>gps</command>        <arg choice='opt'><replaceable>X-options</replaceable></arg>      <arg choice='opt'>-h </arg>      <arg choice='opt'><replaceable>server</replaceable></arg></cmdsynopsis><cmdsynopsis>  <command>xgpsspeed</command>        <arg choice='opt'>-rv</arg>      <arg choice='opt'>-nc <replaceable>X-color</replaceable></arg>      <arg choice='opt'>-h </arg>      <arg choice='opt'><replaceable>server</replaceable></arg></cmdsynopsis></refsynopsisdiv><refsect1 id='description'><title>DESCRIPTION</title><refsect2 id='gpsd'><title>gpsd</title><para><application>gpsd</application> is a monitor daemon that watchesa TCP/IP port (2947 by default), waiting for an application to requestlocation information from a GPS.  The GPS is expected to bedirect-connected to the machine running<application>gpsd</application> via a USB or RS232C serial port whichis specified to gpsd at startup.</para><para>Optionally, <application>gpsd</application> may getdifferential-GPS corrections from a ground station running a RTCM-S104server; this will improve position-fix accuracy from roughly 10 metersto roughly 2 meters, provided you are within 1000 kilometers or so ofthe ground station.</para><para>The program accepts the following options:</para><variablelist remap='TP'><varlistentry><term>-p</term><listitem><para>Set GPS device name (default is <filename>/dev/gps</filename>).</para></listitem></varlistentry><varlistentry><term>-T <replaceable>device-type</replaceable></term><listitem><para>Set GPS type, usually not necessary because most GPSes now speakthe standard NMEA 0183 protocol. For a list of driver types,look at what <command>gpsd -?</command> writes to standard output.This option may be unavailable if the daemon was compiled withoutsupport for the non-NMEA drivers.</para></listitem></varlistentry><varlistentry><term>-S</term><listitem><para>Set TCP/IP port (default is 2947).</para></listitem></varlistentry><varlistentry><term>-s</term><listitem><para>Set GPS communication speed in bits per second (default is set by device type).</para></listitem></varlistentry><varlistentry><term>-d</term><listitem><para>Query a differential-GPS (DGPS) server.  If a suffix of theserver name begins with ":" it is interpreted as a port number,overriding the default IANA-assigned port of 2101.For DGPS servers available for use with this option, see<ulink url='http://www.wsrcc.com/wolfgang/gps/dgps-ip.html'>DGPS corrections over the Internet</ulink>.</para></listitem></varlistentry><varlistentry><term>-i</term><listitem><para>Set initial longitude/latitude in degrees (TripMate andEarthMate only; helps them develop a first fix more quickly).Required format is %f[NS]:%f[EW]; that is a decimal number of degreeslatitude, followed by the suffix N or S, followed by a colon, followedby a decimal number of degrees longitude, followed by the suffix E orW.  The numbers may have fractional parts to the right of a decimalpoint.  This option may be unavailable if the daemon was compiledwithout TripMate or EarthMate support.</para></listitem></varlistentry><varlistentry><term>-n</term><listitem><para>Don't wait for a client to connect before pollingthe GPS.  The wait is a feature; many serial GPSes go to a standbymode (not drawing power) before the host machine asserts DTR, sowaiting for the first actual request can save valuable battery poweron portable equipment.  This option combines well with -D2 to enablemonitoring of the GPS data stream.</para></listitem></varlistentry><varlistentry><term>-h</term><listitem><para>Display help message and terminate.</para></listitem></varlistentry><varlistentry><term>-D</term><listitem><para>Set debug level. At debug levels 2 and above,<application>gpsd</application> stays in foreground and reportsincoming sentence and actions to standard error.</para></listitem></varlistentry></variablelist><para><application>gpsd</application> should be able to query any GPSthat speaks either the standard textual NMEA 0183 protocol or thebinary Rockwell protocol used by EarthMate and some otherGPSes.</para><para>The request protocol for gpsd clients is very simple.  Eachrequest consists of a single ASCII character followed by a newline.Case of the request character is ignored,  Each request returns a lineof response text ended by a CR/LF.  Requests and responses are as follows, with %f standing for a decimal float numeral and %d fordecimal integer numeral:</para><variablelist><varlistentry><term>a</term><listitem><para>The current altitude as "A=%f", meters above mean sea level.</para></listitem></varlistentry><varlistentry><term>d</term><listitem><para>Returns the UTC time in the ISO 8601 format,"D=yyyy-mm-ddThh:nmm:ss.ssZ". Digits of precision in the fractional-secondspart will vary and may be zero.</para></listitem></varlistentry><varlistentry><term>l</term><listitem><para>Returns three fields: a protocol revision number,the gpsd version, and a list of accepted request letters.</para></listitem></varlistentry><varlistentry><term>m</term><listitem><para>The gps mode as "M=%d". 1=no fix, 2=2D (no altitude), 3=3D (with altitude).</para></listitem></varlistentry><varlistentry><term>p</term><listitem><para>Returns the current position in the form "P=%f %f";numbers are in degrees, latitude first.</para></listitem></varlistentry><varlistentry><term>q</term><listitem><para>Returns "Q=%d %f %f %f": a count of satellites used in the lastfix, and three estimated position errors in meters &mdash; position, horizontal, and vertical.</para></listitem></varlistentry><varlistentry><term>r</term><listitem><para>Sets or toggles 'raw' mode. Return "R=0" or "R=1". Inraw mode you read the NMEA data stream from the GPS. (Non-NMEA GPSesget their communication format translated to NMEA on the fly.)  Thecommand 'r' immediately followed by the digit '1' or the plus sign '+'sets raw mode.  The command 'r' followed by the digit '0' or the minussign '-' clears raw mode.  The command 'r' with neither suffix togglesraw mode.</para></listitem></varlistentry><varlistentry><term>s</term><listitem><para>The gps status as "S=%d". 0=no fix, 1=fix,2=DGPS-corrected fix.</para></listitem></varlistentry><varlistentry><term>t</term><listitem><para>Track made good; course "T=%f" in degrees from true north.</para></listitem></varlistentry><varlistentry><term>v</term><listitem><para>The current speed as "V=%f" in knots.</para></listitem></varlistentry><varlistentry><term>w</term><listitem><para>Sets or toggles 'watcher' mode (see the descroiptionbelow). Return "W=0" or "W=1".The command 'w' immediately followed bythe digit '1' or the plus sign '+' sets watcher mode.  The command 'w'followed by the digit '0' or the minus sign '-' clears watcher mode.The command 'w' with neither suffix toggles watchermode.</para></listitem></varlistentry><varlistentry><term>x</term><listitem><para>Returns "X=1" if the GPS is online, "X=0" ifnot.</para></listitem></varlistentry><varlistentry><term>y</term> <listitem><para>Returns Y= followed by a count not more than 12, followed bythat many quintuples of satellite PRNs, elevation/azimuth pairs(elevation an integer formatted as %d in range 0-90, azimuth aninteger formatted as %d in range 0-359), signal strengths indecibels, and 1 or 0 according as the satellite was or wasnot used in the last fix. Each number is followed by one space.</para></listitem></varlistentry></variablelist><para>Note that a response consisting of just ? following the =means that there is no valid data available.</para><para>Requests can be concatenated and sent as a string; gpsd will thenrespond with a comma-separated list of replies.</para><para>Every gpsd reply will start with the string "GPSD" followed bythe replies. Examples:</para><screen>      query:       "p\n"      reply:       "GPSD,P=36.000000 123.000000\r\n"      query:       "d\n"      reply:       "GPSD,D=2002-11-16T02:45:05.12Z\r\n"      query:       "va\n"      reply:       "GPSD,V=0.000000,A=37.900000\r\n"</screen><para>When clients are active but the GPS is not responding, gpsd will spin trying to open the GPS device once per second.  Thus, it can be leftrunning in background and survive having the GPS repeatedly unpluggedand plugged back in.</para><para>The recommended mode for clients is watcher mode.  In watchermode <application>gpsd</application> ships a line of data to theclient each time the the GPS sends a sentence, but rather than beingraw NMEA the line is a gpsd response as if the user had just sent someset of gpsd commands.  That set of commands is the minimum for whichthe incoming sentence is relevant &mdash; e.g., a GPRMC sentence shipsa "pvs" response because it contains position, velocity and GPS statusdata.  Additionally, watching clients get notifications in the formX=0 or X=1 when the online/offline status of the GPS changes.</para><para>Sending SIGHUP to a running <application>gpsd</application>forces it to close the GPS and all client connections.  It will thenattempt to reconnect to the GPS and resume listening for clientconnections.  This may be useful if your GPS enters a wedged orconfused state but can be soft-reset by pulling down DTR.</para></refsect2><refsect2><title>gps</title><para><application>gps</application> is a simple test client for<application>gpsd</application> with an X interface. It displayscurrent GPS animation and (for GPSes that support the feature) thelocations of accessible satellites.</para><para><application>gps</application> accepts an -h option as for<application>gpsd</application>. An optional argument may specify anserver to get data from; a colon-separated suffix is taken as a portnumber.  The misfeature of previous versions that allowed it todirect-connect to the serial device has been removed.</para></refsect2><refsect2><title>xgpsspeed</title><para><application>xgpsspeed</application> is a speedometer that usesposition information from the GPS. It accepts an -h option andoptional argument as for <application>gps</application>.Additionally, it accepts -rv (reverse video) and -nc (needle color)options. The misfeature of previous version that allowed it todirect-connect to the serial device has been removed.</para></refsect2></refsect1><refsect1 id='limitations'><title>LIMITATIONS</title> <para>There is a limitation in the accuracy of<application>gpsd</application>-using applications that stems from thefact that <application>gpsd</application> waits passively for updatesfrom the sensor rather than actively polling for them (which can't bedone in a device-independent way).  Most GPSes ship updates just onceper second.  At 50km/h (31mi/h) that's 13.8 meters change in positionbetween updates.  This is good enough if you're on foot or in a carbut not good enough for aviation applications.</para></refsect1><refsect1 id='standards'><title>APPLICABLE STANDARDS</title> <para>The official NMEA protocol standard is available on paper fromthe <ulink url='http://www.nmea.org/pub/0183/'>National MarineElectronics Association</ulink>. A description of the protocol is<ulink url='http://vancouver-webpages.com/peter/nmeafaq.txt'>availableon the Web</ulink>.  gpsd parses the following NMEA sentences: GPRMC,GPGLL, GPVTG, GPGGA, GPGSA, GPGSV.  Note that gpsd returns puredecimal degrees, not the hybrid degree/minute format described in theNMEA standard.</para><para>The Rockwell protocol is described as an addendum on <ulinkurl='http://www.gpsinformation.net/dale/nmea.htm'>this page aboutNMEA</ulink>.</para></refsect1><refsect1 id='see_also'><title>SEE ALSO</title><para><citerefentry><refentrytitle>libgps</refentrytitle><manvolnum>3</manvolnum></citerefentry><citerefentry><refentrytitle>libgpsd</refentrytitle><manvolnum>3</manvolnum></citerefentry><citerefentry><refentrytitle>gpsprobe</refentrytitle><manvolnum>1</manvolnum></citerefentry></para></refsect1><refsect1 id='maintainer'><title>AUTHORS</title> <para>Remco Treffcorn, Derrick Brashear, Russ Nelson, Eric S. Raymond.This manual page by Eric S. Raymond <email>esr@thyrsus.com</email>.There is a project page, with <application>gps</application>screenshots, <ulinkurl="http://www.berlios.de/gpsd/">here</ulink>.</para></refsect1></refentry>