Introduction

nano-ros is a lightweight ROS 2 client library for embedded real-time systems. It runs on bare-metal microcontrollers, FreeRTOS, NuttX, ThreadX, and Zephyr, as well as Linux and *BSD. The entire core stack is no_std compatible.

flowchart TB
    App["<b>Application</b><br/>Rust / C / C++ node code"]
    Core["<b>nano-ros core</b><br/>Executor · Node · pub/sub · services · actions · CDR"]
    RMW["<b>RMW backend</b><br/>Zenoh · XRCE-DDS · Cyclone DDS · custom"]
    Plat["<b>Platform</b><br/>clock · heap · threads · sleep · sockets · libc"]
    Wire(["ROS 2 / DDS / Zenoh wire"])
    App --> Core --> RMW --> Plat
    RMW -. wire-compatible .-> Wire

Four layers, swappable independently: the same node code runs over any RMW backend on any platform. Here is a complete Linux publisher — register a backend, open the executor, publish std_msgs/Int32 on /chatter once a second:

use nros::prelude::*;
use std_msgs::msg::Int32;

fn main() {
    // Pick the backend at compile time; this one line registers it.
    nros_rmw_zenoh::register().unwrap();

    let config = ExecutorConfig::new("tcp/127.0.0.1:7447").node_name("talker");
    let mut executor: Executor = Executor::open(&config).unwrap();

    let mut node = executor.create_node("talker").unwrap();
    let publisher = node.create_publisher::<Int32>("/chatter").unwrap();

    let mut count = 0i32;
    executor
        .register_timer(nros::TimerDuration::from_millis(1000), move || {
            publisher.publish(&Int32 { data: count }).unwrap();
            count += 1;
        })
        .unwrap();

    executor.spin_blocking(SpinOptions::default()).unwrap();
}

The same program in C and C++ is in the First Node guides: Rust · C · C++. When a project grows beyond one node, continue with Multi-Node Project Layout.

Key Features

• Minimal stack — three software layers (application, nano-ros, transport). Lean dependency tree, fast compile times.
• Pluggable middleware — choose Zenoh (agent-less, direct peer communication), XRCE-DDS (agent-based), or Cyclone DDS (RTPS wire-compatible with stock ROS 2) at compile time. Same application code regardless of backend.
• Rust-first with C API — the core is written in Rust for memory safety and ergonomics, with a thin C FFI (Foreign Function Interface) layer following rclc conventions.
• True no_std — runs on bare-metal Cortex-M3 with no heap allocator. The alloc and std features are opt-in.
• Standalone tooling — nros generate-rust produces message bindings without a ROS 2 installation (bundled interface definitions).
• Formally verified — 160 Kani bounded model checking harnesses and 102 Verus deductive proofs cover CDR serialization, scheduling, and protocol correctness.
• ROS 2 compatible — interoperates with standard ROS 2 nodes via rmw_zenoh_cpp, or directly over RTPS with rmw_cyclonedds_cpp (same wire protocol, no key rewriting). Topics, services, and actions work across the boundary.

Quick board check — does it work on the board I have today?

Legend: Verified = booted + tested in CI. Ready = builds and runs but no in-CI gate yet — drop into the matching examples/<plat>/ to compile and try.

Footnotes — ¹ MPS2-AN385 bare-metal is Rust-only (nros-c / nros-cpp need an RTOS for libc / heap). ² STM32F4 Rust path is the canonical target for the bare-metal board crate; FreeRTOS variant uses the shared nros-board-freertos glue. ³ ESP32-S3 needs the xtensa-esp32s3-none-elf Rust target via the espup toolchain installer (not rustup — Xtensa targets aren’t in upstream rust). ⁴ PX4 path is via the external-module template in integrations/px4/ — C++ only because PX4’s uORB binding is C++-only.

Supported platforms (by RTOS)

RMW Backends

nano-ros supports several middleware backends, selected at compile time by adding the backend crate as a dependency:

• Zenoh (nros-rmw-zenoh) — peer-to-peer via zenoh-pico. No agent process. Compatible with ROS 2 rmw_zenoh_cpp.
• XRCE-DDS (nros-rmw-xrce-cffi) — agent-based via Micro-XRCE-DDS. Compatible with micro-ROS agent.
• Cyclone DDS (nros-rmw-cyclonedds) — C++ shim; full RTPS wire-compat with stock rmw_cyclonedds_cpp.

Application code is identical regardless of backend — switch with a single Cargo feature flag or Zephyr Kconfig option.

Project Status

nano-ros is under active development. Core capabilities are functional and exercised in CI; see the platform chapters for per-target detail.

How This Book Is Organized

• Getting Started — install toolchains, build your first app, connect to ROS 2.
• Concepts — understand the architecture, feature system, and backend model.
• Guides — step-by-step walkthroughs for message generation, QEMU testing, and ESP32 development.
• Platforms — per-RTOS setup and configuration.
• Reference — API details, environment variables, build commands, and wire protocol.
• Advanced — formal verification, real-time analysis, safety features, and contributing.

Choose Your Entry

Different readers want different paths through this book. Pick the shoe that fits and jump straight to the right page.

🧪 I’m taking a glance

You heard about nano-ros and want to know in 5 minutes whether it’s worth playing with.

• Start at the “Can I use nano-ros right now?” matrix in the intro. One row per dev board you might have on your desk.
• Then the Project Status paragraph for the maturity signal.
• If you stay interested, jump to one of the starters below.

🔌 I have an ESP32 on my desk right now

Already have hardware? Two-step path:

1. Linux first — First Node — Rust on your host to verify the stack in ~10 minutes (nros setup native --rmw zenoh then cargo run).
2. Then ESP32 — once Linux works, follow ESP32 (esp-hal) for the Rust cross-compile path. You need a second machine (or the host itself) running zenohd on your Wi-Fi network — the board needs network reach to the router. For a C-only path use ESP32 (ESP-IDF component) if you already have ESP-IDF set up.

🚀 I want to get started shipping something

You’ve decided to use nano-ros and want a working talker on Linux first, then maybe move to an MCU.

1. Install + first build — install the nros CLI, then nros setup native --rmw zenoh.
2. First Node in your language: Rust · C · C++.
3. Building two or more nodes? Move next to Multi-Node Project Layout.
4. Troubleshooting — First 10 Minutes if anything goes sideways.
5. Cross-compile for an RTOS via the Embedded Starters section.

🔬 I’m evaluating capabilities

You’re a senior engineer or tech lead assessing nano-ros for adoption. You want to see scope of coverage, performance bounds, verification status, and trade-offs before committing.

• Architecture Overview — the three-layer model.
• Execution Model and Two-Layer API — poll vs callback discipline.
• Choosing an RMW Backend — capability matrix per backend, including QoS coverage and multi-backend bridges.
• Real-Time Analysis + Scheduling Models — RT scheduling story.
• Formal Verification — Kani
  • Verus harness coverage.
• Safety Protocol — E2E CRC, EN 50159 mapping.
• Production Readiness Checklist — concrete adoption gates.
• nano-ros vs micro-ROS — head-to-head with the closest peer project.

💼 I’m scoping nano-ros for a fleet / product line

You’re a PM, CTO, or technical buyer. You want license terms, supplier reach, deployment patterns, and risk signals before you write the memo.

• Setup Compared to Standard ROS 2 — the elevator pitch + what stays familiar vs what changes.
• Differences from Standard ROS 2 — feature deltas in plain prose.
• Supported Boards — the procurement matrix (vendor × board × MCU × RTOS × status).
• Choosing an RMW Backend — decision tree.
• Cross-backend Bridges — multi-RMW fleets.
• Safety Protocol — E2E CRC framework + standards mapping.
• Production Readiness Checklist — what you’d ask your pilot team to validate.
• nano-ros vs micro-ROS — license / governance / commercial support comparison.

Still not sure?

Read the Introduction for the one-page overview. Every section above branches from there.

Setup Compared to Standard ROS 2

This page is for ROS 2 users who already know the normal desktop flow: install a ROS distro, create a workspace, run rosdep, build with colcon, and select an RMW at runtime with RMW_IMPLEMENTATION.

nano-ros keeps the workspace and package vocabulary, but changes the setup boundary because it targets embedded and RTOS builds.

Standard ROS 2 Flow

A typical ROS 2 application starts from a distro install:

source /opt/ros/humble/setup.bash
mkdir -p ~/ros2_ws/src
cd ~/ros2_ws
rosdep install --from-paths src --ignore-src -y
colcon build
source install/setup.bash

The middleware implementation is selected at process startup:

export RMW_IMPLEMENTATION=rmw_cyclonedds_cpp
ros2 run my_pkg my_node

That model assumes shared libraries, a hosted OS, and runtime plugin loading.

nano-ros Flow

Where standard ROS 2 installs a distro and resolves system packages with rosdep, nano-ros provisions a per-board toolchain with one command. nros setup replaces the distro install + rosdep: it ships prebuilt toolchains per platform per RMW — the cross-compiler, emulator, RMW host daemon, and SDK sources for a board are fetched from a pinned index into a shared store (${NROS_HOME:-~/.nros}/sdk). You do not install cross-toolchains by hand, and you do not need a ROS distro on the machine.

# 1. Build the in-tree nros CLI (analogous to installing a ROS distro, Phase 218):
source ./activate.sh        # OR: direnv allow / source ./activate.fish
just setup-cli              # builds packages/cli/target/release/nros

# 2. Provision a board + RMW (analogous to `rosdep install`):
nros setup native --rmw zenoh

# 3. Build + run an example (the nano-ros source is vendored in your project):
cd examples/native/rust/talker
cargo run

For embedded targets, name the board instead of native; nros setup fetches the matching prebuilt cross-toolchain + emulator + SDK:

nros setup qemu-arm-freertos --rmw zenoh     # arm-none-eabi-gcc, qemu, FreeRTOS+lwIP
nros setup zephyr            --rmw zenoh     # Zephyr west workspace + SDK bits
nros setup qemu-arm-nuttx    --rmw zenoh     # arm-none-eabi-gcc, qemu, NuttX

Useful flags: nros setup --list (every package + version), nros setup <board> --dry-run (resolve + print the plan, fetch nothing), nros setup --licenses (license-gated packages). See Supported Boards for the board list and nros CLI for every subcommand.

Contributors working on nano-ros itself drive the same index through just — just <module> setup calls nros setup <board> under the hood, so the provisioned toolchains are identical.

Choosing platform + RMW

Unlike standard ROS 2, RMW and platform are compile-time choices — there is no runtime RMW_IMPLEMENTATION switch on embedded targets (no dlopen). The pair is selected via CMake cache vars + Cargo features:

# Each example is a standalone CMake project that pulls nano-ros in
# via add_subdirectory.
set(NANO_ROS_PLATFORM freertos)
set(NANO_ROS_RMW      zenoh)
set(NANO_ROS_BOARD    mps2-an385-freertos)
add_subdirectory(<repo-root>  nano_ros)

target_link_libraries(my_app PRIVATE NanoRos::NanoRos)
nros_platform_link_app(my_app)
nano_ros_link_rmw(my_app RMW zenoh)

Multi-RMW bridges (one binary, two or more backends) use Executor::open_with_rmw("<name>", ...) + node_builder.rmw("<name>") — see Cross-backend Bridges.

What Stays Familiar

• Workspace layout: one source checkout next to your packages.
• Package metadata: downstream packages still use package.xml.
• ROS vocabulary: nodes, publishers, subscriptions, services, actions, QoS profiles, parameters, and message packages keep ROS-shaped names.
• colcon build still works as a consumer-side build for POSIX workspaces that already use it; embedded targets use cmake, cargo, west, or idf.py directly.
• Interop: POSIX nano-ros nodes can communicate with standard ROS 2 nodes through compatible RMW backends (Zenoh, Cyclone DDS, XRCE).

What Changes

• Source-only. No binary SDK tarball, no crates.io umbrella crate, no Arduino zip / ESP-IDF binary component / GitHub Releases artifact. The locked policy is git clone --branch=v<X.Y.Z> + in-tree build.
• Per-board provisioning, no rosdep. nros setup <board> --rmw <rmw> is the single setup command. It fetches prebuilt toolchains (cross-gcc, emulator), the RMW host daemon, and SDK sources for exactly that board+RMW into ~/.nros/sdk — no system-wide package install, no ROS distro. (The just <module> setup recipes call the same command for contributors.)
• Compile-time RMW + platform. Embedded targets can’t dlopen, so the RMW and platform combination is locked in by CMake cache vars (NANO_ROS_PLATFORM, NANO_ROS_RMW) and Cargo features at build time.
• No install prefix. removed just install-local and every install(...) rule; consumers pull nano-ros into their build via add_subdirectory(<repo-root>). The integration shells under integrations/<rtos>/ re-export the same root CMake under each RTOS’s native package manager.
• Generated bindings in-tree. Message codegen lands under <your-package>/generated/ (or OUT_DIR for Cargo builds), not in an installed ROS message library.
• Configuration is build-time on embedded. Runtime env vars (ROS_DOMAIN_ID, NROS_LOCATOR — legacy alias ZENOH_LOCATOR, …) work on POSIX; embedded targets resolve config via CMake cache, Kconfig (Zephyr), Cargo features, or a sidecar nros.toml ([node] + [[transport]]).

Next Step

Continue with Installation, then run the ROS 2 Interoperability example before moving to a platform-specific guide.

Installation

nano-ros is distributed as source, vendored into the consumer’s project tree (git submodule, west manifest, ESP-IDF component, etc.) and built in-tree via add_subdirectory(nano-ros). There is no binary tarball, no system-wide install step, no find_package(NanoRos).

activate.sh is the after-install step, NOT a prereq. Sourcing activate.sh (or activate.fish, or direnv allow) only wires the workspace env into a new shell — it presumes the nros binary already exists at packages/cli/target/release/nros. The three bootstrap paths below (A/B/C) are what produce that binary; the activate file is what makes it findable in every subsequent shell.

See build-as-subdirectory.md for the canonical user incantation (4-line CMakeLists.txt). This page walks the surrounding workspace + per-target setup choices.

Pattern A: nano-ros lives inside your ROS 2 workspace

The recommended layout is to clone nano-ros into your workspace’s src/ directory alongside your packages:

~/ros2_ws/
├── src/
│   ├── nano-ros/             # <-- this repo
│   ├── pkg_a/                # your package(s)
│   ├── pkg_b/
│   └── …
└── (build/, install/, log/ — generated by colcon)

colcon build discovers nano-ros + each user package via package.xml, builds them in dependency order, and shares one nano-ros build across every consuming package. Users never run cmake manually — the per-user package’s CMakeLists.txt does add_subdirectory(../nano-ros nano_ros) under the hood.

A complete working example lives at examples/templates/multi-package-workspace/.

Pattern B: nano-ros as a third-party subdirectory

For C/C++ projects that don’t use colcon at all:

~/my_project/
├── CMakeLists.txt
├── src/main.c
└── third_party/
    └── nano-ros/             # git submodule

The top-level CMakeLists.txt:

cmake_minimum_required(VERSION 3.22)
project(my_app LANGUAGES C)

# `NROS_RMW` is the user-facing cache var (overridable via
# `-DNROS_RMW=<rmw>`); forward it to `NANO_ROS_RMW`, the var the
# nano-ros add_subdirectory reads. Matches the canonical example
# shape in examples/native/c/talker/CMakeLists.txt.
set(NANO_ROS_PLATFORM posix)
set(NROS_RMW "zenoh" CACHE STRING
    "Active RMW (zenoh|xrce|cyclonedds) — selects the backend linked into my_app.")
set(NANO_ROS_RMW "${NROS_RMW}")
add_subdirectory(third_party/nano-ros nano_ros)

add_executable(my_app src/main.c)
target_link_libraries(my_app PRIVATE NanoRos::NanoRos)
nros_platform_link_app(my_app)

nros_platform_link_app transitively wires the selected RMW backend on POSIX — no explicit nano_ros_link_rmw() call is needed. That is the entire consumption shape. See build-as-subdirectory.md for the full walkthrough.

Provision your toolchain with nros setup

nros setup is the single command that prepares a machine to build nano-ros for a given board. It ships prebuilt toolchains per platform per RMW — the cross-compiler, emulator, RMW host daemon, and any SDK sources a board needs are fetched from a pinned index and placed in a shared store (~/.nros/sdk). You do not install cross-toolchains by hand, and you do not need ROS 2 on the machine.

1. Get the nros CLI onto PATH

Pick one path from a fresh checkout — just is NOT a prereq.

A. Bare machine (no Rust, no just, no cargo):

git clone https://github.com/NEWSLabNTU/nano-ros.git
cd nano-ros
./scripts/bootstrap.sh base

Installs rustup, just, builds the in-tree nros CLI at packages/cli/target/release/nros, leaves the binary on PATH for this shell.

B. Already have cargo (most contributors):

cargo build --release --manifest-path packages/cli/Cargo.toml --bin nros
export PATH="$PWD/packages/cli/target/release:$PATH"

C. Tagged release, no Rust at all:

./scripts/install-nros-prebuilt.sh

Downloads the matching nros-<triple>.tar.gz from the GitHub release, sha256-verifies, installs to packages/cli/target/release/nros.

All three paths produce the per-checkout binary at packages/cli/target/release/nros. One checkout = one CLI version = one runtime ABI — no global install, no ~/.nros/bin PATH skew across worktrees.

2. Activate the workspace (every subsequent shell)

The bootstrap path you ran in §1 left nros on PATH for that shell only. Every new shell needs the workspace env wired in. Pick whichever fits your shell — all three wire the same env exports + PATH entries from the Phase 218.C SSoT activate.sh:

direnv allow                  # auto-activates on `cd nano-ros` (recommended)
source ./activate.sh          # bash / zsh, one-shot per shell
source ./activate.fish        # fish, one-shot per shell

The activate file also sources /opt/ros/humble/setup.bash if present (required by nros generate-rust + cyclonedds codegen + rmw_zenoh interop tests) and exports NROS_REPO_DIR.

3. Provision a board (+ RMW)

nros setup <board> --rmw <zenoh|xrce|cyclonedds>

nros setup resolves the board’s package set union the RMW’s host packages and fetches them all — prebuilt cross-toolchain + emulator + RMW daemon + board SDK sources. --rmw defaults to zenoh.

Useful flags:

nros setup --list            # every package in the index + its version
nros setup <board> --dry-run # resolve + print the plan, fetch nothing
nros setup --licenses        # license-gated packages + how to install them
nros setup --tool qemu       # one tool by name
nros setup --source freertos-kernel   # one source package by name

Each board’s exact package set lives in the index; run nros setup <board> --dry-run to see precisely what a board pulls. See Supported Boards for the full board list and nros CLI for every subcommand.

Heads-up before your first example. Every nano-ros example (Linux talker, FreeRTOS talker, …) connects to its RMW host daemon at startup — zenohd for zenoh, the Micro-XRCE-DDS agent for xrce. Cyclone DDS is in-process — no separate daemon — so the heads-up below doesn’t apply if you ran nros setup … --rmw cyclonedds. nros setup … --rmw <rmw> installs the daemon into the nros store (~/.nros/sdk/<tool>/<version>/bin/; the cache root is ~/.nros/sdk/ — toolchains, transports, and daemons all land under there); you must then run it in a dedicated terminal before launching any example. For zenoh, put the store binary on PATH once and run it:

