Skip to content

autoware_component_interface_specs#

This package defines the standardized component interface specifications for Autoware Core, ensuring consistent communication and interaction between various components in the Autoware autonomous driving stack.

Purpose#

The purpose of this package is to:

  • Provide a single source of truth for component interface definitions
  • Ensure consistency across different implementations
  • Facilitate modular development and component interchangeability
  • Document the communication protocols between Autoware Core components

Structure#

The package contains interface specifications for various components, including:

  • Message definitions
  • Service interfaces
  • Action interfaces

Usage#

To use these interface specifications in your component:

  1. Add this package as a dependency in your package.xml:

    <depend>autoware_component_interface_specs</depend>

  2. Use the provided interfaces in your component code.

    #include <autoware/component_interface_specs/localization.hpp>
// Example: Creating a publisher using the interface specs
using KinematicState = autoware::component_interface_specs::localization::KinematicState;
rclcpp::Publisher<KinematicState::Message>::SharedPtr publisher_ =
create_publisher<KinematicState::Message>(
KinematicState::name,
autoware::component_interface_specs::get_qos<KinematicState>());
// Example: Creating a subscription using the interface specs
auto subscriber_ = create_subscription<KinematicState::Message>(
KinematicState::name,
autoware::component_interface_specs::get_qos<KinematicState>(),
std::bind(&YourClass::callback, this, std::placeholders::1));

Versioning#

Each domain namespace declares a semantic Version (version.hpp) and a Specs tuple listing every interface it owns. 0.x denotes an unstable interface while the standard is stabilizing. Compatibility is decided on the MAJOR field only; is_compatible is the reference encoding of that rule for consumers that compile against this package. The deploy-time admission gate in autoware_component_interface_admission is a no-dependency leaf package, so it restates the same relation rather than calling is_compatible — the two must be changed together.

A domain declares its version, its Specs registry, and the ADL hook that spec_version<Spec>() resolves through in one macro, so the three cannot drift apart:

namespace autoware::component_interface_specs::control
{
struct ControlCommand { /* ... */ };

AUTOWARE_COMPONENT_INTERFACE_SPECS_DEFINE_DOMAIN(0, 1, 0, ControlCommand)
}  // namespace autoware::component_interface_specs::control

Quality of service#

Topic specs carry the QoS their endpoints are created with (depth, reliability, durability); get_qos<Spec>() turns that into an rclcpp::QoS.

Services have a QoS profile too, but not a per-spec one. Every create_service and create_client call takes ROS 2's rmw_qos_profile_services_default — KEEP_LAST(10), RELIABLE, VOLATILE — unmodified, so all services really do run under identical conditions. Rather than repeat that profile on every ServiceSpec, it is declared once as service_qos in utils.hpp and returned by get_service_qos(). test_service_qos.cpp asserts it still equals the RMW default it mirrors, so a change to that default surfaces as a test failure instead of as silent drift between the specs and the wire.

C++ standard#

The domain headers, version.hpp and utils.hpp are C++17, matching the CMAKE_CXX_STANDARD 17 that autoware_package() gives every Autoware target.

concepts.hpp needs C++20, because the standard library only exposes <concepts> in C++20 mode. A target that wants it opts in:

target_compile_features(<target> PRIVATE cxx_std_20)

CMake raises that one target to -std=c++20 and leaves every other target — and every C++17 consumer of the domain headers — on -std=c++17. This is what the package's own generate_interface_manifest and gtest targets do, and it builds on Humble / gcc-11 (Ubuntu 22.04) as well as on Jazzy. Both targets are BUILD_TESTING-gated, so a C++20 compile failure in either could never break the header-only package for its C++17 consumers.

Below C++20, concepts.hpp is an empty header rather than a hard error, so including it is always safe. Test AUTOWARE_COMPONENT_INTERFACE_SPECS_HAS_CONCEPTS before naming anything it declares.

Interface manifest#

interface_manifest.json is a machine-readable list of every registered interface: its domain, interface name, message or service type, kind, version, and the QoS its endpoints are created with. It is generated from the Specs tuples by the generate_interface_manifest tool and committed to the repository as the source of truth.

