Defining a Type Adapter

In order to adapt a custom type to a ROS type, the user must create a template specialization of this structure for the custom type. In that specialization they must:

• change is_specialized to std::true_type,
• specify the custom type with using custom_type = ...,
• specify the ROS type with using ros_message_type = ...,

• provide static convert functions with the signatures:

  • static void convert_to_ros_message(const custom_type &, ros_message_type &),
  • static void convert_to_custom(const ros_message_type &, custom_type &)

The convert functions must convert from one type to the other.

For example, here is a theoretical example for adapting std::string to the std_msgs::msg::String ROS message type:

template<>
struct rclcpp::TypeAdapter<
   std::string,
   std_msgs::msg::String
>
{
  using is_specialized = std::true_type;
  using custom_type = std::string;
  using ros_message_type = std_msgs::msg::String;

  static
  void
  convert_to_ros_message(
    const custom_type & source,
    ros_message_type & destination)
  {
    destination.data = source;
  }

  static
  void
  convert_to_custom(
    const ros_message_type & source,
    custom_type & destination)
  {
    destination = source.data;
  }
};

Type Adaptation in Topics

The adapter can then be used when creating a publisher or subscription, e.g.:

using MyAdaptedType = TypeAdapter<std::string, std_msgs::msg::String>;
auto pub = node->create_publisher<MyAdaptedType>("topic", 10);
auto sub = node->create_subscription<MyAdaptedType>(
  "topic",
  10,
  [](const std::string & msg) {...});

You can also be more declarative by using the adapt_type::as metafunctions, which are a bit less ambiguous to read:

using AdaptedType = rclcpp::adapt_type<std::string>::as<std_msgs::msg::String>;
auto pub = node->create_publisher<AdaptedType>(...);

If you wish, you may associate a custom type with a single ROS message type, allowing you to be a bit more brief when creating entities, e.g.:

// First you must declare the association, this is similar to how you
// would avoid using the namespace in C++ by doing `using std::vector;`.
RCLCPP_USING_CUSTOM_TYPE_AS_ROS_MESSAGE_TYPE(std::string, std_msgs::msg::String);

// Then you can create things with just the custom type, and the ROS
// message type is implied based on the previous statement.
auto pub = node->create_publisher<std::string>(...);

Note that it is also possible to use a ROS type with a publisher or subscriber that has been specialized to use a custom message, e.g.:

using AdaptedType = rclcpp::adapt_type<std::string>::as<std_msgs::msg::String>;
auto pub = node->create_publisher<AdaptedType>(...);

// Publish a std::string
std::string custom_msg = "My std::string"
pub->publish(custom_msg);

// Publish a std_msgs::msg::String;
std_msgs::msg::String ros_msg;
ros_msg.data = "My std_msgs::msg::String";
pub->publish(ros_msg);

Type Adaptation in Services

Type adaptation can be used with a client and service by creating a struct that defines a type adapter for the request and the response. For example:

using MyAdaptedRequestType = TypeAdapter<std::string, std_msgs::msg::String>;
using MyAdaptedResponseType = TypeAdapter<bool, std_msgs::msg::Bool>;

struct MyServiceTypeAdapter {
   using Request = MyAdaptedRequestType;
   using Response = MyAdaptedResponseType;
};

auto client = node->create_client<MyServiceTypeAdapter>("service");
auto service = node->create_service<MyServiceTypeAdapter>(
  "service",
  [](const std::string & request) {...});

Similarly, either the request or response can be adapted:

using MyAdaptedRequestType = TypeAdapter<bool, std_msgs::msg::Bool>;

struct MySetBoolTypeAdapter {
   using Request = MyAdaptedRequestType;
   using Response = std_srvs::srv::SetBool::Response;
};

Type Adaptation in Actions

Similar to services, type adaptation can be used with action clients and action services by creating a struct that defines a type adapter for the request, feedback, and result. As with services, the ROS type for a request, feedback, or result can be specified for use in this structure as well.

struct MyActionTypeAdapter {
   using Goal = MyAdaptedGoalType;
   using Feedback = MyAdaptedFeedbackType;
   using Result = MyAdaptedResultType;
};

auto node = rclcpp::Node::make_shared("action_node");
auto action_client = rclcpp_action::create_client<MyActionTypeAdapter>(node, "action");
auto action_server = rclcpp_action::create_server<MyActionTypeAdapter>(
  node,
  "action",
  handle_goal,
  handle_cancel,
  handle_accepted);

Selecting a term

There are various terms that may be suitable for type adapting feature described. In selecting a term,

• Clearly communicate the described feature
• Clearly communicate the order of custom type and ROS type arguments

• The custom type should be the first argument so that * the custom type is the first argument in both the explicit and implicit syntax * the custom type is read first, for convenience
• The syntax reads well

Masquerade<std_msgs::msg::String>::as<std::string>

Masquerade<std::string>::as<std_msgs::msg::String>

Facade<std::string>::instead_of<std_msgs::msg::String>

TypeAdapter<std::string>::as<std_msgs::msg::String>

Including "Type" in the name

Most of the terms being considered refer to general design patterns and, thus, using just the pattern's name may cause naming collisions or confusion as those design patterns may be used in other parts of the ROS codebase. To reduce ambiguity, including the term selected with "Type" would make its usage clearer and help avoid name collisions; it should also make it easier for developers to find relevant documentation.

If the word "Type" should be appended or prepended to the selected term will largely be a matter of how it reads. For example, "TypeAdapter" is perhaps more natural than "AdapterType".

Adding this feature in rclcpp

Placing this feature in ROS 2's client support library, rcl, would allow this feature to be used in other client libraries, such as rclcpp and rclpy. However, we believe that the concrete benefits for C++ currently outweigh the potential benefits for existing or theoretical client libraries in other languages. For example, placing this feature in rclcpp allows us to avoid type erasure (which would be necessary to place this functionality into rcl) and to use ownership mechanics (unique and shared pointer) to ensure it is safely implemented. Another added advantage of placing this feature in rclcpp is that it reduce the number of function calls and calls that potentially are to functions in separate shared libraries.

Perhaps we can support a form of this feature in other languages in rcl or rmw in the future. One challenge in doing this is that it may require custom type support, which may be middleware specific. This possibility will be further explored in the future.

On the Location for Specifying the Type Adapter

It was suggested that we only template the Publisher::publish method, but in addition to being more convenient, specifying a type adapter for the publisher at instantiation rather than in Publisher::publish allows the intra process system to be setup to expect a custom type. Similarly, it is preferable to specify the adapted type at instantiation for subscriptions, service clients, service servers, action clients, and action servers.

Comparison to ROS 1's Type Adaptation

Although intended to be similar in functionality, the proposed feature and ROS 1's type adaptation support [5] have a few important differences:

• This feature will support both convert and (de)serialize functions, and require at least one or the other, but also allow both. The reason for this is that convert is superior for intra-process communication and the (de)serialization functions are better for inter-process communication.
• This feature will also require the user to write less code when creating an adapter, as compared to the ROS 1 implementation.
• An advantage of following the ROS 1 approach is that an extra copy can be avoided; although it is likely much more challenging to implement this feature the ROS 1 way because of the middleware.