diff options
| author | Eric S. Raymond <esr@thyrsus.com> | 2009-12-04 21:29:20 +0000 |
|---|---|---|
| committer | Eric S. Raymond <esr@thyrsus.com> | 2009-12-04 21:29:20 +0000 |
| commit | 012d54014f104a3b4be2ccf760360f9c7bab91d6 (patch) | |
| tree | e3975c7632528ca83ddd916cb2017b20b25afbea | |
| parent | f680109beb3aa3fd9e2dfc650c1f0c21e3cf0117 (diff) | |
| download | gpsd-012d54014f104a3b4be2ccf760360f9c7bab91d6.tar.gz | |
Update website documentation for the new release and new wire protocol.
| -rw-r--r-- | NEWS | 2 | ||||
| -rw-r--r-- | www/bt.html | 2 | ||||
| -rw-r--r-- | www/bu_303b.html | 2 | ||||
| -rw-r--r-- | www/compatibility.html | 129 | ||||
| -rw-r--r-- | www/excellence.html | 2 | ||||
| -rw-r--r-- | www/faq.html | 231 | ||||
| -rw-r--r-- | www/for-vendors.html | 2 | ||||
| -rw-r--r-- | www/future.html | 8 | ||||
| -rw-r--r-- | www/gps-hacking.html | 2 | ||||
| -rw-r--r-- | www/gypsy.html | 2 | ||||
| -rw-r--r-- | www/hacking.html | 25 | ||||
| -rw-r--r-- | www/hall-of-shame.html | 2 | ||||
| -rw-r--r-- | www/hardware-head.html | 2 | ||||
| -rw-r--r-- | www/history.html | 2 | ||||
| -rw-r--r-- | www/index.html.in | 10 | ||||
| -rw-r--r-- | www/protocol-transition.txt | 30 | ||||
| -rw-r--r-- | www/references.html | 2 | ||||
| -rw-r--r-- | www/upstream-bugs.html | 2 | ||||
| -rw-r--r-- | www/wishlist.html | 2 | ||||
| -rw-r--r-- | www/xgps-sample.html | 2 |
20 files changed, 53 insertions, 408 deletions
@@ -5,7 +5,7 @@ consequence, AIS is now fully supported in both daemon and client. Detection of end of a fix-reporting cycle is now reliable; accordingly data is accumulated from cycle start and the "J" - (nojitter) opoption on both server and client side is gone. We have + (nojitter) option on both server and client side is gone. We have abandoned the gpsflash subproject since it has become apparent that we can't do it without more vendor cooperation than we're likely to get. Increase major version of shared library due to significant API diff --git a/www/bt.html b/www/bt.html index 112228f7..83bcd303 100644 --- a/www/bt.html +++ b/www/bt.html @@ -29,7 +29,7 @@ Bluetooth and <code>gpsd</code> <a href="hardware.html">Hardware</a><br/> <a href="hacking.html">Hacker's Guide</a><br/> - <a href="compatibility">Application Compatibility</a> + <a href="protocil-transition.html">Application Compatibility</a> <a href="references.html">References</a><br/> <a href="history.html">History</a><br/> <a href="future.html">Future</a><br/> diff --git a/www/bu_303b.html b/www/bu_303b.html index 8a2765ce..dc8803ad 100644 --- a/www/bu_303b.html +++ b/www/bu_303b.html @@ -27,7 +27,7 @@ BU-303 GPS Receiver <a href="index.html#others">Other GPSDs</a><br/> <a href="hardware.html">Hardware</a><br/> <a href="hacking.html">Hacker's Guide</a><br/> - <a href="compatibility">Application Compatibility</a> + <a href="protocil-transition.html">Application Compatibility</a> <a href="references.html">References</a><br/> <a href="history.html">History</a><br/> <a href="future.html">Future</a><br/> diff --git a/www/compatibility.html b/www/compatibility.html deleted file mode 100644 index 6665c6a2..00000000 --- a/www/compatibility.html +++ /dev/null @@ -1,129 +0,0 @@ -<!doctype html public "-//w3c//dtd html 4.0 transitional//en"> -<html> -<head> - <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> - <meta name="Description" content="How to survive GPSD API changes"> - <meta name="Keywords" content="GPS, translator, GIS"> - <title>Application Compatibility</title> - <link rel="stylesheet" href="main.css" type="text/css"/> -</head> -<body> - -<div id="Header">Application Compatibility: Surviving GPSD API Changes</div> - -<div id="Menu"> - <img src="gpsd-logo-small.png"/><br /> - <a href="index.html">Home</a><br/> - <a href="index.html#news">News</a><br/> - <a href="index.html#downloads">Downloads</a><br/> - <a href="index.html#mailing-lists">Mailing lists</a><br/> - <a href="index.html#documentation">Documentation</a><br/> - <a href="faq.html">FAQ</a><br/> - <a href="xgps-sample.html">Screenshots</a><br/> - <a href="index.html#recipes">Recipes</a><br/> - <a href="index.html#others">Other GPSDs</a><br/> - <a href="hardware.html">Hardware</a><br/> - <a href="for-vendors.html">For GPS Vendors</a><br/> - <a href="hall-of-shame.html">Hall of Shame</a><br/> - Compatibility<br/> - <a href="hacking.html">Hacker's Guide</a><br/> - <a href="references.html">References</a><br/> - <a href="history.html">History</a><br/> - - <div> </div> - - <a href='http://www.catb.org/hacker-emblem/'><img - src='http://www.catb.org/hacker-emblem/glider.png' - alt='hacker emblem' /></a><br /> - - <hr/> - <script type="text/javascript"><!-- - google_ad_client = "pub-1458586455084261"; - google_ad_width = 160; - google_ad_height = 600; - google_ad_format = "160x600_as"; - google_ad_type = "text"; - google_ad_channel = ""; - //--></script> - <script type="text/javascript" - src="http://pagead2.googlesyndication.com/pagead/show_ads.js"> - </script> - <hr/> - - <a href="http://validator.w3.org/check/referer"><img - src="http://www.w3.org/Icons/valid-xhtml10" - alt="Valid XHTML 1.0!" height="31" width="88" /></a> -</div> -<div id="Content"> - -<p>A day is coming when the application interface of GPSD will have to -change in a major and incompatible way. This page explains why, and -what you as a GPS-aware application writer can do to be forward- and -backward-compatible when the day comes.</p> - -<h2>Why the disruption?</h2> - -<p>The design of the <a href="gpsd.html">request/response protocol</a> -that our client libraries use to talk to the daemon is inadequate. We -are nearly out of room to maneuver around the inadequacies, and fixing -them will require a major break with the past.</p> - -<p>The protocol design made sense under the cost constraints of the -mid-1990s when the earliest paleolithic versions of GPSD were first -written, but there are three specific problems with it that have grown -more pressing as the range of GPS-using applications has widened and -the daemon's command set has expaned to match:</p> - -<ol> -<li><p>Commands are single letters, and we have about run out of -letters. (This means there's no little or room left to extend the -command set.)</p></li> - -<li><p>There's no way to support returning multiline responses to a -client. (This is a problem for returning things like <a -href="http://gps.wva.net/html.common/rinex.html">RINEX</a> format, -which we'd like to be able to do when a device can report -pseudoranges.)</p> - -<li><p>The existing command set encourages sloppy handling of data -by supporting commands that return PVT and fix-quality information -in atomized partial form, without timestamps.</p> -</li> -</ol> - -<p>Client wrapper libraries like <a href="libgps.html">libgps</a> -seal off applications from most of the protocol level, but not -all of it. In particular, the second argument of -<code>gps_query()</code> is a protocol command string. Thus, -even if the coming transition doesn't change the libgps function-call -signatures in the API, client code will have to change.</p> - -<h2>Minimizing the impact</h2> - -<p>The first step to minimizing your exposure is this: <b>Don't talk -directly to GPSD.</b> Use one of the client libraries we ship -instead; we have one for C, one for Python, and there is a separately -distributed Net::GPSD for Perl. By not doing the response parsing -yourself, you'll avoid having huge amounts of code exposed to the -protocol change.</p> - -<p>Each set of client bindings will provide a major and minor -API revision-level symbol. The final major revision of the -old interface is 3; arguably it should actually 1, but we didn't have -a separate count for minor revisions until this transition was -into the planning stages.</p> - -<p>Use the API level to conditionalize your client code. In the best -case, all that will change is <code>gps_query()</code> argument -strings, but we're not sure of that yet.</p> - -</div> -<hr/> <script language="JavaScript" src="datestamp.js" -type='text/javascript'></script> -</body> -</html> -<!-- -Local Variables: -compile-command: "./upload hacking.html" -End: ---> diff --git a/www/excellence.html b/www/excellence.html index 550c326d..8e8d0709 100644 --- a/www/excellence.html +++ b/www/excellence.html @@ -29,7 +29,7 @@ GPSD and Code Excellence <a href="wishlist.html">Wish List</a><br/> <a href="hall-of-shame.html">Hall of Shame</a><br/> <a href="hacking.html">Hacker's Guide</a><br/> - <a href="compatibility">Application Compatibility</a> + <a href="protocol-transition.html">Application Compatibility</a> <a href="references.html">References</a><br/> <a href="history.html">History</a><br/> <a href="future.html">Future</a><br/> diff --git a/www/faq.html b/www/faq.html index 687ae507..e8828c38 100644 --- a/www/faq.html +++ b/www/faq.html @@ -30,7 +30,7 @@ GPSD Frequently Asked Questions <a href="wishlist.html">Wish List</a><br/> <a href="hall-of-shame.html">Hall of Shame</a><br/> <a href="hacking.html">Hacker's Guide</a><br/> - <a href="compatibility">Application Compatibility</a> + <a href="protocol-transition.html">Application Compatibility</a> <a href="references.html">References</a><br/> <a href="history.html">History</a><br/> <a href="future.html">Future</a><br/> @@ -65,21 +65,15 @@ GPSD Frequently Asked Questions <ul> <li><a href='#bug-reporting'>How do I report bugs in GPSD?</a><br/> <li><a href='#nodata'>I get no data from my GPS</a></h1> -<li><a href='#oldcommands'>Why does the first A,E,O,P,T,U, or V command to a device always return "?"</a><br/> <li><a href='#timelag'>Why does GPS time lag wall time by 11-15 seconds?</a></li> <li><a href="#singleshot">Why does my single-shot query fail to return fix data?</a><br/> <li><a href='#speed'>Why does my receiver report wildly fluctuating speed?</a><br/> <li><a href='#gpsdrive'>Why do I get implausibly low speeds when using gpsdrive?</a><br/> -<li><a href='#flicker'>Why does the date field in <code>xgps</code> flicker to "n/a" part of the time even when there's a fix?</a><br/> -<li><a href='#flicker'>Why does <code>xgps</code> flicker between displaying FIX and NOFIX about once a second?</a><br/> -<li><a href='#flicker'>Why doesn't <code>gpsd</code> set its J=1 option by default and avoid the flicker problem?</a><br/> <li><a href='#kismet'>Why do I get flaky results when I try to use <code>gpsd</code> with Kismet?</a><br/> <li><a href='#bluetooth'>Why do I have to restart <code>gpsd</code> whenever I power-cycle my Bluetooth device?</a><br/> <li><a href='#lockup'>My <code>gpsd</code> sometimes stops responding overnight</a><br/> -<li><a href='#why_migrate'>Why use this version of <code>gpsd</code>?</a><br/> <li><a href='#why_not_parse_nmea'>Why use the <code>gpsd</code> protocol rather than parsing raw NMEA?</a><br/> <li><a href='#interfacing'>How should I interface my application with <code>gpsd</code>?</a><br/> -<li><a href='#changes'>How has the <code>gpsd</code> interface changed since 1.x?</a><br/> <li><a href='#web'>How do I get gpsd data into a web page?</a><br/> </ul> @@ -305,46 +299,6 @@ command to it. Alternatively, running the daemon at -D 4 may reveal the version.</p> </blockquote> -<h1 id="oldcommands">Why does the first A,E,O,P,T,U, or V command to a device always return "?"</h1> - -<p>Note: These commands are now deprecated. The old command protocol -they are part of will be <a href="orotocol-transition.html">removed at -some time in the future</a>. If you rely on them, you will create -problems for yourself. Use one of the client libraries included with -<code>gpsd</code> to avoid problems.</p> - -<p>To understand what's going on, you need to know that -<code>gpsd</code> does not immediately assign a client a GPS from its -pool of known devices when the client connects. Rather, it waits -until the client issues a command that requires GPS information.</p> - -<p>The reason for this goes back to when multi-device support was -added in 2.21. In a multi-device world, what the client might want to -do is list available GPSes (with K) and choose one (with F). There is -also at least one other command, L, that doesn't require a GPS. And -in general, waiting until a GPS is really needed to wake one up is a -good idea — it saves power, which can be important because -GPS-equipped computers are more than likely running off a battery.</p> - -<p>So <code>gpsd</code> now defers binding the device. Your first -request for fix data triggers the action of binding a GPS to your -channel, but <em>at that time</em> no GPS is yet bound. The GPS -doesn't have a fix, so you get ?. But by the time of your -<em>next</em> request <code>gpsd</code> has polled the daemon and has -a fix.</p> - -<p>Generally only human beings testing <code>gpsd</code> via telnet/ssh -ever notice this behavior. <code>gpsd</code>-using applications poll the -daemon repeatedly; the delay before the second response comes in -normally is not noticeable.</p> - -<p>We haven't fixed this because the test clients and libgps all use -watcher mode. In watcher mode, you get 'O' updates whenever the GPS -ships a recognized sentence. The old-style individual requests are -obsolete, really; they were poorly thought out and are only retained -for backward compatibility. You should fix your application to use -watcher mode — or better yet, the libgps client library.</p> - <h1 id="nodata">I get no data from my GPS</h1> <p>This answer may apply if you have followed the Quick Start @@ -399,58 +353,6 @@ producing an accumulating stall. The symptom of this is sentence times that look right at startup but gradually fall behind clock time. To fix this, bump your speed to 9600 or higher.</p> -<h1 id="singleshot">Why does my single-shot query fail to return fix data?</h1> - -<p>Note: The new protocol does not support single-shot queries at all — -the race conditions associated wit them are intractable. You should -not rely on such commands. Use the new protcol, preferably through -a client libary, instead.</p> - -<p>This is closely related to the previous item.</p> - -<p>The old-style query commands such as P and A are are safe to use -with J=1 if you're polling repeatedly, but they're a dicey way to go -if you're opening a channel to <code>gpsd</code>, doing a single-shot -query, and then hanging up. Even repeating the query a few times -won't necessarily work.</p> - -<p>The problem is that your queries are in a race with the daemon's logic for -assigning and initializing a GPS. It won't try to assign a GPS to your -channel until the first command that demands actual device information.</p> - -<p>Then the race begins. The daemon will be interleaving reads of whatever -packet fragments the GPS is shipping with reads from your client -socket. It is entirely possible that the rest of your commands -will get processed before the daemon reads and processes enough GPS -sentences to get a fix — especially if the serial device is -slow and the GPS has a long initialization sequence.</p> - -<p>(A similar race existed in <code>gpsd</code> versions before -multi-device support was added in 2.21; if you issued a query too -soon after device open it would fail in exactly this way.)</p> - -<p>The right way to code your client is to set watcher mode and -read a couple of O responses before trying to parse one. That way -the daemon paces the action, actually telling the client when it -receives packets.</p> - -<p>To be certain of having full fix data, you'd need to wait for as -many O responses as there are sentences that set fix data in the -device's normal cycle. For SiRFs, one read will do because normally -only one sentence in the cycle ships fix data. For NMEA devices you -don't have a full fix before five reads, enough for an entire -GPRMC/GPGGA/GPVTG/GPGLL/GPGSV cycle in whatever permutation the device -ships it.</p> - -<p>In practice, three O reads will always be enough to get you -<em>some</em> fix information — worst case is your first O came -from a GPGSA and all you get is a mode, and then you get GPVTG, but -you'll always get lat/lon on the next O.</p> - -<p>Clients that poll P or A repeatedly won't have a problem; the race -effects will show up but be limited to noise in the first few seconds -of samples.</p> - <h1 id='speed'>Why does my receiver report wildly fluctuating speed?</h1> <p>If your problem is wildly fluctuating speed reports on a SiRF, @@ -467,53 +369,6 @@ similar solution.</p> <p>This is a gpsdrive bug, as you can verify by running <code>xgps</code> alongside it.</p> -<h1 id='flicker'>Why does the date field in <code>xgps</code> flicker -to "n/a" part of the time even when there's a fix?</h1> - -<p>The sentence or packet your GPS uses to report satellite -bearing/elevation has no timestamp. The <code>xgps</code> -date display flickers to "n/a" when it has just seen this report.</p> - -<p>This is a known problem. It's not a bug — or, at least, not -a bug in the GPSD code. Blame the idiot protocol designers who -saw fit not to timestamp their satellite-data packet. (NMEA and Garmin -GPSes don't. SiRF GPSes do. Score one for SiRF.)</p> - -<p><code>gpsd</code> is faithfully reporting the information it is -getting from the GPS, including the fact that the Y sentence contains -no date. That's its job. The libgps library is doing its bit by -passing everything from <code>gpsd</code> on to the client application -as it arrives, including the lack of date.</p> - -<p>The -j option of <code>xgps</code> will work around this problem. -It sends <code>gpsd</code> an initialization command that causes it -not to clear fix data at the beginning of each reporting cycle. This -will eliminate the flicker, but means that you may occasionally see -stale and invalid data.</p> - -<h1 id='flicker'>Why does <code>xgps</code> flicker between displaying FIX -and NOFIX about once a second?</h1> - -<p>It's the same problem as the previous entry, and can be banished -with the -j option.</p> - -<p>Other fields may flicker as well; latitude is especially prone to -this. Usually the problem only affects NMEA devices, so if you are -using something wuith a SiRF or other chipset that reports in a -non-NMEA format you will never see it.</p> - -<h1 id='flicker'>Why doesn't <code>gpsd</code> set its J=1 option by -default and avoid the flicker problem?</h1> - -<p>Because that's policy, and policy is really the client's job. We -choose to make <code>gpsd</code> report what the GPS tells it as -faithfully as it can without making assumptions about how the client -wants to use the data.</p> - -<p>The design issues here are much thornier than they at first appear. -See <a href="hacking.html#buffering">this extended discussion</a> in -the <a href="hacking.html">Hacker's Guide</a>.</p> - <h1 id='kismet'>Why do I get flaky results when I try to use <code>gpsd</code> with Kismet?</h1> <p>Kismet's interface was designed for a much older version of @@ -570,52 +425,10 @@ brought on by lots of I/O activity.</p> <p>Another thing to try is running <code>gpsd</code> under Valgrind overnight and seeing if it reports any leaks.</p> -<h1 id='why_migrate'>Why use this version of <code>gpsd</code>?</h1> - -<p>If you have written a <code>gpsd</code>-aware application using one -of the old 1.x versions, or a fork such as <code>ngpsd</code> or -<code>tgpsd</code>, here are some good functional reasons to migrate -to 2.0:</p> - -<ol> -<li>The new version supports AIS as well as GPS receivers.</li> - -<li>Hotplug- and reconnect support. Your application does not have to be -aware of GPS device connects and disconnects, but can choose to be by -watching for X commands.</li> - -<li>Your application can now query whether or not the GPS is online -and get an authoritative answer.</li> - -<li>Timestamps are now no longer truncated to seconds, but reported to -whatever resolution the GPS ships. Often (notably on SiRF-II GPSes) -this is milliseconds.</li> - -<li>There is a "watcher" mode. It is like raw mode in that the -GPS streams updates at you, but unlike it in that the updates are in -the simpler GPSD format rather than the more complex NMEA one.</li> - -<li>The daemon now automatically tries to reconnect to the GPS once -a second when it is offline but clients are connected.</li> - -<li>Writes to clients are nonblocking, so new <code>gpsd</code> cannot -be stalled by a wedged client.</li> - -<li>The code in the new version has been carefully audited for quality, -static-checked using <a href='http://www.splint.org'>splint</a>, and -is regression-tested before every release.</li> - -<li>It took us two years of hard work, but as of late 2006 -<code>gpsd</code> dominates its application niche so completely that -every competitor we knew of in 2004 has been abandoned by its own -maintainers in our favor. The 1.x versions or any fork you use won't -be getting any future maintenance.</li> -</ol> - <h1 id='why_not_parse_nmea'>Why use the <code>gpsd</code> protocol rather than parsing raw NMEA?</h1> -<p>Some applications that use <code>gpsd</code> start raw mode with -the 'r' command and parse the NMEA directly. This is not a good idea.</p> +<p>Some applications that use <code>gpsd</code> start raw mode +and parse the NMEA directly. This is not a good idea.</p> <p>One problem with raw mode is that NMEA is a poorly specified standard. There are, for example, two different and incompatible @@ -639,7 +452,7 @@ same sorts of computation that more capable GPSes use.</p> <h1 id='interfacing'>How should I interface my application with <code>gpsd</code>?</h1> <p>The <code>gpsd</code> package provides two ways for C code to get -data from a GPS or AIS rceiver. Both go through the libgps.a library, +data from a GPS or AIS receiver. Both go through the libgps.a library, which supports two sets of entry points. The <a href="libgpsd.html">low-level interface</a> talks directly to the GPS. The <a href="libgps.html">high-level interface</a> communicates with @@ -664,42 +477,6 @@ build from source that conditions out all but one of the drivers.</p> <p>For Python programmers, there is a gps.py module the high-level interface. It exports a class that encapsulates a GPS session.</p> -<h1 id='changes'>How has the <code>gpsd</code> interface changed since 1.x?</h1> - -<p>Note: This section describes evolutionary changes in the old -1.x-2.x protocol. This protocol is now deprecated; while still -supported for backward compatibility, it will be removed in the -future. You should be using the new JSON-based protocol. preferably -through one of our client libraries.</p> - -<p>There are three minor incompatibilities with <code>gpsd</code> 1.x:</p> - -<p>First, <code>gpsd</code>-2's command-line options have been changed -and simplified. If your <code>gpsd</code>-using application is -starting up <code>gpsd</code> directly you may find you have to modify -the invocation. However, we don't recommend this. New -<code>gpsd</code> is designed to be started by hotplug scripts when -a USB device wakes up, or started at boot time and run -continuously just like any normal daemon. It will do nothing, and be -swapped out, unless there are clients trying to query the GPS.</p> - -<p>Second, <code>gpsd</code> now returns "?" as the contents for a -field when it doesn't have valid data for that field (e.g. latitude -or longitude before the first fix). This is only an issue if you are -interpreting GPSD responses yourself rather than using libgps.a or the -gps.py Python module.</p> - -<p>Third, the format of the timestamp returned by the D command has -changed, from "%m/%d/%Y %H:%M:%S" to ISO-8601: "%Y-%m-%dT%H:%M:%SZ". -No more U.S.-centric date-format assumptions! Also, as previously -noted, the seconds part may have one or more digits of decimal fractional -seconds.</p> - -<p>The protocol and API around <code>gpsd</code> will need to change -again in the future. See <a href="compatibility.html">this -compatibility page</a> for explanation, and for advice on how to -minimize your exposure to the change.</p> - <h1 id='web'>How do I get gpsd data into a web page?</h1> <p>The <code>gpsd</code> source-code distribution now includes a PHP diff --git a/www/for-vendors.html b/www/for-vendors.html index 2a5b8164..b0f2ca37 100644 --- a/www/for-vendors.html +++ b/www/for-vendors.html @@ -30,7 +30,7 @@ GPSD Welcomes Vendor Cooperation <a href="wishlist.html">Wish List</a><br/> <a href="hall-of-shame.html">Hall of Shame</a><br/> <a href="hacking.html">Hacker's Guide</a><br/> - <a href="compatibility">Application Compatibility</a> + <a href="protocol-transition.html">Application Compatibility</a> <a href="references.html">References</a><br/> <a href="history.html">History</a><br/> <a href="future.html">Future</a><br/> diff --git a/www/future.html b/www/future.html index c1625b90..46ac4b9f 100644 --- a/www/future.html +++ b/www/future.html @@ -31,7 +31,7 @@ Future of the GPS project <a href="hall-of-shame.html">Hall of Shame</a><br/> <a href="hacking.html">Hacker's Guide</a><br/> <a href="references.html">References</a><br/> - <a href="compatibility">Application Compatibility</a> + <a href="protocol-transition.html">Application Compatibility</a> <a href="history.html">History</a><br/> Future<br/> @@ -64,8 +64,7 @@ Future of the GPS project <h2>The new GPSD protocol</h2> -<p>As of mid-September 2009, we are wrapping up a three-month siege of -intense work on a top-to-bottom redesign of GPSD's wire protocol. +<p>2.90 has shipped, and with it the redesign of GPSD's wire protocol. While this brings many benefits (including, immediately, the ability to interpret and report on the output of marine AIS receivers) it poses some significant deployment challenges as well.</p> @@ -75,9 +74,6 @@ poses some significant deployment challenges as well.</p> new protocol.</a>. Here is our tentative release schedule:</p> <dl> -<dt>2.90 — 4 December</dt> -<dd><p>New client API freezes. Wire protocol still considered unstable.</p></dd> - <dt>2.91 — Before end of January 2010</dt> <dd><p>Wire protocol freezes (no incompatible changes going forward from this point). Old protocol support will be removed from the daemon, but diff --git a/www/gps-hacking.html b/www/gps-hacking.html index 5d843502..e34e136e 100644 --- a/www/gps-hacking.html +++ b/www/gps-hacking.html @@ -29,7 +29,7 @@ ESR's Guide to Hacking With GPS <a href="for-vendors.html">For GPS Vendors</a><br/> <a href="wishlist.html">Wish List</a><br/> <a href="hacking.html">Hacker's Guide</a><br/> - <a href="compatibility">Application Compatibility</a> + <a href="protocol-transition.html">Application Compatibility</a> <a href="references.html">References</a><br/> <a href="history.html">History</a><br/> <a href="future.html">Future</a><br/> diff --git a/www/gypsy.html b/www/gypsy.html index e88f642e..97c3b408 100644 --- a/www/gypsy.html +++ b/www/gypsy.html @@ -26,7 +26,7 @@ <a href="for-vendors.html">For GPS Vendors</a><br/> <a href="hall-of-shame.html">Hall of Shame</a><br/> <a href="hacking.html">Hacker's Guide</a><br/> - <a href="compatibility">Application Compatibility</a> + <a href="protocol-transition.html">Application Compatibility</a> <a href="references.html">References</a><br/> <a href="history.html">History</a><br/> <a href="future.html">Future</a><br/> diff --git a/www/hacking.html b/www/hacking.html index ca541706..eb23de03 100644 --- a/www/hacking.html +++ b/www/hacking.html @@ -26,7 +26,7 @@ <a href="for-vendors.html">For GPS Vendors</a><br/> <a href="hall-of-shame.html">Hall of Shame</a><br/> Hacker's Guide<<br/> - <a href="compatibility">Application Compatibility</a> + <a href="protocol-transition.html">Application Compatibility</a> <a href="references.html">References</a><br/> <a href="history.html">History</a><br/> <a href="future.html">Future</a><br/> @@ -1139,20 +1139,12 @@ logfile format.</p> portion during which the GPS has no fix, a portion during which it has a fix but is stationary, and a portion during which it is moving.</p> -<h1 id="designahead">GPSD-NG, the Next-Generation GPSD Protocol</h1> +<h1 id="designahead">Future Protocol Directions</h1> -<p>There are almost no more letters left in the namespace of the GPSD -version 3 protocol. As early as 2006 we had only one more -command left, 'h', and that was it. We knew that that, extending the set would -require a new command/response syntax. Some posts in the dev-list -archive refer to this as "Version 4", but GPSD-NG got implemented. -well before that major version level was reached </p> +<p>The new protocol based on <a href="http://www.json.org/">JSON</a> +(JavaScript Object Notation) shipped in 2.90.</a> -<p>The new protocol has now been implemented and is in testing. It is -based on <a href="http://www.json.org/">JSON</a> (JavaScript Object -Notation).</a> - -<p>The major virtue of JSON is its extensibility. There are +<p>A major virtue of JSON is its extensibility. There are <em>lots</em> of other things a sensor wedded to a GPS might report that don't fit the position-velocity-time model of the oldstyle O report. Depth of water. Temperature of water. Compass heading. Roll. @@ -1160,11 +1152,8 @@ Pitch. Yaw. We've already had requests to handle some of these for NMEA-emitting devices like magnetic compasses (which report heading via a proprietary TNTHTM sentence) and fish finders (which report water depth and temperature via NMEA DPT and MTW sentences). JSON -gives a natural way to add ad-hoc fields.</p> - -<p>The '{' introducer on JSON responses serves to distinguish -them from old-style responses that effectively have 'GPSD,' as an -introducer. +gives a natural way to add ad-hoc fields, and we expect to +explot that in the future.</p> <h2>Proposed sentences:</h2> diff --git a/www/hall-of-shame.html b/www/hall-of-shame.html index c3351a05..bfcfd473 100644 --- a/www/hall-of-shame.html +++ b/www/hall-of-shame.html @@ -29,7 +29,7 @@ GPS Hall of Shame <a href="wishlist.html">Wish List</a><br/> Hall of Shame</br> <a href="hacking.html">Hacker's Guide</a><br/> - <a href="compatibility">Application Compatibility</a> + <a href="protocol-transition.html">Application Compatibility</a> <a href="references.html">References</a><br/> <a href="hardware.html">Hardware</a><br/> <a href="history.html">History</a><br/> diff --git a/www/hardware-head.html b/www/hardware-head.html index 7f0ae90f..ee32fb9f 100644 --- a/www/hardware-head.html +++ b/www/hardware-head.html @@ -27,7 +27,7 @@ <a href="wishlist.html">Wish List</a><br/> <a href="hall-of-shame.html">Hall of Shame</a><br/> <a href="hacking.html">Hacker's Guide</a><br/> - <a href="compatibility">Application Compatibility</a> + <a href="protocol-transition.html">Application Compatibility</a> <a href="references.html">References</a><br/> <a href="history.html">History</a><br/> <a href="future.html">Future</a><br/> diff --git a/www/history.html b/www/history.html index 96310597..7c90eca9 100644 --- a/www/history.html +++ b/www/history.html @@ -30,7 +30,7 @@ A Brief History of GPSD <a href="wishlist.html">Wish List</a><br/> <a href="hall-of-shame.html">Hall of Shame</a><br/> <a href="hacking.html">Hacker's Guide</a><br/> - <a href="compatibility">Application Compatibility</a> + <a href="protocol-transition.html">Application Compatibility</a> <a href="references.html">References</a><br/> <a href="future.html">Future</a><br/> History<br/> diff --git a/www/index.html.in b/www/index.html.in index 76146d28..8aef01e6 100644 --- a/www/index.html.in +++ b/www/index.html.in @@ -33,7 +33,7 @@ <a href="hall-of-shame.html">Hall of Shame</a><br/> <a href="hacking.html">Hacker's Guide</a><br/> <a href="references.html">References</a><br/> - <a href="compatibility">Application Compatibility</a> + <a href="protocol-transition.html">Application Compatibility</a> <a href="history.html">History</a><br/> <a href="future.html">Future</a><br/> @@ -66,10 +66,10 @@ <h1 id='news'>Urgent news for maintainers of <code>gpsd</code> clients</h1> -<p>We've been warning it was coming for years, and it's here: the -request/response protocol used by <code>gpsd</code> is about to change -in ways that will break your application if you're not careful. The -old protocol is still supported, but will remain so only for a very +<p>We've been warning it was coming for years, and it's here: in 2.90, +the request/response protocol used by <code>gpsd</code> has changed in +ways that will break your application if you're not careful. The old +protocol is still supported, but will remain so only for a very limited time. Read <a href="protocol-transition.html">"Moving to GPSD-NG: a Guide for Client Developers"</a> to find out why this is happening and what you need to do about it.</p> diff --git a/www/protocol-transition.txt b/www/protocol-transition.txt index e38ca805..ca2f595a 100644 --- a/www/protocol-transition.txt +++ b/www/protocol-transition.txt @@ -1,10 +1,10 @@ = Moving to GPSD-NG: a Guide for Client Developers = Eric S. Raymond <esr@thyrsus.com> -v1.2, November 2009 +v1.3, December 2009 == Why a new protocol? == -GPSD is moving to a new request/response protocol. This move has been +GPSD has moved to a new request/response protocol. This move has been forced upon us because the old one ran out of namespace. It was designed with case-insensitive single-character command/response codes. 25 of 26 ASCII alphabetics were already in use by 2006, and @@ -19,13 +19,25 @@ line noise and only delayed the day of reckoning. Instead, we've written a new protocol that is upward-compatible with the old one in that you can mix old and new syntax. -The old protocol will continue to be available for some time, but not -indefinitely. Eventually we're going to want to shed the code -complexity and overhead of maintaining both protocols at once. This -will happen sooner than it otherwise might have because gpsd is in -part targeted for SBCs and other constrained environments where -shaving a few K off the runtime image can actually matter. When -it comes to keeping the codebase lean and mean, we try harder. +There were other problems as well. The old command set encouraged +sloppy handling of data by supporting commands that return PVT and +fix-quality information in atomized partial form, without +timestamps. + +There was also no way to support returning more than single-line +responses to a client. This is a problem for returning things like <a +http://gps.wva.net/html.com[RINEX] format, which we'd like to be able +to do when a device can report pseudoranges. + +The old protocol will continue to be available until the 2.91 release, +but that's not far in the future; it coould be removed from the +development sources a t any time, and may already have been when you +read this. Eventually we're going to want to shed the code complexity +and overhead of maintaining both protocols at once. This will happen +sooner than it otherwise might have because gpsd is in part targeted +for SBCs and other constrained environments where shaving a few K off +the runtime image can actually matter. When it comes to keeping the +codebase lean and mean, we try harder. We'll try to make the transition easy, but we cannot guarantee no problems. The sooner you start adapting your code, the less pain you diff --git a/www/references.html b/www/references.html index 3ecb9c3b..54c0486a 100644 --- a/www/references.html +++ b/www/references.html @@ -27,7 +27,7 @@ <a href="wishlist.html">Wish List</a><br/> <a href="hall-of-shame.html">Hall of Shame</a><br/> <a href="hacking.html">Hacker's Guide</a><br/> - <a href="compatibility">Application Compatibility</a> + <a href="protocol-transition.html">Application Compatibility</a> References<br/> <a href="history.html">History</a><br/> <a href="future.html">Future</a><br/> diff --git a/www/upstream-bugs.html b/www/upstream-bugs.html index a0d8f468..b11ea6c4 100644 --- a/www/upstream-bugs.html +++ b/www/upstream-bugs.html @@ -24,7 +24,7 @@ <a href="for-vendors.html">For GPS Vendors</a><br/> <a href="hall-of-shame.html">Hall of Shame</a><br/> <a href="hacking.html">Hacker's Guide</a><br/> -<a href="compatibility">Application Compatibility</a> +<a href="protocol-transition.html">Application Compatibility</a> <a href="references.html">References</a><br/> <a href="history.html">History</a><br/> <a href="future.html">Future</a><br/> diff --git a/www/wishlist.html b/www/wishlist.html index 64865e2e..dfa542ce 100644 --- a/www/wishlist.html +++ b/www/wishlist.html @@ -28,7 +28,7 @@ Wiahlist<br/> <a href="hall-of-shame.html">Hall of Shame</a><br/> <a href="hacking.html">Hacker's Guide</a><br/> <a href="references.html">References</a><br/> -<a href="compatibility">Application Compatibility</a> +<a href="protocol-transition.html">Application Compatibility</a> <a href="history.html">History</a><br/> <a href="future.html">Future</a><br/> <div> </div> diff --git a/www/xgps-sample.html b/www/xgps-sample.html index 145db54a..53e590d4 100644 --- a/www/xgps-sample.html +++ b/www/xgps-sample.html @@ -30,7 +30,7 @@ The xgps client <a href="wishlist.html">Wish List</a><br/> <a href="hall-of-shame.html">Hall of Shame</a><br/> <a href="hacking.html">Hacker's Guide</a><br/> - <a href="compatibility">Application Compatibility</a> + <a href="protocol-transition.html">Application Compatibility</a> <a href="history.html">History</a><br/> <div> </div> |