Quick Start¶

Build¶

cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build -j
python3 apps/gnss.py doctor

At any point, ask for one concrete next step. Before a successful demo this recommends the offline first run; afterwards it offers a route based on the kind of data or integration you want to use:

python3 apps/gnss.py next
python3 apps/gnss.py next --goal rtk

gnss next only inspects local artifacts. Use --format json to integrate the same progress decision into another interface. It reports four local stages: first-run, choose-goal, apply-to-data, and inspect-result. Standard output/spp_solution.pos, output/rtk_solution.pos, and output/ppp_solution.pos files advance to inspection only when they contain at least one solution epoch; empty or header-only outputs remain at apply-to-data. If a documented standard input is not present, the command lists the missing paths and opens focused command help instead of recommending a processing command that is guaranteed to fail.

Docker¶

For the no-build self-contained demo, use the published image and mount only the output directory:

docker pull ghcr.io/rsasaki0109/gnssplusplus-library:v0.2.0
mkdir -p output
docker run --rm \
  -v "$PWD/output:/workspace/output" \
  ghcr.io/rsasaki0109/gnssplusplus-library:v0.2.0 \
  demo --output-dir /workspace/output/self-contained-demo

The demo uses the tracked synthetic PPP fixture and should produce 8 processed and 8 valid solutions plus .pos, KML, and JSON artifacts. It is an offline plumbing check, not a field-accuracy or RTK-fix benchmark. For other commands, build a local image explicitly:

docker build -t libgnsspp:latest .
docker run --rm -it -v "$PWD:/workspace" libgnsspp:latest --help
docker compose up gnss-web

The container installs the gnss dispatcher and Python helpers under /opt/libgnsspp, along with the tracked demo fixture under /opt/libgnsspp/share/libgnsspp/demo. Larger sample datasets are not embedded; mount your source tree or your own dataset directory into /workspace for dataset-dependent commands.

First solutions¶

python3 apps/gnss.py spp \
  --obs data/rover_static.obs \
  --nav data/navigation_static.nav \
  --out output/spp_solution.pos

python3 apps/gnss.py solve \
  --rover data/short_baseline/TSK200JPN_R_20240010000_01D_30S_MO.rnx \
  --base data/short_baseline/TSKB00JPN_R_20240010000_01D_30S_MO.rnx \
  --nav data/short_baseline/BRDC00IGS_R_20240010000_01D_MN.rnx \
  --mode static \
  --out output/rtk_solution.pos

python3 apps/gnss.py ppp \
  --static \
  --obs data/rover_static.obs \
  --nav data/navigation_static.nav \
  --out output/ppp_solution.pos

python3 apps/gnss.py visibility \
  --obs data/rover_static.obs \
  --nav data/navigation_static.nav \
  --csv output/visibility.csv \
  --summary-json output/visibility_summary.json \
  --max-epochs 60

python3 apps/gnss.py replay \
  --rover-rinex data/rover_kinematic.obs \
  --base-rinex data/base_kinematic.obs \
  --nav-rinex data/navigation_kinematic.nav \
  --mode moving-base \
  --out output/moving_base_replay.pos \
  --max-epochs 20

Main commands¶

