| name | gnss-gps-integration |
| description | Use when integrating a UART GNSS/GPS module (u-blox M8/M9/M10, Quectel Lxx), parsing NMEA GGA/RMC/GSA/GSV or UBX-NAV-PVT, or debugging no-fix, TTFF, checksum, or PPS issues |
GNSS GPS Integration
Overview
Use this skill to connect a GNSS/GPS module to an MCU over UART and turn raw output into a trusted fix. The hard parts are proving the byte stream is intact (NMEA XOR checksum, UBX sync), rejecting invalid fixes, and getting acceptable TTFF given antenna, sky view, and backup-power constraints.
When To Use
Use this skill when:
- The user integrates u-blox
NEO-M8N, NEO-M9N, MAX-M10, or Quectel L76/L80/LC76 over UART.
- The work involves parsing
$GxGGA, $GxRMC, $GxGSA, $GxGSV, the *hh XOR checksum, or the UBX binary protocol (0xB5 0x62, UBX-NAV-PVT).
- Symptoms include no satellites, TTFF too long,
RMC status V, lat/lon of 0, truncated NMEA frames, or PPS not toggling.
- Configuration uses the legacy
UBX-CFG-PRT/UBX-CFG-MSG messages (M8-era), the config-key interface UBX-CFG-VALSET/UBX-CFG-VALGET (M9/M10), or PMTK sentences (PMTK251, PMTK220, PMTK314).
Do not use this skill when the UART link itself is unproven; confirm bytes arrive at the correct baud first.
First Questions
Ask for:
- Exact module and vendor (u-blox M8/M9/M10 vs Quectel Lxx), since protocol and config differ.
- UART baud (u-blox default
9600, Quectel L76 default 9600), wiring (TX/RX crossed, CMOS 3V3 levels).
- Active vs passive antenna, its supply/bias-T, and current sky visibility (indoors vs open sky).
- Backup power: is
V_BCKP/RTC battery or supercap fitted, or does the module lose power fully each cycle?
- Whether the design needs continuous or low-power periodic fixes, and if PPS time sync is required.
- Current raw output (paste a few NMEA lines) and the observed failure.
Integration Checklist
-
Prove the raw stream.
Log UART bytes at the module's default baud before parsing; confirm $G... ASCII lines or UBX 0xB5 0x62 frames, not garbage from a baud mismatch.
-
Validate every sentence.
Compute the XOR of all chars between $ and *, compare to the two hex digits after *, and drop the line on mismatch or missing CR/LF instead of parsing junk.
-
Gate on the fix flag.
Trust position only when RMC status is A (not V) and GGA fix quality is nonzero; treat lat/lon 0,0 as no-fix, and read satellite count/HDOP from GGA, sats-in-view from GSV.
-
Configure output intentionally.
On u-blox M8 use the legacy UBX-CFG-PRT (baud/protocols) and UBX-CFG-MSG (per-message rate); on M9/M10 use the config-key interface UBX-CFG-VALSET/UBX-CFG-VALGET, since the legacy CFG-* messages are deprecated there. Poll or enable UBX-NAV-PVT for a binary fix. On Quectel/MTK use PMTK314 (sentence selection), PMTK220 (update rate), PMTK251 (baud). Save config if the module supports it.
-
Handle startup and backup power.
Expect cold start (~30 s to minutes) when ephemeris is lost; keep V_BCKP/RTC powered so warm/hot starts (seconds) work. Issuing a cold start (PMTK103) or a full cold start (PMTK104, which also clears config) clears aiding data and forces a long TTFF.
-
Wire PPS and low-power correctly.
If timing matters, latch the PPS edge in an ISR and pair it with the time from RMC/UBX-NAV-PVT; for periodic duty cycling, allow re-acquisition time and avoid killing backup power between wakeups.
Common Failures
- No satellites: passive antenna with no bias voltage, antenna indoors/blocked, or open/short on the active-antenna feed (no current = open, excess = short).
- Baud mismatch: reading a
115200 module at 9600 yields framing errors and random bytes.
- Checksum failures or truncated lines: undersized RX buffer, UART overrun, or parsing before a full
\r\n line arrives.
- Every fix is a cold start (long TTFF):
V_BCKP/RTC unpowered, so ephemeris/almanac are lost on each power cycle.
- Position stuck at
0,0 or status V: parser ignores the validity flag and publishes an unfixed solution.
- UBX ignored: wrong sync bytes, class/ID, or a mis-computed 8-bit Fletcher checksum (
CK_A/CK_B) on the CFG message.
Verification
Before claiming the GNSS link works:
- State module, baud, antenna type/power, and protocol (NMEA and/or UBX).
- Show a captured sentence with a checksum you recomputed and confirmed.
- Confirm a real fix:
RMC status A, nonzero GGA quality, plausible lat/lon, sat count and HDOP.
- Report measured TTFF from cold and from warm/hot start, and confirm backup power behavior.
- If used, confirm PPS toggles at 1 Hz and aligns with the reported time.
Example
User:
NEO-M8N 接上了,UART 有数据,但一直定位不了,$GNRMC 的状态一直是 V。
Agent:
- Confirms baud (
9600 default) and captures a few raw lines to verify checksums pass and sentences are complete.
- Reads
GGA fix quality and GSV sats-in-view; asks about antenna type/power and whether the module is under open sky.
- Explains
V means no valid fix yet, checks for a cold start with no V_BCKP backup, and moves the antenna to clear sky to let ephemeris download before expecting status A.
