GPS Tracker V1

GPS RTK Tracker

Firmware, dashboard, and prototype PCB files for a portable RTK GNSS tracker built around a Heltec WiFi LoRa 32 V4 and a Waveshare/Quectel LG290P receiver.

The tracker reads high-rate NMEA from the LG290P, forwards NTRIP/RTCM corrections over WiFi, shows live fix state on the OLED and RGB LED, serves a phone-friendly surveying dashboard, and can send compact low-rate location uplinks to The Things Network (TTN).

This started as an EE 2185 Circuits Design Project at the University of Vermont. The hardware and firmware are now in a working prototype state and are published under the MIT License.

Table Of Contents

• Current Status
• What It Does
• Prototype Warnings
• Hardware
• Quick Start
• Configuration
• Web Dashboard
• NTRIP And RTK
• TTN LoRaWAN
• PCB Files
• Power Path
• Pin Notes
• API And Exports
• Packet Formats
• Troubleshooting
• Repository Layout
• License

Current Status

Working and field-tested:

• GNSS UART parsing from the LG290P at 460800 baud
• OLED display using the stable manual Heltec V4 display path
• RGB fix-status LED
• Battery ADC reading with board-specific calibration
• WiFi station mode, setup/offline AP mode, and saved WiFi profiles
• NTRIP client with live RTCM forwarding to the GNSS module
• RTK Float in field testing with live RTCM bytes
• ESP32-hosted dashboard with maps, precision plots, logs, survey marks, and CSV/JSON/GeoJSON/KML exports
• TTN OTAA join and app-port-2 uplinks on US915 FSB2
• Custom through-hole V1 PCB bring-up, charging, and power routing

Still prototype-grade:

• RTK Fixed has not yet been made stable in controlled field testing.
• Charger and LDO temperatures need conservative limits before enclosure use.
• The first assembled PCB needed battery-voltage calibration and has RGB red and blue physically swapped; firmware compensates.

What It Does

The firmware has three major jobs:

1. RTK rover operation: read live position from the LG290P, connect to an NTRIP caster over WiFi, send rover GGA to the caster, and forward binary RTCM corrections back to the receiver.
2. Field dashboard: host a lightweight dashboard directly from the ESP32 so a phone or laptop can view position, fix quality, precision, RTK state, satellites, logs, setup, and survey marks.
3. Low-rate radio reporting: send tiny position packets either over direct P2P LoRa or over TTN LoRaWAN. TTN is for breadcrumbs and marked points, not high-rate live tracking.

What it does not do:

• It does not provide RTK corrections over LoRaWAN. RTK corrections still come from NTRIP over WiFi/hotspot.
• It does not use paid map APIs. The embedded dashboard uses browser-loaded map tiles and simple outbound Google Maps links.
• It is not yet a certified surveying instrument. Treat it as an educational and prototype field tool.

Prototype Warnings

Read this before copying the hardware design:

• Battery/charger safety: the MCP73831 is a linear Li-Ion charger. The original 2 kOhm PROG resistor sets roughly 500 mA and can run hot in a SOT-23-5 package. Use a lower current such as 200 mA with 5 kOhm, or 100 mA with 10 kOhm, unless you have verified board and enclosure thermals.
• Regulator heat: when the tracker is on and powered from USB, the 3.3 V LDO can become the dominant hot part. Check it with the real GNSS, WiFi, OLED, and radio load.
• RTK Fixed depends on antenna conditions: good WiFi is not enough. You need a stable antenna, low multipath, good sky view, compatible RTCM, and enough still convergence time.
• Open setup AP: GPS-RTK-Setup is intentionally open for easy field setup. Use it briefly and locally; do not leave it active around untrusted users.
• Secrets: the tracked repo contains no WiFi, NTRIP, TTN, or Heltec license secrets. Keep real credentials in ignored config_private.h or in the dashboard's ESP32 Preferences storage.

Hardware

Known-good target:

The LG290P antenna quality and placement matter a lot. For RTK Fixed testing, use a stable outdoor antenna setup with low multipath and a suitable ground plane if the antenna expects one.

Quick Start

1. Install Board Support

Use Arduino IDE or arduino-cli with the Heltec ESP32 Dev-Boards package. Select:

Avoid mixing old Heltec V3 helper libraries into this project.

2. Compile

Known-good CLI command:

arduino-cli compile \
  --fqbn Heltec-esp32:esp32:heltec_wifi_lora_32_V4:CDCOnBoot=cdc,PartitionScheme=app3M_fat9M_16MB,LORAWAN_REGION=3 \
  --build-path /tmp/gps_rtk_tracker_build \
  .

LORAWAN_REGION=3 is important for TTN US915. If the firmware is compiled for EU868, TTN joins in Vermont will fail even when the keys are correct.

3. Add Private Credentials

For compile-time defaults, copy:

cp config_private.example.h config_private.h

Then fill in WiFi and NTRIP values in config_private.h. That file is ignored by Git.

