Porting a ROS 2 C++ node to nano-ros

Goal: take a normal ROS 2 C++ node (one that compiles + runs under colcon build against ros-humble-*) and run it under nano-ros — without rewriting the source. The rclcpp:: names are declared by nano-ros’s own C++ headers — <rclcpp/rclcpp.hpp> is nros-cpp’s own umbrella, not a layer over another API. The CMake side is part of nano-ros’s own package: cmake/NanoRosAmentSurface.cmake defines the ament_* verbs, cmake/find/ holds the Find<pkg>.cmake modules, and diagnostic_updater is packages/api/nros-diagnostic-updater. So the only delta is build-script glue.

The canonical proof lives at examples/templates/cpp-port-minimal-publisher/ — the ROS 2 tutorial’s minimal_publisher.cpp vendored unmodified, building against nano-ros via the three glue lines below.

The one compile definition, and why you do not type it

A ported file names rclcpp::Node, std::make_shared<MyNode>() and create_publisher<M>(...) returning a SharedPtr. Those signatures are spelled in std::shared_ptr and std::string, and nano-ros compiles that surface only when a build asks for it by defining NROS_CPP_STD. It is never inferred from what your compiler happens to have on its include path.

nano-ros’s ament surface sets it for you: every target created through ament_auto_add_* / rclcpp_components_register_node, and every target linking rclcpp::rclcpp, gets it. A project following the two layers of glue below needs nothing extra. You type it yourself only when you build a ported translation unit some other way:

target_compile_definitions(my_ported_node PRIVATE NROS_CPP_STD=1)

Two things worth knowing before you reach for it:

• This is not a host-versus-embedded switch. Code written against rclcpp::Node does not want the flag on a native Linux build either; ported rclcpp code wants it on a Cortex-M3 build just as much. The split is whose code it is, not what it runs on. See C++ API — two surfaces.
• Define it per target, not per file. It changes the layout of rclcpp::Node, so two translation units of one image disagreeing about it is an ODR break rather than a missing function.

If you forget it the failure is loud and at compile time — an unknown rclcpp::Node, or a create_publisher overload that does not match — never a silent behaviour change.

Two layers of glue

Per-package CMakeLists.txt — zero nano-ros lines

The ported pkg’s CMakeLists.txt carries only stock ROS 2 syntax. Same file builds under both colcon build AND a nano-ros build:

cmake_minimum_required(VERSION 3.20)
project(my_node LANGUAGES CXX)

find_package(ament_cmake REQUIRED)
find_package(rclcpp REQUIRED)
find_package(std_msgs REQUIRED)
# … any other msg packages the source #include's.

add_executable(my_node src/my_node.cpp)
ament_target_dependencies(my_node rclcpp std_msgs)

ament_package()

find_package(rclcpp) resolves through nano-ros’s Findrclcpp.cmake, which defines rclcpp::rclcpp over the nros-cpp runtime — and with it the include path on which <rclcpp/rclcpp.hpp> and <rclcpp_components/register_node_macro.hpp> are nano-ros’s own headers; find_package(std_msgs) resolves through the message-package resolver (it walks NROS_INTERFACE_SEARCH_PATH > AMENT_PREFIX_PATH > bundled); nano-ros’s ament_target_dependencies wires both link targets.

These are find MODULES rather than <pkg>Config.cmake files on purpose: find_package() tries module mode first, so nano-ros’s rclcpp wins over an installed ROS 2 even when /opt/ros/<distro>/setup.bash has been sourced.

Workspace umbrella CMakeLists.txt — one nano-ros include

The umbrella CMakeLists.txt (sits at the workspace root, next to src/) is the only nano-ros-aware file:

cmake_minimum_required(VERSION 3.22)
project(my_workspace LANGUAGES CXX)
set(CMAKE_CXX_STANDARD 14)

# 1) Pull nano-ros in.
set(NROS_PLATFORM posix)
set(NROS_RMW "zenoh" CACHE STRING "Active RMW.")
set(NROS_RMW "${NROS_RMW}")
add_subdirectory("/path/to/nano-ros" nano_ros)