Command	Purpose
`gnss commands`	List or search registered dispatcher commands as text or JSON
`gnss help <command>`	Show focused help for one command
`gnss doctor`	Check local setup, built tools, dataset/docs readiness, Docker, and ROS2 hints
`gnss ros2-doctor`	Check ROS2 receiver readiness, serial permissions, launch/record commands, and topic debug commands
`gnss ros2-bag-doctor`	Inspect a ROS2 GNSS bag for required topics, message rates, timestamp gaps, raw-binary replayability, and MCAP reader/metadata fallback
`gnss field-report`	Aggregate setup, ROS2, bag, and realtime-smoke diagnostics into Markdown and JSON handoff artifacts
`gnss robotics-smoke`	Run PPC RTK `quick`, `realtime`, or `full` smoke profiles with runtime gates and debug reasons
`gnss spp`	Batch SPP from rover/nav RINEX
`gnss solve`	Batch RTK from rover/base/nav RINEX
`gnss ppp`	Batch PPP from rover RINEX plus nav or precise products
`gnss visibility`	Export azimuth/elevation/SNR visibility rows and summary JSON from rover/nav RINEX
`gnss visibility-plot`	Render a visibility CSV into a polar/elevation PNG quick-look
`gnss moving-base-plot`	Render a moving-base solution/reference pair into a baseline/heading PNG quick-look
`gnss moving-base-prepare`	Extract rover/base UBX, reference CSV, and optional receiver CSV from a ROS2 moving-base bag
`gnss moving-base-signoff`	Validate a real moving-base replay/live dataset against per-epoch base/rover reference coordinates
`gnss scorpion-moving-base-signoff`	One-command prepare + BRDC fetch + replay validation for the public SCORPION bag with receiver side-by-side output
`gnss fetch-products`	Fetch and cache `SP3`/`CLK`/`IONEX`/`DCB` files from local or remote sources
`gnss ppp-products-signoff`	Run static, kinematic, or PPC PPP sign-off with fetched product presets or templates, plus comparison CSV/PNG artifacts
`gnss vmf-atl`	Convert VMF site-wise GNSS tidal APL coefficients into libgnss++ ATL coefficient files
`gnss stream`	Inspect and relay RTCM over file, NTRIP, TCP, or serial
`gnss station`	Validate, start, monitor, stop, and restart a long-running RTK session with run artifacts
`gnss convert`	Convert RTCM or UBX into simple RINEX outputs
`gnss ubx-info`	Inspect `NAV-PVT`, `RAWX`, `SFRBX` from file or serial
`gnss ionex-info`	Inspect `IONEX` headers, maps, and auxiliary DCB blocks
`gnss dcb-info`	Inspect `Bias-SINEX` or auxiliary DCB products
`gnss qzss-l6-info`	Inspect direct QZSS L6 frames and export Compact SSR payloads
`gnss web`	Local browser UI for summary JSON, live/moving-base/PPP-product sign-offs, trajectories, moving-base/visibility plots, receiver status, and artifact links
`gnss ppc-rtk-signoff`	Fixed RTK sign-off profiles for PPC Tokyo/Nagoya, with optional RTKLIB/commercial receiver side-by-side output
`gnss ppc-coverage-matrix`	Full six-run PPC Tokyo/Nagoya coverage-profile matrix with JSON/Markdown summaries

Long-running RTK station¶

For a field receiver and correction stream, copy configs/examples/station.example.toml, replace the endpoints, and validate before starting:

gnss station check --config configs/examples/station.example.toml
gnss station start --config configs/examples/station.example.toml
gnss station status --config configs/examples/station.example.toml --wait-seconds 5 --tail-log-lines 20

Each start creates a timestamped directory under run_root and writes a resolved receiver config, run.json, status.json, live.log, and the solution file. latest.json lets status and stop find the newest run; gnss station stop --config ... is safe to repeat. Stations enable child process restart by default; set auto_restart = false when an operator must inspect a failure before it is restarted. JSON output masks URI credentials. The longer-term operational roadmap is tracked in docs/development_backlog.md. Application delivery priority is defined separately by the primary application roadmap.

Local web UI¶

python3 apps/gnss.py web \
  --port 8085 \
  --rcv-status output/receiver.status.json

Open http://127.0.0.1:8085 to inspect benchmark tables, live/moving-base/PPP-product sign-offs, receiver status, moving-base/visibility plots, moving-base history, commercial receiver side-by-side metrics, and linked artifacts/provenance. PPC and moving-base rows include receiver comparison deltas when their summaries contain commercial receiver results; PPP-product rows include direct links to fetched products, MALIB .pos, comparison CSV/PNG, and dataset reference files. The robotics realtime smoke panel auto-discovers output/robotics_smoke*/**/*.json and shows pass/fail status, runtime gates, tuning knobs, and direct debug links. The ROS2 bag doctor panel auto-discovers output/ros2_bag*_summary.json and shows topic presence, message rates, timestamp gaps, and raw-binary replay readiness for field bags.

Create a single handoff report after a field run:

python3 apps/gnss.py field-report \
  --out output/field_report.md \
  --json-out output/field_report.json

The report collects gnss doctor, gnss ros2-doctor, existing ros2-bag-doctor summaries, and existing robotics-smoke summaries. It is the artifact to attach when a field laptop, researcher, and robotics integrator need to discuss the same run.

The local web UI auto-discovers output/field_report*.json and surfaces the report links, Markdown preview, setup/ROS2/bag/smoke status, and next debug commands near the top of the dashboard.

You can also store the same arguments in configs/examples/web.example.toml and run:

python3 apps/gnss.py web --config-toml configs/examples/web.example.toml

Docker form:

docker run --rm -it -p 8085:8085 -v "$PWD:/workspace" \
  libgnsspp:latest web --host 0.0.0.0 --port 8085 --root /workspace

