Software / Documentation / GPS

GPS Module

Real-time location, speed, and heading data recording with offline map display support.

Raspberry Pi Only

This module is designed for Raspberry Pi with the BerryGPS or BerryGPS-IMU from Ozzmaker. Other GPS receivers may work but are not officially supported.

The GPS module records location, speed, and heading data from a BerryGPS receiver during experiment sessions. It provides real-time position tracking and can display your route on an offline map.

Getting Started

  1. Connect your GPS receiver — UART or USB-serial
  2. Ensure GPS has clear sky view — For satellite lock
  3. Enable the GPS module — From the Modules menu
  4. Wait for device detection and satellite fix
  5. Start a session — To begin recording

User Interface

Map Display

Shows current position on an offline map:

  • Blue dot indicates current location
  • Trail shows recent path
  • Map tiles are cached for offline use

Telemetry Panel

Real-time GPS data:

Field Description
Latitude/Longitude Current coordinates in decimal degrees
Speed Current velocity (km/h or mph)
Heading Direction of travel (0-360 degrees)
Altitude Height above sea level (meters)
Satellites Number of satellites in view
Fix Quality GPS fix status (No Fix, 2D, 3D, DGPS)

Recording Sessions

Starting Recording

When you start a recording session:

  • GPS data logging begins immediately
  • Position updates recorded at receiver rate (typically 1-10 Hz)
  • Status shows connection and fix quality

During Recording

Each data point captures:

  • Timestamp (UTC from GPS satellites)
  • Latitude and longitude
  • Speed and heading
  • Altitude and fix quality
  • Number of satellites and accuracy metrics

Data Output

File Location

{session_dir}/GPS/

Files Generated

File Description
{timestamp}_GPS_trial{NNN}.csv Parsed GPS data
{timestamp}_NMEA_trial{NNN}.txt Raw NMEA sentences (optional)

Example: 20251208_143022_GPS_trial001.csv

GPS CSV Columns (21 fields)

Column Description
Module Always "GPS"
trial Trial number (integer, 1-based)
timestamp_utc GPS UTC time (ISO 8601 format)
timestamp_unix Unix timestamp (seconds, 6 decimals)
record_time_mono Host monotonic time (seconds, 9 decimals)
latitude Latitude (decimal degrees, + = North)
longitude Longitude (decimal degrees, + = East)
altitude_m Altitude above mean sea level (meters)
geoid_separation_m Geoid separation (meters)
speed_knots Speed over ground (knots)
speed_kmh Speed over ground (km/h)
speed_mph Speed over ground (mph)
heading_true True heading (degrees 0-360)
heading_magnetic Magnetic heading (degrees)
fix_quality Fix type (0=None, 1=GPS, 2=DGPS, etc.)
fix_type Fix mode (1=None, 2=2D, 3=3D)
satellites_used Satellites in position solution
satellites_in_view Total satellites visible
hdop Horizontal dilution of precision
vdop Vertical dilution of precision
pdop Position dilution of precision

Example row:

GPS,1,2024-12-08T14:30:22.500Z,1733665822.500000,12345.678901234,-37.8136,144.9631,42.5,0.0,25.3,46.9,29.1,185.2,184.8,1,3,8,12,1.2,1.8,2.1

Timing and Synchronization

Timestamp Types

Timestamp Source Use Case
timestamp_utc GPS satellites Most accurate absolute time (atomic clock derived, ±100 ns)
timestamp_unix GPS time as Unix seconds Cross-system time reference
record_time_mono Host monotonic clock Cross-module synchronization

Cross-Module Synchronization

Use record_time_mono to correlate GPS with other modules:

  • Camera encode_time_mono
  • Audio write_time_monotonic
  • Use timestamp_unix for absolute time reference

DOP Values (Dilution of Precision)

DOP Quality Position Accuracy
< 1.0 Ideal Sub-meter
1-2 Excellent ~1-2 meters
2-5 Good ~5-10 meters
5-10 Moderate ~50 meters
> 10 Poor Consider waiting for better fix

GPS Fix Quality

Fix Type Satellites Description
No Fix < 3 Insufficient satellites visible
2D Fix 3 Position available (lat/lon) but no altitude
3D Fix 4+ Full position including altitude
DGPS 4+ Differential correction applied (sub-meter accuracy)

Configuration

Setting Default Notes
Serial Port /dev/serial0 Raspberry Pi hardware UART
Baud Rate 9600 BerryGPS default; do not change unless you've reconfigured the GPS
Update Rate 1 Hz BerryGPS default; can be configured up to 10 Hz

Offline Maps

The module uses pre-downloaded map tiles for offline display.

Download tiles for your area:

python -m rpi_logger.modules.GPS.download_offline_tiles

Tile storage location:

~/.cache/rpi_logger/map_tiles/

Hardware Setup

BerryGPS from Ozzmaker

This module is designed for use with the BerryGPS or BerryGPS-IMU connected to your Raspberry Pi's UART header. See the Ozzmaker Quick Start Guide for hardware installation.

Serial Port

The BerryGPS connects via the Raspberry Pi's hardware UART at /dev/serial0 (default baud rate: 9600).

Raspberry Pi UART Setup

Enable the serial port for GPS communication:

  1. Enable serial port in raspi-config:
    • Interfacing Options > Serial
    • Login shell: No
    • Serial port: Yes
  2. Reboot
  3. Verify /dev/serial0 points to the hardware UART

Pi 5 Only

Add dtparam=uart0_console to /boot/firmware/config.txt

Verifying GPS Connection

Test with a terminal program before launching:

  • You should see NMEA sentences like $GPRMC, $GPGGA, etc.
  • Data arrives at the configured baud rate (typically 9600)

Troubleshooting

Device not detected
  1. Check UART/serial or USB-serial connection
  2. Verify correct serial port in config
  3. Check baud rate matches GPS receiver (typically 9600)
  4. Test serial connection with a terminal program (e.g., PuTTY, screen, minicom)
No GPS fix
  1. Move to area with clear sky view
  2. Wait 1-2 minutes for cold start acquisition
  3. Check antenna connection if using external antenna
  4. Verify GPS receiver LED indicates searching
Inaccurate position
  1. Check number of satellites (need 4+ for 3D fix)
  2. Move away from buildings/obstructions
  3. Use external antenna for better reception
  4. Wait for DGPS correction if available
Map not displaying
  1. Download offline tiles for your area
  2. Check internet connection for initial download
  3. Verify tile cache directory exists
  4. Check available disk space