Provided by: gpsd_2.39-5_i386 bug

NAME

       gpsd - interface daemon for GPS receivers

SYNOPSIS

       gpsd [-F control-socket] [-S listener-port] [-b] [-l] [-G] [-n] [-N]
            [-h] [-P pidfile] [-D debuglevel] [-V] [[source-name]...]

DESCRIPTION

       gpsd is a monitor daemon that watches a TCP/IP port (2947 by default),
       waiting for applications to request information 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 or RS232C
       serial port. The port 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 uBlox
       ANTARIS devices. It can read heading and attitude information from the
       Oceanserver 5000 digital compass.

       The GPS protocols 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.

       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
       the section called “ACCURACY” and the section called “FILES” for
       discussion.

       The program accepts the following options:

       -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.

       -S
           Set TCP/IP port on which to listen for GPSD clients (default is
           2947).

       -b
           Broken-device-safety, otherwise known as read-only mode. Some
           popular bluetooth and USB receivers lock up or become totally
           inaccessible when probed 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 solution would be for Bluetooth
           to not be so fragile. A platform independent method to identify
           serial-over-Bluetooth devices would also be nice.

       -G
           This flag causes gpsd to listen on all addresses (INADDR_ANY)
           rather than just the loopback (INADDR_LOOPBACK) address. For the
           sake of privacy and security, PVT information is now private to the
           local machine until the user makes an effort to expose this to the
           world. Listening on the loopback by default is a change from
           previous behaviour.

       -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. It is thought that some GPSes go to a standby
           mode (drawing less power) before the host machine asserts DTR, so
           waiting for the first actual request might save battery power on
           portable equipment. This option is deprecated as it was found to be
           confusing; gpsd will now always remain connected to the configured
           receivers.

       -N
           Don´t daemonize; run in foreground. Also suppresses
           privilege-dropping. This switch is mainly useful for debugging. Its
           meaning may change in future versions.

       -h
           Display help message and terminate.

       -P
           Specify the name and path to record the daemon´s process ID.

       -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.

       -V
           Dump version and exit.

       Arguments are interpreted as the names of data sources. Normally, a
       data source is the name of a local serial device from which the daemon
       may expect GPS data.

       A data source name may also be a URL pointing to a specific
       differential-GPS service (DGPSIP server or Ntrip broadcaster).If the
       URL starts with "ntrip://" Ntrip will be used; if the URL starts with
       "dgpsip://", DGPSIP will be used.  Gpsd also defaults to DGPSIP if no
       protocol is defined. For Ntrip services that require authentication, a
       prefix of the form "username:password@" can be added before the name of
       the Ntrip broadcaster. If a suffix of the service name begins with ":"
       it is interpreted as a port number, overriding the default
       IANA-assigned port of 2101. For Ntrip service you also need to specify
       which stream to use; the stream is given in the 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".

       Internally, the daemon maintains a device list holding the pathnames of
       GPSes 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 the section
       called “GPS DEVICE MANAGEMENT” for details on this). Daemon startup
       will abort with an error if neither any devices nor a control socket
       are specified.

       At any given time, each client will be listening to only one of the
       GPSes on the device list. By default, a client´s device is the one that
       most recently shipped information to the daemon at the time the client
       first requests GPS information.

           Warning
           It is planned that the command protocol described below will change
           radically at API version 4. It is a bad idea for applications to
           speak this protocol directly: rather, they should use the libgps
           client library and take appropriate care to conditionalize their
           code on the major and minor API version symbols. See the GPSD
           project website for more information on the protocol and API
           change.

       The request protocol for gpsd clients is very simple. Each request
       normally consists of a single ASCII character followed by a newline.
       Case of the request character is ignored. Each request returns a line
       of response text ended by a CR/LF. Requests and responses are as
       follows, with %f standing for a decimal float numeral and %d for
       decimal integer numeral:

       Any command other than L, F, K, W=0 or R=0 is considered a request for
       GPS information and will cause a GPS device to be connected to the
       client´s channel.

       a
           The current altitude as "A=%f", meters above mean sea level.

       b
           The B command with no argument returns four fields giving 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, or even)
           and stop bits (1 or 2).

           The command "B=%d" sets the baud rate, not changing parity or stop
           bits; The command "B=%d [78] [NOE] [12]" (B followed by whiteapace;
           followed by a numeric speed; followed by one of the digits 7 or 8;
           followed by whitespace; followed by one of the letters ´N´, ´O´, or
           ´E´; followed by whitespace; followed by one of the digits ´1´ or
           2´) sets not only speed but word length, parity, and stop bits.

           For both forms, watch the response, because it is possible for this
           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. Both forms are rejected if more than one client is attached
           to the channel.

           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 serrial adaptor
           chip with the UART on the GPS chipset whjen 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.

           (Older versions of gpsd supported changing speed only.)

       c
           C with no following = asks the daemon to return the cycle time of
           the attached GPS, if any. If there is no attached device it will
           return "C=?".

           If the driver has the capability to change sampling rate the
           command "C=%f" does so, setting a new cycle time in seconds. The
           "C=" form is rejected if more than one client is attached to the
           channel.

           If the driver has the capability to change sampling rate, this
           command always returns "C=%f %f" giving the current cycle time in
           seconds and the minimum possible cycle time. If the driver does not
           have the capability to change sampling rate, this returns, as
           "C=%f", the cycle time in seconds only.

           Either number may be fractional, indicating a GPS cycle shorter
           than a second; however, if >1 the cycle time must be a whole
           number. Also note that relatively few GPSes have the ability to set
           sub-second cycle times; consult your hardware protocol description
           to make sure this works.

           This command will return "C=?" at start of session, before the
           first full packet has been received from the GPS, because the GPS
           type is not yet known. To set up conditions for a real answer,
           issue it after some command that reads position/velocity/time
           information from the device.

       d
           Returns the UTC time in the ISO 8601 format,
           "D=yyyy-mm-ddThh:nmm:ss.ssZ". Digits of precision in the
           fractional-seconds part will vary and may be absent.

       e
           Returns "E=? %f %f": estimated position errors in meters —
           horizontal, and vertical (95% confidence level). Note: many GPSes
           do not supply these numbers. When the GPS does not supply them,
           gpsd computes them from satellite DOP using fixed figures for
           expected non-DGPS and DGPS range errors in meters. A value of ´?´
           for either of these numbers should be taken to mean that component
           of DOP is not available. The ? value is a backwards-compatibility
           placeholder; some early versions of GPSD returned a total error
           estimate there. See also the ´q´ command.

       f
           Gets or sets the active GPS device name. The bare command ´f´
           requests a response containing ´F=´ followed by the name of the
           active GPS device. The other form of the command is ´f=´, in which
           case all following printable characters up to but not including the
           next CR/LF are interpreted as the name of a trial GPS device. If
           the trial device is in gpsd´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.

           The ´f=´ command may fail if the specified device name is not on
           the daemon´s device list. This device list is initialized with the
           paths given on the command line, if any were specified. For
           security reasons, ordinary clients cannot change this device list;
           instead, this must be done via the daemon´s local control socket
           declared with the -F option.

           Once an ´f=´ command succeeds, the client is tied to the specified
           device until the client disconnects.

           Whether the command is ´f´ or ´f=´ or not, and whether it succeeds
           or not, the response always lists the name of the client´s device.

           (At protocol level 1, the F command failed if more than one client
           was attached, and multiple devices were not supported.)

       g
           With =, accepts a single argument which may have either of the
           values ´gps´ or ´rtcm104v2´, 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 be bound to whatever available device the daemon finds first.

           This command returns either ´?´ if no device of the specified
           type(s) could be assigned, otherwise a string (´GPS´ or
           ´RTCM104v2´) identifying the kind of information the attached
           device returns.

           (Earlier versions accepted ´RTCM104´ and returned ´RTCM104´ rather
           than ´RTCM104v2´)

       i
           Returns a text string identifying the GPS. The string may contain
           spaces and is terminated by CR-LF. This command will return ´?´ at
           start of session, before the first full packet has been received
           from the GPS, because its type is not yet known.

       j
           Get or set buffering policy; this only matters for NMEA devices
           which report fix data in several separate sentences during the poll
           cycle (and in particular it doesnt matter for SiRF chips). The
           default (j=0) is to clear all fix data at the start of each poll
           cycle, so until the sentence that reports a given piece of data
           arrives queries will report ?. Setting j=1 will disable this,
           retaining data from the previous cycle. This is a per-user-channel
           bit, not a per-device one. The j=0 setting is hyper-correct and
           never displays stale data, but may produce a jittery display; the
           j=1 setting allows stale data but smooths the display.

           (At protocol level below 3, there was no J command. Note, this
           command is experimental and its semantics are subject to change.)

       k
           Returns a line consisting of "K=" followed by an integer count of
           of all GPS devices known to gpsd, followed by a space, followed by
           a space-separated list of the device names. This command lists
           devices the daemon has been pointed at by the command-line
           argument(s) or an add command via its control socket, and has
           successfully recognized as GPSes. Because GPSes might be unplugged
           at any time, the presence of a name in this list does not guarantee
           that the device is available.

           (At protocol level 1, there was no K command.)

       l
           Returns four fields: the major protocol/API revision number, the
           minor revision number, the gpsd version, and a list of accepted
           request letters. Note: earlier versions of this command returned
           only three fields, omitting the minor revision number.

       m
           The NMEA mode as "M=%d". 0=no mode value yet seen, 1=no fix, 2=2D
           (no altitude), 3=3D (with altitude).

       n
           Get or set the GPS driver mode. Without argument, reports the mode
           as "N=%d"; N=0 means NMEA mode and N=1 means alternate mode (binary
           if it has one, for SiRF and Evermore chipsets in particular). With
           argument, set the mode if possible; the new mode will be reported
           in the response. The "N=" form is rejected if more than one client
           is attached to the channel.

       o
           Attempts to return a complete time/position/velocity report as a
           unit. Any field for which data is not available being reported as
           ?. If there is no fix, the response is simply "O=?", otherwise a
           tag and timestamp are always reported. Fields are as follows, in
           order:

           tag
               A tag identifying the last sentence received. For NMEA devices
               this is just the NMEA sentence name; the talker-ID portion may
               be useful for distinguishing among results produced by
               different NMEA talkers in the same wire.

           timestamp
               Seconds since the Unix epoch, UTC. May have a fractional part
               of up to .01sec precision.

           time error
               Estimated timestamp error (%f, seconds, 95% confidence).

           latitude
               Latitude as in the P report (%f, degrees).

           longitude
               Longitude as in the P report (%f, degrees).

           altitude
               Altitude as in the A report (%f, meters). If the mode field is
               not 3 this is an estimate and should be treated as unreliable.

           horizontal error estimate
               Horizontal error estimate as in the E report (%f, meters).

           vertical error estimate
               Vertical error estimate as in the E report (%f, meters).

           course over ground
               Track as in the T report (%f, degrees).

           speed over ground
               Speed (%f, meters/sec). Note: older versions of the O command
               reported this field in knots.

           climb/sink
               Vertical velocity as in the U report (%f, meters/sec).

           estimated error in course over ground
               Error estimate for course (%f, degrees, 95% confidence).

           estimated error in speed over ground
               Error estimate for speed (%f, meters/sec, 95% confidence).
               Note: older experimental versions of the O command reported
               this field in knots.

           estimated error in climb/sink
               Estimated error for climb/sink (%f, meters/sec, 95%
               confidence).

           mode
               The NMEA mode (%d, ?=no mode value yet seen, 1=no fix, 2=2D,
               3=3D). (This field was not reported at protocol levels 2 and
               lower.)

       p
           Returns the current position in the form "P=%f %f"; numbers are in
           degrees, latitude first.

       q
           Returns "Q=%d %f %f %f %f %f": a count of satellites used in the
           last fix, and five dimensionless dilution-of-precision (DOP)
           numbers — spherical, horizontal, vertical, time, and total
           geometric. These are computed from the satellite geometry; they are
           factors by which to multiply the estimated UERE (user error in
           meters at specified confidence level due to ionospheric delay,
           multipath reception, etc.) to get actual circular error ranges in
           meters (or seconds) at the same confidence level. See also the ´e´
           command. Note: Some GPSes may fail to report these, or report only
           one of them (often HDOP); a value of 0.0 should be taken as an
           indication that the data is not available.

           Note: Older versions of gpsd reported only the first three DOP
           numbers, omitting time DOP and total DOP.

       r
           Sets or toggles ´raw´ mode. Return "R=0" or "R=1" or "R=2". In raw
           mode you read the NMEA data stream from each GPS. (Non-NMEA GPSes
           get their communication format translated to NMEA on the fly.) If
           the device is a source of RTCM-104 corrections, the corrections are
           dumped in the textual format described in rtcm104(5).

           The command ´r´ immediately followed by the digit ´1´ or the plus
           sign ´+´ sets raw mode. The command ´r´ immediately followed by the
           digit ´2´ sets super-raw mode; for non-NMEA (binary) GPSes or
           RTCM-104 sources this dumps the raw binary packet. The command ´r´
           followed by the digit ´0´ or the minus sign ´-´ clears raw mode.
           The command ´r´ with neither suffix toggles raw mode.

           Note: older versions of gpsd did not support super-raw mode.

       s
           The NMEA status as "S=%d". 0=no fix, 1=fix, 2=DGPS-corrected fix.

       t
           Track made good; course "T=%f" in degrees from true north.

       u
           Current rate of climb as "U=%f" in meters per second. Some GPSes
           (not SiRF-based) do not report this, in that case gpsd computes it
           using the altitude from the last fix (if available).

       v
           The current speed over ground as "V=%f" in knots.

       w
           Sets or toggles ´watcher´ mode (see the description below). Return
           "W=0" or "W=1".The command ´w´ immediately followed by the 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 watcher mode.

       x
           Returns "X=0" if the GPS is offline, "X=%f" if online; in the
           latter case, %f is a timestamp from when the last sentence was
           received.

           (At protocol level 1, the nonzero response was always 1.)

       y
           Returns Y=, followed by a sentence tag, followed by a timestamp
           (seconds since the Unix epoch, UTC) and a count not more than 12,
           followed by that many quintuples of satellite PRNs,
           elevation/azimuth pairs (elevation an integer formatted as %d in
           range 0-90, azimuth an integer formatted as %d in range 0-359),
           signal strengths in decibels, and 1 or 0 according as the satellite
           was or was not used in the last fix. Each number is followed by one
           space.

           (At protocol level 1, this response had no tag or timestamp.)

       z
           The Z command returns daemon profiling information of interest to
           gpsd developers. The format of this string is subject to change
           without notice.

       $
           The $ command returns daemon profiling information of interest to
           gpsd developers. The format of this string is subject to change
           without notice.

       Note that a response consisting of just ? following the = means that
       there is no valid data available. This may mean either that the device
       being queried is offline, or (for position/velocity/time queries) that
       it is online but has no fix.

       Requests can be concatenated and sent as a string; gpsd will then
       respond with a comma-separated list of replies.

       Every gpsd reply will start with the string "GPSD" followed by the
       replies. Examples:

                 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"

       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 left
       running in background and survive having a GPS repeatedly unplugged and
       plugged back in. When it is properly installed along with hotplug
       notifier scripts feeding it device-add commands, gpsd should require no
       configuration or user action to find devices.

       The recommended mode for clients is watcher mode. In watcher mode gpsd
       ships a line of data to the client each time the GPS gets either a fix
       update or a satellite picture, but rather than being raw NMEA the line
       is a gpsd ´o´ or ´y´ response. Additionally, watching clients get
       notifications in the form X=0 or X=%f when the online/offline status of
       the GPS changes, and an I response giving the device type when the user
       is assigned a device.

       Clients should be prepared for the possibility that additional fields
       (such as heading or roll/pitch/yaw) may be added to the O command, and
       not treat the occurrence of extra fields as an error. The protocol
       number will be incremented if and when such fields are added.

       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.

