diff options
author | Eric S. Raymond <esr@thyrsus.com> | 2009-07-09 23:27:16 +0000 |
---|---|---|
committer | Eric S. Raymond <esr@thyrsus.com> | 2009-07-09 23:27:16 +0000 |
commit | 36d0da63fc37d1724775797ac7a9eae78c5086f4 (patch) | |
tree | 744e1038b5fbda4ffa93d41ff53ed6e2b6d319ab /www | |
parent | 92938e4782c82af08e4ffda40af291c0dc2f1d98 (diff) | |
download | gpsd-36d0da63fc37d1724775797ac7a9eae78c5086f4.tar.gz |
Define a configuratrion switch for NG protocol support.
Bring the Hacking Guide description (mostly) up to date.
Diffstat (limited to 'www')
-rw-r--r-- | www/hacking.html | 144 |
1 files changed, 52 insertions, 92 deletions
diff --git a/www/hacking.html b/www/hacking.html index 986e16ac..4475ede0 100644 --- a/www/hacking.html +++ b/www/hacking.html @@ -1385,48 +1385,7 @@ reports. This is a problem; in general, we can't assume that a gpsd instance running in a car or boat will have access to <code>ntpd</code> or NIST radio time signals.</p> -<h1 id="designahead">Designing Ahead</h1> - -<p>This section is preliminary design sketches for things we are -likely to need to do in the future.</p> - -<h2 id="nonpvt">Non-TPV Data</h2> - -<p>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 O -report. Depth of water. Temperature of water. Compass heading. -Roll. 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).</p> - -<p>To cope with this, we could either:</p> - -<ol> -<li>extend the O tuple to report non-TPV kinds of information, or</li> -<li>define a new set of requests and responses for non-TPV data.</li> -</ol> - -<p>The simplest way to attack this problem would be to just start adding -fields to the O response for each new kind of data we get asked to -handle. The problem with this is that we could pile up fields forever -and end up with a monstrously long report most of the fields of -which are always '?' and some of which are the moral equivalent of -"count of the nose hairs on the nearest warthog".</p> - -<p>There's a slightly more civilized possibility. We could add -optional private-use fields to the O report, the semantics of which -would be allowed to vary by device. So, for example, the Hummingbird -would return water depth in the first private-use field, while the TNT -would return heading. Clients would have to know, based on the device -type as revealed by I, how to interpret and label the data in the -private-use fields.</p> - -<p>If we go for alternative (2), the first consequence is that we -actually have to implement a next-generation protocol. The existing GPSD -protocol is about out of namespace.</p> - -<h2 id="protov4">Design Sketch for GPSD-NG, the Next-Generation GPSD Protocol</h2> +<h1 id="designahead">Design Sketch for GPSD-NG, the Next-Generation GPSD Protocol</h1> <p>There are almost no more letters left in the namespace of the GPSD version 3 protocol. At time of writing in late 2006 we can have one @@ -1435,15 +1394,19 @@ require a new command/response syntax. Some posts in the dev-list archive refer to this as "Version 4", but that is a rev level we may or may not reach before GPSD-NG has to be implemented.</p> -<p>Steps towards defining a new syntax have been taken. The senior -developers have agreed on a new protocol with a basic sentence syntax -like this: +<p>Steps towards defining and implementing a new syntax have been +taken. The new protocol is based on <a +href="http://www.json.org/">JSON</a> (JavaScript Object Notation).</a> -<pre> -<request> ::= <introducer> <commands> <newline> - -<command> ::= <command-id>=<arg1>,<arg2>,<arg3>,...<argn>; -</pre> +<p>The 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. +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>Each request shall begin with an introducer character, '?'. The purpose of the introducer is to inform the command parser that @@ -1457,29 +1420,16 @@ newline.</p> <p>Each command shall begin with a command identifier. The command identifier shall begin with an alphabetic character and consist of -alphanumeric characters. It shall be followed by an equal sign. The -52 command identifiers consisting of a single alphabetic are -reserved equivalents of the old-style GPSD commands. Command -identifiers are case-insensitive.</p> - -<p>The equal sign may be followed by zero or more comma-separated -arguments. Arguments may contain any US-ASCII character other than -the introducer character, the equal sign, the comma, or the hash '#' -character (reserved for comments).</p> - -<p>If the final argument of a command has a newline immediately after -a leader equal-sign or separator comma, the content of the argument is a -multiline continuation. If a continuation line begins with a '.', -that '.' is removed before interpretation. The content of the -argument consists of all following lines until a line which is empty -after '.' (e.g. a line consisting solely of the argument terminator -'.' and a LF or CR-LF).</p> +alphanumeric characters. It shall be followed by either an equal sign +or a line termination (CR-LF or LF).The equal sign, if present, mudt +be followed by a legal JSON object.</p> <p>Responses shall have the same format as requests, except that -responses have the introducer '!'. The response to a command shall -have the same identifier as the command.</p> +responses have the introducer '!' and the length limit is 1024 +characters. The response to a command shall have the same identifier +as the command.</p> -<h3>Syntax Examples:</h3> +<h2>Syntax Examples:</h2> <pre> # GPSD-NG equivalent of X query request; no arguments @@ -1489,13 +1439,6 @@ have the same identifier as the command.</p> # GPSD-NG equivalent of B request to set baud rate ?b=9600 !b=9600 -# -# Hypothetical extended command with a multiline response -?id -!id= -This is a Foobar 2317 GPS -Firmware revision 555.55 -. </pre> <p>Here's a longer example. Note that this is a far more complex @@ -1508,14 +1451,12 @@ they'll just say ?WATCH=+TPV+SKY+STATUS and be done.</p> # and one RTCM3 correction source. The fields are full name, # service type, and name tag, -> ?DEVICES --> !DEVICES= -/dev/ttyUSB0,GPS,GPS#1 -/dev/ttyUSB1,AIS,AIS#1 -/dev/ttyS0,RTCM3,RTCM3#1 -. +-> !DEVICES=[{"device":"/dev/ttyUSB0","class":"GPS","id":"GPS#1"}, + {"device":"/dev/ttyUSB1","class":"AIS","id":"AIS#1"}, + {"device":"/dev/ttyS0","class":"RTCM3","id":"RTCM3#1"}] # # Client asks the GPS to identify itself. --> ?ID=GPS#1 +-> ?ID="GPS#1" <- !ID=GPS#1,GPS,SiRF,231.000.000ES-01-39 # # Client subscribes to TPV, SKY, and STATUS reports from the GPS. @@ -1524,26 +1465,45 @@ they'll just say ?WATCH=+TPV+SKY+STATUS and be done.</p> <- !WATCH=GPS#1,+TPV+SKY+STATUS # # Daemon begins to stream TPVs (like our O report) and SKYs (like Y) -<- !TPV=GPS#1,MID2,1119197561.890,0.005,46.498203637,7.568074350,1327.780,21.000,124.484,0.0000,0.000,0.000,?,23.56,?,3 -<- !SKY=GPS#1,MID4,1119197562.890,7:10,45,196,34,1:29,67,310,40,1:28,59,108,42,1:26,51,304,43,1:8,44,58,41,1:27,16,66,39,1:21,10,301,0,0: -<- !TPV=GPS#1,MID2,1119197563.890,0.005,46.498208969,7.568087260,1328.596,21.000,124.484,190.3797,0.091,0.085,?,23.60,?,3 -<- !TPV=GPS#1,MID2,1119197564.890,0.005,46.498215161,7.568087260,1329.321,21.000,124.484,0.0000,0.086,0.091,?,23.53,?,3 -<- !TPV=GPS#1,MID2,1119197565.890,0.005,46.498221628,7.568088976,1328.639,21.000,124.484,0.0000,0.086,0.091,?,23.56,?,3 +# Whitespace between togens is not significant in JSON. +<- !TPV={"device":"GPS#1","tag":"MID2","time":1119197561.890, + "lon":46.498203637,"lat":7.568074350,"alt":1327.780,"eph":21.000, + "epv":124.484,"mode":3} +<- !SKY={"device":"GPS#1","tag":"MID4","time":1119197562.890,"reported":7 + "satellites": + {"PRN":10,"el":45,"az":196,"ss":34,"used":1} + {"PRN":29,"el":67,"az":310,"ss":40,"used":1} + {"PRN":28,"el":59,"az":108,"ss":42,"used":1} + {"PRN":26,"el":51,"az":304,"ss":43,"used":1} + {"PRN":8,"el":44,"az":58,"ss":41,"used":1} + {"PRN":27,"el":16,"az":66,"ss":39,"used":1} + {"PRN":21,"el":10,"az":301,"ss":0,"used":0}] +<- !TPV={"device":"GPS#1","tag":"MID2","time":1119197563.890, + "lon":46.498208969,"lat":7.568087260,"alt":1328.596, + "eph":21.000,"epv":124.138,"mode":3} +<- !TPV={"device":"GPS#1","tag":"MID2","time":1119197564.890, + "lon":46.498215161,"lat":7.568087260,"alt":1329.321, + "eph":21.000,"epv":124.483,"mode":3} +<- !TPV={"device":"GPS#1","tag":"MID2","time":1119197565.890," + lon":46.498221628,7"lat":.568088976,"alt":1328.639, + "eph":21.000,"epv":124.484,"mode":3} # # Client subscribes to Type 1 AIS reports. To subscribe to all # reports from a device, we would omit the type argument. -> ?WATCH=AIS#1,+1 <- !WATCH=AIS#1,+1 # -# Daemon begins to stream AIVDM Type 1 reports +# Daemon begins to stream AIS Type 1 reports # Fields are: device, message type, timestamp, MMSI, navigation status, # ROT, SOG, position accuracy, longitude, latitude, COG, and true heading. -!AIS=AIS#1,TYPE1,1119197565.890,371798000,0,?,12.3,1,-123.395383333,48.38163333333,224,215 +!AIS={"device=":"AIS#1","type":1,"time":1119197565.890,"mmsi":371798000, + "sec":0,"rot":12.3,"speed":-123,"accuracy":true,"lon":395383333, + "lat":48.38163333333,"course":224,"heading":215} </pre> <p> -<h3>Rationale:</h3> +<h2>Rationale:</h2> <p>The purpose of the introducer is to permit old-style and new-style commands to be mixed in the same session. Most of the rest of the NG @@ -1560,7 +1520,7 @@ requests as for responses. This is so we can keep the 78-character line limit while allowing the daemon to pass back more data than can fit on a line.</p> -<h3>Proposed sentences:</h3> +<h2>Proposed sentences:</h2> <p>Chris Kuethe has floated the following list requests for discussion:</p> |