Diff: GPS.h

Revision:

39:9b4b9433e220

Parent:

38:e6cab4632d84

Child:

40:295099ff5338

--- a/GPS.h	Fri Apr 11 16:30:54 2014 +0000
+++ b/GPS.h	Fri Apr 11 19:16:03 2014 +0000
@@ -18,32 +18,139 @@
 class GPSParser
 {
 public:
-    #define WAIT      -1
-    #define NOT_FOUND  0
+    // 
+    #define WAIT      -1 //!< wait for more incoming data (the start of a message was found, or no data available)
+    #define NOT_FOUND  0 //!< a parser concluded the the current offset of the pipe doe not contain a valid message
+    
+    #define UNKNOWN     0x000000        //!< message type is unknown 
+    #define UBX         0x100000        //!< message if of protocol NMEA
+    #define NMEA        0x200000        //!< message if of protocol UBX
+    #define LENGTH(x)   (x & 0x00FFFF)  //!< extract/mask the length
+    #define PROTOCOL(x) (x & 0xFF0000)  //!< extract/mask the type
+
+    /** Get a line from the physical interface. This fucntion 
+        needs to be implemented in the inherited class.
+        \param buf the buffer to store it
+        \param len size of the buffer
+        \return type and length if something was found, 
+                WAIT if not enough data is available
+                NOT_FOUND if nothing was found
+    */ 
+    virtual int getMessage(char* buf, int len) = 0;
     
-    #define UNKNOWN     0x000000
-    #define UBX         0x100000
-    #define NMEA        0x200000
-    #define LENGTH(x)   (x & 0x00FFFF)
-    #define PROTOCOL(x) (x & 0xFF0000)
-
-    virtual int getMessage(char* buf, int len) = 0; 
+    /** send a buffer
+        \param buf the buffer to write
+        \param len size of the buffer to write
+        \return bytes written
+    */
     virtual int send(const char* buf, int len);
+    
+    /** send a NMEA message, this function just takes the 
+        payload and calculates and adds checksum. ($ and *XX\r\n will be added)
+        \param buf the message payload to write
+        \param len size of the message payload to write
+        \return total bytes written
+    */
     virtual int sendNmea(const char* buf, int len);
-    virtual int sendUbx(unsigned char cls, unsigned char id, const void* buf = NULL, int len = 0);
+    
+    /** send a UBX message, this function just takes the 
+        payload and calculates and adds checksum.
+        \param cls the UBX class id 
+        \param id the UBX message id
+        \param buf the message payload to write
+        \param len size of the message payload to write
+        \return total bytes written
+    */
+    virtual int send(const char* buf, int len);
+    
+    /** Power off the gps, it can be again woken up by an 
+        edge on the serial port on the external interrupt pin. 
+    */
     void powerOff(void);
     
+    /** get the first character of a NMEA field
+        \param ix the index of the field to find
+        \param start the start of the buffer
+        \param end the end of the buffer
+        \return the pointer to the first character of the field. 
+    */
     static const char* findNmeaItemPos(int ix, const char* start, const char* end);
+    
+    /** extract a double value from a buffer containing a NMEA message
+        \param ix the index of the field to extract
+        \param buf the NMEA message
+        \param len the size of the NMEA message
+        \param val the extracted value
+        \return true if successful, false otherwise
+    */
     static bool getNmeaItem(int ix, char* buf, int len, double& val);
+    
+    /** extract a interger value from a buffer containing a NMEA message
+        \param ix the index of the field to extract
+        \param buf the NMEA message
+        \param len the size of the NMEA message
+        \param val the extracted value
+        \param base the numeric base to be used (e.g. 8, 10 or 16)
+        \return true if successful, false otherwise
+    */
     static bool getNmeaItem(int ix, char* buf, int len, int& val, int base/*=10*/);
+    
+    /** extract a char value from a buffer containing a NMEA message
+        \param ix the index of the field to extract
+        \param buf the NMEA message
+        \param len the size of the NMEA message
+        \param val the extracted value
+        \return true if successful, false otherwise
+    */
     static bool getNmeaItem(int ix, char* buf, int len, char& val);
+    
+    /** extract a latitude/longitude value from a buffer containing a NMEA message
+        \param ix the index of the field to extract (will extract ix and ix + 1)
+        \param buf the NMEA message
+        \param len the size of the NMEA message
+        \param val the extracted latitude or longitude
+        \return true if successful, false otherwise
+    */
     static bool getNmeaAngle(int ix, char* buf, int len, double& val);
+    
 protected:
+    /** Get a line from the physical interface. 
+        \param pipe the receiveing pipe to parse messages 
+        \param buf the buffer to store it
+        \param len size of the buffer
+        \return type and length if something was found, 
+                WAIT if not enough data is available
+                NOT_FOUND if nothing was found
+    */ 
     static int _getMessage(Pipe<char>* pipe, char* buf, int len);
+    
+    /** Check if the current offset of the pipe contains a NMEA message.
+        \param pipe the receiveing pipe to parse messages 
+        \param len numer of bytes to parse at maximum
+        \return length if something was found (including the NMEA frame) 
+                WAIT if not enough data is available
+                NOT_FOUND if nothing was found
+    */ 
     static int _parseNmea(Pipe<char>* pipe, int len);
+    
+    /** Check if the current offset of the pipe contains a UBX message.
+        \param pipe the receiveing pipe to parse messages 
+        \param len numer of bytes to parse at maximum
+        \return length if something was found (including the UBX frame)
+                WAIT if not enough data is available
+                NOT_FOUND if nothing was found
+    */ 
     static int _parseUbx(Pipe<char>* pipe, int len);
+    
+    /** Write bytes to the physical interface. This function 
+        needs to be implemented by the inherited class. 
+        \param buf the buffer to write
+        \param len size of the buffer to write
+        \return bytes written
+    */
     virtual int _send(const void* buf, int len) = 0;
-    static const char toHex[16];
+    
+    static const char toHex[16]; //!< num to hex conversion
 };
 
 /** gps class which uses a serial port 
@@ -64,6 +171,7 @@
               int baudrate  _C027DEFAULT( GPSBAUD ),
               int rxSize    = 256 , 
               int txSize    = 128 );
+              
     /** Get a line from the physical interface. 
         \param buf the buffer to store it
         \param len size of the buffer
@@ -72,6 +180,7 @@
                 NOT_FOUND if nothing was found
     */ 
     virtual int getMessage(char* buf, int len);
