Skip to content
This repository was archived by the owner on Jan 28, 2021. It is now read-only.

Commit 86e3df1

Browse files
committed
Add auto-reporting documentation to readme
1 parent 96c226d commit 86e3df1

File tree

1 file changed

+33
-0
lines changed

1 file changed

+33
-0
lines changed

README.md

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -38,6 +38,39 @@ Documentation
3838

3939
* **[Installing an Arduino Library Guide](https://learn.sparkfun.com/tutorials/installing-an-arduino-library)** - Basic information on how to install an Arduino library.
4040

41+
Polling vs. auto-reporting
42+
--------------------------
43+
44+
This library supports two modes of operation for getting navigation information with the `getPVT`
45+
function (based on the `UBX_NAV_PVT` protocol packet): polling and auto-reporting.
46+
47+
The standard method is for the sketch to call `getPVT` (or one of the `getLatitude`, `getLongitude`,
48+
etc. methods) when it needs a fresh navigation solution. At that point the library sends a request
49+
to the GPS to produce a fresh solution. The GPS then waits until the next measurement occurs (e.g.
50+
once per second or as set using `setNavigationFrequency`) and then sends the fresh data.
51+
The advantage of this method is that the data received is always fresh, the downside is that getPVT
52+
can block until the next measurement is made by the GPS, e.g. up to 1 second if the nav frequency is
53+
set to one second.
54+
55+
An alternate method can be chosen using `setAutoPVT(true)` which instructs the GPS to send the
56+
navigation information (`UBX_NAV_PVT` packet) as soon as it is produced. This is the way the older
57+
NMEA navigation data has been used for years. The sketch continues to call `getPVT` as before but
58+
under the hood the library returns the data of the last solution received from the GPS, which may be
59+
a bit out of date (how much depends on the `setNavigationFrequency` value).
60+
61+
The advantage of this method is that getPVT does not block: it returns true if new data is available
62+
and false otherwise. The disadvantages are that the data may be a bit old and that buffering for
63+
these spontaneus `UBX_NAV_PVT` packets is required (100 bytes each). When using Serial the buffering
64+
is an issue because the std serial buffer is 32 or 64 bytes long depending on Arduino version. When
65+
using I2C the buffering is not an issue because the GPS device has at least 1KB of internal buffering
66+
(possibly as large as 4KB).
67+
68+
As an example, assume that the GPS is set to produce 5 navigation
69+
solutions per second and that the sketch only calls getPVT once a second, then the GPS will queue 5
70+
packets in its internal buffer (about 500 bytes) and the library will read those when getPVT is
71+
called, update its internal copy of the nav data 5 times, and return `true` to the sketch. The
72+
skecth calls `getLatitude`, etc. and retrieve the data of the most recent of those 5 packets.
73+
4174
Products That Use This Library
4275
---------------------------------
4376

0 commit comments

Comments
 (0)