export PATH="$(dirname "$(ls -d ~/.nros/sdk/zenohd/*/bin/zenohd | tail -1)")":$PATH
zenohd        # leave running for the whole session

Without it the talker blocks forever on Executor::open with no output. Default ports: tcp/127.0.0.1:7447 on POSIX, tcp/10.0.2.2:7451 on QEMU FreeRTOS (Slirp forwards to host). Mismatch = silent hang; see Troubleshooting — First 10 Minutes.

After provisioning, follow the per-platform starter page (FreeRTOS, Zephyr, NuttX, …) for the board’s build + run steps.

Rust-only consumers

nano-ros is source-only — nothing is published to crates.io (decision 2026-05-14). The full nros crate can’t be published because it depends transitively on C/C++ submodules (zenoh-pico, mbedtls); nros-core isn’t carved out for crates.io either, to avoid a hybrid distribution model with version drift between the crates.io snapshot and in-repo HEAD.

Rust packages consume nano-ros via path dependency on the in-workspace checkout:

[dependencies]
nros = { path = "src/nano-ros/packages/core/nros",
         default-features = false,
         features = ["std", "rmw-cffi", "platform-posix", "ros-humble"] }

Each Rust package carries its own .cargo/config.toml patch entries when needed — see examples/templates/multi-package-workspace/src/pkg_rust_publisher/ for the pattern.

Contributor setup (working on nano-ros itself)

Contributors clone the repo and drive everything through just. The just setup recipes are thin wrappers over the same nros setup index — just <module> setup calls nros setup <board> under the hood, so the toolchains a contributor gets are identical to a user’s.

git clone https://github.com/NEWSLabNTU/nano-ros.git
cd nano-ros
./scripts/bootstrap.sh base   # path A from §1 above; gets rustup + just + nros
source ./activate.sh          # OR: direnv allow / source ./activate.fish
just setup all                # provision every supported board's SDK/toolchain

Diagnose missing tools (read-only):

just doctor tier=all

Provision one module:

just freertos setup           # → nros setup qemu-arm-freertos
just nuttx setup              # → nros setup qemu-arm-nuttx
just threadx_linux setup      # → nros setup threadx-linux

Docker environment

For a containerized environment with QEMU 7.2+:

just docker build
just docker shell      # Interactive shell with all tools
just docker test-qemu  # Run QEMU tests in container

Migrating from a pre-140 checkout

If you were on a nano-ros version that still had just install-local, see migration-install-local-removal.md for the one-page rewrite.

Next Steps

• First Node — Rust — build + run a Rust talker on Linux
• First Node — C — build + run a C talker on Linux
• First Node — C++ — build + run a C++ talker on Linux
• Build as Subdirectory — CMake consumption walkthrough
• C API — API entry points and CMake integration
• examples/templates/multi-package-workspace/ — full mixed C / C++ / Rust example

First Node — Rust (Linux)

Build, run, and verify a single nano-ros publisher node on Linux in about ten minutes. Uses the canonical Zenoh backend; no router needs to be pre-installed (the repo ships zenohd).

Stuck? See Troubleshooting — First 10 Minutes for the common first-build errors.

Prereqs

Pick one path from a fresh checkout — just is NOT a prereq.

A. Bare machine (no Rust, no just, no cargo):

./scripts/bootstrap.sh base

Installs rustup, just, builds the in-tree nros CLI at packages/cli/target/release/nros, leaves the binary on PATH for this shell.

B. Already have cargo (most contributors):

cargo build --release --manifest-path packages/cli/Cargo.toml --bin nros
export PATH="$PWD/packages/cli/target/release:$PATH"

C. Tagged release, no Rust at all:

./scripts/install-nros-prebuilt.sh

Downloads the matching nros-<triple>.tar.gz from the GitHub release, sha256-verifies, installs to packages/cli/target/release/nros.

Every subsequent shell sources the workspace env via one of:

direnv allow                  # if you use direnv
source ./activate.sh          # bash / zsh
source ./activate.fish        # fish

Then provision the native host (installs the zenoh router zenohd into a shared store — no ROS 2 needed):

nros setup native --rmw zenoh

See Install + first build (Linux) for more.

Project layout

The talker is a standalone Cargo package that pulls nano-ros in via a path dependency. Three files matter:

examples/native/rust/talker/
├── Cargo.toml          # path dep on `nros` + `nros-rmw-zenoh`
├── package.xml         # ROS-style manifest (drives codegen tooling)
├── generated/          # auto-generated message bindings (gitignored)
└── src/
    └── main.rs         # 60-line talker

POSIX talkers read the locator / domain from environment variables (NROS_LOCATOR — legacy alias ZENOH_LOCATOR — and ROS_DOMAIN_ID) — no nros.toml is needed. The nros.toml shape used by embedded targets shows up under the Embedded Starters section.

The Cargo.toml is the contract that wires nano-ros into your package. The in-tree talker is a member of the nano-ros workspace, so it does NOT carry a [workspace] table — cargo walks up and picks up the root Cargo.toml. Verbatim from examples/native/rust/talker/Cargo.toml (trimmed to the docs-relevant fields — the in-tree file also exposes rmw-cyclonedds / rmw-xrce features for the multi-RMW build path):

[package]
name    = "native-rs-talker"
version = "0.1.0"
edition = "2024"
license = "MIT OR Apache-2.0"
publish = false

[[bin]]
name = "talker"
path = "src/main.rs"

[features]
default   = ["rmw-zenoh"]
rmw-zenoh = ["dep:nros-rmw-zenoh"]

[dependencies]
nros = { path = "../../../../packages/core/nros",
         default-features = false,
         features = ["std", "rmw-cffi", "platform-posix"] }
nros-platform-cffi = { path = "../../../../packages/core/nros-platform-cffi",
                       features = ["posix-c-port"] }
nros-rmw-zenoh = { path = "../../../../packages/zpico/nros-rmw-zenoh",
                   features = ["std", "platform-posix", "ros-humble"],
                   optional = true }
std_msgs = { version = "*", default-features = false }
log = "0.4"
env_logger = "0.11"

Copying this out of the workspace? Once you move the directory elsewhere on disk, the path deps no longer resolve and there is no parent workspace to inherit from. Two options:

1. Replace each path = "../../../../packages/..." with an absolute path to your nano-ros checkout, AND add an empty [workspace] table to stop cargo walking further up the filesystem.
2. Keep it inside examples/ in your own fork of nano-ros — the simpler path while you’re learning the API.

Configure

Three runtime knobs, each overridable at three layers (defaults → config.toml → env vars):

config.toml (optional, alongside Cargo.toml):

[zenoh]
locator   = "tcp/127.0.0.1:7447"
domain_id = 0

Build

cd examples/native/rust/talker
cargo build           # or: cargo build --release

First build pulls dependencies (~3 minutes). Re-builds finish in seconds.

Run

Three terminals (each command below blocks; keep them open):

# Terminal 1 — zenoh router. Blocks the shell until Ctrl-C.
zenohd                               # installed by `nros setup native`

# Terminal 2 — the talker. The talker logs via `log::info!`, so set
# RUST_LOG=info — without it `env_logger` only shows errors and the
# `Published: N` lines stay hidden.
cd examples/native/rust/talker
RUST_LOG=info cargo run
# Expected output (on stderr):
#   [INFO  native_rs_talker] nros Native Talker (Zenoh Transport)
#   [INFO  native_rs_talker] =========================================
#   [INFO  native_rs_talker] Published: 0
#   [INFO  native_rs_talker] Published: 1
#   …

That’s the nano-ros side fully working. Optional step: verify interop with stock ROS 2.

# Terminal 3 — stock ROS 2 with rmw_zenoh_cpp. NOTE: rmw_zenoh_cpp
# uses its OWN router daemon (`ros2 run rmw_zenoh_cpp rmw_zenohd`),
# NOT the in-tree zenohd from terminal 1. They need to peer with
# each other, or both clients need to point at the same router.
# Simplest: stop terminal 1 and run only `rmw_zenohd` instead, then
# launch the talker pointing at rmw_zenohd's port (default 7447).
source /opt/ros/humble/setup.bash
export RMW_IMPLEMENTATION=rmw_zenoh_cpp
ros2 run rmw_zenoh_cpp rmw_zenohd &       # in its own subshell
# Talker publishes best-effort; stock `ros2 topic echo` defaults to
# RELIABLE, so the QoS-mismatched echo silently delivers nothing.
# Force best-effort to receive:
ros2 topic echo /chatter std_msgs/msg/Int32 --qos-reliability best_effort

If ros2 topic echo shows no output despite the talker printing Published:, the routers aren’t peering — confirm both processes point at the same port (default tcp/127.0.0.1:7447).

Readiness signal. Within 5 seconds of RUST_LOG=info cargo run, the talker should print Published: 0 (the Rust talker pre-publishes 0 before the counter advances). If no Published: line in 30 seconds:

1. Confirm RUST_LOG is set. Without RUST_LOG=info (or debug), env_logger filters out the Published: lines and the run looks silent even when it’s working.
2. Confirm zenohd is running (terminal 1). Without it, the talker blocks on Executor::open indefinitely.
3. Re-run with RUST_LOG=debug cargo run and look for “Failed to open session” — usually a wrong locator or wrong port.
4. See Troubleshooting — First 10 Minutes.

GitHub source

Canonical, copy-out: examples/native/rust/talker/

Copy the directory, rename the package, and your starter is ready to modify.

Next

• Add a subscription: examples/native/rust/listener/
• Generate bindings for custom .msg / .srv / .action files: Message Generation
• Cross-compile for an RTOS: pick the right Embedded Starter from the next section (FreeRTOS / Zephyr / NuttX / ThreadX / ESP32 / Bare-metal Cortex-M3).

First Node — C (Linux)

Build, run, and verify a single nano-ros publisher node on Linux from C. Uses CMake, the Zenoh backend, and add_subdirectory consumption.

Stuck? See Troubleshooting — First 10 Minutes for the common first-build errors.

Prereqs

Pick one path from a fresh checkout — just is NOT a prereq.

A. Bare machine (no Rust, no just, no cargo):

./scripts/bootstrap.sh base

Installs rustup, just, builds the in-tree nros CLI at packages/cli/target/release/nros, leaves the binary on PATH for this shell.

B. Already have cargo (most contributors):

cargo build --release --manifest-path packages/cli/Cargo.toml --bin nros
export PATH="$PWD/packages/cli/target/release:$PATH"

C. Tagged release, no Rust at all:

./scripts/install-nros-prebuilt.sh

Downloads the matching nros-<triple>.tar.gz from the GitHub release, sha256-verifies, installs to packages/cli/target/release/nros.

Every subsequent shell sources the workspace env via one of:

direnv allow                  # if you use direnv
source ./activate.sh          # bash / zsh
source ./activate.fish        # fish

Then provision the native host (installs the zenoh router zenohd into a shared store — no ROS 2 needed):

nros setup native --rmw zenoh

See Install + first build (Linux) for more.

Project layout

The talker is a standalone CMake project that pulls nano-ros via add_subdirectory(<repo-root>). Four files matter:

examples/native/c/talker/
├── CMakeLists.txt      # add_subdirectory + targets
├── package.xml         # ROS-style manifest (drives codegen tooling)
└── src/
    └── main.c          # ~100-line talker

An optional nros.toml sidecar can override the runtime locator / domain id (canonical schema described in Configuration). The shipped native C talker doesn’t carry one — locator + domain default to env vars.

The CMake preamble matches the canonical example shape in examples/native/c/talker/CMakeLists.txt — five set(...) lines plus the per-target link:

cmake_minimum_required(VERSION 3.22)
project(my_talker LANGUAGES C)

set(CMAKE_C_STANDARD 11)
set(CMAKE_C_STANDARD_REQUIRED ON)

# Pull nano-ros in. Adjust the relative path to your repo root.
# `NROS_RMW` is the user-facing cache var (overridable via
# `-DNROS_RMW=<rmw>`); the example forwards it to `NANO_ROS_RMW`,
# the var the nano-ros add_subdirectory reads.
set(NANO_ROS_PLATFORM posix)
set(NROS_RMW "zenoh" CACHE STRING
    "Active RMW (zenoh|xrce|cyclonedds) — selects the backend linked into my_talker.")
set(NANO_ROS_RMW "${NROS_RMW}")
add_subdirectory(<rel-path-to-nano-ros> nano_ros)

# Generate C bindings for std_msgs (transitively depends on
# builtin_interfaces; the dependency is declared explicitly).
nros_generate_interfaces(builtin_interfaces SKIP_INSTALL)
nros_generate_interfaces(std_msgs DEPENDENCIES builtin_interfaces
                                  SKIP_INSTALL)

add_executable(my_talker src/main.c)
target_link_libraries(my_talker PRIVATE
    std_msgs__nano_ros_c
    NanoRos::NanoRos)
nros_platform_link_app(my_talker)

nros_platform_link_app(my_talker) transitively wires the active RMW’s strong nros_app_register_backends() stub (calling nros_rmw_zenoh_register() for the zenoh build above). On POSIX you do not call nano_ros_link_rmw() explicitly — the platform module handles it.

The C entry point is int nros_app_main(int argc, char **argv) (not main); <nros/app_main.h> provides the OS-side main stub that wires signal handling and forwards to your function.

#include <nros/app_main.h>
#include <nros/init.h>
#include <nros/executor.h>
#include <nros/node.h>
#include <nros/publisher.h>
#include <nros/timer.h>
#include "std_msgs.h"

int nros_app_main(int argc, char** argv) {
    // 1. nros_init() — opens the zenoh session
    // 2. nros_executor_init() / nros_node_init()
    // 3. std_msgs_msg_int32_publisher_init() — typed publisher
    // 4. nros_timer_init() with a 1 Hz period + publish callback
    // 5. nros_executor_spin() until SIGINT
}

Configure

Three runtime knobs:

nros.toml (optional) accepts the same [node] + [[transport]] schema as every other nano-ros tutorial (see Configuration); the C runtime reads it only when wired explicitly via nros_config_load() (see the example source).

Build

cd examples/native/c/talker
cmake -B build
cmake --build build

The first configure pulls and builds nano-ros’s Rust staticlibs (~3 minutes). Re-builds finish in seconds.

Run

Three terminals.

# 1. Start the zenoh router:
zenohd                               # installed by `nros setup native`

# 2. Run the talker:
cd examples/native/c/talker
./build/c_talker
# Expected output:
#   nros C Talker
#   =================
#   Published: 0
#   Published: 1
#   Published: 2
#   …

# 3. Verify from stock ROS 2:
source /opt/ros/humble/setup.bash
export RMW_IMPLEMENTATION=rmw_zenoh_cpp
# Talker publishes best-effort; stock `ros2 topic echo` defaults to
# RELIABLE, so the QoS-mismatched echo silently delivers nothing.
# Force best-effort to receive:
ros2 topic echo /chatter std_msgs/msg/Int32 --qos-reliability best_effort

Readiness signal. Within 5 seconds of ./build/c_talker, the binary should print Published: 0 on stdout — Rust + C + C++ all start the counter at 0 (Phase 208.D.9). If no Published: line in 30 seconds:

1. Confirm zenohd is running (terminal 1). Without it, nros_support_init returns immediately with -4 (NROS_RET_NOT_FOUND — connection refused).
2. Wrong locator / unreachable host → same -4 signature in stderr. Reachable host but mismatched port → talker hangs on session-open handshake rather than returning a code.
3. See Troubleshooting — First 10 Minutes.

GitHub source

Canonical, copy-out: examples/native/c/talker/

Next

• Add a subscription: examples/native/c/listener/
• Service / action shapes: service-client/, action-client/
• Custom .msg / .srv / .action: Message Generation
• Cross-compile for an RTOS: pick the right Embedded Starter from the next section.

First Node — C++ (Linux)

Build, run, and verify a single nano-ros publisher node on Linux from C++14. Uses CMake, the Zenoh backend, and add_subdirectory consumption.

Stuck? See Troubleshooting — First 10 Minutes for the common first-build errors.

Prereqs

Pick one path from a fresh checkout — just is NOT a prereq.

A. Bare machine (no Rust, no just, no cargo):

./scripts/bootstrap.sh base

Installs rustup, just, builds the in-tree nros CLI at packages/cli/target/release/nros, leaves the binary on PATH for this shell.

B. Already have cargo (most contributors):

cargo build --release --manifest-path packages/cli/Cargo.toml --bin nros
export PATH="$PWD/packages/cli/target/release:$PATH"

C. Tagged release, no Rust at all:

./scripts/install-nros-prebuilt.sh

Downloads the matching nros-<triple>.tar.gz from the GitHub release, sha256-verifies, installs to packages/cli/target/release/nros.

Every subsequent shell sources the workspace env via one of:

direnv allow                  # if you use direnv
source ./activate.sh          # bash / zsh
source ./activate.fish        # fish

Then provision the native host (installs the zenoh router zenohd into a shared store — no ROS 2 needed):

nros setup native --rmw zenoh

See Install + first build (Linux) for more.

Project layout

The talker is a standalone CMake project that pulls nano-ros via add_subdirectory(<repo-root>). Two files matter:

examples/native/cpp/talker/
├── CMakeLists.txt      # add_subdirectory + targets
└── src/
    └── main.cpp        # ~70-line talker

POSIX talkers read the locator + domain from arguments passed to nros::init(...); no config.toml is needed. Embedded variants under examples/<plat>/cpp/talker/ carry a config.toml that their board crate reads.

CMake preamble matches the canonical example at examples/native/cpp/talker/CMakeLists.txt — five set(...) lines + per-target link. LANGUAGES C CXX (not CXX alone): the per-target register stub the nano-ros add_subdirectory emits is a C translation unit, so C must be enabled in this directory scope or the link fails.

cmake_minimum_required(VERSION 3.22)
project(my_talker LANGUAGES C CXX)

set(CMAKE_CXX_STANDARD 14)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

# `NROS_RMW` is the user-facing cache var (overridable via
# `-DNROS_RMW=<rmw>`); the example forwards it to `NANO_ROS_RMW`,
# the var the nano-ros add_subdirectory reads.
set(NANO_ROS_PLATFORM posix)
set(NROS_RMW "zenoh" CACHE STRING
    "Active RMW (zenoh|xrce|cyclonedds) — selects the backend linked into my_talker.")
set(NANO_ROS_RMW "${NROS_RMW}")
add_subdirectory(<rel-path-to-nano-ros> nano_ros)

# Generate C++ bindings (LANGUAGE CPP — separate from the C variant).
nros_generate_interfaces(builtin_interfaces LANGUAGE CPP SKIP_INSTALL)
nros_generate_interfaces(std_msgs DEPENDENCIES builtin_interfaces
                                  LANGUAGE CPP SKIP_INSTALL)

add_executable(my_talker src/main.cpp)
target_link_libraries(my_talker PRIVATE
    std_msgs__nano_ros_cpp
    NanoRos::NanoRosCpp)
nros_platform_link_app(my_talker)

nros_platform_link_app(my_talker) transitively registers the selected RMW backend — on POSIX you do not call nano_ros_link_rmw() explicitly.

The C++ entry point is int nros_app_main(int argc, char** argv) (same as C); <nros/app_main.h> provides the OS-side main stub.

The body uses typed nros::Publisher<M> / nros::Subscription<M> wrappers over the C ABI:

#include <nros/app_main.h>
#include <nros/nros.hpp>
#include "std_msgs.hpp"

#define NROS_TRY_LOG(file, line, expr, ret) \
    std::fprintf(stderr, "[nros] %s:%d %s -> %d\n", file, line, expr, (int)ret)

int nros_app_main(int argc, char** argv) {
    NROS_TRY_RET(nros::init("tcp/127.0.0.1:7447", 0), 1);

    nros::Node node;
    NROS_TRY_RET(nros::create_node(node, "talker"), 1);

    nros::Publisher<std_msgs::msg::Int32> pub;
    NROS_TRY_RET(node.create_publisher(pub, "/chatter"), 1);

    // ... register a timer + spin
}

NROS_TRY_RET short-circuits on any non-OK return code and logs the expression that failed. Define NROS_TRY_LOG once (any sink — here std::fprintf) and reuse it across every call site.

Configure

Three runtime knobs:

Reading from env in C++ is std::getenv("NROS_LOCATOR") plus the same nros::init call — see the GitHub source for the full pattern.

Build

cd examples/native/cpp/talker
cmake -B build
cmake --build build

First configure builds nano-ros’s Rust staticlibs (~3 minutes). Re-builds finish in seconds.

Run

Three terminals.

# 1. zenoh router (installed by `nros setup native`):
zenohd

# 2. Run the talker:
cd examples/native/cpp/talker
./build/cpp_talker
# Expected:
#   Published: 0
#   Published: 1
#   …

# 3. Verify from stock ROS 2:
source /opt/ros/humble/setup.bash
export RMW_IMPLEMENTATION=rmw_zenoh_cpp
# Talker publishes best-effort; stock `ros2 topic echo` defaults to
# RELIABLE, so the QoS-mismatched echo silently delivers nothing.
# Force best-effort to receive:
ros2 topic echo /chatter std_msgs/msg/Int32 --qos-reliability best_effort

Readiness signal. Within 5 seconds of ./build/cpp_talker, the binary should print Published: 0 — Rust + C + C++ all start the counter at 0 (Phase 208.D.9). If no Published: line in 30 seconds:

1. Confirm zenohd is running (terminal 1). Without it, nros::init returns -100 (TransportError) — the NROS_TRY_RET macro logs the failed call to stderr.
2. Check stderr for [nros] …/main.cpp:LINE nros::init(...) -> -N diagnostics. -3 / -100 both indicate transport open failed.
3. See Troubleshooting — First 10 Minutes.

GitHub source

Canonical, copy-out: examples/native/cpp/talker/

Next

• Add a subscription: examples/native/cpp/listener/
• Services + actions: service-client/, action-client/
• Parameters: parameters/
• Custom .msg / .srv / .action: Message Generation
• Cross-compile for an RTOS: pick the right Embedded Starter from the next section.

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 Phase 209 compat layer (nros/rclcpp_compat.hpp + cmake/compat/NrosRclcppCompat.cmake + nros-diagnostic-updater) is built for this; 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.

Two layers of glue

Per-package CMakeLists.txt — zero nano-ros lines (Phase 210)

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 the rclcpp Find-stub (which auto-applies the rclcpp_compat.hpp force-include); find_package(std_msgs) resolves through the smart Find-stub (Phase 210.A.2 → walks NROS_INTERFACE_SEARCH_PATH > AMENT_PREFIX_PATH > bundled); the ament_target_dependencies compat shim wires both link targets.

Workspace umbrella CMakeLists.txt — one nano-ros include (Phase 210)

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(NANO_ROS_PLATFORM posix)
set(NROS_RMW "zenoh" CACHE STRING "Active RMW.")
set(NANO_ROS_RMW "${NROS_RMW}")
add_subdirectory("/path/to/nano-ros" nano_ros)

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

# 3) Drop-in source-compat surface.
include("/path/to/nano-ros/cmake/compat/NrosRclcppCompat.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 by Phase 210.F.2).

Legacy nros_generate_interfaces(<pkg>) shape

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.

What “just works” without source edits

The compat surface covers the patterns a typical ROS 2 C++ node 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 under Phase 210 (ROS-convention codegen).

• Message string fields. nano-ros codegen emits nros::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 (Phase 123.B.8 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)

• rclcpp_lifecycle::LifecycleNode — Phase 209.H (deferred). Until that lands, replace LifecycleNode with Node + manual configure/activate bookkeeping.
• Yaml-loaded parameters. declare_parameter<T>("name", default) reads from a launch yaml in stock ROS 2. nano-ros embedded has no yaml loader; Phase 209.F bakes the original yaml + the source into a constexpr parameter table (nros bake-params). Until that ships, expose parameters as compile-time constants (or via nano_ros_read_config(... "nros.toml")
  • nano_ros_generate_config_header(...)).
• 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

Open follow-ups: 209.F (yaml params bake), 209.H (LifecycleNode), 210.E.3 (in-tree migration of legacy nros_generate_interfaces(<pkg>) call sites). If your port surfaces a new gap not covered by the compat header, file it under Phase 209 (Track-A = tree-side fix that lands in cmake/compat/ or packages/core/nros-cpp/; Track-B = a codegen change).

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.

Drop your reduced-case node under examples/templates/<your-port>/ and add it to CI once the gap closes.

Your own message package

You write a ROS 2 msg package once. The same src/my_msgs/ directory builds under both:

• colcon build — upstream rosidl_default_generators produces the upstream-ROS bindings.
• a nano-ros build — rosidl_generate_interfaces(...) is intercepted by nano-ros’s wrapper and routed through nano-ros codegen.

Different build systems, identical source tree. No nano-ros-specific files in the msg package.

The msg package — stock ROS shape

Drop a verbatim ROS msg pkg under src/ of your workspace:

src/my_msgs/
├── package.xml
├── CMakeLists.txt
└── msg/
    └── MyMsg.msg

src/my_msgs/package.xml:

<?xml version="1.0"?>
<package format="3">
  <name>my_msgs</name>
  <version>0.1.0</version>
  <description>My ROS 2 msg package</description>
  <maintainer email="you@example.org">you</maintainer>
  <license>Apache-2.0</license>

  <buildtool_depend>ament_cmake</buildtool_depend>
  <depend>std_msgs</depend>
  <build_depend>rosidl_default_generators</build_depend>
  <exec_depend>rosidl_default_runtime</exec_depend>

  <member_of_group>rosidl_interface_packages</member_of_group>

  <export>
    <build_type>ament_cmake</build_type>
  </export>
</package>

src/my_msgs/CMakeLists.txt:

cmake_minimum_required(VERSION 3.20)
project(my_msgs)

find_package(ament_cmake REQUIRED)
find_package(rosidl_default_generators REQUIRED)
find_package(std_msgs REQUIRED)

rosidl_generate_interfaces(${PROJECT_NAME}
    msg/MyMsg.msg
    DEPENDENCIES std_msgs
)

ament_export_dependencies(rosidl_default_runtime)
ament_package()

src/my_msgs/msg/MyMsg.msg:

std_msgs/Header header
string payload
int32 sequence

Zero nano-ros-specific lines. Run colcon build from this dir — upstream ROS produces a working msg package. Drop the same dir into a nano-ros build (below) — nano-ros codegen produces the equivalent bindings.

The consumer — stock ROS shape

// src/my_app/src/my_app.cpp
#include <chrono>
#include <memory>

#include <rclcpp/rclcpp.hpp>
#include "my_msgs/msg/my_msg.hpp"

using namespace std::chrono_literals;

class MyNode : public rclcpp::Node {
public:
    MyNode() : rclcpp::Node("my_node") {
        publisher_ = this->create_publisher<my_msgs::msg::MyMsg>("topic", 10);
        timer_ = this->create_wall_timer(500ms, [this]() {
            my_msgs::msg::MyMsg m;
            m.payload = "hello";
            publisher_->publish(m);
        });
    }
private:
    std::shared_ptr<rclcpp::TimerBase> timer_;
    std::shared_ptr<rclcpp::Publisher<my_msgs::msg::MyMsg>> publisher_;
};

int main(int argc, char* argv[]) {
    rclcpp::init(argc, argv);
    rclcpp::spin(std::make_shared<MyNode>());
    rclcpp::shutdown();
    return 0;
}

src/my_app/CMakeLists.txt:

cmake_minimum_required(VERSION 3.20)
project(my_app LANGUAGES CXX)

find_package(ament_cmake REQUIRED)
find_package(rclcpp REQUIRED)
find_package(my_msgs REQUIRED)
find_package(std_msgs REQUIRED)

add_executable(my_app src/my_app.cpp)
target_link_libraries(my_app
    rclcpp::rclcpp
    my_msgs::my_msgs
    std_msgs::std_msgs
)

ament_package()

The nano-ros umbrella — the only nano-ros-specific file

The two src/ packages are stock ROS. One umbrella CMakeLists.txt at the workspace root pulls nano-ros in:

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

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

# Point the smart Find-stub at this workspace (must precede the compat
# include so the workspace Find<pkg>.cmake auto-emit picks it up).
set(NROS_INTERFACE_SEARCH_PATH "${CMAKE_SOURCE_DIR}/src")

# Pull the rclcpp source-compat layer (find_package(rclcpp) etc.).
include(/path/to/nano-ros/cmake/compat/NrosRclcppCompat.cmake)

# Bulk-build every workspace msg pkg in topo order. One line, no
# add_subdirectory(src/<pkg>) per pkg.
nros_workspace_interfaces()

# Build the consumer app.
add_subdirectory(src/my_app)

Build:

cmake -B build -S .
cmake --build build -j
./build/src/my_app/my_app

Cross-build proof — same source under colcon

cd src && colcon build

src/my_msgs/ produces the upstream my_msgs bindings; src/my_app/ links against the upstream rclcpp + my_msgs::my_msgs. The nano-ros build above produces the same source linked against NanoRos::NanoRosCpp through the nano-ros codegen, with the smart Find-stub forwarding find_package(my_msgs) → my_msgs::my_msgs.

The interface-package search path

find_package(<pkg>) walks three layers, highest priority first:

Shadowing — a workspace my_msgs and an AMENT my_msgs resolve to the workspace one, with a message(STATUS ...) line noting the shadow.

Shadowing contract

When two layers carry the same package name (e.g. a workspace std_msgs and /opt/ros/<distro>/share/std_msgs/), the higher layer wins — silently and deterministically. Concretely:

1. NROS_INTERFACE_SEARCH_PATH > AMENT_PREFIX_PATH > bundled. The smart Find-stub (cmake/compat/stubs/_NrosFindRosMsgPackage.cmake) walks the three layers in order; the first hit wins. Lower layers are skipped entirely.

2. The configure pass emits a message(STATUS ...) line noting the resolved path, e.g.

   -- nros: find_package(std_msgs) -> /path/to/workspace/src/std_msgs
   

   Grep your configure log for nros: find_package(<pkg>) to confirm which layer supplied each pkg.

3. Intra-workspace shadowing — when two roots under NROS_INTERFACE_SEARCH_PATH both ship the same pkg, the nros_workspace_interfaces() bulk orchestrator keeps the earlier-listed one and warns about the shadowed copy.

4. No partial overrides. Shadowing is whole-package: a workspace pkg replaces ALL of an AMENT pkg’s interfaces, not a subset. If you only want to add MyExtraMsg.msg to std_msgs, ship a separate pkg (e.g. my_std_extra_msgs) — don’t shadow.

Compile-time fail-safe

Shadowing is observed at compile time: if your workspace std_msgs declares a Marker.msg and your consumer includes "std_msgs/msg/marker.hpp", the build only succeeds when the workspace copy is the one linked. AMENT’s std_msgs ships no Marker.msg, so a fall-through resolves to a missing header. The build outcome is the strongest evidence — nm on the linked binary is the symbol-level corroborator.

Reference fixture for shadowing

The canonical smoke proof for the Layer 1 > Layer 2 case ships at examples/templates/workspace-shadowing/ — a workspace std_msgs carrying a Marker.msg shadows the AMENT-installed std_msgs. The fixture’s README.md walks through the cmake + nm verification. A regression test (packages/testing/nros-tests/tests/phase210_f4_shadowing.rs) re-runs the same proof in CI when AMENT is sourced.

Reference fixture

examples/templates/local-msg-package/ ships the exact pattern above end-to-end (two workspace msg pkgs with a dep between them, plus a consumer node). Use it as a copy-out template.

Troubleshooting — First 10 Minutes

The Linux starter walkthroughs assume nros setup native --rmw zenoh has run, zenohd is reachable, and the right Rust target is installed. When something goes wrong in the first ten minutes, the error you see usually points at one of the predictable misses below.

Each branch quotes the real stderr you can grep against — not a paraphrase. If your error text matches, the fix on the right is the one to try.

A. Build failures (cargo / cmake)

A1. Missing path-deps onto in-tree crates

error[E0432]: unresolved import `nros`
error: failed to load source for dependency `nros`
error: could not find `nros-rmw-zenoh`

The example’s Cargo.toml carries a path-dep onto the in-tree packages/core/nros* crates (the canonical copy-out shape). When the example is cargo-built from a stripped-down checkout (e.g. you vendored only the example dir into your own workspace), those path = "../../../../packages/…" entries resolve to nothing. Fix one of:

• Build inside a full nano-ros checkout, OR
• Rewrite the path = … entries to git = … against github.com/NEWSLabNTU/nano-ros and pin a rev.

This is not an nros setup issue — nros setup only fetches the SDK / source-package payload (zenoh-pico, mbedtls, cyclonedds, …); it does not synthesise missing Cargo dependencies.

A2. nros codegen tool not found

nros (codegen tool) not found on PATH or in packages/cli/target/release/
or ${NROS_HOME:-~/.nros}/bin. nano-ros assumes `nros` is provided
(Phase 218 carries the CLI in-tree at packages/cli/). Build it with:
  just setup-cli                 # or: just setup

Missing the nros binary on PATH and in the per-checkout location. Phase 218 builds it from the in-tree sub-workspace; first activate the workspace, then build:

source ./activate.sh        # OR: direnv allow / source ./activate.fish
just setup-cli              # builds packages/cli/target/release/nros

If packages/cli/target/release/nros exists but PATH doesn’t see it — that’s the [PATH] doctor status (D2 below), not this branch (the activate file is what puts it on PATH).

The nros binary ships the codegen — there is no separate nros-codegen build step. CMake examples auto-resolve nros from PATH / packages/cli/target/release/ / ${NROS_HOME:-~/.nros}/bin/; -D_NANO_ROS_CODEGEN_TOOL=<path> is an override, not a requirement.

A3. Rust target not installed

error: could not compile … due to previous error
the target `thumbv7m-none-eabi` is not installed

Add it:

rustup target add thumbv7m-none-eabi
# or whichever target the example's `.cargo/config.toml` names

A4. Cross linker not found

error: linker `arm-none-eabi-gcc` not found

The cross toolchain wasn’t provisioned. Run nros setup for your board (it ships a prebuilt arm-none-eabi-gcc):

nros setup qemu-arm-freertos       # or qemu-arm-nuttx / mps2-an385 / …

A5. Cyclone DDS runtime missing

ld: cannot find -lddsc
ld: cannot find -lcyclonedds-ddsc

The Cyclone DDS runtime wasn’t provisioned:

nros setup native --rmw cyclonedds

A6. cargo build --features rmw-cyclonedds can’t link

undefined reference to `nros_rmw_cyclonedds_register`
undefined reference to `dds_create_participant`

rmw-cyclonedds cannot link from cargo alone — the Cyclone backend is C++ + CMake, registered via nros_rmw_cffi_register from a CMake-built target. Phase 175 wired this through CMakeLists.txt + Corrosion. Use the cmake build path instead:

cd examples/native/c/talker        # (or cpp / rust)
cmake -B build-cyclone -DNROS_RMW=cyclonedds
cmake --build build-cyclone

The pure cargo build --features rmw-cyclonedds only succeeds for the zenoh-pico + xrce backends today.

A7. “current package believes it’s in a workspace”

error: current package believes it's in a workspace when it's not:
current:   …/Cargo.toml
workspace: /…/nano-ros/Cargo.toml

cargo walks up the directory tree looking for a workspace root and adopts the example into the outer nano-ros workspace. Per-example Cargo.tomls don’t ship an empty [workspace] table yet (tracked as F1 in phase-208-followups.md).

Hits on:

• nested clones / worktrees of nano-ros that share an ancestor path with the outer nano-ros/Cargo.toml;
• a user vendoring an example into their own workspace.

Workaround on a regular clone: build from the nano-ros root, e.g. cargo build -p qemu-bsp-talker, instead of cd’ing into the example dir.

A8. direnv allow reminder

NROS_PLATFORM_CFFI_INCLUDE not set (direnv allow, or build via just)
FREERTOS_PORT not set

Phase 208.D.1 made the common build sites autoresolve these from the in-tree checkout, so a fresh cargo build no longer panics on them in canonical examples. If your custom build site still does, run direnv allow once after clone, or set the env explicitly / build via the just <plat> recipe.

B. Binary runs but no output

B1. Rust: Failed to open session: Transport(ConnectionFailed)

thread 'main' panicked at examples/native/rust/talker/src/lib.rs:96:58:
Failed to open session: Transport(ConnectionFailed)

zenohd isn’t running, or isn’t reachable on the locator the talker is pointed at. Start it in another terminal (nros setup native --rmw zenoh lands zenohd under ${NROS_HOME:-~/.nros}/sdk/zenohd/; the activate file puts it on PATH):

zenohd --listen tcp/127.0.0.1:7447

Default ports: tcp/127.0.0.1:7447 on POSIX, tcp/10.0.2.2:7451 on QEMU FreeRTOS (Slirp forwards to host), 7452 NuttX, 7453 ThreadX-RV, 7454 ESP32, 7455 ThreadX-Linux, 7456 Zephyr.

B2. C: NROS_CHECK failed: nros_support_init(...) -> -4

NROS_CHECK failed at src/main.c:152: nros_support_init(&app.support, locator, domain_id) -> -4

Process exits 1 (the retval passed to NROS_CHECK_RET). -4 = NROS_RET_NOT_FOUND — the locator was unreachable (zenohd not running, or wrong port). Same fix as B1 above.

The C API entry point is nros_support_init, not nros_init or nros::init — those don’t exist in the C API.

B3. C++: process exits 156 after a nros::init failure

nros::init returned NROS_CPP_RET_TRANSPORT_ERROR (-100)

Same root cause as B1/B2 — zenohd not reachable. NROS_CPP_RET_TRANSPORT_ERROR = -100 is the C++ result code that NROS_TRY_RET propagates from main(); on POSIX this becomes (unsigned char)-100 = 156 as the process exit code. Treat “exited 156 after starting” as the C++ equivalent of B1.

B4. Override the locator at runtime

When the talker can’t reach the daemon and you don’t want to edit nros.toml, override the locator with the canonical env var:

NROS_LOCATOR=tcp/192.168.1.50:7447 ./build/c_talker
# Legacy alias (still accepted): ZENOH_LOCATOR=… ./build/c_talker
ROS_DOMAIN_ID=7 ./build/c_talker         # also overridable

The Rust / C / C++ talkers all read NROS_LOCATOR first, fall back to ZENOH_LOCATOR, then to nros.toml, then to the build-time default.

B5. Binary exits immediately, no error printed

Buffering: setvbuf(stdout, NULL, _IOLBF, 0) if you piped the run. POSIX terminals flush on newline; piped stdout full-buffers and may eat short outputs. Add a RUST_LOG=info (Rust) or unbuffer the C / C++ output (stdbuf -oL).

C. ROS 2 side sees nothing

C1. RMW mismatch

# On the ROS 2 side, default rmw_fastrtps_cpp will NOT see nano-ros:
export RMW_IMPLEMENTATION=rmw_zenoh_cpp     # for Zenoh
export RMW_IMPLEMENTATION=rmw_cyclonedds_cpp # for Cyclone

C2. QoS mismatch — echo silent, list sees the topic

ros2 topic list           # /chatter shown
ros2 topic echo /chatter  # … nothing

nano-ros publishers default to BEST_EFFORT; stock ros2 topic echo defaults to RELIABLE. The QoS-mismatched subscriber is created but receives no data. Force best-effort on the echo:

ros2 topic echo /chatter std_msgs/msg/Int32 --qos-reliability best_effort

D. Doctor + last-resort

D1. Use the per-platform doctor first

just freertos doctor       # FreeRTOS / QEMU / arm-none-eabi
just nuttx doctor          # NuttX
just zephyr doctor         # Zephyr
just threadx_linux doctor  # ThreadX-Linux
# etc.

Each scoped doctor is fast and prints the same fixit hints for the toolchain you actually need.

D2. [PATH] nros built but not on PATH

The doctor now reports this distinct from [MISSING] when the binary is built at packages/cli/target/release/nros (or the transitional ${NROS_HOME:-~/.nros}/bin/nros) but PATH doesn’t see it. Activate the workspace — it wires PATH:

source ./activate.sh        # bash / zsh
# OR
source ./activate.fish      # fish
# OR
direnv allow                # auto-activates on `cd nano-ros`

Don’t loop on just workspace cargo-tools — that re-runs the build which short-circuits on the same PATH miss.

D3. Full sweep (slow)

just doctor tier=default

Only run this when you’re standing up every supported platform in one go. It walks every per-platform doctor and can take a few minutes.

D4. File an issue

When all else fails, include:

• the exact command you ran,
• the full stderr,
• rustc --version, cmake --version, qemu-system-arm --version,
• nros --version.

What success looks like

A correctly-running Rust Linux talker (examples/native/rust/talker) prints something like this on stderr (with RUST_LOG=info):

[INFO  native_rs_talker] nros Native Talker (Zenoh Transport)
[INFO  native_rs_talker] =========================================
[INFO  native_rs_talker] Node created: talker
[INFO  native_rs_talker] Publisher created for topic: /chatter
[INFO  native_rs_talker] Published: 0
[INFO  native_rs_talker] Published: 1
[INFO  native_rs_talker] Published: 2

A correctly-running C talker (examples/native/c/talker) prints on stdout:

nros C Talker
=================
Published: 0
Published: 1
Published: 2

A correctly-running C++ talker prints the same Published: N line once per second.

The ROS 2 side (ros2 topic echo /chatter std_msgs/msg/Int32 --qos-reliability best_effort with RMW_IMPLEMENTATION=rmw_zenoh_cpp) should see:

data: 0
---
data: 1
---
data: 2
---

If you see all three of these — talker logging, ROS 2 echo output, and matching counter values — interop is verified end-to-end.

See also

• Install + first build — full setup walkthrough
• First Node — Rust — the canonical Rust starter
• Troubleshooting — broader issue-by-issue reference for post-first-build problems

Multi-Node Project Layout

You built the single-file talker in examples/native/rust/talker/: one main.rs, one Cargo.toml, one package — open a terminal, run cargo run, done. That shape covers a lot of ground: demos, driver tests, single-purpose microcontroller apps.

At some point it stops being enough.

When you outgrow one app

Three common triggers:

1. Two or more nodes. You want a talker and a listener, or a sensor driver alongside a control loop. Splitting them into one entry binary per node file works until you need to tune their wiring or deploy them to different boards.

2. A shared launch topology. You want to describe once how nodes are named, remapped, and parameterised — and reuse that description across a dev laptop, a hardware bring-up board, and a sim target.

3. Multiple deploy targets. The same talker logic goes on a native Linux host for integration testing and on an STM32F4 for production. The node logic is identical; only the boot and board differ.

4. Mixed implementation languages. You want to keep a C driver or legacy C node, but host the composed system in a C++ or Rust Entry pkg. The Node-pkg register ABI is language-neutral, so a C Node pkg can link into the same Entry binary as C++ or Rust Node pkgs.

That’s when you split your project into a multi-node workspace.

Canonical layout

Start with the whole project before diving into the parts:

my_robot_ws/
├── Cargo.toml                  # Rust workspace root, or CMakeLists.txt for C/C++
└── src/
    ├── talker_pkg/             # Node pkg: reusable node logic, no main()
    ├── listener_pkg/           # Node pkg: another reusable node
    ├── robot_bringup/          # Bringup pkg: launch XML + system.toml
    └── native_entry/           # Entry pkg: one runnable binary for one board

The roles are deliberately separated:

A typical product has many Node pkgs, one Bringup pkg per logical system, and one Entry pkg per board or deploy target. The same talker_pkg and listener_pkg can be linked into a native host Entry pkg for integration testing and a Cortex-M Entry pkg for hardware.

Reading order

This group starts broad and then drills into each part:

1. Project layout — this page: when to split and how the roles fit.
2. Node packages — reusable node libraries with nros::node!.
3. Bringup packages — launch XML, system.toml, remaps, parameters.
4. Entry packages — the board-specific binary that boots the topology.
5. C / C++ multi-node workspaces — the same structure through CMake.
6. Mixed-language workspaces — C Node pkgs hosted by C/C++ Entry pkgs.
7. Role reference — metadata fields and macro forms in reference style.

Prereqs

Pick one path from a fresh checkout — just is NOT a prereq.

A. Bare machine (no Rust, no just, no cargo):

./scripts/bootstrap.sh base

Installs rustup, just, builds the in-tree nros CLI at packages/cli/target/release/nros, leaves the binary on PATH for this shell.

B. Already have cargo (most contributors):

cargo build --release --manifest-path packages/cli/Cargo.toml --bin nros
export PATH="$PWD/packages/cli/target/release:$PATH"

C. Tagged release, no Rust at all:

./scripts/install-nros-prebuilt.sh

Downloads the matching nros-<triple>.tar.gz from the GitHub release, sha256-verifies, installs to packages/cli/target/release/nros.

Every subsequent shell sources the workspace env via one of:

direnv allow                  # if you use direnv
source ./activate.sh          # bash / zsh
source ./activate.fish        # fish

Then provision the native host:

nros setup native --rmw zenoh

The three roles in practice

Node pkg — a lib crate that contains one node’s logic. It declares nros::node!(T) and carries [package.metadata.nros.node] in its Cargo.toml. It has no fn main() — that lives in the Entry pkg. One Node pkg per node. Think of it as a composable building block: the same talker_pkg lib can be assembled into a native binary and an embedded binary without any source change.

Bringup pkg — a purely declarative directory that owns the launch topology. It contains a package.xml, a system.toml (listing which nodes run, how they’re wired, per-target deploy config), and a launch/ directory with ROS 2 launch XML. No Cargo.toml, no compiled code. Naming convention <system>_bringup, matching nav2 / Autoware / turtlebot3. This role is optional — a workspace with a single deploy target can fold the launch files and system.toml directly into the Entry pkg.

Entry pkg — a bin crate that boots a topology on one specific board. It carries [package.metadata.nros.entry] with deploy = "<board>" and a src/main.rs that is just nros::main!(...). One Entry pkg per deploy target. The Entry pkg links in all Node pkg libs, links in the board crate, and hands control to the nano-ros runtime.

The app-node shape you already know (examples/native/rust/talker/) is effectively a fused Entry + Node pkg: a single package that is both the logic and the boot point. That fusion is fine — and encouraged — for single-node work. Only split when you actually need the flexibility.

ROS 2 ↔ nano-ros command map

If you’re coming from ROS 2, here’s the mapping of the commands you already know:

Build verbs (cargo for Rust, cmake for C/C++, west for Zephyr, idf.py for ESP-IDF) are used directly — there is no CLI build indirection. The composed Entry pkg binary IS the launch product: one Entry pkg = one binary = one process. Multi-process orchestration (equivalent to multiple ros2 launch nodes in separate processes) is a separate Entry pkg per deploy + a shell script / tmux session, not a CLI verb.

The app-node shape stays valid

There is no obligation to restructure. If your project is one node on one board, the app-node shape (src/main.rs + one package = both logic and boot) is perfectly idiomatic and has no runtime penalty. The three-role split is a tool for when you need it, not a gatekeeping requirement.

Where to go next

Walk through the multi-node project model step by step:

1. Node packages — scaffold and implement Node pkgs with nros::node!.
2. Bringup packages — declare your topology in a Bringup pkg.
3. Entry packages — write the Entry pkg that boots everything together.
4. C / C++ multi-node workspaces — use the same project shape with CMake.

For C Node pkgs hosted by a C++ Entry pkg, see Mixed-language workspace.

For the full API reference covering all three roles, see Role reference.

Node packages

This page is part of the Multi-Node Projects group. Previous: Project layout — Next: Bringup packages

A Node pkg is the unit of reusable behaviour in a multi-node workspace. It is a Rust library — a [lib] crate — that implements one node and registers it with nros::node!(T). The Entry pkg is what boots the binary; the Node pkg is what runs inside it.

Prereqs

Pick one path from a fresh checkout — just is NOT a prereq.

A. Bare machine (no Rust, no just, no cargo):

./scripts/bootstrap.sh base

Installs rustup, just, builds the in-tree nros CLI at packages/cli/target/release/nros, leaves the binary on PATH for this shell.

B. Already have cargo (most contributors):

cargo build --release --manifest-path packages/cli/Cargo.toml --bin nros
export PATH="$PWD/packages/cli/target/release:$PATH"

C. Tagged release, no Rust at all:

./scripts/install-nros-prebuilt.sh

Downloads the matching nros-<triple>.tar.gz from the GitHub release, sha256-verifies, installs to packages/cli/target/release/nros.

Every subsequent shell sources the workspace env via one of:

direnv allow                  # if you use direnv
source ./activate.sh          # bash / zsh
source ./activate.fish        # fish

Then provision the native host:

nros setup native --rmw zenoh

Scaffolding a Node pkg

Use nros new to create a skeleton:

nros new talker --platform native --lang rust

nros new creates a project skeleton. For a workspace, move (or create) the result under src/talker_pkg/ so the workspace root’s Cargo.toml can include it as a member:

# workspace Cargo.toml
[workspace]
resolver = "2"
members = ["src/talker_pkg", "src/listener_pkg", "src/native_entry"]

Node pkg anatomy

A Node pkg has three files:

src/talker_pkg/
├── package.xml          # ROS 2 manifest — <exec_depend> per message package
├── Cargo.toml           # [lib] + [package.metadata.nros.node] metadata
└── src/lib.rs           # impl Node + ExecutableNode; ends with nros::node!(Talker);

No fn main() here — a Node pkg is a library linked into an Entry pkg. The Entry pkg’s macro-generated runtime owns nros::init, executor open, RMW registration, and the spin/yield loop.

Cargo.toml — the [package.metadata.nros.node] block

The metadata block is what the nros CLI reads to discover, name, and wire this node into a topology. From examples/stm32f4/rust/talker_pkg/Cargo.toml:

[lib]
crate-type = ["rlib"]

[dependencies]
nros = { path = "../../../../packages/core/nros", default-features = false,
         features = ["alloc", "rmw-cffi", "platform-bare-metal", "ros-humble"] }

[package.metadata.nros.node]
class = "stm32f4_talker_pkg::Talker"
name = "talker"
default_namespace = "/"

The three fields in [package.metadata.nros.node]:

For a native workspace the nros dep would use features = ["std", "rmw-cffi", "platform-posix", "ros-humble"] instead of platform-bare-metal. The RMW feature (rmw-zenoh, rmw-xrce, rmw-cyclonedds) is chosen at build time — it is not baked into the Node pkg itself.

src/lib.rs — the node implementation

A Node pkg implements two traits: Node (declarative registration) and ExecutableNode (per-callback body), then calls nros::node! to export the trampolines the Entry macro expects.

Here is the essential shape, drawn from examples/stm32f4/rust/talker_pkg/src/lib.rs (see that file for the full worked version):

#![allow(unused)]
fn main() {
use nros::{
    CallbackCtx, ExecutableNode, Node, NodeContext, NodeOptions, NodeResult,
    TimerDuration,
};

pub struct Talker;

impl Node for Talker {
    const NAME: &'static str = "talker";

    fn register(ctx: &mut NodeContext<'_>) -> NodeResult<()> {
        let mut node = ctx.create_node(NodeOptions::new("talker"))?;
        let chatter = node.create_publisher_for_topic::<MyMsg>("/chatter")?;
        let _timer =
            node.create_timer_for_callback_name("on_tick", TimerDuration::from_millis(1000))?;
        node.callback_for_name("on_tick")
            .publishes_entity(&chatter)?;
        Ok(())
    }
}

impl ExecutableNode for Talker {
    type State = i32;

    fn init() -> Self::State { 0 }

    // See the full example for the callback body.
}

nros::node!(Talker);   // <-- exports the trampolines; this is the last line
}

Key points:

• Node::register is declarative — it runs once at startup to declare publishers, subscriptions, timers, and callback edges. No message bytes flow here.
• ExecutableNode::on_callback is the body — called by the Entry pkg’s executor each time a callback fires. state is your per-node mutable storage.
• nros::node!(Talker) must be the last public API call in the file. It generates the extern "C" trampolines the Entry macro imports.
• There is no fn main() in a Node pkg.

package.xml — the ROS 2 manifest

A Node pkg that uses generated message types lists them as <exec_depend> entries. Minimal example:

<?xml version="1.0"?>
<package format="3">
  <name>talker_pkg</name>
  <version>0.1.0</version>
  <description>Talker node</description>
  <maintainer email="dev@example.com">Developer</maintainer>
  <license>MIT OR Apache-2.0</license>

  <depend>std_msgs</depend>

  <export>
    <build_type>ament_cargo</build_type>
  </export>
</package>

If your node uses no external message packages, the <depend> line can be omitted.

Building

From the workspace root, sync generated interfaces first, then let Cargo compile the Node pkgs and Entry pkg:

# From examples/workspaces/rust/ (or your workspace root):
nros ws sync
nros codegen-system --bringup demo_bringup
cargo build -p native_entry

No per-Node-pkg invocation is needed — the workspace resolver handles dependency ordering.

To cross-compile for an embedded target, pass --target and ensure .cargo/config.toml in the workspace root sets the right linker and target:

cargo build --target thumbv7em-none-eabihf

Next steps

• Bringup packages — wire the Node pkgs together into a topology.
• Entry packages — build the binary that boots the topology on real hardware or a host process.
• Role reference — the full reference for all three roles, metadata fields, and the nros::main!() four forms.

Bringup packages

A Bringup pkg is the declarative glue that ties your Node packages together into a runnable topology. It owns the launch file, the wiring between nodes, and the per-target deploy config — all without any compiled code of its own.

Pre-requisite: You’ve scaffolded your Node packages following the Node packages guide. This page adds the demo_bringup layer between them and the Entry package that boots everything.

Prereqs

Pick one path from a fresh checkout — just is NOT a prereq.

A. Bare machine (no Rust, no just, no cargo):

./scripts/bootstrap.sh base

Installs rustup, just, builds the in-tree nros CLI at packages/cli/target/release/nros, leaves the binary on PATH for this shell.

B. Already have cargo (most contributors):

cargo build --release --manifest-path packages/cli/Cargo.toml --bin nros
export PATH="$PWD/packages/cli/target/release:$PATH"

C. Tagged release, no Rust at all:

./scripts/install-nros-prebuilt.sh

Downloads the matching nros-<triple>.tar.gz from the GitHub release, sha256-verifies, installs to packages/cli/target/release/nros.

Every subsequent shell sources the workspace env via one of:

direnv allow                  # if you use direnv
source ./activate.sh          # bash / zsh
source ./activate.fish        # fish

Then provision the native host:

nros setup native --rmw zenoh

What a Bringup pkg is

A Bringup pkg is pure declarative — no Cargo.toml, no CMakeLists.txt, no src/. Its job is to describe which nodes run, how they’re wired, and where they deploy. Naming convention: <system>_bringup (aliased <system>_launch), matching nav2 / Autoware / turtlebot3.

It is optional: required only when two or more Entry packages share one topology. A single-Entry workspace can fold launch/ + system.toml directly into the Entry pkg.

Anatomy

src/demo_bringup/
├── package.xml          # ROS 2 manifest; <exec_depend> per node pkg
├── system.toml          # [system] + [[component]] + [deploy.<target>]
├── launch/
│   └── system.launch.xml   # ROS 2 launch schema, verbatim
└── config/                 # optional — params.yaml, per-target overrides

system.toml — node wiring + deploy targets

The system.toml is the machine-readable topology. It lists every node the system runs, its class path, and one or more deploy targets (which board, which RMW, which domain).

Below is a minimal two-node example adapted from the real fixture at packages/testing/nros-tests/fixtures/orchestration_e2e/demo_pkg_bringup/system.toml:

[system]
name = "demo"
rmw = "zenoh"
domain_id = 0

[[component]]
pkg = "talker_pkg"
class = "talker_pkg::Talker"
name = "talker"

[[component]]
pkg = "listener_pkg"
class = "listener_pkg::Listener"
name = "listener"

[deploy.native]
kind = "self"
target = "x86_64-unknown-linux-gnu"

Key fields:

For multi-domain setups or cross-domain bridges add [[domain]] and [[bridge]] sections — see docs/design/0024-multi-node-workspace-layout.md §11 for the full schema.

launch/system.launch.xml — ROS 2 launch schema

The launch file uses the ROS 2 launch XML schema verbatim — nano-ros reads it with the same parser so existing nav2/Autoware/turtlebot3 XML pastes in and Just Works.

<launch>
  <node pkg="talker_pkg" exec="talker" name="talker"/>
  <node pkg="listener_pkg" exec="listener" name="listener"/>
</launch>

v1 tag set

Substitutions

• $(find <pkg>) — resolves to the package’s install/source path
• $(var <arg>) — expands a launch argument
• $(env <name>) — reads an environment variable

A richer example using args and remapping (taken from the real fixture):

<launch>
  <arg name="talker_name" default="talker" />

  <node pkg="talker_pkg" exec="talker" name="$(var talker_name)" output="screen">
    <param name="rate_hz" value="25" />
    <remap from="chatter" to="/chatter" />
  </node>

  <node pkg="listener_pkg" exec="listener" name="listener"/>
</launch>

Note: Python .launch.py files are not yet supported in v1 — use the XML schema above.

package.xml

A standard ROS 2 manifest. List each Node package as an <exec_depend>:

<?xml version="1.0"?>
<package format="3">
  <name>demo_bringup</name>
  <version>0.1.0</version>
  <description>Bringup package for the demo system</description>
  <maintainer email="you@example.com">Your Name</maintainer>
  <license>Apache-2.0</license>

  <exec_depend>talker_pkg</exec_depend>
  <exec_depend>listener_pkg</exec_depend>

  <export>
    <build_type>ament_cmake</build_type>
  </export>
</package>

No <build_depend> entries — there is nothing to compile.

Workflow: check → run

Once your Bringup pkg is written, use nros check to validate and cargo run to execute the topology:

# 1. Lint the bringup pkg (pure-declarative check — no Cargo.toml, stray files, etc.)
nros check --bringup src/demo_bringup

# 2. Lint the whole workspace (pkg/class rows, duplicate system.toml, etc.)
nros check --workspace .

# 3. Run the composed Entry binary (boots all nodes in a single process)
zenohd --listen tcp/127.0.0.1:7447 &   # router — in another shell
cargo run -p native_entry

Both nros check forms pass for the canonical template at examples/workspaces/rust/.

Caveat — nros plan with this template

• nros plan demo_bringup resolves a topology into plan.json for static type/QoS checks, but it currently requires pre-collected source-metadata sidecars (record.json + per-pkg _metadata/*.json). The automatic metadata-build path (nros metadata --build) is not yet wired for lib-only Node pkgs, so nros plan does not produce a plan straight from this template. See packages/testing/nros-tests/fixtures/orchestration_e2e/ for the pre-collected-sidecar pipeline.

The canonical template README at examples/workspaces/rust/README.md is the source of truth for the current CLI state.

Runnable copy-out

examples/workspaces/rust/ is the canonical Rust 3-role workspace that pairs with this guide. Copy the whole directory out and rename the packages. nros ws sync materializes generated message crates, nros codegen-system bakes the Bringup package, and cargo build -p native_entry builds the Entry pkg.

The workspace README at examples/workspaces/rust/README.md documents the exact CLI commands that are verified green today.

When you don’t need a Bringup pkg

If you have a single Entry pkg and don’t plan to share the topology across multiple boards, fold launch/ and system.toml directly into the Entry pkg. The nros::main! macro accepts a launch = argument that names the bringup package:

#![allow(unused)]
fn main() {
// Multi-node: reads launch/system.launch.xml from demo_bringup
nros::main!(launch = "demo_bringup");

// Explicit file within a bringup pkg
nros::main!(launch = "demo_bringup:sim.launch.xml");
}

If the launch files live inside the Entry pkg itself, point at it by name. The Entry package page covers this in full.

Where to go next

• Entry packages — the nros::main! macro and native_entry
• Role reference — full reference for all three roles
• Project layout — start here if you haven’t read it yet

Entry packages

An Entry pkg is the binary that boots a topology on a specific board. Where a Node pkg is a library (no fn main) and a Bringup pkg is purely declarative, the Entry pkg is the one thing that actually runs: it names a board, wires the runtime, and — for multi-node setups — points at a Bringup pkg that describes which nodes should be launched.

You have one Entry pkg per deploy target. A workspace targeting both a native workstation and an STM32F4 board has two Entry pkgs that reference the same Node pkgs; only the board and (optionally) the launch target differ.

Prereqs

Pick one path from a fresh checkout — just is NOT a prereq.

A. Bare machine (no Rust, no just, no cargo):

./scripts/bootstrap.sh base

Installs rustup, just, builds the in-tree nros CLI at packages/cli/target/release/nros, leaves the binary on PATH for this shell.

B. Already have cargo (most contributors):

cargo build --release --manifest-path packages/cli/Cargo.toml --bin nros
export PATH="$PWD/packages/cli/target/release:$PATH"

C. Tagged release, no Rust at all:

./scripts/install-nros-prebuilt.sh

Downloads the matching nros-<triple>.tar.gz from the GitHub release, sha256-verifies, installs to packages/cli/target/release/nros.

Every subsequent shell sources the workspace env via one of:

direnv allow                  # if you use direnv
source ./activate.sh          # bash / zsh
source ./activate.fish        # fish

Then provision the native host (the canonical first Entry pkg target; for STM32F4 / Zephyr / ESP32 swap in the matching nros setup board):

nros setup native --rmw zenoh

Package layout

src/native_entry/
├── package.xml
├── Cargo.toml           # [[bin]] + deps on node pkgs + board crate
│                        # + [package.metadata.nros.entry]
└── src/main.rs          # nros::main!(launch = "demo_bringup");

No library code lives here. The Entry pkg links the Node pkg rlibs and hands them to the runtime that nros::main!() generates.

Cargo.toml metadata

The [package.metadata.nros.entry] table tells the CLI which deploy target this binary is built for. The embedded example examples/stm32f4/rust/talker-embassy/ uses:

[package.metadata.nros.entry]
deploy = "embassy-stm32f4"

A native Entry pkg that references a Bringup pkg looks like:

[package.metadata.nros.entry]
deploy = "native"

[package.metadata.nros.deploy.native]
board     = "posix"
rmw       = "zenoh"
domain_id = 0

deploy is the key that nros check and the Entry macro use to find the board crate and verify the topology. Keep it short and descriptive — it becomes the identifier in nros plan output and in system.toml’s [deploy.<name>] table when you later add a Bringup pkg.

nros::main!() — four forms

#![allow(unused)]
fn main() {
// 1. Single-node self-bringup: reads [package.metadata.nros.entry] deploy
//    from Cargo.toml and boots the Node pkg that is the only member of
//    this workspace (or the one marked default).
nros::main!();

// 2. Single-node, explicit board type.
nros::main!(board = NativeBoard);

// 3. Multi-node: reference a Bringup pkg; boot its default launch file
//    (the one listed under [system] in system.toml).
nros::main!(launch = "demo_bringup");

// 4. Multi-node, explicit launch file.
nros::main!(launch = "demo_bringup:sim.launch.xml");

// 5. Full form: board + launch file + runtime arg overrides.
nros::main!(board = NativeBoard, launch = "demo_bringup:sim.launch.xml", args = [("use_sim","true")]);
}

The macro reads [package.metadata.nros.entry] at compile time to select the right board and executor backend. On Embassy / RTIC targets it emits the framework-specific #[embassy_executor::main] or #[rtic::app] body so your src/main.rs stays a single line.

The real examples/stm32f4/rust/talker-embassy/src/main.rs collapses to exactly this:

#![allow(unused)]
#![no_std]
#![no_main]

fn main() {
use defmt_rtt as _;
use panic_probe as _;

nros::main!();
}

Escape hatch

If you need more control than the macro provides — custom startup ordering, hardware init before the runtime, or a fully manual executor loop — you can bypass nros::main!():

#![allow(unused)]
fn main() {
// Option A: delegate init to the board crate, supply your own closure.
<NativeBoard as BoardEntry>::run(|runtime| {
    let node = runtime.create_node("talker", "/", &Default::default())?;
    // ...
    Ok(())
});

// Option B: fully manual — no board crate.
let executor = nros::Executor::open(&ExecutorConfig::default())?;
// wire nodes, spin manually ...
}

Option A is the right choice when you need to run something before the first spin (e.g. DMA setup, flash unlock). Option B is there for board-bringup authors adding a new platform.

Running a native Entry pkg

The verified path for the canonical Rust workspace is cargo run -p native_entry. Start a Zenoh router first, then boot the Entry binary from the workspace root:

# in another shell:
zenohd --listen tcp/127.0.0.1:7447 &

cargo run -p native_entry

native_entry opens the executor against the router, registers talker + listener (composed into a single process), and runs the topology.

The canonical Rust workspace is at examples/workspaces/rust/. For Zephyr, QEMU, ESP-IDF, and other non-native targets, use the platform’s native build/run tool or the focused just <plat> run recipe.

Running on Zephyr

On Zephyr the RTOS framework is the workflow: west build is the build verb, Kconfig selects the RMW, and the Entry is an ordinary Zephyr application. There is no nros build / nros launch build path here, and you do not type the RMW as a Cargo --features flag or bake the board into the package.

source ./activate.sh

# Provision message bindings once. This is platform-agnostic workspace
# provisioning (sibling to `west update` / `rosdep`), NOT a compile step —
# the same `nros ws sync` output feeds every board and every RMW.
nros ws sync

# west is the build verb. Choose the board with `-b`, and select the RMW with
# the matching Kconfig overlay via -DCONF_FILE. The Entry source never changes.
west build -b native_sim/native/64 src/zephyr_entry \
    -- -DCONF_FILE="prj.conf;prj-zenoh.conf"

west build -t run            # native_sim; `west flash` for hardware

Swap -b native_sim/native/64 for any other Zephyr board (-b nrf52840dk/nrf52840, -b stm32f4_disco, …) and prj-zenoh.conf for prj-xrce.conf / prj-cyclonedds.conf to pick a different RMW — nothing else changes. One Zephyr Entry pkg (src/zephyr_entry/) covers every Zephyr board: unlike the board-specific FreeRTOS / ThreadX Entries, Zephyr owns its board abstraction, so the board is chosen at west build -b time rather than baked into the package (see One Entry pkg per board).

The Entry source is identical to the native, FreeRTOS, and ThreadX Entries — the same one-line launch macro, with the launch file as the single source of truth for the node set:

#![allow(unused)]
fn main() {
// examples/workspaces/rust/src/zephyr_entry/src/lib.rs
nros::main!(launch = "demo_bringup:system.launch.xml");
}

One Entry pkg per board

Each deploy target gets its own Entry pkg. A workspace that runs on both native and embassy-stm32f4 would have two Entry pkgs that share the same Node pkg library:

Both reference the same talker_pkg and listener_pkg Node pkg rlibs. The board crate provides the BoardEntry impl and any hardware-specific initialisation; the Node pkgs are board-agnostic.

Zephyr is the exception — one Entry per RTOS, not per board. Zephyr already owns its board abstraction, so a single zephyr_entry covers native_sim, nrf52, stm32, aemv8r, … with the board chosen at west build -b <board> time. Contrast FreeRTOS / ThreadX, whose board crates are board-specific, so each of those Entries bakes one board. See Running on Zephyr.

The examples/stm32f4/rust/talker-embassy/ example demonstrates the embedded shape: deploy = "embassy-stm32f4" + nros::main!(); on a no_std / no_main binary that delegates everything to the EmbassyStm32F4 board crate.

C / C++ Entry packages

C and C++ Entry packages use the same role split through CMake. See C / C++ multi-node workspaces.

Where to go next

• Role reference — full reference for all three roles.
• Bringup packages — the system.toml + launch XML that an Entry pkg points at.
• Node packages — the Node pkgs your Entry pkg links.
• Project layout — the full 3-role picture and when to use it.

C / C++ multi-node workspaces

The four previous chapters (project layout, node packages, bringup packages, entry packages) describe the canonical three-role node + bringup + entry shape against the Rust path (nros::node!(…) + nros::main!(launch = …)). This chapter shows the C and C++ path through the same shape, role-for-role.

Phase 219 closed the parity gap. Same launch.xml, same package.xml, same system.toml, same workspace pkg-index — the only thing that changes language-side is the cmake-fn / macro surface.

TL;DR — side-by-side

The reference C++ workspace ships in-tree at examples/workspaces/cpp/. Copy the whole directory, rename the packages.

Workspace layout

Identical structure to the Rust template, swapping Cargo.toml → CMakeLists.txt:

my_ws/
├── CMakeLists.txt                # nano_ros_workspace(SUBDIRS …)
└── src/
    ├── talker_pkg/               # Node pkg (C++)
    │   ├── package.xml
    │   ├── CMakeLists.txt        # nano_ros_node_register(…)
    │   └── src/{Talker.hpp,Talker.cpp}
    ├── listener_pkg/             # Node pkg (C++)
    │   ├── package.xml
    │   ├── CMakeLists.txt
    │   └── src/{Listener.hpp,Listener.cpp}
    ├── demo_bringup/             # Bringup pkg (language-agnostic — copy/paste
    │   ├── package.xml           #          works between Rust and C++ workspaces)
    │   ├── system.toml
    │   └── launch/system.launch.xml
    └── native_entry/             # Entry pkg (C++)
        ├── package.xml
        ├── CMakeLists.txt        # nano_ros_entry(LAUNCH …)
        └── src/main.cpp          # NROS_MAIN(…) one-liner

Workspace root

Four declarations:

cmake_minimum_required(VERSION 3.22)
project(my_ws LANGUAGES C CXX)
include(<nano-ros>/cmake/NanoRosWorkspace.cmake)

nano_ros_workspace(
    BACKEND        zenoh                # zenoh | xrce | cyclonedds
    PLATFORM       posix                # posix | … (default posix)
    NANO_ROS_ROOT  <path-to-nano-ros>   # also: -D cache var, $NANO_ROS_ROOT,
                                        # or auto-walk for nros-sdk-index.toml
    SUBDIRS        src/talker_pkg
                   src/listener_pkg
                   src/native_entry
)

nano_ros_workspace() (Phase 219.I) does the heavy lifting in one call:

1. Sets NANO_ROS_PLATFORM=posix + NANO_ROS_RMW=zenoh.
2. add_subdirectory(<nano-ros>) once at root scope (so per-pkg subdirs don’t collide on re-include).
3. include(NanoRosNodeRegister.cmake) + include(NanoRosEntry.cmake) once.
4. add_subdirectory(<each member>) for each SUBDIRS entry.

Subdir CMakeLists begin with the dual call:

nano_ros_workspace_pkg_guard()  # no-op inside a workspace; bootstraps standalone solo

— the cmake equivalent of cargo [workspace] discipline. Every member compiles standalone (with -DNANO_ROS_ROOT=<path>) or as part of the workspace; the per-pkg CMakeLists doesn’t change between modes.

Node pkg

A typed component (RFC-0043) — no main(). The pkg ships a class with a configure(::nros::Node&) method that creates real entities (a Publisher, a Timer) and binds member callbacks by identity (member-fn-pointer template param, no string callback name, no interpreter). The Entry pkg constructs the object and calls configure(node); the executor dispatches the callbacks.

# src/talker_pkg/CMakeLists.txt
cmake_minimum_required(VERSION 3.22)
project(talker_pkg LANGUAGES C CXX)
nano_ros_workspace_pkg_guard()
nros_find_interfaces(LANGUAGE CPP SKIP_INSTALL)

nano_ros_node_register(
    NAME    talker
    CLASS   talker_pkg::Talker     # §212.L.4 — class prefix must equal PROJECT_NAME
    SOURCES src/Talker.cpp)

target_link_libraries(talker_pkg_talker_component PUBLIC std_msgs__nano_ros_cpp)

// src/talker_pkg/include/talker_pkg/Talker.hpp
#pragma once
#include <nros/component.hpp>
#include <nros/nros.hpp>
#include "std_msgs.hpp"

namespace talker_pkg {

class Talker {
    ::nros::Publisher<std_msgs::msg::Int32> pub_;
    ::nros::Timer timer_;
    int count_ = 0;

    void on_tick();  // real body; bound via &Talker::on_tick (no name)

  public:
    ::nros::Result configure(::nros::Node& node);
};

}  // namespace talker_pkg

// src/talker_pkg/src/Talker.cpp
#include "talker_pkg/Talker.hpp"

namespace talker_pkg {

void Talker::on_tick() {
    std_msgs::msg::Int32 m;
    m.data = count_++;
    (void)pub_.publish(m);
}

::nros::Result Talker::configure(::nros::Node& node) {
    ::nros::Result r = node.create_publisher(pub_, "/chatter");
    if (!r.ok()) return r;
    // Member-fn-pointer-as-template-param → no-alloc trampoline; `this` is ctx.
    return ::nros::bind_timer<Talker, &Talker::on_tick>(node, timer_, 1000, this);
}

}  // namespace talker_pkg

The Entry pkg constructs Talker in static storage and calls configure(node) on the real executor — the same component model the Rust nros::node!(Talker) + the C NROS_C_COMPONENT paths use, so C++, C, and Rust Node pkgs interoperate in one launch graph.

Scaffold a C++ Node pkg with:

$ nros new --component my-talker --lang cpp --use-case talker
✓ Created nano-ros C++ Node pkg 'my-talker'
  Class     : my_talker::Talker
  Node      : talker
  Kind      : typed component (RFC-0043)

Bringup pkg

Language-agnostic — copy verbatim from the bringup chapter. package.xml + system.toml + launch/system.launch.xml. No Cargo.toml, no CMakeLists.txt. Stock ROS 2 launch.xml from nav2 / Autoware / turtlebot3 pastes in modulo unsupported tags.

<!-- src/demo_bringup/launch/system.launch.xml -->
<launch>
  <node pkg="talker_pkg" exec="talker" name="talker"/>
  <node pkg="listener_pkg" exec="listener" name="listener"/>
</launch>

Entry pkg

The C++ Entry pkg’s CMakeLists.txt calls nano_ros_entry(LAUNCH …) — Phase 219.D added the LAUNCH keyword:

# src/native_entry/CMakeLists.txt
cmake_minimum_required(VERSION 3.22)
project(native_entry LANGUAGES C CXX)
nano_ros_workspace_pkg_guard()

nano_ros_entry(
    NAME    native_entry
    SOURCES src/main.cpp                              # user-authored
    LAUNCH  "demo_bringup:system.launch.xml"          # Phase 219.D
    DEPLOY  native)

At configure time the cmake fn shells nros codegen entry --lang cpp --typed, emits ${CMAKE_BINARY_DIR}/native_entry_nros_main_generated.cpp (the canonical int main() body that constructs each launch node’s component + calls configure(node) on the real executor via NativeBoard::run_components), appends it to the target’s sources, and auto-links every <pkg>_<exec>_component static lib the launch XML named (Phase 219.J). The user’s main.cpp is a single declarative line:

// src/native_entry/src/main.cpp
#include <nros/main.hpp>
NROS_MAIN(nros::board::NativeBoard, "demo_bringup:system.launch.xml")

NROS_MAIN(...) is a sentinel macro — the cmake fn owns the generated body, the user’s TU is documentation + IDE hint.

nros new scaffolds an Entry pkg:

$ nros new my-entry --lang cpp --platform native

Build + boot

nros ws sync
nros codegen-system --bringup demo_bringup
cmake -S . -B build -DNANO_ROS_ROOT=<path-to-nano-ros>
cmake --build build
./build/src/native_entry/native_entry

The build produces:

• src/talker_pkg/libtalker_pkg_talker_component.a — the Node pkg static lib (_component is the compatibility target suffix).
• src/listener_pkg/liblistener_pkg_listener_component.a — ditto.
• src/native_entry/native_entry — the Entry exe, with the generated int main() + register-call sequence + Board boot stub linked in.

cmake configure is incremental — pinned CMAKE_CONFIGURE_DEPENDS on every file nros codegen entry reads (depfile from the CLI), so any launch.xml / package.xml / Node pkg edit re-runs codegen.

What runs where

Same partition as the Rust track — the only thing that changes is the syntax the user types into the three pkgs.

C / C++ scaffolding via nros new

The C-side compatibility scaffold (nros new --component … --lang c) is available for pure-C Node pkgs. Pure-C and mixed C/C++ workspace examples live under examples/workspaces/.

See also

• examples/workspaces/cpp/ — the canonical reference workspace (talker + listener Node pkgs + Bringup pkg + Entry pkg, all C++).
• Phase 219 roadmap — full landing order + acceptance bar.
• Multi-node workspace layout design §11 — LOCKED canonical shape (Bringup + Node + Entry).

Mixed-language workspace

nano-ros Node pkgs are linked through a C ABI register trampoline, so one Entry pkg can host Node pkgs written in different languages. The native reference shape is:

• C Node pkg for C code you want to keep in C.
• C++ Entry pkg for the boot harness and generated launch wiring.
• Optional C++ Node pkgs in the same workspace.
• One Bringup pkg with the normal ROS 2 launch XML.

The mixed workspace is in examples/workspaces/mixed/. For a pure-C Entry host, use examples/workspaces/c/.

Layout

my_ws/
├── CMakeLists.txt
└── src/
    ├── c_talker_pkg/             # C Node pkg
    ├── cpp_listener_pkg/         # C++ Node pkg
    ├── demo_bringup/             # launch XML + system.toml
    └── native_entry/             # C++ Entry pkg

The root uses the same CMake workspace helper as the C++ track:

include(<nano-ros>/cmake/NanoRosWorkspace.cmake)

nano_ros_workspace(
    BACKEND  zenoh
    PLATFORM posix
    SUBDIRS  src/c_talker_pkg
             src/cpp_listener_pkg
             src/native_entry)

C Node pkg

A C Node pkg is a typed component (RFC-0043): no main(). It defines a state struct + a configure(node, executor, self) function and exports the C-ABI factory/configure seam via NROS_C_COMPONENT(StateT, configure_fn) — the typed Entry creates the node and runs configure on the real executor.

# Raw `/chatter` publisher carries the type name as a string → no generated C
# bindings needed (so no nros_find_interfaces for this pkg).
nano_ros_node_register(
    NAME     talker
    CLASS    c_talker_pkg::Talker
    LANGUAGE C
    TYPED
    SOURCES  src/Talker.c
    DEPLOY   native)

#include <stdint.h>
#include <nros/component.h>

typedef struct {
    _Alignas(8) uint8_t pub[NROS_C_PUBLISHER_STORAGE_SIZE];
    int32_t count;
} c_talker_pkg_t;

static void on_tick(void* ctx) {
    c_talker_pkg_t* self = (c_talker_pkg_t*)ctx;
    uint8_t buf[8] = {0x00, 0x01, 0x00, 0x00};  /* CDR_LE header + LE int32 */
    buf[4] = (uint8_t)self->count;
    (void)nros_cpp_publish_raw(self->pub, buf, sizeof(buf));
    self->count++;
}

