ROS 2 Agnocast

An rclcpp-compatible true zero-copy IPC middleware that supports all ROS message types, including message structs already generated by rosidl.

Agnocast is based on the following papers and the corresponding prototype. It also integrates CallbackIsolatedExecutor.

• T. Ishikawa-Aso, A. Yano, T. Azumi, and S. Kato, “Work in Progress: Middleware-Transparent Callback Enforcement in Commoditized Component-Oriented Real-time Systems,” in Proc. IEEE Real-Time and Embedded Technology and Applications Symposium (RTAS), 2025, pp. 78–81. IEEE Xplore (pdf).
• T. Ishikawa–Aso and S. Kato, “ROS 2 Agnocast: Supporting Unsized Message Types for True Zero-Copy Publish/Subscribe IPC,” in Proc. 28th Int. Symp. Real-Time Distributed Computing (ISORC), 2025, pp. 1–10. IEEE Xplore (pdf).
• T. Ishikawa–Aso, A. Yano, K. Imai, T. Azumi, and S. Kato, “ipc_shared_ptr: A Publish/Subscribe-Aware Smart Pointer for Cross-Process Object Lifetime Management,” in Proc. 29th Int. Symp. Real-Time Distributed Computing (ISORC), 2026 (to appear). arXiv:2605.04226 (pdf).

Talks:

• ROSCon 2025, Singapore: “Agnocast: A ROS 2-Compatible Middleware Enabling True Zero-Copy IPC for Unsized Message Types” by Takahiro Ishikawa-Aso (video)
• ROSCon JP 2025, Nagoya: “CallbackIsolatedExecutor: 二重スケジューリングを不要にする新しいExecutorとスケジューリング理論” by Takahiro Ishikawa-Aso (video, in Japanese; an English summary is available on the TIER IV tech blog)

Table of Contents

• Supported Environments
• For Users
• For Developers
• Debug
• Troubleshooting
• Documents

Supported Environments

Agnocast is currently available in the following environments. This reflects the current status, and support is expected to expand in the future.

Warning: Agnocast service/client is not officially supported yet and the API may change in the future. Use at your own risk.

For Users

For installation, setup, and usage instructions, please refer to the Getting Started Guide.

For Developers

Clone the repository

Clone the latest main branch for development:

git clone https://github.com/autowarefoundation/agnocast.git
cd agnocast

Setup

Run the setup script to install dependencies:

bash scripts/dev/setup.bash

Setup pre-commit

File truncated at 100 lines see the full file

Contributing to Agnocast

Thank you for your interest in contributing to Agnocast!

Pull Request Requirements

Version Update Labels (Required)

Every pull request must have exactly one of the following labels:

• need-major-update: User API breaking changes - requires MAJOR version update
• need-minor-update: Internal API breaking changes (kmod/agnocastlib compatibility) - requires MINOR version update
• need-patch-update: Bug fixes and other changes - requires PATCH version update

Important notes:

• PRs without a version label or with multiple version labels will not be mergeable due to automated checks.
• PR Title Convention: If you need need-major-update or need-minor-update, please include this in the PR title as well.
  • Example: fix(foo)[needs major version update]: bar
  • Example: feat(baz)[needs minor version update]: qux

Versioning Rules

Agnocast follows a modified semantic versioning scheme:

MAJOR version (need-major-update)

Increment when you make breaking changes to the User API.

Examples:

• Changing public API function signatures
• Removing or renaming user-facing APIs
• Modifying behavior that affects users of the library

MINOR version (need-minor-update)

Increment when you make breaking changes to internal APIs or component compatibility.

This includes changes that affect compatibility between:

• kmod
• agnocastlib

Examples:

• Removing or renaming ioctl commands
• Modifying data structures used in ioctl interfaces
• Changing shared data structures between kmod/agnocastlib
• Breaking changes to internal APIs not exposed to end users

PATCH version (need-patch-update)

Increment for bug fixes and other changes that don’t fall into the above categories.

Examples:

• Bug fixes
• Documentation updates
• Performance improvements (without API changes)
• Refactoring (without API changes)
• Test additions or improvements

Testing Requirements

Before submitting a PR, please ensure the following tests pass:

• Autoware
• bash scripts/test/e2e_test_1to1.bash (required)
• bash scripts/test/e2e_test_2to2.bash (required)
• kunit tests (required when modifying the kernel module)

Questions?

If you’re unsure which version label to use, feel free to ask in the PR comments or open a discussion.