imu_latency_tools

imu_latency_tools is a ROS 2 package containing a set of CLI tools for measuring and visualising the latency and inter‑arrival jitter of IMU messages. It subscribes to any sensor_msgs/msg/Imu topic, computes per‑sample delays, logs the data to CSV, computes summary statistics (min/max/mean/standard deviation and several percentiles) and produces publication‑quality plots. A companion script can regenerate plots at any time from a saved CSV file. A simple launch file is provided for convenience.

Features

• Latency and inter‑arrival measurement: Compute message latency between the timestamp in the header and the time of receipt on the host, or measure inter‑arrival jitter if the device’s timestamp cannot be trusted.
• CSV logging: Record per‑message samples including host receipt time, message time and latency in milliseconds.
• Summary statistics: Automatically calculate min, max, mean, standard deviation, p50, p90, p95 and p99 and save them in JSON format.
• Plots: Generate a latency–over‑time chart (with optional rolling mean and percentile overlays) and a histogram. If Matplotlib is not installed, logging still works.
• Baseline correction: Optionally remove the fixed offset between the device clock and the host clock so that relative jitter can be studied independently of absolute synchronisation.
• Quality‑of‑Service controls: Configure reliability, history, durability and queue depth of the ROS 2 subscription to suit your transport layer.
• Launch file and Python entry points: Use via ros2 run (imu_latency_logger and imu_latency_plot) or run directly with Python. A launch file simplifies running from a ROS 2 workspace.

Advanced latency analysis

In addition to the basic logger, this package provides an advanced analysis tool exposed via the entry point imu_latency_logger_advanced. This variant builds on the basic functionality with several important enhancements:

• Drift removal: Performs a global linear regression between the sensor’s timestamp and the host’s monotonic time to remove both offset and clock drift, reporting the drift in parts per million (ppm) and the initial offset. A sliding‑window regression is optionally computed to visualise drift variations over time.

• Comprehensive statistics: Calculates not only mean and standard deviation, but also median absolute deviation (MAD), skewness and kurtosis of the latency distribution, plus a rich set of percentiles (10th, 50th, 90th, 95th, 99th and 99.9th).

• Inter‑arrival jitter metrics: Always measures the inter‑arrival time between messages on the host’s monotonic clock, reporting jitter statistics and an estimated message rate in Hz.

• Multiple plots: Generates several publication‑quality figures with distinct colour palettes and semi‑transparent markers:

  • Latency residual versus time with optional rolling mean and p95 overlays.
  • Histogram of latency residuals.
  • Histogram of raw wall‑clock latency.
  • Inter‑arrival jitter versus time and its histogram.
  • Clock drift over time derived from sliding‑window regression.
  • Raw versus residual latency scatter plot for visualising the effect of drift correction.

  If matplotlib is unavailable, the advanced logger still records CSV and JSON summaries without failing.

To run the advanced logger from a ROS 2 workspace:

ros2 run imu_latency_tools imu_latency_logger_advanced \
  --topic /olive/olixSense/x1/id001/imu \
  --duration 600 \
  --warmup 5 \
  --qos-reliability besteffort --qos-depth 1000

All of the basic options apply, and additional arguments such as --sliding-window and --rolling-window control the drift estimation window and smoothing overlays respectively. See --help for full details.

Installation

ROS 2 workspace

Clone this repository into your ROS 2 workspace and build it using colcon:

cd ~/ros2_ws/src
git clone <repository-url> imu_latency_tools
cd ~/ros2_ws
rosdep install --from-paths src --ignore-src -r -y
colcon build --packages-select imu_latency_tools
source install/setup.bash

Pure Python environment

If you only need the CLI scripts outside ROS 2, create a virtual environment and install the package in editable mode:

python3 -m venv .venv && source .venv/bin/activate
pip install --upgrade pip
pip install -r requirements.txt
pip install -e .

Usage

Measuring latency or arrival jitter

Run the logger with your IMU topic and desired options. For example, to measure latency for ten minutes, discard the first five seconds and remove any constant clock offset between the sensor and host:

ros2 run imu_latency_tools imu_latency_logger \
  --topic /olive/olixSense/x1/id001/imu \
  --duration 600 \
  --baseline-correct \
  --warmup 5

Key options:

• --topic – fully qualified topic name to subscribe to.
• --duration – logging duration in seconds (default: 600).
• --baseline-correct – subtract the initial timestamp offset from all latencies to focus on relative jitter.
• --warmup – number of seconds of samples to discard before computing statistics and plots.
• --mode {latency,arrival} – compute latency using the message timestamps (latency) or measure inter‑arrival jitter ignoring timestamps (arrival).
• --qos-reliability, --qos-history, --qos-depth and --qos-durability – tune the subscription’s Quality of Service settings. See rclpy documentation for details.

Generated files will have a timestamped prefix (or you can supply --out to override) and include:

• *.csv – raw samples (recv_time_s, msg_time_s, latency_ms).
• *.json – summary statistics as a JSON object.
• *.png – latency over time with optional rolling statistics.
• *_hist.png – histogram of latencies.

Replotting later

If you need to regenerate plots or adjust plotting parameters without re‑recording data, use the companion CLI against the saved CSV:

ros2 run imu_latency_tools imu_latency_plot \
  --csv path/to/imu_latency_20250101_120000.csv \
  --rolling-window 200 \
  --hist-bins 80

License

This project is licensed under the MIT License – see the LICENSE file for details.