rclcpp compatibility

What a ported rclcpp node gets, by the upstream spelling it uses. “Hosted builds” means a target built with NROS_CPP_STD, which the ament verbs set for a ported package. The porting steps are in Port a C++ node.

Measured: the stock rclcpp examples

Each file below, from ros2/examples (Humble and Jazzy), is compiled, linked and booted beside its port. The table is rendered from the record the test holds the counts to, so it cannot drift:

Two surfaces: freestanding, and NROS_CPP_STD

One set of headers ships two API shapes, and a build picks one.

The freestanding surface is the default and it is not a fallback. It is plain C++14 with no standard library, no exceptions and no RTTI: rclcpp::Node, create_* writing through an out-reference and returning an rclcpp::Result, const char* for names, uint64_t period_ms for durations. It is the surface for every node written for nano-ros, native host builds included.

The std surface is an opt-in and it is reached only by defining NROS_CPP_STD. Defining it turns on the six NROS_CPP_HAS_* capability macros in rclcpp/detail/std_detect.hpp, and with them: the std::string / std::function / std::chrono / std::vector convenience overloads in nros/std_compat.hpp, the RCLCPP_*_STREAM logging macros, and — the piece that actually motivates the flag — rclcpp::Node’s upstream-shaped factories, which return std::shared_ptr and take const std::string& names.

Do I need this flag?

The split is ported rclcpp code versus code written for nano-ros. It is not host versus embedded. A native Linux build does not want the flag any more than a Cortex-M3 build does; a ported node wants it on both.

If you are unsure, build without it. The failure direction is loud: a missing overload at compile time, never a silent behaviour change.

Turning it on

Define it on the target, not per file:

target_compile_definitions(my_ported_node PRIVATE NROS_CPP_STD=1)

Per target rather than per #define-before-include, because the macro changes the layout of rclcpp::Node (it carries hosted-only members and an enable_shared_from_this base), so two translation units of one image that disagree about it are an ODR/layout break rather than a missing function. An image may set the flag on one module and not another, so keep the definition at target granularity and give every translation unit of a target the same answer.

A ported package usually needs none of this. nano-ros’s ament surface sets NROS_CPP_STD=1 on every target its ament_* verbs create, and find_package(rclcpp) sets it on whatever links rclcpp::rclcpp, so a ported package already has the surface it needs; see Porting a ROS 2 C++ node.

The ported shape

With the flag set, an upstream node’s own spelling compiles: std::make_shared, SharedPtr returns, a std::string topic, a QoS depth, a capturing lambda and a std::chrono period.

#include <rclcpp/rclcpp.hpp>
#include "std_msgs/std_msgs.hpp"

using namespace std::chrono_literals;

int main(int argc, char** argv) {
    rclcpp::init(argc, argv);
    auto node = std::make_shared<rclcpp::Node>("talker");
    auto pub = node->create_publisher<std_msgs::msg::Int32>("chatter", 10);
    int count = 0;
    auto timer = node->create_wall_timer(1s, [&]() {
        std_msgs::msg::Int32 msg;
        msg.data = ++count;
        pub->publish(msg);
    });
    rclcpp::spin(node);
    rclcpp::shutdown();
}

A failed create_* here ABORTS, naming the call, because upstream throws and nano-ros has no exceptions. To handle the failure instead, use the Result-returning forms above.

Why it is not detected for you

Earlier releases discovered the capability macros from the include path with __has_include, so a hosted compiler handed you the std-flavoured API whether you asked for it or not. That was removed because no probe answers the question correctly on both embedded toolchains:

Each probe is right on exactly one embedded toolchain and wrong on the other: libstdc++ 13 added bits/requires_hosted.h, so header presence stopped implying usability. Only the request is right on both, because it is not a probe — it is you saying which surface you want. The full measurement is in the comments of rclcpp/detail/std_detect.hpp.

Hosted-only shapes

Subscriptions with MessageInfo (hosted)

On a hosted build (NROS_CPP_STD) a dispatch subscription’s callback may take upstream’s const rclcpp::MessageInfo& as a second argument, after the message in any of its four forms (const M&, std::shared_ptr<const M>, std::shared_ptr<M>, std::unique_ptr<M>):

auto sub = node->create_subscription<std_msgs::msg::Int32>(
    "/chatter", 10, [](const std_msgs::msg::Int32& msg, const rclcpp::MessageInfo& info) {
        const auto& r = info.get_rmw_message_info();
        printf("%d from seq %llu at %lld ns\n", msg.data,
               (unsigned long long)r.publication_sequence_number, (long long)r.source_timestamp);
    });

