Pipe Interface

voxl-open-vins-server communicates exclusively through ModalAI’s MPA pipe architecture: sensors stream in through client pipes, estimates stream out through server pipes, and a control pipe accepts runtime commands. This page is the complete communications reference — what each pipe carries, when it publishes, and how to interpret states, quality, and error codes.

Table of contents

1. The pipe map
2. Input pipes
3. Output pipes
   1. /run/mpa/ov — primary VIO output
   2. /run/mpa/ov_extended — extended output
   3. /run/mpa/ov_status — health and diagnostics
4. Control pipe
5. States
6. Quality
7. Error codes
8. Frame conventions
9. Client tools

The pipe map

Publishing happens on the VIO thread, immediately after every estimator update — there is no separate publish timer. The output rate therefore tracks the camera update rate (e.g. ~60 Hz on a rig whose reference camera runs 60 fps), with IMU-rate pose propagation available to consumers that extrapolate between updates.

Input pipes

All cameras must reference the same IMU in vio_cams.conf. The IMU clock is the common timebase against which every camera’s time offset is estimated.

Camera frames are pushed into the estimator’s lock-free per-camera ingest directly from the camera pipe callbacks — nothing blocks a camera thread, and a stalled camera cannot stall the pipeline. The IMU callback drives estimation: each IMU batch advances the filter and releases any camera frames whose global time order is now decided.

Output pipes

/run/mpa/ov — primary VIO output

Publishes vio_data_t (defined in modal_pipe_interfaces.h), the packet consumed by voxl-px4 for position control:

/run/mpa/ov_extended — extended output

Publishes ext_vio_data_t: everything in vio_data_t plus pose/velocity covariance diagonals, gyro/accel bias estimates, camera extrinsics in use, and the list of currently tracked feature locations (consumed by voxl-portal for the VIO overlay). Only written when at least one client is connected, so it costs nothing in normal flight.

/run/mpa/ov_status — health and diagnostics

Publishes ov_status_t at the health-check cadence: hysteresis state, counters, and operational diagnostics for logging and fleet monitoring (voxl-log-vins consumes this alongside ov).

Control pipe

The server listens on /run/mpa/ov/control (also reachable through the ov_extended channel):

voxl-reset-vins        # hard reset
voxl-reset-vins -s     # soft reset

See Initialization & Resets for what each reset preserves and when the server triggers them autonomously.

States

Quality

quality is a 0–100 score computed from the tracked-feature population: per-camera image coverage (a 5×5 occupancy grid), SLAM landmark uncertainty, and MSCKF track quality, pooled over a short window so that asynchronous per-camera updates score exactly like synchronized batch updates. The published value is smoothed with a short time constant; -1 means failed, 0 means resetting.

A hysteresis state machine (INITIAL → GOOD/BAD) sits on top of the raw score to prevent rapid quality flapping; its thresholds are configurable in voxl-open-vins-server.conf (see the main page). The full design and the exact formulas — the windowed feature union, per-camera grid scoring, and the published-value EMA — are documented on the async page: Estimation quality on asynchronous rigs and Appendix A.5.

Error codes

error_code is a bitmask; multiple codes can be active simultaneously. The health monitor (30 Hz) classifies codes into two severities:

Only estimator-health codes can trigger an automatic reset. Transport hiccups — a dropped frame or IMU sample — are expected events on a busy system (the asynchronous ingest disposes frames deliberately for ordering and staleness) and must never take down a healthy filter. Warning-class codes self-clear after 10 s without a new occurrence.

Frame conventions

Internally the estimator runs in the OpenVINS world frame (gravity-aligned, z-up). The publisher transforms every output into ModalAI’s FRD (front-right-down) local frame convention before writing to the pipes, using the body → imu extrinsic from /etc/modalai/extrinsics.conf when imu_body_frame_mode is enabled. Heading is re-zeroed at every (re)initialization: the local frame’s x-axis is the vehicle’s heading at init, which is what position controllers expect.

Client tools