GPS DEVICE MANAGEMENT

       gpsd maintains an internal list of GPS devices. 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.

       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 reponse 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
       list. 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 to atmospheric signal lag than latitude/longitude, 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
       eceiving 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,
       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 0.000,000,340 = 3.4×10-7 seconds. A more important limit is
       the GPS tick rate. While the one-per-second PPS pulses emitted by
       serial GPS units are timed to the GPS system´s intrinsic accuracy
       limit,the satellites only emit navigation messages at 0.01-second
       intervals, and the timestamps in them only carry 0.01-second precision.
       Thus, the timestamps that gpsd reports in time/position/velocity
       messages are normally accurate only to 1/100th of a second.

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.
       This facility is only available when the daemon is started from root.
       If you´re going to use gpsd you probably want to run it -n mode so the
       clock will be updated even when no clients are active.

       Note that deriving time from messages received from the GPS is not as
       accurate as you might expect. Messages are often delayed in the
       receiver and on the link by several hundred milliseconds, and this
       delay is not constant. 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.

       When gpsd receives a sentence with a timestamp, it packages the
       received timestamp with current local time and sends it to a
       shared-memory segment with an ID known to ntpd, the network time
       synchronization daemon. If ntpd has been properly configured to receive
       this message, it will be used to correct the system clock.

       Here is a sample ntp.conf configuration stanza telling ntpd how to read
       the GPS notfications:

           server 127.127.28.0 minpoll 4 maxpoll 4
           fudge 127.127.28.0 time1 0.420 refid GPS

           server 127.127.28.1 minpoll 4 maxpoll 4 prefer
           fudge 127.127.28.1 refid GPS1

       The magic pseudo-IP address 127.127.28.0 identifies unit 0 of the ntpd
       shared-memory driver; 127.127.28.1 identifies unit 1. Unit 0 is used
       for message-decoded time and unit 1 for the (more accurate, when
       available) time derived from the PPS synchronization pulse. Splitting
       these notifications allows ntpd to use its normal heuristics to weight
       them.

       With this configuration, ntpd will read the timestamp posted by gpsd
       every 16 seconds and send it to unit 0. The number after the parameter
       time1 is an offset in seconds. You can use it to adjust out some of the
       fixed delays in the system. 0.035 is a good starting value for the
       Garmin GPS-18/USB, 0.420 for the Garmin GPS-18/LVC.

       After restarting ntpd, a line similar to the one below should appear in
       the output of the command "ntpq -p" (after allowing a couple of
       minutes):

           remote       refid      st t when poll reach  delay    offset  jitter
           =========================================================================
           +SHM(0)     .GPS.      0 l   13   16  377    0.000    0.885   0.882

       If you are running PPS then it will look like this:

           remote       refid      st t when poll reach  delay    offset  jitter
           =========================================================================
           -SHM(0)     .GPS.      0 l   13   16  377    0.000    0.885   0.882
           *SHM(1)     .GPS1.     0 l   11   16  377    0.000   -0.059   0.006

       When the value under "reach" remains zero, check that gpsd is running;
       and some application is connected to it or the ´-n´ option was used.
       Make sure the receiver is locked on to at least one satellite, and the
       receiver is in SiRF binary, Garmin binary or NMEA/PPS mode. Plain NMEA
       will also drive ntpd, but the accuracy as bad as one second. When the
       SHM(0) line does not appear at all, check the system logs for error
       messages from ntpd.

       When no other reference clocks appear in the NTP configuration, the
       system clock will lock onto the GPS clock. When you have previously
       used ntpd, and other reference clocks appear in your configuration,
       there may be a fixed offset between the GPS clock and other clocks. The
       gpsd developers would like to receive information about the offsets
       observed by users for each type of receiver. Please send us the output
       of the "ntpq -p" command and the make and type of receiver.

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 userid as set by configure) 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), an ´O´ 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.

       If your GPS uses a SiRF chipset at firmware level 231, and it is after
       31 May 2007, reported UTC time may be off by the difference between 13
       seconds and whatever leap-second correction is currently applicable,
       from startup until complete subframe information is received (normally
       about six seconds). 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.

       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.

       If you are using an NMEA-only GPS (that is, not using SiRF or Garmin or
       Zodiac binary mode) and the GPS does not emit GPZDA at the start of its
       update cycle (which most consumer-grade NMEA GPSes do not) and it is
       after 2099, then the century part of the dates gpsd delivers will be
       wrong.

