8.8 KiB
GPS Module Wiring Guide
Overview
This guide shows how to connect a GPS module (e.g., MakerFocus GT-U7, NEO-6M) to the ESP32 boards supported by this firmware. The GPS provides NMEA sentences for position/time and an optional PPS (pulse-per-second) signal for precise timing.
Supported GPS Modules
- MakerFocus GT-U7 (recommended) — 3.3V compatible, NMEA output, PPS, 9600 baud default
- NEO-6M — Same pinout and NMEA format
Connections Required
| GPS Pin | ESP32 Side | Function |
|---|---|---|
| VCC | 3.3V | Power (3.3V only) |
| GND | GND | Ground |
| TXD | ESP32 RX | NMEA data from GPS → ESP32 |
| RXD | ESP32 TX | Optional: config/commands to GPS |
| PPS | GPIO input | Pulse-per-second (optional but recommended) |
Note: TX and RX are crossed: GPS TXD → ESP32 RX, GPS RXD → ESP32 TX.
Power with SD card: If you also use the SparkFun microSD breakout, J1 Pin 1 (3.3V) and J1 Pin 15 (GND) must use Y-cables: one branch to the GPS, one to the SD breakout, so both devices are powered from the same 3.3V and GND. See SD_CARD_WIRING.md for the combined pin diagram.
ESP32-C5 (DevKitC-1)
Wiring Table
| GPS Module Pin | ESP32-C5 GPIO | Header Location | Function |
|---|---|---|---|
| VCC | 3V3 | J1 Pin 1 (Left) | Power |
| GND | GND | J1 Pin 15 (Left) | Ground |
| TXD (NMEA out) | GPIO23 (RX) | J3 Pin 5 (Right) | GPS → ESP32 |
| RXD (config in) | GPIO24 (TX) | J3 Pin 4 (Right) | ESP32 → GPS (optional) |
| PPS | GPIO1 | J1 Pin 6 (Left) | Pulse per second |
Note: GPIO25 (J1 Pin 13) is a strapping pin and can interfere with PPS input; the firmware uses GPIO1 (J1 Pin 6) instead.
Quick Wiring (5 wires)
GT-U7 VCC → J1 Pin 1 (3V3) [use Y-cable if also powering SD breakout]
GT-U7 GND → J1 Pin 15 (GND) [use Y-cable if also powering SD breakout]
GT-U7 TXD → J3 Pin 5 (GPIO23) — ESP32 RX
GT-U7 RXD → J3 Pin 4 (GPIO24) — ESP32 TX
GT-U7 PPS → J1 Pin 6 (GPIO1)
Minimal Wiring (4 wires, no config)
GT-U7 VCC → J1 Pin 1 (3V3)
GT-U7 GND → J1 Pin 15 (GND)
GT-U7 TXD → J3 Pin 5 (GPIO23)
GT-U7 PPS → J1 Pin 6 (GPIO1)
Pin Locations (J1 / J3)
| J1 (Left) | Pin | J3 (Right) | Pin |
|---|---|---|---|
| 3V3 | 1 | GND | 1 |
| RST | 2 | TX (UART0) | 2 |
| ... | ... | RX (UART0) | 3 |
| ... | ... | GPIO24 | 4 ← GPS RXD |
| ... | ... | GPIO23 | 5 ← GPS TXD |
| GPIO1 | 6 ← PPS | ... | ... |
| ... | ... | ... | ... |
| GPIO25 | 13 | ... | ... (strapping, avoid for PPS) |
| 5V | 14 (do not use) | ... | ... |
| GND | 15 | ... | ... |
ESP32-S3 (DevKitC-1)
| GPS Module Pin | ESP32-S3 GPIO | Function |
|---|---|---|
| VCC | 3V3 | Power |
| GND | GND | Ground |
| TXD | GPIO4 (RX) | GPS → ESP32 |
| RXD | GPIO5 (TX) | ESP32 → GPS (optional) |
| PPS | GPIO6 | Pulse per second |
Quick Wiring
GT-U7 VCC → 3V3
GT-U7 GND → GND
GT-U7 TXD → GPIO4 (RX)
GT-U7 RXD → GPIO5 (TX)
GT-U7 PPS → GPIO6
ESP32 (Original / Standard)
| GPS Module Pin | ESP32 GPIO | Function |
|---|---|---|
| VCC | 3V3 | Power |
| GND | GND | Ground |
| TXD | GPIO16 (RX) | GPS → ESP32 |
| RXD | GPIO17 (TX) | ESP32 → GPS (optional) |
| PPS | GPIO4 | Pulse per second |
Quick Wiring
GT-U7 VCC → 3V3
GT-U7 GND → GND
GT-U7 TXD → GPIO16 (RX)
GT-U7 RXD → GPIO17 (TX)
GT-U7 PPS → GPIO4
PPS Polarity
The firmware supports both rising-edge and falling-edge (active-low) PPS. Many u-blox GT-U7/NEO-6M modules use active-low PPS (line pulls low for ~100 ms at each second). The default is GPS_PPS_ACTIVE_LOW=1 in board_config.h. If PPS Lock shows NO despite correct wiring, try flipping this (set to 0 for rising-edge).
Important Notes
⚠️ Warnings:
- Use 3.3V only — Do not connect GPS VCC to 5V; many modules are 3.3V logic.
- TX ↔ RX crossover — GPS TXD connects to ESP32 RX; GPS RXD connects to ESP32 TX.
- Avoid strapping pins (e.g., GPIO2, GPIO3 on ESP32-C5) for general I/O.
Testing
After wiring, use the gps console command to check NMEA output and fix status. Example:
gps status
gps nmea
Troubleshooting
NMEA Valid: NO
- TX/RX swapped — GPS TXD must go to ESP32 RX (GPIO23 on C5). If you swapped them, NMEA won't parse.
- Wrong pins — Double-check GPIO numbers. Older guides (e.g.
esp32-c5-gps-sync-guide.html) use GPIO4/5 for UART; the firmware expects GPIO23/24. - No satellite fix — Move the antenna near a window or outdoors. Cold start can take 1–2 minutes.
- Power — Ensure VCC is 3.3V. Some modules draw more current during acquisition.
PPS Locked: NO (but NMEA Valid: YES)
- Verify signal — Run
gps pps-test(orgps pps-test -d 5) to poll the PPS GPIO. If no edges are detected, the signal isn't reaching the ESP32. - Wrong PPS pin — The firmware expects PPS on GPIO1 (J1 Pin 6). GPIO25 (Pin 13) is a strapping pin and can interfere; use Pin 6 instead.
- PPS polarity — Many u-blox modules use active-low PPS. The default
GPS_PPS_ACTIVE_LOW=1inboard_config.htriggers on falling edge. If it still fails, try settingGPS_PPS_ACTIVE_LOW=0(rising-edge). - PPS not enabled — Some modules need UBX configuration to output PPS. GT-U7 usually outputs it by default once a fix is acquired.
- Loose connection — PPS is a 1 Hz signal; a bad connection will cause missed edges.
No Time / No Fix
- Antenna — Active antennas need power; ensure the module’s antenna connector matches. Outdoor or window placement helps.
- Startup delay — Allow 1–2 minutes for cold start. Check
gps nmeafor $GPGGA with "A" (valid) vs "V" (invalid).
Documentation Mismatch
If you followed doc/esp32-c5-gps-sync-guide.html, note its pinout differs from the current firmware:
| Signal | Old guide | Current firmware |
|---|---|---|
| RX (GPS TXD) | GPIO4, J3 Pin 8 | GPIO23, J3 Pin 5 |
| TX (GPS RXD) | GPIO5, J3 Pin 9 | GPIO24, J3 Pin 4 |
| PPS | GPIO1, J1 Pin 6 | GPIO1, J1 Pin 6 ✓ (same) |
Use the pinout in this document for compatibility with the firmware.
Configuration Source
Pin assignments are defined in main/board_config.h. To change pins for a custom board, edit the appropriate #elif defined (CONFIG_IDF_TARGET_...) block.
Complete Pin Reference (ESP32-C5)
The following table shows all pins for both the SparkFun microSD breakout and the GPS module (MakerFocus GT-U7 / NEO-6M), and how they map to the ESP32-C5 DevKit.
SparkFun microSD Transflash Breakout — All Pins
| SparkFun Pin | Label | ESP32-C5 | J1 Pin | Function |
|---|---|---|---|---|
| 1 | VCC | 3V3 | 1 | Power (3.3V only) |
| 2 | GND | GND | 15 | Ground |
| 3 | SCK | GPIO9 | 10 | SPI clock |
| 4 | MOSI / DI | GPIO10 | 11 | Data in to card |
| 5 | MISO / DO | GPIO8 | 9 | Data out from card |
| 6 | CS | GPIO7 | 8 | Chip select |
| 7 | CD | GPIO26 | 12 | Card detect (LOW = inserted) |
Note: Pin numbering may vary by SparkFun breakout revision. Some boards use DI/DO labels; DI = MOSI, DO = MISO.
GPS Module (GT-U7 / NEO-6M) — All Pins
| GPS Pin | Label | ESP32-C5 | J1/J3 | Function |
|---|---|---|---|---|
| 1 | VCC | 3V3 | J1 Pin 1 | Power (3.3V only) |
| 2 | GND | GND | J1 Pin 15 | Ground |
| 3 | TXD | GPIO23 (RX) | J3 Pin 5 | NMEA data out → ESP32 RX |
| 4 | RXD | GPIO24 (TX) | J3 Pin 4 | Config in ← ESP32 TX (optional) |
| 5 | PPS | GPIO1 | J1 Pin 6 | Pulse per second |
Note: GPS and ESP32 may share VCC/GND with the SD card if powered from the same 3V3 rail.
Combined ESP32-C5 J1 Header (Left Side)
| Pin | Signal | SparkFun | GPS | Notes |
|---|---|---|---|---|
| 1 | 3V3 | VCC | VCC | Shared power |
| 2 | RST | — | — | Do not connect |
| 3 | GPIO2 | — | — | Strapping pin |
| 4 | GPIO3 | — | — | Strapping pin |
| 5 | GPIO0 | — | — | Boot mode |
| 6 | GPIO1 | — | PPS | GPS pulse |
| 7 | GPIO6 | — | — | — |
| 8 | GPIO7 | CS | — | SD chip select |
| 9 | GPIO8 | MISO (DO) | — | SD data out |
| 10 | GPIO9 | CLK (SCK) | — | SD clock |
| 11 | GPIO10 | MOSI (DI) | — | SD data in |
| 12 | GPIO26 | CD | — | SD card detect |
| 13 | GPIO25 | — | — | Strapping (avoid for PPS) |
| 14 | 5V | — | — | Do not use |
| 15 | GND | GND | GND | Shared ground |
| 16 | NC | — | — | No connection |
Combined ESP32-C5 J3 Header (Right Side)
| Pin | Signal | SparkFun | GPS | Notes |
|---|---|---|---|---|
| 1 | GND | — | — | — |
| 2 | TX (UART0) | — | — | USB bridge |
| 3 | RX (UART0) | — | — | USB bridge |
| 4 | GPIO24 | — | RXD | ESP32 TX → GPS RXD |
| 5 | GPIO23 | — | TXD | GPS TXD → ESP32 RX |