autoware_agnocast_wrapper

The purpose of this package is to integrate Agnocast, a zero-copy middleware, into each topic in Autoware with minimal side effects. Agnocast is a library designed to work alongside ROS 2, enabling true zero-copy publish/subscribe communication for all ROS 2 message types, including unsized message types.

• Agnocast Repository: https://github.com/tier4/agnocast
• Discussion on Agnocast Integration into Autoware: https://github.com/orgs/autowarefoundation/discussions/5835
• Review Guide for Agnocast Wrapper PRs

This package provides macros that wrap functions for publish/subscribe operations and smart pointer types for handling ROS 2 messages. When Autoware is built using the default build command, Agnocast is not enabled. However, setting the environment variable ENABLE_AGNOCAST=1 enables Agnocast and results in a build that includes its integration. This design ensures backward compatibility for users who are unaware of Agnocast, minimizing disruption.

Two Integration Approaches

This package provides two approaches for integrating Agnocast. Both will coexist for the foreseeable future.

1. Node Wrapper (agnocast_wrapper::Node)

Use this when you want the entire node to transparently switch between rclcpp::Node and agnocast::Node at runtime. The node wrapper automatically selects the correct underlying implementation based on the ENABLE_AGNOCAST environment variable.

Currently supported APIs:

• Publisher / Subscription / PollingSubscriber
• Parameters
• Logger, Clock
• Callback groups
• Node interfaces (partial: get_node_base_interface(), get_node_topics_interface(), get_node_parameters_interface())

Note: Timer (create_wall_timer, create_timer) is not yet supported and will be added in a future update.

#include <autoware/agnocast_wrapper/node.hpp>

class MyNode : public autoware::agnocast_wrapper::Node
{
public:
  explicit MyNode(const rclcpp::NodeOptions & options)
  : Node("my_node", options)
  {
    pub_ = create_publisher<std_msgs::msg::String>("output", 10);
    sub_ = create_subscription<std_msgs::msg::String>(
      "input", 10, [this](std::unique_ptr<const std_msgs::msg::String> msg) { /* ... */ });
  }

private:
  autoware::agnocast_wrapper::Publisher<std_msgs::msg::String>::SharedPtr pub_;
  autoware::agnocast_wrapper::Subscription<std_msgs::msg::String>::SharedPtr sub_;
};

To use the Node wrapper in your package, add the following to your CMakeLists.txt:

find_package(autoware_agnocast_wrapper REQUIRED)
ament_target_dependencies(my_node_component autoware_agnocast_wrapper)

Registering a Node with autoware_agnocast_wrapper_register_node

Instead of calling rclcpp_components_register_node directly, use the autoware_agnocast_wrapper_register_node macro to register your component node. This macro:

1. Registers the component with rclcpp_components (for component container support)
2. Creates a standalone executable that can switch between rclcpp::Node and agnocast::Node at runtime based on the ENABLE_AGNOCAST environment variable

When ENABLE_AGNOCAST is not set or set to 0, this macro falls back to standard rclcpp_components_register_node behavior.

find_package(autoware_agnocast_wrapper REQUIRED)

ament_auto_add_library(my_node_component SHARED src/my_node.cpp)
ament_target_dependencies(my_node_component autoware_agnocast_wrapper)

autoware_agnocast_wrapper_register_node(my_node_component
  PLUGIN "my_package::MyNode"
  EXECUTABLE my_node
)

Parameters:

Valid executor values:

• ROS2_EXECUTOR: SingleThreadedExecutor, MultiThreadedExecutor
• AGNOCAST_EXECUTOR: SingleThreadedAgnocastExecutor, MultiThreadedAgnocastExecutor, CallbackIsolatedAgnocastExecutor, AgnocastOnlySingleThreadedExecutor, AgnocastOnlyMultiThreadedExecutor, AgnocastOnlyCallbackIsolatedExecutor

Node class requirements:

The required PLUGIN base class depends on the AGNOCAST_EXECUTOR type. The generated template enforces this via if constexpr at compile time:

Non-AgnocastOnly executors use NodeInstanceWrapper::get_node_base_interface() directly, which works with any node type (rclcpp::Node, agnocast_wrapper::Node, etc.) without requiring a cast. AgnocastOnly executors require get_agnocast_node(), which is only available on autoware::agnocast_wrapper::Node.

File truncated at 100 lines see the full file

Changelog for package autoware_agnocast_wrapper

1.8.0 (2026-05-01)

• chore: align package versions to 1.7.0 and reset changelogs

• Merge remote-tracking branch 'origin/main' into tmp/bot/bump_version_base

• docs(autoware_agnocast_wrapper): use FindPackageShare and PathJoinSubstitution in Python launch examples (#999)

• fix(autoware_agnocast_wrapper): support jazzy (rclcpp 28~) (#980) fix(autoware_agnocast_wrapper): fix Jazzy build by using version-conditional callback type alias

• fix(autoware_agnocast_wrapper): fix false positive LD_PRELOAD warning in agnocast_env.launch.py (#973)

• refactor(autoware_agnocast_wrapper): remove executor threading model consistency validation (#970)

  • refactor(autoware_agnocast_wrapper): remove executor threading model consistency validation
  • docs(autoware_agnocast_wrapper): clarify behavior reference tables in README

  - Reword introductory sentence to clarify that only ROS2_EXECUTOR matters when ENABLE_AGNOCAST=0

  - Use full CMake option strings (e.g. SingleThreadedExecutor) instead of abbreviations in both behavior reference tables

  • style(pre-commit): autofix

  * fix(autoware_agnocast_wrapper): fix forbidden word ROS2 to ROS 2 in README ---------Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

• feat(autoware_agnocast_wrapper): support message filter in agnocast wrapper (#951)

  * feat(autoware_agnocast_wrapper): add register_node macro for runtime rclcpp/agnocast switching Add [autoware_agnocast_wrapper_register_node]{.title-ref} CMake macro as a drop-in replacement for [rclcpp_components_register_node]{.title-ref}. When ENABLE_AGNOCAST=1, it generates a standalone executable that can switch between rclcpp::Node and agnocast::Node at runtime based on the ENABLE_AGNOCAST environment variable. When ENABLE_AGNOCAST is not set, it falls back to standard rclcpp_components_register_node behavior with zero overhead. Key features:

  • Configurable ROS2 and Agnocast executor types
  • Two-pass template generation (configure_file + file(GENERATE))
  • Support for both rclcpp::Node and agnocast_wrapper::Node plugins
  • Target existence validation at configure time
  • ABI consistency enforcement via autoware_agnocast_wrapper_setup()
  • Change agnocastlib from build_depend to depend
  • fix(autoware_agnocast_wrapper): add static_assert to enforce PLUGIN base class at compile time

  * fix(autoware_agnocast_wrapper): add runtime ROS2 fallback for AgnocastOnly executors When agnocast_only=true but ENABLE_AGNOCAST=0 at runtime, the node now falls back to the ROS2 executor instead of unconditionally using the AgnocastOnly executor.

  * fix(autoware_agnocast_wrapper): warn on mismatched executor threading models Emit a CMake WARNING when ROS2_EXECUTOR and AGNOCAST_EXECUTOR have different threading models (e.g., SingleThreadedExecutor with MultiThreadedAgnocastExecutor), as this silently changes behavior depending on the runtime ENABLE_AGNOCAST value.

  • docs(autoware_agnocast_wrapper): add executor behavior reference table to README
  • style(pre-commit): autofix
  • fix(autoware_agnocast_wrapper): replace forbidden word ROS2 with ROS 2
  • style(pre-commit): autofix

  * fix(autoware_agnocast_wrapper): remove static_assert that fails in non-template main() The static_assert inside if constexpr (agnocast_only) is always evaluated because main() is not a template function. Additionally, the component type header is not included in the generated source (loaded via class_loader at runtime), so the type cannot be resolved at compile time.

  • delete deprecated mark from publish(const MessageT&) API
  • support message_filter in agnocast_wrapper
  • style(pre-commit): autofix
  • fix cpplint
  • fix cpplint
  • add comments

File truncated at 100 lines see the full file