FILES

       /dev/ttyS0
           Prototype TTY device. After startup, gpsd sets its group ID to the
           owner of this device if no GPS device was specified on the command
           line does not exist.

APPLICABLE STANDARDS

       The official NMEA protocol standard is available on paper from the
       National Marine Electronics Association[1], but is proprietary and
       expensive; the maintainers of gpsd have made a point of not looking at
       it. The GPSD website[2] 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. It recognizes these with either the normal GP talker-ID prefix, or
       with the II prefix emitted by Seahawk Autohelm marine navigation
       systems, or with the IN prefix emitted by some Garmin units. It
       recognizes one vendor extension, the PGRME emitted by some Garmin GPS
       models.

       Note that gpsd returns pure decimal degrees, not the hybrid
       degree/minute format described in the NMEA standard.

       Differential-GPS corrections are conveyed by the RTCM-104 proocol. The
       applicable standard for RTCM-104 V2 is RTCM Recommended Standards for
       Differential NAVSTAR GPS Service RTCM Paper 194-93/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.

SEE ALSO

       cgps(1), libgps(3), libgpsd(3), gpsprof(1), gpsfake(1), gpsctl(1),
       gpscat(1), rtcm-104(5).

AUTHORS

       Remco Treffcorn, Derrick Brashear, Russ Nelson, Eric S. Raymond, Chris
       Kuethe. This manual page by Eric S. Raymond esr@thyrsus.com. There is a
       project site at here[2].

NOTES

        1. National Marine Electronics Association
           http://www.nmea.org/pub/0183/

        2. GPSD website
           http://gpsd.berlios.de/

[FIXME: source]                   08/15/2009                           GPSD(8)