static nros_ret_t talker_configure(const nros_cpp_node_t* node, void* executor,
                                   c_talker_pkg_t* self) {
    self->count = 0;
    int32_t rc = nros_cpp_publisher_create(node, "/chatter",
        "std_msgs::msg::dds_::Int32_", "", nros_c_qos_default(), self->pub);
    if (rc != 0) return rc;
    size_t timer;
    return nros_cpp_timer_create(executor, /*period_ms=*/1000, on_tick, self, &timer);
}

NROS_C_COMPONENT(c_talker_pkg_t, talker_configure)

nano_ros_node_register(... LANGUAGE C TYPED ...) injects NROS_PKG_NAME, so NROS_C_COMPONENT exports the __nros_c_component_<pkg>_{create,configure} seam the typed Entry calls — interoperable with C++ configure(Node&) and Rust nros::node! components in one launch graph.

Entry pkg

Use a C++ or Rust Entry pkg as the usual host for migration work. In the C++ template:

nano_ros_entry(
    NAME    native_entry
    SOURCES src/main.cpp
    BOARD   native
    LAUNCH  "demo_bringup:system.launch.xml"
    DEPLOY  native)

The launch file names both Node pkgs:

<launch>
  <node pkg="c_talker_pkg" exec="talker" name="talker"/>
  <node pkg="cpp_listener_pkg" exec="listener" name="listener"/>
</launch>

The generated Entry translation unit calls each package’s __nros_component_<pkg>_register symbol and the CMake sidecar links the matching static libraries. The symbol keeps the legacy component spelling for ABI compatibility; the user-facing package role is still Node pkg.

For a pure-C workspace, the Entry pkg uses the same launch-driven shape with LANG c:

nano_ros_entry(
    NAME    native_entry
    SOURCES src/main.c
    BOARD   native
    LAUNCH  "demo_bringup:system.launch.xml"
    LANG    c
    DEPLOY  native)

Scaffolding

# Current compatibility scaffold for Node pkgs:
nros new --component c_talker_pkg --lang c --use-case talker
nros new --component cpp_listener_pkg --lang cpp --use-case listener
nros new system demo_bringup --components c_talker_pkg,cpp_listener_pkg

For a complete working tree, copy the template instead of creating each package separately.

Role Reference: Node, Bringup, and Entry Packages

nano-ros multi-node workspaces split into three kinds of package:

• Node pkg — a reusable, board-agnostic node library. Defines what a node does (publishers, subscribers, timers, services, actions) and registers itself with the nros::node!(T) macro. No main(), no board pick, no deploy config. (Previously called a component package; renamed to Node pkg to match ROS 2 composable-node naming.)
• Bringup pkg — pure declarative: owns the launch topology and per-target deploy config. Contains a package.xml, system.toml, launch/*.launch.xml, and optional config/. No Cargo.toml, no compiled code. Named <system>_bringup. Optional — only required when ≥2 Entry pkgs share one topology; a single-Entry workspace folds launch/ + system.toml into the Entry pkg directly.
• Entry pkg — a per-board binary that composes one or more Node pkgs into a runnable system. Owns the board choice (via the Board trait family), the launch file reference, and the deploy/domain/bridge config. Typically ~30 LoC of main.rs.

The split exists because a node’s logic is portable across boards, but boot + transport + deploy config is not. One Node pkg can be reused across native POSIX, FreeRTOS, and Zephyr targets by writing one Entry pkg per target.

single-Node convenience: for a single-Node workspace on native hosts, a Node pkg can declare [package.metadata.nros.entry] deploy = "<board>" in its own Cargo.toml and skip the Entry pkg directory entirely — see Single-Node-pkg convenience below. Embedded boards still need a hand-written Entry pkg.

Node pkg

A Node pkg is a normal Rust library (or C++ static library) with a few nano-ros-specific knobs:

src/talker_pkg/
├── Cargo.toml          # [lib] crate-type = ["rlib", "staticlib"]
│                       # [package.metadata.nros.node]
│                       #     class = "talker_pkg::Talker"
├── package.xml         # ROS 2 package manifest (<exec_depend> etc.)
├── src/
│   └── lib.rs          # impl Node for Talker { … }
│                       # nros::node!(Talker);
└── launch/             # OPTIONAL — per-node launch fragment
    └── talker.launch.xml

src/lib.rs declares the user class, implements Node + ExecutableNode (init / on_callback / optional tick), and ends with nros::node!(Talker); to emit the register trampoline. Codegen owns the spin loop — your code only describes what the node has and what its callbacks do.

Key rules:

• No fn main(). A Node pkg builds as rlib + staticlib and is linked into an Entry pkg’s binary. Codegen synthesises the spin driver; you never hand-write one.
• class field must start with the pkg dir name. nros check rejects class = "foo::Talker" inside src/talker_pkg/ — the pkg name and the class prefix are the same identity. (Phase 212.L.4.)
• C++ / C analogue: nano_ros_node_register(NAME … CLASS … SOURCES …) cmake fn + a typed component in the source — C++ a configure(::nros::Node&) method, C a NROS_C_COMPONENT(StateT, configure_fn) seam (RFC-0043). Same conceptual shape, no Cargo.toml.
• package.xml is mandatory. Even pure-Rust Node pkgs ship one — <exec_depend> lines drive ROS 2 launch discovery when the system runs through ros2 launch outside the nano-ros toolchain.

Bringup pkg (optional)

A Bringup pkg is pure declarative — it owns the launch topology and per-target deploy config, and contains no compiled code:

src/demo_bringup/
├── package.xml          # <name>demo_bringup</name>, <exec_depend> per node
├── system.toml          # [system] + [[component]] + [deploy.<target>] (+ [[domain]]/[[bridge]])
├── launch/
│   └── system.launch.xml   # ROS 2 launch schema, verbatim
└── config/                 # optional — params.yaml, etc.

No Cargo.toml, no CMakeLists.txt, no src/. Naming convention <system>_bringup (alias <system>_launch), matching nav2 / Autoware / turtlebot3. It is optional: required only when two or more Entry pkgs share one topology. A single-Entry workspace folds launch/ + system.toml into the Entry pkg directly.

launch/*.launch.xml is the ROS 2 launch schema verbatim — <launch>, <arg>, <node>, <param>, <remap>, <group>, <include>, with $(find <pkg>) / $(var) / $(env) substitutions. Stock nav2/Autoware XML pastes in and Just Works (Python .launch.py is not supported yet). See the workspace bringup tutorial.

Entry pkg

An Entry pkg is a binary crate that combines one or more Node pkgs with a board choice, a launch file, and per-board deploy config:

src/robot_entry/
├── Cargo.toml          # [[bin]] name = "robot_entry"
│                       # [dependencies]
│                       #     talker_pkg   = { path = "../talker_pkg" }
│                       #     listener_pkg = { path = "../listener_pkg" }
│                       #     nros-board-posix = { … }            # or another family
│                       # [package.metadata.nros.entry]
│                       #     deploy = "native"
│                       # [package.metadata.nros.deploy.native]
│                       #     board     = "posix"
│                       #     rmw       = "zenoh"
│                       #     domain_id = 0
│                       #     locator   = "tcp/127.0.0.1:7447"
├── package.xml         # <exec_depend>talker_pkg</exec_depend>, listener_pkg, …
└── src/
    └── main.rs         # one line: `nros::main!(launch = "demo_bringup");`

The nros::main!() proc-macro (Phase 212.N.9) reads the launch file at compile time, walks the workspace pkg-index for each <node pkg=…> entry, and expands to a fn main() that delegates to <Board as BoardEntry>::run(...), dispatching one <pkg>::register(runtime)? call per launch row. The macro has four forms; pick whichever matches your composition shape:

nros::main!();                                          // single-node self-bringup (reads [..nros.entry] deploy)
nros::main!(board = NativeBoard);                       // single-node, explicit board
nros::main!(launch = "demo_bringup");                   // multi-node, default launch from system.toml
nros::main!(launch = "demo_bringup:sim.launch.xml");    // multi-node, explicit file
nros::main!(                                            // all explicit
    board  = NativeBoard,
    launch = "demo_bringup:sim.launch.xml",
    args   = [("use_sim", "true")],
);

Form-1 (no args) reads [package.metadata.nros.entry] deploy = "<board>" from this Entry pkg’s own Cargo.toml and maps the board key ("native"/"freertos"/"zephyr"/…) to the right board crate via a small lookup table. Forms 2–4 use the user-supplied path verbatim. Forms 3/4 reference a Bringup pkg by <bringup>[:<file>] — the Bringup pkg’s dir hosts launch/<file>.launch.xml plus an optional system.toml naming the default file ([system] default_launch = "..."). The nros::main!() expansion replaces the older build.rs + include!(env!("OUT_DIR")/run_plan.rs) shape end-to-end; new Entry pkgs no longer need a build.rs or a nros-build build-dep — just nros + the target board crate.

Escape hatch: skip the macro entirely and call <NativeBoard as BoardEntry>::run(|runtime| { ... }), or go fully manual with nros::Executor::open(&ExecutorConfig::default()).

Key rules:

• One Entry pkg per board target. Want to run the same nodes on native POSIX, on a QEMU-MPS2-AN385 FreeRTOS target, and on a real ThreadX board? Three Entry pkgs (robot_entry_native, robot_entry_qemu_freertos, robot_entry_acme_threadx) sharing the same Node pkgs and (usually) the same launch/system.launch.xml via symlink or <include>.
• launch/system.launch.xml is the canonical name. nros plan resolution order: --file <path> → <dir>/launch/<pkg>.launch.xml → <dir>/launch/system.launch.xml → the single <dir>/launch/*.launch.xml → synth (only for non-Entry, single-Node pkgs).
• Deploy config lives in Cargo.toml. [package.metadata.nros.deploy.<target>] holds board / RMW / domain / locator per target; [[package.metadata.nros.domain]] and [[package.metadata.nros.bridge]] carry multi-domain topology.
• C++ analogue: cmake fn nano_ros_entry(NAME <name> LANGUAGE CXX LAUNCH …) plus NROS_MAIN(...). Metadata flows through ${BUILD}/nros-metadata.json rather than a sidecar TOML.

Workspace shape

A typical multi-Node workspace, with one Entry pkg per supported board:

my_ws/
├── Cargo.toml          # [workspace] members = ["src/talker_pkg", "src/listener_pkg", "src/robot_entry"]
│                       # [workspace.metadata.nros] default_system = "demo_bringup"
└── src/
    ├── talker_pkg/         # Node pkg (lib, nros::node!)
    ├── listener_pkg/       # Node pkg
    ├── demo_bringup/       # Bringup pkg (declarative; no Cargo.toml)
    └── robot_entry/        # Entry pkg (bin, nros::main!(launch = "demo_bringup"))

cargo build at the workspace root builds everything via cargo’s native scheduler. nros plan reads [workspace.metadata.nros] default_system to pick the Entry pkg (or you pass nros plan robot_entry explicitly).

For C++-majority or mixed workspaces, CMake is the top-level driver instead — see the multi-node workspace design doc.

Single-Node-pkg convenience (cargo run Just Works)

For tiny fixtures and host-side dev loops, a Node pkg can declare itself as its own Entry pkg by adding [package.metadata.nros.entry] deploy = "<board>" to its Cargo.toml, alongside the usual [package.metadata.nros.node] and [package.metadata.nros.deploy.<target>] tables. src/main.rs collapses to one line:

// src/main.rs
nros::main!();

The macro reads deploy = "<board>" from this pkg’s own Cargo.toml, maps it to the right board crate, and emits fn main() + <this_pkg>::register(runtime)?; — the latter resolves through the companion src/lib.rs cargo auto-wires alongside the binary target. No build.rs, no launch file (one is synthesised in-memory), no hand-written boot glue. This is the L.7 self-entry planner path (Phase 212.L.7 + N.5 + N.9).

Limits of the convenience:

• Native only. Embedded boards (FreeRTOS, ThreadX, Zephyr, bare-metal) still require a hand-written Entry pkg — board init is non-trivial enough that hiding it behind a one-liner does more harm than good.
• One Node. Two or more Node pkgs in the same workspace = author an Entry pkg. The point of the convenience is to skip ceremony for tiny single-node fixtures, not to grow into a multi-node composition root.

Quick reference

FreeRTOS (QEMU MPS2-AN385)

Single-node starter on FreeRTOS + lwIP, cross-compiled for Cortex-M3 and booted in QEMU MPS2-AN385. Slirp networking; no host TAP / bridge / sudo. Rust, C, and C++ talkers all live in-tree.

Prereqs. nros setup qemu-arm-freertos is the single command that prepares your machine for this board. It fetches a prebuilt toolchain set into the shared store at ~/.nros/sdk — the arm-none-eabi-gcc cross-compiler, the patched qemu-system-arm emulator, the FreeRTOS kernel + lwIP sources, and the RMW host daemon. You do not hand-install a cross-toolchain and you do not need a ROS 2 install.

Setup

Build the in-tree nros CLI (Phase 218):

source ./activate.sh        # OR: direnv allow / source ./activate.fish
just setup-cli              # builds packages/cli/target/release/nros

Then provision the board (--rmw defaults to zenoh; pick xrce or cyclonedds to match the example you intend to run):

nros setup qemu-arm-freertos --rmw zenoh

This fetches the cross-compiler, the patched qemu-system-arm, the FreeRTOS + lwIP sources, and the RMW host daemon (zenohd for zenoh, the Micro-XRCE-DDS agent for xrce) into ${NROS_HOME:-~/.nros}/sdk.

Project layout

Each language uses the standard nano-ros canonical example shape — standalone Cargo (Rust) or CMake (C / C++) project under examples/qemu-arm-freertos/<lang>/<example>/.

examples/qemu-arm-freertos/
├── rust/talker/             # Cargo package, cross-compile target = thumbv7m-none-eabi
│   ├── Cargo.toml
│   ├── .cargo/config.toml          # target + QEMU runner
│   ├── nros.toml                   # network + zenoh locator + scheduling
│   ├── package.xml
│   ├── generated/                  # codegen output — build.rs runs
│   │                               #   `nros generate-rust` on first
│   │                               #   `cargo build`; gitignored.
│   └── src/main.rs
├── c/talker/                 # CMake project, add_subdirectory consumption
│   ├── CMakeLists.txt
│   ├── nros.toml
│   ├── package.xml
│   └── src/main.c
└── cpp/talker/               # CMake C++14 project
    ├── CMakeLists.txt
    ├── nros.toml
    ├── package.xml
    └── src/main.cpp

The Rust Cargo.toml pulls the FreeRTOS board crate (nros-board-mps2-an385-freertos) which wraps the kernel + lwIP + LAN9118 driver build. The C / C++ CMakeLists.txt follows the canonical add_subdirectory(<repo-root>) + nano_ros_link_rmw(<target> RMW zenoh) pattern with NANO_ROS_BOARD = mps2-an385-freertos.

Configure

Network + Zenoh + scheduling live in nros.toml (parsed by the board crate at boot). Verbatim from the in-tree examples/qemu-arm-freertos/rust/talker/nros.toml:

# nano-ros config (direct mode). See
# docs/design/0004-configuration-and-transports.md.

[node]
domain_id = 0

[[transport]]
kind    = "ethernet"
ip      = "10.0.2.20/24"
mac     = "02:00:00:00:00:00"
gateway = "10.0.2.2"
locator = "tcp/10.0.2.2:7451"

[node.rt]
app_priority = 12
app_stack_bytes = 262144
zenoh_read_priority = 16
zenoh_read_stack_bytes = 5120
zenoh_lease_priority = 16
zenoh_lease_stack_bytes = 5120
poll_priority = 16
poll_interval_ms = 5

The 10.0.2.0/24 subnet is QEMU Slirp’s default; 10.0.2.2 is the Slirp gateway that forwards to host loopback. No TAP, no sudo.

Per-language test-fixture ports: Rust → 7451, C → 7551, C++ → 7651. The talker / listener under each <lang>/ uses the matching port; start zenohd on the one you intend to test against. The C / C++ example trees ship their own nros.toml with the matching port.

Build

# Rust:
cd examples/qemu-arm-freertos/rust/talker
cargo build --release

# C / C++ — use the cross-toolchain CMake invocation:
just freertos build-fixtures        # builds every in-tree zenoh +
                                    # DDS example across Rust / C / C++
# Or single-example (the `nros` CLI on PATH auto-resolves the codegen
# tool — no `-D_NANO_ROS_CODEGEN_TOOL=` needed):
toolchain="$(pwd)/cmake/toolchain/arm-freertos-armcm3.cmake"
cd examples/qemu-arm-freertos/c/talker
cmake -B build -DCMAKE_TOOLCHAIN_FILE="$toolchain" \
              -DCMAKE_BUILD_TYPE=Release
cmake --build build --parallel

First Rust build pulls + cross-compiles deps (~5 min). C / C++ build also compiles FreeRTOS kernel + lwIP — first run ~3 min.

Run

# 1. Start zenohd on the host (Slirp forwards 10.0.2.2:7451 → host:7451).
#    The just recipe wraps `zenohd --listen tcp/127.0.0.1:7451
#    --no-multicast-scouting` (the D.2 PATH shim resolves zenohd from
#    `~/.nros/sdk/zenohd/<v>/bin/zenohd`):
just freertos zenohd &
# Equivalent, if the recipe isn't available or you want the literal
# invocation (works as long as `zenohd` is on PATH):
zenohd --listen tcp/127.0.0.1:7451 --no-multicast-scouting &

# 2. Boot the talker in QEMU. The just recipe wraps qemu-system-arm
#    with the LAN9118 + Slirp wiring the example expects; works for
#    Rust as well (it builds + boots the in-tree binary):
just freertos talker
# Or, single-language, in the Rust example dir:
cd examples/qemu-arm-freertos/rust/talker
cargo run --release

# 3. Verify from stock ROS 2:
source /opt/ros/humble/setup.bash
export RMW_IMPLEMENTATION=rmw_zenoh_cpp
# Talker publishes best-effort; stock `ros2 topic echo` defaults to
# RELIABLE, so the QoS-mismatched echo silently delivers nothing.
# Force best-effort to receive:
ros2 topic echo /chatter std_msgs/msg/Int32 --qos-reliability best_effort

QEMU exits via Ctrl-A x.

For batch testing without manual QEMU launches: just freertos test runs every E2E (pub/sub, service, action) against a temporary in-test zenohd.

Readiness signal. Within ~20 seconds of QEMU boot, the talker should print Published: 0 on its semihosting stdout (the Rust talker pre-publishes 0 before the first counter bump). QEMU cold-boot through FreeRTOS init + lwIP DHCP + zenoh session open typically takes 10–15 s. If no Published: line in 30 seconds:

1. Confirm zenohd is running on the host (Slirp forwards 10.0.2.2:7451 → host:7451). Without it the talker retries the zenoh handshake until QEMU is killed.
2. Check the talker’s early log for lwIP DHCP timeout or Failed to open session.
3. Bridge tip: ros2 topic echo /chatter from a stock ROS 2 install (with RMW_IMPLEMENTATION=rmw_zenoh_cpp) confirms end-to-end interop.
4. See Troubleshooting — First 10 Minutes.

GitHub source

Canonical, copy-out:

• Rust: examples/qemu-arm-freertos/rust/talker/
• C: examples/qemu-arm-freertos/c/talker/
• C++: examples/qemu-arm-freertos/cpp/talker/

Next

• Subscriber: peer listener/ directory next to each talker.
• Services + actions: peer service-*/ and action-*/ directories.
• Real hardware: same code runs on STM32F4-Discovery / NXP-LPC55S69 / TI-MSP432 with a different board crate + linker script; see the Bare-metal Cortex-M3 page for the no-RTOS variant.
• RTOS-specific debugging: FreeRTOS LAN9118 Debugging.

