]> gpsd 8 9 Aug 2004 gpsd interface daemon for GPS receivers gpsd -F control-socket -S listener-port -b -l -G -n -N -h -P pidfile -D debuglevel -V source-name 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 -b (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 perfornance 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. gpsd is a monitor daemon that watches a TCP/IP port (2947 by default), waiting for applications to request 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 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 and 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 mode, 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. -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 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. AIS feed A URI with the prefix "ais://", followed by a hostname, a colon, and a port number. The daemon will open a socket to the indicated server and read AIVDM/AIVDO packets from it. Example: ais://data.aishub.net:4006. Ntrip caster A URI with the prefix "ntrip://" followed by the name of an Ntrp caster. 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. Internally, the daemon maintains a device list 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. Clients communicate with the dameon via textual request and responses. Currently there are two supported protocols, but there may be only one in the future. It is a bad idea for applications to speak either 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. Do not rely on being able to use this protocol directly! This protocol has run out of command namespace and is not flexible enough to handle report types other than for GPS devices. Thus, it is in the process of being replaced by a new, JSON-based protocol documented in a later section; development on the old protocol has ceased and support for it may be removed at any time after the new one is deemed mature. Under the old protocol, each client will at any given time be listening to only one of the GPSes on the internal device list (this restriction is removed under the new JSON-based protocol). 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. 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 whitespace; 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 any of the values 'gps', 'ais', 'rtcm104v2', or 'rtcm104v3' , 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 R, W and B commands will bind the client to whatever available device the daemon finds first. All other commands require a GPS and will attempt to bind the client to one. This command returns either '?' if no device of the specified type(s) could be assigned, otherwise a string ('GPS', 'AIS' 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. 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 revision number, the minor protocol 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 protocol 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.) 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 device was activated or 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, 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. The count field was formerly limited 12 - this is no longer the case, since receivers with more than 12 channels are common and there are enough satellites in orbit to have more than 12 usable. (At protocol level 1, this response had no tag or timestamp.) The "J" command present in earlier version of the protocol is now ignored and a no-op. Internal changes in the daemon (which can now detect the end of a fix-reporting cycle reliably) have made it unnecessary). The "Z" command and "$" response, previously documented only with a warning that they were subject to change without notice, have been removed. 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" 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. If the device is a source of RTCM-104 corrections, the corrections are dumped in the Sager dump format described in rtcm1045. 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. The new GPSD protocol is built on top of JSON, JaveScript Object Notation. Use of this metaprotocol to pass structured data between daemon and client avoids the non-extensibility problems of the old protocol, and permits a richer set of record types to be passed up to clients. 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 or one of the strings "DEVICE" or "ERROR". Their length limit is 1024 characters, including trailing newline. Here are the most important responses: TPV A TPV object is a time-position-velocity report. The "class" and "mode" fields will reliably be present. Others may be reported or not depending on the fix quality. Name Always? Type Description class Yes string Fixed: "TPV" tag No string Type tag associated with this GPS sentence; from an NMEA device this is just the NMEA sentence type.. device No string Name of originating device time No numeric Seconds since the Unix epoch, UTC. May have a fractional part of up to .01sec precision. ept No numeric Estimated timestamp error (%f, seconds, 95% confidence). lat No numeric Latitude in degrees: +/- signifies West/East lon No numeric Longitude in degrees: +/- signifies North/South. alt No numeric Altitude in meters. epx No numeric Longitude error estimate in meters, 95% confidence. epy No numeric Latitude error estimate in meters, 95% confidence. epv No numeric Estimated vertical error in meters, 95% confidence. track No numeric Course over ground, degrees from true north. 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 estinmate in degrees, 95% confifdence. eps No numeric Speed error estinmate in meters/sec, 95% confifdence. epc No numeric Climb/sink error estinmate in meters/sec, 95% confifdence. mode Yes numeric NMEA mode: %d, 0=no mode value yet seen, 1=no fix, 2=2D, 3=3D. 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 actrually received; see gps.h for bitmask names and values. Here's an example: {"class":"TPV","tag":"MID2","device":"/dev/pts/1", "time":1118327688.280,"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. Name Always? Type Description class Yes string Fixed: "SKY" tag No string Type tag associated with this GPS sentence; from an NMEA device this is just the NMEA sentence type.. device No string Name of originating device time No numeric Seconds since the Unix epoch, UTC. May have a fractional part of up to .01sec precision. xdop No numeric Longitudinal dilution of precision, a dimensionsless factor which should be multiplied by a base UERE to get an error estimate. ydop No numeric Latitudinal dilution of precision, a dimensionsless factor which should be multiplied by a base UERE to get an error estimate. vdop No numeric Altitude dilution of precision, a dimensionsless factor which should be multiplied by a base UERE to get an error estimate. tdop No numeric Time dilution of precision, a dimensionsless factor which should be multiplied by a base UERE to get an error estimate. hdop No numeric Horizontal dilution of precision, a dimensionsless factor which should be multiplied by a base UERE to get a circular error estimate. pdop No numeric Spherical dilution of precision, a dimensionsless factor which should be multiplied by a base UERE to get an error estimate. gdop No numeric Hyperspherical dilution of precision, a dimensionsless factor which should be multiplied by a base UERE to get an error estimate. xdop No numeric Longitudinal dilution of precision, a dimensionsless 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 nit include them in their reports. Many that do report DOPs report only HDOP, two-dimensial 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 correspoding DOP is unavailable; some devices use more sophisticated error modeling than the covariance calculation. The satellite list objects have the following elements: Name Always? Type Description PRN Yes numeric PRN ID of the satellite 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? 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","tag":"MID2","device":"/dev/pts/1","time":1118327688.280 "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}]} And here are the commands: ?VERSION; Returns an object with the following attributes: 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.. 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":$Id$,"proto_major":3,"proto_minor":1} ?DEVICES; Returns a device list object with the following elements: Name Always? Type Description class Yes string Fixed: "DEVICES" devices Yes list List of device descriptions 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 in the section covering notifications. ?WATCH This command sets watcher mode. It also sets or elicits a report of per-subscriber buffering policy and the raw bit. An argument WATCH object changes the subscriber's policy. The respunce describes the subscriber's policy. The response will also include a DEVICES object. A WATCH object has the following elements: Name Always? Type Description class Yes string Fixed: "WATCH" enable No boolean Eanable (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. scaled No boolean If true, apply scaling divisors to output before dumping; default is false. Applies only to AIS reports. 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. There is an additional boolean "timing" attribute which is undodumented because that portion of the interface is considered unstable and for developer use only. In watcher mode, GPS reports are dumpred as TPV and SKY responses. AIS 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} ?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 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. A DEVICE object has the following elements: 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 At device activation and device close time. numeric Time the device was activated, or 0 if it is being closed. 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 Yes 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 ?CONFIGDEV when (and only when) the rate is switchable. It is read-only and not settable. The serial parameters will be omitted in a responce describing a TCP/IP source such as an Ntrip, DGPSIP, or AIS feed. The contents of the flags field should be interpreted as follows: 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 GPS 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", "speed":4800,"serialmode":"8N1","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: 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. 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. Other fields are as named ands specified in the AIVDM/AIVDO Protocol Decoding document. RTCM2 corrections are dumped in the JSON format described in rtcm1045. 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. 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. 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. 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 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, 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. 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. 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. 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). 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, 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. 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. /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. The official NMEA protocol standard is available on paper from the National Marine Electronics Association, but is proprietary and expensive; the maintainers of gpsd have made a point of not looking at it. The GPSD 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. 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. 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. gps1, libgps3, libgpsd3, gpsprof1, gpsfake1, gpsctl1, gpscat1, rtcm-1045. 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.