proto2ros

When exposing Protobuf interfaces to ROS 2, proto2ros streamlines message translation and generation, so as to trivially augment rosidl pipeline invocations to take Protobuf definitions and output ROS 2 message definitions. Additionally, message conversion APIs are generated to simplify bridging Protobuf and ROS 2 message code.

Table of contents

• Features
  • Message generation
    • Package mapping
    • Type mapping
      • Scalar types
      • Message types
      • Enum types
      • Map types
      • Any types
      • Recursive types
    • Field mapping
      • Optional fields
      • Repeated fields
      • One-of fields
      • Deprecated fields
      • Reserved fields
  • Code generation
    • Python APIs
    • C++ APIs
• Configuration
• Use cases
  • Dual Protobuf / ROS 2 package
  • ROS 2 vendored Protobuf messages

Features

Message generation

Protobuf enumeration and message definitions are translated to equivalent ROS 2 message definitions. Protobuf definitions, including comments, are extracted from Protobuf descriptor sets, as generated by protoc. More than one ROS 2 message definition may be necessary to represent a given Protobuf definition, as explained in the map types and one-of fields subsections.

Package mapping

All Protobuf packages to which processed definitions belong are implicitly mapped to the ROS 2 package that will host their ROS 2 message equivalents. As for the rest, the user may specify a package mapping in proto2ros configuration. Whether that is necessary or not depends on how message types are mapped.

Type mapping

Scalar types

The mapping between Protobuf and ROS 2 scalar types is shown below.

Note that, unlike all others, the Protobuf bytes scalar type maps to a sequence type in ROS 2. This is convenient but forces special handling of repeated bytes fields.

Messages types

Every Protobuf message maps to a ROS 2 message. For statically typed message (as opposed to dynamically typed google.protobuf.Any messages), this mapping is derived from the sequential application of the following rules, on first match wins basis:

• A user-defined message mapping in proto2ros configuration matches. Fully qualified message names are used verbatim.
• A user-defined or implicit package mapping in proto2ros configuration matches. If multiple matches are found, the longest match applies. Fully qualified message names are camel-cased.
• Passing unknown Protobuf messages is allowed by proto2ros configuration. Then proto2ros/AnyProto is used.

For google.protobuf.Any messages, the rules for any types apply.

It is through message mappings that ad-hoc equivalences can be established e.g. some Protobuf message may be equivalent to some standard ROS 2 message (and this is already the case for several core Protobuf messages, see default proto2ros configuration). It is through package mappings that equivalences generated by proto2ros in full, for a given ROS 2 package or one of its dependencies, interact with each other.

For example, given the following configuration overlay:

File truncated at 100 lines see the full file

Changelog for package proto2ros

1.0.0 (2024-12-02)

• Add proto2ros documentation (#5)
• Add GHA CI workflow (#3)
• Please pre-commit linters (#2)
• Bring sources from [bdaiinstitute/ros_utilities]{.title-ref} (#1)
• Contributors: mhidalgo-bdai