get_rmw_message_info() carries source_timestamp, received_timestamp, publication_sequence_number, reception_sequence_number and the 24-byte publisher_gid, as the backend reported them. A backend that reports none (XRCE, uORB) leaves every field zero. from_intra_process is always false. A freestanding build refuses the shape at compile time: the metadata path keeps the callable on the heap. SubscriptionOptions::message_info = true with a callback that takes no MessageInfo aborts the create, because it would otherwise configure nothing.

Actions with upstream’s goal handles (hosted)

On a hosted build (NROS_CPP_STD) the stock rclcpp_action spellings are drop-ins over the two classes above:

using Fibonacci = example_interfaces::action::Fibonacci;
using GoalHandle = rclcpp_action::ServerGoalHandle<Fibonacci>;
using namespace std::placeholders;

// Server: free factory over the node interfaces, std::bind-ed members.
rclcpp_action::Server<Fibonacci>::SharedPtr server = rclcpp_action::create_server<Fibonacci>(
    get_node_base_interface(), get_node_clock_interface(), get_node_logging_interface(),
    get_node_waitables_interface(), "fibonacci",
    std::bind(&MyNode::handle_goal, this, _1, _2),    // (const GoalUUID&, shared_ptr<const Goal>)
    std::bind(&MyNode::handle_cancel, this, _1),      // (shared_ptr<GoalHandle>)
    std::bind(&MyNode::handle_accepted, this, _1));   // (shared_ptr<GoalHandle>)
// in handle_accepted: goal_handle->get_goal(), ->publish_feedback(fb),
// ->is_canceling(), ->succeed(result) / ->abort(result) / ->canceled(result)

// Client: SendGoalOptions' upstream fields, bound per goal by async_send_goal.
auto client = rclcpp_action::create_client<Fibonacci>(this, "fibonacci");
auto opts = rclcpp_action::Client<Fibonacci>::SendGoalOptions();
opts.goal_response_callback = [](rclcpp_action::ClientGoalHandle<Fibonacci>::SharedPtr h) {};
opts.feedback_callback = [](auto h, const std::shared_ptr<const Fibonacci::Feedback> fb) {};
opts.result_callback = [](const rclcpp_action::Client<Fibonacci>::WrappedResult& r) {
    // r.code: rclcpp_action::ResultCode::SUCCEEDED / ABORTED / CANCELED; r.result
};
auto fut = client->async_send_goal(goal, opts);   // rclcpp::Future<GoalAccept>

// The handle-taking calls return upstream's std::shared_future.
auto result = client->async_get_result(goal_handle);   // shared_future<WrappedResult>
auto cancel = client->async_cancel_goal(goal_handle);  // shared_future<CancelResponse::SharedPtr>
if (rclcpp::spin_until_future_complete(node, result) == rclcpp::FutureReturnCode::SUCCESS) {
    const auto& wrapped = result.get();
}
// server, after handle_goal returned ACCEPT_AND_DEFER:
goal_handle->execute();   // ACCEPTED -> EXECUTING, status array published

X<A>::SharedPtr is rclcpp::Owned<X<A>> (the entity by value), and the get_node_*_interface() handles name the node and do nothing else. A goal handle is a heap token over the goal id: every call forwards to the server or client keyed by it, and the goal’s state stays in the arena. Drive it from the executor’s task only — not from a thread you started — and do not move the server while a handle is in use. The callbacks run from the executor’s dispatch, beside the client-wide set_callbacks ones. async_send_goal returns the goal-keyed rclcpp::Future<GoalAccept>, not a std::shared_future; get_goal_stamp is absent.

async_get_result / async_cancel_goal / async_cancel_all_goals / async_cancel_goals_before return a rclcpp_action::detail::DrivenSharedFuture<T>, which IS-A std::shared_future<T>: its is_ready() (what spin_until_future_complete polls), wait_for and get drive the client’s dispatch and executor while they wait, since no other thread fulfils it. Converted to a bare std::shared_future it still completes, but only when something else drives the client. Every async_get_result for one goal returns the handle’s own future; a result-aware goal’s handle is kept by the client until its result arrives, as upstream’s pending request keeps it. Cancel replies are taken by the executor’s spin, as upstream’s executor delivers them: the spin settles the waiting async_cancel_* future and runs its cancel_callback, so a caller that keeps only the callback needs no poll(). A nano-ros server acts on the zero-id cancel-all / cancel-before forms as an rclcpp server does. A reply no future claims is kept for try_recv_cancel_response, oldest first, up to rclcpp_action::CANCEL_STASH_CAP (4) per client. These need std::promise, so they are hosted-only twice over: a libstdc++ built without threads (arm-none-eabi) refuses them as a freestanding build does.

