GPStracker/gps-test-tool

GPS Test Tool - PC Application

Standalone PC program that reprocesses recorded NMEA logs (or lets you feed NMEA sentences from a live source) through the actual embedded filtering and GPX-generation code from ../soft (gpx.c, nmea.c, autopause.c, syslog.c), unmodified. Useful for reviewing/re-tuning filter behavior against real recorded tracks, and for regression-testing the parser against malformed input, without flashing a device.

How it works

main.h is a single central header that switches between the embedded build and a PC build via #define PC_BUILD:

• Standard C headers (stdio, time, math, ...) instead of AVR headers
• Stub avr/*.h headers (pgmspace.h, interrupt.h, eeprom.h, io.h) so __flash/PROGMEM-style code compiles as plain RAM data
• Stub project headers (stime.h, settings.h, timec.h, expander.h, display headers) that satisfy includes without pulling in embedded-only code
• A FIL/f_*() FatFS-like shim backed by plain FILE*, so gpx.c can write files without linking ff.c

Each *_wrapper.c file just does #define PC_BUILD / #include "main.h" and then #include "../soft/<file>.c", so the real embedded source is compiled as-is, not copied. main.c is the tool's own driver/main() — soft/main.c itself is not part of this build.

Build

cd gps-test-tool
make            # builds ./gps-test-tool
make clean      # removes build artifacts and generated output/debug files

Running

./gps-test-tool <input.nmea>

Each run processes the input file twice — once with filters enabled, once disabled — and produces four files in the current directory:

• output_filtered.gpx / output_unfiltered.gpx — GPX 1.1 tracks
• debug_filtered.txt / debug_unfiltered.txt — per-run debug console output plus a summary (points processed, distance, elevation gain/loss, moving/stopped time, average speeds)

"Filters enabled" mirrors an out-of-the-box device: Kalman filtering, distance/minimum-distance thresholds, 3-point averaging, and auto-pause are all active. "Filters disabled" turns off the distance/Kalman filtering (CONFFLAG_DISABLE_FILTERS) so you can compare raw vs. filtered output for the same input.

Adjusting settings

Device settings can be given as options (defaults in brackets; the ranges the device accepts are in soft/settings.c's limits_min_u8/limits_max_u8):

-A        disable auto-pause                 [enabled]
-t SEC    auto-pause time                    [30]
-d M      auto-pause distance                [10]
-s KMH    auto-pause speed                   [3]
-k N      points skipped after a fix         [0]
-m N      minimum satellites                 [4]
-v        verbose system log

The auto-pause defaults match soft/settings.c's out-of-the-box defaults.

Single run

-o FILE makes a single run with the given settings instead of the filtered/unfiltered pair, writing only that GPX file. -l FILE also writes its debug output, and -n disables filters:

./gps-test-tool -o out.gpx -l out.txt -n -t 60 input.nmea

Input format

Plain text, one NMEA sentence per line (\n or \r\n), the same as a device's raw log file. The parser only acts on recognized sentences (RMC, GGA, GSA, VTG, ...); unrelated lines are ignored. Example minimal input:

$GPRMC,123519,A,4807.038,N,01131.000,E,022.4,084.4,230394,003.1,W*6A
$GPGGA,123519,4807.038,N,01131.000,E,1,08,0.9,545.4,M,46.9,M,,*47

GUI

make gui                          # builds ./gps-test-tool-gui too (needs GTK3, libsoup3)
./gps-test-tool-gui [input.nmea]

Shows the input NMEA track (thin dark line) and the resulting GPX track (one colour per <trkseg>, i.e. per pause-separated segment) on an OpenStreetMap background. The GPX is produced by running gps-test-tool -o (looked up next to the GUI binary, then in PATH), so it is always the same result the command-line tool gives. Changing any setting in the side panel reprocesses the file immediately; the summary from the debug output is shown below the settings. "Save GPX..." stores the current result.

• Mouse wheel zooms around the cursor, left-drag pans, "Zoom to fit" goes back to the whole track.
• Coordinates under the cursor are shown in the bottom bar; a left click freezes them (and marks the point), a right click releases them.
• Settings, the last file and the window size are remembered in ~/.config/gps-test-tool/gui.ini; map tiles are cached in ~/.cache/gps-test-tool/tiles.

Automated tests

A regression test (test-malformed) feeds the real gps_parse() a fixture of real and synthetic edge-case NMEA sentences (malformed_test.nmea): truncated lines, bad checksums, invalid epochs, short dialect variants, and a run long enough to exercise HDOP-based speed-sample gating.

make run-test-malformed

This builds test-malformed and runs it against malformed_test.nmea. It asserts that:

• nothing crashes the parser, regardless of how malformed a line is (run under valgrind/ASan for a stronger guarantee than "exited zero")
• invalid-epoch lines (RMC status V, VTG mode N) do not add a speed sample
• a genuinely poor-quality fast sample (bad HDOP) is excluded from the speed average outright
• a genuinely fast, good-quality sample is capped rather than excluded or let through raw

To run it against a different fixture file:

./test-malformed path/to/other.nmea

Any non-zero exit / FAIL: line means a check failed.