bertos/net/nmeap/doc/tutorial.html

   1 <html>\r
   2 <body>\r
   3 <h1>NMEAP TUTORIAL AND REFERENCE</h1>\r
   4 <hr />\r
   5 <pre>\r
   6 copyright (c) 2005 David M. Howard\r
   7 This work is licensed under the Creative Commons Attribution License.\r
   8 To view a copy of this license, visit\r
   9 http://creativecommons.org/licenses/by/2.0/ or send a letter to\r
  10 Creative Commons, 559 Nathan Abbott Way, Stanford, California 94305,USA\r
  11 You are free:\r
  12     * to copy, distribute, display, and perform the work\r
  13     * to make derivative works\r
  14     * to make commercial use of the work\r
  15 Under the following conditions:\r
  16 Attribution. You must give the original author credit.\r
  17     * For any reuse or distribution, you must make clear to others the\r
  18       license terms of this work.\r
  19     * Any of these conditions can be waived if you get permission from\r
  20       the author.\r
  21 </pre>   \r
  22 <hr />\r
  23 <h2>Table Of Contents</h2>\r
  24 <ol>\r
  25 <li><a href="#c1">Installing the Source Code</a></li>\r
  26 <li><a href="#c2">Building the Library</a></li>\r
  27 <li><a href="#c3">Description and Examples</a></li>\r
  28 <li><a href="#c4">API Documentation</a></li>\r
  29 </ol>\r
  30 <a name="c1">&nbsp;</a>\r
  31 </a><h2>1. Installing the source code</h2>\r
  32 Get the source code from <a href="http://sourceforge.net/projects/nmeap/">NMEAP at sourceforge.net</a>\r
  33 <pre>\r
  34 \r
  35 Linux:\r
  36         expand the tarball to a directory of your choice.\r
  37         >tar --gzip -xf [tarball name]\r
  38         >cd [nmeap...]\r
  39         \r
  40 Windows:\r
  41         use Winzip to unzip the zipfile to a directory of your choice\r
  42         \r
  43 </pre>\r
  44 \r
  45 <a name="c2">&nbsp;</a>\r
  46 <h2>2. Building the library </h2>\r
  47 <pre>\r
  48 \r
  49 Linux:\r
  50         >cd [working directory]\r
  51         >make\r
  52         This builds a static library named libnmeap.a in the 'lib' directory. there is no option for a dynamic library. \r
  53         This thing is so small that it isn't worth the trouble. It also builds the test/examples programs in\r
  54         'tst'.\r
  55         \r
  56 Windows:\r
  57         >cd [working directory]\r
  58         >nmake -f win32.mak\r
  59         Again, this builds a static library names libnmeap.lib in the 'lib' direcotry, plus the test programs in 'tst'\r
  60 </pre>\r
  61 <a name="c3">&nbsp;</a>\r
  62 <h2>3. Description and Examples</h2>\r
  63 <p>The NMEA-0183 standard specifies how the output is formatted for GPS data output, usually on a serial port. The data \r
  64 consists of 'sentences' delimited by CR/LF end of line markers. A lot has been written about the format, so this document\r
  65 won't cover the specifics. A good place to start is the <a href="http://vancouver-webpages.com/peter/nmeafaq.txt">NMEA FAQ</a> \r
  66 maintained by Peter Bennett.</p> \r
  67 <p>NMEAP is an extensible C language parser library that takes NMEA sentences as input and spits out the decoded data as output. You link\r
  68 NMEAP in to your application, set it up, initialize it and feed it bytes. It signals you when it has found a complete valid sentence and \r
  69 provides the parsed out data to you. Parsing NMEA-0183 is pretty easy but it has a few tricky bits. The value of NMEAP is not that it is\r
  70 rocket science to write an NMEA parser, but that it provides a relatively efficient implementation that works, along with an\r
  71 extension framework to add more sentence parsers without hacking the base source code.</p>\r
  72 <p>An NMEA 'sentence' has the following format:</p>\r
  73 <pre>\r
  74         $name,data1,data2,...,dataN*XX[CR/LF]\r
  75         OR\r
  76         $name,data1,data2,...,dataN[CR/LF]\r
  77         \r
  78 where\r
  79         header       := a 5 digit sentence identifier. all ASCII upper case. e.g. GPGGA\r
  80         data1..dataN := some number of data elements, all ASCII numbers or letters, in all kinds of weird formats.\r
  81                     fields can be empty, in which case 2 commas will be side by side.\r
  82                     normally data fields are identified by their position in the sentence. \r
  83         *XX          := a '*' plus two ASCII hex digits of checksum. this field is optional.\r
  84         [CR/LF]      := end of line is terminated by a carriage return/linefeed pair.\r
  85         \r
  86 example from the <a href="http://vancouver-webpages.com/peter/nmeafaq.txt">NMEA FAQ</a>:\r
  87         $GPGGA,123519,4807.038,N,01131.324,E,1,08,0.9,545.4,M,46.9,M,,*42\r
  88 </pre>  \r
  89 <p>The NMEAP parser works as follows:\r
  90 <ol>\r
  91         <li>the application sets up the parser and specifies which sentences are to be parsed\r
  92                 and what is to be done with the output data from the parser.</li>\r
  93         <li>the application reads raw bytes from its IO device and passes the bytes to the parser,\r
  94                 either byte by byte or as a buffer/length pair.</li>\r
  95         <li>nmeap:\r
  96         <ul>\r
  97                 <li>runs the input bytes through a lexical scanner that recognizes complete and valid sentences</li>\r
  98                 <li>when a sentence is recognized, a second lexical scanner divides the sentence into discrete tokens.</li>\r
  99                 <li>the name field is matched internally to a sentence parser for that name</li>\r
 100                 <li> the sentence parser picks out the data strings and decodes them into an nmeap or user \r
 101                 defined data structure  with normal data types such as integer, float, double etc. </li>\r
 102                 <li>notifies the client application that a sentence was found and decoded, either thru a callout \r
 103                 to an event handler (ala Expat) or via a return code and a shared data structure, or both.</li>\r
 104         </ul>\r
 105         </li>\r
 106 </ol>\r
 107 <h4>Sentence Parsers</h4>\r
 108 <p>Most of the work in NMEAP is done by the sentence parsers. Each type of NMEA sentence string has an associated parser. NMEAP provides\r
 109 standard ones, and the user can add more in a systematic way.\r
 110 The sentence parser is responsible for knowing the token position of the data elements and whatever format they \r
 111 are in. There are functions in nmeap to decode standard data element formats. If something is nonstandard, \r
 112 the sentence parser decodes it. Each sentence parser has a 'struct' type associated with it\r
 113 that the decoded data gets poked into an instance of that data structure, which is provided by the client application when nmeap is set\r
 114 up.</p>\r
 115 <h4>Memory Allocation</h4>\r
 116 <p>All memory allocation is done by the application. Several data items are required. The application can declare them statically or use\r
 117 malloc or whatever. NMEAP doesn't do any memory allocation on its own. This is an important requirement for portability and especially in\r
 118 embedded systems where memory allocation needs to be tightly defined and controlled.\r
 119 </p>\r
 120 <h4>Threads</h4>\r
 121 <p>NMEAP as implemented is not meant to be called from multiple threads. It expects to execute within the context of a single thread. The sentence callouts execute\r
 122 in the context of the thread of the nmeap client thread. Given how nmeap works, it doesn't really make sense to make nmeap thread-safe\r
 123 because the usage pattern is intrinsically single thread. If one wanted to, one could add some mutex locking within the nmeap function\r
 124 calls to make it thread safe. In a multithreaded environment, a more likely approach to thread-safety is to put synchronization in the client side of the application,\r
 125 within the sentence parser callouts or inline handling of sentence data.\r
 126 </p>\r
 127 <h4>IO</h4>\r
 128 <p>NMEAP is IO agnostic. That is a pompous way of saying that NMEAP doesn't do the IO, the client application does it. There are way too\r
 129 many IO schemes to handle to keep it portable, especially in the embedded world. That said, the example programs contain a Linux and a Win32 specific\r
 130 program that includes serial IO for those two platforms.\r
 131 </p>\r
 132 \r
 133 <h4>Examples</h4>\r
 134 Look at the code for the following example programs to see the usage patterns. The are all located in the\r
 135 'tst' directory. There are big, obvious comments delineating the steps to setting up and using NMEAP.\r
 136 The IO is simulated in the samples. Follow the comments in the code\r
 137 to see the sequence of operations to setup and run the parser. When you are ready just plug in your own IO.\r
 138 <ol>\r
 139         <li>tst/test1.c Setup for standard GGA and RMC sentences with byte by byte IO (easiest to code up)</li>\r
 140         <li>tst/test2.c Setup for standard GGA and RMC sentences with block IO (more efficient from a system call standpoint)</li>\r
 141         <li>tst/test3.c Adding a custom parser</li>\r
 142         <li>tst/wingps.c A console program that reads a serial port and writes the decoded data to standard out for WIN32 applications</li>\r
 143 </ol>\r
 144 <a name="c4">&nbsp;</a>\r
 145 <h3>API Documentation</h3>\r
 146 The documentation for the actual API is in <a href="www.doxygen.org">Doxygen<a> HTML format and is contained in the 'doc' directory of\r
 147 the source distribution. Or, all the external data structures, constants and functions are defined in 'inc/nmeap.h'. \r
 148 \r
 149 <p>END</p>\r
 150 </body>\r
 151 </html>\r