# 2) Point the message-package resolver at this workspace's src/ (must
#    precede the ament-surface include so workspace-pkg Find<pkg>.cmake
#    auto-emit picks it up).
set(NROS_INTERFACE_SEARCH_PATH "${CMAKE_SOURCE_DIR}/src")

# 3) nano-ros's ament / rclcpp surface.
include("/path/to/nano-ros/cmake/NanoRosAmentSurface.cmake")

# 4) Bulk-build every workspace msg pkg in topo order (one line instead of
#    N add_subdirectory(src/<pkg>) lines).
nros_workspace_interfaces()

# 5) Build consumer apps.
add_subdirectory(src/my_node)

No nros_generate_interfaces(<pkg>) calls per consumer — the smart Find-stub does the codegen at find_package(<pkg>) time.

Reference fixture

examples/templates/local-msg-package/ ships the pattern end-to-end: two workspace msg pkgs (local_msgs, extra_msgs) with intra-workspace dep + a C++ consumer pulling msgs from BOTH the workspace AND AMENT (std_msgs, geometry_msgs, sensor_msgs) via one find_package shape. Cross-build proof: the same src/ builds under colcon build (CI-gated).

Legacy nros_generate_interfaces(<pkg>) shape

(The full current-vs-legacy spelling table lives in Message Generation.)

Per-package nros_generate_interfaces(std_msgs LANGUAGE CPP SKIP_INSTALL) calls still work (back-compat preserved) but are deprecated for new code — they bypass the ROS-convention smart Find-stub + workspace discovery. Existing in-tree examples will migrate as part of Phase 210.E.3.

Running the ported node on a microcontroller

The same source runs on an RTOS, main included. Build glue for each platform sits beside the source, and the source itself does not change. examples/templates/cpp-port-minimal-publisher carries two such directories, mps2-an385-freertos/ and zephyr/, each with a CMakeLists.txt built around one line:

find_package(nano_ros REQUIRED)
nano_ros_add_executable(minimal_publisher ../src/minimal_publisher.cpp ROS2_MAIN)

The board comes from the directory’s system.toml, as for any nano-ros image. Every nano_ros_add_executable reaches your main: no C runtime calls int main(int argc, char** argv) on a board, so the build renames main in your sources only (never in the board’s own startup) and calls it from the platform’s entry, with argc == 0. ROS2_MAIN adds what a ported program needs on top of that:

• It gives the ported code the C++ standard library. A ported node uses std::string, std::to_string and <chrono> literals.
  • On FreeRTOS the toolchain compiles C++ -ffreestanding, which makes <string> an #error, so the flag is removed for this package’s directory. nano-ros’s own code stays freestanding.
  • On Zephyr, select the full library in prj.conf: CONFIG_REQUIRES_FULL_LIBCPP=y and CONFIG_GLIBCXX_LIBCPP=y.
• It asks for the std-shaped API (NROS_CPP_STD), the same one the ament verbs give a ported package on a host.

Where the node connects is decided when the image is built, because a board has no environment to read it from: the NROS_ENTRY_LOCATOR cache variable on FreeRTOS, the image’s locator in system.toml on Zephyr (rendered into CONFIG_NROS_ZENOH_LOCATOR). rclcpp::init(argc, argv) reads it in every source file that includes <rclcpp/rclcpp.hpp>.

A node with a hand-written spin loop also works. The other two templates, rclcpp-compat-smoke/ and topic-state-monitor-port/, have the same two directories, and their main is the common shape:

while (rclcpp::ok()) {
    node->tick();
    rclcpp::spin_some(node);
    std::this_thread::sleep_for(std::chrono::milliseconds(100));
}

On FreeRTOS the board provides what the C++ library needs for this: std::this_thread::sleep_for sleeps the calling task, and std::chrono::steady_clock counts from boot, because the board has no real-time clock. A package that uses another library, such as diagnostic_updater, names it the usual way, ament_target_dependencies(<name> diagnostic_updater). On Zephyr the dependency goes to app, where the sources are compiled.

Zephyr’s native_sim cannot run a ported node. There Zephyr links its own C library, and the host’s libstdc++ cannot run on top of it. Use a Cortex-M board such as mps2/an385 in QEMU, which is what the template targets.

A whole workspace on a board

A ported workspace keeps each package’s own CMakeLists.txt, unchanged. Only the root that configures the packages is new. examples/templates/ament-workspace-port has three roots over one stock package:

• FreeRTOS: find_package(nano_ros), then add_subdirectory for each package, with system.toml naming the board. Build with nros build.
• Zephyr: find_package(Zephyr) first, then the same two lines, plus a package.xml and the Kconfig fragments beside them. Build with nros build.
• posix: the same root you already use.

On a board, nano-ros reads the stock CMake verbs this way:

• add_executable builds an image, as nano_ros_add_executable(... ROS2_MAIN) does. The board’s entry calls your main, and the image gets its locator and domain from system.toml.
• add_library(... SHARED) builds STATIC, because an image is one binary.
• A package that finds rclcpp gets the C++ standard library. Its directory is compiled without -ffreestanding.
• ament_target_dependencies(<target> std_msgs) on a C++ target generates the message package if nothing has yet.
• A plain target_link_libraries(<exe> <lib>) keeps working beside nano-ros’s own links.
• A package that calls find_package(ament_cmake) is a ported package: its C++ is hosted even if it never finds rclcpp, and a message package it finds is generated in C++, so target_link_libraries(<lib> PUBLIC ${std_msgs_TARGETS}) reaches the headers.
• find_package(<sibling>) reaches a library package of the same workspace when the root sets NROS_INTERFACE_SEARCH_PATH and calls nros_workspace_interfaces() before adding the packages. Zephyr has the same call.
• -Wpedantic -Werror and -fPIC on a package’s directory are fine. On Zephyr the image’s kernel link is never position-independent, whatever the package adds.
• std::mutex and std::recursive_mutex exist although the RTOS toolchains’ libstdc++ has no threads: nano-ros defines them over the platform’s mutex for the ported package. std::condition_variable, std::thread and std::promise are still absent there.

What porting Nav2 packages to FreeRTOS and Zephyr needed edited in the source:

• Exceptions. An RTOS image is built -fno-exceptions, so a throw does not compile. Guard it with #if defined(__cpp_exceptions) and abort in the other arm. A try / catch around a call needs the same guard.

• Linux scheduling. Nav2’s setSoftRealTimePriority() calls sched_setscheduler. On an RTOS a thread’s priority is its tier’s (system.toml [tasks.*]), so make the call a no-op there.

• Per-request client callbacks. No std::promise, so no Client<S>::SharedFuture: read the future on a later tick (the client row in the table below).

• Parameters with no default. A board has no command line. State the launch file’s parameters in the image instead, and leave the source alone:

  [image.<id>]
  params_files = ["config/x.param.yaml"]
  ros_args = ["--ros-args", "-p", "update_rate:=10.0"]
  

  The build bakes both into the image, and rclcpp::init applies them ahead of whatever command line there is, so a host’s real arguments still win. A C (rclc) program does not read them.

What a workspace image still has to state:

• Pool sizes: let the census answer. Say that the image’s entities are what its program creates, and state no size:

  [[component]]
  pkg = "my_pkg"
  class = "my_pkg::MyNode"
  name = "my_node"        # the executable, when the workspace builds several
  entities = "census"
  

  The configure then builds the same sources for the host, runs the program once in census mode, and sizes the publisher, subscriber, queryable, liveliness and executor-callback pools from what it created. Nothing has to be built twice by hand, and a current census is reused. This works on the add_subdirectory and find_package roads, for a host image and a FreeRTOS one, and for a Zephyr application. On Zephyr the census also decides whether an in-image client reaches an in-image server (local_queryable) and, when it records a parameter, the parameter store and the nros heap’s default. A program that creates several nodes is counted node by node. The census run constructs the node, so it needs the node’s parameters: state them with params_files (above). One Zephyr pool stays yours to state, because Zephyr sizes it in Kconfig: zenoh-pico takes a POSIX condition variable per subscriber and queryable, and the configure refuses a CONFIG_MAX_PTHREAD_COND_COUNT below what the census needs, naming the number to set in your prj-zenoh.conf.

• Message bounds. An unbounded sequence or string in a message the node publishes gets the default bound, which can make one message megabytes. Bound it in nros-codegen.toml, for example [packages."diagnostic_msgs"] sequence = 4 and string = 64.

• Parameter capacities and the app stack. The default capacities fit: both ported Nav2 nodes boot on FreeRTOS’s default 64 KiB app stack, at peaks of 12.5 and 16.8 KiB. [knobs.params] (max_string_value_len, max_array_len, max_byte_array_len) still shrinks the parameter store’s RAM. If a node needs more stack, raise it with set(NROS_FREERTOS_APP_STACK_KB <KiB>) in the root. The boot line app task stack peak <used> of <total> says what it needed.

• The heap. On FreeRTOS, NROS_FREERTOS_HEAP_KB on freertos_config; on Zephyr, [image.<id>.knobs.zephyr] heap_size. A Zephyr heap that runs out while a subscription is created reports ConnectionFailed, not an out-of-memory.

• The Zephyr board. Name the board package, board = "mps2-an385-zephyr", not the generic zephyr (which lowers to native_sim). The package carries the board’s QEMU network, sizing and entropy Kconfig, so the leaf names only its own os_config fragments.

What “just works” without source edits

nano-ros covers the patterns a typical ROS 2 C++ node uses:

Measured: the stock rclcpp examples

packages/api/nros-cpp/tests/compile/rclcpp-examples/ holds 13 files from ros2/examples (humble and jazzy) verbatim, each beside its port. The repository’s C++ check compiles and links every port against nros-cpp, boots it on a stub middleware, and fails if the number of edited lines changes in either direction (edits.json). Today:

The remaining causes, largest first:

• Callback groups and the multi-threaded executor (18 lines).
• Exceptions (11 lines). There is nothing to catch.
• The action server’s thread per goal (6 lines). The stock handle_accepted detaches a std::thread that drives the goal handle; a goal handle used from a thread you started races the executor (nano-ros starts no threads behind it and a one-level image has no executor lock). The port calls execute(goal_handle) in the accepted callback and drops the rclcpp::Rate::sleep, which would re-enter the executor from that callback.
• A global Node::SharedPtr assigned from make_shared (2 lines each).
• seq.back() on a generated sequence (2 lines). FixedSequence / HeapSequence are not std::vector; write seq[seq.length() - 1].

Upstream’s goal-handle shapes are drop-ins, so the two action examples need 6 and 2 edited lines; the total is 43.

Actions: goal handles on a hosted build

The action types keep upstream’s names and concepts, and GoalResponse / CancelResponse / ResultCode keep upstream’s enumerators and values.

On a hosted build (-DNROS_CPP_STD, what the porting flow sets) the stock spellings are drop-ins:

• rclcpp_action::create_server<A>(node->get_node_base_interface(), …clock, …logging, …waitables, name, handle_goal, handle_cancel, handle_accepted) and rclcpp_action::create_client<A>(…base, …graph, …logging, …waitables, name), or the (node, name, …) shape. Each returns X<A>::SharedPtr, which is rclcpp::Owned<X<A>>: the entity by value, so a member Server<A>::SharedPtr action_server_; works and nothing is shared. The get_node_*_interface() getters return a handle naming the node, whose only use is these two calls.
• The callbacks take upstream’s shapes, std::bind-ed members included: handle_goal(const GoalUUID&, std::shared_ptr<const Goal>), handle_cancel(std::shared_ptr<ServerGoalHandle<A>>), handle_accepted(std::shared_ptr<ServerGoalHandle<A>>).
• ServerGoalHandle<A> answers get_goal_id, get_goal, is_active, is_executing, is_canceling, and publish_feedback / succeed / abort / canceled take upstream’s std::shared_ptrs. Each call forwards to the server, keyed by the goal id; the goal itself lives in the server’s static arena, and the handle is a token over it. execute() moves a goal accepted with ACCEPT_AND_DEFER to EXECUTING and publishes the status; for ACCEPT_AND_EXECUTE the server does that itself before handle_accepted, as upstream’s does.
• Client<A>::SendGoalOptions carries upstream’s goal_response_callback (a ClientGoalHandle<A>::SharedPtr, null when rejected), feedback_callback (std::shared_ptr<const Feedback>) and result_callback (WrappedResult{goal_id, code, result}), and async_send_goal(goal, options) binds them to that goal. Giving a result callback requests the result once the goal is accepted, as upstream does.
• async_get_result(goal_handle, result_callback) and async_cancel_goal(goal_handle, cancel_callback), plus async_cancel_all_goals / async_cancel_goals_before(stamp), return upstream’s std::shared_future (of a WrappedResult, or a CancelResponse::SharedPtr with return_code and goals_canceling), so rclcpp::spin_until_future_complete(node, f) then f.get() work unchanged. The future drives the client while it is polled or waited on.

What stays different, each a compile error or written below:

• async_send_goal returns rclcpp::Future<GoalAccept>, the goal-keyed future send_goal_future returns, not a std::shared_future of a goal handle. auto f = client->async_send_goal(goal, opts); compiles; a caller that waits on f gets the acceptance (the future never blocks without spinning).
• A cancel reply is taken by the executor’s spin, as upstream’s is: the spin settles the async_cancel_* future and runs its cancel_callback, so code that keeps only the callback ports as written. A nano-ros server acts on the zero-id cancel-all / cancel-before forms as an rclcpp server does.
• A goal handle is driven from the executor’s task. Do not hand it to a thread you start (see the 6 lines above). It names its server by address, so the server must not move while a handle is in use; a SharedPtr does not move it.
• No get_goal_stamp: the arena keeps no acceptance time.
• It is not a Waitable (no execute / is_ready / set_on_ready_callback): the executor drives the server directly.
• wait_for_action_server returns Result and the budget is required (see the table above).

On a freestanding build there is no allocator for a goal handle, so ClientGoalHandle::SharedPtr, ServerGoalHandle::SharedPtr, rclcpp_action::create_server, async_send_goal and an assignment to SendGoalOptions’ upstream fields are each a compile error naming the goal-id-keyed form:

• Server. Declare the Server<A>, initialise it with node.create_action_server(srv, name), and install set_goal_callback_with_ctx / set_cancel_callback_with_ctx / set_accepted_callback_with_ctx (function pointers with a void* context). The callbacks receive the 16-byte goal id; feedback and termination are calls on the server keyed by it — srv.publish_feedback(id, fb), srv.succeed(id, result), abort, canceled — taking the message by const reference.
• Client. client.set_callbacks(SendGoalOptions{goal_response, feedback, result, context}) installs raw callbacks once for every goal the client sends; send_goal_async(goal, goal_id) sends. send_goal_future / get_result_future are the future-shaped spellings, each keyed by its goal. rclcpp_action::create_client works here too (no allocator involved).

Two things the compiler will not tell you

Everything else on this page either works or fails to compile. These two compile and behave slightly differently, so they are written down rather than left for a debugging session.

Node::ok() — nano-ros cannot throw, so YOU have to ask

Upstream’s rclcpp::Node constructor THROWS when the node cannot be created. nano-ros is built -fno-exceptions, so the constructor cannot: it records the failure and the node answers false to ok().

rclcpp::Node node("talker");
if (!node.ok()) return 1;        // <- this line replaces upstream's try/catch

A generated entry already does this and halts naming the node, so a workspace component needs nothing. A hand-written main does not, and a node that failed to create will otherwise go on to create publishers that quietly do nothing. There is no diagnostic for it — the object exists either way, which is the whole point of not throwing — so checking ok() after constructing a node by hand is on you.

The same shape applies to init(), the two-phase form:

rclcpp::Node node;
if (!node.init("talker").ok()) return 1;

Result carries [[nodiscard]] on C++17 and later, so that one the compiler does warn about.

Node::SharedPtr observes, it does not own

rclcpp::Node::SharedPtr is rclcpp::Handle<rclcpp::Node> on every target, embedded included: a copyable reference that does not keep the node alive. A node is constructed by your main (or the generated entry) and outlives everything it is handed to, so storing and copying it works as upstream’s does. Two consequences:

• shared_from_this() returns that handle. It is safe to pass to anything that holds it for less than the node’s lifetime (diagnostic_updater::Updater(shared_from_this(), 1.0) is the common case), and NOT safe to store somewhere that outlives the node. It never throws where upstream would raise bad_weak_ptr. nano-ros cannot derive from std::enable_shared_from_this<Node>: its std::weak_ptr member exists only where <memory> does, so two translation units of one firmware image could disagree about the object’s layout.
• rclcpp::Node::SharedPtr node = std::make_shared<MyNode>(); is a compile error. The shared_ptr there is a temporary, and a handle to it would dangle at the end of the line; the compiler names the deleted conversion. Write auto node = std::make_shared<MyNode>(); instead. A shared_ptr you keep converts to Node::SharedPtr freely, and rclcpp::spin(…) accepts the temporary directly.

rclcpp::TimerBase is a NAME here, not a hierarchy

rclcpp::TimerBase::SharedPtr timer_; compiles unchanged, and you should keep writing it — it is the only spelling that works against real ROS 2 as well as against nano-ros, since upstream has no rclcpp::Timer.

What differs is behind the name. nano-ros has no timer hierarchy: TimerBase is an ALIAS for the one flat rclcpp::Timer, so is_same<TimerBase, Timer>::value is true and neither spelling carries a vtable. The executor dispatches through a raw function pointer, so a polymorphic base would be cost with no caller.

Consequences worth knowing:

• Timer::SharedPtr is a small handle, not a std::shared_ptr. Its callback lives in the executor, so the handle does not own the timer. Dropping or overwriting timer_ leaves the timer firing; destroying the node stops it. timer_.reset() releases the timer for good. timer_->reset() restarts it, as upstream. A member declared as std::shared_ptr<rclcpp::TimerBase> does not compile: spell it rclcpp::TimerBase::SharedPtr.
• The same holds for Subscription<M>::SharedPtr, Service<S>::SharedPtr and Client<S>::SharedPtr: dropping the handle leaves the entity running, and sub_.reset() / srv_.reset() / cli_.reset() releases it for every copy at once. A one-shot timer or subscription that resets ITSELF from its own callback works: the release takes effect when the callback returns.
• rclcpp::WallTimer<...> and rclcpp::GenericTimer<...> do not exist. The clock axis is the second verb rclcpp::create_timer(node, clock, period, cb) plus a runtime field, not a type parameter.
• DERIVING from rclcpp::TimerBase gets you a concrete handle with a non-virtual destructor. Upstream code almost never does this; if yours does, it needs rework. There is no timer hierarchy here: the executor dispatches through a raw function pointer, so a polymorphic base would be a vtable nothing calls, and TimerBase is a name that promises WallTimer and GenericTimer siblings we deliberately do not have. The clock axis is a runtime field plus the second verb rclcpp::create_timer, not a type parameter.

A real package: Autoware’s autoware_external_cmd_selector

This node was ported (Autoware 0.45.0; 12 subscriptions, 7 publishers, a service, two parameters, diagnostic_updater, a component registered with rclcpp_components_register_node(... EXECUTABLE ...)) through a workspace umbrella like the one above. Its package needed no source edit and no CMakeLists edit, and it runs against a stock ROS 2 Humble rmw_zenoh_cpp peer: topics, the service, ros2 param, /diagnostics. Three things it needed from the person porting it:

1. Source the project’s install before configuring. Its CMakeLists calls find_package(autoware_cmake) and its message packages come from Autoware’s own install; both reach a machine through source <autoware>/install/setup.bash. nano-ros reads what that puts on AMENT_PREFIX_PATH and CMAKE_PREFIX_PATH: autoware_cmake’s own macros run over nano-ros’s ament verbs, and each message package is generated by nano-ros codegen, never taken from the installed upstream C++.

2. Raise the pool sizes. A package built this way declares no entity counts, so every pool sits at its embedded default, and start-up stops at the first one that fills, naming its knob. Unless the census derives them from the program (see “Pool sizes” above), set them in the environment of the configure and build:

   export NROS_EXECUTOR_MAX_CBS=40 NROS_ZENOH_MAX_LIVELINESS=128 \
          NROS_ZENOH_MAX_PUBLISHERS=32 NROS_ZENOH_MAX_SUBSCRIBERS=32 \
          NROS_ZENOH_MAX_QUERYABLES=32
   

   Those are what this node needed with headroom; a smaller node needs less.

