# 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 |