Zephyr (west module)

Single-node starter on Zephyr via the in-tree zephyr/ west module. nano-ros ships as a Zephyr module — west discovers it from your workspace’s west.yml, drops in a prj.conf Kconfig surface, and the standard west build / west flash flow takes care of the rest.

Contributor path? Building nano-ros’s own Zephyr examples straight from this repository (no west-managed workspace) is covered at Zephyr (contributor). The page below is the canonical user entry.

Just want a working starter? Clone the nano-ros-zephyr-example repo (west init -m …) — a manifest + zenoh talker app pinned to a tested Zephyr, with the same quickstart as below baked in. The steps here explain what it does so you can adapt it to your own workspace.

Prereqs. Run nros setup zephyr --rmw <rmw> once (see Prerequisites below) — it provisions the Zephyr west workspace + Zephyr SDK bits, the emulator, and your RMW’s host daemon into the shared store. No hand-installed Zephyr SDK, west, or cross-toolchain, and no ROS 2 install required. Python: 3.10+ on Zephyr 3.7 LTS, but ≥ 3.12 on Zephyr 4.x (4.x’s find_package(Python3) requires 3.12 — see the version matrix below). nano-ros’s imported west fragment zephyr/west.yml is a manifest-only file — it does NOT pull Zephyr itself; that has to be in your parent manifest (zephyrproject-rtos/zephyr).

Which Zephyr? — 3.7 LTS and 4.x both supported

nano-ros consumes as a module on both the 3.7 LTS line (supported to Jan 2027; the safety-island default) and the current 4.x rolling line. You build against whatever Zephyr your workspace already pins — nano-ros adapts. The two lines differ only in how you select an RMW and apply nano-ros’s Zephyr patches:

native_sim networking uses NSOS (host loopback) on both lines — no TAP/bridge/root. The copy-out, snippet, patch-apply, and dual-line build flows are exercised in CI (just zephyr ci-both, just zephyr check-copy-out).

Project layout

A Zephyr workspace using nano-ros looks like any other Zephyr project — the nano-ros module sits beside Zephyr, your application sits beside both:

my_zephyr_ws/
├── .west/
├── zephyr/                            # cloned by `west init`
├── modules/
│   └── nano-ros/                      # imported via west.yml
└── apps/
    └── my_app/                        # your application
        ├── CMakeLists.txt
        ├── prj.conf                   # Kconfig — selects nros + RMW
        ├── west.yml                   # (optional) per-app manifest
        └── src/
            └── main.c                 # nros user code

The application CMakeLists.txt is a stock Zephyr app — find_package(Zephyr)

• target_sources. No add_subdirectory(<nano-ros>) is needed; the module shell handles it once CONFIG_NROS=y flips on.

A minimal apps/my_app/ looks like this (mirrors examples/zephyr/c/talker/ with the names stripped to the essentials):

# apps/my_app/CMakeLists.txt
cmake_minimum_required(VERSION 3.20.0)
find_package(Zephyr REQUIRED HINTS $ENV{ZEPHYR_BASE})
project(my_app)
target_sources(app PRIVATE src/main.c)

// apps/my_app/src/main.c
#include <nros/nros.h>
#include <nros/publisher.h>
#include <std_msgs/msg/int32.h>

int main(void) {
    nros_init_args_t args = nros_init_args_default();
    nros_context_t ctx;
    nros_init(&args, &ctx);
    nros_node_t node;
    nros_create_node(&ctx, "my_app", &node);
    nros_publisher_t pub;
    nros_create_publisher(&node, std_msgs__msg__Int32_type_support(),
                          "/chatter", &pub);
    std_msgs__msg__Int32 msg = { .data = 0 };
    while (nros_ok(&ctx)) {
        nros_publish(&pub, &msg);
        msg.data++;
        k_sleep(K_SECONDS(1));
    }
    return 0;
}

prj.conf is the one shown in Configure below.

Prerequisites

nros setup provisions the parts nano-ros owns — the RMW host daemon (zenohd / Micro-XRCE-DDS agent) and the RMW transport submodules (zenoh-pico + mbedtls for zenoh, the cyclonedds fork) — from a pinned index into ${NROS_HOME:-~/.nros}/sdk / the nano-ros checkout. It does not replace Zephyr’s own SDK, and interface codegen still needs the ROS message definitions.

1. Build the in-tree nros CLI (Phase 218, from the nano-ros checkout):

   source ./activate.sh        # OR: direnv allow / source ./activate.fish
   just setup-cli              # builds packages/cli/target/release/nros
   

2. Provision the RMW (daemon + transports) from the nano-ros checkout:

   ( cd modules/nano-ros && nros setup zephyr --rmw zenoh )  # zenohd + zenoh-pico + mbedtls
   ( cd modules/nano-ros && nros setup --source px4-rs )     # workspace cargo-load dep
   

3. Install the Zephyr SDK the standard Zephyr way (nros setup does not provide it) and expose it — export ZEPHYR_SDK_INSTALL_DIR=/path/to/zephyr-sdk-<ver> (or register it via the SDK’s setup.sh -c).
4. Message definitions for codegen. The interface codegen resolves a package’s msg/*.msg from NROS_<PKG>_DIR (e.g. export NROS_STD_MSGS_DIR=/opt/ros/humble/share/std_msgs) — point it at a ROS install or any dir holding the .msg files.

The RMW host daemon must be running before an example connects (zenohd -l tcp/127.0.0.1:7456 for zenoh; the Micro-XRCE-DDS agent for xrce).

Configure

Add nano-ros (and a Zephyr pin — zephyr/west.yml is manifest-only; it does not pull Zephyr itself) to your workspace west.yml:

manifest:
  remotes:
    - name: nano-ros
      url-base: https://github.com/NEWSLabNTU
    - name: zephyr
      url-base: https://github.com/zephyrproject-rtos
  projects:
    - name: zephyr
      remote: zephyr
      revision: v3.7.0          # or your chosen 3.7 LTS / 4.x SHA
      path: zephyr
      import: true               # pulls Zephyr's own modules
    - name: nano-ros
      remote: nano-ros
      revision: main             # required — repo's default branch is
                                 # `main`; west defaults to `master`
                                 # otherwise and the fetch fails.
      path: modules/nano-ros
      import:
        file: zephyr/west.yml    # pulls nano-ros's transport deps

Then per-application prj.conf:

CONFIG_NROS=y
CONFIG_NROS_C_API=y
CONFIG_NROS_RMW_ZENOH=y                 # bool per RMW: NROS_RMW_{ZENOH,XRCE,CYCLONEDDS}
# (ROS edition is a build-time Cargo feature, NOT a Kconfig symbol — do not set
#  CONFIG_NROS_ROS_EDITION; Zephyr aborts on the undefined symbol.)

# Required for any networked RMW on QEMU / native_sim:
CONFIG_NETWORKING=y
CONFIG_NET_IPV4=y
CONFIG_NET_TCP=y

CONFIG_NROS=y activates the shell, which maps Kconfig values to NANO_ROS_* CMake cache vars and add_subdirectory()s the root nano-ros CMake. NanoRos::NanoRos is linked into your app library transparently.

Build

If your workspace is a fresh manifest-only dir (no .west/), initialise it first so west knows which west.yml is the manifest:

cd my_zephyr_ws
west init -l .                           # one-time; points west at the
                                         # local west.yml in cwd
west update                              # clones nano-ros + Zephyr into the workspace

(If you started from west init -m <remote>, both calls above are already done — go straight to west build below.)

The transports + px4-rs come from the prerequisites step (west update clones nano-ros but not its submodules). With the Zephyr SDK + NROS_STD_MSGS_DIR exported (also prerequisites), build your app — nros on PATH is auto-resolved as the codegen tool:

# native_sim (POSIX, no QEMU). The 3.7 line needs the NSOS line overlay; apply
# the NSOS patches first (see "apply nano-ros's patches" below).
overlay="$PWD/modules/nano-ros/cmake/zephyr/native-sim-line-3.7.conf"
west build -b native_sim/native/64 apps/my_app -- -DCONF_FILE="prj.conf;$overlay"

# A real board, e.g. Cortex-A9 (no native_sim overlay):
west build -b qemu_cortex_a9 apps/my_app

(Verified end-to-end on a fresh BYO west workspace: this builds to zephyr.exe and runs to Published: 0 against zenohd -l tcp/127.0.0.1:7456. On the 4.4 line, find_package(Python3) requires ≥ 3.12 and you select the RMW with -S nros-zenoh instead of the overlay.)

For a quick sanity check that the module is wired correctly:

west build -t menuconfig                 # confirm CONFIG_NROS=y is visible

Rust applications

Two things differ for a Rust app (C/C++ apps skip this section):

1. The Rust crate’s [lib] must be named rustapp (crate-type = ["staticlib"]) — a zephyr-lang-rust contract: its rust_cargo_application() links librustapp.a. The Cargo package name is free.

2. Generate the interface crates + the [patch.crates-io] wiring for YOUR layout — do not copy an in-repo example’s .cargo/config.toml: its ../../../../packages/core/... paths are repo-relative and break in a copied-out app. From your app dir, run (after the Prerequisites nros setup, which provides the codegen toolchain + message sources):

   nros generate-rust --generate-config \
       --nano-ros-path "$PWD/../../modules/nano-ros/packages/core"
   

   This writes generated/<pkg>/ (the message crates) and a .cargo/config.toml whose [patch.crates-io] points the nros-* crates at your modules/nano-ros/packages/core/* and the generated interfaces at generated/*. Adjust --nano-ros-path to your workspace’s modules/nano-ros/packages/core (the dir holding nros-core, nros-node, …). The example apps’ committed .cargo/config.toml is for the in-tree build only.

Run

# 1. Start zenohd on the host. The in-tree just recipe runs the
#    pinned in-tree zenohd on the zephyr fixture port (7456) — the
#    same port the example apps' `nros.toml` / Kconfig defaults pick
#    up:
just zephyr zenohd &
#    Or directly:
#    zenohd --listen tcp/0.0.0.0:7456 --no-multicast-scouting

# 2. Boot the app. nano-ros's own in-tree zephyr talker has a
#    matching just recipe for the canonical `native_sim` build path:
just zephyr talker
#    For a BYO west workspace + your own app:
# QEMU Cortex-A9:
west build -t run
# native_sim:
./build/zephyr/zephyr.exe

# 3. Verify from stock ROS 2 in another terminal:
source /opt/ros/humble/setup.bash
export RMW_IMPLEMENTATION=rmw_zenoh_cpp
# Talker publishes best-effort; stock `ros2 topic echo` defaults to
# RELIABLE, so the QoS-mismatched echo silently delivers nothing.
# Force best-effort to receive:
ros2 topic echo /chatter std_msgs/msg/Int32 --qos-reliability best_effort

The Zephyr boot banner runs first, then nano-ros prints Published: 0, Published: 1, … as the talker fires — Rust + C + C++ all start at 0 (Phase 208.D.9).

Readiness signal. On native_sim, expect Published: 0 within 5 seconds of just zephyr talker (or ./build/zephyr/zephyr.exe); on qemu_cortex_a9 expect it within ~15 seconds (QEMU cold boot + Zephyr init). If no Published: line in 30 seconds:

1. Confirm CONFIG_NROS=y lit up via west build -t menuconfig; without it the module shell never add_subdirectory’s nano-ros.
2. Check CONFIG_NETWORKING=y, CONFIG_NET_IPV4=y, CONFIG_NET_TCP=y in prj.conf — Zephyr networking is opt-in.
3. Confirm zenohd reachable from the simulated network (Slirp needs 10.0.2.2:7456 on QEMU; native_sim uses host loopback).
4. See Troubleshooting — First 10 Minutes.

Zephyr 4.x build gotchas.

• Could NOT find Python3 ... required is at least "3.12" — 4.x needs Python ≥ 3.12. Provision one without sudo (e.g. uv venv --python 3.12 .venv312 && uv pip install west -r zephyr/scripts/requirements.txt) and run west through it (.venv312/bin/python -m west build ...), so the ROS descriptor-codegen subprocess still uses the system ROS Python.
• attempt to assign the value ... to the undefined symbol ETH_NATIVE_POSIX — that symbol was renamed ETH_NATIVE_TAP in 4.x; the version-aware NSOS overlay handles it (just zephyr build-one does this automatically).

Zephyr 4.x: select the RMW with a snippet

On 4.x, nano-ros ships west snippets so you pick the RMW on the build line instead of hand-writing the overlay:

west build -b native_sim/native/64 -S nros-cyclonedds apps/my_app
#                                   ^^^^^^^^^^^^^^^^^^^  nros-zenoh | nros-cyclonedds | nros-xrce

The snippet (shipped via the module’s snippet_root) carries the RMW-common Kconfig — equivalent to merging prj-<rmw>.conf. The prj-<rmw>.conf / -DCONF_FILE path still works (and is the only option on 3.7).

nano-ros patches into your workspace

nano-ros needs a few patches to Zephyr’s native_sim NSOS driver (recvmsg, IPv4-multicast) so the host-loopback-based examples work. Both supported lines (3.7 LTS and 4.x) take the same path — nros setup zephyr reads zephyr/patches.yml and applies each patch against the workspace’s Zephyr tree, sha256-checked. No extra step on your side beyond the provisioning command (already run during Prerequisites).

To re-apply (e.g. after a west update reset the tree):

nros setup zephyr --rmw zenoh

(Earlier nano-ros revisions documented a west patch apply flow on 4.x — that required a workspace-side west extension that doesn’t ship with stock Zephyr. Phase 208.D.7 / E.9 unified both lines on the provisioner. Cyclone-DDS-on-Zephyr patches stay baked into the pinned cyclonedds submodule, not delivered through patches.yml.)

Copy out an example as your starting point

The examples/zephyr/<lang>/<role>/ dirs are copy-out clean — copy one into your own app tree and it builds against the nano-ros module with no reference back into the nano-ros repo:

cp -r modules/nano-ros/examples/zephyr/c/talker apps/my_app
# cyclonedds examples need the host idlc + the ROS message dirs:
export NROS_STD_MSGS_DIR=/opt/ros/humble/share/std_msgs   # PKG_DIR contract
west build -b native_sim/native/64 -S nros-zenoh apps/my_app

Cyclone idlc and the descriptor-gen scripts are located via the module’s exported cache vars (NROS_CYCLONE_IDLC, NROS_CYCLONE_SCRIPTS_DIR, NROS_CYCLONE_CMAKE_DIR); message-package dirs come from NROS_<PKG>_DIR env (defaulting to /opt/ros/humble/share/<pkg>). No /opt/ros or repo-relative paths are baked into the example.

See the zephyr/ module dir + its Kconfig for the canonical in-repo surface.

GitHub source

• Zephyr module shell: zephyr/
• Worked examples: examples/zephyr/rust/, examples/zephyr/c/, examples/zephyr/cpp/
• Module manifest: zephyr/module.yml
• Kconfig surface (canonical post-Phase-208.D.7 fold — every CONFIG_NROS* symbol the doc cites lives here): zephyr/Kconfig
• Patches applied by nros setup zephyr (the west patch flow on this page was retired in Phase 208.E.9): zephyr/patches.yml

Next

• Pick a real board (Nordic, NXP, STM32, …): swap -b <board> and add a board-specific overlay to your prj.conf.
• Cyclone DDS on Cortex-A/R: see the DDS section of Choosing an RMW Backend for the required Kconfig deltas.
• Build nano-ros’s own Zephyr examples without west: Zephyr (contributor).

NuttX (apps/external)

Single-node starter on NuttX. nano-ros plugs into the standard NuttX app discovery as an external app under apps/external/nano-ros/, exposing Kconfig knobs under Application Configuration → External Modules → nano-ros. Use this entry when your NuttX board ships its own kernel build and you want to add ROS 2 communication.

Contributor path? Building nano-ros’s own NuttX QEMU examples straight from this repository (no NuttX-managed workspace) is covered at NuttX (contributor). The page below is the canonical user entry.

Prereqs. Install the nros CLI once per machine, then run nros setup qemu-arm-nuttx --rmw <zenoh|xrce|cyclonedds> (--rmw defaults to zenoh). This fetches a prebuilt toolchain set into ${NROS_HOME:-~/.nros}/sdk — the NuttX cross-compiler, the emulator, the NuttX sources, and the RMW host daemon — so you do not hand-install a cross-toolchain and do not need a ROS 2 install:

source ./activate.sh        # OR: direnv allow / source ./activate.fish
just setup-cli              # builds packages/cli/target/release/nros (Phase 218)
nros setup qemu-arm-nuttx --rmw zenoh

You still need a NuttX ≥ nuttx-12 checkout with an apps/ sibling and Python 3.10+ for the NuttX configure scripts.

Project layout

NuttX’s “external apps” pattern places the app shim under $NUTTX_APPS_DIR/external/<name>/:

$NUTTX_DIR/                              # NuttX kernel checkout
$NUTTX_APPS_DIR/                             # sibling: apps tree
└── external/
    └── nano-ros/                        # symlink or submodule of
        ├── Make.defs                    #   integrations/nuttx/
        ├── Makefile
        ├── CMakeLists.txt               #   (cmake-driven NuttX builds)
        └── Kconfig
my_app/                                  # your application
├── package.xml
├── Cargo.toml | CMakeLists.txt
├── generated/                           # Rust codegen — build.rs runs
│                                        #   `nros generate-rust` on first
│                                        #   `cargo build`; gitignored.
└── src/main.{rs,c,cpp}

Wire the shell into your NuttX apps tree. Easiest path:

just nuttx setup        # contributor helper: stages the shell +
                        # example apps into $NUTTX_APPS_DIR/external/
                        # (delegates to `nros setup qemu-arm-nuttx`
                        # for the toolchain/SDK provisioning)

This runs scripts/nuttx/stage-external-apps.sh, which writes $NUTTX_APPS_DIR/external/Make.defs + Kconfig and symlinks the integration shell (external/nano-ros) plus every example app (external/nano-ros-<example>-<lang>). Menuconfig surfaces them under Application Configuration → External Modules.

If you’d rather wire it yourself (e.g. into a vendored apps tree):

ln -s /path/to/nano-ros/integrations/nuttx \
      $NUTTX_APPS_DIR/external/nano-ros
# then copy integrations/nuttx/external-Make.defs.in →
# $NUTTX_APPS_DIR/external/Make.defs and add a matching
# $NUTTX_APPS_DIR/external/Kconfig that `source`s the shell.

Configure

NuttX uses Kconfig as its single source of truth. After the symlink above:

cd $NUTTX_DIR
make menuconfig
# Navigate to:
#   Application Configuration → External Modules → nano-ros
#   [*] nano-ros ROS 2 client
#       RMW backend  →  zenoh           # zenoh | xrce | cyclonedds
#       ROS 2 edition →  humble

Networking Kconfig requirements live under Networking Support — enable CONFIG_NET, CONFIG_NET_TCP, CONFIG_NET_IPv4. For QEMU nsh_smp configurations the defaults already include these.

Runtime config (locator / domain id) is read from the companion nros.toml next to the example source. Verbatim from the in-tree examples/qemu-arm-nuttx/rust/talker/nros.toml (this is the file just nuttx talker consumes — port 7452 matches just nuttx zenohd):

# nano-ros config (direct mode). See
# docs/design/0004-configuration-and-transports.md.

[node]
domain_id = 0

[[transport]]
kind    = "ethernet"
ip      = "10.0.2.30/24"
gateway = "10.0.2.2"
locator = "tcp/10.0.2.2:7452"

The C + C++ variants ship analogous files with distinct ports (7552 and 7652) so parallel test runs don’t collide on one router; just nuttx zenohd binds 7452 (Rust). When you boot a C or C++ talker directly, either edit the locator line of its nros.toml —

[[transport]]
kind    = "ethernet"
ip      = "10.0.2.30/24"
gateway = "10.0.2.2"
locator = "tcp/10.0.2.2:7452"   # was 7552 / 7652 — match `just nuttx zenohd`

— or start a sibling zenohd on the matching port (zenohd --listen tcp/127.0.0.1:7552 --no-multicast-scouting for C, …:7652 for C++).

Build

cd $NUTTX_DIR
make                                # full kernel + apps build

The Cargo build of nano-ros’s Rust staticlibs runs as a sub-step of the NuttX app build; libnros_c.a is linked at the final app link stage.

For CMake-driven NuttX builds:

cmake -B build -DBOARD=qemu-armv7a \
              -DCONFIG=nsh_smp
cmake --build build

Run

# 1. Start zenohd on the host (Slirp forwards 10.0.2.2:7452 → host).
#    The in-tree just recipe runs the daemon on the nuttx fixture
#    port (7452):
just nuttx zenohd &

# 2. QEMU NuttX (ARM). For nano-ros's own in-tree QEMU examples the
#    just recipe wraps qemu-system-arm with the right wiring. `talker`
#    here is the Rust variant; the C / C++ variants boot through the
#    `make`-driven path described under "Auto-configure glue" below:
just nuttx talker
#    For a NuttX-managed workspace where you've staged the
#    integration shell + your own app, mirror the recipe's actual
#    flags (see `just/nuttx.just::_run-qemu`):
qemu-system-arm -M virt -cpu cortex-a7 -nographic \
                -icount shift=auto \
                -kernel $NUTTX_DIR/nuttx \
                -netdev user,id=net0 \
                -device virtio-net-device,netdev=net0
# `$NUTTX_DIR/nuttx` is the linked NuttX ELF produced by `make`
# at the NuttX source root — adjust if your workspace puts it
# elsewhere (e.g. an out-of-tree build dir).
# At the NSH prompt, run the example's PROGNAME — the
# `make`-driven build registers every nano-ros example as a
# built-in command via Application.mk's `-Dmain=<PROGNAME>_main`
# rename. Real PROGNAMEs (from
# `packages/testing/nros-tests/tests/nuttx_make_e2e.rs::EXPECTED_PROGNAMES`):
nsh> nuttx_c_talker            # C talker
# nsh> nuttx_cpp_talker        # C++ talker
# nsh> nuttx_c_listener        # ...and listener / service / action variants

# Real hardware: standard NuttX flash flow (openocd / J-Link / etc.)

# 3. Verify from stock ROS 2 in another terminal:
source /opt/ros/humble/setup.bash
export RMW_IMPLEMENTATION=rmw_zenoh_cpp
# Talker publishes best-effort; stock `ros2 topic echo` defaults to
# RELIABLE, so the QoS-mismatched echo silently delivers nothing.
# Force best-effort to receive:
ros2 topic echo /chatter std_msgs/msg/Int32 --qos-reliability best_effort

Readiness signal. After typing the app’s NSH command (e.g. nuttx_c_talker), expect Published: 0 on the NSH console within 5 seconds — Rust + C + C++ all start the counter at 0 (Phase 208.D.9). If no Published: line:

1. Confirm the app actually ran — ps should show your task.
2. Confirm networking — ifconfig shows a configured interface. With the virtio-net + Slirp wiring above, eth0 comes up at 10.0.2.30 (matches examples/qemu-arm-nuttx/*/talker/nros.toml).
3. Confirm zenohd reachable; the locator in nros.toml / nros_init arguments must match.
4. See Troubleshooting — First 10 Minutes.

Auto-configure glue (NSH built-in registration)

The make-driven build above relies on a host-side glue layer that the in-tree just nuttx build-fixtures-make recipe owns end-to-end (see just/nuttx.just::build-fixtures-make). If you wire a NuttX workspace by hand, reproduce the same three steps:

1. Swap in the nano-ros board defconfig. Stock NuttX qemu-armv7a/nsh ships without CONFIG_NET=y, virtio-net, or TLS_NELEM. The board defconfig packages/boards/nros-board-nuttx-qemu-arm/nuttx-config/defconfig already carries the full networking + TLS stack zenoh-pico needs; copy it to $NUTTX_DIR/.config and run make olddefconfig.
2. Stage the integration shell + example apps. Run scripts/nuttx/stage-external-apps.sh "$NUTTX_APPS_DIR" to symlink integrations/nuttx/ and every example app into $NUTTX_APPS_DIR/external/. Remove $NUTTX_APPS_DIR/Kconfig so NuttX’s mkkconfig.sh rediscovers the new apps/external/Kconfig.
3. Flip the nano-ros Kconfig knobs via kconfig-tweak. The recipe enables NROS, NROS_C_API, NROS_CPP_API, every NROS_EXAMPLE_<EX>_<LANG>, sets TLS_NELEM=8, disables LIBCXXNONE + enables LIBCXXTOOLCHAIN, and disables ALLSYMS for the bootstrap link. Re-run make olddefconfig so the newly-visible dependencies settle, then make.

kconfig-tweak ships in the kconfig-frontends package on most distros. Without it the recipe skips ("NuttX skip: kconfig-tweak not on PATH"); install it before retrying.

GitHub source

• NuttX integration shell: integrations/nuttx/
• Worked NuttX QEMU examples: examples/qemu-arm-nuttx/rust/, examples/qemu-arm-nuttx/c/, examples/qemu-arm-nuttx/cpp/
• Kconfig schema: integrations/nuttx/Kconfig

Next

• Multiple apps: each app declares its own progname in Application Configuration → External Modules; they share the one libnros_c.a build via the external-app shell.
• DDS on NuttX: bump the netbuffer Kconfig knobs (similar to the Zephyr DDS profile under Choosing an RMW Backend).
• Build nano-ros’s own NuttX QEMU tests without a NuttX-managed workspace: NuttX (contributor).

ThreadX (Linux sim / RISC-V64 QEMU)

Single-node starter on Microsoft Azure RTOS ThreadX + NetX Duo (BSD socket layer). Two flavours ship in-tree:

• threadx-linux — ThreadX user-space simulator on Linux. Fast build, host network stack, ideal for development.
• threadx-riscv64 — QEMU virt machine with the RISC-V64 GCC toolchain. Full kernel + NetX Duo TCP/IP stack.

Rust, C, and C++ are supported on both flavours — just <flavour> build-fixtures produces threadx_cpp_* and riscv64_threadx_cpp_* binaries alongside the Rust + C ones. See the coverage matrix for the per-RMW cell status.

Prereqs. Install the nros CLI once, then run nros setup <board> --rmw <rmw> for the flavour you need (see Setup). It provisions the cross-compiler, emulator, RMW host daemon, and ThreadX/NetX sources — no hand-installed riscv64 cross toolchain, qemu-system-riscv64, or ROS 2 required.

Setup

nros setup is the single canonical command to prepare a machine to build nano-ros for a board. It ships prebuilt toolchains per platform per RMW — the cross-compiler, emulator, RMW host daemon, and SDK sources (the ThreadX/NetX sources, and for threadx-linux the POSIX-sim sources) are fetched from a pinned index into a shared store at ${NROS_HOME:-~/.nros}/sdk. You do not need ROS 2 installed.

Build the in-tree nros CLI (Phase 218):

source ./activate.sh        # OR: direnv allow / source ./activate.fish
just setup-cli              # builds packages/cli/target/release/nros

Provision the ThreadX flavour you need (+ the RMW):

nros setup threadx-linux --rmw zenoh          # POSIX-sim flavour; --rmw defaults to zenoh
nros setup qemu-riscv64-threadx --rmw zenoh   # only if you need the RISC-V64 QEMU flow
source ./setup.bash

The RMW host daemon must be running before any example: zenohd for zenoh, the Micro-XRCE-DDS agent for xrce. nros setup … --rmw <rmw> installs it.

Project layout

Each example is a standalone Cargo or CMake project under examples/threadx-{linux,riscv64}/<lang>/<example>/:

examples/threadx-linux/
├── rust/talker/                 # Cargo, target = x86_64-unknown-linux-gnu
│   ├── Cargo.toml
│   ├── package.xml
│   ├── generated/                # codegen output — build.rs runs
│   │                             #   `nros generate-rust` on first
│   │                             #   `cargo build`; gitignored.
│   └── src/main.rs
└── c/talker/                    # CMake, add_subdirectory
    ├── CMakeLists.txt
    ├── package.xml
    └── src/main.c

examples/qemu-riscv64-threadx/
├── rust/talker/                 # Cargo, target = riscv64gc-unknown-linux-gnu
│   └── ...
└── c/talker/
    └── ...

ThreadX-linux runs as a regular host process — no QEMU. NetX Duo uses the nx_bsd_* BSD socket shim layered on the host TCP stack (threadx-linux variant) or on its own NetX Duo TCP/IP stack (riscv64 variant).

Configure

Each talker carries a per-flavour nros.toml. Both files are reproduced verbatim below.

threadx-linux — examples/threadx-linux/rust/talker/nros.toml:

# nano-ros config (direct mode). See
# docs/design/0004-configuration-and-transports.md.

[node]
domain_id = 0

