Diff: gnss.h

Revision:

4:82308d600690

Parent:

3:2a1cd49ead85

Child:

5:af4baf3c67f3

--- a/gnss.h	Thu May 04 16:29:39 2017 +0000
+++ b/gnss.h	Tue Jun 06 21:05:08 2017 +0100
@@ -26,23 +26,25 @@
 #include "pipe.h"
 #include "serial_pipe.h"
 
-#ifdef TARGET_UBLOX_C030
+#if defined (TARGET_UBLOX_C030) || defined (TARGET_UBLOX_C027)
 # define GNSS_IF(onboard, shield) onboard
 #else
 # define GNSS_IF(onboard, shield) shield
 #endif
 
-/** basic GNSS parser class
+/** Basic GNSS parser class.
 */
 class GnssParser
 {
 public:
-    //! Constructor
+    /** Constructor.
+     */
     GnssParser();
-    //! Destructor
+    /** Destructor.
+     */
     virtual ~GnssParser(void);
 
-    /** Power on / Wake up the GNSS
+    /** Power-on/wake-up the GNSS.
     */
     virtual bool init(PinName pn) = 0;
     
@@ -60,89 +62,89 @@
     };
     
     /** Get a line from the physical interface. This function
-        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
-    */ 
+     * 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;
     
-    /** send a buffer
-        \param buf the buffer to write
-        \param len size of the buffer to write
-        \return bytes written
-    */
+    /** 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
-    */
+     * 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);
     
-    /** 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
-    */
+    /** 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 sendUbx(unsigned char cls, unsigned char id, 
                         const void* buf = NULL, int len = 0);
     
     /** Power off the GNSS, it can be again woken up by an
-        edge on the serial port on the external interrupt pin. 
+     * 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. 
-    */
+    /** 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
-    */
+    /** 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
-    */
+    /** 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
-    */
+    /** 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
-    */
+    /** 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:
@@ -150,85 +152,89 @@
     */
     void _powerOn(void);
 
-    /** 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
-    */ 
+    /** 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
-    */ 
+     * @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
-    */ 
+     * @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
-    */
+     * 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]; //!< num to hex conversion
-    DigitalInOut *_gnssEnable; //!< IO pin that enables GNSS
+    DigitalInOut *_gnssEnable;    //!< IO pin that enables GNSS
 };
 
-/** GNSS class which uses a serial port
-    as physical interface. 
-*/
+/** GNSS class which uses a serial port as physical interface. 
+ */
 class GnssSerial : public SerialPipe, public GnssParser
 {
 public:
-    /** Constructor
-        \param tx is the serial ports transmit pin (GNSS to CPU)
-        \param rx is the serial ports receive pin (CPU to GNSS)
-        \param baudrate the baudrate of the GNSS use 9600
-        \param rxSize the size of the serial rx buffer
-        \param txSize the size of the serial tx buffer
-    */
+    /** Constructor.
+     * @param tx is the serial ports transmit pin (GNSS to CPU).
+     * @param rx is the serial ports receive pin (CPU to GNSS).
+     * @param baudrate the baudrate of the GNSS use 9600.
+     * @param rxSize the size of the serial rx buffer.
+     * @param txSize the size of the serial tx buffer.
+     */
     GnssSerial(PinName tx    GNSS_IF( = GNSSTXD, = D8 /* = D8 */), // resistor on shield not populated
                PinName rx    GNSS_IF( = GNSSRXD, = D9 /* = D9 */), // resistor on shield not populated
                int baudrate  GNSS_IF( = GNSSBAUD, = 9600 ),
                int rxSize    = 256 ,
                int txSize    = 128 );
               
-    //! Destructor
+    /** Destructor.
+     */
     virtual ~GnssSerial(void);
     
+    /** Initialise the GNSS device.
+     * @param pn  NOT USED.
+     * @return true if successful, otherwise false.
+     */
     virtual bool init(PinName pn = NC);
     
     /** Get a line from the physical interface. 
-        \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
-    */ 
+     * @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);
     
 protected:
     /** Write bytes to the physical interface.
-        \param buf the buffer to write
-        \param len size of the buffer to write
-        \return bytes written
-    */
+     * @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);
 };
 
@@ -237,89 +243,91 @@
 class GnssI2C : public I2C, public GnssParser
 {
 public: 
-    /** Constructor
-        \param sda is the I2C SDA pin (between CPU and GNSS)
-        \param scl is the I2C SCL pin (CPU to GNSS)
-        \param adr the I2C address of the GNSS set to (66<<1)
-        \param rxSize the size of the serial rx buffer
-    */
+    /** Constructor.
+     * @param sda is the I2C SDA pin (between CPU and GNSS).
+     * @param scl is the I2C SCL pin (CPU to GNSS).
+     * @param adr the I2C address of the GNSS set to (66<<1).
+     * @param rxSize the size of the serial rx buffer.
+     */
     GnssI2C(PinName sda          GNSS_IF( = NC, = /* D16 TODO */ NC ),
             PinName scl          GNSS_IF( = NC, = /* D17 TODO */ NC ),
             unsigned char i2cAdr GNSS_IF( = (66<<1), = (66<<1) ),
             int rxSize           = 256 );
-    //! Destructor
+    /** Destructor
+     */
     virtual ~GnssI2C(void);
     
-    /** helper function to probe the i2c device
-        \return true if successfully detected the GNSS chip.
-    */ 
+    /** Helper function to probe the i2c device.
+     * @param pn  the power-on pin for the chip.
+     * @return true if successfully detected the GNSS chip.
+     */ 
     virtual bool init(PinName pn = GNSS_IF( NC, NC /* D7 resistor R67 on shield not mounted */));
     
     /** Get a line from the physical interface. 
-        \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
-    */ 
+     * @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);
     
-    /** send a buffer
-        \param buf the buffer to write
-        \param len size of the buffer to write
-        \return bytes written
-    */
+    /** 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
-    */
+    /** Send an 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);
     
-    /** 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
-    */
+    /** 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 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; }
+    /** 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 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
-    */
+     * @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 
-        \return bytes read
-    */
+    /** Read bytes from the physical interface.
+     * @param buf the buffer to read into.
+     * @param len size of the read buffer .
+     * @return bytes read.
+     */
     int _get(char* buf, int len);
     
-    Pipe<char> _pipe;           //!< the rx pipe
-    unsigned char _i2cAdr;      //!< the i2c address
-    static const char REGLEN;   //!< the length i2c register address
-    static const char REGSTREAM;//!< the stream i2c register address
+    Pipe<char> _pipe;           //!< the rx pipe.
+    unsigned char _i2cAdr;      //!< the i2c address.
+    static const char REGLEN;   //!< the length i2c register address.
+    static const char REGSTREAM;//!< the stream i2c register address.
 };
 
 #endif