You can also leave compile-time credentials blank and configure WiFi/NTRIP/TTN from the dashboard Setup tab.

4. Flash And Open Serial

Open Serial Monitor at 115200 baud with USB CDC On Boot enabled. On startup, look for:

=== GPS RTK Tracker ===
[GNSS] UART1 started at 460800 bps
[WEB] Dashboard listening on port 80

When WiFi connects, Serial and the OLED show the board IP. Open:

http://<board-ip>/

If WiFi is missing or fails, connect to the open setup AP:

SSID: GPS-RTK-Setup
URL:  http://192.168.4.1/setup

Configuration

Compile-time defaults live in config.h and optional private overrides live in config_private.h.

Common compile-time values:

Dashboard-saved values take priority over compile-time defaults. The Setup tab can save:

• WiFi profiles
• NTRIP caster, port, mountpoint, username, and password
• Radio mode: off, P2P LoRa, or TTN LoRaWAN
• P2P TX enable
• TTN DevEUI, JoinEUI/AppEUI, AppKey, sub-band, and transmit options

Blank password/key fields preserve the existing saved value. Type a new secret only when you want to replace it.

Web Dashboard

The ESP32 hosts a small dependency-free dashboard using WiFiServer. It is available when the tracker is connected to normal WiFi, and a simplified offline/setup page is available from GPS-RTK-Setup.

Dashboard tabs:

Map notes:

• The online dashboard uses Leaflet in the phone browser.
• Burlington/Vermont testing includes Vermont VCGI orthoimagery, plus OpenStreetMap and Esri fallbacks.
• The ESP32 does not download map tiles. Your phone or laptop does.
• Google Maps is used only as an outbound coordinate link, not as an embedded paid JavaScript API.

Offline/setup page notes:

• No internet assets, no Leaflet, and no external CSS/JS.
• Shows position, fix quality, battery, RTK status, logs, cached WiFi scan results, saved WiFi profiles, local track plot, survey marks, and sky view.
• Manual rescan briefly drops GPS-RTK-Setup, scans in station-only mode, caches results, and restarts the AP.

NTRIP And RTK

The NTRIP client:

1. Connects to station WiFi.
2. Opens the caster/mountpoint TCP connection.
3. Checks for a valid response such as ICY 200 OK.
4. Sends rover GGA to VRS mountpoints.
5. Forwards binary RTCM bytes to the LG290P.

Healthy RTK transport looks like:

[NTRIP] Caster response: ICY 200 OK
[NTRIP] Stream active - receiving RTCM
[NTRIP] First RTCM bytes received

RTK Float means the receiver is using corrections but has not resolved carrier phase ambiguities tightly enough for RTK Fixed. If RTCM bytes are increasing and the fix reaches RTK Float, WiFi/NTRIP is probably working. Persistent Float is usually an antenna, multipath, receiver configuration, or correction-message compatibility problem.

For RTK Fixed testing:

• Keep the antenna completely still for several minutes.
• Use open sky, away from windows, walls, vehicles, metal railings, roofs, and trees.
• Use a ground plane when the antenna type expects one.
• Confirm the mountpoint is intended for your region and emits compatible multi-constellation RTCM, ideally MSM messages.
• Capture the RTK tab and Serial log if Float is stable but Fixed never appears.

TTN LoRaWAN

TTN is for low-rate location reporting when WiFi is not the main display path. It is not for centimeter-rate plotting and does not carry RTK corrections.

Recommended TTN setup:

1. Create a TTN application.
2. Register an end device manually with OTAA.
3. Use frequency plan United States 902-928 MHz, FSB 2 (used by TTN).
4. Use LoRaWAN 1.0.x settings.
5. Generate or enter:
   • DevEUI: 16 hex characters
   • JoinEUI/AppEUI: 16 hex characters
   • AppKey: 32 hex characters
6. In the tracker Setup tab, choose TTN LoRaWAN, enter the values, choose the US915 sub-band, save, and reboot.
7. Watch TTN Console Live Data for join and uplink events.

Important TTN notes:

• Serial prints the compiled LoRaWAN region and channel mask at boot. For US915 FSB2, the region should be US915 and the mask should include FF00 plus 0002 in the fifth word.
• The Heltec LoRaWAN stack needs the board's chip-specific Heltec license. If Serial prints Please provide a correct license!, use Heltec's license lookup for the printed ESP32ChipID, send AT+CDKEY=<32 hex chars> in Serial Monitor, and reboot.
• If bad TTN settings make the tracker hang during radio startup, hold the Heltec PRG/BOOT button while resetting. Safe mode forces radio off for that boot and starts setup/offline mode.
• Uplinks are unconfirmed by default to avoid downlink usage.
• TTN Sandbox fair use is small: keep payloads tiny and breadcrumb intervals in minutes, not seconds.

Manual survey marks are prioritized over breadcrumbs. If the LoRaWAN MAC is busy, a pending mark remains queued and retries instead of being silently dropped.