{
  "domain": "control",
  "interface": "/control/command/control_cmd",
  "type": "autoware_control_msgs/msg/Control",
  "kind": "topic",
  "version": "0.1.0",
  "qos": {
    "history": "keep_last",
    "depth": 1,
    "reliability": "reliable",
    "durability": "volatile"
  }
}

reliability and durability are the two axes ROS 2 checks when it decides whether a publisher and a subscription may talk at all, which is why a deploy-time gate needs them alongside the type and the version. Service entries carry the shared service_qos profile.

Regenerate the manifest by hand after changing any domain's specs, QoS or versions:

colcon build --symlink-install --packages-select autoware_component_interface_specs
./build/autoware_component_interface_specs/generate_interface_manifest \
  src/autoware_component_interface_specs/interface_manifest.json

The generator emits the same layout Prettier produces, so the committed file is stable across regenerations. Adjust the output path to match where the package lives in your workspace. test_manifest.cpp diffs the generator's output against the committed file, so a stale manifest fails the build rather than reaching consumers.

Interface type-hash lockfile#

interface_type_hashes.jazzy.lock records the RIHS01 type hash (the ROS Interface Hashing Standard, proposed in REP-2011) of every registered message and service type. A RIHS01 hash is a deterministic function of the full type description — transitively including every nested .msg include — so a change to a type's definition in any repository changes its hash. This is the drift tripwire that complements the same-PR version bump: it catches a forgotten bump, and it is the only mechanism for the types owned by other repositories.

RIHS01 hashes exist only on ROS 2 Iron and newer, so the lockfile is Jazzy-specific and the generator's hash-emitting path is #if __has_include(<rosidl_runtime_c/type_hash.h>)-guarded — on Humble the tool is a no-op and the freshness test skips.

Regenerate it (Jazzy only) once you have established that the type change behind the new hash is intentional and reviewed — see "When the freshness gate fails" below before running this:

colcon build --symlink-install --packages-select autoware_component_interface_specs
./build/autoware_component_interface_specs/generate_type_hashes \
  src/autoware_component_interface_specs/interface_type_hashes.jazzy.lock

test_type_hashes.cpp diffs the generator's output against the committed file, but only when AUTOWARE_CIS_CHECK_TYPE_HASHES is set — this repo's own GitHub Actions sets it, while the ROS build farm's devel jobs do not, so a dependency-version skew on the build farm can never turn those jobs red. The always-on covers_every_manifest_type test still guarantees the lockfile and interface_manifest.json describe the same set of types.

When the freshness gate fails#

A red committed_lockfile_is_up_to_date means a registered type's definition changed relative to the last state a reviewer approved. Regenerating the lockfile is the last step, not the first — a bare refresh launders an unreviewed type change into the committed file and leaves the gate with nothing to catch. Decide which case you are in:

  1. You intentionally changed a registered type definition. Bump the affected domain's version in its header, then regenerate the lockfile in the same pull request. The version bump is what tells consumers the interface moved; the lockfile only records that it did.
  2. You did not touch any type definition. Then the change arrived through a message-repository dependency — most often autoware_msgs, or a type owned by geometry_msgs / nav_msgs / autoware_adapi_v1_msgs. Find the upstream commit that moved the hash, decide whether that change is acceptable for this interface surface, and reference it in the pull request. If it is not acceptable, the fix belongs upstream, not here.

For reviewers. A commit that only refreshes interface_type_hashes.jazzy.lock, with no accompanying domain version bump and no reference to the upstream change that moved the hash, should be rejected — it is indistinguishable from silencing the gate. The lockfile's value is entirely in the review it forces; a hash diff nobody explained has bought nothing.

Coverage limit. A RIHS01 hash does not cover message constants or field default values, so an enum-only .msg edit or a default-value change does not change the hash. The lockfile is therefore a structural/wire tripwire — the secondary check. The primary enforcement is a path-based gate that requires a domain version bump when a registered type's .msg/.srv changes in the same repository; it becomes fully effective once the message definitions and this package live together (tracked in autoware_msgs#169). Until then, the lockfile is the available mechanism for every row.