242 lines
8.8 KiB
Markdown
242 lines
8.8 KiB
Markdown
# 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](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 |
|