TTN Payload Decoder

Use this JavaScript uplink decoder in TTN for app port 2:

function s32(b, i) {
  var v = (b[i] << 24) | (b[i + 1] << 16) | (b[i + 2] << 8) | b[i + 3];
  return v;
}

function s16(b, i) {
  var v = (b[i] << 8) | b[i + 1];
  return v & 0x8000 ? v - 0x10000 : v;
}

function decodeUplink(input) {
  var b = input.bytes;
  if (b.length !== 16) {
    return { data: {}, errors: ["expected 16 byte GPS RTK payload"] };
  }
  return {
    data: {
      kind: b[0] === 2 ? "mark" : "breadcrumb",
      sequence: b[1],
      latitude: s32(b, 2) / 10000000,
      longitude: s32(b, 6) / 10000000,
      altitude_m: s16(b, 10) / 10,
      fix_type: b[12],
      battery_percent: b[13],

PCB Files

PCB files are in hardware/GPS_Tracker_V1/.

gerbers_v2 is the preferred fabrication set. Older working Gerbers are not included because they had earlier outline, hole, and archive-cleanliness issues.

Before ordering another board:

1. Open the KiCad project and run DRC.
2. Inspect gerbers_v2 in the manufacturer viewer.
3. Confirm the three mounting holes are drilled/routed as intended.
4. Decide whether R1 should be changed for lower charge current.
5. Confirm the BOM matches the actual assembly method and footprints.

Power Path

The custom PCB has its own USB-C charger and 3.3 V supply path:

USB-C VBUS -> +5V -> MCP73831 charger -> VBAT
USB-C VBUS -> +5V -> MAX40200 ideal diode -> SYS_IN
Battery JST -> VBAT -> MAX40200 ideal diode -> SYS_IN
SYS_IN -> power switch -> SYS_SW -> XC6220 3.3 V regulator -> 3V3 rails

Practical behavior:

The custom board does not intentionally feed its +5V net into the Heltec 5 V pin. Be careful when multiple USB cables are connected during debugging.

Pin Notes

Final firmware pin choices for the assembled PCB:

Heltec V4 labels worth preserving:

Low-Power Battery Divider

The intended switched divider:

VBAT -> P-MOS source
P-MOS drain -> 390k -> VBAT_SENSE -> 100k -> GND
VBAT_SENSE -> GPIO6
0.1 uF from VBAT_SENSE to GND

P-MOS gate -> 1M -> VBAT
P-MOS gate -> NPN collector
NPN emitter -> GND
GPIO37 -> 10k -> NPN base
NPN base -> 100k -> GND  optional pulldown

Behavior:

• GPIO37 LOW: divider off.
• GPIO37 HIGH: NPN pulls the P-MOS gate low, divider turns on, GPIO6 reads battery voltage.
• Recheck VBAT_CALIBRATION_SCALE with a multimeter if the resistor values, ADC wiring, or PCB revision changes.

API And Exports

Useful dashboard endpoints:

Large responses are streamed in small batches so GNSS, NTRIP, LoRa, and tracker logic keep running between chunks.

Packet Formats

P2P LoRa Packet

The direct P2P LoRa position packet is 14 bytes:

TTN Packet

The TTN position payload is 16 bytes on app port 2:

Troubleshooting

gps-rtk.local Does Not Resolve

Use the IP shown on the OLED or in Serial Monitor. Phone hotspots and some mobile browsers often do not resolve mDNS reliably.

No RTCM Bytes

If rtcm=0B stays at zero after the caster accepts the connection:

• Confirm the caster response is ICY 200 OK or another success response.
• Confirm the RTK tab shows rover GGA being sent.
• Try a known nearby mountpoint.
• Check NTRIP username/password and mountpoint spelling.
• Confirm the phone/hotspot has real internet, not only local WiFi.

RTK Float But No RTK Fixed

If RTCM bytes are increasing and fix quality reaches RTK Float, the correction path is alive. For Fixed, improve antenna conditions and check receiver/caster compatibility. Multipath near windows, buildings, vehicles, and metal surfaces is the usual enemy.

TTN Joins But Payload Shows {}

The TTN decoder returns {} when the payload length is not the expected 16-byte app-port-2 tracker payload. Check that the uplink is on app port 2 and that you pasted the decoder from this README into the TTN payload formatter.

Second TTN Mark Does Not Appear Immediately

Manual marks are rate-limited and the LoRaWAN MAC can be busy. The firmware keeps pending marks queued and retries them, but TTN is intentionally slow. Use multi-minute breadcrumbs and avoid rapid repeated mark sends unless testing.

OLED Resets Or USB Reconnects

Do not use the standard Heltec.display path for this project. The stable Heltec V4 display path is:

1. Start Heltec with built-in display disabled.
2. Enable Vext.
3. Initialize a dedicated SSD1306Wire instance.

The current display.cpp already does this.

Repository Layout

License

This project is released under the MIT License. See LICENSE.