[[transport]]
kind    = "ethernet"
ip      = "192.0.3.10/24"
mac     = "02:00:00:00:00:00"
gateway = "192.0.3.1"
interface = "tap-tx0"
locator = "tcp/127.0.0.1:7455"

threadx-riscv64 — examples/qemu-riscv64-threadx/c/talker/nros.toml:

# nano-ros config (direct mode). See
# docs/design/0004-configuration-and-transports.md.

[node]
domain_id = 0

[[transport]]
kind    = "ethernet"
ip      = "10.0.2.40/24"
mac     = "52:54:00:12:34:56"
gateway = "10.0.2.2"
locator = "tcp/10.0.2.2:7553"

ThreadX-Linux normally uses a veth pair (tap-tx0) for an isolated host link, but nros setup threadx-linux does not create the interface — the test fixtures fall back to a loopback path when tap-tx0 is absent, which is fine for the happy-path tutorial. Bring up tap-tx0 by hand (ip link add … type veth …) only when you need real-network bridging. The QEMU-RISC-V64 fixture uses Slirp’s default 10.0.2.2 gateway just like the FreeRTOS QEMU flow.

Build

# threadx-linux:
just threadx_linux build-fixtures   # build all rust + c examples

# Single example:
cd examples/threadx-linux/rust/talker
cargo build --release

# threadx-riscv64:
just threadx_riscv64 build-fixtures

First setup builds ThreadX + NetX Duo (~3 min). Subsequent example builds finish in seconds.

Run

# threadx-linux (no QEMU). Step 1 brings up the in-tree zenohd on
# the threadx-linux port (7455). Step 2 runs the talker via the
# matching just recipe — same binary the example dir builds.
just threadx_linux zenohd &
just threadx_linux talker
# Expected (per src/main.rs structured logs):
#   Declaring publisher on /chatter (std_msgs/Int32)
#   Publisher declared
#   Published: 0
#   Published: 1
#   ...

# threadx-riscv64 (QEMU virt). Same shape — zenohd on 7453 first,
# then the talker recipe boots `qemu-system-riscv64` with the
# virtio-net + Slirp wiring baked in:
just threadx_riscv64 zenohd &
just threadx_riscv64 talker

# Verify from stock ROS 2:
source /opt/ros/humble/setup.bash
export RMW_IMPLEMENTATION=rmw_zenoh_cpp
# Talker publishes best-effort; stock `ros2 topic echo` defaults to
# RELIABLE, so the QoS-mismatched echo silently delivers nothing.
# Force best-effort to receive:
ros2 topic echo /chatter std_msgs/msg/Int32 --qos-reliability best_effort

For batch testing: just threadx_linux test runs every pubsub / service / action against an in-test zenohd.

Readiness signal. threadx-linux: Published: 0 within 3 seconds of just threadx_linux talker on a warm cache; a cold first run rebuilds the Rust example (~80 s on a fresh checkout) before the first publish lands. threadx-riscv64 (QEMU): within ~15 seconds of QEMU boot. If no Published: line:

1. Confirm zenohd reachable on the locator from nros.toml (threadx-linux uses 127.0.0.1; riscv64 QEMU uses 10.0.2.2).
2. threadx-linux: confirm the veth bridge came up via nros setup threadx-linux.
3. See Troubleshooting — First 10 Minutes.

GitHub source

• ThreadX-Linux Rust: examples/threadx-linux/rust/talker/
• ThreadX-Linux C: examples/threadx-linux/c/talker/
• ThreadX-RISC-V64 Rust: examples/qemu-riscv64-threadx/rust/talker/
• Board crates: packages/boards/nros-board-threadx-linux/, packages/boards/nros-board-threadx-qemu-riscv64/

Next

• Subscriber + service + action peers in the same example tree.
• DDS on ThreadX: Cyclone DDS is the surviving DDS backend (nros-rmw-cyclonedds, selected via -DNANO_ROS_RMW=cyclonedds); see Choosing an RMW Backend.
• Real hardware: same code runs against ThreadX vendor BSPs (Renesas Synergy, MIMXRT, etc.); replace the QEMU board crate with a vendor board crate.

ESP32 (esp-hal, bare-metal Rust)

Single-node starter on ESP32-C3 using the bare-metal esp-hal Rust path — no ESP-IDF — running under the Espressif QEMU fork (OpenETH ethernet). For the ESP-IDF component path (C / C++ apps), see ESP32 (ESP-IDF component).

Prereqs. nros setup esp32 is the single command that prepares your machine. It fetches a prebuilt esp-hal toolchain and the chosen RMW host daemon from a pinned index into the shared store at ~/.nros/sdk — you do not hand-install cross-compilers, and you do not need ROS 2 installed.

Setup

Build the in-tree nros CLI (Phase 218):

source ./activate.sh        # OR: direnv allow / source ./activate.fish
just setup-cli              # builds packages/cli/target/release/nros

Provision the board (and RMW):

nros setup esp32 --rmw zenoh     # --rmw defaults to zenoh; xrce | cyclonedds also valid

This pulls the SDK sources nano-ros owns (zenoh-pico + mbedtls submodules for zenoh; analogous for xrce / cyclonedds) and lands the RMW host daemon (zenohd for zenoh, the Micro-XRCE-DDS agent for xrce) under ${NROS_HOME:-~/.nros}/sdk (the activate file puts the in-tree CLI on PATH; legacy ${NROS_HOME:-~/.nros}/bin/ install remains supported transitionally). esp-hal itself is a Cargo dependency the example pulls in at build time, not a separately-installed toolchain; the only cross-toolchain you may need to add by hand is the rustup target — once per host:

rustup target add riscv32imc-unknown-none-elf      # ESP32-C3

Project layout

Each example is a standalone Cargo package targeting riscv32imc-unknown-none-elf (ESP32-C3). The board crate (nros-board-esp32-qemu) wraps the OpenETH / esp-hal init.

ESP32-S3 (Xtensa) is NOT supported today. The tutorial targets the RISC-V ESP32-C3 only. Xtensa targets do not ship via rustup (they require the espup toolchain installer) and the in-tree board crate is RISC-V only; this gap is tracked separately.

examples/qemu-esp32-baremetal/rust/talker/
├── Cargo.toml
├── .cargo/config.toml         # target = riscv32imc-unknown-none-elf
├── nros.toml                  # ethernet transport + zenoh locator
├── package.xml
├── generated/                 # codegen output — build.rs runs
│                              #   `nros generate-rust` on first
│                              #   `cargo build`; gitignored.
└── src/main.rs                # esp-hal init → nros_app_main

Configure

nros.toml carries the transport stack. The QEMU ESP32 board uses an ethernet transport via nros-board-esp32-qemu. Verbatim from examples/qemu-esp32-baremetal/rust/talker/nros.toml:

# nano-ros config (direct mode). See
# docs/design/0004-configuration-and-transports.md.

[node]
domain_id = 0

[[transport]]
kind    = "ethernet"
ip      = "10.0.2.50/24"
mac     = "02:00:00:00:00:01"
gateway = "10.0.2.2"
locator = "tcp/10.0.2.2:7454"

Build

# QEMU ESP32 (qemu-system-riscv32). `just esp32 build-qemu` (which
# `just esp32 talker` depends on) builds the QEMU-board variant; the
# example's build.rs invokes `nros generate-rust` automatically, so
# the `generated/` dir populates on first build (gitignored).
just esp32 build-qemu

Run

# QEMU ESP32. First bring up zenohd on the esp32 fixture port (7454):
just esp32 zenohd &
# Then boot the talker binary in qemu-system-riscv32 (esp32c3):
just esp32 talker
# Expected serial output (per src/main.rs):
#   Declaring publisher on /chatter (std_msgs/Int32)
#   Publisher declared
#   Published: 0
#   Published: 1
#   ...

# Verify from stock ROS 2 on the same network:
source /opt/ros/humble/setup.bash
export RMW_IMPLEMENTATION=rmw_zenoh_cpp
# Talker publishes best-effort; stock `ros2 topic echo` defaults to
# RELIABLE, so the QoS-mismatched echo silently delivers nothing.
# Force best-effort to receive:
ros2 topic echo /chatter std_msgs/msg/Int32 --qos-reliability best_effort

Readiness signal. QEMU ESP32: ~15 seconds after a warm cache — the just esp32 talker recipe re-runs build-qemu every invocation, so a first / cold run adds ~25 s of build time on top. If no Published: line:

1. Wrong locator → talker logs zenoh open failed and retries. Confirm zenohd is reachable on the host IP (10.0.2.2:7454).
2. Confirm .cargo/config.toml target is riscv32imc-unknown-none-elf (ESP32-C3). The tutorial does not support ESP32-S3 (Xtensa) yet.
3. See Troubleshooting — First 10 Minutes.

GitHub source

• QEMU ESP32 talker: examples/qemu-esp32-baremetal/rust/talker/
• Board crate: packages/boards/nros-board-esp32-qemu/

Next

• Subscriber + service + action peer directories under the same examples/qemu-esp32-baremetal/rust/.
• ESP-IDF component path for C / C++ apps: ESP32 (ESP-IDF component).
• ESP32-S3 (Xtensa) — not supported today. The Xtensa toolchain does not ship via rustup (it requires espup), and there is no in-tree Xtensa board crate. Stick with ESP32-C3 (RISC-V) for now.

ESP32 (ESP-IDF component)

Single-node starter on ESP32-family chips via the ESP-IDF component path — Espressif’s native C / C++ build system. For the bare-metal Rust (esp-hal) path, see ESP32 (esp-hal).

Prereqs. Two independent toolchains.

1. ESP-IDF itself — ≥ 5.1, installed through Espressif’s own installer so idf.py is on PATH (source $IDF_PATH/export.sh). nros setup does not replace this; the IDF toolchain comes from idf.py install / Espressif’s tooling.

2. The nano-ros side — the RMW host daemon (and any nano-ros host tools you use for testing) come from the nros CLI:

   source ./activate.sh        # OR: direnv allow / source ./activate.fish
   just setup-cli              # builds packages/cli/target/release/nros (Phase 218)
   nros setup esp32 --rmw zenoh     # lands the RMW host daemon
                                    # (zenohd for zenoh, the
                                    # Micro-XRCE-DDS agent for xrce)
                                    # in ${NROS_HOME:-~/.nros}/sdk, AND clones the
                                    # transport submodules
                                    # (zenoh-pico + mbedtls for zenoh)
                                    # into the nano-ros checkout
                                    # so the IDF build can compile
                                    # them in-tree.
   

Project layout

ESP-IDF apps are CMake projects with idf.py as the orchestrator. nano-ros plugs in as a component pulled by IDF’s component manager or by a local path during development.

my_idf_app/
├── CMakeLists.txt                 # top-level: `project(my_app)`
├── sdkconfig                      # IDF Kconfig (generated)
├── main/
│   ├── CMakeLists.txt             # `idf_component_register(REQUIRES nano-ros …)`
│   ├── idf_component.yml          # declares nano-ros as a managed dependency
│   ├── app_main.c | app_main.cpp
│   └── nros.toml                  # (optional) runtime locator + domain
└── components/                    # (optional) local components override

The idf_component.yml is the dependency manifest:

dependencies:
  nano-ros:
    # During development — local path to your nano-ros clone:
    path: ../../../nano-ros/integrations/nano-ros
    # Once published to the Espressif Component Registry:
    # version: "*"

The shell at integrations/nano-ros/ wraps the nano-ros root CMake into a standard IDF component, mapping IDF Kconfig knobs to NANO_ROS_* cache vars.

Configure

After idf.py menuconfig:

Component config → nano-ros
    RMW backend          (zenoh)        zenoh | xrce | cyclonedds
    ROS 2 edition        (humble)       humble | iron

The nano-ros component itself exposes only those two knobs. Wi-Fi credentials + zenoh locator are NOT in this Kconfig — provide them via your app’s own Kconfig.projbuild (Espressif’s standard pattern) or via environment variables, then pass them to nros::init(locator, domain_id) at startup.

Build

cd my_idf_app
idf.py set-target esp32c3        # or esp32s3, esp32, esp32c6
idf.py build

First build cross-compiles nano-ros’s Rust staticlibs + IDF components (~5 min). Re-builds finish in seconds.

Run

# Flash + monitor:
idf.py -p /dev/ttyUSB0 flash monitor
# Expected serial output:
#   I (1234) nano-ros: Wi-Fi connected
#   I (1456) nano-ros: zenoh session opened
#   I (1567) nano-ros: Published: 0

# Verify from stock ROS 2 on the same network:
source /opt/ros/humble/setup.bash
export RMW_IMPLEMENTATION=rmw_zenoh_cpp
# Talker publishes best-effort; stock `ros2 topic echo` defaults to
# RELIABLE, so the QoS-mismatched echo silently delivers nothing.
# Force best-effort to receive:
ros2 topic echo /chatter std_msgs/msg/Int32 --qos-reliability best_effort

QEMU ESP32 testing path: see the just esp_idf recipes — they boot the IDF binary in qemu-system-xtensa via Espressif’s patched QEMU.

Readiness signal. After idf.py flash monitor, expect I (XXXX) nano-ros: Wi-Fi connected followed by I (XXXX) nano-ros: Published: 0 within 10 seconds — Rust + C + C++ all start the counter at 0 (Phase 208.D.9). If no Published: line:

1. Wi-Fi creds — IDF Kconfig under Component config → nano-ros must carry SSID + password OR your nros.toml must.
2. Wrong locator — confirm host running zenohd is on the same Wi-Fi subnet (or routable to it). NAT will block discovery.
3. idf.py menuconfig shows the Component config → nano-ros submenu (the component is wired) and CONFIG_NROS_RMW is set to a backend name (zenoh/xrce/cyclonedds). There is no separate CONFIG_NROS_ENABLED toggle on ESP-IDF; the component’s presence in main/idf_component.yml is the on-switch.
4. See Troubleshooting — First 10 Minutes.

GitHub source

• IDF component shell: integrations/nano-ros/
• Component manifest: integrations/nano-ros/idf_component.yml
• Kconfig surface: integrations/nano-ros/Kconfig.projbuild

A complete reference app showing Wi-Fi + zenoh wiring on top of the component is not in-tree yet; the bare-metal examples/qemu-esp32-baremetal/rust/talker/ is the closest worked example.

Next

• Bare-metal esp-hal Rust path: ESP32 (esp-hal).
• Multi-component IDF apps: nano-ros sits next to other Espressif components (network, storage, sensors) — IDF’s component manager resolves them all.

Bare-metal Cortex-M3 (QEMU)

Single-node starter on bare-metal Cortex-M3 (QEMU MPS2-AN385) — no RTOS, no kernel scheduler. Pure cooperative spin via zpico_spin_once. Rust only. nros-c / nros-cpp are not supported on bare-metal targets (they assume a hosted RTOS for startup / heap / libc); see the examples coverage matrix for the policy.

When to use this path: ultra-constrained Cortex-M0+ / M3 / M4 targets with no OS scheduler, no pthread. If you have FreeRTOS or any RTOS, use the FreeRTOS starter instead — it’s more ergonomic and produces smaller code overall.

Prereqs. Install the nros CLI once per machine, then provision this board. nros setup fetches a prebuilt bare-metal toolchain (arm-none-eabi-gcc, qemu-system-arm, the zenoh router) plus the Rust thumbv7m-none-eabi target into a shared store — no manual cross-compiler install, no ROS 2 needed.

# Build the in-tree nros CLI (Phase 218):
source ./activate.sh        # OR: direnv allow / source ./activate.fish
just setup-cli              # builds packages/cli/target/release/nros

# Provision the bare-metal Cortex-M3 board (zenoh RMW is the default):
nros setup qemu-arm-baremetal --rmw zenoh

Real-board variants exist too: nros setup mps2-an385 and nros setup stm32f4 provision the same bare-metal toolchain for physical hardware.

Project layout

examples/qemu-arm-baremetal/rust/talker/
├── Cargo.toml
├── .cargo/config.toml         # target = thumbv7m-none-eabi
│                              # runner = qemu-system-arm ... -kernel
├── nros.toml                  # network + zenoh
├── package.xml
├── generated/                 # codegen output — build.rs runs
│                              #   `nros generate-rust` on first
│                              #   `cargo build`; gitignored.
└── src/main.rs                # #[entry] fn main() -> !

The board crate is nros-board-mps2-an385 (note: no -freertos suffix — this is the bare-metal variant) which provides:

• Cortex-M3 startup + linker script
• LAN9118 driver for smoltcp
• BoardIdle::wfi() for cooperative wait

Configure

Verbatim from the in-tree examples/qemu-arm-baremetal/rust/talker/nros.toml:

# nano-ros config — QEMU ARM bare-metal talker (direct mode).
# Read by the nros-board-mps2-an385 board crate via Config::from_toml.

[node]
domain_id = 0

# Single ethernet transport running a zenoh session. `ip` is CIDR
# (address/prefix); the locator rides the transport.
[[transport]]
kind    = "ethernet"
ip      = "10.0.2.10/24"
mac     = "02:00:00:00:00:00"
gateway = "10.0.2.2"
rmw     = "zenoh"
locator = "tcp/10.0.2.2:7450"

QEMU Slirp networking — no host TAP / bridge / sudo. The zenohd default port is 7447; this example expects 7450 so start the router with zenohd --listen tcp/127.0.0.1:7450 (or edit nros.toml to match zenohd’s 7447 default).

Build

cd examples/qemu-arm-baremetal/rust/talker
cargo build --release

First build (~5 min) cross-compiles all of nano-ros’s Rust deps for thumbv7m-none-eabi. Re-builds finish in seconds.

Run

# 1. Bring up zenohd on the host (Slirp forwards 10.0.2.2:7450 → host
#    127.0.0.1:7450). The bare-metal test-fixture port is 7450, NOT
#    zenohd's default 7447 — edit `nros.toml` if you want 7447 instead.
#    The just recipe runs the in-tree zenohd installed by
#    `nros setup ... --rmw zenoh` on that port:
just qemu zenohd &
#    Or directly:
#    zenohd --listen tcp/127.0.0.1:7450 --no-multicast-scouting

# 2. Boot the talker in QEMU. The `just qemu talker` recipe wraps
#    qemu-system-arm with the LAN9118 networking wiring the example
#    expects — it's the only working invocation for this tutorial
#    (the example's `.cargo/config.toml` runner is bare `-kernel`,
#    no `-nic socket,model=lan9118,…`, so a plain `cargo run` boots
#    QEMU without networking):
just qemu talker
# Expected serial-over-semihosting output (per src/main.rs):
#   Declaring publisher on /chatter (std_msgs/Int32)
#   Publisher declared
#   Published: 0
#   Published: 1
#   ...

# 3. Verify from stock ROS 2:
source /opt/ros/humble/setup.bash
export RMW_IMPLEMENTATION=rmw_zenoh_cpp
# Talker publishes best-effort; stock `ros2 topic echo` defaults to
# RELIABLE, so the QoS-mismatched echo silently delivers nothing.
# Force best-effort to receive:
ros2 topic echo /chatter std_msgs/msg/Int32 --qos-reliability best_effort

QEMU exits via Ctrl-A x.

Readiness signal. Within ~15 seconds of QEMU boot (no RTOS init delay, but smoltcp + zenoh handshake still takes a few seconds), expect Published: 0 on semihosting stdout (the Rust talker pre-publishes 0 before the counter advances). If no Published: line:

1. zenohd not running — talker spins on smoltcp poll until killed.
2. Wrong LAN9118 emulation flag — qemu-system-arm needs -nic socket,model=lan9118,… or equivalent. The example’s .cargo/config.toml runner is bare -kernel (so a plain cargo run boots QEMU without networking); the LAN9118 wiring lives in the just qemu talker recipe (just/qemu-baremetal.just::talker), which is the working invocation for this tutorial. If you copy the runner out, mirror those flags.
3. Cooperative spin starvation — if you added a long-running callback, the entire executor stalls; bare-metal has no preemption.
4. See Troubleshooting — First 10 Minutes.

GitHub source

• Bare-metal talker: examples/qemu-arm-baremetal/rust/talker/
• Board crate: packages/boards/nros-board-mps2-an385/

Constraints to be aware of

• No alloc by default. Pure no_std + heapless for bounded collections. If you need alloc, opt in via the alloc feature on your board crate and supply a #[global_allocator].
• No wake primitive. Cooperative single-thread spin only; the executor’s nros_platform_wake_* slots return Unsupported.
• No preemption. A long-running user callback blocks every other dispatchable handle until it returns.
• nros-c / nros-cpp NOT supported. These wrappers assume hosted-RTOS libc + heap. Pure-Rust API only on this target.

For Cortex-M3 with an RTOS, switch to the FreeRTOS starter.

Next

• Subscriber / service / action peers under the same examples/qemu-arm-baremetal/rust/ tree.
• Wake-callback opt-in: the wake-callback (latency-probe) bench under packages/testing/nros-bench/wake-latency-cortex-m3/ shows how to feed a backend’s transport-notify into the cooperative spin loop on bare-metal.
• Real hardware: same code runs on STM32F4-Discovery with a different board crate (nros-board-stm32f4) and a different linker script.

PX4 Autopilot (external module)

Single-node starter on PX4 Autopilot via the external-module copy-out template. PX4’s EXTERNAL_MODULES_LOCATION pattern lets downstream firmware drop in nano-ros without forking PX4 itself. C++ only — PX4’s uORB binding is C++-only (Rust + C not in the coverage matrix).

Prereqs. A PX4-Autopilot ≥ v1.16 clone, the matching cross toolchain (e.g. gcc-arm-none-eabi for Pixhawk targets), and python3 with the PX4 development requirements installed (bash ./Tools/setup/ubuntu.sh once).

Project layout

PX4 external modules live outside the PX4 source tree and are hooked in at configure time. The template at integrations/px4/module-template/ has the PX4-required src/modules/<name>/ shape:

my_drone_firmware/
├── PX4-Autopilot/                          # PX4 source tree (submodule)
└── px4-modules/                            # passed via EXTERNAL_MODULES_LOCATION
    └── nano-ros/                           # copy-out from integrations/px4/module-template/
        └── src/
            ├── CMakeLists.txt              # populates config_module_list_external
            └── modules/
                └── nano_ros_app/
                    ├── CMakeLists.txt      # px4_add_module(... MAIN nano_ros_app)
                    └── nano_ros_app.cpp    # the user-editable app

Prereq. PX4 is a full-tier dependency. Run just setup px4 first to populate third-party/px4/PX4-Autopilot and third-party/px4/px4-rs. just px4 doctor reports the gap on a fresh clone.

just setup px4              # equivalent to: just px4 setup
just px4 doctor

Vendor the template into your firmware repo, then point PX4 at its parent directory + tell the template where nano-ros lives via NANO_ROS_DIR. The template accepts either form — a CMake cache variable (-DNANO_ROS_DIR=<path>) takes precedence over an environment variable (NANO_ROS_DIR=…), then the in-tree default:

cmake -B build -S PX4-Autopilot \
      -DCONFIG=px4_fmu-v5_default \
      -DEXTERNAL_MODULES_LOCATION=$PWD/px4-modules/nano-ros \
      -DNANO_ROS_DIR=$PWD/../nano-ros            # point at your nano-ros clone

# Or via environment, if you prefer:
NANO_ROS_DIR=$PWD/../nano-ros cmake -B build -S PX4-Autopilot \
      -DCONFIG=px4_fmu-v5_default \
      -DEXTERNAL_MODULES_LOCATION=$PWD/px4-modules/nano-ros

(EXTERNAL_MODULES_LOCATION must point at the dir containing the template’s src/ — that’s px4-modules/nano-ros, not its parent. PX4’s root CMakeLists.txt does add_subdirectory("${EXTERNAL_MODULES_LOCATION}/src" …), so the path resolves to px4-modules/nano-ros/src per the layout above.)

Inside the module, the canonical pattern bridges uORB → nano-ros. The module is a PX4Module subclass that runs in its own work queue, opens an nros executor, and forwards uORB messages onto a zenoh / DDS topic (or vice versa). Edit nano_ros_app.cpp to add your topic bindings.

Configure

The template does not ship a Kconfig overlay (no Kconfig.projbuild files). Module enablement is implicit once EXTERNAL_MODULES_LOCATION points at the template’s parent. Pass RMW + ROS-edition selection via CMake cache vars rather than menuconfig:

cmake -B build -S PX4-Autopilot \
      -DCONFIG=px4_fmu-v5_default \
      -DEXTERNAL_MODULES_LOCATION=$PWD/px4-modules/nano-ros \
      -DNANO_ROS_DIR=$PWD/../nano-ros \
      -DNANO_ROS_RMW=zenoh

(Adding a Kconfig overlay so the module appears under menuconfig → External modules is a follow-up task; for now the template is always enabled.)

Build

cd PX4-Autopilot
make px4_fmu-v5_default
# Or for the SITL simulator (POSIX target — easier to develop against):
make px4_sitl_default gazebo

The first build cross-compiles nano-ros’s Rust staticlibs alongside PX4’s NuttX kernel + apps (~10 min on a fresh checkout).

Run

# SITL: PX4 boots Gazebo + the autopilot binary
cd PX4-Autopilot
make px4_sitl_default gazebo
# In the PX4 console:
pxh> nano_ros_app start

# Real hardware (Pixhawk): flash via QGroundControl or
#     `make px4_fmu-v5_default upload` over the bootloader USB

# Verify from stock ROS 2 on the same network (only after you have
# added uORB → nano-ros forwarders to nano_ros_app.cpp — the shipped
# template forwards nothing on its own):
source /opt/ros/humble/setup.bash
export RMW_IMPLEMENTATION=rmw_zenoh_cpp
ros2 topic echo /vehicle_local_position px4_msgs/msg/VehicleLocalPosition

Readiness signal. After nano_ros_app start in the PX4 console, the shipped template logs nano-ros uORB backend registered and returns immediately — it doesn’t start a publisher loop or print a “bridge started” line on its own. You’re expected to edit nano_ros_app.cpp to wire your uORB → nano-ros forwards. If nano_ros_app reports register failed, check:

1. Module didn’t register — the template logs nros_rmw_uorb_register() -> <rc> on startup (search the PX4 boot log for nros_rmw_uorb_register). A non-zero <rc> usually means a NuttX kernel-config / feature-gate mismatch.
2. Once you’ve added forwarders, zenohd must be reachable from the autopilot’s network (Pixhawk: configured via QGroundControl or param set).
3. uORB topic not advertised yet — start the upstream PX4 module that publishes it (commander start etc.) first.
4. See Troubleshooting — First 10 Minutes.

GitHub source

• PX4 external-module template: integrations/px4/module-template/
• Worked PX4 example: examples/px4/cpp/uorb/nros-register-check/
• PX4 integration roadmap notes: integrations/px4/README.md

Constraints to be aware of

• uORB binding is C++-only. The PX4 example collapses uORB registration to a C++ port; Rust / C variants exist for non-PX4 RTOSes but not for PX4.
• PX4’s NuttX kernel. Underneath, PX4 runs NuttX; if you need to debug at the kernel layer, the NuttX starter page applies too.
• uORB throughput vs zenoh hops. uORB is in-process pub/sub at ~µs latency; zenoh adds network-RTT. Plan accordingly when bridging high-rate streams.

Next

• Add your own uORB topics to the bridge: see the nano_ros_app.cpp template’s topic-table section.
• Multi-vehicle: PX4-XRCE-Agent → nano-ros XRCE backend gives you the standard PX4-ROS bridge with nano-ros on the autopilot side.
• For pure-NuttX (no PX4) firmware: see the NuttX starter.

ARM FVP (FVP_BaseR_AEMv8R)

Run nano-ros on Arm’s Base_RevC AEMv8-R Fast Models — the Cortex-A SMP profile under Zephyr 3.7 (board id fvp_baser_aemv8r/fvp_aemv8r_aarch64/smp). The FVP is the canonical local proxy for the safety-island reference platforms that follow the same hwv2 Zephyr shape; pair this chapter with the Zephyr (west module) starter for the build half.

Phase 217. The build half (just zephyr build-fvp-aemv8r{,-cyclonedds}) shipped in Phase 117.13–117.14; the run half — invoking FVP_BaseR_AEMv8R and piping UART 0–3 to stdout — landed as Phase 217.A on 2026-06-03. See docs/roadmap/phase-217-arm-fvp-local-runtime.md.

When to use

• You need to exercise a Cortex-A SMP Zephyr image on a developer laptop without dedicated silicon.
• You’re bringing up a new hwv2 safety-island target — the FVP is the closest in-tree reference for board.cmake + SMP boot + Cyclone DDS shape.
• You’re validating Phase 117 stock-RMW interop locally before promoting to a hardware bench.

The FVP is not a replacement for QEMU on Cortex-M (mps2-an385, mps3-an547); those targets are covered by FreeRTOS (QEMU) and the Zephyr starter. The FVP is also not the same surface as Corellium’s AVH cloud FVP — AVH packages firmware as .coreimg and provisions via a remote API; local FVP loads a raw ELF via -a cluster0.cpu*=<elf>. AVH is out of scope for this chapter.

Prereqs

• A working Zephyr 3.7 workspace — run nros setup zephyr once if you haven’t (see the Zephyr starter).
• The Arm Base_RevC AEMv8R Fast Models binary — license-gated. Download from developer.arm.com — Arm Ecosystem FVPs after accepting the EULA. nano-ros does not download it (the [gated.arm-fvp] row in nros-sdk-index.toml declares the tool but the fetch is your responsibility — same policy as the NVIDIA Orin SPE FSP).

After installing, export one of the discovery env vars:

# Preferred — Zephyr's canonical name; takes highest priority.
export ARMFVP_BIN_PATH=/opt/Arm/FastModels/Base_RevC_AEMv8R/models/Linux64_GCC-9.3

# Alternative — directory layout from the gated installer; the
# resolver scans `models/Linux64_GCC-*/` underneath it.
export ARM_FVP_DIR=/opt/Arm/FastModels/Base_RevC_AEMv8R

If neither is set, FVP_BaseR_AEMv8R is discovered via PATH as a last-ditch fallback.

Installer surface (Phase 217.B.1)

After extracting the Arm FVP tarball, run the discovery script:

ARM_FVP_DIR=/path/to/extracted/fvp \
    scripts/installers/arm-fvp-installer.sh

The installer locates FVP_BaseR_AEMv8R under $ARM_FVP_DIR, symlinks the containing directory to ~/.nros/sdks/arm-fvp/current/ (atomic via ln -sfn), and prints the export ARMFVP_BIN_PATH=… line for your shell rc. Run scripts/installers/arm-fvp-installer.sh --print-env later to re-emit the export. It never downloads anything — gated-tool policy.

Doctor check (Phase 217.B.2)

nros doctor --board fvp-aemv8r-smp cross-checks the [gated.arm-fvp] entry in nros-sdk-index.toml and warns (never hard-fails — gated) when the FVP can’t be resolved via ARMFVP_BIN_PATH, ARM_FVP_DIR, PATH, or the canonical ~/.nros/sdks/arm-fvp/current/FVP_BaseR_AEMv8R landing path. The just zephyr run-fvp-aemv8r{,-cyclonedds} recipes do the equivalent inline via scripts/zephyr/resolve-fvp-bin.sh and skip with a clear hint when the binary can’t be found.

Build

The build half is unchanged from Phase 117.13 / 117.14:

# Phase 117.13 — Zephyr-only talker.
just zephyr build-fvp-aemv8r

# Phase 117.14 — C++ pub/sub over Cyclone DDS, the wire-compat
# reference for the safety-island slice.
just zephyr build-fvp-aemv8r-cyclonedds

Each recipe shells west build -b fvp_baser_aemv8r/fvp_aemv8r_aarch64/smp inside the zephyr-workspace/ directory and produces zephyr.elf at one of:

• zephyr-workspace/build-fvp-aemv8r-talker/zephyr/zephyr.elf
• zephyr-workspace/build-aemv8r-cyclonedds-talker/zephyr/zephyr.elf

Run

Once the build artifacts and ARM_FVP_DIR / ARMFVP_BIN_PATH are in place:

# Boot the Phase 117.13 talker.
just zephyr run-fvp-aemv8r

# Boot the Phase 117.14 cpp/cyclonedds talker.
just zephyr run-fvp-aemv8r-cyclonedds

Under the hood the recipe:

1. Verifies west + the Zephyr workspace + zephyr.elf exist; skips with a hint otherwise.
2. Resolves the FVP binary directory via scripts/zephyr/resolve-fvp-bin.sh (priority order: ARMFVP_BIN_PATH → ARM_FVP_DIR/models/Linux64_GCC-*/ → dirname $(command -v FVP_BaseR_AEMv8R)).
3. Exports ARMFVP_BIN_PATH=<dir> and shells west build -d <build-dir> -t run, which drives Zephyr’s cmake/emu/armfvp.cmake target with the canonical boards/arm/fvp_baser_aemv8r/board.cmake -C flags — UART 0–3 piped to stdout, GICv3, cache state, NUM_CORES from CONFIG_MP_MAX_NUM_CPUS. No flags are duplicated in the just recipe.

Exit cleanly with Ctrl-C.

Expected output

The Zephyr 3.7 boot banner appears on UART0 first, followed by the talker. The exact line counts depend on CONFIG_BOOT_BANNER and your locator config, but the markers to look for are:

*** Booting Zephyr OS build v3.7.0 ***
[00:00:00.xxx,000] <inf> nros: session up (domain 0)
Published: 0/1
Published: 1/2
...

For the cpp/cyclonedds recipe, the same banner is followed by Cyclone DDS reader-match logs and std_msgs/Int32 publish lines. Verify ROS 2 interop by running a sibling listener in another terminal:

# stock ROS 2 — reads the FVP's Cyclone DDS publisher
ros2 topic echo /chatter std_msgs/msg/Int32

The same std_msgs/Int32 payload + byte-equal CDR framing must appear on both sides — that’s the Phase 117 stock-RMW interop contract.

Cross-references

• docs/roadmap/phase-217-arm-fvp-local-runtime.md — the runtime slice. Track A (run recipes) landed; B (installer
  • doctor), C (smoke test), D (Rust example), E (this chapter) ongoing.
• docs/roadmap/archived/phase-117-cyclonedds-rmw.md — Phase 117.13 (Zephyr FVP build smoke) + 117.14 (Cyclone DDS port + cpp talker) are the build smokes the runtime exercises.
• Environment Variables — ARM_FVP_DIR / ARMFVP_BIN_PATH — the discovery contract.
• Zephyr (west module) — the parent Zephyr starter; the FVP is a board-target slice of it.
• examples/zephyr/cpp/cyclonedds/talker-aemv8r/README.md — the example walk-through.

Native POSIX

Use the native POSIX target for first experiments, CI smoke tests, and ROS 2 interoperability checks on Linux or *BSD. It uses OS sockets, the host process environment, and the same source checkout layout as the embedded targets.

When to Use It

• You want the shortest path to a working nano-ros publisher or subscriber.
• You are validating message generation, CMake integration, or ROS 2 interop before moving to an RTOS.
• Your deployment target is Linux, *BSD, or an embedded Linux system.

Setup

Build the in-tree nros CLI (Phase 218), then provision the native host. For a host build there is no cross-toolchain to fetch — nros setup native installs only the RMW host daemon (zenohd for zenoh, the Micro-XRCE-DDS agent for xrce) into a shared store. ROS 2 is not required.

# Build the in-tree nros CLI:
source ./activate.sh        # OR: direnv allow / source ./activate.fish
just setup-cli              # builds packages/cli/target/release/nros

# Provision the native host (zenoh RMW is the default):
nros setup native --rmw zenoh        # or: --rmw xrce / --rmw cyclonedds

native and posix are accepted as the same board name.

For a colcon consumer workspace that already has nano-ros under src/:

colcon build && source install/setup.bash

Package Layout

For a POSIX application package:

my_posix_node/
├── package.xml
├── Cargo.toml          # Rust path
├── CMakeLists.txt      # C / C++ path
└── src/
    └── main.rs         # or main.c / main.cpp

Keep package beside nano-ros in workspace src/. Use path dependencies for Rust or add_subdirectory(<path-to-nano-ros>) for C/C++.

Code Example

Rust publisher skeleton:

use nros::prelude::*;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let config = ExecutorConfig::from_env().node_name("talker");
    let mut executor = Executor::open(&config)?;
    let mut node = executor.create_node("talker")?;
    let publisher = node.create_publisher::<std_msgs::msg::Int32>("/chatter")?;

    let mut msg = std_msgs::msg::Int32 { data: 0 };
    loop {
        publisher.publish(&msg)?;
        msg.data += 1;
        executor.spin_once(100);
    }
}