Real moving-base sign-off¶

moving-base-signoff is for external real datasets. Provide recorded replay or live inputs plus a reference CSV with per-epoch base/rover ECEF coordinates.

Typical replay preparation flow:

python3 apps/gnss.py moving-base-prepare \
  --input /datasets/moving_base/2023-06-14T174658Z.zip \
  --rover-ubx-out output/moving_base_rover.ubx \
  --base-ubx-out output/moving_base_base.ubx \
  --reference-csv output/moving_base_reference.csv \
  --commercial-csv output/commercial_receiver_solution.csv

python3 apps/gnss.py fetch-products \
  --date 2023-06-14 \
  --preset brdc-nav

python3 apps/gnss.py scorpion-moving-base-signoff \
  --summary-json output/scorpion_moving_base_summary.json

python3 apps/gnss.py moving-base-signoff \
  --config-toml configs/signoff/moving_base_signoff.example.toml

python3 apps/gnss.py moving-base-signoff \
  --config-toml configs/signoff/moving_base_signoff.example.toml \
  --commercial-pos output/commercial_receiver_solution.csv \
  --commercial-matched-csv output/commercial_receiver_matches.csv

python3 apps/gnss.py live-signoff \
  --config-toml configs/signoff/live_signoff.example.toml

Product-driven PPP¶

python3 apps/gnss.py fetch-products \
  --date 2024-01-02 \
  --preset igs-final \
  --preset ionex \
  --preset dcb \
  --summary-json output/products.json

python3 apps/gnss.py ppp-static-signoff \
  --fetch-products \
  --product-date 2024-01-02 \
  --product sp3=https://cddis.nasa.gov/archive/gnss/products/{gps_week}/COD0OPSFIN_{yyyy}{doy}0000_01D_05M_ORB.SP3.gz \
  --product clk=https://cddis.nasa.gov/archive/gnss/products/{gps_week}/COD0OPSFIN_{yyyy}{doy}0000_01D_30S_CLK.CLK.gz \
  --product ionex=https://cddis.nasa.gov/archive/gnss/products/ionex/{yyyy}/{doy}/COD0OPSFIN_{yyyy}{doy}0000_01D_01H_GIM.INX.gz \
  --product dcb=https://cddis.nasa.gov/archive/gnss/products/bias/{yyyy}/CAS0MGXRAP_{yyyy}{doy}0000_01D_01D_DCB.BSX.gz \
  --summary-json output/ppp_static_summary.json

python3 apps/gnss.py ppp-kinematic-signoff \
  --max-epochs 120 \
  --require-common-epoch-pairs-min 120 \
  --require-reference-fix-rate-min 95 \
  --require-converged \
  --require-convergence-time-max 300 \
  --require-mean-error-max 7 \
  --require-p95-error-max 7 \
  --require-max-error-max 7 \
  --require-mean-sats-min 18 \
  --require-ppp-solution-rate-min 100

python3 apps/gnss.py ppp-products-signoff \
  --config-toml configs/signoff/ppp_products_ppc.example.toml

python3 apps/gnss.py ppc-rtk-signoff \
  --config-toml configs/signoff/ppc_rtk_signoff.example.toml

python3 apps/gnss.py ppc-rtk-signoff \
  --dataset-root /datasets/PPC-Dataset \
  --city tokyo \
  --realtime-profile sigma-demote \
  --summary-json output/ppc_tokyo_run1_sigma_demote_signoff.json

IERS PPP Loading Benches¶

Atmospheric tidal loading (ATL) requires station-specific S1/S2 coefficients. Convert VMF site-wise GNSS tidal APL coefficients to the libgnss++ .atl format, then run a paired PPP bench with ATL toggled:

python3 apps/gnss.py vmf-atl \
  --station PERT \
  --station TSKB \
  --output-dir tests/fixtures/iers

python3 apps/gnss.py ppp-iers-atm-tidal-loading-multisite-bench \
  --sites configs/benchmarks/iers_atl_multisite_vmf.example.json \
  --output-dir output/iers_atm_tidal_loading_multisite_bench_vmf

The example config expects the PPP observation/products under data/igs_2026105/ and uses the tracked VMF-derived ATL fixtures for PERT and TSKB. Use site-specific real coefficients for production validation; tests/fixtures/iers/tskb_synth.atl is only a deterministic smoke fixture.

Local docs¶

python3 -m pip install -r requirements-docs.txt
python3 -m mkdocs serve