Quick Start

This guide will get you up and running with Strapdown-rs in minutes.

Installation

Add Strapdown-rs to your Cargo.toml:

cargo add strapdown-core

Or install the simulation binary:

cargo install strapdown-sim

Running Your First Simulation

1. Prepare Input Data

Strapdown-sim expects CSV files with IMU and GNSS data. The format follows the Sensor Logger app convention:

timestamp,gyro_x,gyro_y,gyro_z,accel_x,accel_y,accel_z,latitude,longitude,altitude
1234567890.0,0.01,-0.02,0.03,0.5,-0.2,9.81,45.5,-122.6,100.0
...

2. Declare the frame

Every command below assumes NED -- north, east, down -- which is the library default and what strapdown-sim syn emits.

Sensor Logger exports are ENU: at rest the device reports +g along its up axis, not -g along a down axis. For those, add --enu (or is_enu = true in a config file):

strapdown-sim cl --enu -i data/sensor_logger.csv -o results/output.csv

You will not get this wrong silently. The tool checks the declared frame against the leading records' sensed specific force and refuses a mismatch, naming the flag to pass -- mechanizing ENU records as NED adds the sensed force to the gravity model instead of cancelling it, and integrates at 2 g (#296).

3. Run a Simulation

Dead Reckoning (dr; ol is a different, unimplemented mode):

strapdown-sim dr -i data/input.csv -o results/output.csv

Closed-Loop (16-state ESKF, the default):

strapdown-sim cl -i data/input.csv -o results/output.csv

Closed-Loop with EKF:

strapdown-sim cl -i data/input.csv -o results/output.csv --filter ekf

Closed-Loop with UKF:

strapdown-sim cl -i data/input.csv -o results/output.csv --filter ukf

Particle Filter:

strapdown-sim pf -i data/input.csv -o results/output.csv --num-particles 100

4. View Results

The output CSV contains the estimated navigation state:

timestamp,latitude,longitude,altitude,velocity_north,velocity_east,velocity_down,roll,pitch,yaw
1234567890.0,45.50001,-122.59999,100.1,1.2,0.5,-0.1,0.01,0.02,90.5
...

Using Configuration Files

For more complex scenarios, use TOML configuration files:

# config.toml -- a whole `SimulationConfig`. `mode` is the only required field.
mode = "closed-loop"          # dead-reckoning | open-loop | closed-loop | particle-filter | synthetic
input = "data/trajectory.csv"
output = "results/navigation.csv"
seed = 42
is_enu = false                # NED is the default; Sensor Logger exports need `true`

[logging]
level = "info"

[closed_loop]
filter = "eskf"               # eskf (default) | ukf | ekf

[aiding]
seed = 42

[aiding.scheduler]            # when GNSS fixes arrive
kind = "fixed_interval"
interval_s = 5.0
phase_s = 0.0

[aiding.fault]                # how they are corrupted
kind = "none"

Run it with the config alone — --config supplies the whole run, so a subcommand and its -i/-o/--filter arguments are ignored when it is present:

strapdown-sim --config config.toml

core/tests/example_configs.rs parses every file under examples/configs/ and asserts it deserializes into the scenario it describes, because every field has a default: a misspelled section is dropped silently and the run simulates nothing.

Run with:

strapdown-sim --config config.toml

Next Steps