Michel2/Adafruit_GPS
1
0 Fork 0
mirror of https://github.com/adafruit/Adafruit_GPS.git synced 2026-10-27 06:20:18 +00:00
Code Issues Packages Projects Releases Wiki Activity

Document GPS setup and all examples

Browse Source 
Co-authored-by: Limor Fried <ladyada@users.noreply.github.com>
This commit is contained in:
ladyadaandLimor Fried committed 2026-09-15 12:04:58 -04:00
1 parent 6d811e98f0
commit 6ad57c1f70
1 file changed
+125 -20
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+125 -20
View File
@@ -1,26 +1,131 @@
# Adafruit_GPS [![Build Status](https://travis-ci.com/adafruit/Adafruit_GPS.svg?branch=master)](https://travis-ci.com/adafruit/Adafruit_GPS) [![Documentation](https://github.com/adafruit/ci-arduino/blob/master/assets/doxygen_badge.svg)](http://adafruit.github.io/Adafruit_GPS/html/index.html)
# Adafruit GPS Library [![Arduino Library CI](https://github.com/adafruit/Adafruit_GPS/actions/workflows/githubci.yml/badge.svg)](https://github.com/adafruit/Adafruit_GPS/actions/workflows/githubci.yml) [![Documentation](https://raw.githubusercontent.com/adafruit/ci-arduino/master/assets/doxygen_badge.svg)](https://adafruit.github.io/Adafruit_GPS/html/index.html)
> **Warning**
>
> This library assumes that only valid, supported NMEA sentences are parsed.
> Parsing invalid or unsupported NMEA sentences may result in memory corruption and/or unhandled faults & exceptions!
Read time, date, location, speed, and altitude from a GPS module in an Arduino
sketch. The library reads NMEA sentences (the text messages sent by the GPS) and
makes supported fields available as variables in your program.
This is the Adafruit GPS library - the ultimate GPS library
for the ultimate GPS module!
Use it with the [Ultimate GPS Breakout](https://www.adafruit.com/product/746),
[GPS FeatherWing](https://www.adafruit.com/product/3133), or
[Mini GPS PA1010D](https://learn.adafruit.com/adafruit-mini-gps-pa1010d-module).
The library supports UART serial, I2C, and SPI connections; choose an interface
your GPS module actually provides. Module-specific configuration commands are
not universal across GPS manufacturers.
Tested and works great with the Adafruit Ultimate GPS module
using MTK33x9 chipset
------> http://www.adafruit.com/products/746
## Getting started
These modules use TTL serial to communicate, 2 pins are required to
interface.
1. In the Arduino IDE Library Manager, search for **Adafruit GPS** and install
**Adafruit GPS Library**, including its offered dependencies. The SD logger
example needs the **SD** library from Arduino.
2. Follow the wiring guide for your module:
[Ultimate GPS](https://learn.adafruit.com/adafruit-ultimate-gps) or
[PA1010D](https://learn.adafruit.com/adafruit-mini-gps-pa1010d-module).
Check its power and signal voltage requirements before connecting it.
3. Open **File > Examples > Adafruit GPS Library** and select an example below.
Choose your board and USB port, then upload the sketch.
4. Open the Serial Monitor at the speed used by `Serial.begin()` in the sketch
(usually **115200 baud**). This is separate from the GPS serial speed, which
is usually **9600 baud** in these examples.
5. Start with an **EchoTest** to check that GPS messages arrive. Then use a
**Parsing** example to display time and position. Put the antenna where it
has a clear view of the sky; receiving text does not mean a position fix has
been acquired yet.
Adafruit invests time and resources providing this open source code,
This README describes the source in this repository. Library Manager releases
may not yet include the latest merged fixes.
## Choosing a connection
| Connection | When to use it | Example setup |
| --- | --- | --- |
| Hardware serial | Your board has a spare serial port, such as `Serial1`. | GPS TX connects to that port's RX; GPS RX connects to its TX. Select the port with `GPSSerial` in the sketch. |
| Software serial | An Uno or Metro 328 uses its main serial port for USB, so you need another pair of pins for the GPS. | The supplied examples use GPS TX to D8 and GPS RX to D7. SoftwareSerial support and usable pins depend on the board. |
| I2C | Your GPS exposes SDA and SCL, as the PA1010D does. | Connect SDA, SCL, power, and ground. Examples use address `0x10`; on an Uno or Metro Mini, SDA is A4 and SCL is A5. |
| SPI | Your GPS specifically supports SPI. | Follow its wiring requirements; the echo example uses CS on D10 and reset on D9. |
## Example guide
Every example is linked below. An **echo** sketch shows the GPS's raw text;
a **parsing** sketch turns that text into individual readings.
| Example | What it does |
| --- | --- |
| [GPS_HardwareSerial_EchoTest](examples/GPS_HardwareSerial_EchoTest/GPS_HardwareSerial_EchoTest.ino) | Passes text between the Serial Monitor and a GPS on `Serial1`. A good first wiring test on a board with a spare serial port. |
| [GPS_HardwareSerial_Parsing](examples/GPS_HardwareSerial_Parsing/GPS_HardwareSerial_Parsing.ino) | Displays time, fix status, position, speed, and altitude from a GPS on `Serial1`. |
| [GPS_HardwareSerial_Timing](examples/GPS_HardwareSerial_Timing/GPS_HardwareSerial_Timing.ino) | Shows how old the last time and position updates are, and how to keep time between GPS messages. |
| [GPS_SoftwareSerial_EchoTest](examples/GPS_SoftwareSerial_EchoTest/GPS_SoftwareSerial_EchoTest.ino) | Shows incoming GPS text using pins D8 and D7. Start here with an Uno or Metro 328 and a serial GPS. |
| [GPS_SoftwareSerial_Parsing](examples/GPS_SoftwareSerial_Parsing/GPS_SoftwareSerial_Parsing.ino) | Reads a serial GPS using D8 and D7 and displays its time, fix status, and location. |
| [GPS_I2C_EchoTest](examples/GPS_I2C_EchoTest/GPS_I2C_EchoTest.ino) | Passes text between the Serial Monitor and an I2C GPS at `0x10`. Start here with a PA1010D. |
| [GPS_I2C_Parsing](examples/GPS_I2C_Parsing/GPS_I2C_Parsing.ino) | Displays time, fix status, position, speed, and altitude from an I2C GPS. |
| [GPS_I2C_OLEDdebug](examples/GPS_I2C_OLEDdebug/GPS_I2C_OLEDdebug.ino) | Currently another Serial Monitor/I2C bridge, despite its name. It does not initialize or draw to an OLED. |
| [GPS_SPI_EchoTest](examples/GPS_SPI_EchoTest/GPS_SPI_EchoTest.ino) | Resets an SPI GPS and passes text between it and the Serial Monitor. Requires an SPI-capable GPS and the reset connection. |
| [shield_sdlog](examples/shield_sdlog/shield_sdlog.ino) | Saves GPS sentences to numbered text files on an SD card using an Uno/Metro 328 logger shield setup. See the logging notes below. |
| [GPS_HardwareSerial_LOCUS_Start](examples/GPS_HardwareSerial_LOCUS_Start/GPS_HardwareSerial_LOCUS_Start.ino) | Starts recording in the GPS module's own LOCUS memory, using `Serial1`. |
| [GPS_SoftwareSerial_LOCUS_Start](examples/GPS_SoftwareSerial_LOCUS_Start/GPS_SoftwareSerial_LOCUS_Start.ino) | Starts LOCUS recording using D8 and D7. |
| [GPS_HardwareSerial_LOCUS_Status](examples/GPS_HardwareSerial_LOCUS_Status/GPS_HardwareSerial_LOCUS_Status.ino) | Starts LOCUS recording, then reports settings, record count, and memory usage from the GPS on `Serial1`. |
| [GPS_SoftwareSerial_LOCUS_Status](examples/GPS_SoftwareSerial_LOCUS_Status/GPS_SoftwareSerial_LOCUS_Status.ino) | Starts LOCUS recording, then reports its settings and memory usage using D8 and D7. |
| [GPS_HardwareSerial_LOCUS_DumpBasic](examples/GPS_HardwareSerial_LOCUS_DumpBasic/GPS_HardwareSerial_LOCUS_DumpBasic.ino) | Requests saved LOCUS records over `Serial1` and prints the raw response. Turns off regular NMEA output first. |
| [GPS_SoftwareSerial_LOCUS_DumpBasic](examples/GPS_SoftwareSerial_LOCUS_DumpBasic/GPS_SoftwareSerial_LOCUS_DumpBasic.ino) | Requests saved LOCUS records using D8 and D7 and prints the raw response. Turns off regular NMEA output first. |
| [GPS_HardwareSerial_LOCUS_Erase](examples/GPS_HardwareSerial_LOCUS_Erase/GPS_HardwareSerial_LOCUS_Erase.ino) | **Erases saved LOCUS records** in the GPS connected to `Serial1`. |
| [GPS_SoftwareSerial_LOCUS_Erase](examples/GPS_SoftwareSerial_LOCUS_Erase/GPS_SoftwareSerial_LOCUS_Erase.ino) | **Erases saved LOCUS records** in the GPS connected to D8 and D7. |
| [NMEA_EXTENSIONS](examples/NMEA_EXTENSIONS/NMEA_EXTENSIONS.ino) | Generates and parses simulated navigation and instrument messages without GPS hardware. Use a board with more RAM than an Uno. |
| [blank](examples/blank/blank.ino) | Leaves the processor idle so a compatible board's USB-to-serial converter can talk directly to the GPS. Uses special wiring in the sketch; it is not the usual D8/D7 connection. |
## Logging
**SD logging** writes files to a separate SD card. The `shield_sdlog` example
uses GPS pins D8/D7, the hardware SPI pins, and SD chip select D10. It writes raw
NMEA text into files such as `GPSLOG00.TXT`. With `LOG_FIXONLY` set to `false`, it
also saves sentences while the GPS has no position fix. Set it to `true` if you
only want records with a fix.
The Uno and Metro 328 have only 2 KB of RAM. SD logging leaves limited room for
additional buffers and variables; keep constant print messages in `F()` when
extending the example. The logger uses AVR-specific code and needs adaptation
for other processor families.
**LOCUS logging** uses memory inside a compatible GPS module and does not need
an SD card. Support depends on the module and its firmware. The Start and Status
examples enable recording; the Erase examples delete saved records. After a
DumpBasic example disables normal NMEA output, run a Parsing example to restore
the usual output configuration.
## Reading data and troubleshooting
- Call `GPS.read()` frequently so incoming data is not lost. When
`GPS.newNMEAreceived()` is true, pass `GPS.lastNMEA()` to `GPS.parse()` and
check its return value before using that sentence's results.
- Check `GPS.fix` before using a position. GPS text and time information can
arrive before a valid location is available. For applications that need fresh
data, also check `GPS.secondsSinceFix()`.
- If the Serial Monitor shows nothing, check its baud rate, the selected USB
port, wiring, and whether the sketch waits for `Serial`. A `while (!Serial)`
wait on a native USB board requires opening the Serial Monitor; remove that
wait when the project must run without a computer.
- Some PA1010D firmware stops responding over I2C in standby and cannot be
woken with an I2C command. `wakeup()` then returns `false` after its response
timeout; recovery may require cycling the GPS module's power. See
[issue #124](https://github.com/adafruit/Adafruit_GPS/issues/124).
- The extended marine/instrument features are normally enabled on non-AVR
boards and disabled on AVR to save space. See
[Adafruit_GPS.h](src/Adafruit_GPS.h) for the `NMEA_EXTRAS` build setting.
> **Parser limitations:** Feed the parser complete, supported NMEA sentences
> from your GPS. Checks reject bad checksums and many incomplete sentences, but
> the parser is not hardened for arbitrary input. Malformed or unsupported input
> may still cause memory corruption or faults.
See the [API documentation](https://adafruit.github.io/Adafruit_GPS/html/index.html)
for constructors, commands, and available data fields. To report a problem,
include your board, GPS model and connection, library version, example or small
reproduction sketch, and the relevant error output or raw NMEA sentences in a
[GitHub issue](https://github.com/adafruit/Adafruit_GPS/issues).
## License and support
Written by Limor Fried/Ladyada for Adafruit Industries.
Distributed under the BSD license; see [license.txt](license.txt).
The copyright and license notices must be included in any redistribution.
Adafruit invests time and resources providing this open source code;
please support Adafruit and open-source hardware by purchasing
products from Adafruit!
Written by Limor Fried/Ladyada for Adafruit Industries.
BSD license, check license.txt for more information
All text above must be included in any redistribution
To install, use the Arduino Library Manager to search for 'Adafruit GPS' and install the library.
products from [Adafruit](https://www.adafruit.com/).