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

**Current status:** the build is broken at the moment. `soft/main.c` (not
yet committed) added `tracking_is_paused()`, which `soft/gpx.c` and
`soft/nmea.c` now call, but `soft/main.c` itself isn't compiled into this
PC tool (it has its own driver, `main.c`), and no stub for
`tracking_is_paused()` exists here yet. This tool already has an analogous
stub for `is_paused()` in `gpx_wrapper.c`/`main.h` — `tracking_is_paused()`
needs the same treatment before `make` will succeed again.

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

There's no command-line or interactive settings UI. To try different
device settings against a log, edit the defaults in `reset_system()` in
`main.c` (around line 67) and rebuild:

```c
System.conf.skip_points = 0;
System.conf.auto_pause_time = 30;   // seconds
System.conf.auto_pause_dist = 10;   // meters
System.conf.auto_pause_speed = 3;   // km/h
System.conf.min_sats = 4;           // minimum satellites for a valid fix
```

These match `soft/settings.c`'s out-of-the-box defaults, so start from a
known-good baseline before changing them.

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

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