gnss.h

00001 /* mbed Microcontroller Library
00002  * Copyright (c) 2017 u-blox
00003  *
00004  * Licensed under the Apache License, Version 2.0 (the "License");
00005  * you may not use this file except in compliance with the License.
00006  * You may obtain a copy of the License at
00007  *
00008  *     http://www.apache.org/licenses/LICENSE-2.0
00009  *
00010  * Unless required by applicable law or agreed to in writing, software
00011  * distributed under the License is distributed on an "AS IS" BASIS,
00012  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00013  * See the License for the specific language governing permissions and
00014  * limitations under the License.
00015  */
00016 
00017 #ifndef GNSS_H
00018 #define GNSS_H
00019 
00020 /**
00021  * @file gnss.h
00022  * This file defines a class that communicates with a u-blox GNSS chip.
00023  */
00024 
00025 #include "mbed.h"
00026 #include "pipe.h"
00027 #include "serial_pipe.h"
00028 
00029 #if defined (TARGET_UBLOX_C030) || defined (TARGET_UBLOX_C027)
00030 # define GNSS_IF(onboard, shield) onboard
00031 #else
00032 # define GNSS_IF(onboard, shield) shield
00033 #endif
00034 
00035 #ifdef TARGET_UBLOX_C027
00036 # define GNSSEN   GPSEN
00037 # define GNSSTXD  GPSTXD
00038 # define GNSSRXD  GPSRXD
00039 # define GNSSBAUD GPSBAUD
00040 #endif
00041 
00042 /** Basic GNSS parser class.
00043 */
00044 class GnssParser
00045 {
00046 public:
00047     /** Constructor.
00048      */
00049     GnssParser();
00050     /** Destructor.
00051      */
00052     virtual ~GnssParser(void);
00053 
00054     /** Power-on/wake-up the GNSS.
00055     */
00056     virtual bool init(PinName pn) = 0;
00057     
00058     enum { 
00059         // getLine Responses
00060         WAIT      = -1, //!< wait for more incoming data (the start of a message was found, or no data available)
00061         NOT_FOUND =  0, //!< a parser concluded the the current offset of the pipe doe not contain a valid message
00062     
00063         #define LENGTH(x)   (x & 0x00FFFF)  //!< extract/mask the length
00064         #define PROTOCOL(x) (x & 0xFF0000)  //!< extract/mask the type
00065 
00066         UNKNOWN   = 0x000000,       //!< message type is unknown 
00067         UBX       = 0x100000,       //!< message if of protocol NMEA
00068         NMEA      = 0x200000        //!< message if of protocol UBX
00069     };
00070     
00071     /** Get a line from the physical interface. This function
00072      * needs to be implemented in the inherited class.
00073      * @param buf the buffer to store it.
00074      * @param len size of the buffer.
00075      * @return type and length if something was found, 
00076      *         WAIT if not enough data is available,
00077      *         NOT_FOUND if nothing was found
00078      */ 
00079     virtual int getMessage(char* buf, int len) = 0;
00080     
00081     /** Send a buffer.
00082      * @param buf the buffer to write.
00083      * @param len size of the buffer to write.
00084      * @return bytes written.
00085      */
00086     virtual int send(const char* buf, int len);
00087     
00088     /** send a NMEA message, this function just takes the 
00089      * payload and calculates and adds checksum. ($ and *XX\r\n will be added).
00090      * @param buf the message payload to write.
00091      * @param len size of the message payload to write.
00092      * @return total bytes written.
00093      */
00094     virtual int sendNmea(const char* buf, int len);
00095     
00096     /** Send a UBX message, this function just takes the
00097      * payload and calculates and adds checksum.
00098      * @param cls the UBX class id.
00099      * @param id the UBX message id.
00100      * @param buf the message payload to write.
00101      * @param len size of the message payload to write.
00102      * @return total bytes written.
00103      */
00104     virtual int sendUbx(unsigned char cls, unsigned char id, 
00105                         const void* buf = NULL, int len = 0);
00106     
00107     /** Power off the GNSS, it can be again woken up by an
00108      * edge on the serial port on the external interrupt pin. 
00109     */
00110     void powerOff(void);
00111     
00112     /** get the first character of a NMEA field.
00113      * @param ix the index of the field to find.
00114      * @param start the start of the buffer.
00115      * @param end the end of the buffer.
00116      * @return the pointer to the first character of the field. 
00117      */
00118     static const char* findNmeaItemPos(int ix, const char* start, const char* end);
00119     
00120     /** Extract a double value from a buffer containing a NMEA message.
00121      * @param ix the index of the field to extract.
00122      * @param buf the NMEA message.
00123      * @param len the size of the NMEA message.
00124      * @param val the extracted value.
00125      * @return true if successful, false otherwise.
00126      */
00127     static bool getNmeaItem(int ix, char* buf, int len, double& val);
00128     
00129     /** Extract a interger value from a buffer containing a NMEA message.
00130      * @param ix the index of the field to extract.
00131      * @param buf the NMEA message.
00132      * @param len the size of the NMEA message.
00133      * @param val the extracted value.
00134      * @param base the numeric base to be used (e.g. 8, 10 or 16).
00135      * @return true if successful, false otherwise.
00136      */
00137     static bool getNmeaItem(int ix, char* buf, int len, int& val, int base/*=10*/);
00138     
00139     /** Extract a char value from a buffer containing a NMEA message.
00140      * @param ix the index of the field to extract.
00141      * @param buf the NMEA message.
00142      * @param len the size of the NMEA message.
00143      * @param val the extracted value.
00144      * @return true if successful, false otherwise.
00145      */
00146     static bool getNmeaItem(int ix, char* buf, int len, char& val);
00147     
00148     /** Extract a latitude/longitude value from a buffer containing a NMEA message.
00149      * @param ix the index of the field to extract (will extract ix and ix + 1),
00150      * @param buf the NMEA message,
00151      * @param len the size of the NMEA message,
00152      * @param val the extracted latitude or longitude,
00153      * @return true if successful, false otherwise.
00154      */
00155     static bool getNmeaAngle(int ix, char* buf, int len, double& val);
00156     
00157 protected:
00158     /** Power on the GNSS module.
00159     */
00160     void _powerOn(void);
00161 
00162     /** Get a line from the physical interface.
00163      * @param pipe the receiveing pipe to parse messages .
00164      * @param buf the buffer to store it.
00165      * @param len size of the buffer.
00166      * @return type and length if something was found, 
00167      *         WAIT if not enough data is available,
00168      *         NOT_FOUND if nothing was found.
00169      */ 
00170     static int _getMessage(Pipe<char> * pipe, char* buf, int len);
00171     
00172     /** Check if the current offset of the pipe contains a NMEA message.
00173      * @param pipe the receiveing pipe to parse messages.
00174      * @param len numer of bytes to parse at maximum.
00175      * @return length if something was found (including the NMEA frame),
00176      *         WAIT if not enough data is available,
00177      *         NOT_FOUND if nothing was found.
00178      */ 
00179     static int _parseNmea(Pipe<char> * pipe, int len);
00180     
00181     /** Check if the current offset of the pipe contains a UBX message.
00182      * @param pipe the receiveing pipe to parse messages.
00183      * @param len numer of bytes to parse at maximum.
00184      * @return length if something was found (including the UBX frame),
00185      *         WAIT if not enough data is available,
00186      *         NOT_FOUND if nothing was found.
00187      */ 
00188     static int _parseUbx(Pipe<char> * pipe, int len);
00189     
00190     /** Write bytes to the physical interface. This function 
00191      * needs to be implemented by the inherited class. 
00192      * @param buf the buffer to write.
00193      * @param len size of the buffer to write.
00194      * @return bytes written.
00195      */
00196     virtual int _send(const void* buf, int len) = 0;
00197     
00198     static const char _toHex[16]; //!< num to hex conversion
00199     DigitalInOut *_gnssEnable;    //!< IO pin that enables GNSS
00200 };
00201 
00202 /** GNSS class which uses a serial port as physical interface. 
00203  */
00204 class GnssSerial : public SerialPipe, public GnssParser
00205 {
00206 public:
00207     /** Constructor.
00208      * @param tx is the serial ports transmit pin (GNSS to CPU).
00209      * @param rx is the serial ports receive pin (CPU to GNSS).
00210      * @param baudrate the baudrate of the GNSS use 9600.
00211      * @param rxSize the size of the serial rx buffer.
00212      * @param txSize the size of the serial tx buffer.
00213      */
00214     GnssSerial(PinName tx    GNSS_IF( = GNSSTXD, = D8 /* = D8 */), // resistor on shield not populated
00215                PinName rx    GNSS_IF( = GNSSRXD, = D9 /* = D9 */), // resistor on shield not populated
00216                int baudrate  GNSS_IF( = GNSSBAUD, = 9600 ),
00217                int rxSize    = 256 ,
00218                int txSize    = 128 );
00219               
00220     /** Destructor.
00221      */
00222     virtual ~GnssSerial(void);
00223     
00224     /** Initialise the GNSS device.
00225      * @param pn  NOT USED.
00226      * @return true if successful, otherwise false.
00227      */
00228     virtual bool init(PinName pn = NC);
00229     
00230     /** Get a line from the physical interface. 
00231      * @param buf the buffer to store it.
00232      * @param len size of the buffer.
00233      * @return type and length if something was found, 
00234      *         WAIT if not enough data is available,
00235      *         NOT_FOUND if nothing was found.
00236      */ 
00237     virtual int getMessage(char* buf, int len);
00238     
00239 protected:
00240     /** Write bytes to the physical interface.
00241      * @param buf the buffer to write.
00242      * @param len size of the buffer to write.
00243      * @return bytes written.
00244      */
00245     virtual int _send(const void* buf, int len);
00246 };
00247 
00248 /** GNSS class which uses a i2c as physical interface.
00249 */
00250 class GnssI2C : public I2C, public GnssParser
00251 {
00252 public: 
00253     /** Constructor.
00254      * @param sda is the I2C SDA pin (between CPU and GNSS).
00255      * @param scl is the I2C SCL pin (CPU to GNSS).
00256      * @param adr the I2C address of the GNSS set to (66<<1).
00257      * @param rxSize the size of the serial rx buffer.
00258      */
00259     GnssI2C(PinName sda          GNSS_IF( = NC, = /* D16 TODO */ NC ),
00260             PinName scl          GNSS_IF( = NC, = /* D17 TODO */ NC ),
00261             unsigned char i2cAdr GNSS_IF( = (66<<1), = (66<<1) ),
00262             int rxSize           = 256 );
00263     /** Destructor
00264      */
00265     virtual ~GnssI2C(void);
00266     
00267     /** Helper function to probe the i2c device.
00268      * @param pn  the power-on pin for the chip.
00269      * @return true if successfully detected the GNSS chip.
00270      */ 
00271     virtual bool init(PinName pn = GNSS_IF( NC, NC /* D7 resistor R67 on shield not mounted */));
00272     
00273     /** Get a line from the physical interface. 
00274      * @param buf the buffer to store it.
00275      * @param len size of the buffer.
00276      * @return type and length if something was found, 
00277      *         WAIT if not enough data is available,
00278      *         NOT_FOUND if nothing was found.
00279      */ 
00280     virtual int getMessage(char* buf, int len);
00281     
00282     /** Send a buffer.
00283      *  @param buf the buffer to write.
00284      *  @param len size of the buffer to write.
00285      *  @return bytes written.
00286      */
00287     virtual int send(const char* buf, int len);
00288     
00289     /** Send an NMEA message, this function just takes the 
00290      * payload and calculates and adds checksum ($ and *XX\r\n will be added).
00291      * @param buf the message payload to write.
00292      * @param len size of the message payload to write.
00293      * @return total bytes written.
00294      */
00295     virtual int sendNmea(const char* buf, int len);
00296     
00297     /** Send a UBX message, this function just takes the 
00298      * payload and calculates and adds checksum.
00299      * @param cls the UBX class id.
00300      * @param id the UBX message id.
00301      * @param buf the message payload to write.
00302      * @param len size of the message payload to write.
00303      * @return total bytes written.
00304      */
00305     virtual int sendUbx(unsigned char cls, unsigned char id, 
00306                         const void* buf = NULL, int len = 0);
00307                         
00308 protected:
00309     /** Check if the port is writeable (like SerialPipe)
00310      * @return true if writeable        
00311      */
00312     bool writeable(void) {return true;}
00313     
00314     /** Write a character (like SerialPipe).
00315      * @param c  the character to write.
00316      * @return true if succesffully written .
00317      */
00318     bool putc(int c) {char ch = c; return send(&ch, 1);}
00319     
00320     /** Write bytes to the physical interface.
00321      * @param buf the buffer to write.
00322      * @param len size of the buffer to write.
00323      * @return bytes written.
00324      */
00325     virtual int _send(const void* buf, int len);
00326     
00327     /** Read bytes from the physical interface.
00328      * @param buf the buffer to read into.
00329      * @param len size of the read buffer .
00330      * @return bytes read.
00331      */
00332     int _get(char* buf, int len);
00333     
00334     Pipe<char>  _pipe;           //!< the rx pipe.
00335     unsigned char _i2cAdr;      //!< the i2c address.
00336     static const char REGLEN;   //!< the length i2c register address.
00337     static const char REGSTREAM;//!< the stream i2c register address.
00338 };
00339 
00340 #endif
00341 
00342 // End Of File