<?xml version="1.0" encoding="ISO-8859-1"?><!DOCTYPE refentry PUBLIC    "-//OASIS//DTD DocBook XML V4.1.2//EN"   "docbook/docbookx.dtd" [<!ENTITY gpsdsock         "/var/run/gpsd.sock">]><refentry id='gpsd.8'><refmeta><refentrytitle>gpsd</refentrytitle><manvolnum>8</manvolnum><refmiscinfo class='date'>9 Aug 2004</refmiscinfo></refmeta><refnamediv id='name'><refname>gpsd</refname><refpurpose>interface daemon for GPS receivers</refpurpose></refnamediv><refsynopsisdiv id='synopsis'><cmdsynopsis>  <command>gpsd</command>        <arg choice='opt'>-f <replaceable>GPS-devicename</replaceable></arg>      <arg choice='opt'>-F <replaceable>control-socket</replaceable></arg>      <!-- arg choice='opt'>-R      <replaceable>rtcm-listener-port</replaceable></arg -->      <arg choice='opt'>-S <replaceable>listener-port</replaceable></arg>      <arg choice='opt'>-b </arg>      <arg choice='opt'>-n </arg>            <arg choice='opt'>-N </arg>            <arg choice='opt'>-h </arg>      <arg choice='opt'>-P <replaceable>pidfile</replaceable></arg>      <arg choice='opt'>-D <replaceable>debuglevel</replaceable></arg>      <arg choice='opt'>-V </arg>      <arg rep='repeat'>           <group><replaceable>source-name</replaceable></group>      </arg></cmdsynopsis></refsynopsisdiv><refsect1 id='description'><title>DESCRIPTION</title><para><application>gpsd</application> is a monitor daemon that watchesa TCP/IP port (2947 by default), waiting for applications to requestinformation from GPSes or differential-GPS radios attached to the host machine.Each GPS or radio is expected to be direct-connected to the host via a USB orRS232C serial port.  The port may be specified to<application>gpsd</application> at startup, or it may be set via acommand shipped down a local control socket (e.g. by a USB hotplugscript). Given a GPS device by either means,<application>gpsd</application> discovers the correct port speed andprotocol for it.</para><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 other GPSes, theTSIP binary protocol used by Trimble GPSes, or the binary SiRFprotocol used by SiRFstar chipsets, or the Garmin binary protocol usedby the USB version of the Garmin 18 and other Garmin USB GPSes, or thebinary protocol used by Evermore chipsets, or the extended NMEA usedby iTrax. <application>gpsd</application> effectively hides thedifferences among these. It also knows about and uses commands thattune the GPS for lower latency, decreased bandwidth usage, orincreased accuracy on the San Jose Navigation FV18, the Sony CXD2951,the uBlox, and the Motorola OnCore GT+.  It can read heading andattitude information from the True North Technologies Revolution 2XDigital compass.</para><para><application>gpsd</application> can use differential-GPScorrections from a DGPS radio or over the net, from a ground stationrunning a DGPSIP server or a Ntrip broadcaster that reports RTCM-S104data; this will improve user error by roughly a factor of four.  When<application>gpsd</application> opens a serial device emittingRTCM-104, it automatically recognizes this and uses the device as acorrection source for all connected GPSes.  <!-- If no server isspecified, <application>gpsd</application> will hunt for one.--> See<xref linkend='accuracy'/> and <xref linkend='files'/> fordiscussion.</para><!-- para><application>gpsd</application> may itself serve DGPSIP datafrom an attached RTCM-104 source to other instances of<application>gpsd</application> connecting on port 2101.</para --><para>The program accepts the following options:</para><variablelist remap='TP'><varlistentry><term>-f</term><listitem><para>Set a GPS device name.  This option is deprecated and may beremoved in a future version.  Each command-line argument will betreated as a device to be probed for the presence of a GPS; that,rather than the -f option, is the preferred way of specifying GPSdevices at startup.</para></listitem></varlistentry><varlistentry><term>-F</term><listitem><para>Create a control socket for device addition and removalcommands.  You must specify a valid pathname on your local filesystem; this will be created as a Unix-domain socket to which you can writecommands that edit the daemon's internal device list.</para></listitem></varlistentry><!-- varlistentry><term>-R</term><listitem><para>Set TCP/IP port on which to listen for DGPSIP clients(default is 2101). The option -R 0 will disable serving DGPSIPclients.</para></listitem></varlistentry --><varlistentry><term>-S</term><listitem><para>Set TCP/IP port on which to listen for GPSD clients (default is 2947).</para></listitem></varlistentry><varlistentry><term>-d</term><listitem><para>This is a deprecated option which takes a differential-GPS source as argument.  See the description of argument interpretationbelow.</para></listitem></varlistentry><varlistentry><term>-b</term><listitem><para>Broken-device-safety, otherwise known as read-only mode. Somepopular bluetooth and USB receivers lock up or become totally inaccessible whenprobed or reconfigured. 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 solutionwould be for bluetooth to not be so fragile. A platform independent methodto identify serial-over-bluetooth devices would also be nice.</para></listitem></varlistentry><varlistentry><term>-n</term><listitem><para>Don't wait for a client to connect before pollingwhatever GPS is associated with it.  The wait is a feature; manyserial GPSes go to a standby mode (not drawing power) before the hostmachine asserts DTR, so waiting for the first actual request can savevaluable battery power on portable equipment.  This option combineswell with -D2 to enable monitoring of the GPS data stream.</para></listitem></varlistentry><varlistentry><term>-N</term><listitem><para>Don't daemonize; run in foreground.  Also suppresses privilege-dropping.  This switch is mainly useful for debugging.Its meaning may change in future versions.</para></listitem></varlistentry><varlistentry><term>-h</term><listitem><para>Display help message and terminate.</para></listitem></varlistentry><varlistentry><term>-P</term><listitem><para>Specify the name and path to record the daemon's process ID.</para></listitem></varlistentry><varlistentry><term>-D</term><listitem><para>Set debug level. At debug levels 2 and above,<application>gpsd</application> reports incoming sentence and actionsto standard error if <application>gpsd</application> is in the foreground(-N) or to syslog if in the background.</para></listitem></varlistentry><varlistentry><term>-V</term><listitem><para>Dump version and exit.</para></listitem></varlistentry></variablelist><para>Arguments are interpreted as the names of data sources.  Normally, a data source is the name of a local serial device fromwhich the daemon may expect GPS data.</para><para>A data source name may also be a URL pointing to a specificdifferential-GPS service (DGPSIP server or Ntrip broadcaster).If theURL starts with "ntrip://" Ntrip will be used; if the URL starts with"dgpsip://", DGPSIP will be used.  <application>Gpsd</application>also defaults to DGPSIP if no protocol is defined.  For Ntrip servicesthat require authentication, a prefix of the form "username:password@"can be added before the name of the Ntrip broadcaster.  If a suffix ofthe service name begins with ":" it is interpreted as a port number,overriding the default IANA-assigned port of 2101.  For Ntrip serviceyou also need to specify which stream to use; the stream is given inthe form "/streamname". So, an example DGPSIP URL could be"dgpsip://dgpsip.example.com" and a Ntrip URL could be"ntrip://foo:bar@ntrip.example.com:80/example-stream". <!-- If thisoption is not given, <application>gpsd</application> will hunt for aDGPSIP server. --></para><para>Internally, the daemon maintains a device list holding thepathnames of GPSes known to the daemon. Initially, this list is thelist of device-name arguments specified on the command line.  Thatlist may be empty, in which case the daemon will have no devices onits search list until they are added by a control-socket command (see<xref linkend='devices'/> for details on this).  Daemon startup willabort with an error if neither any devices nor a control socket arespecified.</para><para>At any given time, each client will be listening to only one ofthe GPSes on the device list.  By default, a client's device is theone that most recently shipped information to the daemon at the timethe client first requests GPS information (that is, issues any commandother than F, K, W=0 or R=0).</para><para>The request protocol for <application>gpsd</application> clientsis very simple.  Each request normally consists of a single ASCIIcharacter followed by a newline.  Case of the request character isignored.  Each request returns a line of response text ended by aCR/LF.  Requests and responses are as follows, with %f standing for adecimal float numeral and %d for decimal 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>b</term><listitem><para>The B command with no argument returns four fieldsgiving the parameters of the serial link to the GPS as "B=%d %d %c%d"; baud rate, byte size, parity, (N, O or E for no parity, odd, oreven) and stop bits (1 or 2).  The command "B=%d" sets the baud rate,not changing parity or stop bits; watch the response, because it ispossible for this to fail if the GPS does not support aspeed-switching command.  In case of failure, the daemon and GPS willcontinue to communicate at the old speed.  The B= form is rejectedif more than one client is attached to the channel.</para></listitem></varlistentry><varlistentry><term>c</term><listitem><para>C with no following = asks the daemon to return the cycle timeof the attached GPS, if any.  If there is no attached device it willreturn "C=?".</para><para>If the driver has the capability to change sampling rate thecommand "C=%f" does so, setting a new cycle time in seconds. The "C="form is rejected if more than one client is attached to thechannel.</para><para>If the driver has the capability to change sampling rate, thiscommand always returns "C=%f %f" giving the current cycle time inseconds and the minimum possible cycle time at the current baud rate.If the driver does not have the capability to change sampling rate,this returns, as "C=%f", the cycle time in seconds only.</para><para>Either number may be fractional, indicating a GPS cycle shorterthan a second; however, if >1 the cycle time must be a whole number. Alsonote that relatively few GPSes have the ability to set sub-secondcycle times; consult your hardware protocol description to make surethis works.</para> <para>This command will return "C=?" at start of session, before thefirst full packet has been received from the GPS, because the GPS type isnot yet known. To set up conditions for a real answer, issue it aftersome command that reads position/velocity/time information from thedevice.</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 absent.</para></listitem></varlistentry><varlistentry><term>e</term><listitem><para>Returns "E=%f %f %f": three estimated position errors in meters&mdash; total, horizontal, and vertical (95% confidencelevel).  Note: many GPSes do not supply these numbers.  When theGPS does not supply them, <application>gpsd</application> computesthem from satellite DOP using fixed figures for expected non-DGPS and DGPS range errors in meters.  A value of '?' for any of thesenumbers should be taken to mean that component of DOP is not available.See also the 'q' command.</para></listitem></varlistentry><varlistentry><term>f</term><listitem><para>Gets or sets the active GPS device name. The barecommand 'f' requests a response containing 'F=' followed by the nameof the active GPS device.  The other form of the command is 'f=', inwhich case all following printable characters up to but not includingthe next CR/LF are interpreted as the name of a trial GPS device. Ifthe trial device is in <application>gpsd</application>'s device list,it is opened and read to see if a GPS can be found there.  If it can,the trial device becomes the active device for this client.</para><para>The 'f=' command may fail if the specified device name is not onthe daemon's device list.  This device list is initialized with thepaths given on the command line, if any were specified.  For securityreasons, ordinary clients cannot change this device list; instead,this must be done via the daemon's local control socket declared withthe -F option.</para><para>Once an 'f=' command succeeds, the client is tied to thespecified device until the client disconnects.</para><para>Whether the command is 'f' or 'f=' or not, and whether it succeedsor not, the response always lists the name of the client's device.</para><para>(At protocol level 1, the F command failed if more than oneclient was attached, and multiple devices were not supported.)</para></listitem></varlistentry><varlistentry><term>g</term><listitem><para>With =, accepts a single argument which may have either of thevalues 'gps' or 'rtcm104', with case ignored.  This specifies the type of information the client wants and forces a device assignment.  Without =, forces a device assignment but doesn't force the type.This command is optional; if it is not given, the client will bebound to whatever available device the daemon finds first.</para><para>This command returns either '?' if no device of the specifiedtype(s) could be assigned, otherwise a string ('GPS' or 'RTCM104')identifying the kind of information the attached device returns.</para></listitem></varlistentry><!--<varlistentry><term>h</term><listitem><para>Heading, "H=%f" in degrees from true north.  Only available fromTrue North Technologies or comparable digital compass devices (c.f. 't')</para>