ServerGoalHandle::execute() and Server<A>::execute(goal_id) move an ACCEPTED goal to EXECUTING and publish the status array; the latter reports NotFound / NotAllowed where upstream raises. create_server executes an ACCEPT_AND_EXECUTE goal before handle_accepted; the goal-id API leaves it ACCEPTED.

Goal slots. Each action sub-client holds at most MAX_CONCURRENT_GOALS (4) requests in flight. A future dropped (or cancel()ed) before its reply frees its request’s slot, unless something else still waits on that reply — a client-wide set_callbacks hook, or an upstream goal (async_send_goal with callbacks, async_get_result). A late reply for a freed slot is dropped. On a freestanding build each of these shapes is a compile error (NROS_RCLCPP_REFUSE_ACTION_GOAL_HANDLE) naming the goal-id-keyed form above; create_client alone works there.

Action client futures

Future-based async. send_goal_future() / get_result_future() return a Future<T> keyed by its goal: each future receives only its own goal’s acceptance or result, whether the executor dispatched it during spin_once or the future’s own poll took it, and a result for a goal nobody waits on is dropped. At most MAX_CONCURRENT_GOALS of each may be pending per client; past that the send is refused and the future is empty (valid() false):

auto fut = client.send_goal_future(goal);
typename decltype(client)::GoalAccept accept;
RCLCPP_TRY(fut.wait(executor.handle(), 5000, accept));
if (accept.accepted) {
    auto rfut = client.get_result_future(accept.goal_id);
    Fibonacci::Result result;
    RCLCPP_TRY(rfut.wait(executor.handle(), 10000, result));
}

GoalAccept is a nested type on rclcpp_action::Client<A> (16-byte UUID + bool accepted).

Parameters and /parameter_events

Parameters are methods on the node (declare_parameter<T>, get_parameter<T>, set_parameter<T>, undeclare_parameter), over the executor’s one store. node.start_parameter_services() serves them on the six rcl_interfaces services, so ros2 param reaches them, and publishes /parameter_events (rcl_interfaces/msg/ParameterEvent, rmw_qos_profile_parameter_events) as rclcpp’s node does:

rclcpp::Node node;
RCLCPP_TRY(executor.create_node(node, "ctrl"));
node.declare_parameter<int64_t>("gain", 3);   // before or after: both reported
RCLCPP_TRY(node.start_parameter_services());  // start-up event: new_parameters = [gain]
node.set_parameter<int64_t>("gain", 4);       // changed_parameters = [gain]
node.undeclare_parameter("gain");             // deleted_parameters = [gain]

Each event names the node’s fully qualified name in node; the events are published on the next spin. The image needs the param_services capability. One publisher per executor serves every node. It is on for every served node unless the node was built with rclcpp::NodeOptions().start_parameter_event_publisher(false), which opts that one node out; the other nodes keep publishing.

To react to OTHER nodes’ changes, a hosted build has rclcpp::ParameterEventHandler. It subscribes to /parameter_events once, on the node you give it:

auto handler = std::make_shared<rclcpp::ParameterEventHandler>(node);
auto h = handler->add_parameter_callback(
    "gain", [](const rclcpp::Parameter& p) { use(p.as_int()); }, "/controller");
auto e = handler->add_parameter_event_callback(
    [](const rcl_interfaces::msg::ParameterEvent& ev) { /* every event */ });

Keep the handles: dropping one unregisters it, as upstream’s do. An empty node name means this node, and a relative one resolves against this node’s namespace. A parameter callback sees new and changed values, never deletions. An event callback receives the type it takes, so rcl_interfaces must be generated for the image. The per-parameter handle is rclcpp::ParameterCallbackHandle, as upstream (the handler’s nested ParameterEventHandler::ParameterCallbackHandle names the same type). A freestanding build refuses the handler at compile time; there, subscribe to /parameter_events with create_subscription yourself.

Design background

• RFC-0089: ROS 2 API adoption, and the compile-or-conform rule — upstream’s namespaces and names, the _in rule, the hosted surface
• RFC-0018: C++ API design — freestanding C++14, no exceptions, the Result channel