ESP32/doc/GPS_WIRING.md

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 (or gps 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=1 in board_config.h triggers on falling edge. If it still fails, try setting GPS_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 nmea for $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