GPS Module
Real-time location, speed, and heading data recording with offline map display support.
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
- Connect your GPS receiverUART or USB-serial
- Ensure GPS has clear sky viewFor satellite lock
- Enable the GPS moduleFrom the Modules menu
- Wait for device detection and satellite fix
- Start a sessionTo 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 with raw NMEA sentences |
Raw NMEA sentences are preserved in the raw_sentence column of the CSV.
Example: 20251208_143022_GPS_trial001.csv
GPS CSV Columns (25 fields)
| Column | Description |
|---|---|
trial | Trial number (integer, 1-based) |
module | Always “GPS” |
device_id | Device identifier string |
label | User-assigned device label |
record_time_unix | Host Unix timestamp (seconds, 6 decimals) |
record_time_mono | Host monotonic time (seconds, 9 decimals) |
device_time_unix | GPS device time (Unix seconds) |
latitude_deg | Latitude (decimal degrees, + = North) |
longitude_deg | Longitude (decimal degrees, + = East) |
altitude_m | Altitude above mean sea level (meters) |
speed_mps | Speed over ground (meters per second) |
speed_kmh | Speed over ground (km/h) |
speed_knots | Speed over ground (knots) |
speed_mph | Speed over ground (mph) |
course_deg | Course over ground (degrees 0-360) |
fix_quality | Fix type (0=None, 1=GPS, 2=DGPS, etc.) |
fix_mode | Fix mode (1=None, 2=2D, 3=3D) |
fix_valid | Whether fix is valid (boolean) |
satellites_in_use | Satellites in position solution |
satellites_in_view | Total satellites visible |
hdop | Horizontal dilution of precision |
pdop | Position dilution of precision |
vdop | Vertical dilution of precision |
sentence_type | NMEA sentence type (e.g., RMC, GGA) |
raw_sentence | Original NMEA sentence |
Example row:
1,GPS,berrygps_serial0,GPS_Label,1733665822.500000,12345.678901234,1733665822.450000,-37.8136,144.9631,42.5,12.97,46.9,25.3,29.1,185.2,1,3,true,8,12,1.2,2.1,1.8,RMC,"$GPRMC,143022.50,A,3748.816,S,14457.786,E,25.3,185.2,081224,,,A*7C"Timing and Synchronization
Timestamp Types
| Timestamp | Source | Use Case |
|---|---|---|
record_time_unix | Host wall clock | Cross-system time reference |
record_time_mono | Host monotonic clock | Cross-module synchronization |
device_time_unix | GPS satellites | Most accurate absolute time (atomic clock derived) |
Cross-Module Synchronization
Use record_time_mono to correlate GPS with other modules:
- Camera
record_time_mono - Audio
record_time_mono - Use
record_time_unixfor 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 rslogger.modules.GPS.download_offline_tilesTile storage location:
~/.cache/rslogger/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:
- Enable serial port in
raspi-config:- Interfacing Options > Serial
- Login shell: No
- Serial port: Yes
- Reboot
- Verify
/dev/serial0points to the hardware UART
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
- Check UART/serial or USB-serial connection
- Verify correct serial port in config
- Check baud rate matches GPS receiver (typically 9600)
- Test serial connection with a terminal program (e.g., PuTTY, screen, minicom)
No GPS fix
- Move to area with clear sky view
- Wait 1-2 minutes for cold start acquisition
- Check antenna connection if using external antenna
- Verify GPS receiver LED indicates searching
Inaccurate position
- Check number of satellites (need 4+ for 3D fix)
- Move away from buildings/obstructions
- Use external antenna for better reception
- Wait for DGPS correction if available
Map not displaying
- Download offline tiles for your area
- Check internet connection for initial download
- Verify tile cache directory exists
- Check available disk space