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/autowarefoundation/agnocast
• Agnocast Documentation: https://autowarefoundation.github.io/agnocast_doc/main/
• 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.

agnocast_wrapper::Node does not publicly derive from rclcpp::Node. It exposes a curated subset of the rclcpp::Node surface and forwards each member to the underlying implementation (rclcpp::Node or agnocast::Node). The member names and argument lists are identical in both builds (ENABLE_AGNOCAST=0 and =1), so a node written against it compiles unchanged either way — provided you spell the handle, options and message types with the AUTOWARE_* macros (see Type spellings). If you need an API that is not listed below, extend the wrapper, or reach the underlying node via get_rclcpp_node() (declared in both builds, but it throws when the node is in Agnocast mode — see the build-modes table).

Supported API surface

The following members / free functions are provided. Unless noted, signatures mirror their rclcpp::Node counterparts.

OnSetParametersCallbackType is aliased in this namespace and resolves to the correct rclcpp type for both Humble (rclcpp 16.x) and Jazzy (rclcpp 28+).

Polling subscribers are not a Node member. Use the free function polling::create_polling_subscriber<MessageT>(node, topic, qos) — see Polling Subscriber.

Reading another node’s parameters is not a Node member either. Use autoware::agnocast_wrapper::AsyncParametersClient, which takes a Method 2 node. Of the parameter service calls it exposes only get_parameters(), alongside wait_for_service() and service_is_ready(); the setter, descriptor and listing calls are not wrapped yet, and on_parameter_event() has no Agnocast counterpart. On the Agnocast backend the response arrives over an Agnocast subscription, so get_parameters() resolves its future only while an Agnocast executor spins the node.

create_client() and create_service() also accept an rmw_qos_profile_t. This is not part of the supported surface: it exists so that Humble-era call sites passing rmw_qos_profile_services_default keep compiling, and it will be removed. Pass an rclcpp::QoS.

Type spellings

The member names and argument lists above are the same in both builds, but the handle, options and message types they use are not the same C++ types. Always spell them with the AUTOWARE_* macros so the same source compiles in both builds:

A subscription callback may also take the plain MessageT::ConstSharedPtr; it needs no macro because it is spelled the same in both builds.

On the Agnocast path an owning handle must not outlive the subscription that delivered it. This covers AUTOWARE_MESSAGE_CONST_SHARED_PTR, a callback taking MessageT::ConstSharedPtr, the pointer returned by polling::take_data(), a message delivered to a message_filters synchronizer callback, and AUTOWARE_CLIENT_RESPONSE_PTR, which the client delivers through a response subscription of its own and which therefore must not outlive the client. Reading it afterwards can return recycled memory, and releasing it can abort the process. Members are destroyed in reverse declaration order, so declare the subscription before any member that caches a message:

AUTOWARE_SUBSCRIPTION_PTR(PointCloud2) sub_;   // declared first -> destroyed last
std::shared_ptr<const PointCloud2> latest_;    // destroyed first -> safe

AUTOWARE_CLIENT_PTR(SrvT) client_;             // same rule for a cached client response
std::shared_ptr<const SrvT::Response> cached_;

The DDS path lets the same pointer be held indefinitely, so a node validated only with ENABLE_AGNOCAST=0 will not show the problem.

File truncated at 100 lines see the full file

Changelog for package autoware_agnocast_wrapper

1.10.0 (2026-09-28)

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

• feat(autoware_agnocast_wrapper): add the autoware_node launch action (#1457)

  • feat(autoware_agnocast_wrapper): add the autoware_node launch action
  • fix(autoware_agnocast_wrapper): follow use_agnocast and keep other nodes off Agnocast
  • fix(autoware_agnocast_wrapper): accept plain strings in AutowareNode
  • fix(autoware_agnocast_wrapper): name the node in the mode and heaphook errors
  • refactor(autoware_agnocast_wrapper): drop a duplicate lookup and parse check
  • docs(autoware_agnocast_wrapper): document the autoware_node_plugins resource

  * test(autoware_agnocast_wrapper): run the autoware_node test without the install space ---------

• refactor(autoware_agnocast_wrapper): drop the discovery agent spawn from the launch wrapper (#1451)

  • feat(autoware_agnocast_wrapper): drop the discovery agent spawn from the launch wrapper
  • style(pre-commit): autofix
  • docs(autoware_agnocast_wrapper): note that Agnocast starts the discovery agent

  * docs(autoware_agnocast_wrapper): note how the discovery agent auto-start can fail The auto-start only warns and continues when the agent is unavailable, so name the two ways it can be absent as a starting point for the reader.

  * docs(autoware_agnocast_wrapper): drop the discovery agent troubleshooting note The paragraph described agnocastlib internals inaccurately: the commands fall back to the local ioctl view rather than coming back empty, the AGNOCAST_NO_DISCOVERY_AGENT path short-circuits before any logging, and the env var predicate accepts only 1/true/yes rather than any value. Rather than track internals that already differ between agnocastlib releases, drop the paragraph. The sentence above it already carries the point: the wrapper no longer launches the agent because Agnocast does. ---------Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com> Co-authored-by: Tran Huu Nhat Huy <<29034232+TranHuuNhatHuy@users.noreply.github.com>>

• feat(autoware_agnocast_wrapper): support polling_policy::All (#1443)

  • feat(autoware_agnocast_wrapper): support polling_policy::All
  • test(autoware_agnocast_wrapper): poll for the All batch instead of sleeping
  • refactor(autoware_agnocast_wrapper): decide the depth rule at the call site
  • refactor(autoware_agnocast_wrapper): keep the polling helpers in the package detail namespace
  • refactor(autoware_agnocast_wrapper): spell the All vector like the other policies
  • refactor(autoware_agnocast_wrapper): point the depth rejection at polling_policy::All
  • docs(autoware_agnocast_wrapper): scope the cross-backend promise to the policies that keep it

  * docs(autoware_agnocast_wrapper): note what holding an All vector costs ---------Co-authored-by: atsushi yano <<55824710+atsushi421@users.noreply.github.com>>

• feat(autoware_agnocast_wrapper): add generic pubsub wrapper (#1442)

  • feat: add generic pubsub wrapper
  • style(pre-commit): autofix
  • refactor(autoware_agnocast_wrapper): return client responses as std::shared_ptr (#1419)
  • feat(autoware_agnocast_wrapper): add to_shared_ptr() for client responses
  • refactor(autoware_agnocast_wrapper): move to_shared_ptr() to the message_ptr layer
  • style(pre-commit): autofix
  • fix(autoware_agnocast_wrapper): reject publisher-side handles in to_shared_ptr()
  • refactor(autoware_agnocast_wrapper): return client responses as std::shared_ptr
  • style(pre-commit): autofix
  • docs(autoware_agnocast_wrapper): document the client response in the lifetime rules

  * docs(autoware_agnocast_wrapper): drop the stale client response row from the type table ---------Co-authored-by: pre-commit-ci[bot]

File truncated at 100 lines see the full file