diff options
| author | Eric S. Raymond <esr@thyrsus.com> | 2006-06-07 11:40:37 +0000 |
|---|---|---|
| committer | Eric S. Raymond <esr@thyrsus.com> | 2006-06-07 11:40:37 +0000 |
| commit | 17b4d514a3811a4ccdfbf2d379547dcb943b092f (patch) | |
| tree | c32f25088ebf2ccbd5126c7e19b75d13a396c5a8 | |
| parent | 7472a7b846320ee0697e8cc3dab40d53a84effe8 (diff) | |
| download | gpsd-17b4d514a3811a4ccdfbf2d379547dcb943b092f.tar.gz | |
splint cleanup
| -rw-r--r-- | AUTHORS | 1 | ||||
| -rw-r--r-- | Makefile.am | 6 | ||||
| -rw-r--r-- | README | 2 | ||||
| -rw-r--r-- | dgpsip.c | 19 | ||||
| -rw-r--r-- | gpsd.8 | 585 | ||||
| -rw-r--r-- | gpsd.c | 42 | ||||
| -rw-r--r-- | gpsd.h | 17 | ||||
| -rw-r--r-- | gpsd.spec.in | 5 | ||||
| -rw-r--r-- | gpsd.xml | 40 | ||||
| -rw-r--r-- | libgpsd_core.c | 27 | ||||
| -rw-r--r-- | ntrip.c | 473 | ||||
| -rw-r--r-- | rtcmdecode.1 | 104 | ||||
| -rw-r--r-- | rtcmdecode.xml | 2 | ||||
| -rw-r--r-- | www/references.html | 12 |
14 files changed, 922 insertions, 413 deletions
@@ -6,3 +6,4 @@ Gary E. Miller <gem@rellim.com> Jeff Francis <jeff@gritch.org> Amaury Jacquot <sxpert@esitcom.org> Chris Kuethe <chris.kuethe@gmail.com> +Ville Nuorvala <vnuorval@tcs.hut.fi> diff --git a/Makefile.am b/Makefile.am index 44db677c..649fd1c1 100644 --- a/Makefile.am +++ b/Makefile.am @@ -114,7 +114,9 @@ libgps_c_sources = \ packet.c \ gpsutils.c \ geoid.c \ + dgnss.c \ dgpsip.c \ + ntrip.c \ sirf.c \ report.c \ isgps.c \ @@ -122,7 +124,9 @@ libgps_c_sources = \ srecord.c \ bits.h \ truenorth.c \ - timebase.h + timebase.h \ + bsd-base64.c \ + bsd-base64.h BUILT_SOURCES = packet_names.h packet_names.h: packet_states.h @@ -93,6 +93,8 @@ Gary Miller <gem@rellim.com> wrote the driver for Garmin binary protocol. Amaury Jacquot <sxpert@esitcom.org> added DBUS support. +Ville Nuorvala <vnuorval@tcs.hut.fi> wrote the NTRIP support. + We are delighted to acknowlege the assistance of Carl Carter, a field application engineer at SiRF. He assisted us with the correction and tuning of the SiRF binary-protocol driver, shedding a good deal of @@ -33,6 +33,7 @@ int dgpsip_open(struct gps_context_t *context, const char *dgpsserver) /* greeting required by some RTCM104 servers; others will ignore it */ (void)snprintf(buf,sizeof(buf), "HELO %s gpsd %s\r\nR\r\n",hn,VERSION); (void)write(context->dsock, buf, strlen(buf)); + context->dgnss_service = dgnss_dgpsip; } else gpsd_report(1, "can't connect to DGPS server %s, netlib error %d.\n", dgpsserver, context->dsock); opts = fcntl(context->dsock, F_GETFL); @@ -55,24 +56,6 @@ void dgpsip_poll(struct gps_context_t *context) } } -void dgpsip_relay(struct gps_device_t *session) -/* pass a DGPSIP connection report to a session */ -{ - if (session->gpsdata.gps_fd !=-1 - && session->context->rtcmbytes > -1 - && session->rtcmtime < session->context->rtcmtime - && session->device_type->rtcm_writer != NULL) { - if (session->device_type->rtcm_writer(session, - session->context->rtcmbuf, - (size_t)session->context->rtcmbytes) == 0) - gpsd_report(1, "Write to rtcm sink failed\n"); - else { - session->rtcmtime = timestamp(); - gpsd_report(2, "<= DGPS: %d bytes of RTCM relayed.\n", session->context->rtcmbytes); - } - } -} - void dgpsip_report(struct gps_device_t *session) /* may be time to ship a usage report to the DGPSIP server */ { @@ -1,456 +1,469 @@ -.\"Generated by db2man.xsl. Don't modify this, modify the source. -.de Sh \" Subsection -.br -.if t .Sp -.ne 5 -.PP -\fB\\$1\fR -.PP -.. -.de Sp \" Vertical space (when we can't use .PP) -.if t .sp .5v -.if n .sp -.. -.de Ip \" List item -.br -.ie \\n(.$>=3 .ne \\$3 -.el .ne 3 -.IP "\\$1" \\$2 -.. -.TH "GPSD" 8 "" "" "" -.SH NAME +.\" ** You probably do not want to edit this file directly ** +.\" It was generated using the DocBook XSL Stylesheets (version 1.69.1). +.\" Instead of manually editing it, you probably should edit the DocBook XML +.\" source for it and then use the DocBook XSL Stylesheets to regenerate it. +.TH "GPSD" "8" "06/06/2006" "9 Aug 2004" "9 Aug 2004" +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.SH "NAME" gpsd \- interface daemon for GPS receivers .SH "SYNOPSIS" -.ad l -.hy 0 .HP 5 -\fBgpsd\fR [\-f\ \fIGPS\-devicename\fR] [\-F\ \fIcontrol\-socket\fR] [\-S\ \fIlistener\-port\fR] [\-d\ \fIDGPSIP\-server\fR] [\-n] [\-N] [\-h] [\-P\ \fIpidfile\fR] [\-D\ \fIdebuglevel\fR] [\-V] [[\fIGPS\-devicename\fR]...] -.ad -.hy - +\fBgpsd\fR [\-f\ \fIGPS\-devicename\fR] [\-F\ \fIcontrol\-socket\fR] [\-S\ \fIlistener\-port\fR] [\-d\ \fIDGPS\-service\ URL\fR] [\-n] [\-N] [\-h] [\-P\ \fIpidfile\fR] [\-D\ \fIdebuglevel\fR] [\-V] [[\fIGPS\-devicename\fR]...] .SH "DESCRIPTION" - -.PP -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\&. - .PP -gpsd should be able to query any GPS that speaks either the standard textual NMEA 0183 protocol, or the binary Rockwell protocol used by EarthMate and some other GPSes, the TSIP binary protocol used by Trimble GPSes, or the binary SiRF protocol used by SiRf\-II and SiRF\-Star chipsets, or the Garmin binary protocol used by the USB version of the Garmin 18 and other Garmin USB GPSes, or the binary protocol used by Evermore chipsets, or the extended NMEA used by iTrax\&. gpsd effectively hides the differences among these\&. It also knows about and uses commands that tune the GPS for lower latency, decrease bandwidth usage, or increased accuracy on the San Jose Navigation FV18, the Sony CXD2951, the uBlox, and the Motorola OnCore GT+\&. It can read heading and attitude information from the True North Technologies Revolution 2X Digital compass\&. - -.PP -gpsd can use differential\-GPS corrections from a DGPS radio or over the net, from a ground station running a DGPSIP server that reports RTCM\-S104 data; this will improve user error 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\&. See [xref to refsect1] and [xref to refsect1] for discussion\&. - +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. +.PP +gpsd +should be able to query any GPS that speaks either the standard textual NMEA 0183 protocol, or the binary Rockwell protocol used by EarthMate and some other GPSes, the TSIP binary protocol used by Trimble GPSes, or the binary SiRF protocol used by SiRf\-II and SiRF\-Star chipsets, or the Garmin binary protocol used by the USB version of the Garmin 18 and other Garmin USB GPSes, or the binary protocol used by Evermore chipsets, or the extended NMEA used by iTrax. +gpsd +effectively hides the differences among these. It also knows about and uses commands that tune the GPS for lower latency, decreased bandwidth usage, or increased accuracy on the San Jose Navigation FV18, the Sony CXD2951, the uBlox, and the Motorola OnCore GT+. It can read heading and attitude information from the True North Technologies Revolution 2X Digital compass. +.PP +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\-S104 data; this will improve user error 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.See +the section called \(lqACCURACY\(rq +and +the section called \(lqFILES\(rq +for discussion. .PP The program accepts the following options: - .TP \-f -Set a GPS device name\&. This option is deprecated and may be removed in a future version\&. Each command\-line argument will be treated as a device to be probed for the presence of a GPS; that, rather than the \-f option, is the preferred way of specifying GPS devices at startup\&. - +Set a GPS device name. This option is deprecated and may be removed in a future version. Each command\-line argument will be treated as a device to be probed for the presence of a GPS; that, rather than the \-f option, is the preferred way of specifying GPS devices at startup. .TP \-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\&. - +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. .TP \-S -Set TCP/IP port on which to listen for GPSD clients (default is 2947)\&. - +Set TCP/IP port on which to listen for GPSD clients (default is 2947). .TP \-d -Query a specific differential\-GPS (DGPSIP) server\&. If a suffix of the server name begins with ":" it is interpreted as a port number, overriding the default IANA\-assigned port of 2101\&. - +Query a specific differential\-GPS service (DGPSIP server or Ntrip broadcaster). If the DGPS\-service 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". .TP \-n -Don't wait for a client to connect before polling whatever GPS is associated with it\&. The wait is a feature; many serial GPSes go to a standby mode (not drawing power) before the host machine asserts DTR, so waiting for the first actual request can save valuable battery power on portable equipment\&. This option combines well with \-D2 to enable monitoring of the GPS data stream\&. - +Don't wait for a client to connect before polling whatever GPS is associated with it. The wait is a feature; many serial GPSes go to a standby mode (not drawing power) before the host machine asserts DTR, so waiting for the first actual request can save valuable battery power on portable equipment. This option combines well with \-D2 to enable monitoring of the GPS data stream. .TP \-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\&. - +Don't daemonize; run in foreground. Also suppresses privilege\-dropping. This switch is mainly useful for debugging. Its meaning may change in future versions. .TP \-h -Display help message and terminate\&. - +Display help message and terminate. .TP \-P -Specify the name and path to record the daemon's process ID\&. - +Specify the name and path to record the daemon's process ID. .TP \-D -Set debug level\&. At debug levels 2 and above, gpsd reports incoming sentence and actions to standard error\&. - +Set debug level. At debug levels 2 and above, +gpsd +reports incoming sentence and actions to standard error. .TP \-V -Dump version and exit\&. - +Dump version and exit. .PP -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 [xref to refsect1] for details on this)\&. Daemon startup will abort with an error if neither any devices nor a control socket are specified\&. - +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 \(lqGPS DEVICE MANAGEMENT\(rq +for details on this). Daemon startup will abort with an error if neither any devices nor a control socket are specified. .PP -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 (that is, issues any command other than F, K, W=0 or R=0)\&. - +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 (that is, issues any command other than F, K, W=0 or R=0). .PP -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: - +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: .TP a -The current altitude as "A=%f", meters above mean sea level\&. - +The current altitude as "A=%f", meters above mean sea level. .TP 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; watch the response, because it is possible for this to fail if the GPS does not support a speed\-switching command\&. In case of failure, the daemon and GPS will continue to communicate at the old speed\&. The B= form is rejected if more than one client is attached to the channel\&. - +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; watch the response, because it is possible for this to fail if the GPS does not support a speed\-switching command. In case of failure, the daemon and GPS will continue to communicate at the old speed. The B= form is rejected if more than one client is attached to the channel. .TP 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 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\&. - -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 '?' at start of session, before the first full packet has been received from the GPS, because its 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\&. - +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. +.sp +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 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. +.sp +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. +.sp +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. To set up conditions for a real answer, issue it after some command that reads position/velocity/time information from the device. .TP 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\&. - +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. .TP e -Returns "E=%f %f %f": three estimated position errors in meters -- total, 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 zero for any of these numbers should be taken to mean that component of DOP is not available\&. See also the 'q' command\&. - +Returns "E=%f %f %f": three estimated position errors in meters \(em total, 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 zero for any of these numbers should be taken to mean that component of DOP is not available. See also the 'q' command. .TP 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\&.) - +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. +.sp +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. +.sp +Once an 'f=' command succeeds, the client is tied to the specified device until the client disconnects. +.sp +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. +.sp +(At protocol level 1, the F command failed if more than one client was attached, and multiple devices were not supported.) .TP g -With =, accepts a single argument which may have either of the values '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 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 'RTCM104') identifying the kind of information the attached device returns\&. - +With =, accepts a single argument which may have either of the values '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 be bound to whatever available device the daemon finds first. +.sp +This command returns either '?' if no device of the specified type(s) could be assigned, otherwise a string ('GPS' or 'RTCM104') identifying the kind of information the attached device returns. .TP 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\&. - +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. .TP 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\&.) - +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. +.sp +(At protocol level 1, there was no K command.) .TP l -Returns three fields: a protocol revision number, the gpsd version, and a list of accepted request letters\&. - +Returns three fields: a protocol revision number, the gpsd version, and a list of accepted request letters. .TP m -The NMEA mode as "M=%d"\&. 0=no mode value yet seen, 1=no fix, 2=2D (no altitude), 3=3D (with altitude)\&. - +The NMEA mode as "M=%d". 0=no mode value yet seen, 1=no fix, 2=2D (no altitude), 3=3D (with altitude). .TP 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\&. - +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. .TP 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: - +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: .RS - .TP 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\&. - +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. .TP timestamp -Seconds since the Unix epoch, UTC\&. May have a fractional part of up to \&.01sec precision\&. - +Seconds since the Unix epoch, UTC. May have a fractional part of up to .01sec precision. .TP time error -Estimated timestamp error (%f, seconds, 95% confidence)\&. - +Estimated timestamp error (%f, seconds, 95% confidence). .TP latitude -Latitude as in the P report (%f, degrees)\&. - +Latitude as in the P report (%f, degrees). .TP longitude -Longitude as in the P report (%f, degrees)\&. - +Longitude as in the P report (%f, degrees). .TP altitude -Altitude as in the A report (%f, meters)\&. - +Altitude as in the A report (%f, meters). .TP horizontal error estimate -Horizontal error estimate as in the E report (%f, meters)\&. - +Horizontal error estimate as in the E report (%f, meters). .TP vertical error estimate -Vertical error estimate as in the E report (%f, meters)\&. - +Vertical error estimate as in the E report (%f, meters). .TP course over ground -Track as in the T report (%f, degrees)\&. - +Track as in the T report (%f, degrees). .TP speed over ground -Speed (%f, meters/sec)\&. Note: older versions of the O command reported this field in knots\&. - +Speed (%f, meters/sec). Note: older versions of the O command reported this field in knots. .TP climb/sink -Vertical velocity as in the U report (%f, meters/sec)\&. - +Vertical velocity as in the U report (%f, meters/sec). .TP estimated error in course over ground -Error estimate for course (%f, degrees, 95% confidence)\&. - +Error estimate for course (%f, degrees, 95% confidence). .TP estimated error in speed over ground -Error estimate for speed (%f, meters/sec, 95% confidence)\&. Note: older versions of the O command reported this field in knots\&. - +Error estimate for speed (%f, meters/sec, 95% confidence). Note: older versions of the O command reported this field in knots. .TP -climb/sink -Estimated error for climb/sink (%f, meters/sec, 95% confidence)\&. - +estimated error in climb/sink +Estimated error for climb/sink (%f, meters/sec, 95% confidence). .RE -.IP - .TP p -Returns the current position in the form "P=%f %f"; numbers are in degrees, latitude first\&. - +Returns the current position in the form "P=%f %f"; numbers are in degrees, latitude first. .TP 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\&. - +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 \(em 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. +.sp +Note: Older versions of +gpsd +reported only the first three DOP numbers, omitting time DOP and total DOP. .TP 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 \fBrtcm104\fR(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\&. - +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 +\fBrtcm104\fR(5). +.sp +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. +.sp +Note: older versions of +gpsd +did not support super\-raw mode. .TP s -The NMEA status as "S=%d"\&. 0=no fix, 1=fix, 2=DGPS\-corrected fix\&. - +The NMEA status as "S=%d". 0=no fix, 1=fix, 2=DGPS\-corrected fix. .TP t -Track made good; course "T=%f" in degrees from true north\&. - +Track made good; course "T=%f" in degrees from true north. .TP u -Current rate of climb as "U=%f" in meters per second\&. Some GPSes (non\-Sirf\-II based) do not report this, in that case gpsd computes it using the altitude from the last fix (if available)\&. - +Current rate of climb as "U=%f" in meters per second. Some GPSes (non\-Sirf\-II based) do not report this, in that case +gpsd +computes it using the altitude from the last fix (if available). .TP v -The current speed over ground as "V=%f" in knots\&. - +The current speed over ground as "V=%f" in knots. .TP w -Sets or toggles 'watcher' mode (see the descroiption 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\&. - +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. .TP 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\&.) - +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. +.sp +(At protocol level 1, the nonzero response was always 1.) .TP 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\&.) - +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. +.sp +(At protocol level 1, this response had no tag or timestamp.) .TP 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 Z command returns daemon profiling information of interest to +gpsd +developers. The format of this string is subject to change without notice. .PP -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\&. - +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. .PP -Requests can be concatenated and sent as a string; gpsd will then respond with a comma\-separated list of replies\&. - +Requests can be concatenated and sent as a string; +gpsd +will then respond with a comma\-separated list of replies. .PP -Every gpsd reply will start with the string "GPSD" followed by the replies\&. Examples: - -.IP - +Every +gpsd +reply will start with the string "GPSD" followed by the replies. Examples: +.sp +.nf query: "p\\n" - reply: "GPSD,P=36\&.000000 123\&.000000\\r\\n" + reply: "GPSD,P=36.000000 123.000000\\r\\n" query: "d\\n" - reply: "GPSD,D=2002\-11\-16T02:45:05\&.12Z\\r\\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" - + reply: "GPSD,V=0.000000,A=37.900000\\r\\n" +.fi .PP -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\&. - +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. .PP -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\&. - +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. .PP -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\&. - +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. .SH "GPS DEVICE MANAGEMENT" - .PP -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\&. - +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. .PP -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 \fI/dev/foo\fR\&. 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 \fI/dev/foo\fR from the search list\&. send "\-/dev/foo\\n"\&. - +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 +\fI/dev/foo\fR. 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 +\fI/dev/foo\fR +from the search list. send "\-/dev/foo\\n". .PP -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 control string to a specified device, write to the control socket a '!', followed by the device name, followed by '=', followed by the control string. .PP -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\&. - +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. .PP -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 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. .SH "ACCURACY" - .PP -The base user 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 \fInot\fR rely on GPS altitude for life\-critical tasks such as landing an airplane\&. - +The base user 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 +\fInot\fR +rely on GPS altitude for life\-critical tasks such as landing an airplane. .PP -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\&. - +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. .PP -DGPS correction will reduce UERE from roughly 8 meters to roughly 2 meters, provided you are within about 100mi (160km) of a DGPS ground station\&. - +DGPS correction will reduce UERE from roughly 8 meters to roughly 2 meters, provided you are within about 100mi (160km) of a DGPS ground station. .PP -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\&. - +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. .SH "USE WITH NTP" - -.PP -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 \fB\-n\fR mode so the clock will be updated even when no clients are active\&. - -.PP -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\&. - -.PP -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\&. - .PP -Here is a sample \fIntp\&.conf\fR configuration stanza telling ntpd how to read the GPS notfications: - +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 +\fB\-n\fR +mode so the clock will be updated even when no clients are active. +.PP +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. +.PP +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. +.PP +Here is a sample +\fIntp.conf\fR +configuration stanza telling +ntpd +how to read the GPS notfications: +.sp .nf +server 127.127.28.0 minpoll 4 maxpoll 4 +fudge 127.127.28.0 time1 0.420 refid GPS -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 - +server 127.127.28.1 minpoll 4 maxpoll 4 prefer +fudge 127.127.28.1 refid GPS1 .fi - .PP -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\&. - +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. .PP -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\&. - +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. .PP 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): - -.IP +.sp +.nf 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(0) .GPS. 0 l 13 16 377 0.000 0.885 0.882 +.fi .PP If you are running PPS then it will look like this: - -.IP +.sp +.nf 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 - +\-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 +.fi .PP -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\-II, 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 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\-II, 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. .PP -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\&. - -.SH "USE WITH D-BUS" - +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. +.SH "USE WITH D\-BUS" .PP -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\&. - +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. .SH "SECURITY AND PERMISSIONS ISSUES" - .PP -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" 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 \fI/dev/ttyS0\fR\&. - +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" and its group ID to the group of the initial GPS passed on the command line \(em or, if that device doesn't exist, to the group of +\fI/dev/ttyS0\fR. .PP -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\&. - +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. .PP -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)\&. - +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). .PP -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)\&. - +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). .SH "LIMITATIONS" - .PP -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\&. - +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. .PP -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\&. - +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. .PP -If your GPS uses a SiRF chipset at firmware level 231, and it is after 1 Jan 2006, 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\&. - +If your GPS uses a SiRF chipset at firmware level 231, and it is after 1 Jan 2006, 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. .PP -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\&. - +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. .PP -Autobauding on the Trimble GPSes can take as long as 5 seconds if the device speed is not matched to the GPS speed\&. - +Autobauding on the Trimble GPSes can take as long as 5 seconds if the device speed is not matched to the GPS speed. .PP -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\&. - +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. .SH "FILES" - .TP \fI/dev/ttyS0\fR -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\&. - +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. .SH "APPLICABLE STANDARDS" - .PP -The official NMEA protocol standard is available on paper from the National Marine Electronics Association: \fIhttp://www.nmea.org/pub/0183/\fR, but is proprietary and expensive; the maintainers of gpsd have made a point of not looking at it\&. The GPSD website: \fIhttp://gpsd.berlios.de/\fR links to several documents that collect publicly disclosed information about the protocol\&. - -.PP -gpsd parses the following NMEA sentences: RMC, GGA, GSA, GSV, 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, PGRME\&. Note that gpsd returns pure decimal degrees, not the hybrid degree/minute format described in the NMEA standard\&. - +The official NMEA protocol standard is available on paper from the +[1]\&\fINational Marine Electronics Association\fR, but is proprietary and expensive; the maintainers of +gpsd +have made a point of not looking at it. The +[2]\&\fIGPSD website\fR +links to several documents that collect publicly disclosed information about the protocol. +.PP +gpsd +parses the following NMEA sentences: RMC, GGA, GSA, GSV, 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, PGRME. Note that +gpsd +returns pure decimal degrees, not the hybrid degree/minute format described in the NMEA standard. .SH "SEE ALSO" - .PP - \fBgps\fR(1), \fBlibgps\fR(3), \fBlibgpsd\fR(3), \fBgpsprof\fR(1), \fBgpsfake\fR(1), \fBrtcm\-104\fR(5)\&. - +\fBgps\fR(1), +\fBlibgps\fR(3), +\fBlibgpsd\fR(3), +\fBgpsprof\fR(1), +\fBgpsfake\fR(1), +\fBrtcm\-104\fR(5). .SH "AUTHORS" - .PP -Remco Treffcorn, Derrick Brashear, Russ Nelson, Eric S\&. Raymond\&. This manual page by Eric S\&. Raymond <esr@thyrsus\&.com>\&. There is a project page here: \fIhttp://gpsd.berlios.de/\fR\&. - +Remco Treffcorn, Derrick Brashear, Russ Nelson, Eric S. Raymond. This manual page by Eric S. Raymond +<esr@thyrsus.com>. There is a project page +[2]\&\fIhere\fR. +.SH "REFERENCES" +.TP 3 +1.\ National Marine Electronics Association +\%http://www.nmea.org/pub/0183/ +.TP 3 +2.\ GPSD website +\%http://gpsd.berlios.de/ @@ -60,10 +60,6 @@ #define QLEN 5 -/* Where to find the list of DGPS correction servers, if there is one */ -#define DGPS_SERVER_LIST "/usr/share/gpsd/dgpsip-servers" - - /* * The name of a tty device from which to pick up whatever the local * owning group for tty devices is. Used when we drop privileges. @@ -78,8 +74,10 @@ static jmp_buf restartbuf; static struct gps_context_t context = { .valid = 0, .sentdgps = false, + .dgnss_service = dgnss_none, .fixcnt = 0, .dsock = -1, + .dgnss_privdata = NULL, .rtcmbytes = 0, .rtcmbuf = {'\0'}, .rtcmtime = 0, @@ -172,11 +170,11 @@ void gpsd_report(int errlevel, const char *fmt, ... ) static void usage(void) { - (void)printf("usage: gpsd [-n] [-N] [-d dgpsip-server] [-D n] [-F sockfile] [-P pidfile] [-S port] [-h] device...\n\ + (void)printf("usage: gpsd [-n] [-N] [-d dgnss-service] [-D n] [-F sockfile] [-P pidfile] [-S port] [-h] device...\n\ Options include: \n\ -n = don't wait for client connects to poll GPS\n\ -N = don't go into background\n\ - -d host[:port] = set DGPS server \n\ + -d [{dgpsip|ntrip}://][user:passwd@]host[:port][/stream] = set DGPS service\n\ -F sockfile = specify control socket location\n\ -P pidfile = set file to record process ID \n\ -D integer (default 0) = set debug level \n\ @@ -489,7 +487,7 @@ static bool assign_channel(struct subscriber_t *user) /*@ +branchstate +usedef +globstate @*/ #ifdef RTCM104_SERVICE -static int handle_dgpsip_request(int cfd UNUSED, char *buf UNUSED, int buflen UNUSED) +static int handle_rtcm_request(int cfd UNUSED, char *buf UNUSED, int buflen UNUSED) /* interpret a client request; cfd is the socket back to the client */ { return 0; /* not actually interpreting these yet */ @@ -1072,7 +1070,7 @@ int main(int argc, char *argv[]) static bool nowait = false; static int st, csock = -1; static gps_mask_t changed; - static char *dgpsserver = NULL; + static char *dgnss_service = NULL; static char *gpsd_service = NULL; #ifdef RTCM104_SERVICE static char *rtcm_service = NULL; @@ -1115,7 +1113,7 @@ int main(int argc, char *argv[]) gpsd_service = optarg; break; case 'd': - dgpsserver = optarg; + dgnss_service = optarg; break; case 'n': nowait = true; @@ -1200,8 +1198,8 @@ int main(int argc, char *argv[]) gpsd_report(1, "listening on port %s\n", rtcm_service); #endif /* RTCM104_SERVICE */ - if (dgpsserver) { - int dsock = dgpsip_open(&context, dgpsserver); + if (dgnss_service) { + int dsock = dgnss_open(&context, dgnss_service); if (dsock >= 0) FD_SET(dsock, &all_fds); } @@ -1388,10 +1386,10 @@ int main(int argc, char *argv[]) FD_CLR(csock, &rfds); } - /* be ready for DGPSIP reports */ - if (context.dsock >= 0 && FD_ISSET(context.dsock, &rfds)) - dgpsip_poll(&context); - + if (context.dsock >= 0 && FD_ISSET(context.dsock, &rfds)) { + /* be ready for DGPS reports */ + dgnss_poll(&context); + } /* read any commands that came in over control sockets */ for (cfd = 0; cfd < FD_SETSIZE; cfd++) if (FD_ISSET(cfd, &control_fds)) { @@ -1411,9 +1409,9 @@ int main(int argc, char *argv[]) if (!allocated_channel(channel)) continue; - /* pass the current DGPSIP correction to the GPS if new */ + /* pass the current RTCM correction to the GPS if new */ if (channel->device_type) - dgpsip_relay(channel); + rtcm_relay(channel); /* get data from the device */ changed = 0; @@ -1471,14 +1469,12 @@ int main(int argc, char *argv[]) } #ifdef NOT_FIXED - /* may be time to hunt up a DGPSIP server */ if (context.fixcnt > 0 && context.dsock == -1) { for (channel=channels; channel < channels+MAXDEVICES; channel++) { if (channel->gpsdata.fix.mode > MODE_NO_FIX) { - dgpsip_autoconnect(&context, - channel->gpsdata.fix.latitude, - channel->gpsdata.fix.longitude, - DGPS_SERVER_LIST); + dgnss_autoconnect(&context, + channel->gpsdata.fix.latitude, + channel->gpsdata.fix.longitude); break; } } @@ -1504,7 +1500,7 @@ int main(int argc, char *argv[]) #ifdef RTCM104_SERVICE if (subscribers[cfd].requires==RTCM104 || subscribers[cfd].requires==ANY) { - if (handle_dgpsip_request(cfd, buf, buflen) < 0) + if (handle_rtcm_request(cfd, buf, buflen) < 0) detach_client(cfd); } else #endif /* RTCM104_SERVICE */ @@ -46,9 +46,11 @@ struct gps_context_t { int valid; /* member validity flags */ #define LEAP_SECOND_VALID 0x01 /* we have or don't need correction */ /* DGPSIP status */ - bool sentdgps; /* have we sent a DGPSIP R report? */ + bool sentdgps; /* have we sent a DGPS report? */ + enum { dgnss_none, dgnss_dgpsip, dgnss_ntrip } dgnss_service; /* type of DGNSS service */ int fixcnt; /* count of good fixes seen */ - int dsock; /* socket to DGPS server */ + int dsock; /* socket to DGPSIP server/Ntrip caster */ + void *dgnss_privdata; /* DGNSS service specific data */ ssize_t rtcmbytes; /* byte count of last RTCM104 report */ char rtcmbuf[RTCM_MAX]; /* last RTCM104 report */ double rtcmtime; /* timestamp of last RTCM104 report */ @@ -249,12 +251,20 @@ extern ssize_t packet_parse(struct gps_device_t *, size_t); extern ssize_t packet_get(struct gps_device_t *); extern int packet_sniff(struct gps_device_t *); +extern int dgnss_open(struct gps_context_t *, char *); +extern void dgnss_poll(struct gps_context_t *); +extern void dgnss_report(struct gps_device_t *); +extern void dgnss_autoconnect(struct gps_context_t *, double, double); +extern void rtcm_relay(struct gps_device_t *); + extern int dgpsip_open(struct gps_context_t *, const char *); extern void dgpsip_poll(struct gps_context_t *); -extern void dgpsip_relay(struct gps_device_t *); extern void dgpsip_report(struct gps_device_t *); extern void dgpsip_autoconnect(struct gps_context_t *, double, double, const char *); +extern int ntrip_open(struct gps_context_t *, char *); +extern void ntrip_poll(struct gps_context_t *); +extern void ntrip_report(struct gps_device_t *); extern int gpsd_open(struct gps_device_t *); extern bool gpsd_write(struct gps_device_t *, void const *, size_t); @@ -267,6 +277,7 @@ extern void gpsd_close(struct gps_device_t *); extern void gpsd_zero_satellites(/*@out@*/struct gps_data_t *sp)/*@modifies sp@*/; extern void gpsd_interpret_subframe(struct gps_device_t *, unsigned int[]); extern /*@ observer @*/ char *gpsd_hexdump(const void *, size_t); +extern void gpsd_position_fix_dump(struct gps_device_t *, /*@out@*/char[], size_t); extern int netlib_connectsock(const char *, const char *, const char *); extern int ntpshm_init(struct gps_context_t *, bool); diff --git a/gpsd.spec.in b/gpsd.spec.in index af5facd3..3331177a 100644 --- a/gpsd.spec.in +++ b/gpsd.spec.in @@ -143,10 +143,11 @@ cp gps.py gpsfake.py "$RPM_BUILD_ROOT"%{_libdir}/python${PYVERSION}/site-package %{_libdir}/X11/app-defaults/xgpsspeed %changelog -* Tue Mar 14 2006 Eric S. Raymond <esr@snark.thyrsus.com> - @VERSION@-1 +* Tue Jun 6 2006 Eric S. Raymond <esr@snark.thyrsus.com> - 2.33-1 - Fix bad unit conversion in V output. Clean up some man-page messes. Fixed buggy libgps parsing of multiple responses. It's now possible - to lock gpsd to a fixed speed at compile time for embedded use. + to lock gpsd to a fixed speed at compile time for embedded use. Added + NTRIP support, thanks to Ville Nuorvala. * Sun Mar 12 2006 Eric S. Raymond <esr@snark.thyrsus.com> - 2.32-1 - Cleanup of the xgps layout, and minor memory-leak fixes for xgps. Fix @@ -23,7 +23,7 @@ <!-- arg choice='opt'>-R <replaceable>rtcm-listener-port</replaceable></arg --> <arg choice='opt'>-S <replaceable>listener-port</replaceable></arg> - <arg choice='opt'>-d <replaceable>DGPSIP-server</replaceable></arg> + <arg choice='opt'>-d <replaceable>DGPS-service URL</replaceable></arg> <arg choice='opt'>-n </arg> <arg choice='opt'>-N </arg> <arg choice='opt'>-h </arg> @@ -65,15 +65,15 @@ and attitude information from the True North Technologies Revolution 2X Digital compass.</para> <para><application>gpsd</application> can use differential-GPS -corrections from a DGPS radio or over the net, from a ground station running a -DGPSIP server that reports RTCM-S104 data; this will improve user -error by roughly a factor of four. When <application>gpsd</application> -opens a serial device emitting RTCM-104, it automatically recognizes -this and uses the device as a correction source for all connected GPSes. -<!-- If no server is specified, <application>gpsd</application> will -hunt for one.--> -See <xref linkend='accuracy'/> and <xref -linkend='files'/> for discussion.</para> +corrections from a DGPS radio or over the net, from a ground station +running a DGPSIP server or a Ntrip broadcaster that reports RTCM-S104 +data; this will improve user error by roughly a factor of four. When +<application>gpsd</application> opens a serial device emitting +RTCM-104, it automatically recognizes this and uses the device as a +correction source for all connected GPSes. <!-- If no server is +specified, <application>gpsd</application> will hunt for one.--> See +<xref linkend='accuracy'/> and <xref linkend='files'/> for +discussion.</para> <!-- para><application>gpsd</application> may itself serve DGPSIP data from an attached RTCM-104 source to other instances of @@ -114,11 +114,21 @@ clients.</para></listitem> <varlistentry> <term>-d</term> <listitem> -<para>Query a specific differential-GPS (DGPSIP) server. If a suffix of the -server name begins with ":" it is interpreted as a port number, -overriding the default IANA-assigned port of 2101. <!-- If this -option is not given, <application>gpsd</application> will hunt -for a DGPSIP server. --></para> +<para>Query a specific differential-GPS service (DGPSIP server or +Ntrip broadcaster). If the DGPS-service URL 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 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". <!-- If this +option is not given, <application>gpsd</application> will hunt for a +DGPSIP server. --></para> </listitem> </varlistentry> <varlistentry> diff --git a/libgpsd_core.c b/libgpsd_core.c index 4f17660b..cda8aee3 100644 --- a/libgpsd_core.c +++ b/libgpsd_core.c @@ -213,8 +213,9 @@ static double degtodm(double a) return t; } -static void gpsd_binary_fix_dump(struct gps_device_t *session, - char bufp[],size_t len) +/*@ -mustdefine @*/ +void gpsd_position_fix_dump(struct gps_device_t *session, + /*@out@*/char bufp[], size_t len) { struct tm tm; time_t intfixtime; @@ -257,9 +258,18 @@ static void gpsd_binary_fix_dump(struct gps_device_t *session, (void)strcat(bufp, (session->mag_var > 0) ? "E": "W"); } nmea_add_checksum(bufp); - len -= strlen(bufp); - bufp += strlen(bufp); } +} +/*@ +mustdefine @*/ + +static void gpsd_transit_fix_dump(struct gps_device_t *session, + char bufp[], size_t len) +{ + struct tm tm; + time_t intfixtime; + + intfixtime = (time_t)session->gpsdata.fix.time; + (void)gmtime_r(&intfixtime, &tm); /*@ -usedef @*/ (void)snprintf(bufp, len, "$GPRMC,%02d%02d%02d,%c,%09.4f,%c,%010.4f,%c,%.4f,%.3f,%02d%02d%02d,,", @@ -280,6 +290,13 @@ static void gpsd_binary_fix_dump(struct gps_device_t *session, nmea_add_checksum(bufp); } +static void gpsd_binary_fix_dump(struct gps_device_t *session, + char bufp[], size_t len) +{ + gpsd_position_fix_dump(session, bufp, len); + gpsd_transit_fix_dump(session, bufp + strlen(bufp), len - strlen(bufp)); +} + static void gpsd_binary_satellite_dump(struct gps_device_t *session, char bufp[], size_t len) { @@ -637,7 +654,7 @@ gps_mask_t gpsd_poll(struct gps_device_t *session) } } - dgpsip_report(session); + dgnss_report(session); return session->gpsdata.set; } diff --git a/ntrip.c b/ntrip.c new file mode 100644 index 00000000..9d89c4e8 --- /dev/null +++ b/ntrip.c @@ -0,0 +1,473 @@ +/* ntrip.c -- gather and dispatch DGNSS data from Ntrip broadcasters */ +#include <unistd.h> +#include <stdlib.h> +#include <stdio.h> +#include <math.h> +#include <netdb.h> +#include <sys/socket.h> +#include <sys/time.h> +#include <string.h> +#include <errno.h> +#include <fcntl.h> +#include "gpsd.h" +#include "bsd-base64.h" + +struct ntrip_stream_t { + char mountpoint[101]; + enum { fmt_rtcm2, fmt_rtcm2_0, fmt_rtcm2_1, fmt_rtcm2_2, fmt_rtcm2_3, fmt_unknown } format; + int carrier; + double latitude; + double longitude; + int nmea; + enum { cmp_enc_none, cmp_enc_unknown } compr_encryp; + enum { auth_none, auth_basic, auth_digest, auth_unknown } authentication; + int fee; + int bitrate; +}; + +#define NTRIP_SOURCETABLE "SOURCETABLE 200 OK\r\n" +#define NTRIP_ENDSOURCETABLE "ENDSOURCETABLE" +#define NTRIP_CAS "CAS;" +#define NTRIP_NET "NET;" +#define NTRIP_STR "STR;" +#define NTRIP_BR "\r\n" +#define NTRIP_QSC "\";\"" +#define NTRIP_ICY "ICY 200 OK" +#define NTRIP_UNAUTH "401 Unauthorized" + +/*@ -fullinitblock @*/ +static struct ntrip_stream_t ntrip_stream = { + .longitude = NAN, + .latitude = NAN +}; +/*@ +fullinitblock @*/ + +/*@ -temptrans -mustfreefresh @*/ +static char *ntrip_field_iterate(char *start, /*@null@*/char *prev, const char *eol) +{ + char *s, *t, *u; + + if (start) + s = start; + else { + if (!prev) + return NULL; + s = prev + strlen(prev) + 1; + if (s >= eol) + return NULL; + } + + /* ignore any quoted ; chars as they are part of the field content */ + t = s; + while ((u = strstr(t, NTRIP_QSC))) + t = u + strlen(NTRIP_QSC); + + if ((t = strstr(t, ";"))) + *t = '\0'; + + gpsd_report(5, "Next Ntrip source table field %s\n", s); + + return s; +} +/*@ +temptrans +mustfreefresh @*/ + +/*@ -mustfreefresh @*/ +static void ntrip_str_parse(char *str, size_t len, + /*@out@*/struct ntrip_stream_t *hold) +{ + char *s, *eol = str + len; + + memset(hold, 0, sizeof(*hold)); + + /* <mountpoint> */ + if ((s = ntrip_field_iterate(str, NULL, eol))) + strncpy(hold->mountpoint, s, sizeof(hold->mountpoint) - 1); + /* <identifier> */ + s = ntrip_field_iterate(NULL, s, eol); + /* <format> */ + if ((s = ntrip_field_iterate(NULL, s, eol))) { + if (strcasecmp("RTCM 2", s)==0) + hold->format = fmt_rtcm2; + else if (strcasecmp("RTCM 2.0", s)==0) + hold->format = fmt_rtcm2_0; + else if (strcasecmp("RTCM 2.1", s)==0) + hold->format = fmt_rtcm2_1; + else if (strcasecmp("RTCM 2.2", s)==0) + hold->format = fmt_rtcm2_2; + else if (strcasecmp("RTCM 2.3", s)==0) + hold->format = fmt_rtcm2_3; + else + hold->format = fmt_unknown; + } + /* <format-details> */ + s = ntrip_field_iterate(NULL, s, eol); + /* <carrier> */ + if ((s = ntrip_field_iterate(NULL, s, eol))) + (void)sscanf(s, "%d", &hold->carrier); + /* <nav-system> */ + s = ntrip_field_iterate(NULL, s, eol); + /* <network> */ + s = ntrip_field_iterate(NULL, s, eol); + /* <country> */ + s = ntrip_field_iterate(NULL, s, eol); + /* <latitude> */ + hold->latitude = NAN; + if ((s = ntrip_field_iterate(NULL, s, eol))) + (void)sscanf(s, "%lf", &hold->latitude); + /* <longitude> */ + hold->longitude = NAN; + if ((s = ntrip_field_iterate(NULL, s, eol))) + (void)sscanf(s, "%lf", &hold->longitude); + /* <nmea> */ + if ((s = ntrip_field_iterate(NULL, s, eol))) { + (void)sscanf(s, "%d", &hold->nmea); + } + /* <solution> */ + s = ntrip_field_iterate(NULL, s, eol); + /* <generator> */ + s = ntrip_field_iterate(NULL, s, eol); + /* <compr-encryp> */ + if ((s = ntrip_field_iterate(NULL, s, eol))) { + if (strcasecmp("none", s)==0) + hold->compr_encryp = cmp_enc_none; + else + hold->compr_encryp = cmp_enc_unknown; + } + /* <authentication> */ + if ((s = ntrip_field_iterate(NULL, s, eol))) { + if (strcasecmp("N", s)==0) + hold->authentication = auth_none; + else if (strcasecmp("B", s)==0) + hold->authentication = auth_basic; + else if (strcasecmp("D", s)==0) + hold->authentication = auth_digest; + else + hold->authentication = auth_unknown; + } + /* <fee> */ + if ((s = ntrip_field_iterate(NULL, s, eol))) { + (void)sscanf(s, "%d", &hold->fee); + } + /* <bitrate> */ + if ((s = ntrip_field_iterate(NULL, s, eol))) { + (void)sscanf(s, "%d", &hold->bitrate); + } + /* ...<misc> */ + while ((s = ntrip_field_iterate(NULL, s, eol))); +} +/*@ +mustfreefresh @*/ + +static int ntrip_sourcetable_parse(int fd, char *buf, ssize_t blen, + const char *stream, + struct ntrip_stream_t *keep) +{ + struct ntrip_stream_t hold; + ssize_t llen, len = 0; + char *line; + bool srctbl = false; + bool match = false; + + for (;;) { + char *eol; + ssize_t rlen; + + memset(&buf[len], 0, (size_t)(blen - len)); + + if ((rlen = recv(fd, &buf[len], (size_t)(blen - 1 - len), 0)) < 0) { + if (errno == EINTR) + continue; + return -1; + } + if (rlen == 0) + continue; + + line = buf; + rlen = len += rlen; + + gpsd_report(5, "Ntrip source table buffer %s\n", buf); + + if (!srctbl) { + /* parse SOURCETABLE */ + if (strncmp(line,NTRIP_SOURCETABLE,strlen(NTRIP_SOURCETABLE))==0) { + srctbl = true; + llen = (ssize_t)strlen(NTRIP_SOURCETABLE); + line += llen; + len -= llen; + } else { + gpsd_report(1, "Received unexpexted Ntrip reply %s.\n", buf); + return -1; + } + } + if (!srctbl) + return -1; + + while (len > 0) { + /* parse ENDSOURCETABLE */ + if (strncmp(line, NTRIP_ENDSOURCETABLE, strlen(NTRIP_ENDSOURCETABLE))==0) + return match ? 0 : -1; + + if (!(eol = strstr(line, NTRIP_BR))) + break; + + gpsd_report(4, "next Ntrip source table line %s\n", line); + + *eol = '\0'; + llen = (ssize_t)(eol - line); + + /* todo: parse headers */ + + /* parse STR */ + if (strncmp(line, NTRIP_STR, strlen(NTRIP_STR))==0) { + ntrip_str_parse(line + strlen(NTRIP_STR), (size_t)(llen - strlen(NTRIP_STR)), &hold); + if (stream!=NULL && strcmp(stream, hold.mountpoint)==0) { + /* todo: support for RTCM 3.0, SBAS (WAAS, EGNOS), ... */ + if (hold.format == fmt_unknown) { + gpsd_report(1, + "Ntrip stream %s format not supported\n", + line); + return -1; + } + /* todo: support encryption and compression algorithms */ + if (hold.compr_encryp != cmp_enc_none) { + gpsd_report(1, + "Ntrip stream %s compression/encryption algorithm not supported\n", + line); + return -1; + } + /* todo: support digest authentication */ + if (hold.authentication != auth_none + && hold.authentication != auth_basic) { + gpsd_report(1, + "Ntrip stream %s authentication method not supported\n", + line); + return -1; + } + memcpy(keep, &hold, sizeof(hold)); + match = true; + } + /* todo: compare stream location to own location to + find nearest stream if user hasn't provided one */ + } + /* todo: parse CAS */ + /* else if (strncmp(line, NTRIP_CAS, strlen(NTRIP_CAS))==0); */ + + /* todo: parse NET */ + /* else if (strncmp(line, NTRIP_NET, strlen(NTRIP_NET))==0); */ + + llen += strlen(NTRIP_BR); + line += llen; + len -= llen; + gpsd_report(5, "Remaining Ntrip source table buffer %d %s\n", len, line); + } + /* message too big to fit into buffer */ + if (len == blen - 1) + return -1; + + if (len > 0) + memcpy(buf, &buf[rlen-len], (size_t)len); + } + + return (int)len; +} + +static int ntrip_stream_probe(const char *caster, + const char *port, + const char *stream, + struct ntrip_stream_t *keep) +{ + int ret; + int dsock; + char buf[BUFSIZ]; + + if ((dsock = netlib_connectsock(caster, port, "tcp")) < 0) { + printf("error %d\n", dsock); + return -1; + } + (void)snprintf(buf, sizeof(buf), + "GET / HTTP/1.1\r\n" + "User-Agent: NTRIP gpsd/%s\r\n" + "Connection: close\r\n" + "\r\n", + VERSION); + (void)write(dsock, buf, strlen(buf)); + ret = ntrip_sourcetable_parse(dsock, buf, (ssize_t)sizeof(buf), stream, keep); + (void)close(dsock); + return ret; +} + +static int ntrip_auth_encode(const struct ntrip_stream_t *stream, + const char *auth, + /*@out@*/char buf[], + size_t size) +{ + memset(buf, 0, size); + if (stream->authentication == auth_none) + return 0; + else if (stream->authentication == auth_basic) { + char authenc[64]; + if (!auth) + return -1; + memset(authenc, 0, sizeof(authenc)); + if (b64_ntop((u_char *) auth, strlen(auth), authenc, sizeof(authenc) - 1) < 0) + return -1; + (void)snprintf(buf, size - 1, "Authorization: Basic %s\r\n", authenc); + } else { + /* todo: support digest authentication */ + } + return 0; +} + +/*@ -nullpass @*/ /* work around a splint bug */ +static int ntrip_stream_open(const char *caster, + const char *port, + const char *auth, + struct gps_context_t *context, + struct ntrip_stream_t *stream) +{ + char buf[BUFSIZ]; + char authstr[128]; + int opts; + + if (ntrip_auth_encode(stream, auth, authstr, sizeof(authstr)) < 0) { + gpsd_report(1, "User-ID and password needed for %s:%s/%s\n", + caster, port, stream->mountpoint); + return -1; + } + if ((context->dsock = netlib_connectsock(caster, port, "tcp")) < 0) + return -1; + + (void)snprintf(buf, sizeof(buf), + "GET /%s HTTP/1.1\r\n" + "User-Agent: NTRIP gpsd/%s\r\n" + "Accept: rtk/rtcm, dgps/rtcm\r\n" + "%s" + "Connection: close\r\n" + "\r\n", + stream->mountpoint, VERSION, authstr); + (void)write(context->dsock, buf, strlen(buf)); + + memset(buf, 0, sizeof(buf)); + if (read(context->dsock, buf, sizeof(buf) - 1) < 0) + goto close; + + /* parse 401 Unauthorized */ + if (strstr(buf, NTRIP_UNAUTH)) { + gpsd_report(1, "%s not authorized for Ntrip stream %s:%s/%s\n", + auth, caster, port, stream->mountpoint); + goto close; + } + /* parse SOURCETABLE */ + if (strstr(buf, NTRIP_SOURCETABLE)) { + gpsd_report(1, "Broadcaster doesn't recognize Ntrip stream %s:%s/%s\n", + caster, port, stream->mountpoint); + goto close; + } + /* parse ICY 200 OK */ + if (!strstr(buf, NTRIP_ICY)) { + gpsd_report(1, "Unknown reply %s from Ntrip service %s:%s/%s\n", + buf, caster, port, stream->mountpoint); + goto close; + } + opts = fcntl(context->dsock, F_GETFL); + + if (opts >= 0) + (void)fcntl(context->dsock, F_SETFL, opts | O_NONBLOCK); + + context->dgnss_service = dgnss_ntrip; +#ifndef S_SPLINT_S + context->dgnss_privdata = stream; +#endif + return context->dsock; +close: + (void)close(context->dsock); + return -1; +} +/*@ +nullpass @*/ + +/*@ -branchstate @*/ +int ntrip_open(struct gps_context_t *context, char *caster) +/* open a connection to a Ntrip broadcaster */ +{ + char *amp, *colon, *slash; + char *auth = NULL; + char *port = NULL; + char *stream = NULL; + int ret; + + /*@ -boolops @*/ + if ((amp = strchr(caster, '@'))) { + if ((colon = strchr(caster, ':')) && colon < amp) { + auth = caster; + *amp = '\0'; + caster = amp + 1; + } else { + gpsd_report(1, "can't extract user-ID and password from %s\n", + caster); + return -1; + } + } + /*@ +boolops @*/ + if ((slash = strchr(caster, '/'))) { + *slash = '\0'; + stream = slash + 1; + } else { + /* todo: add autoconnect like in dgpsip.c */ + gpsd_report(1, "can't extract Ntrip stream from %s\n", caster); + return -1; + } + if ((colon = strchr(caster, ':'))) { + port = colon + 1; + *colon = '\0'; + } + if (!port) { + port = "rtcm-sc104"; + if (!getservbyname(port, "tcp")) + port = DEFAULT_RTCM_PORT; + } + if (ntrip_stream_probe(caster, port, stream, &ntrip_stream)) { + gpsd_report(1, "unable to probe for data about stream %s:%s/%s\n", + caster, port, stream); + return -1; + } + ret = ntrip_stream_open(caster, port, auth, context, &ntrip_stream); + if (ret >= 0) + gpsd_report(1,"connection to Ntrip broadcaster %s established.\n", + caster); + else + gpsd_report(1, "can't connect to Ntrip stream %s:%s/%s.\n", + caster, port, stream); + return ret; +} +/*@ +branchstate @*/ + +void ntrip_poll(struct gps_context_t *context) +/* poll the NTRIP server for a correction report */ +{ + if (context->dsock > -1) { + context->rtcmbytes = read(context->dsock, context->rtcmbuf, sizeof(context->rtcmbuf)); + if (context->rtcmbytes < 0 && errno != EAGAIN) + gpsd_report(1, "Read from rtcm source failed\n"); + else + context->rtcmtime = timestamp(); + } +} + +void ntrip_report(struct gps_device_t *session) +/* may be time to ship a usage report to the Ntrip caster */ +{ + struct ntrip_stream_t *stream = session->context->dgnss_privdata; + /* + * 10 is an arbitrary number, the point is to have gotten several good + * fixes before reporting usage to our Ntrip caster. + */ + if (stream!=NULL && stream->nmea!=0 + && session->context->fixcnt > 10 && !session->context->sentdgps) { + session->context->sentdgps = true; + if (session->context->dsock > -1) { + char buf[BUFSIZ]; + gpsd_position_fix_dump(session, buf, sizeof(buf)); + (void)write(session->context->dsock, buf, strlen(buf)); + gpsd_report(2, "=> dgps %s", buf); + } + } +} diff --git a/rtcmdecode.1 b/rtcmdecode.1 index 74f12f2b..e96c369f 100644 --- a/rtcmdecode.1 +++ b/rtcmdecode.1 @@ -1,78 +1,70 @@ -.\"Generated by db2man.xsl. Don't modify this, modify the source. -.de Sh \" Subsection -.br -.if t .Sp -.ne 5 -.PP -\fB\\$1\fR -.PP -.. -.de Sp \" Vertical space (when we can't use .PP) -.if t .sp .5v -.if n .sp -.. -.de Ip \" List item -.br -.ie \\n(.$>=3 .ne \\$3 -.el .ne 3 -.IP "\\$1" \\$2 -.. -.TH "RTCMDECODE" 1 "" "" "" -.SH NAME +.\" ** You probably do not want to edit this file directly ** +.\" It was generated using the DocBook XSL Stylesheets (version 1.69.1). +.\" Instead of manually editing it, you probably should edit the DocBook XML +.\" source for it and then use the DocBook XSL Stylesheets to regenerate it. +.TH "RTCMDECODE" "1" "06/06/2006" "13 Jul 2005" "13 Jul 2005" +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.SH "NAME" rtcmdecode \- decode RTCM104 streams into a readable format .SH "SYNOPSIS" -.ad l -.hy 0 .HP 11 \fBrtcmdecode\fR [\-d] [\-e] [\-v\ \fIdebuglevel\fR] -.ad -.hy - .SH "DESCRIPTION" - .PP -This tool is a decoder for RTCM\-104, an obscure and complicated serial protocol used for broadcasting pseudorange corrections from differential\-GPS reference stations\&. RTCM\-104 is expected on standard input; an equivalent, 100%\-information\-preserving text format is written to standard output\&. - +This tool is a decoder for RTCM\-104, an obscure and complicated serial protocol used for broadcasting pseudorange corrections from differential\-GPS reference stations. RTCM\-104 is expected on standard input; an equivalent, 100%\-information\-preserving text format is written to standard output. .PP -You can use this tool with \fBnc\fR(1) to examine RTCM feeds from DGPSIP servers\&. - +You can use this tool with +\fBnc\fR(1) +to examine RTCM feeds from DGPSIP servers or Ntrip broadcasters. .PP -The decoder dump format is described in \fBrtcm\fR(5); these lines go to standard output\&. As well as data the decoder also prints decoder status messages to standard error, as necessary\&. - +The decoder dump format is described in +\fBrtcm\fR(5); these lines go to standard output. As well as data the decoder also prints decoder status messages to standard error, as necessary. .SH "OPTIONS" - .PP -The \-d option tells the program to decode RTCM\-104 presented on standard input to a text dump in the format of \fBrtcm\-104\fR(5) on standard output\&. This is the default behavior\&. - +The \-d option tells the program to decode RTCM\-104 presented on standard input to a text dump in the format of +\fBrtcm\-104\fR(5) +on standard output. This is the default behavior. .PP -The \-e option option tells the program to encode a text dump in the format of \fBrtcm\-104\fR(5) to standard output\&. - +The \-e option option tells the program to encode a text dump in the format of +\fBrtcm\-104\fR(5) +to standard output. .PP -The \-v option sets a verbosity level\&. It is mainly of interest to developers\&. - +The \-v option sets a verbosity level. It is mainly of interest to developers. .SH "APPLICABLE STANDARDS" - .PP -The applicable standard is RTCM Recommended Standards for Differential NAVSTAR GPS Service RTCM Paper 194\-93/SC 104\-STD\&. - +The applicable standard is +RTCM Recommended Standards for Differential NAVSTAR GPS Service +RTCM Paper 194\-93/SC 104\-STD. .PP -Ordering instructions are accessible from the website of the Radio Technical Commission for Maritime Services: \fIhttp://www.rtcm.org/\fR under "Publications"\&. - +Ordering instructions are accessible from the website of the +[1]\&\fIRadio Technical Commission for Maritime Services\fR +under "Publications". .SH "BUGS AND LIMITATIONS" - .PP -RTCM\-104 represents floating\-point quantities as an integer multiple of a fixed scale factor\&. Editing an RTCM\-104 dump can produce numbers that are not an integer multiple of the scale factor for their field\&. If you do this, the value actually packed into binary RTCM\-104 will be rounded down to the nearest scale unit, and dumping will show slightly different numbers than those you entered\&. - +RTCM\-104 represents floating\-point quantities as an integer multiple of a fixed scale factor. Editing an RTCM\-104 dump can produce numbers that are not an integer multiple of the scale factor for their field. If you do this, the value actually packed into binary RTCM\-104 will be rounded down to the nearest scale unit, and dumping will show slightly different numbers than those you entered. .PP -The decoder logic is sufficiently convoluted to confuse some compiler optimizers, notably in GCC 3\&.x at \-O2, into generating bad code\&. - +The decoder logic is sufficiently convoluted to confuse some compiler optimizers, notably in GCC 3.x at \-O2, into generating bad code. .SH "SEE ALSO" - .PP - \fBgpsd\fR(8), \fBgps\fR(1), \fBlibgps\fR(3), \fBlibgpsd\fR(3), \fBgpsprof\fR(1), \fBgpsfake\fR(1), \fBrtcm\-104\fR(5)\&. - +\fBgpsd\fR(8), +\fBgps\fR(1), +\fBlibgps\fR(3), +\fBlibgpsd\fR(3), +\fBgpsprof\fR(1), +\fBgpsfake\fR(1), +\fBrtcm\-104\fR(5). .SH "AUTHOR" - .PP -Eric S\&. Raymond <esr@thyrsus\&.com>\&. This is a somewhat hacked version of an RTCM decoder originally written by Wolfgang Rupprecht\&. There is a project page for gpsd here: \fIhttp://gpsd.berlios.de/\fR\&. - +Eric S. Raymond +<esr@thyrsus.com>. This is a somewhat hacked version of an RTCM decoder originally written by Wolfgang Rupprecht. There is a project page for +gpsd[2]\&\fIhere\fR. +.SH "REFERENCES" +.TP 3 +1.\ Radio Technical Commission for Maritime Services +\%http://www.rtcm.org/ +.TP 3 +2.\ here +\%http://gpsd.berlios.de/ diff --git a/rtcmdecode.xml b/rtcmdecode.xml index 3d4ee38b..12214446 100644 --- a/rtcmdecode.xml +++ b/rtcmdecode.xml @@ -32,7 +32,7 @@ written to standard output.</para> <para>You can use this tool with <citerefentry><refentrytitle>nc</refentrytitle><manvolnum>1</manvolnum></citerefentry> -to examine RTCM feeds from DGPSIP servers.</para> +to examine RTCM feeds from DGPSIP servers or Ntrip broadcasters.</para> <para>The decoder dump format is described in <citerefentry><refentrytitle>rtcm</refentrytitle><manvolnum>5</manvolnum></citerefentry>; diff --git a/www/references.html b/www/references.html index 6f9e65d7..d2113673 100644 --- a/www/references.html +++ b/www/references.html @@ -90,9 +90,15 @@ rtcm-104, the specification used for broadcasting differential-gps corrections. Unfortunately, its distribution terms are also evil.</dd> <dt><a href='http://igs.ifag.de/index_ntrip.htm'>Ntrip home page</a></dt> -<dd>NTRIP is a protocol for shipping DGPS corrections that uses HTTP -as a transport layer. We don't support this yet, and may never. The -distribution terms for the NTRIP standard are evil.</dd> +<dd>NTRIP is a protocol for shipping DGPS corrections that uses HTTP +as a transport layer. The distribution terms for the NTRIP standard +are evil, but a stripped down version of the document is freely +available on the home page. Verion 1.0 of the standard is poorly +written, confusing and leaves too much open to the interpretation of +the implementor. With the help of examples in the official standard, +missing in the online version, and the C and Perl reference +implementations, it is however possible to develop a working Ntrip +client.</dd> <dt><a href='http://www.topografix.com/gpx.asp'>GPX Exchange Format</a></dt> <dd>GPX (the GPS Exchange Format) is a light-weight XML data format |