Matlab Fuse Inertial SensorsSAFE

The MATLAB Agentic Toolkit brings proven MATLAB capabilities to AI agents, making engineering and scientific workflows agent-ready.

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
name: matlab-fuse-inertial-sensors
description: >
  Analyzes sensor configurations and creates inertial fusion filters in MATLAB
  Navigation Toolbox. Manages filter selection (imufilter, ahrsfilter,
  complementaryFilter, insfilterMARG, insfilterAsync, insfilterNonholonomic,
  insfilterErrorState, insEKF, insCF), construction, tuning, and fusion loops.
  Use when fusing IMU/AHRS/INS/GPS+IMU data, estimating orientation or pose,
  or choosing a filter. Do NOT use for vision-only SLAM, Simulink fusion, or
  IMU simulation.
license: https://www.mathworks.com/content/dam/mathworks/license/pmrl/license.md
compatibility: R2022a+
metadata:
  author: MathWorks
  version: "1.1"
---

## When to Use

Select, implement, or tune an inertial sensor fusion filter in MATLAB Navigation Toolbox.

## When NOT to Use

- Vision-only or LiDAR-only SLAM (no inertial sensor): use nav SLAM functions instead
- Sensor simulation or data generation only: no filter needed
- Simulink model-based sensor fusion

---

## Choose Your Filter

### Step 1 — Configured or Flexible?

Configured filters cover these sensor combinations exactly:

- Accel + Mag only (no gyro)
- Accel + Gyro (no mag, no GPS)
- Accel + Gyro + Mag
- Accel + Gyro + Mag + Altimeter
- Accel + Gyro + GPS (ground vehicle, no mag)
- Accel + Gyro + GPS + monocular visual odometry (ground vehicle)
- Accel + Gyro + Mag + GPS (synchronous rates)
- Accel + Gyro + Mag + GPS (mixed rates or dropped samples)

```
Is your sensor set one of the above?
        │ No ─────────────────────────────────────────────────────► Step 2B (Flexible)
        │ Yes
        ▼
Need a custom motion model (constant-velocity, bicycle, etc.)?
        │ Yes ────────────────────────────────────────────────────► Step 2B (Flexible)
        │ No
        ▼
Need RTS smoothing, StateCovariance output, or optimizer-based tune()?
        │ Yes ────────────────────────────────────────────────────► Step 2B (Flexible)
        │ No
        ▼
Batch-only processing (no real-time predict/fuse loop needed)?
        │ Yes ────────────────────────────────────────────────────► Step 2B (Flexible)
        │ No
        ▼
        Step 2A (Configured)
```

---

### Step 2A — Pick a configured filter

```
What output do you need?
│
├─ Orientation only (no position)
│   │
│   ├─ Accel + Mag only (no gyro)
│   │   └──► ecompass   [function, not object; single-shot; useful for filter init]
│   │
│   ├─ Accel + Gyro (no mag)
│   │   └──► imufilter   [heading drifts over time without mag]
│   │
│   ├─ Accel + Gyro + Mag
│   │   ├──► ahrsfilter   [default; KF-based, statistically tunable]
│   │   └── lowest compute cost needed?
│   │       └──► complementaryFilter   [gain-based only; no KF, no tune()]
│   │
│   └─ Accel + Gyro + Mag + Altimeter
│       └──► ahrs10filter   [adds altitude + vertical velocity output]
│
└─ Full pose (orientation + position + velocity)
    │
    ├─ No motion constraints (aerial, or ground vehicle without side-slip constraint)
    │   ├─ Accel + Gyro + Mag + GPS, all sensors sync
    │   │   └──► insfilterMARG
    │   └─ Accel + Gyro + Mag + GPS, mixed rates or dropped samples
    │       └──► insfilterAsync
    │
    └─ Ground vehicle with zero side-slip constraint
        ├─ Accel + Gyro + GPS
        │   └──► insfilterNonholonomic
        └─ Accel + Gyro + GPS + monocular visual odometry
            └──► insfilterErrorState
```

---

### Step 2B — Pick a flexible filter

```
Need real-time fusion, StateCovariance output, or optimizer-based tune()?
        │ Yes ──► insEKF   [production use; full KF; real-time and batch APIs]
        │ No
        ▼
Batch-only processing, no covariance needed, quick setup (R2026a+)?
        └──► insCF   [complementary filter; gain-based; not for production]
```

---

## Data Preparation

### Sample Rate

`SampleRate` (Group A filters) and `IMUSampleRate` (Group B filters) must match the actual data rate — a mismatch directly scales the noise model and corrupts all filter outputs. `insfilterAsync`, `insEKF`, and `insCF` are timestamp-driven and have no rate property.

**Convert timestamps to seconds first**, then infer the rate:

```matlab
tSec = rawTimestamp / 1e6;   % μs → s; divide by 1e3 for ms, or skip if already seconds
fs = 1 / median(diff(tSec));
```

**If timestamps are unusable** (all identical, or non-finite result):

```matlab
if numel(unique(tSec)) < 2 || ~isfinite(fs)
    fs = 100;   % use the stated or datasheet rate
end
```

### Time Gaps

All stateful filters accumulate error across a recording gap (a large jump in timestamps). Split the data at each gap and reset the filter at the start of each segment.

```matlab
gapThreshold = 5 / fs;                   % 5× the expected sample interval
gapIdx = find(diff(tSec) > gapThreshold);
segments = [1; gapIdx+1];                % start index of each segment
```

**Group A System object filters** (`imufilter`, `ahrsfilter`, `complementaryFilter`): call `release(filt)` between segments — resets state while preserving all tuned noise properties.

**Group B and other filters**: re-construct the filter object at the start of each segment.

---

## Implementation

Consult the reference file for the filter you chose:

| Filter group              | Reference                                                             |
| ------------------------- | --------------------------------------------------------------------- |
| Attitude filters          | [references/attitude-filters.md](references/attitude-filters.md)     |
| Navigation filters        | [references/navigation-filters.md](references/navigation-filters.md) |
| `insEKF`                  | [references/insekf.md](references/insekf.md)                         |
| `insCF`                   | [references/inscf.md](references/inscf.md)                           |

---

## Tuning

Two `tune` signatures exist — mixing them up is a common error:

- **Signature A** (`imufilter`, `ahrsfilter`) — modifies filter in-place:
  `tune(filt, sensorData, groundT

SAFEgrade B · trust 89/100 Nothing in the source contradicts what it says it does. Grade A is reserved for packages that have also passed the behavioural sandbox.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (0)

No findings outside the package's declared scope.

Gates applied: no_behavioural_pass.