164 lines
11 KiB
Markdown
164 lines
11 KiB
Markdown
SparkFun u-blox Arduino Library
|
|
===========================================================
|
|
|
|
**Please note: this library is now deprecated. Please migrate to the new [SparkFun u-blox GNSS Arduino Library](https://github.com/sparkfun/SparkFun_u-blox_GNSS_Arduino_Library).**
|
|
|
|
**You can find details on how to migrate to v2.0 [here](https://github.com/sparkfun/SparkFun_u-blox_GNSS_Arduino_Library#migrating-to-v20).**
|
|
|
|
You can install v2.0 via the Arduino Library Manager. Search for **SparkFun u-blox GNSS**.
|
|
|
|
<table class="table table-hover table-striped table-bordered">
|
|
<tr align="center">
|
|
<td><a href="https://www.sparkfun.com/products/15136"><img src="https://cdn.sparkfun.com//assets/parts/1/3/5/1/4/15136-SparkFun_GPS-RTK2_Board_-_ZED-F9P__Qwiic_-03.jpg"></a></td>
|
|
<td><a href="https://www.sparkfun.com/products/15005"><img src="https://cdn.sparkfun.com//assets/parts/1/3/3/2/0/15005-SparkFun_GPS-RTK__Qwiic__-_NEO-M8P-2-00.jpg"></a></td>
|
|
<td><a href="https://www.sparkfun.com/products/15193"><img src="https://cdn.sparkfun.com//assets/parts/1/3/6/1/4/15193-SparkFun_GPS_Breakout_-_U.FL__ZOE-M8__Qwiic_-01.jpg"></a></td>
|
|
<td><a href="https://www.sparkfun.com/products/15210"><img src="https://cdn.sparkfun.com//assets/parts/1/3/6/4/8/15210-SparkFun_GPS_Breakout_-_Chip_Antenna__SAM-M8Q__Qwiic_-01.jpg"></a></td>
|
|
<td><a href="https://www.sparkfun.com/products/15733"><img src="https://cdn.sparkfun.com//assets/parts/1/4/3/2/2/15733-SparkFun_GPS_Breakout_-_NEO-M9N__Chip_Antenna__Qwiic_-01.jpg"></a></td>
|
|
</tr>
|
|
<tr align="center">
|
|
<td><a href="https://www.sparkfun.com/products/15136">SparkFun GPS-RTK2 - ZED-F9P (GPS-15136)</a></td>
|
|
<td><a href="https://www.sparkfun.com/products/15005">SparkFun GPS-RTK - NEO-M8P-2 (GPS-15005)</a></td>
|
|
<td><a href="https://www.sparkfun.com/products/15193">SparkFun ZOE-M8Q Breakout (GPS-15193)</a></td>
|
|
<td><a href="https://www.sparkfun.com/products/15210">SparkFun SAM-M8Q Breakout (GPS-15210)</a></td>
|
|
<td><a href="https://www.sparkfun.com/products/15733">SparkFun NEO-M9N Breakout (GPS-15733)</a></td>
|
|
</tr>
|
|
</table>
|
|
|
|
U-blox makes some incredible GPS receivers covering everything from low-cost, highly configurable modules such as the SAM-M8Q all the way up to the surveyor grade ZED-F9P with precision of the diameter of a dime. This library focuses on configuration and control of u-blox devices over I2C (called DDC by u-blox) and Serial. The UBX protocol is supported over both I2C and serial, and is a much easier and lighterweight interface to a GPS module. Stop parsing NMEA data! And simply ask for the datums you need.
|
|
|
|
This library can be installed via the Arduino Library manager. Search for **SparkFun u-blox GNSS**.
|
|
|
|
Although not an integrated part of the library, you will find an example of how to communicate with the older series 6 and 7 modules in the [examples folder](./examples/Series_6_7).
|
|
|
|
Max (400kHz) I2C Support
|
|
-------------------
|
|
|
|
To achieve 400kHz I2C speed please be sure to remove all pull-ups on the I2C bus. Most, if not all, u-blox modules include pull ups on the I2C lines (sometimes called DDC in their manuals). Cut all I2C pull up jumpers and/or remove them from peripheral boards. Otherwise, various data glitches can occur. See issues [38](https://github.com/sparkfun/SparkFun_Ublox_Arduino_Library/issues/38) and [40](https://github.com/sparkfun/SparkFun_Ublox_Arduino_Library/issues/40) for more information. If possible, run the I2C bus at 100kHz.
|
|
|
|
-------------------
|
|
|
|
Want to help? Please do! We are always looking for ways to improve and build out features of this library.
|
|
|
|
* We are always interested in adding SPI support with a checkUbloxSPI() function
|
|
|
|
Thanks to:
|
|
|
|
* [trycoon](https://github.com/sparkfun/SparkFun_Ublox_Arduino_Library/pull/7) for fixing the lack of I2C buffer length defines.
|
|
* [tve](https://github.com/tve) for building out serial additions and examples.
|
|
* [Redstoned](https://github.com/Redstoned) and [davidallenmann](https://github.com/davidallenmann) for adding PVT date and time.
|
|
* [wittend](https://forum.sparkfun.com/viewtopic.php?t=49874) for pointing out the RTCM print bug.
|
|
* Big thanks to [PaulZC](https://github.com/PaulZC) for implementing the combined key ValSet method, geofence functions, better saveConfig handling, as well as a bunch of small fixes.
|
|
* [RollieRowland](https://github.com/RollieRowland) for adding HPPOSLLH (High Precision Geodetic Position).
|
|
* [tedder](https://github.com/tedder) for moving iTOW to PVT instead of HPPOS and comment cleanup.
|
|
* [grexjmo](https://github.com/grexjmo) for pushing for a better NMEA sentence configuration method.
|
|
* [averywallis](https://github.com/averywallis) for adding good comments to the various constants.
|
|
* [blazczak](https://github.com/blazczak) and [geeksville](https://github.com/geeksville) for adding support for the series 6 and 7 modules.
|
|
* [bjorn@unsurv](https://github.com/unsurv) for adding powerOff and powerOffWithInterrupt.
|
|
* [dotMorten](https://github.com/dotMorten) for the MSGOUT keys, autoHPPOSLLH, autoDOP and upgrades to autoPVT.
|
|
* [markuckermann](https://github.com/markuckermann) for spotting the config layer gremlins
|
|
* [vid553](https://github.com/vid553) for the Zephyr port
|
|
* [balamuruganky](https://github.com/balamuruganky) for the NAV-PVT velocity parameters, getSpeedAccEst, getHeadingAccEst, getInvalidLlh, getHeadVeh, getMagDec and getMagAcc
|
|
* [nelarsen](https://github.com/nelarsen) for the buffer overrun improvements
|
|
* [mstranne](https://github.com/mstranne) and [shaneperera](https://github.com/shaneperera) for the pushRawData suggestion
|
|
* [rubienr](https://github.com/rubienr) for spotting the logical AND issues
|
|
|
|
Need a Python version for Raspberry Pi? Checkout the [Qwiic Ublox GPS Py module](https://github.com/sparkfun/Qwiic_Ublox_Gps_Py).
|
|
|
|
Need a library for the u-blox and Particle? Checkout the [Particle library](https://github.com/aseelye/SparkFun_Ublox_Particle_Library) fork.
|
|
|
|
Need a C++ version which runs on Linux? Checkout the [Ublox_Linux_Library](https://github.com/balamuruganky/Ublox_Linux_Library).
|
|
|
|
Contributing
|
|
--------------
|
|
|
|
If you would like to contribute to this library: please do, we truly appreciate it, but please follow [these guidelines](./CONTRIBUTING.md). Thanks!
|
|
|
|
Repository Contents
|
|
-------------------
|
|
|
|
* **/examples** - Example sketches for the library (.ino). Run these from the Arduino IDE.
|
|
* **/src** - Source files for the library (.cpp, .h).
|
|
* **[keywords.txt](./keywords.txt)** - Keywords from this library that will be highlighted in the Arduino IDE.
|
|
* **[library.properties](./library.properties)** - General library properties for the Arduino package manager.
|
|
* **[CONTRIBUTING.md](./CONTRIBUTING.md)** - Guidelines on how to contribute to this library.
|
|
* **[Theory.md](./Theory.md)** - provides detail on how data is processed by the library.
|
|
|
|
Documentation
|
|
--------------
|
|
|
|
* **[Installing an Arduino Library Guide](https://learn.sparkfun.com/tutorials/installing-an-arduino-library)** - Basic information on how to install an Arduino library.
|
|
|
|
Polling vs. Auto-Reporting
|
|
--------------------------
|
|
|
|
This library supports two modes of operation for getting navigation information with the `getPVT`
|
|
function (based on the `UBX_NAV_PVT` protocol packet): polling and auto-reporting.
|
|
|
|
The standard method is for the sketch to call `getPVT` (or one of the `getLatitude`, `getLongitude`,
|
|
etc. methods) when it needs a fresh navigation solution. At that point the library sends a request
|
|
to the GPS to produce a fresh solution. The GPS then waits until the next measurement occurs (e.g.
|
|
once per second or as set using `setNavigationFrequency`) and then sends the fresh data.
|
|
The advantage of this method is that the data received is always fresh, the downside is that getPVT
|
|
can block until the next measurement is made by the GPS, e.g. up to 1 second if the nav frequency is
|
|
set to one second.
|
|
|
|
An alternate method can be chosen using `setAutoPVT(true)` which instructs the GPS to send the
|
|
navigation information (`UBX_NAV_PVT` packet) as soon as it is produced. This is the way the older
|
|
NMEA navigation data has been used for years. The sketch continues to call `getPVT` as before but
|
|
under the hood the library returns the data of the last solution received from the GPS, which may be
|
|
a bit out of date (how much depends on the `setNavigationFrequency` value).
|
|
|
|
The advantage of this method is that getPVT does not block: it returns true if new data is available
|
|
and false otherwise. The disadvantages are that the data may be a bit old and that buffering for
|
|
these spontaneus `UBX_NAV_PVT` packets is required (100 bytes each). When using Serial the buffering
|
|
is an issue because the std serial buffer is 32 or 64 bytes long depending on Arduino version. When
|
|
using I2C the buffering is not an issue because the GPS device has at least 1KB of internal buffering
|
|
(possibly as large as 4KB).
|
|
|
|
As an example, assume that the GPS is set to produce 5 navigation
|
|
solutions per second and that the sketch only calls getPVT once a second, then the GPS will queue 5
|
|
packets in its internal buffer (about 500 bytes) and the library will read those when getPVT is
|
|
called, update its internal copy of the nav data 5 times, and return `true` to the sketch. The
|
|
sketch calls `getLatitude`, etc. and retrieve the data of the most recent of those 5 packets.
|
|
|
|
The library also supports:
|
|
* `autoHPPOSLLH`
|
|
* `autoDOP`
|
|
* `autoHNRAtt`
|
|
* `autoHNRDyn`
|
|
* `autoHNRPVT`
|
|
|
|
Memory Usage
|
|
---------------------------------
|
|
|
|
Version 1.8.9 introduced support for `autoHNR` on the NEO-M8U, and that tipped the balance in terms of RAM use on the ATmega328.
|
|
The library does still run on the ATmega328 but you will see _**Low memory available, stability problems may occur**_ warnings
|
|
as the global variables now occupy 1540 bytes of RAM. If you do want to run this library on the ATmega328, you may need to regress
|
|
to Version 1.8.8 via the Library Manager.
|
|
|
|
Products That Use This Library
|
|
---------------------------------
|
|
* [GPS-16481](https://www.sparkfun.com/products/16481) - SparkFun GPS-RTK-SMA Breakout - ZED-F9P (Qwiic)
|
|
* [GPS-15136](https://www.sparkfun.com/products/15136) - SparkFun GPS-RTK2 Board - ZED-F9P (Qwiic)
|
|
* [GPS-15005](https://www.sparkfun.com/products/15005) - SparkFun GPS-RTK Board - NEO-M8P-2 (Qwiic)
|
|
* [GPS-15210](https://www.sparkfun.com/products/15210) - SparkFun GPS Breakout - Chip Antenna, SAM-M8Q (Qwiic)
|
|
* [GPS-15193](https://www.sparkfun.com/products/15193) - SparkFun GPS Breakout - Chip Antenna, ZOE-M8Q (Qwiic)
|
|
* [GPS-15733](https://www.sparkfun.com/products/15733) - SparkFun GPS Breakout - NEO-M9N, Chip Antenna (Qwiic)
|
|
* [GPS-15712](https://www.sparkfun.com/products/15712) - SparkFun GPS Breakout - NEO-M9N, U.FL (Qwiic)
|
|
* [GPS-16329](https://www.sparkfun.com/products/16329) - SparkFun GPS Dead Reckoning Breakout - NEO-M8U (Qwiic)
|
|
* [SPX-14980](https://www.sparkfun.com/products/14980) - SparkX GPS-RTK Black
|
|
* [SPX-15106](https://www.sparkfun.com/products/15106) - SparkX SAM-M8Q
|
|
|
|
License Information
|
|
-------------------
|
|
|
|
This product is _**open source**_!
|
|
|
|
Various bits of the code have different licenses applied. Anything SparkFun wrote is beerware; if you see me (or any other SparkFun employee) at the local, and you've found our code helpful, please buy us a round!
|
|
|
|
Please use, reuse, and modify these files as you see fit. Please maintain attribution to SparkFun Electronics and release anything derivative under the same license.
|
|
|
|
Distributed as-is; no warranty is given.
|
|
|
|
- Your friends at SparkFun.
|