+    
 protected:
     /** Write bytes to the physical interface.
         \param buf the buffer to write
@@ -96,6 +205,7 @@
            PinName scl          _C027DEFAULT( GPSSCL ),
            unsigned char i2cAdr _C027DEFAULT( GPSADR ), 
            int rxSize           = 256 );
+
     /** helper function to probe the i2c device
         \return true if successfully detected the gps. 
     */ 
@@ -133,23 +243,28 @@
         \param len size of the message payload to write
         \return total bytes written
     */
-    virtual int sendUbx(unsigned char cls, unsigned char id, const void* buf = NULL, int len = 0);
+    virtual int sendUbx(unsigned char cls, unsigned char id, 
+                        const void* buf = NULL, int len = 0);
+                        
 protected:
     /** check if the port is writeable (like SerialPipe)
         \return true if writeable        
     */
     bool writeable(void) { return true; }
+    
     /** Write a character (like SerialPipe)
         \param c  the character to write
         \return true if succesffully written 
     */
     bool putc(int c)     { char ch = c; return send(&ch, 1); }
+    
     /** Write bytes to the physical interface.
         \param buf the buffer to write
         \param len size of the buffer to write
         \return bytes written
     */
     virtual int _send(const void* buf, int len);
+    
     /** read bytes from the physical interface.
         \param buf the buffer to read into
         \param len size of the read buffer