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 #define UBX_FRAME_SIZE 8
00043 #define RETRY 5
00044 #define SYNC_CHAR_INDEX_1 0
00045 #define SYNC_CHAR_INDEX_2 1
00046 #define MSG_CLASS_INDEX 2
00047 #define MSG_ID_INDEX 3
00048 #define UBX_LENGTH_INDEX 4
00049 #define UBX_PAYLOAD_INDEX 6
00050 
00051 enum eUBX_MSG_CLASS {NAV = 0x01, ACK = 0x05, LOG = 0x21};
00052 
00053 enum eUBX_MESSAGE  {UBX_LOG_BATCH, UBX_ACK_ACK, UBX_ACK_NAK, UBX_NAV_ODO, UBX_NAV_PVT, UBX_NAV_STATUS, UBX_NAV_SAT, UNKNOWN_UBX};
00054 
00055 typedef struct UBX_ACK_ACK {
00056     uint8_t msg_class;
00057     uint8_t msg_id;
00058 
00059 }tUBX_ACK_ACK;
00060 
00061 typedef struct UBX_NAV_ODO {
00062     uint8_t version;
00063     uint8_t reserved[3];
00064     uint32_t itow;
00065     uint32_t distance;
00066     uint32_t totalDistance;
00067     uint32_t distanceSTD;
00068 }tUBX_NAV_ODO;
00069 
00070 typedef struct UBX_NAV_PVT {
00071     uint32_t itow;
00072     uint16_t year;
00073     uint8_t month;
00074     uint8_t day;
00075     uint8_t fixType;
00076     uint8_t flag1; // gnssFixOK, diffSoln, psmState, headVehValid and carrSoln.
00077     int32_t lon; // scaling 1e-7
00078     int32_t lat; // scaling 1e-7
00079     int32_t height;
00080     int32_t speed;
00081 
00082 }tUBX_NAV_PVT;
00083 
00084 typedef struct UBX_LOG_BATCH {
00085     uint32_t itow;
00086     int32_t lon; // scaling 1e-7
00087     int32_t lat; // scaling 1e-7
00088     int32_t height;
00089     uint32_t distance;
00090     uint32_t totalDistance;
00091     uint32_t distanceSTD;
00092 
00093 }tUBX_LOG_BATCH;
00094 
00095 typedef struct UBX_CFG_BATCH {
00096     uint32_t version;
00097     uint8_t flags;
00098     uint32_t bufSize;
00099     uint32_t notifThrs;
00100     uint8_t pioId;
00101     uint8_t reserved1;
00102 
00103 }tUBX_CFG_BATCH;
00104 
00105 typedef struct UBX_NAV_STATUS{
00106     uint32_t itow;
00107     uint8_t fix;
00108     uint8_t flags;
00109     uint32_t ttff;
00110     uint32_t msss;
00111 
00112 }tUBX_NAV_STATUS;
00113 
00114 typedef struct UBX_NAV_SAT{
00115     bool status;
00116 
00117 }tUBX_NAV_SAT;
00118 
00119 /** Basic GNSS parser class.
00120 */
00121 class GnssParser
00122 {
00123 public:
00124     /** Constructor.
00125      */
00126     GnssParser();
00127     /** Destructor.
00128      */
00129     virtual ~GnssParser(void);
00130 
00131     /** Power-on/wake-up the GNSS.
00132     */
00133     virtual bool init(PinName pn) = 0;
00134     
00135     enum { 
00136         // getLine Responses
00137         WAIT      = -1, //!< wait for more incoming data (the start of a message was found, or no data available)
00138         NOT_FOUND =  0, //!< a parser concluded the the current offset of the pipe doe not contain a valid message
00139     
00140         #define LENGTH(x)   (x & 0x00FFFF)  //!< extract/mask the length
00141         #define PROTOCOL(x) (x & 0xFF0000)  //!< extract/mask the type
00142 
00143         UNKNOWN   = 0x000000,       //!< message type is unknown 
00144         UBX       = 0x100000,       //!< message if of protocol NMEA
00145         NMEA      = 0x200000        //!< message if of protocol UBX
00146     };
00147     
00148     /** Get a line from the physical interface. This function
00149      * needs to be implemented in the inherited class.
00150      * @param buf the buffer to store it.
00151      * @param len size of the buffer.
00152      * @return type and length if something was found, 
00153      *         WAIT if not enough data is available,
00154      *         NOT_FOUND if nothing was found
00155      */ 
00156     virtual int getMessage(char* buf, int len) = 0;
00157     
00158     /** Send a buffer.
00159      * @param buf the buffer to write.
00160      * @param len size of the buffer to write.
00161      * @return bytes written.
00162      */
00163     virtual int send(const char* buf, int len);
00164     
00165     /** send a NMEA message, this function just takes the 
00166      * payload and calculates and adds checksum. ($ and *XX\r\n will be added).
00167      * @param buf the message payload to write.
00168      * @param len size of the message payload to write.
00169      * @return total bytes written.
00170      */
00171     virtual int sendNmea(const char* buf, int len);
00172     
00173     /** Send a UBX message, this function just takes the
00174      * payload and calculates and adds checksum.
00175      * @param cls the UBX class id.
00176      * @param id the UBX message id.
00177      * @param buf the message payload to write.
00178      * @param len size of the message payload to write.
00179      * @return total bytes written.
00180      */
00181     virtual int sendUbx(unsigned char cls, unsigned char id, 
00182                         const void* buf = NULL, int len = 0);
00183     
00184     /** Power off the GNSS, it can be again woken up by an
00185      * edge on the serial port on the external interrupt pin. 
00186     */
00187     void powerOff(void);
00188     
00189     /** Cuts off the power supply of GNSS by disabling gnssEnable pin
00190     *   Backup supply is provided, can turn it on again by enabling PA15
00191     */
00192     void cutOffPower(void);
00193     
00194     /** get the first character of a NMEA field.
00195      * @param ix the index of the field to find.
00196      * @param start the start of the buffer.
00197      * @param end the end of the buffer.
00198      * @return the pointer to the first character of the field. 
00199      */
00200     static const char* findNmeaItemPos(int ix, const char* start, const char* end);
00201     
00202     /** Extract a double value from a buffer containing a NMEA message.
00203      * @param ix the index of the field to extract.
00204      * @param buf the NMEA message.
00205      * @param len the size of the NMEA message.
00206      * @param val the extracted value.
00207      * @return true if successful, false otherwise.
00208      */
00209     static bool getNmeaItem(int ix, char* buf, int len, double& val);
00210     
00211     /** Extract a interger value from a buffer containing a NMEA message.
00212      * @param ix the index of the field to extract.
00213      * @param buf the NMEA message.
00214      * @param len the size of the NMEA message.
00215      * @param val the extracted value.
00216      * @param base the numeric base to be used (e.g. 8, 10 or 16).
00217      * @return true if successful, false otherwise.
00218      */
00219     static bool getNmeaItem(int ix, char* buf, int len, int& val, int base/*=10*/);
00220     
00221     /** Extract a char value from a buffer containing a NMEA message.
00222      * @param ix the index of the field to extract.
00223      * @param buf the NMEA message.
00224      * @param len the size of the NMEA message.
00225      * @param val the extracted value.
00226      * @return true if successful, false otherwise.
00227      */
00228     static bool getNmeaItem(int ix, char* buf, int len, char& val);
00229     
00230     /** Extract a latitude/longitude value from a buffer containing a NMEA message.
00231      * @param ix the index of the field to extract (will extract ix and ix + 1),
00232      * @param buf the NMEA message,
00233      * @param len the size of the NMEA message,
00234      * @param val the extracted latitude or longitude,
00235      * @return true if successful, false otherwise.
00236      */
00237     static bool getNmeaAngle(int ix, char* buf, int len, double& val);
00238 
00239     /** Enable UBX messages.
00240      * @param none
00241      * @return 1 if successful, false otherwise.
00242      */
00243     int enable_ubx();
00244     
00245     /** GET Message type of receiver UBX message
00246      * @param buff the UXB message
00247      * @return eUBX_MESSAGE
00248      */
00249     eUBX_MESSAGE get_ubx_message(char *);
00250 
00251     /** Method to parse contents of UBX ACK-ACK/NAK and return messageid amd class for which ACK is received
00252      * @param buff the UXB message
00253      * @return tUBX_ACK_ACK
00254      */
00255     tUBX_ACK_ACK decode_ubx_cfg_ack_nak_msg(char *);
00256 
00257     /** Method to parse contents of UBX_NAV_ODO and return decoded msg
00258      * @param buff the UXB message
00259      * @return tUBX_NAV_ODO
00260      */
00261     tUBX_NAV_ODO decode_ubx_nav_odo_msg(char *);
00262 
00263     /** Method to parse contents of UBX_NAV_PVT and return decoded msg
00264      * @param buff the UXB message
00265      * @return tUBX_NAV_PVT
00266      */
00267     tUBX_NAV_PVT decode_ubx_nav_pvt_msg(char *);
00268 
00269     /** Method to parse contents of UBX_LOG_BATCH and return decoded msg
00270      * @param buff the UXB message
00271      * @return tUBX_LOG_BATCH
00272      */
00273     tUBX_LOG_BATCH decode_ubx_log_batch_msg(char *);
00274 
00275     /** Method to parse contents of UBX_NAV_STATUS and return decoded msg
00276      * @param buff the UXB message
00277      * @return tUBX_NAV_STATUS
00278      */
00279     tUBX_NAV_STATUS decode_ubx_nav_status_msg(char *);
00280 
00281     /** Method to parse contents of UBX_NAV_SAT and return decoded msg
00282      * @param buff the UXB message, int length
00283      * @return tUBX_NAV_SAT
00284      */
00285     tUBX_NAV_SAT decode_ubx_nav_sat_msg(char *, int);
00286 
00287     /** Method to send UBX LOG-RETRIEVEBATCH msg. This message is used to request batched data.
00288      * @param bool
00289      * @return int
00290      */
00291     int ubx_request_batched_data(bool sendMonFirst = false);
00292 
00293 protected:
00294     /** Power on the GNSS module.
00295     */
00296     void _powerOn(void);
00297 
00298     /** Get a line from the physical interface.
00299      * @param pipe the receiveing pipe to parse messages .
00300      * @param buf the buffer to store it.
00301      * @param len size of the buffer.
00302      * @return type and length if something was found, 
00303      *         WAIT if not enough data is available,
00304      *         NOT_FOUND if nothing was found.
00305      */ 
00306     static int _getMessage(Pipe<char> * pipe, char* buf, int len);
00307     
00308     /** Check if the current offset of the pipe contains a NMEA message.
00309      * @param pipe the receiveing pipe to parse messages.
00310      * @param len numer of bytes to parse at maximum.
00311      * @return length if something was found (including the NMEA frame),
00312      *         WAIT if not enough data is available,
00313      *         NOT_FOUND if nothing was found.
00314      */ 
00315     static int _parseNmea(Pipe<char> * pipe, int len);
00316     
00317     /** Check if the current offset of the pipe contains a UBX message.
00318      * @param pipe the receiveing pipe to parse messages.
00319      * @param len numer of bytes to parse at maximum.
00320      * @return length if something was found (including the UBX frame),
00321      *         WAIT if not enough data is available,
00322      *         NOT_FOUND if nothing was found.
00323      */ 
00324     static int _parseUbx(Pipe<char> * pipe, int len);
00325     
00326     /** Write bytes to the physical interface. This function 
00327      * needs to be implemented by the inherited class. 
00328      * @param buf the buffer to write.
00329      * @param len size of the buffer to write.
00330      * @return bytes written.
00331      */
00332     virtual int _send(const void* buf, int len) = 0;
00333     
00334     static const char _toHex[16]; //!< num to hex conversion
00335     DigitalInOut *_gnssEnable;    //!< IO pin that enables GNSS
00336 };
00337 
00338 /** GNSS class which uses a serial port as physical interface. 
00339  */
00340 class GnssSerial : public SerialPipe, public GnssParser
00341 {
00342 public:
00343     /** Constructor.
00344      * @param tx is the serial ports transmit pin (GNSS to CPU).
00345      * @param rx is the serial ports receive pin (CPU to GNSS).
00346      * @param baudrate the baudrate of the GNSS use 9600.
00347      * @param rxSize the size of the serial rx buffer.
00348      * @param txSize the size of the serial tx buffer.
00349      */
00350     GnssSerial(PinName tx    GNSS_IF( = GNSSTXD, = D8 /* = D8 */), // resistor on shield not populated
00351                PinName rx    GNSS_IF( = GNSSRXD, = D9 /* = D9 */), // resistor on shield not populated
00352                int baudrate  GNSS_IF( = GNSSBAUD, = 9600 ),
00353                int rxSize    = 512 ,
00354                int txSize    = 512 );
00355               
00356     /** Destructor.
00357      */
00358     virtual ~GnssSerial(void);
00359     
00360     /** Initialise the GNSS device.
00361      * @param pn  NOT USED.
00362      * @param baudrate
00363      * @return true if successful, otherwise false.
00364      */
00365     virtual bool init(PinName pn = NC);
00366     
00367     /** Get a line from the physical interface. 
00368      * @param buf the buffer to store it.
00369      * @param len size of the buffer.
00370      * @return type and length if something was found, 
00371      *         WAIT if not enough data is available,
00372      *         NOT_FOUND if nothing was found.
00373      */ 
00374     virtual int getMessage(char* buf, int len);
00375     
00376 protected:
00377     /** Write bytes to the physical interface.
00378      * @param buf the buffer to write.
00379      * @param len size of the buffer to write.
00380      * @return bytes written.
00381      */
00382     virtual int _send(const void* buf, int len);
00383 };
00384 
00385 /** GNSS class which uses a i2c as physical interface.
00386 */
00387 class GnssI2C : public I2C, public GnssParser
00388 {
00389 public: 
00390     /** Constructor.
00391      * @param sda is the I2C SDA pin (between CPU and GNSS).
00392      * @param scl is the I2C SCL pin (CPU to GNSS).
00393      * @param adr the I2C address of the GNSS set to (66<<1).
00394      * @param rxSize the size of the serial rx buffer.
00395      */
00396     GnssI2C(PinName sda          GNSS_IF( = NC, = /* D16 TODO */ NC ),
00397             PinName scl          GNSS_IF( = NC, = /* D17 TODO */ NC ),
00398             unsigned char i2cAdr GNSS_IF( = (66<<1), = (66<<1) ),
00399             int rxSize           = 256 );
00400     /** Destructor
00401      */
00402     virtual ~GnssI2C(void);
00403     
00404     /** Helper function to probe the i2c device.
00405      * @param pn  the power-on pin for the chip.
00406      * @return true if successfully detected the GNSS chip.
00407      */ 
00408     virtual bool init(PinName pn = GNSS_IF( NC, NC /* D7 resistor R67 on shield not mounted */));
00409     
00410     /** Get a line from the physical interface. 
00411      * @param buf the buffer to store it.
00412      * @param len size of the buffer.
00413      * @return type and length if something was found, 
00414      *         WAIT if not enough data is available,
00415      *         NOT_FOUND if nothing was found.
00416      */ 
00417     virtual int getMessage(char* buf, int len);
00418     
00419     /** Send a buffer.
00420      *  @param buf the buffer to write.
00421      *  @param len size of the buffer to write.
00422      *  @return bytes written.
00423      */
00424     virtual int send(const char* buf, int len);
00425     
00426     /** Send an NMEA message, this function just takes the 
00427      * payload and calculates and adds checksum ($ and *XX\r\n will be added).
00428      * @param buf the message payload to write.
00429      * @param len size of the message payload to write.
00430      * @return total bytes written.
00431      */
00432     virtual int sendNmea(const char* buf, int len);
00433     
00434     /** Send a UBX message, this function just takes the 
00435      * payload and calculates and adds checksum.
00436      * @param cls the UBX class id.
00437      * @param id the UBX message id.
00438      * @param buf the message payload to write.
00439      * @param len size of the message payload to write.
00440      * @return total bytes written.
00441      */
00442     virtual int sendUbx(unsigned char cls, unsigned char id, 
00443                         const void* buf = NULL, int len = 0);
00444                         
00445 protected:
00446     /** Check if the port is writeable (like SerialPipe)
00447      * @return true if writeable        
00448      */
00449     bool writeable(void) {return true;}
00450     
00451     /** Write a character (like SerialPipe).
00452      * @param c  the character to write.
00453      * @return true if succesffully written .
00454      */
00455     bool putc(int c) {char ch = c; return send(&ch, 1);}
00456     
00457     /** Write bytes to the physical interface.
00458      * @param buf the buffer to write.
00459      * @param len size of the buffer to write.
00460      * @return bytes written.
00461      */
00462     virtual int _send(const void* buf, int len);
00463     
00464     /** Read bytes from the physical interface.
00465      * @param buf the buffer to read into.
00466      * @param len size of the read buffer .
00467      * @return bytes read.
00468      */
00469     int _get(char* buf, int len);
00470     
00471     Pipe<char>  _pipe;           //!< the rx pipe.
00472     unsigned char _i2cAdr;      //!< the i2c address.
00473     static const char REGLEN;   //!< the length i2c register address.
00474     static const char REGSTREAM;//!< the stream i2c register address.
00475 };
00476 
00477 #endif
00478 
00479 // End Of File