Use the full First Node — Rust walkthrough for generated messages and runnable commands.

Build and Run

Start the RMW host daemon (installed by nros setup native). For zenoh:

zenohd --listen tcp/127.0.0.1:7447

Run the node directly via cargo run (Rust) or cmake --build build && ./build/<binary> (C/C++), or via colcon build && source install/setup.bash && ros2 run … if the package lives in a colcon consumer workspace.

Configuration

Native examples can read runtime settings from the shell:

export ROS_DOMAIN_ID=0
export NROS_LOCATOR=tcp/127.0.0.1:7447

The same fields are compiled into embedded targets through their platform-specific configuration files. See Configuration for the full layering.

Deployment

POSIX deployment is normal process deployment: install the workspace, source install/setup.bash, set environment, and run the binary. For ROS 2 interop, run ROS 2 Interoperability and set the ROS side to rmw_zenoh_cpp.

Application Workflow

nano-ros users usually want one path: prepare package, write node, build it, then deploy to target. Use Concepts only when workflow raises a technical question.

1. Prepare Workspace and Package

nano-ros is shipped source-only — vendor it next to (or inside) your workspace, then provision the board’s toolchain with nros setup:

# Build the in-tree nros CLI (Phase 218), then provision your board (+ RMW):
./scripts/bootstrap.sh base
source ./activate.sh        # OR: direnv allow / source ./activate.fish
nros setup native --rmw zenoh        # or qemu-arm-freertos, zephyr, …

nros setup ships prebuilt toolchains per platform per RMW — see Installation.

For multi-package workspaces (Pattern A — recommended for POSIX + mixed C / C++ / Rust deployments), put nano-ros and your packages side-by-side under a shared src/:

~/ros2_ws/
├── src/
│   ├── nano-ros/                  # this repo
│   └── my_robot_node/
│       ├── package.xml
│       ├── Cargo.toml             # Rust, if using Rust API
│       ├── CMakeLists.txt         # C/C++, if using CMake
│       ├── config.toml            # embedded targets
│       └── src/
└── build/ install/ log/           # if you use colcon

For third-party C/C++ projects without colcon (Pattern B), pull nano-ros in as a third_party/nano-ros/ git submodule and consume it via add_subdirectory(third_party/nano-ros nano_ros).

See Installation for both patterns. The per-language starter pages document the canonical package shape in their “Project layout” sections: Rust, C, C++. For two or more nodes, use the Multi-Node Projects group: start from the full project layout, then drill into Node, Bringup, and Entry packages.

2. Write Node Code

Choose API language first:

• Rust — use nros, generated message crates, and Executor.
• C — include nros/nros.h and generate interfaces with nros_find_interfaces(LANGUAGE C) in CMake.
• C++ — include nros/nros.hpp and use typed wrappers.

Start with one of the Linux starters above, then adapt to your target via the Embedded Starters section.

3. Generate Messages

If you use custom .msg, .srv, or .action files, generate bindings inside the workspace/build tree. See Message Binding Generation.

4. Configure Target

Pick a platform and an RMW backend at build time (compile-time choice — there is no RMW_IMPLEMENTATION runtime switch on embedded targets):

Supported pairs: posix / freertos / nuttx / threadx / zephyr / esp32 / baremetal × zenoh / xrce / dds / cyclonedds. Not every cell is implemented — see the Coverage Matrix.

Runtime configuration (ROS_DOMAIN_ID, ZENOH_LOCATOR, …) works on POSIX. Embedded targets resolve config via CMake cache vars, Kconfig (Zephyr), Cargo features, or config.toml. See Configuration.

5. Build, Test, Deploy

For each canonical entry point:

# Single example (POSIX, Pattern A or B):
cd examples/native/rust/talker
cargo run

# Single C/C++ example (CMake + add_subdirectory):
cd examples/qemu-arm-freertos/cpp/talker
cmake -B build -DCMAKE_TOOLCHAIN_FILE=$PWD/../../../../../cmake/toolchain/arm-freertos-armcm3.cmake
cmake --build build

# Per-platform multi-example build:
just freertos build-fixtures
just zephyr  build-fixtures
just nuttx   build-fixtures

# Discover full-matrix commands for a platform:
just --group full-matrix --list zephyr

# Multi-component system (orchestration):
nros metadata my_system
nros plan my_system launch/my_system.launch.py
nros check
cargo build                 # or: cmake --build / west build / idf.py build

# POSIX-only colcon consumer-workspace build:
colcon build && source install/setup.bash

For target-specific deployment, go to the matching platform guide. Each guide covers toolchain setup, package layout, code example, build command, run/flash command, and deployment notes.

See Deployment Workflow.

Build as a CMake subdirectory

This is the way to integrate nano-ros into a C or C++ project. The nano-ros repo ships a top-level CMakeLists.txt that exposes everything via add_subdirectory(...). No install step, no find_package(NanoRos), no install prefix removed every last trace of that pipeline.

Layout

my_app/
├── CMakeLists.txt
├── main.c
└── third_party/
    └── nano-ros/        # git clone / git submodule of this repo

User project CMakeLists.txt

cmake_minimum_required(VERSION 3.22)
project(my_app C)

# Pick platform + RMW BEFORE add_subdirectory.
set(NANO_ROS_PLATFORM posix)   # posix | freertos | nuttx | threadx | zephyr | baremetal
set(NANO_ROS_RMW     zenoh)    # zenoh | dds | xrce | cyclonedds

add_subdirectory(third_party/nano-ros nano_ros)

add_executable(my_app main.c)
target_link_libraries(my_app PRIVATE NanoRos::NanoRos)
nros_platform_link_app(my_app)

# Optional — generate C bindings for ROS 2 .msg / .srv / .action files.
# nros_generate_interfaces() is reachable in-tree once nano-ros has been
# add_subdirectory'd; no install step required.
nros_generate_interfaces(std_msgs DEPENDENCIES builtin_interfaces SKIP_INSTALL)
target_link_libraries(my_app PRIVATE std_msgs__nano_ros_c)

That’s the whole story for the host-POSIX / zenoh case. CMake’s transitive target propagation pulls in libnros_c.a, libnros_rmw_zenoh_staticlib.a, the POSIX platform shim, system libraries (pthread, dl, m), and the per-build nros_config_generated.h header automatically.

Cache variables

Variables MUST be set(...) BEFORE add_subdirectory(...) — the sub-project consumes them at include time.

What about installing?

deleted every install(...) rule. nano-ros is consumed in source form — never out of an installed prefix. If you need a shippable artefact, your user project owns the install layout; ship your binary, not nano-ros itself.

For RTOS users who want a more idiomatic surface than raw add_subdirectory, see the integration shells under integrations/<rtos>/ — they translate west / esp-idf / NuttX / PX4 manifests into the same root CMake. Each shell is a ~20-line wrapper around add_subdirectory(<repo>).

Worked example

The examples/native/c/talker/CMakeLists.txt is the canonical copy-out template — 20 lines including codegen + per-app fixup. All 83 in-tree C/C++ examples follow the same shape after.

Message Binding Generation

nros uses generated Rust bindings for ROS 2 message types. The nros generate-rust command generates no_std compatible bindings from package.xml dependencies.

Overview

The binding generator lives in the in-tree CLI sub-workspace at packages/cli/ and provides:

• nros standalone binary
• Pure Rust, no_std compatible output using heapless types
• Automatic dependency resolution via ament index or bundled interfaces
• .cargo/config.toml generation for crate patches

Prerequisites

1. package.xml in project root - Declares ROS interface dependencies

   <?xml version="1.0"?>
   <package format="3">
     <name>my_package</name>
     <version>0.1.0</version>
     <description>My nros package</description>
     <maintainer email="dev@example.com">Developer</maintainer>
     <license>Apache-2.0</license>
     <depend>std_msgs</depend>
     <depend>geometry_msgs</depend>
     <export>
       <build_type>ament_cargo</build_type>
     </export>
   </package>
   

2. nros tool built + on PATH

   The nros CLI is built from the in-tree sub-workspace at packages/cli/ (Phase 218) and put on PATH by the activate file:

   # From the nano-ros repository root
   source ./activate.sh        # OR: direnv allow / source ./activate.fish
   just setup-cli              # builds packages/cli/target/release/nros
   

   See Installation for the full walkthrough.

3. ROS 2 environment (optional for standard types)

   Standard interfaces (std_msgs, builtin_interfaces) are bundled with nros and work without ROS 2. For additional packages (e.g., geometry_msgs, sensor_msgs), source a ROS 2 environment:

   source /opt/ros/humble/setup.bash
   

Workflow

Step 1: Create package.xml

Declare your ROS interface dependencies in <depend> tags:

<depend>std_msgs</depend>      <!-- For std_msgs::msg::Int32, String, etc. -->
<depend>example_interfaces</depend>  <!-- For service types -->

Step 2: Generate bindings

cd my_project
nros generate-rust

This will:

1. Parse package.xml to find dependencies
2. Resolve transitive dependencies (ament index + bundled interfaces)
3. Filter to interface packages (those with msg/srv/action)
4. Generate bindings to generated/ directory

Step 3: Add dependencies to Cargo.toml

Reference the generated crates using crates.io version specifiers:

[dependencies]
std_msgs = { version = "*", default-features = false }
example_interfaces = { version = "*", default-features = false }

The .cargo/config.toml patches redirect these to local paths.

Why msg crates are RMW-agnostic

Generated msg crates carry only the wire-format data type — no backend-specific code, no per-RMW Cargo feature. A user manifest is the plain pair:

[dependencies]
std_msgs = { version = "*", default-features = false }
nros     = { version = "*", features = ["rmw-cyclonedds"] }   # RMW choice lives here

Transport choice and message schema are orthogonal concerns and the manifest reflects that. This matches upstream rclcpp + rclrs, which both ship msg packages RMW-agnostic and let the RMW pick which descriptor representation it wants at runtime.

For DDS-based backends that need a per-type descriptor on the wire (Cyclone DDS today), the nros-rmw-cyclonedds shim builds those descriptors lazily on first pub/sub for a given message type, walks the static field schema exposed by nros-serdes (the Message trait with const TYPE_NAME + const FIELDS), and caches the result in a bounded no_std registry. No per-msg-pkg backend code is required.

Tracking + sizing knob (NROS_CYCLONEDDS_MAX_TYPES): see docs/roadmap/phase-212-ux-cargo-native-and-file-consolidation.md section 212.K.7.

Git Dependency Workflow

For projects that consume nros as a git dependency (not from within the nros repo), use --nano-ros-git instead of --nano-ros-path:

Step 1: Add git dependency to Cargo.toml:

[dependencies]
nros = { git = "https://github.com/jerry73204/nano-ros", default-features = false, features = ["std"] }
std_msgs = { version = "*", default-features = false }

Step 2: Create package.xml (same as above).

Step 3: Generate bindings with git patches:

source /opt/ros/humble/setup.bash
nros generate-rust --config --nano-ros-git

This generates .cargo/config.toml with git-based patches:

[patch.crates-io]
nros-core = { git = "https://github.com/jerry73204/nano-ros" }
nros-serdes = { git = "https://github.com/jerry73204/nano-ros" }
std_msgs = { path = "generated/std_msgs" }
builtin_interfaces = { path = "generated/builtin_interfaces" }

Step 4: Use in code

#![allow(unused)]
fn main() {
use std_msgs::msg::Int32;
use example_interfaces::srv::{AddTwoInts, AddTwoIntsRequest, AddTwoIntsResponse};

let msg = Int32 { data: 42 };
}

Command Options

nros generate-rust [OPTIONS]

Options:
      --manifest <PATH>       Path to package.xml [default: package.xml]
  -o, --output <DIR>          Output directory [default: generated]
      --config                Generate .cargo/config.toml with [patch.crates-io] entries
      --nano-ros-path <PATH>  Path to nros crates (for config patches, local dev)
      --nano-ros-git          Use nros git repo for config patches (external users)
      --force                 Overwrite existing bindings
  -v, --verbose               Enable verbose output

Generated Output Structure

my_project/
├── package.xml              # Your dependency declarations
├── Cargo.toml               # Your package manifest
├── src/
│   └── main.rs              # Your code using generated types
├── generated/               # Generated bindings (do not edit)
│   ├── std_msgs/
│   │   ├── Cargo.toml
│   │   └── src/
│   │       ├── lib.rs       # #![no_std]
│   │       └── msg/
│   │           ├── mod.rs
│   │           └── int32.rs
│   └── builtin_interfaces/  # Transitive dependency
│       └── ...
└── .cargo/
    └── config.toml          # [patch.crates-io] entries

Generated Code Features

no_std by default:

#![allow(unused)]
#![no_std]

fn main() {
pub mod msg;
}

std feature for optional std support:

[features]
default = []
std = ["nros-core/std", "nros-serdes/std"]

heapless types for embedded:

#![allow(unused)]
fn main() {
pub struct String {
    pub data: heapless::String<256>,
}

pub struct Arrays {
    pub data: heapless::Vec<i32, 64>,
}
}

Service types with Request/Response:

#![allow(unused)]
fn main() {
pub struct AddTwoInts;
pub struct AddTwoIntsRequest { pub a: i64, pub b: i64 }
pub struct AddTwoIntsResponse { pub sum: i64 }

impl RosService for AddTwoInts {
    type Request = AddTwoIntsRequest;
    type Reply = AddTwoIntsResponse;
}
}

Standalone Package Mode

Examples are configured as standalone packages (excluded from workspace) because each has its own .cargo/config.toml patches. Build each example from its own directory:

cd examples/native/rust/talker && cargo build --features zenoh
cd examples/native/rust/service-client && cargo build --features zenoh

Regenerating Bindings

To regenerate after ROS package updates or dependency changes:

nros generate-rust --force

Bundled Interfaces

nros ships standard .msg files for common packages so codegen works without a ROS 2 environment:

• std_msgs (Bool, Int32, String, Header, etc.)
• builtin_interfaces (Time, Duration)

These are located at packages/codegen/interfaces/. When a ROS 2 environment is sourced, the ament index takes precedence over bundled files.

Troubleshooting

“Package ‘X’ not found in ament index or bundled interfaces”

• For standard types (std_msgs, builtin_interfaces): should work without ROS 2
• For other packages: source ROS 2 environment: source /opt/ros/humble/setup.bash
• Check package is installed: ros2 pkg list | grep X
• Install if missing: sudo apt install ros-humble-X

Build errors with generated code

• Regenerate with --force flag
• Check nros crate compatibility

C Code Generation (CMake)

The nano_ros_generate_interfaces() CMake function generates C bindings for .msg, .srv, and .action files. It uses a bundled codegen library — no external nros binary needed.

Prerequisites

nano_ros_generate_interfaces() becomes available automatically once the consumer’s CMakeLists.txt invokes add_subdirectory(nano-ros). The codegen tool ships inside the in-tree nros CLI binary (packages/cli/target/release/nros, Phase 218; Phase 195.D had retired the nros-codegen submodule); cmake auto-resolves it from PATH / packages/cli/target/release/ / the transitional ${NROS_HOME:-~/.nros}/bin/. No separate build step.

Usage

See examples/native/c/custom-msg/CMakeLists.txt for a complete example.

Configuration Guide

nano-ros config is language-agnostic and has one home per concern — no setting lives in two places. Workspace/system config lives in Cargo.toml metadata (Rust) or CMake (C/C++) plus a universal system.toml; nros.toml is narrowed to the embedded direct-mode runtime file a single-node app’s board parses at boot. This guide covers what each file owns and the nros.toml format.

One home per concern

Boundary rule. If a knob changes what is compiled/linked, it lives in the build file (Cargo.toml feature / CMakeLists.txt option). If it changes the system topology (components, deploy, domain, RMW), it lives in system.toml. If it is what an embedded single-node board does at boot (node identity, transports, RT), it lives in nros.toml.

Config home by language × scale

Mirrors RFC-0004 §3:

The embedded single-node app that hand-writes main() (no codegen) is the case that keeps nros.toml — see below.

Full design rationale: RFC-0004 (configuration & transports); RMW backend selection & lowering is RFC-0031. For the multi-RMW runtime topic-forwarding bridge (a separate file/feature), see nros-bridge.toml — do not confuse it with the embedded-runtime nros.toml.

nros.toml — embedded direct-mode runtime

