Menu
Build systematic collection of packet logs for a GPS receiver, covering all implemented decode paths per plan/packet-testing.md
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
Create, edit, comment on, and label GitHub issues following the project's style
Implement gpsprot high-level (device-independent) configuration - the ConfigProtocol/Configurator - for a new GPS receiver protocol family
Drive a test satpulsed instance from a recorded packet log, with no GPS hardware, by replaying the log through a FIFO with original packet pacing. Use to exercise the full scan/decode/event pipeline or the web interface from a capture.
End-to-end test of GPS message (gpsprot.*Msg) pipeline with GPS hardware
Stand up a throwaway satpulsed instance as an unprivileged user for testing, fed from a serial device or a FIFO. Use directly to run a test instance, or as the setup step for the drive-satpulsed-from-log and hardware-test-gps-msgs skills.
How to use satpulsetool - GPS receiver configuration and packet decoding tool
| name | packet-testdata |
| description | Build systematic collection of packet logs for a GPS receiver, covering all implemented decode paths per plan/packet-testing.md |
| allowed-tools | Read, Bash, Glob, Grep, Write, Edit, AskUserQuestion, Agent, Skill |
Build a systematic collection of packet logs for a specific GPS receiver model, as described in plan/packet-testing.md. The goal is to produce a set of traces in gps/testdata/packets/ that exercises every implemented decode path in the receiver's lib and domain layers, and includes time messages suitable for deterministic replay testing per plan/timemsg-sync-testing.md.
This is NOT for ad-hoc packet capture during development. It is for building the curated test data collection.
There are two ways to configure GPS receivers for captures, corresponding to the two configuration modes of satpulsetool gps (see docs/man/satpulsetool-gps.1.md):
High-level configuration uses device-independent flags like --pvt-out, --sats-out, --binary, --nmea-out, --raw-out, --time-gnss, --gnss, --survey, --reload. Currently supported on u-blox receivers (u-blox 6 through X20) and Unicore Nebulas IV (UM980, UM981, UM982, UM960). See highlevel-config.md.
Low-level configuration uses a TOML message file (-m) containing protocol-specific commands. This works with all receivers. Message files are in per-vendor subdirectories of configs/gpsmsg/ (e.g., configs/gpsmsg/u-blox/ubx.toml, configs/gpsmsg/unicore/um980.toml, configs/gpsmsg/allystar/allystar.toml). See lowlevel-config.md.
Both approaches can be combined: use high-level config first, then a second invocation with -m to add messages that high-level config cannot reach.
/dev/ttyACM0)u-blox, unicore)Check CLAUDE.local.md for device and baud rate. If not found, ask the user.
Use the satpulsetool skill for reference on satpulsetool command usage.
NTP sync: The capture host must have good time sync. Verify with chronyc sources -- there should be a selected source (marked with *) and the offset should be small (under a few ms). Packet timestamps depend on wall clock accuracy.
Stop satpulsed: The user must stop satpulsed if it is running on the device. This requires sudo. Ask the user to do this -- do not attempt it yourself.
sudo systemctl stop satpulsed
gps/testdata/packets/<vendor>/<model>/
The model name comes from --show-receiver output (see high-level config section).
Create a metadata file in the output directory:
vendor = "<vendor>"
model = "<model>"
firmware = "<firmware string from --show-receiver>"
default-baud = <baud>
Read capture-principles.md for device-independent capture design principles.
Read capture-analysis.md for how to analyze the lib and domain layers to determine what messages need capturing.
For receivers with high-level configuration support (u-blox, Unicore), read highlevel-config.md.
For u-blox receivers specifically, also read ubx-config.md.
For Unicore receivers (UM980, UM981, UM982), also read unicore-config.md.
For all receivers, message files in the per-vendor subdirectories of configs/gpsmsg/ provide low-level message tags. Read lowlevel-config.md for how to use these.
For each capture:
Reload (high-level config receivers only): satpulsetool gps -d <device> -s <baud> --reload to restore NVM state. This ensures no residual configuration from a prior capture leaks in. On USB, add sleep 2 after reload as the device may briefly disconnect. For receivers without high-level config, reset by power cycling or using a reset command from the message file.
Configure (if needed): Run satpulsetool with configuration flags but without --capture or --packet-log.
Add low-level messages (if needed): Run satpulsetool with -m <file> -t <tags> to enable messages not reachable via high-level config. This can follow a high-level config step since -m does not probe or reset the receiver.
Capture: Run satpulsetool with --packet-log <file> --capture 30 (60 for survey). Use 30 seconds for most captures.
Verify: Check message types in the capture with:
jq -r 'select(.out != true) | .msg' <file> | sort | uniq -c | sort -rn
Confirm steady-state messages match expectations. First-epoch residual messages from before configuration took effect are normal and expected.
satpulsetool gps -d <device> -s <baud> --reloadAfter collecting all captures, build with make and run verify-replay.py (in this skill directory):
make
python3 .claude/skills/packet-testdata/verify-replay.py [--ecef x,y,z] out/amd64/satpulsetool <packet-log-directory>
If the antenna's ECEF position is known (check CLAUDE.local.md), pass it with --ecef to enable distance checks on all position events (posGeo, posECEF, survey). Without --ecef, only basic plausibility checks (valid lat/lon range, Earth-radius ECEF magnitude) are performed.
The script replays every .jsonl file through satpulsetool replay, collects all events in memory, and checks for:
The script exits 0 if all checks pass, 1 if any problems are found. Review any findings -- some are known receiver behaviors (e.g., NAV-TIMEUTC gnss=null under GLONASS-only timing) rather than capture defects.