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

This middleware is based on the following paper and the corresponding prototype. The paper has been accepted to IEEE ISORC 2025 (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.

@inproceedings{ishikawa2025ros,
  title={ROS 2 Agnocast: Supporting Unsized Message Types for True Zero-Copy Publish/Subscribe IPC},
  author={Ishikawa--Aso, Takahiro and Kato, Shinpei},
  booktitle={2025 28th International Symposium on Real-Time Distributed Computing (ISORC)},
  pages={01--10},
  year={2025},
  organization={IEEE}
}

• Supported Environments
• For Users
  • Clone the repository
  • Setup
  • Build
  • Run
• For Developers
  • Clone the repository
  • Setup pre-commit
  • Build and insert kmod
  • Test
  • Kernel Module Test
• Debug
• Troubleshooting
• Documents

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

The ROS 2 Jazzy–compatible release is scheduled for late February 2026.

Since ROS packages under src/ such as agnocastlib are not yet distributed from the ROS build farm, a source build is currently required. Therefore, to perform the source build, first check out the specific version as follows:

git clone --branch v2.1.2 https://github.com/tier4/agnocast.git
cd agnocast

Run the setup script to install dependencies:

bash scripts/setup

# Create keyrings directory
sudo install -d -m 0755 /etc/apt/keyrings

# Download and install GPG key
curl -fsSL 'https://keyserver.ubuntu.com/pks/lookup?op=get&search=0xCFDB1950382092423DF37D3E075CD8B5C91E5ACA' \
  | gpg --dearmor | sudo tee /etc/apt/keyrings/agnocast-ppa.gpg >/dev/null
sudo chmod 0644 /etc/apt/keyrings/agnocast-ppa.gpg

# Create repository configuration (deb822 format)
cat <<EOF | sudo tee /etc/apt/sources.list.d/agnocast.sources
Types: deb
URIs: http://ppa.launchpad.net/t4-system-software/agnocast/ubuntu
Suites: jammy
Components: main
Signed-By: /etc/apt/keyrings/agnocast-ppa.gpg
EOF

# Install packages
sudo apt update
sudo apt install agnocast-heaphook-v2.1.2 agnocast-kmod-v2.1.2

Build the project:

colcon build --symlink-install --cmake-args -DCMAKE_BUILD_TYPE=Release

Insert kernel module.

sudo modprobe agnocast

Run sample app (different window for each script). The order does not matter.

bash scripts/run_listener
bash scripts/run_talker

Stop applications and unload kernel module.

sudo modprobe -r agnocast

Clone the latest main branch for development:

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

The following command allows clang-format, markdownlint, and KUNIT Test to be run before each commit.

python3 -m pip install pre-commit
python3 -m pip install --upgrade pre-commit identify
pre-commit install

If you want to disable pre-commit, please run pre-commit uninstall.

Build.

bash scripts/build_all

Check if there is a libagnocast_heaphook.so in install/agnocastlib/lib.

$ ls install/agnocastlib/lib | grep libagnocast_heaphook
libagnocast_heaphook.so

Insert kernel module.

cd agnocast_kmod
sudo insmod agnocast.ko
sudo lsmod

You can build, test and generate the coverage report by following:

bash scripts/test_and_create_report

A custom kernel with the following CONFIG enabled is required to run KUnit Test and obtain the coverage report (sample custom kernel is placed here).

• CONFIG_KUNIT=y
• CONFIG_GCOV_KERNEL=y

If booting with the custom kernel, the following script can be used to run unit tests on kernel modules and generate coverage reports.

bash scripts/run_kunit

You can also use pre-commit

Check the kernel log.

sudo dmesg -w

To use dynamic_debug for dynamically outputting debug logs, please run the following command as super user:

sudo su
echo 'file agnocast_main.c +p' > /sys/kernel/debug/dynamic_debug/control

Check if dynamic_debug is enabled by running the following command. If the right side of the = is p, it is enabled. (If it's _, it is disabled.)

sudo cat /sys/kernel/debug/dynamic_debug/control | grep "agnocast_main.c"
/.../agnocast/agnocast_kmod/agnocast_main.c:810 [agnocast]release_msgs_to_meet_depth =p "Release oldest message in the publisher_queue (publisher_pid=%d) of the topic (topic_name=%s) with qos_depth %d. (release_msgs_to_meet_depth)\012"
/.../agnocast/agnocast_kmod/agnocast_main.c:367 [agnocast]insert_message_entry =p "Insert an entry (topic_name=%s publisher_pid=%d msg_virtual_address=%lld timestamp=%lld). (insert_message_entry)"

To use dynamic_debug, the Linux kernel configuration must have CONFIG_DYNAMIC_DEBUG set to y. If CONFIG_DYNAMIC_DEBUG is not enabled in your environment, perform a debug build with:

make CFLAGS_agnocast.o="-DDEBUG"

Refer to the Linux kernel documentation on kbuild for more information about compilation flags.

If you previously installed Agnocast using the old add-apt-repository method, remove the old configuration before running scripts/setup:

# Remove old repository configuration
sudo add-apt-repository --remove ppa:t4-system-software/agnocast
sudo rm -f /etc/apt/sources.list.d/*agnocast*.list
sudo rm -f /etc/apt/trusted.gpg.d/*agnocast*.gpg

Although Agnocast includes cleanup procedures for resources like shared memory and message queues, these resources may sometimes remain in the system. If you notice that available system memory decreases every time you run an Agnocast-enabled application, you'll need to remove leftover shared memory objects by running:

rm /dev/shm/agnocast@*

Additionally, if you encounter the error mq_open failed: No space left on device, it means that the system has reached the maximum number of message queues. In that case, you may need to remove leftover message queues by running:

rm /dev/mqueue/agnocast@*
rm /dev/mqueue/agnocast_to_ros2@*

• shared memory
• message queue
• Autoware integration
• Memory format in heaphook
• Clang-tidy Suppressions
• How to set environment variables
• ros2 command extension