3. Name the router. NROS_LOCATOR=tcp/<host>:7447 at run time, the same router the ROS 2 side’s rmw_zenoh_cpp uses.

What’s documented as “needs adapt” (codegen-side, not surface-side)

These are cosmetic codegen differences nano-ros’s per-package codegen and the upstream rosidl_default_runtime codegen don’t share; both are tracked as ROS-convention codegen work.

• Message string fields. nano-ros codegen emits rclcpp::FixedString<N>, upstream emits std::string. Assigning a std::string needs a one-token adapter: message.data = s.c_str(). The reverse (std::string{}.c_str()) is what RCLCPP_INFO already takes.
• Generated message header path. CLOSED (alias headers): nano-ros codegen emits BOTH the per-message form <std_msgs/msg/string.hpp> (upstream-shape) AND the umbrella <std_msgs/std_msgs.hpp>. Use whichever the original source picks.

What’s out of scope (will need code adapt or a follow-up phase)

• Persisting parameters. A --params-file <yaml> on the command line is read (scalars), as is -p, and declare_parameter<T>(name) with no default takes its value from there (the Autoware port below declares both of its parameters that way). Parameters then live in a volatile store the standard parameter services can update until the next boot; nothing writes them back.

• A message with an unbounded string or sequence (std_msgs/String’s data) — a subscription to it stops the compile at NROS_UNBOUNDED__<pkg>_msg_<type>__field_<field>. The receive buffer is sized from a bound, and an unbounded field has none. Give it one in a nros-codegen.toml at the workspace root or beside the package’s CMakeLists.txt:

  [fields]
  "std_msgs/String.data" = 256
  

  The wire format does not change. The other levels ([defaults], [packages.*], [types.*]) and the storage modes are in the message field capacity design.

• create_generic_publisher(topic, type, qos) / create_generic_subscription(topic, type, qos, callback) by type name — a compile error naming the alternative. rclcpp loads the type’s typesupport at run time; nano-ros links its types at build time, and the wire key needs the type’s RIHS01 hash, which nothing derives from a name. Pass the hash: create_generic_publisher(topic, type, type_hash, qos) returns a GenericPublisher with publish_serialized(data, len), and create_generic_subscription(topic, type, type_hash, qos, callback) calls callback(const uint8_t* data, size_t len) with each message’s CDR bytes. A generated type states both as M::TYPE_NAME and M::TYPE_HASH.

• class_loader, dlopen composition, a component that is not an rclcpp::Node (get_node_base_interface()) — nano-ros has no runtime loader and no node interfaces. Build the components into one image with a hand-written main, as ros2/demos manual_composition does.

• tf2, image_transport, pluginlib — out of nano-ros scope. Project- specific helpers (autoware universe_utils, PX4 uORB shims) are not nano-ros’s to ship; the porting user vendors them or replaces the call sites with raw nros-cpp ones.

When the port hits a gap

Known open follow-ups: pool sizing on the ament road, the per-request client callback, listing parameter overrides, and the in-tree migration of legacy nros_generate_interfaces(<pkg>) call sites. If your port surfaces a new gap, file an issue with a reduced case — a fix lands either tree-side (in packages/api/nros-cpp/, cmake/NanoRosAmentSurface.cmake or cmake/find/) or as a codegen change, each with its own in-tree test.

In-tree regression fixtures:

• local-msg-package — mixed workspace (workspace + AMENT msg sources) C++ + Rust consumers.
• cpp-port-minimal-publisher — ROS 2 tutorial minimal_publisher.cpp verbatim.
• rclcpp-compat-smoke — minimal source-compat regression test.
• topic-state-monitor-port — multi-sub / wall-timer / diagnostic_updater exercise.

Your ported code stays yours: nano-ros does not take a copy of it as a fixture. What lands is the fix, tested by code written for the test: the Autoware port above left behind tests/cmake-ament-surface-tests.sh and packages/api/nros-cpp/tests/compile/ament_port_surface_runtime.cpp, neither of which contains a line of Autoware’s.