nros.toml is the embedded direct-mode runtime file for a hand-written single-node app. The board reads it via Config::from_toml (compile-baked with include_str! on embedded; filesystem/env on hosted) — no launch file, no planner, no generated main(). This is what the examples/** copy-out templates use (“boilerplate IS lesson”). It carries [node], [[transport]], and [node.rt] only.

It is not a workspace manifest and not read by nros plan/check/codegen-system — a workspace-root nros.toml is rejected by the CLI (nros migrate workspace). Workspace/system config lives in Cargo.toml metadata + system.toml (see the matrix above). The retired config.toml ([network]/[zenoh]/[scheduling]) was folded into the [node] / [[transport]] / [node.rt] sections here.

Shape

# nros.toml

[node]
domain_id = 0              # ROS 2 domain ID (0–232)
# namespace = "/"
# rmw = "zenoh"            # ACTIVE backend; must match a LINKED backend
                           # (the build file picks what is linked)

# One transport per session. A single ethernet/wifi/serial entry is the
# common case; multiple entries open via Executor::open_multi (multi-homed
# or cross-RMW). In-process topic forwarding is the separate [[bridge]] path.
[[transport]]
kind    = "ethernet"       # ethernet | wifi | serial | can
ip      = "10.0.2.10/24"   # CIDR — the prefix rides the address
mac     = "02:00:00:00:00:00"
gateway = "10.0.2.2"
locator = "tcp/10.0.2.2:7447"
# id      = "eth"          # bind key for multi-transport (defaults to rmw)
# interface = "tap-tx0"    # host interface (threadx-linux)

[node.rt]                  # scheduling / real-time (RTOS); omit for defaults
app_priority         = 12
app_stack_bytes      = 65536
zenoh_read_priority  = 16
zenoh_lease_priority = 16
poll_priority        = 16
poll_interval_ms     = 5

Per-kind transport fields:

ip is CIDR (10.0.2.10/24) — the board derives the prefix or netmask from it. A serial locator carrying # (serial/UART_0#baudrate=115200) is fine — quote it.

How nros.toml is consumed

Rust (board Config::from_toml, compile-baked):

use nros_board_mps2_an385::{Config, run};

fn main() -> ! {
    run(Config::from_toml(include_str!("../nros.toml")), |config| {
        let exec = ExecutorConfig::new(config.zenoh_locator)
            .domain_id(config.domain_id);
        // ...
    })
}

C/C++ (CMake parses it into the NROS_APP_CONFIG struct):

nano_ros_read_config("${CMAKE_CURRENT_SOURCE_DIR}/nros.toml")
# Sets NROS_CONFIG_ZENOH_LOCATOR, NROS_CONFIG_DOMAIN_ID, NROS_CONFIG_IP, …

nros_support_init(&support, NROS_APP_CONFIG.zenoh.locator,
                  NROS_APP_CONFIG.zenoh.domain_id);

nros new scaffolds an nros.toml for embedded targets automatically.

Build-time environment variables

Read during cargo build (by build.rs) or by justfile recipes. Set in .env or export in your shell.

SDK paths

Auto-resolved by just setup <platform>; override if SDKs live elsewhere.

Buffer-tuning vars (ZPICO_*, XRCE_*, NROS_*) are optional — see the Environment Variables Reference.

Binary-size knobs (embedded)

On a constrained MCU, two build-time env vars (set in the example’s .cargo/config.toml [env], like the other NROS_* tuning) shed the parts a brokered client doesn’t need:

Static-heap sizing by backend (bare-metal FreeListHeap, set via NROS_HEAP_SIZE):

Measured footprint

Honest, reproducible numbers per (platform, transport, backend, profile) — built with the in-tree examples, the release profile is cargo’s default (opt-3), the size profile is the scaffolded [profile.size] (opt-s + lto

• strip, see Phase 204.3). RAM = data + bss. All cells are after --gc-sections + the size knobs above are applied where noted; the serial cell ships with the recipe below.

The XRCE row uses the Phase 207.6 tight per-session pools — set in the example’s .cargo/config.toml [env] and read by nros-rmw-xrce-cffi’s build.rs: NROS_XRCE_STREAM_HISTORY=4, NROS_XRCE_CUSTOM_TRANSPORT_MTU=512, NROS_XRCE_MAX_SUBSCRIBERS=1, NROS_XRCE_MAX_SERVICE_SERVERS=1, NROS_XRCE_MAX_SERVICE_CLIENTS=1, NROS_XRCE_SUBSCRIBER_RING_DEPTH=1, NROS_XRCE_BUFFER_SIZE=256. Vendor defaults grow xrce_session_state_t to ~390 KB (which wouldn’t fit a 24 KB heap); these knobs drop it to ~12 KB. Defaults are unchanged for hosted / non-tight-RAM consumers — the env vars are pure opt-in.

How to read this:

• The size profile (opt-s) shrinks .text by ~10–26 % with .bss/.data unchanged (opt-level doesn’t touch static buffers — those are the env knobs above). -Oz is not used — on smoltcp examples it grows .bss +24 KB by defeating opt-3’s per-socket dead-buffer DCE (see Phase 204.3).
• Switching ethernet → serial sheds ~50 KB text + ~42 KB .data (no smoltcp stack, no IP link C, tuned heap) — the structural lever.
• FreeRTOS + lwIP cells .bss is dominated by lwIP’s heap + FreeRTOS task stacks (3 MB is the configured headroom, not nano-ros overhead).
• The micro-ROS / XRCE row is a reference, not a nano-ros measurement — no bare-metal XRCE example ships yet (needs a custom-transport injection); the path to parity is XRCE + serial + static pools.

Size-minimal recipe

Smallest measured nano-ros configuration today (qemu-arm-baremetal serial talker, 116 KB text / 101 KB RAM):

# Cargo.toml
[profile.size]
inherits = "release"
opt-level = "s"
lto = "fat"
codegen-units = 1
debug = false
strip = true

# .cargo/config.toml — gc + serial knobs
[target.thumbv7m-none-eabi]
rustflags = [
    "-C", "link-arg=--gc-sections",   # 204.8 — strip unreferenced fns/data
    "-C", "link-arg=-Tlink.x",
]

[env]
NROS_LINK_IP        = "0"      # 204.7 — drop zenoh-pico TCP/UDP link C
ZPICO_NO_SMOLTCP    = "1"      # skip smoltcp glue on bare-metal
NROS_HEAP_SIZE      = "24576"  # 204.5 — right-size for zenoh-pico working set
NROS_SMOLTCP_MAX_SOCKETS     = "1"   # 204.2 — brokered client multiplexes
NROS_SMOLTCP_MAX_UDP_SOCKETS = "1"

Build with cargo build --profile size, or fleet-wide via NROS_CARGO_PROFILE=size just <plat> build. nros new --platform baremetal already scaffolds the [profile.size] + the .cargo/config.toml shape (Phase 204.7/204.8); uncomment the serial block when you swap to a serial transport.

The deeper RAM win waits on XRCE on bare-metal (the ~3 KB-class client + static pools, with discovery offloaded to the agent) — tracked separately; zenoh-pico’s SUBSCRIBER_BUFFERS + alloc-based session are what keep this row’s .bss ~76 KB.

Cargo features (which RMW/platform is linked)

Features select the linked RMW backend, platform, and ROS edition. The nros.toml node.rmw picks which linked backend is active — the two are different layers (link vs run). Matrix + mutual-exclusion rules: Platform Model.

[dependencies]
nros = { path = "…/nros", default-features = false, features = [
    "rmw-cffi",            # generic C-vtable runtime registry
    "platform-bare-metal", # or platform-{freertos,nuttx,threadx,zephyr,posix}
    "ros-humble",          # or ros-iron
    "std", "alloc",        # optional, target-dependent
] }
# Exactly one RMW backend crate; its registration runs before main:
nros-rmw-zenoh = { path = "…/nros-rmw-zenoh", features = ["platform-bare-metal", "link-tcp", "ros-humble"] }
# …or nros-rmw-xrce-cffi / the cyclonedds CMake backend

Runtime environment (POSIX only)

On Linux/*BSD, ExecutorConfig::from_env() reads at process start (embedded targets bake nros.toml instead):

By deployment scenario

.env

cp .env.example .env   # uncomment + adjust; gitignored; auto-loaded by just + direnv

Logging

nano-ros ships a ROS 2 style leveled logging facade (nros-log) with the same Logger + severity surface as rclcpp::Logger / rcutils_logging. Records flow through a single per-platform sink (PlatformSink) that delegates to whichever nros-platform-<rtos> is linked into the binary.

Severity ladder

REP-2012 style, matching rcutils_log_severity_t:

The numeric representation is stable and used by the nros_platform_log_write ABI.

Quick start

Rust

use nros_log::{Logger, Severity};
use nros_log::{nros_info, nros_warn};

static LOGGER: Logger = Logger::new("my_node");

fn main() {
    nros_log::register_logger(&LOGGER);
    nros_log::init(nros_log::sinks::default());

    nros_info!(&LOGGER, "started; domain = {}", 42);
    nros_warn!(&LOGGER, "queue depth {} exceeds soft limit", 5);
}

Inside a node, prefer the Node::logger() accessor — it resolves to the same intern’d entry when the name matches:

#![allow(unused)]
fn main() {
let mut node = executor.create_node("my_node")?;
nros_info!(node.logger(), "subscribed to {}", topic);
}

C

#include <nros/init.h>
#include <nros/node.h>
#include <nros/log.h>

int main(void) {
    nros_support_t support = nros_support_get_zero_initialized();
    nros_support_init(&support, "tcp/127.0.0.1:7447", 0);

    nros_node_t node = nros_node_get_zero_initialized();
    nros_node_init(&node, &support, "my_node", "/");

    nros_logger_t logger = nros_node_get_logger(&node);
    NROS_LOG_INFO(logger, "started; domain=%u", 42);
    NROS_LOG_WARN(logger, "queue depth %u exceeds soft limit", 5);

    nros_node_fini(&node);
    nros_support_fini(&support);
    return 0;
}

C++

#include <nros/nros.hpp>
#include <nros/log.hpp>

int main() {
    nros::init("tcp/127.0.0.1:7447", 0);

    nros::Node node;
    nros::create_node(node, "my_node");

    auto logger = node.get_logger();
    NROS_LOG_INFO(logger, "started; domain=%u", 42);
    NROS_LOG_WARN(logger, "queue depth %u exceeds soft limit", 5);

    nros::shutdown();
    return 0;
}

The first NROS_LOG_* emit auto-installs PlatformSink so C/C++ call sites work without an explicit init step.

Per-platform delivery

Boards on platforms with no native logger (FreeRTOS / ThreadX / bare-metal Rust ESP32) supply their writer fn-ptr at run() time:

#![allow(unused)]
fn main() {
// from nros-board-mps2-an385-freertos/src/lib.rs
fn register_log_writer() {
    unsafe extern "C" fn writer(severity: u8, name_ptr: *const u8, name_len: usize,
                                 msg_ptr: *const u8, msg_len: usize) { … }
    unsafe { nros_platform_register_log_writer(Some(writer), None); }
}
}

Filtering

Compile-time ceiling

Cargo features on nros-log (pick at most one; default max-level-trace):

Below-ceiling macros expand to (); the format call is dead-code-eliminated.

Runtime per-logger threshold

#![allow(unused)]
fn main() {
let logger = nros_log::get_logger("my_node");
logger.set_level(nros_log::Severity::Warn);   // silences Trace/Debug/Info
}

Default = Severity::Info for any logger constructed via Logger::new(name).

Buffer size

nros-log formats each record into a stack-resident heapless::String<N>. N is picked at compile time by the buffer-size-<N> feature family (default 256). Overflow truncates and appends …; the macro never panics on a long format string.

Interop with the log crate

Enable nros-log/log-compat:

#![allow(unused)]
fn main() {
nros_log::log_compat::install_log_crate_bridge()
    .expect("log crate already initialized");
// Now `log::info!(...)` calls from ecosystem crates flow through
// nros-log's dispatcher.

// Or fan out the other direction — re-emit nros records via `log`:
static SINKS: &[&dyn nros_log::LogSink] = &[
    &nros_log::sinks::PlatformSink,
    &nros_log::log_compat::LogCrateSink,
];
nros_log::init(SINKS);
}

Severity maps Trace↔Trace, Debug↔Debug, Info↔Info, Warn↔Warn, Error↔Error round-trip. Fatal folds into Error one-way (log has no Fatal).

Working examples

• Rust: examples/native/rust/logging/
• C: examples/native/c/logging/
• C++: examples/native/cpp/logging/

Each demonstrates per-severity macros + the runtime threshold filter.

Reference

• packages/core/nros-log/ — facade crate.
• packages/core/nros-platform-cffi/include/nros/platform.h — nros_platform_log_write / nros_platform_log_flush / nros_platform_register_log_writer ABI.
• packages/core/nros-c/include/nros/log.h — C API surface (NROS_LOG_* macros + nros_log_emit_fmt).
• packages/core/nros-cpp/include/nros/log.hpp — C++ macros (the legacy NROS_INFO / etc. file:line printf surface stays alongside the new NROS_LOG_* macros).

/rosout publication is explicitly out of scope today; the dispatcher’s &'static [&dyn LogSink] shape leaves room for an add-later RosoutSink that consumes records alongside PlatformSink.

Profiling Your Build

When a build feels slow, nros-build-profile tells you where the time went — codegen vs compile vs link vs flash, which unit dominated, and whether a shared crate was rebuilt redundantly.

It is a passive, read-only tool. Your build runs exactly as today on its native toolchain (west, cmake, idf.py, cargo); the profiler only reads the timing artifacts that build already produced. It never compiles or flashes anything, and it adds no nros build/test command — nros stays setup + codegen.

How it works

Every backend already emits timing data:

The profiler discovers and parses these, then prints a stage table (always) plus an optional per-unit drill-down and diagnostic hints.

Flow 1 — Zephyr / cmake / esp32-idf (no opt-in)

$ west build -b qemu_cortex_a53 examples/zephyr/rust/talker   # build/.ninja_log written
$ just profile examples/zephyr/rust/talker

Backend: ninja (west)        Total: 41.2s

Stage      Duration    %
codegen        1.1s   3%
compile       33.8s  82%
link           6.0s  15%

hints:
  - 1 unit = 61% of compile (libzenoh_pico.a, 20.6s)

Flow 2 — cargo (one flag for per-crate detail)

The coarse table works with any build; the per-crate drill-down needs --timings:

$ cd examples/native/rust/talker && cargo build --timings   # target/cargo-timings/ written
$ just profile examples/native/rust/talker --deep

Backend: cargo               Total: 30.3s

Stage      Duration    %
codegen        1.2s   4%
compile       24.8s  82%
link           3.9s  13%

slowest units:
  zenoh-pico-sys     18.1s ########
  nros-node           2.4s #
  std_msgs            1.1s #
  <80 more>           3.2s

hints:
  - nros-c compiled 3× — examples use isolated target/; pool target_dir to reuse the build

If you build cargo without --timings, you still get the coarse table plus a note telling you how to enable the drill-down — never an error.

Flow 3 — machine-readable (CI regression diffing)

$ just profile examples/zephyr/rust/talker --deep    # then add --json on the bin, or:
$ ./target/debug/nros-build-profile examples/zephyr/rust/talker --json
wrote examples/zephyr/rust/talker/nros-build-profile.json

A CI step can diff nros-build-profile.json across commits to catch build-time regressions (a stage’s seconds or a unit’s share jumping).

External (copy-out) projects

Copy-out example projects have no justfile. Run the bin directly — same output:

$ nros-build-profile <project-dir> --deep

Diagnostics

On top of the numbers, the profiler flags known slow patterns:

• a large native (C/C++/-sys) unit with no incremental → suggest a compiler cache;
• the same crate compiled more than once → suggest pooling target_dir;
• the configured job count vs available RAM (the fixture-build OOM budget).

Silence them with --no-hints.

Deployment Workflow

Deployment means different things per target, but the order is stable: prepare toolchain, build package, move binary/firmware to target, then verify ROS 2 communication.

POSIX

Three equivalent entry points; pick by workspace shape:

# Per-example (Pattern B or any single binary):
cd examples/native/rust/talker
cargo run

# Multi-component system orchestration:
nros metadata my_system
nros plan my_system launch/my_system.launch.py
nros check
cargo run -p robot_entry

# Colcon consumer workspace (Pattern A):
colcon build && source install/setup.bash
ros2 run my_pkg my_node

For interop with stock ROS 2 over Zenoh, run the bundled router (built by just zenohd setup) and point ROS 2 at it:

zenohd --listen tcp/127.0.0.1:7447
export RMW_IMPLEMENTATION=rmw_zenoh_cpp

See Native POSIX.

RTOS and Bare-Metal

RTOS targets usually produce firmware images or simulator binaries:

just freertos build
just freertos test

For real hardware, deployment step becomes flash/load/monitor. For QEMU, deployment is launching simulator with correct network setup.

There is no nros deploy / nros build / nros run verb — Phase 222 removed those wrappers. nros is provisioner + codegen + metadata only; deployment runs on the vendor’s native tools. The embedded deploy contract is a documented three-step sequence (per RFC-0003 §4):

1. Bake — nros codegen-system --bringup <pkg> reads system.toml + [deploy.<board>] + launch/*.xml and emits the baked tree under build/<board>/.
2. Build — the vendor tool builds it: cargo build / cmake --build / west build / idf.py build (the just <plat> build* recipes wrap these with the right -D args derived from [deploy.<board>]).
3. Flash + monitor — the vendor tool again: probe-rs run / west flash / idf.py flash monitor, or the platform’s QEMU runner.

Platform guides should show:

• package layout,
• setup command,
• toolchain requirements,
• build command,
• run/flash command,
• ROS 2 interop or smoke-test command.

Zephyr

Zephyr deployment uses west:

just zephyr setup
source zephyr-workspace/env.sh
west build -b native_sim/native/64 nros/examples/zephyr/rust/talker
./build/zephyr/zephyr.exe

ESP32

ESP32 deployment uses the Espressif toolchain and flash tool:

just esp32 build
just esp32 talker

For physical boards, use the platform guide’s espflash path.

Verify

After deployment, verify from ROS 2 side:

ros2 topic list
ros2 topic echo /chatter std_msgs/msg/Int32 --qos-reliability best_effort

If discovery works but samples do not arrive, check domain ID, router mode, QoS reliability, and platform network setup.

ROS 2 Interop

nano-ros communicates with standard ROS 2 nodes using the rmw_zenoh_cpp middleware. Both sides connect to the same zenohd router and exchange CDR-encoded messages with compatible key expressions.

Prerequisites

• ROS 2 Humble installed
• rmw_zenoh_cpp package (sudo apt install ros-humble-rmw-zenoh-cpp on Ubuntu, or build from source)
• zenohd router running

Quick Start

Open three terminals:

# Terminal 1: Start the zenoh router
zenohd --listen tcp/127.0.0.1:7447

# Terminal 2: Run the nano-ros talker
cd examples/native/rust/talker
RUST_LOG=info cargo run

# Terminal 3: Run a ROS 2 listener
source /opt/ros/humble/setup.bash
export RMW_IMPLEMENTATION=rmw_zenoh_cpp
export ZENOH_CONFIG_OVERRIDE='mode="client";connect/endpoints=["tcp/127.0.0.1:7447"]'
ros2 topic echo /chatter std_msgs/msg/Int32 --qos-reliability best_effort

You should see the ROS 2 listener printing messages published by nano-ros:

data: 1
---
data: 2
---

The Other Direction

ROS 2 publishers also work with nano-ros subscribers:

# Terminal 2: Run the nano-ros listener instead
cd examples/native/rust/listener
RUST_LOG=info cargo run

# Terminal 3: ROS 2 talker
source /opt/ros/humble/setup.bash
export RMW_IMPLEMENTATION=rmw_zenoh_cpp
export ZENOH_CONFIG_OVERRIDE='mode="client";connect/endpoints=["tcp/127.0.0.1:7447"]'
ros2 topic pub /chatter std_msgs/msg/Int32 "{data: 42}" --qos-reliability best_effort

Discovery

nano-ros publishes ROS 2-compatible liveliness tokens, so standard ROS 2 tools work:

source /opt/ros/humble/setup.bash
export RMW_IMPLEMENTATION=rmw_zenoh_cpp
export ZENOH_CONFIG_OVERRIDE='mode="client";connect/endpoints=["tcp/127.0.0.1:7447"]'

ros2 topic list        # Shows /chatter
ros2 topic info /chatter   # Shows publisher/subscriber count
ros2 node list         # Shows nano-ros nodes

Configuration

Domain ID

Both sides must use the same ROS domain ID. nano-ros reads ROS_DOMAIN_ID from the environment (default: 0):

ROS_DOMAIN_ID=42 cargo run    # nano-ros side
ROS_DOMAIN_ID=42 ros2 topic echo /chatter ...  # ROS 2 side

QoS

nano-ros defaults to BEST_EFFORT reliability and VOLATILE durability. When using ROS 2 subscribers, match the QoS:

ros2 topic echo /chatter std_msgs/msg/Int32 --qos-reliability best_effort

Without --qos-reliability best_effort, ROS 2 defaults to RELIABLE, which won’t match the nano-ros publisher’s BEST_EFFORT QoS.

rmw_zenoh Client Mode

By default, rmw_zenoh_cpp uses peer mode and won’t connect to a zenohd router. Force client mode with:

export ZENOH_CONFIG_OVERRIDE='mode="client";connect/endpoints=["tcp/127.0.0.1:7447"]'

Set this before any ros2 command.

Protocol Details

nano-ros uses the same wire format as rmw_zenoh_cpp:

• Data key expression: <domain_id>/<topic>/<type>/TypeHashNotSupported (Humble). Example: 0/chatter/std_msgs::msg::dds_::Int32_/TypeHashNotSupported
• Liveliness tokens: @ros2_lv/<domain>/<zid>/0/... for discovery
• Message encoding: CDR little-endian with 4-byte encapsulation header [0x00, 0x01, 0x00, 0x00]
• RMW attachment: 33-byte metadata (sequence number, timestamp, GID) appended via Zenoh attachment

ROS 2 Iron and Beyond

Iron uses actual type hashes (RIHS01_<sha256>) instead of TypeHashNotSupported. nano-ros currently supports Humble only. Iron support is planned.

Troubleshooting

Topic not visible in ros2 topic list: Ensure both nano-ros and ROS 2 use the same domain ID and that rmw_zenoh_cpp is in client mode pointing to the same router.

Discovery works but no messages received: Check that the QoS matches. Use --qos-reliability best_effort on the ROS 2 side.

rmw_zenoh not connecting: Verify ZENOH_CONFIG_OVERRIDE is set. Without it, rmw_zenoh uses peer mode and won’t find the router.

Next Steps

• Architecture — understand the layer model
• RMW Zenoh Protocol — full wire format reference

RMW Backends: Zenoh, XRCE-DDS, Cyclone DDS

nano-ros supports three RMW (ROS Middleware) backends for connecting embedded devices to a ROS 2 network. Each backend targets different deployment scenarios and resource constraints. Each Node picks its backend at build time; one binary can link multiple backends and bridge between them — see Cross-backend Bridges for the multi-RMW pattern.

Zenoh (rmw-zenoh)

The Zenoh backend uses zenoh-pico, a lightweight C client for the Zenoh protocol. The MCU participates directly in the Zenoh network – there is no protocol translation layer.

How it works:

1. The MCU runs zenoh-pico in client mode, connecting to a zenohd router process over TCP, UDP, or TLS.
2. zenoh-pico creates publishers and subscribers directly on the Zenoh network.
3. ROS 2 nodes running rmw_zenoh_cpp connect to the same zenohd router, enabling transparent interop.
4. In peer mode, two zenoh-pico devices can communicate directly without any router.

Key characteristics:

• Peer-to-peer capable (no mandatory bridge process)
• zenohd is a generic router, not a protocol translator – it forwards messages without interpreting them
• If zenohd crashes, peers in client mode lose routing but the MCU continues running
• Full ROS 2 graph discovery via liveliness tokens
• Transport options: TCP, UDP, TLS (via zpico-smoltcp or platform sockets)

XRCE-DDS (rmw-xrce)

The XRCE-DDS backend uses Micro-XRCE-DDS-Client, the same client library used by micro-ROS. It follows an agent-based model where a lightweight client on the MCU delegates entity creation to an agent process.

How it works:

1. The MCU runs the XRCE-DDS client, connecting to an Agent process over UDP or serial (UART).
2. The client sends requests to the Agent: “create a publisher on topic X with type Y.”
3. The Agent creates full DDS entities on behalf of the client and bridges data between the XRCE protocol and the DDS data space.
4. ROS 2 nodes using any DDS-based RMW (FastDDS, Cyclone DDS) communicate through the Agent.

Key characteristics:

• Agent is mandatory – the MCU cannot participate in the network without it
• If the Agent crashes, the MCU loses all connectivity
• Fully static memory allocation on the MCU (no heap required)
• Client-side discovery is not supported; the Agent handles it
• Transport options: UDP, serial (HDLC framing), CAN FD

Cyclone DDS (rmw-cyclonedds)

Maturity status. Cyclone DDS support is pub/sub-only today. Service create / recv / reply returns NROS_RMW_RET_UNSUPPORTED; status events (liveliness, deadline-miss, etc.) are not wired to Cyclone listeners yet. Wire-level interop with stock rmw_cyclonedds_cpp (Humble) works for topic publishing and subscribing. If your fleet needs RPC or lifecycle events over Cyclone, use Zenoh instead until the gaps close. Full known-limitations list: docs/reference/cyclonedds-known-limitations.md.

The Cyclone DDS backend uses Eclipse Cyclone DDS, the same DDS implementation that ROS 2 ships with via rmw_cyclonedds_cpp. Built as a standalone C++ library at packages/dds/nros-rmw-cyclonedds/ that registers itself with the runtime through the C ABI vtable in nros-rmw-cffi.

How it works:

1. The application (or platform) calls nros_rmw_cyclonedds_register() once before nros::init() — this is automatic when the consumer’s CMake build sets -DNANO_ROS_RMW=cyclonedds.
2. The runtime stores the vtable pointer; subsequent nros::init() calls dispatch through it for session, publisher, subscriber, and service operations.
3. dds_create_domain / dds_create_participant / dds_create_topic / dds_create_writer / dds_create_reader are invoked under the hood; Cyclone owns its own RX threads.
4. ROS 2 nodes using stock rmw_cyclonedds_cpp interoperate directly — same wire protocol, same discovery, no key rewriting (unlike rmw_zenoh’s <domain>/<topic>/<type>/... scheme).

Key characteristics:

• Pure-C++ backend (not a Cargo crate) — Autoware contributors can read and extend the wrapper using the same patterns as actuation_module/include/common/dds/.
• ROS 2 Tier-1 wire compat — pinned to Cyclone DDS tag 0.10.5 to match ros-humble-cyclonedds 0.10.5 + ros-humble-rmw-cyclonedds-cpp 1.3.4.
• Static ddsi_config via dds_create_domain_with_rawconfig skips the XML parser; embedded-friendly.
• Discovery via SPDP multicast or unicast peer list (mirrors Cyclone’s standard config knobs).
• Heap required (Cyclone uses malloc); BUILD_SHARED_LIBS=ON produces libddsc.so for POSIX, static link for embedded.
• No services / actions yet — service create/recv/reply currently returns NROS_RMW_RET_UNSUPPORTED.
• No status events yet — register_subscriber_event / register_publisher_event / assert_publisher_liveliness slots are not wired to Cyclone listeners yet.

Build:

just cyclonedds setup       # build Cyclone DDS from third-party/dds/cyclonedds (tag 0.10.5)
just cyclonedds build-rmw   # build packages/dds/nros-rmw-cyclonedds
just cyclonedds test        # run the CTest harness

Each example picks its RMW via -DNANO_ROS_RMW=cyclonedds at configure time; the root CMakeLists.txt add_subdirectory’s packages/dds/nros-rmw-cyclonedds/ and links the resulting target into NanoRos::NanoRos. No build/install/ prefix, no find_package(NrosRmwCyclonedds) deleted both.

Availability follows from config — the build provisions Cyclone. Selecting cyclonedds (-DNANO_ROS_RMW=cyclonedds / --features rmw-cyclonedds) is your whole responsibility; nros_provide_cyclonedds() resolves the library: a prebuilt install you point at (-DCMAKE_PREFIX_PATH=<install> / -DCycloneDDS_DIR=), else self-provision from source — by default the pinned third-party/dds/cyclonedds submodule, or your own checkout via -DCYCLONEDDS_SOURCE_DIR=<path>. So a bare cmake/cargo build needs no just cyclonedds pre-step; freertos / threadx-rv64 / native examples build Cyclone on demand (sccache-accelerated), gated on the relevant cross toolchain. On a tier without the toolchain, the embedded-Cyclone tests are filtered out of test-all (skipped, not failed). idlc is a host tool, found on PATH (e.g. a ROS 2 install) or via -DIDLC_EXECUTABLE=. See docs/development/sdk-tiers.md § “CycloneDDS — self-provisioned in CMake”.

Known limitations. Cyclone DDS currently has a 2× CDR roundtrip per message, deferred status-event wiring, pending service request-id correlation, and incomplete Cortex-A/R Zephyr board support. See docs/reference/cyclonedds-known-limitations.md for the full list. ARMv8-R toolchain prep (Cortex-A 64-bit FVP, Cortex-R52 hardware) is in docs/reference/zephyr-armv8r-setup.md.

Comparison

Multi-backend binaries (bridges)

A single nano-ros binary can link more than one RMW backend and forward traffic between them. The bridge pattern is useful for:

• Translating between protocols — a gateway node running zenoh ingress + DDS egress lets MCU fleets on zenoh-pico talk to an Autoware stack on Cyclone DDS without a separate translator.
• Hard-real-time + best-effort split — a high-priority Node on Cyclone DDS for control loops, a low-priority Node on Zenoh for telemetry, both in one process.
• Bringing up an XRCE Agent-free fleet — bridge XRCE devices to a Zenoh network so they look like first-class participants to stock ROS 2.

The pattern uses Executor::open_with_rmw("<name>", ...) to pin the primary session and node_builder("name").rmw("<other>").build() to open additional sessions on other backends. Both backends must be in the binary’s link line (Cargo manifest deps + register() call each).

A worked example lives at examples/bridges/native-rust-zenoh-to-dds/; the time-triggered variant under examples/bridges/tt-zenoh-to-xrce/ shows the same pattern under an ARINC-653-style cyclic schedule.

Full walkthrough: Cross-backend Bridges.

RMW Selection

RMW selection is a declared, language-agnostic, per-deploy value — you set it once in system.toml ([system].rmw, optionally overridden per target by [deploy.<t>].rmw) or via a CLI/build flag, and the toolchain lowers that declaration to each language’s native build mechanism: a Rust cargo rmw-<x> feature, or a CMake -DNANO_ROS_RMW cache var. The cargo feature and the CMake var below are the lowering targets the build uses — not the user-facing knob. A binary links the common rmw-cffi runtime plus exactly one backend; the linked backend self-registers through the nros_rmw_vtable_t C ABI, and the registry walker resolves it at Executor::open. See RFC-0031 for the full selection-and-lowering model and precedence rules.

Cargo.toml (Rust)

Lowered form of the declared RMW: add nros with the platform feature plus exactly one nros-rmw-<x> shim dep (cyclonedds is the exception — see below):

# Zenoh backend
[dependencies]
nros = { path = "<...>/packages/core/nros",
         default-features = false,
         features = ["std", "rmw-cffi", "platform-posix"] }
nros-rmw-zenoh = { path = "<...>/packages/zpico/nros-rmw-zenoh",
                   features = ["std", "platform-posix", "ros-humble"] }

# XRCE-DDS backend
[dependencies]
nros = { path = "<...>/packages/core/nros",
         default-features = false,
         features = ["std", "rmw-cffi", "platform-posix"] }
nros-rmw-xrce-cffi = { path = "<...>/packages/xrce/nros-rmw-xrce-cffi",
                       features = ["std"] }

# Cyclone DDS backend — Rust runtime sees the generic rmw-cffi C-ABI
# vtable; actual Cyclone wiring lives C++-side under
# packages/dds/nros-rmw-cyclonedds/ and is selected at CMake
# configure time via -DNANO_ROS_RMW=cyclonedds. The Rust
# manifest only carries the `rmw-cffi` feature; no Rust shim dep.
[dependencies]
nros = { path = "<...>/packages/core/nros",
         default-features = false,
         features = ["std", "rmw-cffi", "platform-posix"] }

Each example also calls <backend>::register() from main() before Executor::open — this drags the rlib’s CGU into the binary so the linkme distributed-slice walker finds the backend. C/C++ builds rely on the CMake-emitted strong stub from nano_ros_link_rmw(... RMW <x>) instead.

For C++ consumers, the declared RMW lowers to the CMake cache var:

cmake -S . -B build -DNANO_ROS_RMW=cyclonedds  # zenoh / xrce / cyclonedds

Kconfig (Zephyr)

# Zenoh backend
CONFIG_NROS_RMW_ZENOH=y

# XRCE-DDS backend
CONFIG_NROS_RMW_XRCE=y

# Cyclone DDS backend (Cortex-A/R Zephyr targets)
CONFIG_NROS_RMW_CYCLONEDDS=y

Enabling more than one simultaneously produces a compile_error!().

Cyclone DDS — per-platform configuration profile

The Cyclone DDS backend speaks raw RTPS over UDP multicast and unicast. The host networking stack on every RTOS needs IGMP enabled, adequate net- buffer pool sizing for the SPDP / SEDP discovery burst, and a way to join a multicast group. Concrete deltas per platform:

Zephyr (platform-zephyr)

# IGMP for SPDP multicast discovery (239.255.0.1:7400+).
CONFIG_NET_IPV4_IGMP=y

# Multicast group slots — RTPS uses up to 4 builtin groups per
# participant (SPDP + SEDP pubs / subs / topics).
CONFIG_NET_IF_MCAST_IPV4_ADDR_COUNT=4

# Net-buffer pools — defaults of 14 / 36 are too small for the SEDP
# burst when more than two service / action entities exist on each
# participant. Symptom of undersizing: runtime starvation as the
# discovery exchange backs up. Cortex_a9 has 512 MB SRAM; the cost
# is trivial.
CONFIG_NET_PKT_RX_COUNT=256
CONFIG_NET_PKT_TX_COUNT=128
CONFIG_NET_BUF_RX_COUNT=512
CONFIG_NET_BUF_TX_COUNT=256
CONFIG_NET_BUF_DATA_SIZE=512

# Heap — Cyclone DDS (malloc) + heapless mailboxes.
CONFIG_COMMON_LIBC_MALLOC_ARENA_SIZE=4194304
CONFIG_HEAP_MEM_POOL_SIZE=524288

On qemu_cortex_a9, additionally use a board overlay to bump the GEM driver’s RX / TX descriptor ring (default 32) so a brief drainer pause doesn’t immediately spill:

&gem0 {
    promiscuous-mode;
    rx-buffer-descriptors = <128>;
    tx-buffer-descriptors = <64>;
};

native_sim is not yet supported — Zephyr’s NSOS driver doesn’t forward IP_ADD_MEMBERSHIP to the host kernel (no IPPROTO_IP case in nsos_adapt_setsockopt). Use qemu_cortex_a9 for DDS-on-Zephyr testing instead.

FreeRTOS + lwIP (platform-freertos)

// FreeRTOSConfig.h / lwipopts.h
#define LWIP_IGMP            1   // SPDP multicast
#define LWIP_SO_RCVTIMEO     1   // Cyclone DDS recv timeouts
#define LWIP_BROADCAST       1
#define IP_REASSEMBLY        1   // RTPS DATA_FRAG fragments
#define MEMP_NUM_NETBUF      32  // discovery burst headroom

NuttX (platform-nuttx)

CONFIG_NET_IGMP=y
CONFIG_NET_BROADCAST=y
CONFIG_NET_UDP_NRECVS=4
CONFIG_NET_RECV_TIMEO=y

ThreadX + NetX Duo (platform-threadx)

tx_user.h / nx_user.h:

#define NX_ENABLE_IGMPV2          // IGMP v2 for RTPS multicast
// NetX BSD layer init must call `bsd_initialize` early — required
// for `setsockopt(SO_RCVTIMEO)` support.

Bare-metal smoltcp (platform-mps2-an385, platform-stm32f4,

platform-esp32-qemu)

#![allow(unused)]
fn main() {
// Bridge config in the board crate.
let mut config = smoltcp::iface::Config::new(...);
config.multicast_groups = vec![Ipv4Address::new(239, 255, 0, 1)];
// MulticastConfig::Strict in smoltcp 0.x; the bridge must expose
// a `join_multicast_group` API.
}

POSIX (platform-posix)

No configuration needed — the kernel does IGMP and setsockopt support natively. Just ensure the loopback interface is up (default).

When to Use Which

Choose Zenoh when:

• You need ROS 2 interop with rmw_zenoh_cpp (the recommended ROS 2 middleware for Jazzy+)
• You want peer-to-peer communication without any bridge process
• Your MCU has at least ~16 KB of heap and ~100 KB of flash
• You are using TCP or UDP networking
• You want simpler deployment (zenohd is a single binary with no configuration required)

Choose XRCE-DDS when:

• Your MCU has very limited RAM (under 8 KB available for middleware)
• You need serial (UART) transport – useful for MCUs without networking hardware
• You are integrating with an existing micro-ROS or DDS deployment
• You want zero heap allocation on the MCU side
• You need CAN FD transport

Choose Cyclone DDS when:

• You want direct, brokerless ROS 2 interop with no zenohd and no Agent
• Your MCU has at least ~32 KB RAM (heap for Cyclone + RTPS state) and a network stack with IGMP
• You’re integrating with a DDS-based ROS 2 deployment running stock rmw_cyclonedds_cpp and want full RTPS wire-compat without protocol translation
• Your tolerance for failure is “samples from peer X stop arriving” rather than “the whole router goes down”
• Note: Cyclone DDS is pub/sub-only today (no services / actions yet)

Any of the three works well for:

• Standard pub/sub and service patterns
• Integration with ROS 2 desktop nodes
• QEMU-based development and testing

Cross-backend bridges

Most nano-ros applications pick one RMW backend at compile time and never look back. A cross-backend bridge is the one case where a single binary needs two backends in parallel — one node receiving on backend A, another publishing on backend B, the executor draining both each tick.

Typical reasons:

• Drone link. A flight controller speaks XRCE-DDS over a serial radio link; the ground-station LAN runs standard DDS. A bridge forwards telemetry verbatim between the two.
• Field gateway. Sensor pods talk zenoh-pico over an unreliable Wi-Fi mesh; the ROS 2 datacenter side wants Cyclone DDS. A bridge republishes after a session-buffered drop check.
• Safety carve-out. Mission-critical traffic stays on the deterministic backend; introspection / logging republishes to a best-effort backend so dashboards never starve the critical pipeline.

This chapter walks the model, the build knobs, and the three shipped examples.

The mental model — rclcpp::Node, twice

nano-ros mirrors rclcpp:

Executor exec;                   // owns the primary session
Node ingress = exec.node_builder("ingress").rmw("xrce").build();
Node egress  = exec.node_builder("egress").rmw("cyclonedds").build();
auto sub = ingress.create_subscription<Foo>(...);
auto pub = egress.create_publisher<Foo>(...);

The executor opens one primary session at open* time. Each extra node_builder(...).rmw(name) call:

1. Looks up name in the registry of linked backends.
2. If name == primary_rmw and the locator matches → the Node binds to the primary session (slot 0). No second session opened.
3. Else → opens a fresh session through that backend’s open_with_rmw and stores it in extra_sessions[N-1]. The new Node’s session_idx = N.

spin_once() drains every session in turn. Handles created through a multi-Session Node route through the node’s resolved session record instead of the legacy support/session pointer kept for single-backend callers.

NodeRecord.session_idx is the dispatch key. Print it to verify which session each Node landed on:

#![allow(unused)]
fn main() {
exec.node(node_in).unwrap().session_idx   // 0 = primary
exec.node(node_out).unwrap().session_idx  // 1 = first extra
}

Build knobs — three audiences, three shapes

Rust binary

Add both backend crates to Cargo.toml and call each register() early in main:

[dependencies]
nros            = { ..., features = ["rmw-cffi"] }
nros-rmw-zenoh  = { ... }
nros-rmw-xrce-cffi = { ... }

fn main() {
    nros_rmw_zenoh::register().expect("register zenoh");
    nros_rmw_xrce_cffi::register().expect("register xrce");
    let mut exec = nros::Executor::open_with_rmw("zenoh",
        &nros::ExecutorConfig::from_env())?;
    let ingress = exec.node_builder("ingress").rmw("zenoh").build()?;
    let egress  = exec.node_builder("egress").rmw("xrce").build()?;
    // ...
}

Why explicit register()? Stable Rust drops un-referenced rlib CGUs from the final link even when the backend’s #[used] static RMW_INIT_ENTRIES exists. The register() call doubles as the symbol reference that drags the rlib in and the registration trigger. C / C++ builds dodge this because --whole-archive pulls every section unconditionally.

C binary

NANO_ROS_RMW=none switches off the root CMake’s RMW auto-pull. Pull each backend’s staticlib through corrosion_import_crate and wrap with --whole-archive so the registry walker finds both names:

set(NANO_ROS_RMW none)
add_subdirectory(${nano_ros_root} nano_ros)

corrosion_import_crate(
    MANIFEST_PATH ${nano_ros_root}/Cargo.toml
    CRATES nros-rmw-xrce-cffi
    NO_DEFAULT_FEATURES
    FEATURES std)
corrosion_import_crate(
    MANIFEST_PATH ${nano_ros_root}/Cargo.toml
    CRATES nros-rmw-zenoh-staticlib
    NO_DEFAULT_FEATURES
    FEATURES "platform-posix;ros-humble")

target_link_libraries(my_bridge PRIVATE
    NanoRos::NanoRos
    -Wl,--whole-archive
    nros_rmw_xrce_cffi-static
    nros_rmw_zenoh_staticlib-static
    -Wl,--no-whole-archive)

Then declare + call the register functions early in nros_app_main:

extern int8_t nros_rmw_xrce_register(void);
extern int8_t nros_rmw_zenoh_register(void);

int nros_app_main(int argc, char** argv) {
    if (nros_rmw_xrce_register() != 0)  return 1;
    if (nros_rmw_zenoh_register() != 0) return 1;
    // ... nros_support_init / nros_executor_init / nros_executor_node_init
}

nros_executor_node_init honours per-Node rmw_name + locator via the nros_node_options_t struct; the executor sets node.executor so subsequent nros_*_init calls (publisher, subscription, service, action) route to the right session.

C++ binary

Same CMake shape as C. The C++ surface (nros-cpp) is a thin header layer; the linker work is identical. Use the Executor::node_builder(name) chain:

auto exec = nros::Executor::open_with_rmw("zenoh", cfg);
auto ingress = exec.node_builder("ingress").rmw("zenoh").build();
auto egress  = exec.node_builder("egress").rmw("xrce").build();
auto pub = egress.create_publisher<std_msgs::String>("/chatter");
exec.register_subscription_on<std_msgs::String>(ingress, "/chatter",
    [&pub](const auto& msg) { pub->publish(msg); });

NROS_RMW environment variable

When a binary links multiple backends, set NROS_RMW to pin the primary before open():

NROS_RMW=zenoh ./my_bridge

The C-side nros_support_init reads it and routes Executor::open through open_with_rmw(name, ...). Without this, the linkme walker returns whichever backend’s ctor fired first, which is non-deterministic across link orderings. The bridge then opens another session against the same backend when the per-Node .rmw(name) matches the unintended primary — and most singleton-state backends (XRCE-DDS-Client’s uxrSession, zenoh-pico’s global g_session) refuse a second open.

The Rust path mirrors this: Executor::open consults $NROS_RMW first; the per-Node resolve_session_slot detects the primary-name match and returns slot 0 instead of opening a duplicate.

Memory + WCET budget

Each extra session adds:

• One ConcreteSession (RMW-specific; see RMW Backends for sizing).
• One register_wake_signal_on_extra wake-callback slot (std only; bare-metal targets share the primary wake).
• One round-trip through spin_once per backend per tick.

The bridge’s per-tick WCET is the sum across linked backends:

bridge_wcet = Σ poll_wcet_i + Σ dispatch_wcet_j

Read the per-backend numbers in the Real-time budget per backend table and add them up — there is no parallelism between backends inside a single executor.

For deadline-critical bridges, partition by SchedContext instead of running everything on the default Fifo slot:

#![allow(unused)]
fn main() {
let ingress = exec.node_builder("ingress")
    .rmw("xrce")
    .sched(critical_sc)   // RT priority
    .build()?;
let egress = exec.node_builder("egress")
    .rmw("cyclonedds")
    .sched(best_effort_sc)
    .build()?;
}

The PiCAS-style per-callback OS-priority dispatcher (gated behind the scheduler-os-priority feature) routes each Node’s callbacks to its own OS priority slot so the slow backend cannot block the fast one.

Shipped examples

examples/bridges/tt-zenoh-to-xrce/

Pure-Rust bridge. Zenoh ingress → XRCE-DDS egress under an ARINC-653-style time-triggered cyclic schedule. Read this first — it shows the multi-RMW Executor::open_with_rmw("zenoh", ...) plus node_builder.rmw("xrce") per-session pin, with raw byte forwarding and no codegen.

zenohd --listen tcp/127.0.0.1:7447 &
build/xrce-agent/MicroXRCEAgent udp4 -p 8888 &
NROS_XRCE_LOCATOR=udp/127.0.0.1:8888 \
    cargo run -p native-rs-bridge-tt-zenoh-to-xrce

examples/bridges/tt-zenoh-to-cyclonedds/

The stock-Cyclone-DDS sibling: same TT schedule, but the egress is .rmw("cyclonedds"), forwarding onto the DDS databus where a stock rmw_cyclonedds_cpp (e.g. an Autoware listener) or another nano-ros cyclonedds node receives the samples. One structural difference from the XRCE variant: Cyclone rejects a raw publisher whose topic type has no registered dds_topic_descriptor_t, so the egress type’s schema is staged before the raw publisher is created —

#![allow(unused)]
fn main() {
// The Cyclone backend installs the registrar during its register():
nros_rmw_cyclonedds_sys::register()?;
// Stage std_msgs/msg/String's schema (NUL-terminated key — it is handed
// straight to Cyclone's C descriptor table):
nros_rmw::register_type_descriptor(
    "std_msgs/msg/String\0",
    &[nros_serdes::schema::Field { name: "data\0", ty: FieldType::String, offset: 0 }],
)?;
let pub_out = node_out.create_publisher_raw("/chatter", "std_msgs/msg/String", hash)?;
}

XRCE registers lazily from name+hash; Cyclone needs the descriptor up front. The backend links the vendored CycloneDDS (no -DNANO_ROS_RMW needed for the Rust binary — the nros-rmw-cyclonedds-sys dep is the selection).

zenohd --listen tcp/127.0.0.1:7447 &
ROS_DOMAIN_ID=0 cargo run -p native-rs-bridge-tt-zenoh-to-cyclonedds
# subscribe on Cyclone DDS /chatter (stock ROS 2 or a nano-ros cyclone node on
# the same ROS_DOMAIN_ID) and publish on zenoh /chatter to see bridged samples.

Coverage matrix

Bridge examples live under examples/bridges/<name>/ (cross-platform, transport- spanning) or under their canonical examples/<plat>/<lang>/bridge/<name>/ cell when the bridge is platform-specific. The examples README coverage matrix lists which <plat> × <lang> combinations ship a bridge today (a bridge spans RMW backends by nature, so RMW is not a directory axis).

Troubleshooting

See also

• Choosing an RMW Backend — single- backend selection criteria.
• RMW Backends — Host-Language Policy — registry + per-backend sizing.
• docs/roadmap/archived/phase-104-multi-backend-bridges.md — design rationale + acceptance criteria.
• docs/roadmap/archived/phase-156-bridge-runtime-blockers.md — the four sub-bugs that gated the D.3 / D.4 E2E tests + how each was resolved.

QoS, Status Events, and Discovery

This page covers runtime event behavior that application authors need after choosing an RMW backend: liveliness, deadline misses, lost messages, and the places where nano-ros deliberately differs from standard ROS 2 waitset-style event handling.

Transport-level status events let an application observe conditions the underlying middleware detects: a remote node going silent, a publisher missing its rate, a subscriber dropping samples. nano-ros exposes a Tier-1 subset useful for embedded RTOS deployments — liveliness changes, deadline misses, and message loss.

This page describes the event surface, the dispatch model, and the patterns that motivate having events at all on RTOS targets.

The Tier-1 events

Five event kinds. Three on subscribers, two on publishers.

Subscriber events

Publisher events

Registering callbacks

Same shape as message callbacks. Register at construction time; callback fires from inside spin_once when the backend detects the event.

Rust

#![allow(unused)]
fn main() {
use core::time::Duration;

let mut sub = node.create_subscription::<SensorReading>("/sensor")?;

// Liveliness — fires when the publisher comes / goes
sub.on_liveliness_changed(|status| {
    if status.alive_count == 0 {
        log::warn!("sensor publisher went silent");
        trigger_failover();
    }
})?;

// Deadline — fires when no sample within 15 ms
sub.on_requested_deadline_missed(Duration::from_millis(15), |status| {
    metric_inc(&LATE_SAMPLE_COUNT, status.total_count_change);
})?;

// Message lost — fires when backend drops a sample
sub.on_message_lost(|status| {
    log::warn!("dropped {} samples", status.total_count_change);
})?;
}

Async equivalents (spin_async / Embassy / tokio):

#![allow(unused)]
fn main() {
let status = sub.next_liveliness_change().await?;
let status = sub.next_deadline_miss().await?;
}

C

static void on_liveliness_changed(
        nros_subscription_t *sub,
        nros_liveliness_changed_status_t status,
        void *user_context) {
    if (status.alive_count == 0) {
        trigger_failover();
    }
}

nros_subscription_set_liveliness_changed_callback(
    sub, on_liveliness_changed, NULL);

Same shape on the four other event kinds. Each returns NROS_RMW_RET_UNSUPPORTED if the active backend doesn’t generate that event.

C++

sub.on_liveliness_changed([&](nros::LivelinessChangedStatus status) {
    if (status.alive_count == 0) trigger_failover();
});

sub.on_requested_deadline_missed(
    std::chrono::milliseconds(15),
    [&](nros::DeadlineMissedStatus status) {
        late_count_ += status.total_count_change;
    });

std::function overloads available with NROS_CPP_STD; freestanding mode uses C function pointers + user-context.

How dispatch works

Events fire from inside drive_io on the executor thread, the same way message callbacks do:

spin_once(timeout)
 └─ session.drive_io(...)
       ├─ backend RX worker detects message → fires message callback
       ├─ backend RX worker detects liveliness change → fires liveliness callback
       ├─ backend timer expires (deadline) → fires deadline callback
       └─ return

Same execution context, same priority, same constraints as message callbacks. The max_callbacks_per_spin knob (see RTOS Cooperation) covers events too — an event callback counts as one against the cap.

This means events get the same scheduling treatment as messages. max_callbacks_per_spin = 1 will fire either one message OR one event per spin_once, whichever the backend has ready first.

Why a callback model, not a waitset

Upstream rmw.h exposes events via a waitset — register an rmw_event_t handle in a waitset, call rmw_wait, then rmw_take_event to pull payload. nano-ros doesn’t have a waitset (see RMW vs upstream Section 4).

Reusing the existing message-callback path avoids introducing the waitset. Trade-off: applications can’t bulk-poll for events. For the Tier-1 set this isn’t load-bearing — events are rare, callbacks are cheap.

Backend support is uneven

Not every backend can generate every event. Apps must handle Unsupported errors when registering:

✓ = wired and tested. 🟡 = surface API works (returns Err while pending), wiring planned. ✗ = not feasible at this layer.

No current backend exposes the full Tier-1 event set through the nano-ros event API. Apps should call Subscriber::supports_event(kind) first or design for graceful fallback.

The Subscriber::supports_event(kind) query lets applications check support before registering:

#![allow(unused)]
fn main() {
if sub.supports_event(EventKind::RequestedDeadlineMissed) {
    sub.on_requested_deadline_missed(...)?;
} else {
    // fallback: app-side timeout monitoring
}
}

Apps that need cross-backend portability code defensively. Apps pinned to one backend can call register-and-unwrap.

What’s deliberately skipped

Three upstream event types are intentionally absent from the API:

*_MATCHED (publication / subscription matched)

Fires when a remote endpoint appears or disappears. Useful for discovery-tracking dashboards and dynamic-topology apps. Static- topology embedded apps don’t benefit; if a use case appears, the event kind is additive.

*_QOS_INCOMPATIBLE

Fires when publisher and subscriber QoS profiles can’t be reconciled. nano-ros surfaces this synchronously at create_publisher / create_subscriber time as NROS_RMW_RET_INCOMPATIBLE_QOS. No runtime event needed; the failure is visible at startup.

*_INCOMPATIBLE_TYPE

Type-hash mismatch. Same: surfaced synchronously as NROS_RMW_RET_TOPIC_NAME_INVALID (or a future NROS_RMW_RET_INCOMPATIBLE_TYPE) at creation. No runtime event.

Patterns

Drone-bridge fail-over on liveliness loss

#![allow(unused)]
fn main() {
let mut sub = node.create_subscription::<VehicleAttitude>("/vehicle_attitude")?;
sub.on_liveliness_changed(|status| {
    if status.alive_count == 0 {
        // PX4 commander.cpp went silent — trigger MRM
        request_minimum_risk_manoeuvre();
    } else if status.alive_count_change > 0 {
        // commander came back online; clear MRM if appropriate
        clear_failover();
    }
})?;
}

This pairs with the cross-backend bridge example pattern.

100 Hz sensor with deadline alarm

#![allow(unused)]
fn main() {
let mut sub = node.create_subscription::<SensorReading>("/imu")?;
sub.on_requested_deadline_missed(
    Duration::from_millis(15),    // expected 100 Hz, allow 15 ms deadline
    |status| {
        if status.total_count_change > 0 {
            log::error!("IMU late: {} missed deadlines", status.total_count_change);
            // Optional: enter degraded-mode controller
        }
    },
)?;
}

Slow-consumer logging

#![allow(unused)]
fn main() {
let mut sub = node.create_subscription::<Pointcloud>("/lidar")?;
sub.on_message_lost(|status| {
    log::warn!("dropped {} pointcloud frames (total: {})",
               status.total_count_change, status.total_count);
    // Tighten downstream filter, reduce work, coalesce, etc.
})?;
}

See also

• RMW API: Differences from upstream rmw.h Section 8 — the design comparison this page expands on.
• RTOS Cooperation — max_callbacks_per_spin treatment of event callbacks.
• Differences from ROS 2 — broader surface comparison.

Serial Transport

This guide covers using serial (UART) transport with nros on embedded targets. Serial transport connects an MCU directly to a zenoh router over UART, without needing an IP stack.

Overview

nros supports two transport mechanisms for connecting embedded devices to a zenoh network:

Serial transport uses zenoh-pico’s built-in COBS framing protocol over UART. No IP stack is required — the MCU sends and receives zenoh frames directly over a serial link to a host running zenohd.

When to Use Serial

• Small MCUs — Cortex-M0/M0+ with no Ethernet MAC and insufficient RAM for smoltcp
• Point-to-point — Direct UART connection to a host, no network infrastructure needed
• Debugging — Serial output is visible in any terminal, easy to inspect
• Mixed topology — Some nodes on Ethernet, others on serial, all bridged through zenohd

Architecture

┌──────────┐     UART      ┌──────────────┐     TCP      ┌──────────┐
│   MCU    │───────────────│   zenohd     │─────────────│  ROS 2   │
│  (nros)  │  COBS frames  │  (router)    │  zenoh net   │  node    │
└──────────┘               └──────────────┘              └──────────┘

The MCU connects to zenohd using a serial/... locator. zenohd bridges serial-connected nodes to the rest of the zenoh network (including ROS 2 nodes using rmw_zenoh).

Platform Support

Serial transport support varies by platform:

On non-bare-metal platforms, serial just works by using a serial/... locator — no extra crates needed. zpico-serial only fills the gap for bare-metal targets where custom FFI symbols replace zenoh-pico’s system layer.

Board Crate Feature Selection

Each board crate uses Cargo features to select the transport:

# Use serial transport (disable default ethernet/wifi)
nros-board-mps2-an385 = { path = "...", default-features = false, features = ["serial"] }

# Use ethernet transport (default)
nros-board-mps2-an385 = { path = "..." }

# Both transports (runtime selection via locator string)
nros-board-mps2-an385 = { path = "...", features = ["serial"] }

Available Features by Board

When both features are enabled, the transport is selected at runtime by the zenoh locator string in Config:

• "tcp/192.0.3.1:7448" → Ethernet/WiFi
• "serial/UART_0#baudrate=115200" → Serial

Quick Start: QEMU Serial Example

1. Build the Serial Talker

cd examples/qemu-arm-baremetal/rust/serial-talker
nros generate-rust
cargo build --release

2. Run in QEMU

cargo run --release

QEMU starts with -serial pty and prints the PTY path:

char device redirected to /dev/pts/3 (label serial0)

3. Connect zenohd

In another terminal, start zenohd with the serial link:

zenohd --connect serial//dev/pts/3#baudrate=115200

The MCU’s messages are now bridged to the zenoh network. Any zenoh subscriber (including ROS 2 nodes) can receive them.

4. Subscribe from Host

# Using zenoh CLI
z_sub -k "0/chatter/**"

# Or from a ROS 2 node
ros2 topic echo /chatter std_msgs/msg/Int32

Configuration

Serial Config

Board crates provide a serial_default() constructor:

#![allow(unused)]
fn main() {
use nros_board_mps2_an385::{Config, run};

let config = Config::serial_default();
// Defaults: baudrate=115200, locator="serial/UART_0#baudrate=115200"

run(config, |config| {
    let exec_config = ExecutorConfig::new(config.zenoh_locator)
        .domain_id(config.domain_id);
    let mut executor = Executor::open(&exec_config)?;
    // ...
    Ok(())
})
}

Custom Baud Rate

#![allow(unused)]
fn main() {
let config = Config::serial_default()
    .with_baudrate(921600)
    .with_zenoh_locator("serial/UART_0#baudrate=921600");
}

Locator Format

Serial locators follow zenoh-pico convention:

QEMU PTY Testing

How It Works

QEMU’s -serial pty flag redirects the emulated UART to a host pseudo-terminal (PTY). This creates a virtual serial port that zenohd can connect to, enabling full end-to-end testing without physical hardware.

┌──────────────────────────────────────────────────────────┐
│                       Host                               │
│  ┌─────────┐    ┌───────────┐    ┌────────────────────┐  │
│  │ zenohd  │◄──►│ /dev/pts/N│◄──►│ QEMU MPS2-AN385   │  │
│  │         │    │  (PTY)    │    │ -serial pty         │  │
│  └────┬────┘    └───────────┘    │ UART0 ──► firmware  │  │
│       │                         └────────────────────┘  │
│       │ zenoh network                                    │
│  ┌────▼────┐                                             │
│  │ z_sub   │                                             │
│  │ or ROS 2│                                             │
│  └─────────┘                                             │
└──────────────────────────────────────────────────────────┘

QEMU Flags

The serial example’s .cargo/config.toml uses:

[target.thumbv7m-none-eabi]
runner = "qemu-system-arm -cpu cortex-m3 -machine mps2-an385 -nographic -semihosting-config enable=on,target=native -serial pty -kernel"

Key flags:

• -serial pty — Expose UART0 as a host PTY
• -nographic — No display window
• -semihosting-config enable=on,target=native — Debug output via semihosting (separate from UART)
• No -netdev / -net — Serial transport doesn’t need Ethernet

-icount shift=auto

For reliable serial communication, add -icount shift=auto to synchronize QEMU’s virtual clock with wall-clock time. Without this, QEMU runs the CPU at full speed, which can cause timing-sensitive serial handshakes to fail:

runner = "qemu-system-arm -cpu cortex-m3 -machine mps2-an385 -nographic -semihosting-config enable=on,target=native -icount shift=auto -serial pty -kernel"

Automated Testing

The integration test test_qemu_serial_pubsub_e2e in packages/testing/nros-tests/tests/emulator.rs automates the full workflow:

1. Build the serial-talker example
2. Launch QEMU with -serial pty
3. Parse the PTY path from QEMU stderr
4. Start zenohd with --connect serial//dev/pts/N#baudrate=115200
5. Subscribe and verify message delivery

Run it with:

just test-qemu

Baud Rate Tuning

Recommended Rates

Higher baud rates increase throughput but may cause framing errors on noisy or long cables. QEMU ignores the baud rate (infinite speed), so rate tuning only matters on physical hardware.

Buffer Sizing

zenoh-pico serial uses a 1500-byte MTU with COBS framing. The maximum wire frame is 1516 bytes. zpico-serial uses a 2048-byte RX ring buffer per port, which accommodates one full frame plus overhead.

For high-throughput scenarios, ensure the MCU’s UART FIFO is drained frequently by calling executor.spin_once() in a tight loop.

Troubleshooting

“Session open failed” or Handshake Timeout

The zenoh serial handshake (Init → Ack) must complete within zenoh-pico’s timeout. Common causes:

• Wrong PTY path — Check that zenohd connects to the correct /dev/pts/N
• Baud rate mismatch — MCU and zenohd must use the same baud rate
• QEMU timing — Add -icount shift=auto to slow down QEMU’s CPU clock

No Messages Received

• Locator mismatch — Ensure the MCU’s zenoh_locator matches what zenohd expects
• Domain ID — Both sides must use the same ROS 2 domain ID
• zenohd not bridging — Verify zenohd is connected to the serial port and also listening on TCP for subscribers

UART Pin Conflicts

On physical hardware, ensure the UART TX/RX pins aren’t shared with the debug console. Some boards use UART0 for debug output — use a different UART for zenoh transport, or disable debug prints.

ESP32 Serial

ESP32 uses zenoh-pico’s built-in ESP-IDF serial implementation. No zpico-serial dependency is needed. Select serial transport in the board crate:

nros-board-esp32-qemu = { path = "...", default-features = false, features = ["serial"] }

The default locator is serial/UART_0#baudrate=115200. ESP32’s USB-JTAG-Serial peripheral or UART0/UART1 can be used.

RTIC Integration

RTIC (Real-Time Interrupt-driven Concurrency) is a concurrency framework for ARM Cortex-M that compiles tasks directly to hardware interrupt handlers — no RTOS kernel, no task control blocks, no software scheduler. nano-ros runs on top of RTIC by letting the framework own fn main, the scheduler, and the dispatchers, while nano-ros contributes one spin task and (optionally) one callback-dispatch task.

This chapter is the user-facing tutorial for that integration. For the underlying design — why per-Node dispatch strategies, why tags instead of closures, why no AsyncNode trait yet — see the sibling internals page Dispatch Strategy.

When to reach for nros::main!() instead of Pattern A

The current in-tree RTIC examples (e.g. examples/stm32f4/rust/talker-rtic/) use the Pattern A escape hatch: hand-written #[rtic::app], manual Executor::open inside #[init], manual spin_once(0) polling task. It looks like this:

#![allow(unused)]
fn main() {
// File: examples/stm32f4/rust/talker-rtic/src/main.rs (today, pre-216.B.5)
#[rtic::app(device = stm32f4xx_hal::pac, dispatchers = [USART1, USART2])]
mod app {
    #[init]
    fn init(cx: init::Context) -> (Shared, Local) {
        let syst = nros_board_stm32f4::init_hardware(&config, cx.device, cx.core);
        nros_rmw_zenoh::register().expect("Failed to register RMW backend");
        let mut executor = Executor::open(&exec_config).unwrap();
        let mut node = executor.create_node("talker").unwrap();
        let publisher = node.create_publisher::<Int32>("/chatter").unwrap();
        net_poll::spawn().unwrap();
        publish::spawn().unwrap();
        (Shared {}, Local { executor, publisher })
    }

    #[task(local = [executor], priority = 1)]
    async fn net_poll(cx: net_poll::Context) {
        loop {
            cx.local.executor.spin_once(core::time::Duration::from_millis(0));
            Mono::delay(10.millis()).await;
        }
    }
}
}

That pattern works, but it’s ~90 lines of glue per binary, and it puts the burden of getting RTIC + nros + the dispatcher list right on every example author. Phase 216.B.5 collapses it to one line:

#![allow(unused)]
fn main() {
// File: examples/stm32f4/rust/talker-rtic/src/main.rs (post-216.B.5)
#![no_std]
#![no_main]

use defmt_rtt as _;
use panic_probe as _;

nros::main!();
}

The nros::main!() proc-macro reads [package.metadata.nros.entry] deploy = "rtic-stm32f4" from the Entry pkg’s Cargo.toml, sees that the board’s metadata declares framework = "rtic", and emits a full #[rtic::app] module — including #[init], __nros_spin, and (if any deployed Node declares DispatchStrategy::Deferred) __nros_dispatch.

Pick nros::main!() whenever:

• You want a one-line main.rs and don’t need custom RTIC tasks.
• Your Node logic is portable across boards (the Node pkg is framework-agnostic; only the Entry pkg picks RTIC).
• You’re happy with the default dispatcher list from the board crate.

Keep Pattern A when:

• You need fine-grained control of dispatcher priorities, monotonic setup, or hand-tuned #[shared] state.
• You’re shipping a one-off bring-up binary and don’t want the Node-pkg / Entry-pkg split overhead.

Both paths stay supported. The escape hatch is the “I want full control” path; nros::main!() is the ergonomic path on top.

The three pkg roles

A nano-ros RTIC workspace is three packages (the 3-pkg-role taxonomy, per docs/design/0024-multi-node-workspace-layout.md §11):

my_rtic_robot/
├── Cargo.toml                         # [workspace] members = [...]
└── src/
    ├── talker_pkg/                    # Node pkg — board-agnostic
    │   ├── package.xml
    │   ├── Cargo.toml
    │   └── src/lib.rs                 # impl Node for Talker + nros::node!(Talker)
    └── talker_entry/                  # Entry pkg — picks RTIC board
        ├── package.xml
        ├── Cargo.toml                 # [package.metadata.nros.entry] deploy = "rtic-stm32f4"
        └── src/main.rs                # nros::main!();

• Node pkg — declares what the node does (publishers, subscriptions, services, actions). No main, no #[rtic::app], no board choice. Builds as rlib + staticlib and gets linked into one or more Entry pkgs.
• Entry pkg — picks the board crate (nros-board-rtic-stm32f4), pins the deploy target, and runs nros::main!();.
• Bringup pkg — optional, only when ≥2 Entry pkgs share the same launch/*.launch.xml topology. Skipped here because we have one binary.

The split exists so the same talker_pkg/ can be deployed under RTIC on STM32F4, under FreeRTOS on QEMU, and under POSIX on a Linux host without any per-target Node-pkg fork.

A minimal Node pkg — pub-only Talker

A pub-only Node declares DispatchStrategy::Inline (the default) — it publishes from its own RTIC task and never enters on_callback.

#![allow(unused)]
fn main() {
// File: src/talker_pkg/src/lib.rs
#![no_std]

use core::time::Duration;
use nros::prelude::*;
use std_msgs::msg::Int32;

pub struct Talker;

pub struct TalkerState {
    publisher: Publisher<Int32>,
    counter: i32,
}

impl Node for Talker {
    const NAME: &'static str = "talker";
    // Inline is the default; spelled out here for clarity.
    const DISPATCH: DispatchStrategy = DispatchStrategy::Inline;

    fn register(ctx: &mut NodeContext<'_>) -> NodeResult<()> {
        ctx.create_publisher::<Int32>("/chatter")?;
        Ok(())
    }
}

impl ExecutableNode for Talker {
    type State = TalkerState;

    fn init() -> Self::State {
        TalkerState { publisher: Publisher::placeholder(), counter: 0 }
    }

    fn tick(state: &mut Self::State, _ctx: &mut TickCtx<'_>) {
        state.counter = state.counter.wrapping_add(1);
        let _ = state.publisher.publish(&Int32 { data: state.counter });
    }

    fn tick_period(_state: &Self::State) -> Option<Duration> {
        Some(Duration::from_millis(1000))
    }
}

nros::node!(Talker);
}

# File: src/talker_pkg/Cargo.toml
[package]
name    = "talker_pkg"
version = "0.1.0"
edition = "2024"

[lib]
crate-type = ["rlib", "staticlib"]

[dependencies]
nros      = { workspace = true, default-features = false }
std_msgs  = { workspace = true }

[package.metadata.nros.node]
class = "talker_pkg::Talker"

The Entry pkg

# File: src/talker_entry/Cargo.toml
[package]
name    = "talker_entry"
version = "0.1.0"
edition = "2024"

[[bin]]
name = "talker_entry"
path = "src/main.rs"

[dependencies]
nros                       = { workspace = true, default-features = false }
nros-board-rtic-stm32f4    = { workspace = true }
talker_pkg                 = { path = "../talker_pkg" }

[package.metadata.nros.entry]
deploy = "rtic-stm32f4"

[package.metadata.nros.deploy.rtic-stm32f4]
board     = "rtic-stm32f4"
rmw       = "zenoh"
domain_id = 0
locator   = "tcp/192.168.1.10:7447"

#![allow(unused)]
fn main() {
// File: src/talker_entry/src/main.rs
#![no_std]
#![no_main]

use defmt_rtt as _;
use panic_probe as _;

nros::main!();
}

That’s the whole Entry pkg. The proc-macro reads deploy = "rtic-stm32f4", looks up the board crate’s framework = "rtic" metadata, and expands into a #[rtic::app(device = ::nros_board_rtic_stm32f4::pac, dispatchers = [USART1, USART2])] module with auto-generated #[init], __nros_spin, and per-Node state slots.

DispatchStrategy::Inline vs Deferred

A Node pkg declares DispatchStrategy via the Node::DISPATCH const. Two variants matter today; FromIsr is reserved as a design slot (see DispatchStrategy::FromIsr).

Inline — pub-only or tick-only Nodes

#![allow(unused)]
fn main() {
impl Node for Talker {
    const NAME: &'static str = "talker";
    const DISPATCH: DispatchStrategy = DispatchStrategy::Inline;
    // ...
}
}

Inline means: callbacks (if any) fire from the executor’s spin loop — the same RTIC task that polls the network transport. On RTIC that’s __nros_spin running at priority = 1.

Pick Inline when:

• The Node has no subscriptions, no service handlers, no action handlers. Its only output is Publisher::publish calls from tick or from a custom RTIC task you spawn yourself.
• The Node has subscriptions, but the per-message work is so cheap (microseconds, no locks, no shared-state touches) that running it inline with the spin loop is acceptable.

The Talker above is the canonical Inline shape: it publishes from tick at 1 Hz, never receives anything, and never blocks the spin loop.

Deferred — callback-driven Nodes

#![allow(unused)]
fn main() {
impl Node for Listener {
    const NAME: &'static str = "listener";
    const DISPATCH: DispatchStrategy = DispatchStrategy::Deferred;
    // ...
}
}

Deferred means: when a callback arrives, the spin loop enqueues a callback token plus context into a heapless::spsc::Queue and returns immediately. A separate __nros_dispatch RTIC task (typically priority = 2, one above spin) drains the queue and calls ExecutableNode::on_callback from its own task context.

Pick Deferred when:

• The Node’s on_callback handler must hold an RTIC lock on a #[shared] resource — running it from the spin task would force every other dispatcher at the spin’s priority to wait on the lock.
• The handler does non-trivial work (parses, integrates, posts to a hardware peripheral) and you want it scheduled independently from network polling.
• The Node sits at a different priority tier than the spin task.

The tag-based registration API for Deferred Nodes

Deferred Nodes can’t use the closure form ctx.create_subscription("/chatter", |msg| { ... }) — the closure captures state by value, and a no-alloc framework runtime has no place to store an unknown closure type. Instead, you register with _static and dispatch via tag match in on_callback:

#![allow(unused)]
fn main() {
// File: src/listener_pkg/src/lib.rs
#![no_std]

use nros::prelude::*;
use std_msgs::msg::Int32;

pub struct Listener;

pub struct ListenerState {
    sub_chatter: SubscriptionTag,
}

impl Node for Listener {
    const NAME: &'static str = "listener";
    const DISPATCH: DispatchStrategy = DispatchStrategy::Deferred;

    fn register(ctx: &mut NodeContext<'_>) -> NodeResult<()> {
        let _tag = ctx.create_subscription_static::<Int32>("/chatter")?;
        Ok(())
    }
}

impl ExecutableNode for Listener {
    type State = ListenerState;

    fn init() -> Self::State {
        // The macro-emitted glue overwrites the placeholder with the
        // real tag at register time.
        ListenerState { sub_chatter: SubscriptionTag::placeholder() }
    }

    fn on_callback(
        state: &mut Self::State,
        cb: Callback<'_>,
        ctx: &mut CallbackCtx<'_>,
    ) {
        if state.sub_chatter == cb {
            let msg: Int32 = ctx.downcast().unwrap();
            defmt::info!("Received: {}", msg.data);
        }
    }
}

nros::node!(Listener);
}

The same shape applies to services (ServiceTag / create_service_static) and actions (ActionTag / create_action_static). The macro lint (216.A.6) rejects mixing closure registration into a Deferred Node — the error spans the offending call and suggests switching to the _static form.

The custom-task escape — nros::main!(custom_tasks = ...)

Coming in Phase 216.B.4. The syntax below is the locked design; it lands after 216.B.3 (the RTIC routing branch of the macro) is in tree.

Real RTIC applications don’t only have nano-ros tasks. You want a dedicated my_adc task to poll an ADC into a #[shared] buffer, or a my_ui task to drive an OLED. The custom_tasks = [...] form of nros::main!() folds your extra task fns into the generated #[rtic::app] module:

#![allow(unused)]
fn main() {
// File: src/talker_entry/src/main.rs (with custom tasks)
#![no_std]
#![no_main]

use defmt_rtt as _;
use panic_probe as _;

nros::main!(custom_tasks = [my_adc, my_ui]);

#[rtic_task(priority = 3, shared = [adc_data])]
async fn my_adc(mut ctx: my_adc::Context) {
    loop {
        let sample = read_adc();
        ctx.shared.adc_data.lock(|d| *d = sample);
        Mono::delay(10.millis()).await;
    }
}

#[rtic_task(priority = 2)]
async fn my_ui(_ctx: my_ui::Context) {
    loop {
        draw_screen();
        Mono::delay(33.millis()).await;
    }
}
}

The proc-macro extracts the user task tokens verbatim, splices them into the generated mod __nros_app, and adds their dispatchers to the RTIC dispatchers = [...] list. Signatures + attributes + priorities are preserved.

Custom tasks can interact with nano-ros via the #[shared] resources the macro exposes — typically executor (the spin executor) for raw publisher access, or a Node’s state slot for direct handler calls. Specifics will be locked when 216.B.4 lands.

DispatchStrategy::FromIsr — not yet

The third variant of DispatchStrategy is reserved for callbacks that fire directly from an ISR handler (e.g. a timer pulse triggering a publish without a scheduler hop). This is a design slot only; the implementation is deferred to Phase 216.E.1.

Landing it requires:

• A reentrancy audit of the dispatch path.
• A lock-free SPSC variant tolerant of ISR-priority producers.
• A per-Node #[isr_safe] proof contract.

Until that work lands, nros check (Phase 216.D.1) rejects DispatchStrategy::FromIsr deployments with a clear diagnostic.

See also

• Dispatch Strategy (internals) — the trichotomy and the per-Node-vs-per-callback rationale.
• Embassy Integration — the async sibling of this chapter.
• Role reference — the 3-pkg-role taxonomy in full.
• Scheduling Models — the RTIC scheduling model in real-time-systems terms.

Embassy Integration

Embassy is an async/await framework for embedded Rust, built around a cooperative executor that polls futures from a single context (per priority tier). nano-ros runs on top of Embassy by letting the framework own fn main, the spawner, and the async executor, while nano-ros contributes one __nros_spin_task async fn and (optionally) one __nros_dispatch_task async fn.

This chapter is the user-facing tutorial for that integration. For the underlying design — why per-Node dispatch strategies, why tags instead of closures, why on_callback stays sync even on async runtimes — see the sibling internals page Dispatch Strategy.

What Embassy buys you and where nano-ros fits

Embassy is an alternative to RTOS-style preemptive tasks: every “task” is an async fn driven by embassy_executor::Spawner::spawn. Tasks yield at .await points; there’s no scheduler tick, no context switch overhead beyond a future poll. For nano-ros that means:

• A natural place for I/O-driven background work (SPI bus servicing, GPIO debounce, sensor frame parsing) that yields at every .await on a embassy_time::Timer or embassy_stm32::spi::Spi::transfer.
• A natural place to spawn downstream work from inside a nano-ros callback — the “spawn-from-sync escape” below.
• Cooperative scheduling means a Node on_callback runs to completion before the executor polls anything else at the same priority. Keep handlers short, hand off long work to a spawned task.

The current in-tree example (examples/stm32f4/rust/talker-embassy/src/main.rs) is Pattern A: hand-written #[embassy_executor::main], hand-written zenoh_poll_task, hand-written publisher_task. It’s a working template but it’s ~150 lines and each example author re-derives the spawn topology. Phase 216.C.4 collapses it to:

#![allow(unused)]
fn main() {
// File: examples/stm32f4/rust/talker-embassy/src/main.rs (post-216.C.4)
#![no_std]
#![no_main]

use defmt_rtt as _;
use panic_halt as _;

nros::main!();
}

The proc-macro reads [package.metadata.nros.entry] deploy = "embassy-stm32f4" from the Entry pkg’s Cargo.toml, sees that the board’s metadata declares framework = "embassy", and expands into a full #[embassy_executor::main] async fn main(spawner: Spawner) including the spin task spawn, the dispatch task spawn, and the run_plan registration call.

Why sync on_callback even on Embassy

A natural-feeling Embassy API would make ExecutableNode::on_callback an async fn. We don’t — for two reasons:

1. The no-alloc contract. Async fns desugar to anonymous future types; storing them generically in the runtime requires either boxing (Box<dyn Future> → alloc dependency) or const-generic GAT plumbing through every trait. Both add cost without buying anything Spawner::spawn doesn’t already give us.
2. Framework-task routing. The runtime already dispatches callbacks from a framework-owned task (__nros_dispatch_task on Embassy, __nros_dispatch on RTIC). The Node author can spawn their own async task from inside the sync on_callback; that task runs under the same executor with no extra plumbing.

So on_callback keeps the same callback-token signature as RTIC, POSIX, and every other backend. The escape for “I need to await something” is the spawn-from-sync pattern below.

AsyncNode (an async-on-callback trait via RPITIT) is reserved as a design slot — see When to wait for AsyncNode at the end of this chapter.

The three pkg roles

The workspace shape is identical to RTIC (the 3-pkg-role taxonomy, per docs/design/0024-multi-node-workspace-layout.md §11):

my_embassy_robot/
├── Cargo.toml                           # [workspace] members = [...]
└── src/
    ├── listener_pkg/                    # Node pkg — board-agnostic
    │   ├── package.xml
    │   ├── Cargo.toml
    │   └── src/lib.rs                   # impl Node for Listener + nros::node!(Listener)
    └── listener_entry/                  # Entry pkg — picks Embassy board
        ├── package.xml
        ├── Cargo.toml                   # [package.metadata.nros.entry] deploy = "embassy-stm32f4"
        └── src/main.rs                  # nros::main!();

The Node pkg stays board-agnostic — listener_pkg/ from the RTIC chapter could be deployed under Embassy by swapping the Entry pkg. That’s the point of the split.

Entry pkg

# File: src/listener_entry/Cargo.toml
[package]
name    = "listener_entry"
version = "0.1.0"
edition = "2024"

[[bin]]
name = "listener_entry"
path = "src/main.rs"

[dependencies]
nros                       = { workspace = true, default-features = false }
nros-board-embassy-stm32f4 = { workspace = true }
listener_pkg               = { path = "../listener_pkg" }

[package.metadata.nros.entry]
deploy = "embassy-stm32f4"

[package.metadata.nros.deploy.embassy-stm32f4]
board     = "embassy-stm32f4"
rmw       = "zenoh"
domain_id = 0
locator   = "tcp/192.168.1.10:7447"

#![allow(unused)]
fn main() {
// File: src/listener_entry/src/main.rs
#![no_std]
#![no_main]

use defmt_rtt as _;
use panic_halt as _;

nros::main!();
}

DispatchStrategy::Deferred is the common case

Every callback-driven Embassy Node should declare DispatchStrategy::Deferred:

#![allow(unused)]
fn main() {
impl Node for Listener {
    const NAME: &'static str = "listener";
    const DISPATCH: DispatchStrategy = DispatchStrategy::Deferred;
    // ...
}
}

Deferred means: the spin task pushes signaled callbacks into an embassy_sync::channel::Channel<NoopRawMutex, _, CHANNEL_CAPACITY> (default capacity 32). A separate __nros_dispatch_task awaits the channel receive end and routes each callback to the right Node’s on_callback. Both tasks run cooperatively on the same Embassy executor; you can spawn your own tasks alongside them.

Inline is allowed but unusual on Embassy:

• The nros check lint (Phase 216.D.1) emits a warning for framework = "embassy" with DispatchStrategy::Inline and suggests switching to Deferred — running callbacks inline on Embassy ties them to the spin task’s poll point, which makes the scheduling cost-vs-benefit confusing.
• If your Node is genuinely pub-only (no subscriptions, no services, no actions), Inline is still fine — the Inline path simply never enters on_callback. The warning above does not apply for pure-publisher Nodes.

The spawn-from-sync escape

Real Embassy Nodes need to do async work downstream from a callback: write to an SPI bus, send a UART frame, poll a sensor with timeout. The pattern is:

1. Hold an embassy_executor::Spawner on Self::State.
2. From inside the sync on_callback, call state.spawner.spawn(handle_downstream(msg)).unwrap().
3. The downstream #[embassy_executor::task] async fn handles the await-heavy work.

Worked example — Listener that writes received data to SPI

#![allow(unused)]
fn main() {
// File: src/listener_pkg/src/lib.rs
#![no_std]

use embassy_executor::Spawner;
use nros::prelude::*;
use std_msgs::msg::Int32;

pub struct Listener;

pub struct ListenerState {
    sub_chatter: SubscriptionTag,
    spawner: Spawner,
}

impl Node for Listener {
    const NAME: &'static str = "listener";
    const DISPATCH: DispatchStrategy = DispatchStrategy::Deferred;

    fn register(ctx: &mut NodeContext<'_>) -> NodeResult<()> {
        let _tag = ctx.create_subscription_static::<Int32>("/chatter")?;
        Ok(())
    }
}

impl ExecutableNode for Listener {
    type State = ListenerState;

    fn init() -> Self::State {
        ListenerState {
            sub_chatter: SubscriptionTag::placeholder(),
            // The macro-emitted glue populates the Spawner from the
            // EmbassyBoardEntry init hook; until then, hold a sentinel
            // that's overwritten before the first dispatch.
            spawner: Spawner::for_current_executor(),
        }
    }

    fn on_callback(
        state: &mut Self::State,
        cb: Callback<'_>,
        ctx: &mut CallbackCtx<'_>,
    ) {
        if state.sub_chatter == cb {
            let msg: Int32 = ctx.downcast().unwrap();
            // Spawn the async work and return immediately. The
            // dispatch task stays unblocked.
            state.spawner.spawn(handle_msg(msg)).unwrap();
        }
    }
}

#[embassy_executor::task(pool_size = 4)]
async fn handle_msg(msg: Int32) {
    // Pretend we have an SPI handle stashed somewhere accessible.
    // The real wiring depends on your peripheral-access pattern;
    // the point is `.await` is free here, even though on_callback
    // is sync.
    defmt::info!("handling /chatter sample: {}", msg.data);
    embassy_time::Timer::after_millis(5).await;
    // spi.write(&msg.data.to_le_bytes()).await.unwrap();
}

nros::node!(Listener);
}

Two things to note:

• Spawner is Copy. Holding a Spawner on Self::State adds no runtime cost beyond an integer copy. You can clone it freely across multiple on_callback calls.
• pool_size matters. #[embassy_executor::task(pool_size = N)] allocates N static slots. If you spawn faster than the spawned tasks complete, spawn(...) returns Err(SpawnError::Busy) — handle it (drop the message, log a warning, etc.). The default is pool_size = 1.

When the spawn pool fills up

Two patterns for backpressure:

1. Drop on full. Treat the spawned task as best-effort. If the spawn returns an error, log it and continue.
2. Channel-based queue. Pre-spawn one long-lived #[embassy_executor::task] async fn that holds an embassy_sync::channel::Channel receive end. The on_callback pushes into the channel’s send end (drop on full or block — your choice). Lets you control queue depth independently of pool_size.

The right pick depends on whether dropped messages are tolerable for your workload; nano-ros doesn’t impose either.

When to wait for AsyncNode

The spawn-from-sync escape covers every case we know of today. But if you find yourself writing a lot of one-off pool-of-one spawn dances — each callback spawning a task whose body is a single .await — that’s a smell, and we’d want to know.

The design slot for direct async callbacks is AsyncNode (Phase 216.E.2):

#![allow(unused)]
fn main() {
// Design sketch — NOT shipping today.
pub trait AsyncNode: 'static {
    const NAME: &'static str;
    const DISPATCH: DispatchStrategy = DispatchStrategy::Deferred;

    fn register(ctx: &mut NodeContext<'_>) -> NodeResult<()>;
    async fn on_callback(
        &mut self,
        callback: AsyncCallbackToken,
        ctx: CallbackCtx,
    );
}
}

It would compile only on Embassy targets (RTIC has no async runtime to drive RPITIT futures into; POSIX + RTOS don’t either), and the nros::node!() macro would emit a separate __nros_node_<pkg>_on_callback_async ABI symbol the Embassy dispatch task picks up. 216.E.2 lands only if real usage shows spawn-from-sync is consistently painful. If your application is hitting that case, file an issue with the call pattern that’s prompting it.

Until then: spawn from sync. It’s two lines per callback and stays fully no-alloc.

See also

• Dispatch Strategy (internals) — the trichotomy and the per-Node-vs-per-callback rationale.
• RTIC Integration — the interrupt-driven sibling of this chapter.
• Role reference — the 3-pkg-role taxonomy in full.
• Scheduling Models — the Embassy cooperative model alongside RTIC, RTOS, and POSIX.

Troubleshooting

Common issues and solutions when working with nros.

zenoh-pico Multiple Client Issues

Symptoms

When running multiple zenoh-pico clients (e.g., a talker and listener) simultaneously connecting to the same router, you may see errors like:

<err> nros_bsp: Failed to open zenoh session: -3
<err> rust: rustapp: BSP init failed: InitFailed(-5)

Or publisher/subscriber declarations fail with:

• Error code -128 (_Z_ERR_GENERIC)
• Error code -78 (_Z_ERR_SYSTEM_OUT_OF_MEMORY)

The first client typically succeeds while subsequent clients fail during z_declare_publisher() or z_declare_subscriber().

Root Cause

This is caused by the Z_FEATURE_INTEREST feature in zenoh-pico. The interest protocol implements write filtering to optimize network traffic by only sending data to interested subscribers. However, this feature has issues when multiple clients connect to the same router:

1. The router tracks “interest” for each client
2. When creating a publisher, zenoh-pico creates a write filter context
3. The filter creation calls _z_session_rc_clone_as_weak() which can fail
4. This manifests as _Z_ERR_SYSTEM_OUT_OF_MEMORY (-78) even when memory is available

The failure occurs in zenoh-pico/src/net/filtering.c:

ctx->zn = _z_session_rc_clone_as_weak(zn);
if (_Z_RC_IS_NULL(&ctx->zn)) {
    _z_write_filter_ctx_clear(ctx);
    z_free(ctx);
    _Z_ERROR_RETURN(_Z_ERR_SYSTEM_OUT_OF_MEMORY);
}

Solution

nros disables Z_FEATURE_INTEREST by default for all builds:

Native builds (build.rs):

#![allow(unused)]
fn main() {
let dst = cmake::Config::new(&zenoh_pico_build)
    // ...
    .define("Z_FEATURE_INTEREST", "0")
    .build();
}

Zephyr builds: The just zephyr setup recipe automatically patches zenoh-pico’s config.h to disable these features. If you set up the workspace manually or the patch wasn’t applied, run:

just zephyr setup  # Updates and patches existing workspace

Or manually edit modules/lib/zenoh-pico/include/zenoh-pico/config.h:

// Change from:
#define Z_FEATURE_INTEREST 1
#define Z_FEATURE_MATCHING 1

// To:
#define Z_FEATURE_INTEREST 0
#define Z_FEATURE_MATCHING 0

Then rebuild with --pristine:

west build -b native_sim/native/64 nros/examples/zephyr/rust/talker -d build-talker --pristine

Note: Z_FEATURE_MATCHING depends on Z_FEATURE_INTEREST, so both must be disabled.

References

• rmw_zenoh_pico disables this feature by default
• zenoh-pico filtering code: src/net/filtering.c
• zenoh-pico interest protocol: src/session/interest.c

zenoh-pico Version Compatibility

Symptoms

Publisher works but z_publisher_put fails immediately:

zenoh_shim: z_publisher_put failed: -100
<err> rust: rustapp: Publish failed: PublishFailed(-1)
zenoh_shim: z_publisher_put failed: -73

Error codes:

• -100: _Z_ERR_TRANSPORT_TX_FAILED - Transport transmission failed
• -73: _Z_ERR_SESSION_CLOSED - Session closed after first failure

Root Cause

Version mismatch between zenoh-pico and zenohd:

• zenoh-pico: 1.5.1 (in west.yml)
• zenohd: 1.7.x (installed via cargo)

The zenoh protocol may have changed, causing transport-level incompatibilities.

Solution

Upgrade zenoh-pico to match zenohd version. All zenoh components in nros are pinned to the same version. Use just zenohd build to build the matching router from the submodule.

Temporary workaround: Install an older zenohd version:

cargo install zenoh --version 1.5.1 --features=zenohd

Multiple Zephyr Instance Issues

Ephemeral Port Conflict

Symptom: When running multiple Zephyr native_sim instances (e.g., talker and listener), both sessions fail to establish or one gets -100 (_Z_ERR_TRANSPORT_TX_FAILED) errors.

Root Cause: Zephyr native_sim uses a test entropy source that produces identical random number sequences unless seeded differently. This causes both instances to select the same ephemeral TCP port when connecting to the router, causing a port conflict.

Solution: Pass different --seed values to each native_sim instance:

# Start listener with one seed
./build-listener/zephyr/zephyr.exe --seed=12345

# Start talker with a different seed
./build-talker/zephyr/zephyr.exe --seed=67890

The --seed parameter initializes the test entropy source with a different value, producing different random numbers and thus different ephemeral ports.

For automated tests: The test framework (packages/testing/nros-tests) automatically assigns unique seeds to each process.

Cyclone DDS: Two native_sim Nodes Never Discover Each Other

Symptom: Two native_sim nodes with the Cyclone DDS RMW (e.g. talker + listener) each start, the publisher reports Published: N, but the subscriber stays at Received: 0 — no abort, no error.

Root Cause: Same fixed-entropy issue as above. Cyclone derives each participant’s DDSI GUID prefix from the entropy source; with identical entropy, both processes get the same GUID. DDSI requires per-participant unique GUIDs — a node treats SPDP from a peer that shares its own GUID as a self-announcement and drops it, so the two never form a proxy-participant pair and discovery never closes.

Solution: Pass different --seed values per instance (exactly as above):

./build-listener/zephyr/zephyr.exe --seed=11
./build-talker/zephyr/zephyr.exe   --seed=22

With distinct seeds the GUID prefixes differ and SPDP discovery completes. (native_sim Cyclone discovery is unicast-only — the embedded config points <Peers> at 127.0.0.1; native_sim’s NSOS multicast RX fd does not survive Cyclone’s select()-based socket waitset. Real hardware has real entropy and full multicast, so neither workaround is needed off native_sim.)

Network Configuration Issues

TAP Interface Setup (QEMU bare-metal only)

Symptom: QEMU cannot connect to the network.

Solution: Run the network setup script:

sudo ./scripts/qemu/setup-network.sh

This creates and configures the tap0 interface at 192.0.3.1. QEMU bare-metal guests live on 192.0.3.10+.

Zephyr native_sim networking

Zephyr native_sim uses NSOS (Native Sim Offloaded Sockets) — socket calls are forwarded to host syscalls, so there is no emulated L2 stack and no TAP bridge. Point each example at a host-loopback zenohd / XRCE Agent:

zenohd --listen tcp/127.0.0.1:7456  # or any host-accessible address

Multiple native_sim instances can coexist without bridge configuration.

Message Too Large / Truncated Messages

Symptoms

• TransportError::MessageTooLarge when receiving service requests or subscription data
• Messages arrive but with corrupted or incomplete payloads
• Large messages (images, point clouds) silently disappear

Root Cause

nros uses static buffers at multiple layers, each with configurable size limits. A message must fit through every layer in the path to be delivered intact.

Zenoh backend layers: