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/String (Hello World: N) on /chatter once a second:

use core::fmt::Write as _;
use nros::prelude::*;
use std_msgs::msg::String as StringMsg;

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::<StringMsg>("/chatter").unwrap();

    let mut count = 0i32;
    executor
        .register_timer(nros::TimerDuration::from_millis(1000), move || {
            count += 1;
            let mut msg = StringMsg::default();
            let _ = write!(msg.data, "Hello World: {count}");
            publisher.publish(&msg).unwrap();
        })
        .unwrap();

    executor.spin_blocking(SpinOptions::default()).unwrap();
    // This is the imperative Layer-2 API; the starters use the
    // declarative `nros::node!` / `nros::main!` form — both are
    // first-class (see Concepts → Two-Layer API).
}

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.
• The same source runs on every supported target — a node body written for one platform compiles unchanged on the others; what differs is build configuration (Cargo.toml, .cargo/config.toml, CMakeLists.txt), not the code you write. This is asserted, not asserted-about: the example_portability test normalizes every platform’s copy of each example and fails if any two differ, so the claim is checked on every run rather than maintained by hope. Two execution models are declared exceptions with written reasons — bare-metal deferred dispatch, and Zephyr’s component shape — and the test names them explicitly rather than hiding them.
• 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; the alloc and std features are opt-in. Whether the IMAGE needs an allocator is the backend’s call, not the core’s: XRCE allocates only at entity setup, zenoh-pico wants an allocator (a bump allocator suffices on bare-metal), and Cyclone DDS allocates per message. scripts/rmw-alloc-sites.py reports every site.
• Standalone tooling — nros generate-rust produces message bindings without a ROS 2 installation (bundled interface definitions).
• Formally verified — 148 Kani bounded model checking harnesses and 83 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 but no in-CI gate yet — where the row names an examples/<plat>/ directory there is an app to compile and try; where it names an integrations/ shell there is build glue but no worked reference app yet.

Footnotes — ¹ MPS2-AN385 bare-metal is Rust-only (nros-c / nros-cpp need an RTOS for libc / heap). ² STM32F4 is reached through the customization ladder, not an in-tree crate; a FreeRTOS variant sits on the shared nros-board-freertos glue. ³ PX4 path is via the external-module template in integrations/px4/ — C++ only because PX4’s uORB binding is C++-only. ⁴ Untested = the code path exists and the port is documented, but no lane in this repo boots it — the hardware is not in the test rack and QEMU models no STM32 MAC. phase-337 W7.a moved the two STM32F4 board crates out of the tree for exactly that reason; keeping a row that says “Verified” for a board nothing verifies is the failure mode the tier registry exists to prevent. ⁵ The ESP-IDF component path is nightly-support only: built by the nightly full-matrix lane, never by the per-change or per-platform ones, and its coverage stops at the image building. The esp-hal row above it is the ESP32 path with a booting CI lane.

Supported platforms (by RTOS)

posix there is the platform layer, which is genuinely POSIX-clean. The host board is named linux, and that is the narrower claim: only Linux is tested, and nros-board-linux::apply_tier_affinity calls sched_setaffinity with cpu_set_t, which libc does not define for macOS. macOS is not supported (AGENTS.md, phase-260).

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’ve never used ROS

New to ROS entirely? Two ideas carry the whole book: a node is a process-like unit that computes; nodes talk through named topics (publish/subscribe), plus request/reply services. ROS 2 is the ecosystem standardizing those; an RMW (“ROS MiddleWare”) backend is the transport that moves the bytes. nano-ros is a small implementation of that model for microcontrollers. That’s enough to start:

1. Install — host toolchain, no ROS 2 required.
2. First Project — scaffold a two-node workspace and watch one node hear the other.
3. Anatomy explains what you built, in nano-ros’s own terms.

🔧 I want it running on the board in my hand tonight

Honest expectations first: the fastest real win is on your Linux host (~10 minutes, no ROS 2, no daemon — --rmw cyclonedds), and every embedded chapter has a QEMU flow that works without hardware. Real-hardware flashing is currently documented only for out-of-tree boards (STM32F4 worked example). The zenoh embedded flows need a ROS 2 install on the host for the router.

1. Check your board’s row in Supported Boards.
2. Take the host win: First Project.
3. Then your platform’s chapter under Bring Your Own RTOS (FreeRTOS / Zephyr / NuttX / ThreadX / ESP32 / bare-metal).

🤖 I have rclcpp/rclpy nodes and a colcon workspace

Experienced ROS 2 developer porting existing nodes to an MCU:

1. Setup Compared to Standard ROS 2 — what stays familiar (package.xml, launch XML, find_package) and what changes (no install prefix, compile-time RMW).
2. Porting a ROS 2 C++ node — the rclcpp-compat shim and its limits.
3. C / C++ multi-node workspaces — the colcon-shaped workspace flow.
4. ROS 2 Interoperability — wire your MCU node into your existing graph. Zenoh needs ros-jazzy-rmw-zenoh-cpp (Humble ships no apt package); Cyclone DDS interops with rmw_cyclonedds_cpp directly, no router.
5. Migration Guide — concept-to-concept map.

🔌 I have a board (or a vendored SDK tree) on my desk

Already have hardware — an ESP32, an STM32Cube or MCUXpresso project, a Zephyr or NuttX workspace? Two-step path:

1. Linux first — First Project on your host verifies the whole stack in ~10 minutes, with no daemon and no ROS 2 install (nros setup native --rmw cyclonedds, one scaffold command, cmake).
2. Then your target — start at How Integration Works: your RTOS keeps its own build tool (west, make, idf.py, your IDE) and nano-ros plugs into it. One chapter per host build system follows it.
3. Company tree, own BSP, forked RTOS? Start at Integrating into a Vendored Tree (pinning, air-gapped CI, the patch set you carry), then the Porting Guide: Build as a CMake subdirectory, Custom Board Package, Vendor Overlay, and the STM32F4 out-of-tree worked example. Know up front: adding a platform (new RTOS) or an in-catalog board still means carrying a small patch set inside your vendored nano-ros checkout — plan for a fork-with-rebase workflow against the nros-v<X.Y.Z> tags.

🚀 I want to get started shipping something

You’ve decided to use nano-ros and want a working system on Linux first, then move it to your target.

1. Install — three commands: ./scripts/bootstrap.sh, source ./activate.sh (every new shell), then nros setup native --rmw cyclonedds.
2. First Project — one scaffolded workspace, C++ and CMake, publishing with nothing else running. Rust variant on the same page.
3. Anatomy of What You Just Built — the three package roles and the one configuration file; every later addition is another instance of these.
4. Growing: nodes, parameters, more deploy targets — the Multi-Node Projects group; other languages — Rust, C, and Mixed.
5. Troubleshooting — First 10 Minutes if anything goes sideways.
6. Talking to a ROS 2 system — zenoh (router-based) or Cyclone DDS (direct, routerless) both interop: Choosing an RMW.

🔬 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.
• Per-RMW Feature Matrix — generated from the backend sources: services, events, QoS per backend. Backend Reference for architecture and footprint; Support Status for versions, pins, and CI tiers.
• Scheduling Wiring Matrix — generated per-platform truth: which classes and kernel capabilities are wired where. Scheduling Models is the narrative behind it (Real-Time Analysis the lint/tooling catalogue).
• Static Pool Inventory + Opaque Storage Sizing — memory footprint knobs and their single source of truth.
• no_std, alloc, and std + Dispatch Strategy — the execution/allocation constraints.
• 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.

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), and no prebuilt nros CLI.

Host prerequisites

Everything toolchain-shaped — rustup, cross-compilers, emulators, the zenoh router — is provisioned by the steps below. The host itself only needs the basics: git, curl, a C toolchain, pkg-config, python3.

Debian / Ubuntu:

sudo apt-get update
sudo apt-get install -y git curl ca-certificates build-essential \
    cmake pkg-config python3 python3-dev zstd \
    python3-catkin-pkg python3-empy python3-lark python3-yaml

Fedora / RHEL:

sudo dnf install -y git curl ca-certificates gcc gcc-c++ make \
    cmake pkgconf-pkg-config python3 python3-devel python3-pip zstd

# Fedora ships no rosidl packages — install the codegen Python deps via pip:
pip install --user catkin_pkg 'empy==3.3.4' lark PyYAML

Arch:

sudo pacman -S --needed git curl base-devel cmake python python-pip zstd

# Arch ships no rosidl packages — install the codegen Python deps
# (use a venv or pipx if your Python is externally managed):
pip install --user catkin_pkg 'empy==3.3.4' lark PyYAML

(base-devel is a package group, and it covers pkg-config; ca-certificates ships with the base system.)

macOS: xcode-select --install, plus brew install cmake pkg-config zstd, then pip install --user catkin_pkg 'empy==3.3.4' lark PyYAML.

(cmake builds the C/C++ quick start and every workspace root; zstd unpacks the prebuilt SDK assets nros setup fetches; python3-dev is needed once, while bootstrap.sh builds the launch resolver — it embeds CPython to parse ROS launch files. Each tool’s absence produces an error naming it. The Python packages feed rosidl_adapter, the ROS message-to-IDL step the CycloneDDS backend uses — on Fedora/Arch/macOS install catkin_pkg, empy==3.3.4, lark and PyYAML via pip or your package manager; empy must stay 3.x.)

These few packages are the only ones you install by hand. Per-board OS dependencies later on are declared in the index and printed for your package manager — apt, dnf, pacman or brew — by:

nros setup --system          # what is missing + the exact install command

That command needs the nros CLI, which is why the basics above come first: they are what it takes to clone the repo and build the CLI.

The whole flow, end to end

Four steps take a bare machine to a building project; each is detailed in a section below.

Why step 2 builds the CLI instead of downloading it. nano-ros is a source distribution today: there is no prebuilt nros to fetch, so obtaining the tool requires the repository and its toolchain. That is backwards — nros provisions dependencies and builds workspaces, so it is meant to be the thing you get first, and the thing that makes cloning this repository unnecessary.

Prebuilt binaries were shipped early and withdrawn, because a released binary emitted code that had drifted from the runtime — and drifted generated code compiles, so the failure was silent. Restoring the download is blocked on one question having a checkable answer: can this binary’s output work with this runtime? RFC-0090 answers it with a codegen version that every generated artifact carries and every runtime asserts. Until that ships in a release, step 2 stays.

# 1. Pull the source at a pinned version (or `main` for latest):
git clone --branch nros-v0.5.0 https://github.com/NEWSLabNTU/nano-ros.git
cd nano-ros

# 2. Build the `nros` CLI from source (installs rustup if needed):
./scripts/bootstrap.sh

# 3. Wire the workspace env into this (and every future) shell:
source ./activate.sh          # or: direnv allow / source ./activate.fish

# 4. Provision the toolchains + RMW daemon for your target:
nros setup <board> --rmw <zenoh|xrce|cyclonedds>    # e.g. `native`

Then point your project’s manifest at the checkout — Pattern A/B below for CMake (the add_subdirectory / -DNANO_ROS_ROOT guard), or the Rust-only consumers path dependency. See Pinning a version for how the tag relates to nros version.

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 bootstrap front door below is what produces 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.

Do I need ROS 2 installed?

Building, no. Running two zenoh nodes, yes — or use Cyclone. nros sync generates the message bindings from the interface sources vendored in packages/cli/interfaces/, so nothing about setup, codegen or compilation needs ROS 2.

Running is where it splits, and the reason is the router. zenoh-pico connects in client mode, so any two-process example needs a zenoh router — and since RFC-0075 that router is rmw_zenoh_cpp/rmw_zenohd, which ships with ROS 2. nano-ros no longer vendors one. So on a host with no ROS 2:

• --rmw cyclonedds works standalone — Cyclone is in-process, there is no daemon to start. This is the ROS-less path.
• --rmw zenoh (the default) has no router. Either install ros-<distro>-rmw-zenoh-cpp, or point NROS_RMW_ZENOHD at a rmw_zenohd you obtained another way.

If you do have ROS 2, source its setup first — that is what makes the router findable:

source /opt/ros/<distro>/setup.bash

nano-ros reads AMENT_PREFIX_PATH from that, so a ROS installed anywhere works, including one you built from source or a colcon overlay — it is not assumed to be under /opt/ros.

Do not expect command -v rmw_zenohd to print anything: rmw_zenohd installs into <prefix>/lib/rmw_zenoh_cpp/, and setup.bash puts only bin/ on PATH. ROS’s own way to reach it is ros2 run rmw_zenoh_cpp rmw_zenohd. So a silent command -v is normal and not a broken install — the ros2 run rmw_zenoh_cpp rmw_zenohd spelling finds it regardless.

Only what you name is used. nano-ros needs the router that ships with your rmw_zenoh_cpp: the two share a zenoh build, and a mismatch shows up as “nothing was delivered” rather than as an error. So the search is NROS_RMW_ZENOHD, then the prefixes you sourced, then $ROS_DISTRO — and nothing else. In particular:

• PATH is not searched. A zenohd there — installed from zenoh’s own instructions, or left behind by an older nano-ros — is usually a different and older zenoh. The machine this was written on had two, at v1.4.0 and 1.7.2, against ROS’s 1.8.0.
• /opt/ros/* is not globbed. If you have humble and jazzy installed, guessing between them is not better than saying nothing. Source the one you want, or set ROS_DISTRO.

If you do want a specific binary, name it with NROS_RMW_ZENOHD; it is used as given, with a warning if it is not an rmw_zenoh_cpp router.

If you once used an older nano-ros, run nros doctor: it reports a retired SDK store entry that is still installed, zenohd included, with the command to remove it.

When you source activate.sh without ROS 2 present it says so:

activate.sh: /opt/ros/humble/setup.bash not found — ROS-dependent recipes
  will fail (interop tests, `ros2` CLI verification). The setup, codegen
  and first-node flows do not need it.

That line is informational on a getting-started host. If you do want the ROS 2 side and your distro has no Humble packages (Arch, for example), a container is the usual answer — nano-ros itself stays on the host.

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. The cross-compiler, emulator, RMW host daemon, and any SDK sources a board needs are resolved 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.

Packages are prebuilt where the index has a binary for your host, and built from source otherwise. Source builds are normal, not an error — but they cost real time and disk, so nros setup announces them before it starts:

nros setup: 1 package(s) have no prebuilt for linux-x86_64 — BUILDING FROM SOURCE: <name>
  Expect minutes (tens of minutes for a large recipe) and hundreds of MB under …

Source recipes build with the workspace’s pinned Rust channel, so a recipe carrying its own pin does not make rustup fetch a second toolchain behind your back. nros setup <board> --dry-run prints the whole plan, prebuilt vs source, without fetching anything — on the native board it is two source packages (zenoh-pico and mbedtls, both vendored submodules) and no daemon at all.

1. Get the nros CLI onto PATH

nano-ros is a source distribution — there is no prebuilt nros download. One front door from a fresh checkout (just is NOT a prereq; rustup is installed on demand):

Sourcing activate.sh on a host without just prints one line about RTOS SDK path defaults (FREERTOS_DIR, NUTTX_DIR, IDF_PATH, …) not being loaded. Harmless — nothing in the user flows reads them, and embedded builds work with plain cargo / cmake. just is a contributor tool: only the in-tree just recipes (test lanes, fixture builds) need it (cargo install just).

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

Builds the in-tree nros CLI from source at packages/cli/target/release/nros and leaves it on PATH for this shell.

Already have cargo? The equivalent by hand (same build, same binary):

git submodule update --init packages/cli/third-party/play_launch
cargo build --release --manifest-path packages/cli/Cargo.toml --bin nros
export PATH="$PWD/packages/cli/target/release:$PATH"

Both 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 (used by the rmw_zenoh interop tests, and it lets codegen resolve message packages from the ament index; building with any RMW — Cyclone included — does NOT require ROS 2, only the pip-installable rosidl_adapter Python packages from the prerequisites) 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 — a zenoh router for zenoh, the Micro-XRCE-DDS agent for xrce. Cyclone DDS is in-process — no separate daemon — so none of this applies if you ran nros setup … --rmw cyclonedds.

For xrce, nros setup … --rmw xrce installs the agent into the nros store (~/.nros/sdk/<tool>/<version>/bin/), and you run it in a dedicated terminal before launching any example.

For zenoh, the router is not provisioned by nros setup: it is ROS 2’s rmw_zenoh_cpp/rmw_zenohd, so that nano-ros is tested against the router a ROS 2 deployment actually runs (RFC-0075). Start it with your ROS environment sourced (leave it running for the whole session):

ZENOH_CONFIG_OVERRIDE='listen/endpoints=["tcp/127.0.0.1:7447"];scouting/multicast/enabled=false' \
    ros2 run rmw_zenoh_cpp rmw_zenohd

It is not configured on the command line — rmw_zenohd ignores argv and reads ZENOH_CONFIG_OVERRIDE, as above. To pick a different endpoint, change the port in the listen/endpoints entry.

Without a router 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:7447 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 one of two ways:

• Registry-style names + patch redirection (what every shipped example uses): declare nros = { version = "*" } (+ msg crates) and let nros sync write the # nros-managed [patch.crates-io] block into .cargo/config.toml, resolving the names into the checkout (NROS_REPO_DIR names it). Copy the project anywhere; re-run nros sync to re-point.
• Explicit path dependency on the in-workspace checkout:

[dependencies]
nros = { path = "src/nano-ros/packages/api/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.

Pinning a version

Consumers pin the source tree, not a package: clone (or submodule) at a nros-v<X.Y.Z> git tag —

git clone --branch nros-v0.5.0 https://github.com/NEWSLabNTU/nano-ros.git
# or, as a submodule in your project:
git submodule add -b main https://github.com/NEWSLabNTU/nano-ros third_party/nano-ros
git -C third_party/nano-ros checkout nros-v0.5.0

The tag names the bundle version: the nros CLI built from that tree prints the same number (nros version → nros 0.5.0; the scripts/check-version-lockstep.sh gate + bootstrap.sh shell-doctor enforce binary↔tree agreement), and the tree’s committed nros-sdk-index.toml pins the exact toolchain/SDK versions nros setup will provision for it. One tag therefore fixes the whole surface: runtime source, CLI behavior, and provisioned toolchains. Upgrading = checking out a newer tag and re-running ./scripts/bootstrap.sh (rebuilds the CLI to match) + nros setup (reconciles the SDK store against the new index; already-current packages are no-ops). See versioning for how the bundle number is chosen.

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 setup <module> 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 setup freertos           # → nros setup qemu-arm-freertos
just setup nuttx              # → nros setup qemu-arm-nuttx
just setup threadx_linux      # → nros setup threadx-linux

Docker environment (contributors)

For a containerized environment with QEMU 7.2+ (in-tree checkout):

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 the (contributor) just install-local recipe, see migration-install-local-removal.md for the one-page rewrite.

Next Steps

• First Project — the Quick Start continues here: scaffold a two-node workspace and run it (no ROS 2 needed)
• 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 Project

One command scaffolds a working multi-node workspace; two more build and run it. C++ and CMake, publishing on your machine, with nothing else running — no router, no daemon, no ROS 2 installation.

This assumes the two-step install is done (nros on your PATH, nros setup native --rmw cyclonedds run once).

Scaffold

nros new my_robot --workspace
cd my_robot

That wrote 21 files — a complete workspace, not a hello-world stub:

my_robot/
├── CMakeLists.txt              # workspace root — names the packages, picks the RMW
└── src/
    ├── talker_pkg/             # a C++ node: publishes std_msgs/Int32 on /chatter
    ├── listener_pkg/           # a C++ node: subscribes to /chatter
    ├── demo_bringup/           # launch file + system.toml — no code
    └── robot_entry/            # the binary: boots the launch topology

What each directory is for is the next chapter, Anatomy of What You Just Built. You don’t need it to run.

Build

cmake -S . -B build -DNANO_ROS_ROOT=<path-to-your-nano-ros-checkout>
cmake --build build

The first configure compiles nano-ros’s runtime into the build tree (~3 minutes); rebuilds are seconds. If you use direnv/activate.sh from the nano-ros checkout, -DNANO_ROS_ROOT can be omitted — the NROS_REPO_DIR env it exports is picked up automatically.

Run

./build/src/robot_entry/robot_entry

Published: 0
Received: 0
Published: 1
Received: 1
Published: 2
Received: 2

One process, two nodes: the talker publishes std_msgs/Int32 on /chatter every 500 ms and the listener prints each one it receives — the interleaved Received: lines are your proof of delivery — exactly as a ROS 2 composition container would run two composable nodes. Ctrl-C stops it.

Why nothing else needed to be running: the default RMW is CycloneDDS, which discovers peers directly — there is no router or daemon in the picture. The zenoh backend (for talking to a ROS 2 system) and XRCE (for the smallest targets) are one page away: Choosing an RMW, and switching is a one-word edit — Switching RMW in Config.

Same thing in Rust

nros new my_rust_robot --workspace --lang rust
cd my_rust_robot
NROS_REPO_DIR=<path-to-nano-ros> nros sync   # Rust-side codegen; once per checkout location
RUST_LOG=info cargo run -p robot_entry

[INFO  talker_pkg] Publishing: 0
[INFO  listener_pkg] I heard: 0
[INFO  talker_pkg] Publishing: 1

(The workspace root is a virtual manifest — cargo run alone has no default binary, so name the entry package with -p robot_entry. The Rust talker ticks at 1 s.)

Same workspace shape, same system.toml, same launch file — only the node implementations and the build tool differ. The extra nros sync step is the Rust-side message codegen; C++ does the equivalent inside CMake, which is why the C++ path doesn’t have it.

If it didn’t work

• nros: RMW session open failed on a busy machine usually means the DDS port range on your ROS_DOMAIN_ID is contended — pick another: ROS_DOMAIN_ID=57 ./build/src/robot_entry/robot_entry.
• Everything else: Troubleshooting — First 10 Minutes.

Where to go next

• Understand the four directories — Anatomy.
• Talk to a real ROS 2 system — ROS 2 Interoperability.
• Put it on a board — How Integration Works.
• Add nodes, parameters, more targets — Project layout and the Multi-Node Projects section.

Anatomy of What You Just Built

Four directories, three roles, one configuration file. Everything you will ever add to this project is another instance of one of these three roles — the shape never changes, it only gains packages.

If you come from ROS 2, each role is something you already know:

Node packages — the code

A node package is one node as a reusable library. The C++ shape is a class with a configure(nros::Node&) method that binds real member callbacks:

src/talker_pkg/
├── CMakeLists.txt          # nano_ros component library
├── package.xml             # ROS package manifest — deps live here
├── include/talker_pkg/Talker.hpp
└── src/Talker.cpp          # bind_timer → publish on /chatter

package.xml is standard ROS: message dependencies (std_msgs) are declared there and code-generated during the build. You never hand-write message types.

The bringup package — the one configuration file

src/demo_bringup/ holds no code: a launch file and system.toml. This is where every configuration axis lives:

[system]
name = "demo"
rmw = "cyclonedds"                   # the RMW axis
domain_id = 0
default_launch = "system.launch.xml"

[[component]]                        # the topology: which nodes exist
pkg = "talker_pkg"
class = "talker_pkg::Talker"
name = "talker"

[image.native]                       # one block per BUILDABLE image
board = "native"

[host.native]                        # WHERE the nodes run; no `nodes` = all

The launch file is the ROS 2 launch XML schema, verbatim — <node>, <param>, <remap>, <group>, <include> with $(find) / $(var) substitutions. A launch file from nav2 or Autoware pastes in unchanged (Python .launch.py is not supported). The scaffold’s launch even carries a per-topic QoS override to show the plumbing:

<node pkg="talker_pkg" exec="talker" name="talker">
  <param name="qos_overrides./chatter.publisher.reliability" value="best_effort"/>
</node>

When you later target hardware, you add an [image.<id>] block per board — the code and topology stay put. That is the growth rule: configuration is a new block, never a restructure.

The entry package — the deliverable

src/robot_entry/ is the binary. Its CMakeLists calls nano_ros_entry(... BRINGUP ... LAUNCH default), which at configure time resolves the bringup’s launch file and generates a main() that constructs each declared component, applies launch parameters and QoS overrides, and runs them on one executor — the launch product is the binary. There is no separate ros2 launch step; running the entry is launching the system.

One entry per deployable image. A robot with a perception image and a control image is one workspace, two entry packages, one bringup.

What was generated vs. what is yours

Everything under src/ is yours to edit. The build tree (build/) holds everything derived: generated message code, the resolved system model, the entry’s generated main(). Nothing derived is ever committed — if you can regenerate it, it does not belong in git.

The same anatomy in Rust

nros new --workspace --lang rust produces the identical shape: node packages are library crates with nros::node!(Talker), the entry is a one-line nros::main!(launch = "demo_bringup", spin = "forever"), and the bringup directory is byte-for-byte the same idea. One difference: Rust message codegen runs as a pre-build step (nros sync) instead of inside CMake.

Next

• The Quick Start continues: Your own message package
• Add a second talker or your own node: Node packages
• Point it at real hardware: How Integration Works
• The full role reference: Bringup packages · Entry packages

Your own message package

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

• a nano-ros build — rosidl_generate_interfaces(...) is intercepted by nano-ros’s wrapper and routed through nano-ros codegen. No ROS 2 install needed — even the rclcpp-shaped consumer below compiles against nano-ros’s source-compat layer.
• colcon build — upstream rosidl_default_generators produces the upstream-ROS bindings (this half, and only this half, needs a ROS 2 install; it is the optional cross-build proof at the end).

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

Where this fits. This chapter uses ROS 2 vocabulary (ament_cmake, rosidl, rclcpp) because its point is that stock ROS shapes work unchanged. If you came straight from First Project and none of that means anything yet, you can skim to “The Rust side” below or skip ahead to First Node — Rust and return later. The standalone tree here is for clarity — in your scaffolded my_robot workspace the same drop-in applies: put src/my_msgs/ next to your node packages.

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

The Rust side

The same msg package feeds a Rust node with no CMake involved: declare it in your node package’s package.xml (<depend>my_msgs</depend>) and manifest (my_msgs = { path = "../../generated/my_msgs", version = "0.0.0", default-features = false } — workspace-level generated/, constant 0.0.0 version), then run nros sync from the workspace root — the package index finds src/my_msgs/ by its package.xml, generates the generated/my_msgs crate, and wires the cargo patch table. The shipped precedent is examples/workspaces/features/src/custom_msgs/ with its rust_reading_listener_pkg consumer. Full detail: Message Generation.

use my_msgs::msg::MyMsg;   // generated crate, same field names

Cross-build proof — same source under colcon (optional; needs ROS 2)

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/workspace_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.

Next

• Something broke on the way here? Troubleshooting — First 10 Minutes.
• Single-node deep dive: First Node — Rust.
• Grow the workspace: Node packages.

Troubleshooting — First 10 Minutes

The Quick Start runs on --rmw cyclonedds — no router daemon exists on that path, so “no output” there is never a router problem; skip section B’s router branches. The zenoh walkthroughs (First Node pages) additionally assume nros setup native --rmw zenoh has run and the ROS 2 zenoh router (ros2 run rmw_zenoh_cpp rmw_zenohd) is reachable. 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. nros crates don’t resolve (missing / stale patch block)

error[E0432]: unresolved import `nros`
error: failed to load source for dependency `nros`
error: no matching package named `nros` found

The example’s Cargo.toml declares nano-ros crates registry-style (nros = { version = "*" } — they are not published to crates.io); the example’s .cargo/config.toml carries the # nros-managed [patch.crates-io] block that resolves them into a nano-ros checkout. This error means the patch block is missing or its relative paths no longer reach a checkout (typical right after copying the example somewhere else). Fix:

cd <the example dir>
NROS_REPO_DIR=/path/to/nano-ros nros sync

which regenerates the message crates and rewrites the patch block for the example’s current location.

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
(the CLI lives in-tree at packages/cli/). Build it with:
  just setup-cli                 # or: just setup

(The message names the contributor recipe; ./scripts/bootstrap.sh runs the same build without just.)

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

./scripts/bootstrap.sh      # builds packages/cli/target/release/nros
source ./activate.sh        # OR: direnv allow / source ./activate.fish

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 — wired 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 a known follow-up).

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

(The quoted message is emitted by the build script; “build via just” in it refers to the contributor recipes.) 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 (contributors can build via the in-tree just <plat> recipe).

B. Binary runs but no output

B1. Rust: RMW session open failed — Transport(ConnectionFailed)

[ERROR nros] RMW session open failed — Transport(ConnectionFailed)

The zenoh router isn’t running, or isn’t reachable on the locator the talker is pointed at. The router comes from ROS 2 (nano-ros no longer ships one) — start it in another terminal:

ZENOH_CONFIG_OVERRIDE='listen/endpoints=["tcp/127.0.0.1:7447"];scouting/multicast/enabled=false' ros2 run rmw_zenoh_cpp rmw_zenohd

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, 7447 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 a native talker can’t reach the daemon, 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 native Rust / C / C++ talkers all read NROS_LOCATOR first, fall back to ZENOH_LOCATOR, then to the build-time default. Embedded targets have no runtime env — their locator is compile-baked from the deploy config ([package.metadata.nros.deploy.<t>] / the package.xml tuple), so a rebuild is the override.

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/String --qos-reliability best_effort

D. Doctor + last-resort

D1. Run the doctor first

nros doctor

It prints fixit hints for the toolchain you actually need. (A just-free platform-scoped doctor spelling does not exist today; contributors with an in-tree checkout can scope via the platform recipes.)

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 the contributor recipe just workspace cargo-tools — that re-runs the build which short-circuits on the same PATH miss.

D3. Full sweep (slow)

nros doctor
nros setup --check

Only run this when you’re standing up every supported platform in one go. It walks the provisioning checks 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  talker] Publishing: 'Hello World: 1'
[INFO  talker] Publishing: 'Hello World: 2'
[INFO  talker] Publishing: 'Hello World: 3'

(That is the full expected output — the talker logs one line per publish, nothing else.)

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

Publishing: 'Hello World: 1'
Publishing: 'Hello World: 2'
Publishing: 'Hello World: 3'

A correctly-running C++ talker prints the same Publishing: 'Hello World: N' line once per second.

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

data: 'Hello World: 1'
---
data: 'Hello World: 2'
---
data: 'Hello World: 3'
---

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

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. The zenoh router comes from ROS 2 (ros2 run rmw_zenoh_cpp rmw_zenohd) — nano-ros no longer ships one. No ROS 2 on this machine? Use --rmw cyclonedds instead: it needs no router at all (see Choosing an RMW).

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. Front door (bare machine OK — no Rust, no just):

./scripts/bootstrap.sh

Installs rustup if needed and builds the in-tree nros CLI from source at packages/cli/target/release/nros, leaving it on PATH for this shell (nano-ros is a source distribution — no prebuilt nros).

B. Already have cargo (equivalent — same build, same binary):

git submodule update --init packages/cli/third-party/play_launch
cargo build --release --manifest-path packages/cli/Cargo.toml --bin nros
export PATH="$PWD/packages/cli/target/release:$PATH"

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 client stack into a shared store; the router itself comes from your ROS 2 install):

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          # registry-style deps + `nros sync` patch table
├── package.xml         # ROS-style manifest (drives codegen tooling)
├── generated/          # auto-generated message bindings (gitignored)
└── src/
    ├── main.rs         # one line: nros::main!(spin = "forever")
    └── lib.rs          # the ~65-line talker node body

Native (host) talkers read the locator / domain from environment variables (NROS_LOCATOR — legacy alias ZENOH_LOCATOR — and ROS_DOMAIN_ID) — no config file is needed. Embedded targets bake their config from [package.metadata.nros.deploy.<target>] instead — the shape shows up under the Embedded Starters section.

The Cargo.toml is the contract that wires nano-ros into your package. Every example is its own standalone Cargo root (an empty [workspace] table stops cargo walking up the filesystem), and nano-ros crates are declared registry-style (version = "*"); the example’s tracked .cargo/config.toml carries an auto-managed [patch.crates-io] block (written by nros sync) that resolves them into a nano-ros checkout. 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", "nros-board-linux/rmw-zenoh"]

[dependencies]
nros = { version = "*", default-features = false,
         features = ["std", "alloc", "env", "rmw-cffi", "macros"] }
nros-platform-cffi = { version = "*", features = ["posix-c-port"] }
nros-board-linux = { version = "*", default-features = false }
nros-rmw-zenoh = { version = "*", default-features = false,
                   features = ["std", "platform-posix", "ros-humble"],
                   optional = true }
# The ONE non-registry dep: your own generated message crate, by path.
std_msgs = { path = "generated/std_msgs", default-features = false }
log = "0.4"
env_logger = "0.11"

[workspace]

Copying this out of the workspace? That is the intended workflow — nano-ros crates are not published to crates.io, so the version = "*" deps resolve through the [patch.crates-io] block in .cargo/config.toml, and nros sync rewrites that block (plus the generated message crates) for wherever the directory lives now:

cp -r examples/native/rust/talker ~/my-talker && cd ~/my-talker
NROS_REPO_DIR=/path/to/nano-ros nros sync
cargo build && RUST_LOG=info cargo run

Prefer vendoring instead? examples/templates/multi-package-workspace/ documents the path-dep workspace layout.

Configure

Three runtime knobs, each an env override on a built-in default:

No config file on native. Embedded targets bake these from [package.metadata.nros.deploy.<target>] instead — see the Configuration Guide.

Build

cd examples/native/rust/talker
nros sync             # once per checkout location: writes the generated/
                      # message bindings + the [patch.crates-io] table
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 (ROS 2's own). Blocks the shell until Ctrl-C.
source /opt/ros/humble/setup.bash
ros2 run rmw_zenoh_cpp rmw_zenohd    # or: just zenohd

# Terminal 2 — the talker. The talker logs via `log::info!`, so set
# RUST_LOG=info — without it `env_logger` only shows errors and the
# `Publishing:` lines stay hidden.
cd examples/native/rust/talker
RUST_LOG=info cargo run
# Expected output (on stderr):
#   [INFO  talker] Publishing: 'Hello World: 1'
#   [INFO  talker] Publishing: 'Hello World: 2'
#   …

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. It talks to the SAME
# router already running in terminal 1 (default tcp/127.0.0.1:7447).
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/String --qos-reliability best_effort

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

Readiness signal. Within ~6 seconds of RUST_LOG=info cargo run (session open + the first 1 s timer tick), the talker should print Publishing: 'Hello World: 1' — the count starts at 1, matching the official ROS 2 demo_nodes_cpp talker. If no Publishing: line in 30 seconds:

1. Confirm RUST_LOG is set. Without RUST_LOG=info (or debug), env_logger filters out the Publishing: lines and the run looks silent even when it’s working.
2. Confirm the router 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 “RMW session open failed” — 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, run NROS_REPO_DIR=<nano-ros checkout> nros sync inside it, 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. Front door (bare machine OK — no Rust, no just):

./scripts/bootstrap.sh

Installs rustup if needed and builds the in-tree nros CLI from source at packages/cli/target/release/nros, leaving it on PATH for this shell (nano-ros is a source distribution — no prebuilt nros).

B. Already have cargo (equivalent — same build, same binary):

git submodule update --init packages/cli/third-party/play_launch
cargo build --release --manifest-path packages/cli/Cargo.toml --bin nros
export PATH="$PWD/packages/cli/target/release:$PATH"

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 client stack into a shared store; the router itself comes from your ROS 2 install — ros2 run rmw_zenoh_cpp rmw_zenohd):

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

On native, locator + domain come from env vars (NROS_LOCATOR, ROS_DOMAIN_ID) with built-in defaults; embedded targets bake them at build time via the package.xml <nano_ros deploy=… rmw=…/> tuple (see Configuration).

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_support_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:

On an embedded target the same knobs are compile-baked from the the package.xml <export><nano_ros deploy="<t>" rmw="<rmw>"/> tuple call in CMakeLists.txt (see Configuration).

Build

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

No nros sync here — a C leaf’s message bindings are generated inside CMake, and unlike the Rust leaves it carries no .cargo/config.toml to resolve. See Workflow by Platform and Language.

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 (ROS 2's own):
source /opt/ros/humble/setup.bash
ros2 run rmw_zenoh_cpp rmw_zenohd    # or: just zenohd

# 2. Run the talker:
cd examples/native/c/talker
./build/c_talker
# Expected output:
#   Publishing: 'Hello World: 1'
#   Publishing: 'Hello World: 2'
#   Publishing: 'Hello World: 3'
#   …

# 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/String --qos-reliability best_effort

Readiness signal. Within ~6 seconds of ./build/c_talker (session open + the first 1 s timer tick), the binary should print Publishing: 'Hello World: 1' on stdout — Rust + C + C++ all start the count at 1, matching the official ROS 2 demo talker. If no Publishing: line in 30 seconds:

1. Confirm the router 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. Front door (bare machine OK — no Rust, no just):

./scripts/bootstrap.sh

Installs rustup if needed and builds the in-tree nros CLI from source at packages/cli/target/release/nros, leaving it on PATH for this shell (nano-ros is a source distribution — no prebuilt nros).

B. Already have cargo (equivalent — same build, same binary):

git submodule update --init packages/cli/third-party/play_launch
cargo build --release --manifest-path packages/cli/Cargo.toml --bin nros
export PATH="$PWD/packages/cli/target/release:$PATH"

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 client stack into a shared store; the router itself comes from your ROS 2 install — ros2 run rmw_zenoh_cpp rmw_zenohd):

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

Native (host) talkers read the locator + domain from arguments passed to nros::init(...); no config file is needed. Embedded variants under examples/<plat>/cpp/talker/ bake theirs from the package.xml <nano_ros deploy=…/> tuple.

The CMakeLists is the ament shape you already know — this is the complete canonical file at examples/native/cpp/talker/CMakeLists.txt, verbatim (RFC-0048: nano_rosConfig.cmake at the checkout root makes find_package(nano_ros) resolve source-side, and the message-package Find-stubs make find_package(std_msgs) generate bindings on the fly):

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

set(CMAKE_CXX_STANDARD 14)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

find_package(nano_ros REQUIRED)
find_package(std_msgs REQUIRED)

nano_ros_add_executable(cpp_talker src/main.cpp)
ament_target_dependencies(cpp_talker std_msgs)

install(TARGETS cpp_talker DESTINATION lib/${PROJECT_NAME})
ament_package()

LANGUAGES C CXX (not CXX alone): the per-target register stub is a C translation unit, so C must be enabled in this directory scope or the link fails. Backend selection is a configure-line cache var (-DNROS_RMW=zenoh|xrce|cyclonedds), not CMake code.

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::String> 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          # with ./activate.sh sourced, nano_ros_ROOT is
                        # exported; a copy-out passes
                        # -Dnano_ros_ROOT=<path-to-nano-ros> explicitly
cmake --build build

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

Run

Three terminals.

# 1. zenoh router (ROS 2's own):
source /opt/ros/humble/setup.bash
ros2 run rmw_zenoh_cpp rmw_zenohd    # or: just zenohd

# 2. Run the talker:
cd examples/native/cpp/talker
./build/cpp_talker
# Expected:
#   nros C++ Talker
#   ===================
#   Node created: talker
#
#   Publishing messages (Ctrl+C to exit)...
#
#   Publishing: 'Hello World: 1'
#   Publishing: 'Hello World: 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/String --qos-reliability best_effort

Readiness signal. Within ~6 seconds of ./build/cpp_talker (session open + the first 1 s timer tick), the binary should print Publishing: 'Hello World: 1' — Rust + C + C++ all start the count at 1, matching the official ROS 2 demo talker. If no Publishing: line in 30 seconds:

1. Confirm the router 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.

Choosing an RMW

Every nano-ros binary picks its RMW (ROS Middleware) backend at build time. There are three: Cyclone DDS, Zenoh (zenoh-pico), and XRCE-DDS. This page helps you pick one; the mechanics of changing your pick live in Switching RMW Backends, and the per-backend deep dive (wire behavior, per-platform network configuration) is in RMW Backends.

Start with Cyclone DDS

For getting started, use Cyclone DDS. It is the one backend that needs no daemon, router, or agent: a nano-ros node publishes with nothing else running, and a stock ROS 2 node using rmw_cyclonedds_cpp sees it directly — same RTPS wire protocol, same discovery, no translation layer in between.

The reason the other two are not the starting point: nano-ros ships no bridge process of its own. The zenoh router is ROS 2’s own rmw_zenohd (see RFC-0075), so the zenoh backend requires a ROS 2 installation just to start the router; the XRCE backend requires a running Micro-XRCE-DDS Agent. Cyclone DDS requires neither.

Current maturity: pub/sub and services interoperate with stock rmw_cyclonedds_cpp; status events (liveliness, deadline-miss) are not wired to Cyclone listeners yet. The full list is in docs/reference/cyclonedds-known-limitations.md.

Zenoh — ROS 2 interop and small embedded targets

Choose the Zenoh backend (built on zenoh-pico) when:

• You are integrating with a ROS 2 fleet running rmw_zenoh_cpp.
• Your target is a small MCU: ~16 KB of heap and ~100 KB of flash are enough, versus ~32 KB+ RAM for Cyclone DDS.
• Your network cannot do UDP multicast (RTPS discovery needs IGMP; zenoh-pico in client mode runs over plain TCP).

The zenoh backend needs a router, and the router comes from your ROS 2 installation — it is the same rmw_zenohd that ROS 2 zenoh nodes use:

ros2 run rmw_zenoh_cpp rmw_zenohd

That invocation works on any host with rmw_zenoh_cpp installed, regardless of where ROS 2 lives — never hard-code an install path to the router binary. See ROS 2 Interop for the full three-terminal walkthrough.

XRCE-DDS — smallest footprint, serial transport

Choose the XRCE-DDS backend when:

• RAM is the constraint: ~3 KB of client RAM, fully static allocation, no heap required on the MCU.
• You need a serial (UART) transport — the only backend that works on an MCU with no networking hardware. See Serial Transport.
• You are joining an existing micro-ROS / DDS deployment: the agent bridges to any DDS-based RMW.

The MCU cannot participate without the Micro-XRCE-DDS Agent (MicroXRCEAgent) running on a host; if the agent stops, the device loses all connectivity.

Capability matrix

Notes on two rows: zenoh’s router-free peer mode exists upstream but nano-ros compiles zenoh-pico without the multicast transport and scouting, so every deployment reaches its peers through the router; and the upstream Micro-XRCE-DDS client defines a CAN FD transport, but nano-ros builds do not enable it.

Decision summary

• Default / getting started / DDS fleet → Cyclone DDS. Nothing to run beside your node; direct rmw_cyclonedds_cpp interop. Needs ~32 KB RAM and a network stack with IGMP.
• rmw_zenoh_cpp fleet, small MCU, or TCP-only network → Zenoh. Needs the router from your ROS 2 install (ros2 run rmw_zenoh_cpp rmw_zenohd).
• Tiny MCU, serial link, or micro-ROS deployment → XRCE-DDS. Smallest footprint, zero heap, but the agent is mandatory.

You do not have to pick exactly one per system: a single binary can link multiple backends and bridge between them — see Cross-backend Bridges.

Once you have picked, Switching RMW Backends shows the exact edits per build system.

Switching RMW Backends

nano-ros selects its RMW backend at build time — there is no RMW_IMPLEMENTATION environment variable to flip at runtime the way desktop ROS 2 does. Which edit you make depends on how your project is built. This page lists the exact change per builder; for help picking a backend in the first place, see Choosing an RMW.

Backend names are the same everywhere: zenoh, xrce, cyclonedds. When nothing selects a backend, the default is zenoh.

C/C++ workspace (CMake)

One edit. The root CMakeLists.txt of a nano-ros workspace calls nano_ros_workspace(...); change its BACKEND argument:

nano_ros_workspace(
    ORDER_FROM_DEPENDS
    BACKEND  cyclonedds          # zenoh | xrce | cyclonedds
    PLATFORM "${NANO_ROS_PLATFORM}"
    SUBDIRS  ${_ws_subdirs})

Then reconfigure and rebuild — preferably into a fresh build directory, so no object files from the previous backend linger.

Note: when the root hard-codes BACKEND, passing -DNROS_RMW=... on the configure line is silently overridden — nano_ros_workspace() stamps the workspace-wide RMW from its BACKEND argument, and the cache variable loses without a warning. Edit the BACKEND argument; do not fight it from the command line.

Single C/C++ package (no workspace function)

A standalone package that consumes nano-ros in source form — either find_package(nano_ros REQUIRED) (the ament-shape entry point, nano_rosConfig.cmake at the checkout root, located via nano_ros_ROOT; RFC-0048) or a raw add_subdirectory — for example a copied-out leaf like examples/native/c/talker/ — picks its backend on the configure line:

cmake -S . -B build -DNROS_RMW=cyclonedds   # zenoh | xrce | cyclonedds
cmake --build build

Use one build directory per backend (build-zenoh/, build-cyclonedds/, …) if you switch back and forth.

Rust workspace

Today this is three edits that must agree. (A scaffold flag that bakes all three from one value is planned; until then, treat this as a checklist.) The example below switches to cyclonedds:

Why three places:

1. system.toml is the declared, language-agnostic selection — it is what the toolchain and deploy tooling read. See Configuration.
2. The board crate is what actually links the backend. On the host board, nros-board-linux’s features are rmw-zenoh (the default), rmw-xrce, and rmw-cyclonedds; each pulls in the corresponding backend crate and registers it during boot. Switching away from zenoh therefore needs default-features = false plus the feature you want.
3. The nros facade feature rmw-cyclonedds is the type-descriptor gate: Cyclone DDS resolves topic types through a runtime descriptor registry, and this feature turns on the hook that registers a message’s descriptor before the topic is created. Without it, create_publisher fails at runtime because the descriptor was never registered. (Zenoh and XRCE do not need a facade feature — steps 1 and 2 are enough for them.)

After editing, re-run nros sync in the workspace and rebuild.

The full-system declaration model — how the one value in system.toml is lowered to cargo features and CMake cache variables — is specified in RFC-0031.

Embedded targets

On embedded platforms the backend is fixed at compile time like everything else — there is nothing to switch on the device. Each platform surfaces the same choice through its own configuration mechanism; on Zephyr, for instance, it is a Kconfig choice (CONFIG_NROS_RMW_ZENOH / CONFIG_NROS_RMW_XRCE / CONFIG_NROS_RMW_CYCLONEDDS, exactly one selected).

See the platform guides for the concrete per-platform workflow:

• Zephyr
• FreeRTOS
• NuttX
• ThreadX
• ESP32

and Workflow by Platform and Language for the overview of which builder applies where.

RMW Backends: Zenoh, XRCE-DDS, Cyclone DDS

Capability truth (services / events / QoS per backend) is the generated Per-RMW Feature Matrix; version pins live on Support Status. This page is the architectural narrative.

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 zenoh router (rmw_zenohd, ROS 2’s own) 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 router, enabling transparent interop.
4. zenoh itself defines a peer mode in which two zenoh-pico devices talk directly with no router. nano-ros does not ship it. The shim is compiled without zenoh-pico’s multicast transport and scouting (nros_zpico_build::MULTICAST_TRANSPORT = false) because those are three more code paths in a library whose job here is fitting on an MCU, and every nano-ros deployment reaches its peers through a router or an agent. NROS_SESSION_MODE=peer is therefore refused at session open with a message saying so — see issue 0682. Enabling it means flipping that constant, rebuilding the shim, and accepting the footprint.

Key characteristics:

• Client/router topology; zenoh’s router-free peer mode is compiled out (see above)
• The router forwards messages without interpreting them – it is not a protocol translator
• If the router 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)

Cyclone DDS (rmw-cyclonedds)

Maturity status. Cyclone DDS supports pub/sub + service round-trips on the native (host) build (full service implementation in src/service.cpp); status events (liveliness, deadline-miss, etc.) are NOT wired to Cyclone listeners yet, and the service-availability probe is deferred (service_server_available returns NROS_RMW_RET_UNSUPPORTED — poll-with-retry instead of waiting on it). Wire-level interop with stock rmw_cyclonedds_cpp (Humble) works for topics and services. 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/rmw/cyclonedds/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.
• Services wired (create/recv/reply — service.cpp); the availability probe (service_server_available) and actions are still unsupported.
• No status events yet — register_subscription_event / register_publisher_event / assert_publisher_liveliness slots are not wired to Cyclone listeners yet.

Build:

Contributors: the in-tree Cyclone DDS build/test lanes are in Per-Platform Contributor Lanes.

Each example picks its RMW via -DNANO_ROS_RMW=cyclonedds at configure time; the root CMakeLists.txt add_subdirectory’s packages/rmw/cyclonedds/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 (that is a contributor-only recipe); 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

¹ Footprint figures are order-of-magnitude planning numbers, not measurements — they vary with features, message set, and opt level. Size your own image with arm-none-eabi-size on your build; the RAM knobs are enumerated in the Static Pool Inventory.

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 image by [image.<id>].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. The selection point is the board crate (RFC-0031’s phase-248 C5b amendment): an app declares one rmw-<x> feature that activates the backend dep and forwards to the board crate’s matching feature. Codegen no longer emits nros/rmw-<x> or nros/platform-<y> — the board brings both.

[features]
default = ["rmw-zenoh"]
# Each `rmw-*` activates the app-owned optional backend dep and forwards to
# the board crate, which is what actually selects the backend.
rmw-zenoh = ["dep:nros-rmw-zenoh", "nros-board-linux/rmw-zenoh"]
rmw-cyclonedds = [
    "nros/rmw-cyclonedds",              # the marker feature; see below
    "dep:nros-rmw-cyclonedds-sys",
    "nros-board-linux/rmw-cyclonedds",
]

In a WORKSPACE you write none of this: [image.<id>].rmw in the bringup’s system.toml is the declaration, and the Entry pkg’s generated manifest carries the lowered form. The block above is the standalone copy-out shape, where there is no bringup to declare it in.

Cyclone DDS backend — Rust runtime sees the generic rmw-cffi C-ABI

vtable; actual Cyclone wiring lives C++-side under

packages/rmw/cyclonedds/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/api/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:

```bash
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 (the router is a single process started with ros2 run rmw_zenoh_cpp rmw_zenohd)

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

Choose Cyclone DDS when:

• You want direct, brokerless ROS 2 interop with no router 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

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. Front door (bare machine OK — no Rust, no just):

./scripts/bootstrap.sh

Installs rustup if needed and builds the in-tree nros CLI from source at packages/cli/target/release/nros, leaving it on PATH for this shell (nano-ros is a source distribution — no prebuilt nros).

B. Already have cargo (equivalent — same build, same binary):

git submodule update --init packages/cli/third-party/play_launch
cargo build --release --manifest-path packages/cli/Cargo.toml --bin nros
export PATH="$PWD/packages/cli/target/release:$PATH"

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. Front door (bare machine OK — no Rust, no just):

./scripts/bootstrap.sh

Installs rustup if needed and builds the in-tree nros CLI from source at packages/cli/target/release/nros, leaving it on PATH for this shell (nano-ros is a source distribution — no prebuilt nros).

B. Already have cargo (equivalent — same build, same binary):

git submodule update --init packages/cli/third-party/play_launch
cargo build --release --manifest-path packages/cli/Cargo.toml --bin nros
export PATH="$PWD/packages/cli/target/release:$PATH"

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/workspaces/rust/src/talker_pkg/Cargo.toml:

[lib]
path = "src/lib.rs"

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

[dependencies]
nros = { path = "../../../../../packages/api/nros", default-features = false,
         features = ["alloc", "rmw-cffi"] }

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

A Node pkg names no platform and no RMW. alloc is the universal baseline and rmw-cffi is the vtable seam; the concrete backend and the platform both flow in from the board crate that the sibling Entry pkg depends on, via cargo feature unification. That is what lets one talker_pkg deploy to a Linux host and a Cortex-M board without a fork.

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/workspaces/rust/src/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.

Services & clients

Server (responds to requests)

Declare the service in Node::register and handle requests in the node body.

• Rust — declare a service edge in register; requests dispatch into ExecutableNode::on_callback like any other callback (read the request and write the reply through the CallbackCtx).

• C++/C (the configure(Node&) component shape) — bind a typed member with nros::bind_service:

  // Response on_request(const Request&) — no hand-rolled CDR.
  AddTwoInts::Response on_add(const AddTwoInts::Request& req) {
      AddTwoInts::Response r; r.sum = req.a + req.b; return r;
  }
  ::nros::Result configure(::nros::Node& node) {
      return ::nros::bind_service<AddTwoInts, MyServer, &MyServer::on_add>(
          node, "/add_two_ints", this);   // service-type name from AddTwoInts::TYPE_NAME
  }
  

  bind_service deserializes the request into the generated Svc::Request, calls your typed member, and serializes the returned Svc::Response — no manual byte offsets. (bind_service_raw<&method> is still available for the rare hand-rolled case.)

Client (issues requests) — call from tick, not on_callback

A node cannot make a blocking service/action client call from on_callback: that runs while the executor is mid-dispatch, so a blocking call would deadlock the spin. Client calls go on the separate per-spin hook ExecutableNode::tick(&mut TickCtx), which the executor runs once per spin_once between callback dispatch:

#![allow(unused)]
fn main() {
fn on_callback(state: &mut State, cb: Callback<'_>, ctx: &mut CallbackCtx<'_>) {
    // ...decide a request is needed; just arm a flag / stash args:
    state.want_call = true;
}

fn tick(state: &mut State, ctx: &mut TickCtx<'_>) {
    if state.want_call {
        state.want_call = false;
        let reply = ctx.call_for_name("add_two_ints", &request);  // blocking, safe here
        // ...use reply
    }
}
}

The two-surface pattern (arm in on_callback, call in tick) is the supported way to drive a client from a declarative node. See examples/workspaces/rust/.../service_client_pkg for the reference.

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 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. Front door (bare machine OK — no Rust, no just):

./scripts/bootstrap.sh

Installs rustup if needed and builds the in-tree nros CLI from source at packages/cli/target/release/nros, leaving it on PATH for this shell (nano-ros is a source distribution — no prebuilt nros).

B. Already have cargo (equivalent — same build, same binary):

git submodule update --init packages/cli/third-party/play_launch
cargo build --release --manifest-path packages/cli/Cargo.toml --bin nros
export PATH="$PWD/packages/cli/target/release:$PATH"

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]] + [image.<id>] + [host.<name>]
├── 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"

[image.native]
board = "native"

[host.native]

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>

Parameter files

<param from="…"/> takes a standard ROS parameter file. Relative paths resolve against the launch file’s own directory.

# config/talker.param.yaml
/**:                      # applies to every node
  ros__parameters:
    use_sim_time: false
talker:                   # applies to the node named `talker` only
  ros__parameters:
    rate_hz: 25
    limits:
      max_accel: 1.5      # reaches the node as `limits.max_accel`

<node pkg="talker_pkg" exec="talker" name="talker">
  <param from="config/talker.param.yaml"/>
  <param name="rate_hz" value="50"/>   <!-- wins over the file -->
</node>

Precedence matches ROS: the /** wildcard block first, then the node-specific block, then inline <param name= value=> last. A node block may be keyed by fully-qualified name (/ns/talker), bare name (talker), or /**/talker.

These values are resolved and baked into the generated entry at build time — embedded targets do no runtime file loading, the same approach the domain ID uses. Editing the YAML re-runs codegen. A from= naming a file that doesn’t exist is a build error, not a silent skip.

Note: the baked values are seeded through the parameter services, so they reach nodes only when param_services is enabled in system.toml.

Note: Python .launch.py files ARE resolved by nros sync (the RFC-0060 resolver executes them with its bundled CPython; $(find-pkg-share) against ROS packages needs a sourced AMENT_PREFIX_PATH). The XML schema above is the native authoring format.

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)
ZENOH_CONFIG_OVERRIDE='listen/endpoints=["tcp/127.0.0.1:7447"];scouting/multicast/enabled=false' ros2 run rmw_zenoh_cpp rmw_zenohd &   # 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 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/ + config/ directly into the Entry pkg. The nros::main! macro’s launch = argument names the bringup package and, optionally, a launch file within it — the SAME inputs you author. The build resolves them to a SystemModel under <workspace>/build/nros/models/ (run nros sync, or let the build system drive it); you never reference the model file, though you can inspect it there:

#![allow(unused)]
fn main() {
// Multi-node: the bringup's default launch (system.launch.xml)
nros::main!(launch = "demo_bringup");

// A named launch file in the bringup pkg
nros::main!(launch = "demo_bringup:sim.launch.xml");

// A launch-argument binding, declared as [[model]] in system.toml
nros::main!(launch = "demo_bringup:multihost.launch.xml", args = [("host", "robot1")]);
}

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 a bare-metal Cortex-M 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. Front door (bare machine OK — no Rust, no just):

./scripts/bootstrap.sh

Installs rustup if needed and builds the in-tree nros CLI from source at packages/cli/target/release/nros, leaving it on PATH for this shell (nano-ros is a source distribution — no prebuilt nros).

B. Already have cargo (equivalent — same build, same binary):

git submodule update --init packages/cli/third-party/play_launch
cargo build --release --manifest-path packages/cli/Cargo.toml --bin nros
export PATH="$PWD/packages/cli/target/release:$PATH"

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 Zephyr / FreeRTOS / 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/qemu-arm-baremetal/rust/talker-rtic/ uses:

[package.metadata.nros.entry]
deploy = "rtic-mps2-an385"

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 [image.<id>] table when you later add a Bringup pkg.

nros::main!() — the 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 = LinuxBoard);

// 3. Multi-node (CANONICAL): name your INPUT — the Bringup pkg (and
//    optionally a launch file inside it; default is its default launch).
//    `nros sync` resolves it into a SystemModel build artifact that the
//    macro bakes from.
nros::main!(launch = "demo_bringup");
nros::main!(launch = "demo_bringup:variant_b.launch.xml");

// 4. Multi-host slice: point at a PER-HOST model. The launch file gates
//    nodes on a `host` launch argument (`if=` conditions), and the model
//    is resolved with `host:=robot1`, so it already contains only this
//    host's nodes — no extra macro key needed.
nros::main!(launch = "demo_bringup:multihost.launch.xml", args = [("host", "robot1")]);

// 5. DEPRECATED (expert override): name the resolved model ARTIFACT
//    directly instead of the input. Skips the sync-freshness contract;
//    warns at bake time (phase-330 W7).
nros::main!(model = "demo_bringup");
}

launch and model are mutually exclusive. launch is the canonical spelling (phase-330 W7): it names your input — the bringup package and launch file — and the entry consumes the SystemModel that nros sync resolves from it. The same resolved artifact drives the Linux runtime (play_launch) and every embedded image, so contract budgets, tiers, and QoS never drift between runtimes. model names the resolved artifact directly — a deprecated expert override. Produce/refresh the model with:

$ nros sync    # resolves models into <ws>/build/nros/models/<bringup>/

nros sync (the pre-build step every workflow already runs) re-resolves the model whenever a bringup’s launch XML or system.toml is newer than it. SystemModels are build artifacts — never commit one (the check-no-tracked-models gate enforces this).

nros sync is the only verb you need. Under the hood it runs the pinned nros-launch-resolve helper (RFC-0060 layer 2; contributors build it in-tree via just setup-launch-resolve) and invokes it by absolute path — never by a bare name on $PATH, because an unrelated ROS 2 play_launch on PATH used to win that race and break every platform’s fixture build (issue 0285). The macro reads [package.metadata.nros.entry] at compile time to select the right board and executor backend; the same model resolves its tier table for whichever RTOS that board targets. 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/qemu-arm-baremetal/rust/talker-rtic/src/main.rs collapses to exactly this:

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

fn main() {
use panic_semihosting 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.
<LinuxBoard 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:
ZENOH_CONFIG_OVERRIDE='listen/endpoints=["tcp/127.0.0.1:7447"];scouting/multicast/enabled=false' ros2 run rmw_zenoh_cpp rmw_zenohd &

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.

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 sync` output feeds every board and every RMW.
nros 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 macro, with the committed SystemModel 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");
}

One Entry pkg per board

Each deploy target gets its own Entry pkg. A workspace that runs on both native and rtic-mps2-an385 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/qemu-arm-baremetal/rust/talker-rtic/ example demonstrates the embedded shape: deploy = "rtic-mps2-an385" + nros::main!(); on a no_std / no_main binary that delegates everything to the RticMps2An385 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.

The parity gap is closed. 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_auto_add_library + nros_components_register_node
    │   └── 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(BRINGUP … 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() 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)

# RFC-0057: the ament shape — the library owns the sources, the register
# owns the identity (keyword parity with rclcpp_components_register_node).
# Interface deps (std_msgs__nano_ros_cpp) are wired automatically.
nano_ros_auto_add_library(talker_lib STATIC src/Talker.cpp)

nros_components_register_node(talker_lib
    PLUGIN talker_pkg::Talker      # any qualified name — upstream namespaces port verbatim
    EXECUTABLE talker
    SHAPE configure                # this walkthrough uses the configure(Node&) shape
    ENTITIES pub:std_msgs/msg/Int32:/chatter timer)

ENTITIES (optional) states what this component’s constructor creates, so the build can size the executor instead of a human counting call sites. Each entry is <kind>[:<type>[:<topic>]], with an optional *N repeat on the kind (pub*5); the kinds are publisher, subscription, timer, service_server, service_client, action_server, action_client and guard_condition. Write ENTITIES NONE for a component that creates none.

It is worth stating even though it is optional: NROS_EXECUTOR_MAX_CBS is derived from it, and the derivation is all-or-nothing. If any component in an image omits ENTITIES, nothing is derived for that image — a count taken over only the components that answered is smaller than the image needs, and a short MAX_CBS fails entity creation at boot. Inspect the composed answer with nros ws entity-inventory --metadata <build>/nros-metadata.json.

Note that a publisher is inventoried but claims no callback slot, so the declared entity count and the derived MAX_CBS are legitimately different numbers.

// 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(BRINGUP … LAUNCH …) — you name the input, and the entry bakes from the SystemModel that nros sync resolved from it (MODEL is the deprecated artifact-naming override):

# 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
    BOARD   native
    BRINGUP "${CMAKE_CURRENT_SOURCE_DIR}/../demo_bringup"
    LAUNCH  default
    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 LinuxBoard::run_components), appends it to the target’s sources, and auto-links every <pkg>_<exec>_component static lib the launch XML named.

BRINGUP + LAUNCH — name your input (canonical)

The canonical spelling names your input: the Bringup package and a launch selector. nros sync resolves that into a SystemModel build artifact (under <ws>/build/nros/models/<bringup>/ — never committed; gate check-no-tracked-models), and the entry bakes from it, so the same artifact drives the Linux runtime and every embedded image (contracts, tiers, QoS never drift). MODEL — naming the resolved artifact file directly — is a deprecated expert override; the two are mutually exclusive. This is the shape the shipped workspace uses:

nano_ros_add_executable(native_entry
    SOURCES src/main.cpp
    BOARD   native
    BRINGUP "${CMAKE_CURRENT_SOURCE_DIR}/../demo_bringup"
    LAUNCH  default
    TYPED
    DEPLOY  native)

nros sync resolves/refreshes the model whenever the bringup’s launch XML or system.toml is newer than it. The user’s main.cpp is a single declarative line:

// src/native_entry/src/main.cpp
#include <nros/main.hpp>
NROS_MAIN(nros::board::LinuxBoard, "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 sync` resolves the SystemModel (via the pinned nros-launch-resolve
# helper) whenever the launch XML or system.toml is newer than the model.
nros sync
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++).
• C++ Entry-pkg roadmap doc — 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_auto_add_library(talker_lib STATIC src/Talker.c)

nros_components_register_node(talker_lib
    PLUGIN c_talker_pkg::Talker
    EXECUTABLE talker
    SHAPE configure
    TYPED
    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_auto_add_library injects NROS_PKG_NAME (language inferred from the sources), 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
    MODEL   "${CMAKE_CURRENT_SOURCE_DIR}/../demo_bringup/config/system_model.yaml"
    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
    MODEL   "${CMAKE_CURRENT_SOURCE_DIR}/../demo_bringup/config/system_model.yaml"
    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.

Rust, C, and Mixed-Language Workspaces

The anatomy does not change with the language: node packages hold code, the bringup holds configuration, an entry per image. This page is what changes — per language — inside that fixed shape.

Rust

Scaffold the whole workspace in Rust, or add Rust node packages to an existing one:

nros new my_robot --workspace --lang rust      # whole workspace
nros new my_node --component --lang rust       # one node pkg, added under src/

A Rust node package is a library crate carrying nros::node!(YourNode); the entry collapses to one line:

#![allow(unused)]
fn main() {
nros::main!(launch = "demo_bringup", spin = "forever");
}

Two Rust-specific facts:

• nros sync before the first build, and again after editing .msg files or moving the checkout. It generates the message crates and the [patch.crates-io] table that maps nros dependencies to your checkout — cargo cannot resolve the workspace without it. C and C++ never need this; their codegen runs inside CMake.
• The RMW is spelled in three places (the bringup’s system.toml, the entry’s board-crate feature, the nros facade feature). The scaffold bakes all three from --rmw; changing it later is the checklist in Switching RMW in Config.

C

C node packages join a workspace the same way:

nros new my_c_node --component --lang c

A C node package is the declarative component shape — a configure function binding callbacks through nros/nros.h — built by the same per-package CMake as C++. There is no C workspace scaffold; start from the C++ workspace (nros new --workspace) and add C packages, which is also what the in-tree reference does.

Mixed — and why it just works

Languages mix per package, not per file, and the bringup does not care: a [[component]] row names a package and a class/entry point, whatever implements it. The in-tree reference workspace (examples/workspaces/mixed/) runs a C talker, a C++ listener, and a Rust heartbeat under one C++ entry:

mixed/src/
├── c_talker_pkg/          # C — publishes std_msgs/Int32 on /chatter
├── cpp_listener_pkg/      # C++ — subscribes
├── rust_heartbeat_pkg/    # Rust — a timer callback
├── demo_bringup/          # one system.toml for all three
└── native_entry/          # one C++ entry boots them together

Copy it out as a starting point if your project is mixed from day one.

Next

• Mixed-language workspaces, in depth
• C / C++ multi-node workspaces
• Node packages

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 must be a namespace-qualified C++ name. The old 212.L.4 prefix rule (class starting with the pkg dir name) is retired by RFC-0057 — pkg on the [[component]] row is the identity authority, so upstream namespaces (autoware::x::Node) port verbatim. nros check still rejects an unqualified class.
• C++ / C analogue: nano_ros_auto_add_library(<lib> STATIC <srcs>) + nros_components_register_node(<lib> PLUGIN … EXECUTABLE …) (RFC-0057, rclcpp_components keyword parity) + 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]] + [image.<id>] + [host.<name>] (+ [[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 files are resolved by nros sync too (the RFC-0060 resolver executes them — see the bringup tutorial). 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-linux = { … }            # 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 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 = LinuxBoard);                       // single-node, explicit board
nros::main!(launch = "demo_bringup");                   // multi-node (CANONICAL): the bringup's default launch
nros::main!(launch = "demo_bringup:sim.launch.xml");    // multi-node, a named launch file
nros::main!(                                            // multi-host: per-host slice via launch args
    launch = "demo_bringup:multihost.launch.xml",
    args = [("host", "robot1")],
);
// DEPRECATED (expert override): name the resolved model ARTIFACT directly
// instead of the input — skips the sync-freshness contract; bake-time warning.
nros::main!(model = "demo_bringup");

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. The launch forms take <bringup>[:<file>] against launch/<file>.launch.xml + system.toml [system] default_launch; nros sync resolves that input into a SystemModel under <ws>/build/nros/models/<bringup>/ (a build artifact — never committed; gate check-no-tracked-models), and the macro bakes from it. 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 <LinuxBoard 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> LANG CXX BRINGUP … LAUNCH …) plus NROS_MAIN(...) (MODEL is the deprecated artifact-naming override, mirroring the macro). 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.

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

How integration works

You already have an RTOS project that builds and runs — an STM32Cube or NXP MCUXpresso tree, a Pico SDK app, an ESP-IDF project, a vendored Zephyr or NuttX workspace. This section is about adding nano-ros to that project, without changing who is in charge.

The principle

nano-ros is a library your project imports. Your RTOS keeps its own build tool. You keep building with west, make, idf.py, cmake, or your IDE, exactly as before. nano-ros never compiles your kernel, never owns your linker script, and never replaces your build system.

What nano-ros contributes to your build is small and fixed:

• a Rust static library (the client runtime, behind a stable C ABI),
• generated code for your messages and system configuration,
• a thin C shim that your build compiles, so it sees your config headers (FreeRTOSConfig.h, lwipopts.h, sdkconfig, …).

The last point is why the shim is source, not a prebuilt: config-header mismatches between your kernel and a prebuilt binary are silent ABI breaks. Your compiler, your headers, your flags.

One shape per host build

Each supported host build system gets a small “shell” — build glue plus the host’s own package manifest — that makes nano-ros look native to it. Pick your row:

Notes on the rows that need them:

• Vendored FreeRTOS — STM32Cube, MCUXpresso, Pico SDK, and upstream FreeRTOS-Kernel all count. Your SDK builds the kernel and network stack; your CMake project does add_subdirectory(nano-ros) and links NanoRos::NanoRos. See the honest caveat in FreeRTOS: who builds the kernel?
• PX4 is a hookless host: its configure step cannot run nano-ros codegen from inside, so codegen runs ahead of the PX4 build, emitting module directories PX4 then builds natively. PlatformIO works the same way, via a pre-build script.
• IDE hosts (STM32CubeIDE, MCUXpresso IDE, IAR, Keil) have no build hook nano-ros can join. A drop-in emitter (prebuilt static library + shim sources + an integration README) is designed but not shipped yet. Today, the practical route is your IDE’s external-CMake or makefile support driving the CMake subdirectory path.

In every row the division of labor is the same: your build owns compile and link; nano-ros owns the adapter shell and the host-time code generation. Generated configuration is baked to C at build time on your host — system.toml and launch files never reach the device.

Two homes for configuration

When you integrate against your own board, you author facts in exactly two places. The split is by what kind of fact it is:

1. A board package — facts intrinsic to the board. A directory in your workspace with a package.xml and an nros-board.toml: the board’s name, RTOS platform, target triple, architecture, entry shape. These are true of every copy of that board on every desk, so they are reusable and shareable. Discovery: the CLI’s board catalog scans <nano-ros>/packages/boards/ plus every root named by NROS_EXTRA_BOARD_PATH (PATH-style list of directories shaped like packages/boards/), so an out-of-tree board dir is seen without copying it into the checkout.

2. An [image.<id>] block, and a [board_config.<board>] beside it — facts about this checkout, this machine, this application. It lives in your bringup package’s system.toml, next to your nodes and launch files:

[image.my-board]
board = "my-board"         # joins to the board package by name
                           # the rustc triple comes from that board's descriptor

[board_config."my-board"]  # site facts: where YOUR SDK lives, which config
sdk.vendor = "{env:VENDOR_SDK_DIR}"     # headers are yours — keyed by BOARD

SDK paths, config-header locations, serial ports: anything another developer’s checkout would spell differently belongs here, keyed per deploy target, and never in the board package.

If a fact would survive being published with the board, it is a board fact. If it names a path on your disk, it is a deploy fact.

FreeRTOS: who builds the kernel?

One honest exception to the principle. On the QEMU reference board, nano-ros can build the FreeRTOS kernel and lwIP for you — point FREERTOS_DIR at a kernel checkout and cmake/platform/nano-ros-freertos.cmake compiles it into the image. That is a convenience for the out-of-the-box demo, and it is the one place nano-ros compiles an RTOS.

With a vendored kernel — STM32Cube’s Middlewares/Third_Party/ FreeRTOS, MCUXpresso’s or the Pico SDK’s bundled kernel — do not use that path. Your SDK’s build owns the kernel, its port selection, and FreeRTOSConfig.h; nano-ros compiles against your include directories and links in as a library, the same as every other row in the table.

Where to go next

• Zephyr workspace: Zephyr (west module)
• NuttX board: NuttX (apps/external)
• ESP-IDF app: ESP32 (ESP-IDF component)
• PX4 firmware: PX4 (integration shell)
• Plain CMake host (FreeRTOS, ThreadX, POSIX): Build as a CMake subdirectory
• Deploy targets and system.toml: Deployment Workflow

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, and the FreeRTOS kernel + lwIP sources. You do not hand-install a cross-toolchain. The zenoh path DOES need a ROS 2 install for the router (ros2 run rmw_zenoh_cpp rmw_zenohd); the xrce path needs only the Micro-XRCE-DDS agent, which nros setup installs.

Setup

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

./scripts/bootstrap.sh      # builds packages/cli/target/release/nros
source ./activate.sh        # OR: direnv allow / source ./activate.fish

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, and the FreeRTOS + lwIP sources into ${NROS_HOME:-~/.nros}/sdk (plus the Micro-XRCE-DDS agent when you pick --rmw xrce). The zenoh router is NOT installed — it comes from your ROS 2 install (RFC-0075).

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                  # deps + [package.metadata.nros.deploy.freertos]
│   ├── .cargo/config.toml          # target + QEMU runner
│   ├── package.xml
│   ├── generated/                  # codegen output — build.rs runs
│   │                               #   `nros generate-rust` on first
│   │                               #   `cargo build`; gitignored.
│   └── src/lib.rs                  # the component class; nros::main! generates the entry
├── c/talker/                 # CMake project, add_subdirectory consumption
│   ├── CMakeLists.txt              # targets (deploy tuple in package.xml)
│   ├── package.xml
│   └── src/Talker.c
└── cpp/talker/               # CMake C++14 project
    ├── CMakeLists.txt
    ├── package.xml
    └── src/Talker.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

Deploy config (router locator, domain, RMW) is declared in the build manifest and baked at compile time — there is no config file on the device. Verbatim from the in-tree examples/qemu-arm-freertos/rust/talker/Cargo.toml:

[package.metadata.nros.deploy.freertos]
board     = "qemu-mps2-an385"
rmw       = "zenoh"
domain_id = 0
locator   = "tcp/10.0.2.2:7447"

The C / C++ trees declare the same in their package.xml <export> tuple (RFC-0048 §4); the connect locator rides the build config (-DNROS_ENTRY_LOCATOR / the fixture row), not the tuple:

<export>
  <build_type>ament_cmake</build_type>
  <nano_ros deploy="freertos" board="mps2-an385-freertos" rmw="zenoh"/>
</export>

Task stacks / priorities come from the board crate’s defaults (Cargo features), not a config file — see the Configuration Guide.

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.

Ports: the shipped examples dial host port 7447.

Contributors: the prebuilt test fixtures bake different ports — see Per-Platform Contributor Lanes.

Build

# Rust — `nros sync` first, once per checkout location. It writes the
# generated message bindings and the [patch.crates-io] table the leaf's
# .cargo/config.toml includes; without it cargo fails while PARSING the
# manifest, with an error that never names sync (see below).
cd examples/qemu-arm-freertos/rust/talker
nros sync
cargo build --release

# C / C++ — use the cross-toolchain CMake invocation (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

Contributors: the in-tree fixture build lanes for this platform are in Per-Platform Contributor Lanes.

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

If you skipped nros sync, the Rust build stops before it starts, with failed to load config include '../../../../../nros-patch.toml' and No such file or directory. That file is generated, not committed — run nros sync in the leaf and build again. The C / C++ builds above do not need it; see Workflow by Platform and Language for why the requirement is per language rather than per platform.

Run

# 1. Start the router (ROS's `rmw_zenohd`) on the host, on port 7447 —
#    the deploy locator the example bakes in its Cargo.toml
#    ([package.metadata.nros.deploy.freertos] locator, shown above).
#    Slirp forwards guest 10.0.2.2:<p> → host:<p>.
ZENOH_CONFIG_OVERRIDE='listen/endpoints=["tcp/127.0.0.1:7447"];scouting/multicast/enabled=false' \
    ros2 run rmw_zenoh_cpp rmw_zenohd &

# 2. Boot the talker in QEMU. The leaf's .cargo/config.toml runner
#    wraps qemu-system-arm with the LAN9118 + Slirp wiring:
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/String --qos-reliability best_effort

QEMU exits via Ctrl-A x.

Contributors: the in-tree fixture run/test lanes for this platform are in Per-Platform Contributor Lanes.

Readiness signal. Within ~20 seconds of QEMU boot, the talker should print Publishing: 'Hello World: 1' on its semihosting stdout — the count starts at 1, matching the official ROS 2 demo talker. QEMU cold-boot through FreeRTOS init + lwIP DHCP + zenoh session open typically takes 10–15 s. If no Publishing: line in 30 seconds:

1. Confirm the router is running on the host on the port the image dials (7447 for the copy-out example — Slirp forwards 10.0.2.2:7447 → host:7447). 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.
• Your own board / RTOS: the Board Integration matrix maps each user profile (Cargo-first, vendor-IDE, Zephyr, ESP-IDF, NuttX, niche fork) to the shortest bring-up path.
• 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 (contributor lanes 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 — the shipped examples/zephyr/c/talker/ quoted directly (only the project/class names are trimmed to my_app), so this page can’t drift from the real API surface. It is a stateful C component (a struct + a configure function, RFC-0043 / phase-244.C2) — not a hand-written main() — because the Zephyr typed carrier generates the entry point and calls into the component by identity:

# apps/my_app/CMakeLists.txt
cmake_minimum_required(VERSION 3.20.0)
find_package(Zephyr REQUIRED HINTS $ENV{ZEPHYR_BASE})
project(my_app)

set(NANO_ROS_PLATFORM zephyr)
include("${NROS_REPO_DIR}/cmake/NanoRosNodeRegister.cmake")
include("${NROS_REPO_DIR}/cmake/NanoRosVerbs.cmake")

nano_ros_auto_add_library(talker_lib STATIC src/Talker.c)

nros_components_register_node(talker_lib
    PLUGIN my_app::Talker
    EXECUTABLE talker
    SHAPE configure
    TYPED
    DEPLOY zephyr)

// apps/my_app/src/Talker.c
// `talker_configure` creates a raw publisher on `/chatter` + a timer that
// publishes a CDR-encoded Int32 counter each tick. `NROS_C_COMPONENT` emits
// the C-ABI factory/configure the Zephyr typed Entry carrier calls.
#include <stddef.h>
#include <stdint.h>
#include <stdio.h>

#include <nros/component.h>

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

static void write_u32_le(uint8_t* p, uint32_t v) {
    p[0] = (uint8_t)v;
    p[1] = (uint8_t)(v >> 8);
    p[2] = (uint8_t)(v >> 16);
    p[3] = (uint8_t)(v >> 24);
}

static void on_tick(void* ctx) {
    talker_t* self = (talker_t*)ctx;
    /* std_msgs/Int32 CDR: 4-byte encapsulation header (CDR_LE) + int32 data. */
    uint8_t buf[8];
    buf[0] = 0x00;
    buf[1] = 0x01;
    buf[2] = 0x00;
    buf[3] = 0x00;
    write_u32_le(buf + 4, (uint32_t)self->count);
    if (nros_cpp_publish_raw(self->pub, buf, sizeof(buf)) == 0) {
        printf("Published: %d\n", (int)self->count);
    }
    self->count++;
}

static nros_ret_t talker_configure(const nros_cpp_node_t* node, void* executor, talker_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_handle;
    return nros_cpp_timer_create(executor, /*period_ms=*/500, on_tick, self, &timer_handle);
}

NROS_C_COMPONENT(talker_t, talker_configure)

See examples/templates/zephyr-byo/app/src/Talker.c for the up-to-date source (this is that BYO starter’s talker, only stripped of its file header comment; the canonical in-tree examples/zephyr/c/talker/ uses the generated typed std_msgs/String bindings instead of raw CDR). Note the nros_cpp_* symbol prefix: those are C-ABI functions from nros-cpp (the cpp is a namespace prefix, not C++ linkage) — a C component links against them directly, and shares the same executor + node as a C++ component would.

prj.conf is the one shown in Configure below — note it needs both CONFIG_NROS_C_API=y and CONFIG_NROS_CPP_API=y: the typed Zephyr carrier that drives this component’s configure is C++, so the nros-cpp header surface must be on the app include path even though Talker.c itself is C.

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):

   ./scripts/bootstrap.sh      # builds packages/cli/target/release/nros
   source ./activate.sh        # OR: direnv allow / source ./activate.fish
   

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 (for zenoh: ZENOH_CONFIG_OVERRIDE='listen/endpoints=["tcp/127.0.0.1:7447"];scouting/multicast/enabled=false' ros2 run rmw_zenoh_cpp rmw_zenohd; 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: nros-v0.5.0      # pin a release tag (west needs SOME
                                 # revision — its default `master` does
                                 # not exist here). `main` works for
                                 # tracking tip, but a tag keeps your
                                 # build reproducible.
      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.)

nros build on Zephyr: it hands off, it does not take over

The other platforms let nros build own the build: it generates a cargo or CMake root from your [image.*] declarations and runs the tool. Zephyr is not like that, on purpose.

You own the west workspace and the application. west init / west update populate the workspace, your app carries its own CMakeLists.txt and prj.conf, and west only runs from inside that workspace. None of that is ours to generate — an app’s Kconfig is authored, not derived (RFC-0065 D5).

So for a Zephyr image nros build:

1. resolves the application — the entry package for that image’s board, not the bringup;
2. resolves your Zephyr — $ZEPHYR_BASE, else $NROS_ZEPHYR_WORKSPACE, else an in-tree zephyr-workspace/, else a sibling ../nano-ros-workspace. Note it is a Zephyr that is needed, not a .west/ directory: with ZEPHYR_BASE set, west build runs from anywhere, which is what makes a freestanding application — one outside the west workspace — work;
3. runs west build from there with the image’s overlays (EXTRA_CONF_FILE, APPLICATION_CONFIG_DIR) already applied.

If it cannot find a workspace it does not guess. It prints the command and where to run it:

$ nros build demo_bringup:zephyr
Error: no west workspace found, so `west build` cannot be run for `zephyr`.

Zephyr differs from the other drivers: YOU own the west workspace and the
application, and `west` only runs inside a workspace …

Run this from your west workspace:

    west build -b native_sim/native/64 …/src/zephyr_entry

Point nros at your workspace:

    NROS_ZEPHYR_WORKSPACE=<dir>   # the dir containing zephyr/

That is deliberate and it is the same boundary nros setup --system draws when it composes an install command and prints it rather than running sudo for you: where the tool is yours, nano-ros hands you the command instead of assuming it may act.

The plain west build below keeps working and is still the primary flow. nros build is the convenience that applies an image’s overlays for you; it never becomes a required layer between you and west.

Starting from nothing: nros new node and nros new entry

A node package is board- and RMW-agnostic — it names no platform, which is what lets the same package be deployed to Linux and to a Cortex-M without an edit:

nros new node talker_pkg

It writes the package and adds the [[component]] row to your bringup. (Use nros new <name> --platform native only for a standalone runnable project — it pins a board crate, so an entry on another platform cannot link it.)

The entry: nros new entry

You do not have to write the entry package by hand:

nros new entry zephyr_entry --platform zephyr

nros new entry: scaffolded ./src/zephyr_entry (7 file(s))
  declared [image.zephyr_entry] in ./src/demo_bringup/system.toml

Next:
  nros sync
  nros build demo_bringup:zephyr_entry --zephyr-workspace <dir>

It writes the package — Cargo.toml, CMakeLists.txt, build.rs, src/lib.rs, prj.conf, prj-zenoh.conf, boards/<board>.conf — and three things outside it that are easy to miss and invisible until they fail:

• the [image.*] block, with board, entry and the conf overlay the entry’s own CMakeLists.txt requires;
• an exclude entry in every enclosing cargo workspace, because a west-built staticlib must not be an ordinary cargo member;
• a path dependency per node package the bringup declares, since the entry links them.

--board, --rmw and --bringup override the defaults (native_sim/native/64, zenoh, and the workspace’s single bringup).

The whole flow, end to end

Five commands, run from your workspace. This is the examples/workspaces/rust transcript, verbatim:

# 0. tell nros where your west workspace is — the directory containing
#    `zephyr/`. On the command line:
#
#      nros build demo_bringup:zephyr --zephyr-workspace /path/to/zephyr-workspace
#
#    or once for the shell, if you would rather not repeat it:
export NROS_ZEPHYR_WORKSPACE=/path/to/zephyr-workspace

# 1. generate the message bindings this workspace's packages depend on.
#    `nros build` refuses with "this workspace has never been synced" until
#    you do — it will not silently build against absent bindings.
nros sync

# 2. build. This resolves the application, applies the image's overlays and
#    runs `west build` for you.
nros build demo_bringup:zephyr

# 3. start the router ROS itself uses — the one `rmw_zenoh_cpp` ships, so it
#    cannot drift from the RMW your ROS 2 nodes use. Separate terminal; it
#    keeps running. Listens on tcp/127.0.0.1:7447.
ros2 run rmw_zenoh_cpp rmw_zenohd

# 4. run the image.
./build/zephyr/zephyr.exe

*** Booting Zephyr OS build v3.7.0 ***
<inf> nros_net_wait: Network ready (NSOS — host kernel sockets)
<inf> rust: rustapp: nros: zephyr workspace entry up (2 nodes)
<inf> rust: talker_pkg: talker publishing chatter seq=0
<inf> rust: talker_pkg: talker publishing chatter seq=1

and from a ROS 2 shell on the same router, the nodes are ordinary ROS nodes:

$ export RMW_IMPLEMENTATION=rmw_zenoh_cpp
$ ros2 topic echo /chatter --once
data: 6
---

Step 3 is not optional and its ORDER does not matter, but the locator does: zenoh-pico is a client, so with no router the image gets

<err> rust: nros: zephyr entry — executor open failed: Transport(ConnectionFailed)

which names no port. Both sides default to tcp/127.0.0.1:7447 — the port rmw_zenohd listens on and a rmw_zenoh_cpp node connects to. Override with CONFIG_NROS_ZENOH_LOCATOR on the image side (via a conf fragment) and ZENOH_CONFIG_OVERRIDE='listen/endpoints=["tcp/127.0.0.1:<port>"]' on the router, and change both.

What an image declares

The Zephyr images in examples/workspaces/* are the worked examples:

[image.zephyr]
board = "native_sim/native/64"
entry = "zephyr_entry"          # only when several entries match, see below
conf  = ["prj-zenoh.conf"]      # the RMW overlay this app requires

• conf names the app’s own Kconfig fragments, in order. They are looked for beside the board config dir, then beside the application, then beside the bringup — the app rung matters because a Zephyr app keeps its prj-<rmw>.conf next to the CMakeLists.txt west builds. These entries FATAL_ERROR without an RMW overlay, so the image has to say which one.
• board is the Zephyr board target — and also a name nano-ros must know. See below.
• entry names the application package. Normally leave it out: an entry declares the deploy target it serves — [package.metadata.nros.entry] deploy in Cargo.toml, nano_ros_add_executable(... DEPLOY zephyr) in CMakeLists.txt — and one package usually claims a given board. Set it when several do (realtime-cpp has zephyr_entry and fvp_entry, both DEPLOY zephyr, on the same board, for two images that differ in payload). Deriving there is a coin flip, so nros build refuses and lists the candidates rather than picking one.

If you live in west: west nros

Everything above assumes you stand in your nano-ros workspace and name the Zephyr one. If you work the other way round — inside the west workspace — west already knows where Zephyr is, so it can tell nros for you:

cd ~/zephyr-workspace
west nros build --workspace ~/my_robot demo_bringup:zephyr

No ZEPHYR_BASE, no NROS_ZEPHYR_WORKSPACE, no --zephyr-workspace. Every argument after nros is passed straight through, so anything nros accepts works here unchanged.

It picks up automatically in any workspace whose manifest lists nano-ros — the same route west fvp takes. Two things worth knowing:

• It only exists inside a west workspace. West loads extension commands from the manifest, so from an unrelated directory you get west: unknown command "nros". That is why this is an addition rather than a replacement: it swaps which of the two trees you have to name, trading the Zephyr path (which differs per machine) for your own workspace path (which you chose).
• It never overwrites a ZEPHYR_BASE you set yourself — an exported one is a deliberate choice, and this only fills in a missing answer.

Which boards you can name

board does two jobs from one string: it is passed to west build -b verbatim, and it is looked up in nano-ros’s board catalog, where a descriptor carries a set of names:

names = ["zephyr", "native_sim/native/64"]

So it is not free-form. A board the catalog does not know is refused with the list of ones it does, because the descriptor supplies more than the -b string — the platform, the toolchain, the entry kind, the declared capabilities. There is no safe default for those.

A board is a package — put it in your workspace. Drop an nros-board.toml beside a package’s package.xml and it joins the catalog like any other package in src/:

my_robot/src/
├── talker_pkg/
└── my_board/
    ├── package.xml
    └── nros-board.toml

# src/my_board/nros-board.toml
[[board]]
names = ["my-board"]              # what your images say
west_board = "qemu_cortex_m3"     # what west is given
platform = "zephyr"
toolchain = "stable"
platform_feature = "platform-zephyr"
link_kind = "none"
entry_kind = "zephyr-staticlib"

# src/demo_bringup/system.toml
[image.zephyr]
board = "my-board"

No environment variable, nothing outside the tree, nothing copied into the nano-ros checkout. west_board is what lets the friendly name be the one your workspace uses — leave it out when your board name already is the west board target, which is what the shipped descriptors do.

For a board shared by several workspaces there is no single workspace to put it in, and $NROS_EXTRA_BOARD_PATH still covers that: PATH-style, naming directories shaped like packages/boards/.

nros new board <name> --for-platform zephyr scaffolds the descriptor. Note this is the nano-ros descriptor; an out-of-tree Zephyr board definition (its devicetree and board.yml) is contributed the Zephyr way, through your module’s board_root.

Adding your own drivers, modules and boards

Everything Zephyr lets you extend, you still extend the Zephyr way. The application CMakeLists.txt is yours (RFC-0065 D5) and nros build runs west build against it, so the extension points are untouched:

Only the last two rows are ours, and they are how an IMAGE differs from its siblings — the module itself is a property of the application, not of one image, so it belongs in the app’s CMakeLists.txt where you would have put it anyway.

nros build passes exactly four things to west of its own — APPLICATION_CONFIG_DIR, EXTRA_CONF_FILE, EXTRA_DTC_OVERLAY_FILE, FILE_SUFFIX, all Zephyr’s own variables — and there is deliberately no image key for arbitrary -D defines. Something your application always needs belongs in its CMakeLists.txt, which keeps one place to look.

Customizing the west command itself

Anything after -- goes to west. west build has two argument zones, and nros build routes each token to the right one using west’s own flag list:

nros build demo_bringup:zephyr -- --pristine        # a west option
nros build demo_bringup:zephyr -- -t run            # build, then run it
nros build demo_bringup:zephyr -- -DMY_OPT=1        # a cmake option
nros build demo_bringup:zephyr -- -p always -DX=1   # both, in one go

which becomes, respectively, the west option zone and the cmake zone:

west build -b <board> <app> -p always -- -DEXTRA_CONF_FILE=… -DX=1

nros build --dry-run prints that line without running it, so you can always see exactly what west is being asked to do — and copy it if you would rather drive west yourself.

Two flags are refused rather than routed, because the image already decides them and a build must not be able to disagree with its own declaration:

$ nros build demo_bringup:zephyr -- --sysbuild
Error: `--sysbuild` is decided by the image, not by the command line.
It comes from the presence of a `sysbuild.conf` beside the application.

Change it there, so one build cannot disagree with the declaration it was
resolved from.

The other is -b/--board, which comes from the image’s board.

Verified by building one. An out-of-tree module with its own Kconfig, a driver source gated on it, a devicetree overlay declaring a node and a binding shipped from the module’s dts_root, added to examples/workspaces/rust’s entry and enabled through the image:

[image.zephyr]
conf = ["prj-zenoh.conf", "prj-user-extra.conf", "user-widget.overlay"]

*** Booting Zephyr OS build v3.7.0 ***
user_extra: out-of-tree driver init, widget-id=42
<inf> rust: rustapp: nros: zephyr workspace entry up (2 nodes)
<inf> rust: talker_pkg: talker publishing chatter seq=0

The driver’s BUILD_ASSERT(DT_NODE_EXISTS(DT_NODELABEL(user_widget))) is what makes that a test rather than a screenshot: without the overlay reaching the build, it fails to compile instead of quietly doing nothing.

A mistake in your module surfaces as Zephyr’s own error, unmediated — a wrong kconfig: path in module.yml reports

ERROR: "kconfig" key in …/extra_module/zephyr/module.yml has value
"../Kconfig" which does not point to a valid Kconfig file.

which is the message you would get from a plain west build, because it is a plain west build.

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 a router started with ZENOH_CONFIG_OVERRIDE='listen/endpoints=["tcp/127.0.0.1:7447"];scouting/multicast/enabled=false' ros2 run rmw_zenoh_cpp rmw_zenohd. On the Zephyr 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 the router (ROS's `rmw_zenohd` — nano-ros ships no router
#    of its own) on port 7447, the port your app's Kconfig default
#    picks up (CONFIG_NROS_ZENOH_LOCATOR defaults to
#    "tcp/127.0.0.1:7447"; change either side to match):
ZENOH_CONFIG_OVERRIDE='listen/endpoints=["tcp/0.0.0.0:7447"];scouting/multicast/enabled=false' \
    ros2 run rmw_zenoh_cpp rmw_zenohd &

# 2. Boot the app from your BYO west workspace:
# QEMU Cortex-A9:
west build -t run
# native_sim:
./build/zephyr/zephyr.exe

# 3. Verify from stock ROS 2 in another terminal. Match the message
# type to the app you booted: the canonical in-tree talker publishes
# std_msgs/String; the raw BYO Talker.c shown above publishes
# std_msgs/Int32.
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/String --qos-reliability best_effort   # in-tree talker
# ros2 topic echo /chatter std_msgs/msg/Int32 --qos-reliability best_effort  # BYO my_app

Contributors: nano-ros’s own zephyr talker has a matching in-tree recipe for the canonical native_sim build path — see Per-Platform Contributor Lanes.

The Zephyr boot banner runs first, then the talker fires: the canonical in-tree talker prints Publishing: 'Hello World: 1', Publishing: 'Hello World: 2', … (Rust + C + C++ all count from 1, matching the official ROS 2 demo talker); the raw BYO Talker.c above prints Published: 0, Published: 1, …

Readiness signal. On native_sim, expect the first publish line (Publishing: 'Hello World: 1' for the in-tree talker; Published: 0 for the BYO app) within 5 seconds of boot (or ./build/zephyr/zephyr.exe); on qemu_cortex_a9 expect it within ~15 seconds (QEMU cold boot + Zephyr init). If no publish 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:7447 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 (contributors: the in-tree just zephyr build-one recipe applies it 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).

Zephyr (contributor / in-tree workflow)

Looking for the user-facing path? This page covers building nano-ros’s own Zephyr examples from this repository. If you’re consuming nano-ros as a Zephyr module in YOUR Zephyr workspace, see Integration: Zephyr (west module) instead.

Complete setup procedure for Zephyr native_sim testing. Networking uses NSOS (Native Sim Offloaded Sockets) — each socket call is forwarded to the host kernel, so tests run on 127.0.0.1 without TAP devices, bridges, or sudo.

Overview

nros uses an in-tree Zephyr workspace at zephyr-workspace/ (gitignored). Set $NROS_ZEPHYR_WORKSPACE to install elsewhere.

nros/
├── scripts/zephyr/
│   ├── setup.sh                      # Initialize workspace
│   ├── migrate-workspace.sh          # Move legacy sibling install in-tree
│   ├── downloads/                    # SDK tarball cache (gitignored)
│   └── sdk/                          # Installed Zephyr SDK (gitignored)
├── zephyr/                           # Zephyr module definition
│   ├── Kconfig                       # RMW backend, API selection, tuning
│   ├── CMakeLists.txt                # Transport C sources + nros-c build
│   └── cmake/                        # nros_cargo_build(), nros_generate_interfaces()
├── examples/zephyr/
│   ├── rust/                   # Rust + zenoh (talker, listener, ...)
│   ├── rust/xrce/                    # Rust + XRCE-DDS (talker, listener)
│   ├── c/                      # C + zenoh (talker, listener)
│   └── c/xrce/                       # C + XRCE-DDS (talker, listener)
├── west.yml                          # West manifest
└── zephyr-workspace/                 # Created by setup.sh (gitignored)
    ├── nros -> ../                   # Symlink back to repo root
    ├── zephyr/                       # Zephyr RTOS v3.7.0
    └── modules/                      # HALs, zephyr-lang-rust

Migrating from the legacy sibling layout

Legacy setups put the workspace at ../nano-ros-workspace/ with an in-tree symlink. Both layouts work (contributors: the in-tree just zephyr recipes auto-detect either), but to consolidate run:

./scripts/zephyr/migrate-workspace.sh --dry-run     # preview
./scripts/zephyr/migrate-workspace.sh               # execute

Prerequisites

Build the in-tree nros CLI (Phase 218), then let it provision the toolchain:

./scripts/bootstrap.sh      # builds packages/cli/target/release/nros
source ./activate.sh        # OR: direnv allow / source ./activate.fish

nros setup provides most components prebuilt per platform per RMW — the cross-compiler, emulator, RMW host daemon, and SDK sources (including the Zephyr west workspace + Zephyr SDK bits) are fetched from a pinned index into a shared store at ${NROS_HOME:-~/.nros}/sdk. You do not hand-install a cross-toolchain, and you do not need ROS 2 installed.

Packages are prebuilt where the index has a binary for your host and built from source otherwise — zenohd is the notable source build, and zenoh is the default --rmw. --dry-run prints the plan for your host. See Installation for the full explanation.

Step 1: Initialize Workspace (One-Time)

nros setup zephyr --rmw zenoh      # --rmw defaults to zenoh; xrce | cyclonedds also valid
source ./activate.sh

This provisions:

• The Zephyr west workspace + Zephyr SDK bits
• The emulator
• The RMW host daemon (zenohd for zenoh, the Micro-XRCE-DDS agent for xrce)
• The in-tree workspace at zephyr-workspace/ (gitignored; auto-detects legacy ../nano-ros-workspace/), with nros symlinked in
• Rust embedded targets

Contributors: the in-tree just setup zephyr recipe still works and now delegates to nros setup zephyr under the hood.

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

Step 2: Networking

No network setup is required. native_sim uses the NSOS offloaded-sockets driver, enabled by boards/native_sim_native_64.conf in each example:

CONFIG_ETH_NATIVE_POSIX=n
CONFIG_NET_SOCKETS_OFFLOAD=y
CONFIG_NET_NATIVE_OFFLOADED_SOCKETS=y

With NSOS, Zephyr’s socket API goes straight to host syscalls. Bind to 127.0.0.1 and reach zenohd / the XRCE Agent on the host loopback just like any other native test. Multiple native_sim processes can coexist without bridge configuration.

Step 3: Build and Run Zephyr Examples

# Source environment
source zephyr-workspace/env.sh

cd zephyr-workspace

# Rust — `nros sync` first, once per checkout location. It writes the
# generated message bindings and the [patch.crates-io] table the leaf's
# .cargo/config.toml includes. This applies to cargo under WEST too: west
# drives the same leaf, so without sync the build fails while PARSING the
# manifest, with an error that never names sync (issue 0694).
#
# `--no-metadata` because the source-metadata probe builds a host binary that
# path-deps this leaf, dragging in the `zephyr` crate — whose build.rs needs a
# DOTCONFIG from a Zephyr cmake configure that has not run yet, and cannot,
# since this sync is its prerequisite (issue 0318). Without the flag the sync
# still succeeds but prints a "no producer" error the reader cannot act on.
# Codegen and the patch table — the reason to run it — are unaffected.
nros sync --no-metadata ../examples/zephyr/rust/talker

# Build Zephyr talker (Rust + zenoh, default backend).
#
# `../examples/...` rather than `<name>/examples/...`: the workspace's link
# back to the checkout is named after YOUR checkout directory
# (`scripts/zephyr/setup.sh` uses `basename "$NANO_ROS_ROOT"`), so it reads
# `nano-ros/` for a plain `git clone` and `nros/` only if you renamed the
# directory. For the in-tree workspace this page sets up, `..` IS the
# checkout and needs no name at all.
west build -b native_sim/native/64 ../examples/zephyr/rust/talker

# Run (no sudo needed)
./build/zephyr/zephyr.exe

RMW Backend Selection

nros supports three RMW backends on Zephyr, selected via prj.conf:

Zenoh (default)

Connects to a zenoh router. Requires POSIX API for zenoh-pico threads.

CONFIG_NROS=y
# CONFIG_NROS_RMW_ZENOH=y  # default, can be omitted
CONFIG_NROS_ZENOH_LOCATOR="tcp/127.0.0.1:7447"
CONFIG_POSIX_API=y
CONFIG_MAX_PTHREAD_MUTEX_COUNT=32
CONFIG_MAX_PTHREAD_COND_COUNT=16

XRCE-DDS

Connects to a Micro-XRCE-DDS Agent over UDP. Requires BSD sockets.

CONFIG_NROS=y
CONFIG_NROS_RMW_XRCE=y
CONFIG_NROS_XRCE_AGENT_ADDR="127.0.0.1"
CONFIG_NROS_XRCE_AGENT_PORT=2018
CONFIG_NET_SOCKETS=y

Cyclone DDS

Brokerless RTPS, wire-compatible with stock ROS 2 (rmw_cyclonedds_cpp). Cyclone’s source is C++, so CONFIG_CPP=y is required even for Rust callers. Cyclone is resource-heavy — it needs a large heap, libc malloc arena, and pthread pools. The bool prerequisites (thread-local storage, dynamic threads, NET_TCP, …) are selected automatically by CONFIG_NROS_RMW_CYCLONEDDS in zephyr/Kconfig; the size knobs stay in prj.conf:

CONFIG_NROS=y
CONFIG_NROS_RMW_CYCLONEDDS=y
CONFIG_CPP=y
CONFIG_POSIX_API=y
CONFIG_NET_IPV4_IGMP=y                  # RTPS SPDP uses UDP multicast
CONFIG_MAIN_STACK_SIZE=524288
CONFIG_HEAP_MEM_POOL_SIZE=4194304
CONFIG_COMMON_LIBC_MALLOC_ARENA_SIZE=16777216
CONFIG_DYNAMIC_THREAD_STACK_SIZE=32768

On native_sim, add the NSOS host-socket offload (CONFIG_NET_SOCKETS_OFFLOAD=y + CONFIG_NET_NATIVE_OFFLOADED_SOCKETS=y) so discovery uses host BSD sockets instead of zeth/TAP. See examples/zephyr/rust/talker/prj-cyclonedds.conf for the full overlay.

API Selection

Choose between Rust and C APIs via prj.conf:

Rust API (default)

CONFIG_NROS_RUST_API=y
CONFIG_RUST=y
CONFIG_RUST_ALLOC=y

CMakeLists.txt uses rust_cargo_application():

cmake_minimum_required(VERSION 3.20.0)
find_package(Zephyr REQUIRED HINTS $ENV{ZEPHYR_BASE})
project(my_example)
rust_cargo_application()

C API

CONFIG_NROS_C_API=y

CMakeLists.txt uses nros_generate_interfaces():

cmake_minimum_required(VERSION 3.20.0)
find_package(Zephyr REQUIRED HINTS $ENV{ZEPHYR_BASE})
project(my_example)
nros_generate_interfaces(std_msgs "msg/Int32.msg")
target_sources(app PRIVATE src/main.c)

Kconfig Reference

All options are under menuconfig NROS in zephyr/Kconfig.

Common Options

Zenoh Options (visible when CONFIG_NROS_RMW_ZENOH=y)

-1 means “derive it from the message bounds”

Three of the rows above, plus CONFIG_NROS_SUBSCRIPTION_BUFFER_SIZE, default to -1. That is not a size: it is how an image says nothing here chose a number, work it out (phase-403 W8, issue 0940).

Codegen derives an exact serialized-size bound for every message type it generates and writes it beside the code as nros_message_bounds.cmake. The build composes those, and the configure prints what it concluded:

-- nros: message-bound sizing DERIVED from 84 types in 11 interface packages (all bounded)
-- nros:   largest type std_msgs/msg/Float64MultiArray at 1496 B -> NROS_SUBSCRIPTION_BUFFER_SIZE
-- nros:   0 types over the 2048 B ceiling -> NROS_MAX_LARGE_SUBSCRIBERS

Three things to know before you rely on it:

• Anything you state wins. A value in your prj.conf, a board .conf, or an environment override outranks the derivation, silently and in both directions. The derived number is a default, never an override.
• It is an UPPER BOUND. The inventory covers every type in the interface closure you LINK, not the ones you subscribe to, so the number is the largest message the image could receive. That is the safe direction, and it can still be far above what you need: the line above names std_msgs/Float64MultiArray, which that image never receives. When the type it names is not one of yours, either state your own value or stop linking the package.
• One unbounded type refuses the lot. If any type in the closure has no derived bound, nothing is derived, every knob keeps its configured value, and the configure names the types and the members that cost them their bound. Deriving over the rest would publish a maximum a real sample can exceed, and that drop is silent on the C++ arena path. The remedy is a bound in the .msg or an inline cap in nros-codegen.toml; one cap on a declaring type ("std_msgs/Header.frame_id") reaches every message that nests it.

The answer, and why it came out that way, is written to <build>/nros/message_bound_knobs.cmake.

XRCE Options (visible when CONFIG_NROS_RMW_XRCE=y)

C API Options (visible when CONFIG_NROS_C_API=y)

E2E Testing

Contributors: the in-tree fixture/test lanes for this platform are in Per-Platform Contributor Lanes.

Troubleshooting

Network Architecture

With NSOS, Zephyr sockets are forwarded to host syscalls — there is no emulated L2/L3 stack to configure, no static IP, and no bridge.

┌─────────────────────────────────────────────────────────────┐
│                      Host (Linux)                            │
│                                                              │
│   ┌────────────────────┐       ┌────────────────────────┐   │
│   │ zephyr.exe talker  │       │ zephyr.exe listener    │   │
│   │ (native_sim+NSOS)  │       │ (native_sim+NSOS)      │   │
│   └─────────┬──────────┘       └──────────┬─────────────┘   │
│             │ host socket() via NSOS       │                │
│             ▼                              ▼                │
│                 127.0.0.1 (loopback)                        │
│             │                              │                │
│             ▼                              ▼                │
│   ┌────────────────────┐       ┌────────────────────────┐   │
│   │ zenohd             │       │ MicroXRCEAgent         │   │
│   │ tcp/127.0.0.1:7447 │       │ udp/127.0.0.1:2018     │   │
│   └────────────────────┘       └────────────────────────┘   │
└─────────────────────────────────────────────────────────────┘

Updating the Workspace

To update Zephyr and modules to latest versions specified in west.yml:

cd zephyr-workspace
west update

To completely recreate the workspace:

Contributors: the in-tree workspace-recreate lane is in Per-Platform Contributor Lanes.

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 mostly-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:

./scripts/bootstrap.sh      # builds packages/cli/target/release/nros (Phase 218)
source ./activate.sh        # OR: direnv allow / source ./activate.fish
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 setup nuttx        # 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 in as external/nano-ros. Menuconfig surfaces it under Application Configuration → External Modules.

Passing --bringup <dir> additionally stages a per-bringup app (external/<bringup>/, with the bringup tree symlinked alongside as external/<bringup>-source) — the Phase 212 multi-package workspace shape. There are no per-EXAMPLE symlinks: that staging loop was retired in phase-212.M-F.12 when the bringup path superseded it.

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.

Deploy config (RMW / domain id, plus an optional locator override) is declared in the build manifest and baked at compile time. Verbatim from the in-tree examples/qemu-arm-nuttx/rust/talker/Cargo.toml:

[package.metadata.nros.deploy.nuttx]
board     = "qemu-armv7a-nsh"
target    = "armv7a-nuttx-eabihf"
rmw       = "zenoh"
domain_id = 0

The C / C++ variants declare the same in their package.xml <export> tuple (RFC-0048 §4):

<export>
  <build_type>ament_cmake</build_type>
  <nano_ros deploy="nuttx" board="nuttx-qemu-arm" rmw="zenoh"/>
</export>

The guest network shape (eth0 10.0.2.30, Slirp gateway 10.0.2.2) comes from the board crate; add a locator = "tcp/10.0.2.2:<port>" field to dial a non-default router port. The prebuilt test fixtures bake distinct per-language allocator ports so parallel suites don’t collide on one router. Start the router (ROS’s rmw_zenohd) on the port your app dials — it must listen on 0.0.0.0, not loopback, because the guest reaches it through QEMU’s Slirp gateway:

ZENOH_CONFIG_OVERRIDE='listen/endpoints=["tcp/0.0.0.0:8200"];scouting/multicast/enabled=false' \
    ros2 run rmw_zenoh_cpp rmw_zenohd

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 the router on the host (Slirp forwards 10.0.2.2:<port> →
#    host). It must listen on 0.0.0.0 for the Slirp gateway; 8200 is
#    the port the in-tree lanes use — match whatever `locator` your
#    app bakes:
ZENOH_CONFIG_OVERRIDE='listen/endpoints=["tcp/0.0.0.0:8200"];scouting/multicast/enabled=false' \
    ros2 run rmw_zenoh_cpp rmw_zenohd &

# 2. QEMU NuttX (ARM). For a NuttX-managed workspace where you've
#    staged the integration shell + your own app, boot QEMU directly:
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/String --qos-reliability best_effort

Contributors: the in-tree fixture/test lanes for nano-ros’s own QEMU examples are in Per-Platform Contributor Lanes.

Readiness signal. After typing the app’s NSH command (e.g. nuttx_c_talker), expect Publishing: 'Hello World: 1' on the NSH console within ~6 seconds — Rust + C + C++ talkers all start the count at 1, matching the official ROS 2 demo talker. If no Publishing: 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 (the board crate’s default for the qemu-arm-nuttx examples).
3. Confirm zenohd reachable; the deploy locator (or the nros_init arguments) must match the router’s listen port.
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. In-tree that is scripts/nuttx/stage-external-apps.sh --bringup <dir>, the only supported NuttX make path since phase-212 M-F.16 retired the per-example build-fixtures-make recipe. If you wire a NuttX workspace by hand, reproduce the same three steps:

1. Bring the required symbols into your config. Stock NuttX qemu-armv7a/nsh ships without CONFIG_NET=y, virtio-net, or TLS_NELEM. If you have no config of your own, copy the board defconfig packages/boards/nros-board-nuttx-qemu/nuttx-config/arm/defconfig to $NUTTX_DIR/.config and run make olddefconfig. If you already maintain a vendor defconfig, do NOT clobber it — merge the nano-ros requirements into it instead (CONFIG_NET=y, the virtio-net / netdev options, CONFIG_TLS_NELEM=8, CONFIG_LIBCXXTOOLCHAIN=y, CONFIG_ALLSYMS=n; diff the board defconfig against nsh for the authoritative list) and re-run make olddefconfig.
2. Stage the integration shell. Run scripts/nuttx/stage-external-apps.sh "$NUTTX_APPS_DIR" to symlink integrations/nuttx/ into $NUTTX_APPS_DIR/external/ (add --bringup <dir> for a workspace app). 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).

NuttX (contributor / in-tree workflow)

Looking for the user-facing path? This page covers building nano-ros’s own NuttX examples on QEMU from this repository. If you’re integrating nano-ros into YOUR NuttX app at apps/external/nano-ros/, see Integration: NuttX external app instead.

nano-ros runs on NuttX, targeting QEMU ARM virt (Cortex-A7 + virtio-net). NuttX provides POSIX-compatible BSD sockets, which makes it the most straightforward RTOS port – zenoh-pico uses the same socket API as on Linux.

Overview

The NuttX platform uses:

• NuttX RTOS – POSIX-compliant real-time OS with BSD socket support
• BSD sockets – standard socket API provided by NuttX’s network stack
• zenoh-pico – Zenoh transport over NuttX sockets (same code path as POSIX)
• virtio-net – NuttX built-in Ethernet driver (no custom driver needed)

Board crate: nros-board-nuttx-qemu (in packages/boards/) — ONE crate serves both QEMU NuttX boards, arm virt and rv-virt. Everything that differs between them is data (a defconfig, a toolchain file, a target triple); nothing in the Rust or C sources is arch-conditional.

Why NuttX Is Simpler Than FreeRTOS

NuttX is the simplest RTOS platform to port because of its strong POSIX compliance (POSIX.1-2008: pthreads, BSD sockets, select(), clock_gettime()):

Because NuttX supports Rust std, examples use standard fn main() entry points and println! – no semihosting or custom panic handlers needed.

Setup

nros setup qemu-arm-nuttx provisions everything this board needs — the NuttX cross-compiler, qemu-system-arm, the NuttX source tree, and the RMW host daemon — into the shared store at ~/.nros/sdk. No hand-installed cross-toolchain and no ROS 2 install required.

Build the in-tree nros CLI (Phase 218), then provision the board (--rmw defaults to zenoh):

./scripts/bootstrap.sh      # builds packages/cli/target/release/nros
source ./activate.sh        # OR: direnv allow / source ./activate.fish
nros setup qemu-arm-nuttx --rmw zenoh

As a contributor, just setup nuttx remains available and now delegates to nros setup qemu-arm-nuttx for the toolchain/SDK provisioning while also staging the external apps.

The NuttX sources land in third-party/nuttx/nuttx/ and third-party/nuttx/nuttx-apps/. Override the paths with environment variables if your sources are elsewhere:

Prerequisites

The nros setup qemu-arm-nuttx step above provisions the qemu-system-arm emulator and the arm-none-eabi-gcc cross-compiler used for NuttX kernel compilation. The one host-side tool you still supply yourself:

• Rust nightly toolchain (NuttX targets are Tier 3, require -Z build-std)

Building

Contributors: the in-tree build lanes for this platform are in Per-Platform Contributor Lanes.

The examples link against NuttX’s POSIX layer, which provides sockets, pthreads, and standard I/O.

Available Examples

All examples are in examples/qemu-arm-nuttx/rust/:

RISC-V (rv-virt, riscv32)

The same NuttX path also runs on QEMU’s RISC-V rv-virt board (rv32imac, riscv32imac-unknown-nuttx-elf), proving the provisioning path is arch-agnostic. Provision and build with:

nros setup qemu-riscv-nuttx --rmw zenoh

Contributors: the in-tree RISC-V fixture build lanes are in Per-Platform Contributor Lanes.

Board crate: nros-board-nuttx-qemu (in packages/boards/) — the same crate as the arm board above, selected by deploy = "nuttx-riscv", which picks the rv-virt [[board]] entry of its nros-board.toml (riscv toolchain, riscv defconfig, riscv32imac-unknown-nuttx-elf). The C pub/sub pair is exercised end-to-end under qemu-system-riscv32, and Rust / C / C++ realtime-tiers workspace runtime lanes cover the multi-tier scheduling path on this board.

Testing

Contributors: the in-tree test lanes for this platform are in Per-Platform Contributor Lanes.

Tests run under qemu-system-arm -M virt with TAP networking. Each QEMU instance connects to the host bridge (br-qemu) via TAP devices for zenohd communication. The test infrastructure builds a NuttX kernel image with the example app embedded, boots it in QEMU, and verifies message exchange.

Network Configuration

NuttX QEMU instances use the same IP scheme as other QEMU board crates:

Architecture

Board Crate

The nros-board-nuttx-qemu board crate follows the standard Config / run() pattern documented in the Custom Board Package guide. It provides network and node configuration presets (talker(), listener(), server(), client()).

Unlike bare-metal and FreeRTOS board crates, there is no custom hardware initialization, no network stack setup, and no task creation. NuttX’s kernel boots the hardware, initializes virtio-net, and starts the application before main() runs. Because NuttX supports Rust std, examples use standard fn main() entry points.

NuttX Defconfig

The QEMU board configuration lives in packages/boards/nros-board-nuttx-qemu/nuttx-config/arm/defconfig (the rv-virt one sits beside it under riscv/) and enables:

• CONFIG_NET – networking subsystem
• CONFIG_NET_TCP / CONFIG_NET_UDP – TCP/UDP protocols
• CONFIG_DRIVERS_VIRTIO + CONFIG_DRIVERS_VIRTIO_NET – virtio Ethernet
• CONFIG_PTHREAD_MUTEX_TYPES – POSIX mutex types (for zenoh-pico)
• CONFIG_DEV_URANDOM – /dev/urandom for session ID generation
• CONFIG_DEFAULT_TASK_STACKSIZE=8192 – adequate stack for nros apps
• CONFIG_BUILD_FLAT – flat memory model (no MMU protection)

Status

NuttX platform support is complete: feature flags, build integration, six Rust examples, E2E network tests, and documentation.

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.

Contributors: the in-tree fixture/test lanes for this platform are in Per-Platform Contributor Lanes.

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, and ThreadX/NetX sources — no hand-installed riscv64 cross toolchain or qemu-system-riscv64. The zenoh path additionally needs a ROS 2 install for the router (ros2 run rmw_zenoh_cpp rmw_zenohd); xrce needs only the Micro-XRCE-DDS agent, which nros setup installs.

Setup

nros setup is the single canonical command to prepare a machine to build nano-ros for a board. Most components are prebuilt per platform per RMW — the cross-compiler, emulator, 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. The zenoh router is NOT among them — it comes from a ROS 2 install (RFC-0075); only the xrce agent is provisioned by nros setup.

Packages are prebuilt where the index has a binary for your host and built from source otherwise. --dry-run prints the plan for your host. See Installation for the full explanation.

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

./scripts/bootstrap.sh      # builds packages/cli/target/release/nros
source ./activate.sh        # OR: direnv allow / source ./activate.fish

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 ./activate.sh

The RMW host daemon must be running before any example: for zenoh the ROS 2 router (ros2 run rmw_zenoh_cpp rmw_zenohd), for xrce the Micro-XRCE-DDS agent (installed by nros setup … --rmw xrce).

Project layout

Each example is a standalone Cargo or CMake project under examples/threadx-linux/ and examples/qemu-riscv64-threadx/ (<lang>/<example>/ under each):

examples/threadx-linux/
├── rust/talker/                 # Cargo, target = x86_64-unknown-linux-gnu
│   ├── Cargo.toml                # deps + [package.metadata.nros.deploy.threadx-linux]
│   ├── package.xml
│   ├── generated/                # codegen output — build.rs runs
│   │                             #   `nros generate-rust` on first
│   │                             #   `cargo build`; gitignored.
│   └── src/lib.rs                # the component class; nros::main! generates the entry
└── c/talker/                    # CMake, add_subdirectory
    ├── CMakeLists.txt            # targets (deploy tuple in package.xml)
    ├── package.xml
    └── src/Talker.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).

Why there are two board crates and one arch port

The two flavours look like one board with two targets, and they are not. nano-ros ships three ThreadX packages, in the three layers RFC-0064 describes:

The arch port is the reason the two boards did not merge. Upstream’s RISC-V64 port types ULONG as unsigned long — 8 bytes on rv64 — but NetX Duo’s packet code does ULONG * arithmetic assuming 4-byte words, so nano-ros retypes it to unsigned int, matching upstream’s own Linux and AArch64 ports. That retype shifts every field offset inside TX_THREAD, and the port’s context-switch assembly loads those fields at hard-coded offsets — so the header change forces the assembly to be forked with it. threadx-linux needs none of this, because upstream’s Linux port already types ULONG as 4 bytes.

That is architecture code, not board code: a second RISC-V64 ThreadX board would need every line of it unchanged, and folding it into a crate that also serves Linux would mean cfg-gating RISC-V assembly there. If you are porting to another RISC-V64 ThreadX board, depend on the arch port and write only the overlay — see Custom boards.

One rule matters if you build ThreadX outside the shipped recipes: the arch port’s inc/ must be searched before $THREADX_DIR/ports/risc-v64/gnu/inc. Get that wrong and the build succeeds against upstream’s 8-byte ULONG, and the symptom is corrupted packets at runtime rather than a compiler error. A _Static_assert(sizeof(ULONG) == 4, …) in packages/boards/nros-board-common/c/threadx_hooks.c turns that mistake into a build failure with a name on it.

Configure

Deploy config is declared per flavour in the build manifest and baked at compile time. Both shipped shapes, verbatim:

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

[package.metadata.nros.deploy.threadx-linux]
board     = "threadx-linux"
rmw       = "zenoh"
domain_id = 0
# locator/ip default to the board's loopback shape (dial 127.0.0.1)

threadx-riscv64 — examples/qemu-riscv64-threadx/c/talker/CMakeLists.txt:

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

find_package(nano_ros REQUIRED)
find_package(std_msgs REQUIRED)

nano_ros_add_executable(c_talker src/main.c)
ament_target_dependencies(c_talker std_msgs)

The deploy coordinate lives in package.xml, not CMake: <nano_ros deploy="threadx" board="riscv64-qemu" rmw="zenoh"/>.

Network shape (guest IP, gateway, router locator) beyond these fields comes from the board crate’s defaults — see the Configuration Guide.

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

# Single example — `nros sync` first (a hand-run cargo build does
# not do it for you):
cd examples/threadx-linux/rust/talker
nros sync
cargo build --release

Contributors: the in-tree fixture build lanes for both flavours are in Per-Platform Contributor Lanes.

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

Contributors (in-tree checkout): the just … build-fixtures recipes run nros sync for you. A hand-run cargo build in a leaf does not — without it cargo fails while parsing the manifest, with failed to load config include '…/nros-patch.toml' and no mention of sync. See Workflow by Platform and Language.

Run

# threadx-linux (no QEMU). Step 1 brings up the router (ROS's
# `rmw_zenohd`) on port 9000 — the deploy `locator` the talker bakes
# in its Cargo.toml. Step 2 builds + runs the talker:
ZENOH_CONFIG_OVERRIDE='listen/endpoints=["tcp/0.0.0.0:9000"];scouting/multicast/enabled=false' \
    ros2 run rmw_zenoh_cpp rmw_zenohd &
cd examples/threadx-linux/rust/talker && nros sync && cargo run --release
# Expected (per src/lib.rs structured logs):
#   Publishing: 'Hello World: 1'
#   Publishing: 'Hello World: 2'
#   ...

# threadx-riscv64 (QEMU virt). Same shape — the router on 9400 first
# (the riscv64 talker dials tcp/10.0.2.2:9400 through QEMU Slirp):
ZENOH_CONFIG_OVERRIDE='listen/endpoints=["tcp/127.0.0.1:9400"];scouting/multicast/enabled=false' \
    ros2 run rmw_zenoh_cpp rmw_zenohd &

# Then boot the built image in QEMU (UART on stdio, Slirp networking):
qemu-system-riscv64 -M virt -m 256M -bios none -nographic \
    -global virtio-mmio.force-legacy=false \
    -kernel <path-to-built-talker-elf> \
    -netdev user,id=net0 \
    -device virtio-net-device,netdev=net0,bus=virtio-mmio-bus.0
# **Contributors (in-tree checkout):** `just threadx_riscv64 talker`
# builds and boots this exact shape in one step.

# 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/String --qos-reliability best_effort

Contributors: the in-tree fixture run/test lanes are in Per-Platform Contributor Lanes.

Readiness signal. threadx-linux: Publishing: 'Hello World: 1' within a few seconds of cargo run --release 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 Publishing: line:

1. Confirm the router is reachable on the deploy locator (threadx-linux uses 127.0.0.1; riscv64 QEMU uses 10.0.2.2).
2. threadx-linux: if you brought up tap-tx0 by hand, confirm it is up; without it the fixtures use the loopback fallback, which is fine for this tutorial (nros setup threadx-linux does not create the interface).
3. See Troubleshooting — First 10 Minutes.

Multi-tier scheduling (phase-297)

ThreadX supports the multi-tier workspace scheduling model (RFC-0053): declare per-tier ThreadX priorities in the workspace manifest with [tiers.<name>.threadx] priority tables, and nros::main! routes the app onto run_tiers — one executor per tier, all sharing one session, with per-tier stacks carved from the ThreadX byte pool. ThreadX priorities follow the native convention: lower number = higher priority. Tiers are sorted descending by raw priority number, so tiers[0] (the numerically-largest, i.e. lowest-priority tier) boots first and then adopts its declared priority. See Scheduling Models for the mechanics.

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 qemu-esp32-baremetal prepares the build: the riscv cross-gcc and espflash from a pinned index into the shared store at ~/.nros/sdk — you do not hand-install cross-compilers. Running under QEMU additionally needs Espressif’s QEMU fork (nros setup --tool esp32-qemu, source-built) and — for zenoh — a ROS 2 install to provide the router.

Time budget. This chapter is the longest embedded setup in the book (~a dozen steps, two source builds, a nightly toolchain): plan an afternoon, not ten minutes. If you have not had a first win yet, take the First Project host flow first — it is the ten-minute one — and come back.

Setup

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

./scripts/bootstrap.sh      # builds packages/cli/target/release/nros
source ./activate.sh        # OR: direnv allow / source ./activate.fish

Provision the board (and RMW):

nros setup qemu-esp32-baremetal --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) plus the riscv cross-gcc and espflash into ${NROS_HOME:-~/.nros}/sdk. It does NOT provide a zenoh router — that is ROS 2’s rmw_zenohd, so the zenoh Run step below needs a ROS install (--rmw cyclonedds needs no daemon at all). 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                 # deps + [package.metadata.nros.deploy.qemu-esp32-baremetal]
├── .cargo/                    # config.toml + nros-board.toml
│                              # (target = riscv32imc-unknown-none-elf lives in nros-board.toml)
├── package.xml
├── generated/                 # codegen output — build.rs runs
│                              #   `nros generate-rust` on first
│                              #   `cargo build`; gitignored.
└── src/                       # lib.rs component class + main.rs entry

Configure

Deploy config lives in the app’s Cargo.toml (baked at compile time; the board’s default Config supplies the remaining smoltcp knobs like the MAC). The QEMU ESP32 board uses OpenETH ethernet via nros-board-esp32-qemu. Verbatim from examples/qemu-esp32-baremetal/rust/talker/Cargo.toml:

[package.metadata.nros.deploy.qemu-esp32-baremetal]
rmw       = "zenoh"
domain_id = 0
ip        = "10.0.2.50"
gateway   = "10.0.2.2"
locator   = "tcp/10.0.2.2:9800"

Build

Contributors: the in-tree fixture/test lanes for this platform are in Per-Platform Contributor Lanes.

Copy the example out, generate bindings, build with the pinned nightly, and pack the flash image:

# once per checkout location — bindings + the [patch.crates-io] table:
NROS_REPO_DIR=<path-to-nano-ros> nros sync

# nightly because the board config builds core/alloc from source
# ([unstable] build-std in .cargo/nros-board.toml). The pinned channel
# is tools/rust-toolchain.toml's; any recent nightly with the rust-src
# component works:
#   rustup toolchain install nightly && rustup component add rust-src --toolchain nightly
#   rustup target add riscv32imc-unknown-none-elf --toolchain nightly
cargo +nightly build --release

# pack the ELF into the flash image QEMU boots (espflash comes from
# `nros setup qemu-esp32-baremetal`, on PATH via activate):
espflash save-image --chip esp32c3 --flash-size 4mb --merge \
    target/riscv32imc-unknown-none-elf/release/esp32_qemu_talker talker.bin

First build cross-compiles core/alloc + every dep (~5 min); rebuilds are seconds. If you build a C-flavored variant, the riscv cross-gcc the zpico shim needs is also provisioned by the same nros setup.

Run

The esp32c3 machine exists only in Espressif’s QEMU fork — stock qemu-system-riscv32 knows only virt. The fork is source-built by:

nros setup --tool esp32-qemu    # clones + builds espressif/qemu (needs
                                # libglib2-dev libpixman-dev libgcrypt-dev;
                                # the command names them if absent)

# 1. Bring up the router (ROS's `rmw_zenohd`) on the port the example
#    dials (9800 — the deploy `locator` above):
ZENOH_CONFIG_OVERRIDE='listen/endpoints=["tcp/127.0.0.1:9800"];scouting/multicast/enabled=false' \
    ros2 run rmw_zenoh_cpp rmw_zenohd &

# 2. Boot the flash image (the file packed in Build above):
qemu-system-riscv32 -M esp32c3 -icount 3 -nographic \
    -drive file=talker.bin,if=mtd,format=raw \
    -nic user,model=open_eth
# Serial output:
#   Publishing: 'Hello World: 1'
#   Publishing: 'Hello World: 2'

Contributors: the in-tree run lane that boots the talker in QEMU is in Per-Platform Contributor Lanes.

# 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/String --qos-reliability best_effort

Readiness signal. QEMU ESP32: ~15 seconds after boot.

If no Publishing: line:

1. Wrong locator → talker logs zenoh open failed and retries. Confirm the router is reachable on the host IP (10.0.2.2:9800).
2. Confirm .cargo/nros-board.toml sets target = "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)

Support level: nightly only. This path is exercised by the nightly full-matrix lane, never by the per-change or per-platform ones, and its coverage stops at “the image builds” — nothing boots an IDF image in CI. Treat it as a working integration shell you can build on, not as a supported starter. If you want a first ESP32 result, take the esp-hal path, which does boot under QEMU in CI.

Contributors: the lane is just esp_idf ci (doctor + build-c-port).

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:

   ./scripts/bootstrap.sh      # builds packages/cli/target/release/nros (Phase 218)
   source ./activate.sh        # OR: direnv allow / source ./activate.fish
   nros setup qemu-esp32-baremetal --rmw zenoh     # lands the toolchain
                                    # (and for xrce the Micro-XRCE-DDS
                                    # agent) in ${NROS_HOME:-~/.nros}/sdk,
                                    # AND clones the transport submodules.
                                    # The zenoh router is NOT installed —
                                    # it comes from ROS 2
                                    # (ros2 run rmw_zenoh_cpp rmw_zenohd)
                                    # (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
└── 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
    Bringup package name (demo_bringup)
    ROS domain ID        (0)
    RMW backend          (xrce)         xrce | zenoh
    ROS 2 edition        (humble)       humble | iron | jazzy

Four knobs. The default RMW is XRCE (CycloneDDS is intentionally absent on ESP — the Kconfig says so). NROS_BRINGUP_NAME drives the configure-time nros codegen-system step, so it must name a bringup package that exists in your workspace — a first build with the default demo_bringup fails if you have none. 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

Honesty note: a complete reference app (Wi-Fi + locator wiring on top of the component) is not in-tree yet — the component shell builds and boots, but you author the app glue. For a worked end-to-end flow today, start with the QEMU esp-hal chapter and come back here to embed into your IDF project.

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 (2567) nano-ros: Publishing: 'Hello World: 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/String --qos-reliability best_effort

Contributors (in-tree checkout): for the QEMU ESP32 testing path see just esp_idf test-c-port — it boots the tests/esp-idf-smoke C-port project on qemu-system-riscv32 (esp32c3 default) 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: Publishing: 'Hello World: 1' within 10 seconds — Rust + C + C++ talkers all start the count at 1, matching the official ROS 2 demo talker. If no Publishing: line:

1. Wi-Fi creds — your app’s own Kconfig (nano-ros’s submenu does not carry them; see Configure above).
2. Wrong locator — confirm the host running the router/agent 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 (xrce/zenoh). 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):
./scripts/bootstrap.sh      # builds packages/cli/target/release/nros
source ./activate.sh        # OR: direnv allow / source ./activate.fish

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

A board-named variant exists too: nros setup mps2-an385 provisions the same QEMU toolchain under a board-named key (nothing extra for physical hardware — no probe/flash tooling). For a real STM32F4 see the out-of-tree worked example.

Project layout

examples/qemu-arm-baremetal/rust/talker/
├── Cargo.toml                 # deps + [package.metadata.nros.deploy.qemu-mps2-an385]
├── .cargo/                    # config.toml + nros-board.toml
│                              # (nros-board.toml carries target = thumbv7m-none-eabi
│                              #  and the qemu-system-arm ... -kernel runner)
├── package.xml
├── generated/                 # codegen output — build.rs runs
│                              #   `nros generate-rust` on first
│                              #   `cargo build`; gitignored.
└── src/                       # lib.rs component class + main.rs entry

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

Direct-exec or RTIC — one crate, two entry shapes

The same crate serves both bare-metal entry models; you pick with a Cargo feature, not a different board crate:

The RTIC surface used to be a separate nros-board-rtic-mps2-an385 crate; phase-337 W6.a folded it in, because it depended on this crate and re-declared its Config — the two copies had drifted to different default IPs, which nothing catches until a node fails to reach the router.

Which network the defaults describe is now explicit rather than implied. Config::default() is the bridge plan (192.0.3.10/24, gateway 192.0.3.1); Config::qemu_slirp() is QEMU’s user-mode NAT (10.0.2.10/24, gateway 10.0.2.2) and is what the RTIC entry boots from. Either way, an Entry pkg that sets ip/gateway/locator in its [package.metadata.nros.deploy.<board>] block overrides the default — which every in-tree example does, and which you should too.

Configure

Deploy config lives in the app’s Cargo.toml and is baked at compile time — nros::main!() folds it into a DeployOverlay the board’s boot Config applies. Verbatim from the in-tree examples/qemu-arm-baremetal/rust/talker/Cargo.toml:

[package.metadata.nros.deploy.qemu-mps2-an385]
locator = "tcp/10.0.2.2:10500"
ip      = "10.0.2.10"
gateway = "10.0.2.2"
netmask = "255.255.255.0"

QEMU Slirp networking — no host TAP / bridge / sudo. The zenoh default port is 7447; this example dials 10500 (the locator above), so start the router (ROS’s rmw_zenohd) on that port:

ZENOH_CONFIG_OVERRIDE='listen/endpoints=["tcp/127.0.0.1:10500"];scouting/multicast/enabled=false' \
    ros2 run rmw_zenoh_cpp rmw_zenohd

or edit the locator above to the port you prefer.

Build

cd examples/qemu-arm-baremetal/rust/talker
nros sync            # once per checkout location; writes the generated
                     # bindings + the [patch.crates-io] table the leaf's
                     # .cargo/config.toml includes
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.

Contributors (in-tree checkout): the just … build-fixtures recipes run nros sync for you. A hand-run cargo build in a leaf does not — without it cargo fails while parsing the manifest, with failed to load config include '…/nros-patch.toml' and no mention of sync. See Workflow by Platform and Language.

Run

# 1. Bring up the router on the host (Slirp forwards 10.0.2.2:10500 →
#    host 127.0.0.1:10500). This example dials 10500, NOT zenoh's
#    default 7447 — edit the deploy `locator` in Cargo.toml if you
#    want 7447:
ZENOH_CONFIG_OVERRIDE='listen/endpoints=["tcp/127.0.0.1:10500"];scouting/multicast/enabled=false' \
    ros2 run rmw_zenoh_cpp rmw_zenohd &

# 2. Boot the talker in QEMU. Invoke qemu-system-arm directly with the
#    LAN9118 networking wiring the example expects (a plain `cargo run`
#    boots QEMU without networking — the example's runner is bare
#    `-kernel`). The patched qemu-system-arm is provisioned by
#    `nros setup qemu-arm-baremetal` and reaches PATH via activate.sh:
qemu-system-arm -cpu cortex-m3 -machine mps2-an385 -nographic \
    -icount shift=auto \
    -semihosting-config enable=on,target=native \
    -kernel target/thumbv7m-none-eabi/release/qemu-bsp-talker \
    -nic user,model=lan9118
# Expected serial-over-semihosting output (per src/lib.rs):
#   Publishing: 'Hello World: 1'
#   Publishing: 'Hello World: 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/String --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 Publishing: 'Hello World: 1' on semihosting stdout — the count starts at 1, matching the official ROS 2 demo talker. If no Publishing: line:

1. Router not running — talker spins on smoltcp poll until killed.
2. Wrong LAN9118 emulation flag — qemu-system-arm needs -nic user,model=lan9118 (or equivalent). The example’s .cargo/config.toml runner is bare -kernel (so a plain cargo run boots QEMU without networking); the direct qemu-system-arm invocation shown above carries the LAN9118 wiring and 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: the same code runs on an STM32F4-Discovery with a board crate of your own and a different linker script — see Worked Example — STM32F4 Out of Tree, which takes that board through the customization ladder end to end.

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. Provision the source trees first to populate third-party/px4/PX4-Autopilot and third-party/px4/px4-rs, then initialize PX4’s own submodules.

nros setup --source px4-autopilot --source px4-rs
git -C third-party/px4/PX4-Autopilot submodule update --init \
    --depth 1 --recommend-shallow --recursive

PX4’s own Python dependencies come from its Tools/setup scripts (e.g. PX4-Autopilot/Tools/setup/ubuntu.sh) — run those per PX4’s documentation if the firmware build complains about missing Python modules.

Contributors (in-tree checkout): just px4 doctor reports the provisioning gap on a fresh clone.

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: packages/testing/nros-px4-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.

PX4 (integration shell)

Contributor docs? Building nano-ros’s PX4 example from this repository is covered at PX4 (contributor).

nano-ros lifts the PX4 EXTERNAL_MODULES_LOCATION pattern into a generic copy-out template under integrations/px4/module-template/. Downstream PX4 apps vendor the template, customise it, and point EXTERNAL_MODULES_LOCATION at their copy.

Prereqs

• PX4-Autopilot checkout (git clone https://github.com/PX4/PX4-Autopilot)
• The full PX4 SITL build toolchain (make px4_sitl_default works standalone)

Contributors (in-tree checkout): for nano-ros’s in-repo PX4 checks:

just setup px4              # `_setup-common` + the px4 module recipe
just px4 doctor

One-liner vendor

cp -r /path/to/nano-ros/integrations/px4/module-template \
      ./my-px4-modules

Layout (PX4 enforces this exactly)

my-px4-modules/
└── src/
    ├── CMakeLists.txt                       (lists module names)
    └── modules/
        └── nano_ros_app/
            ├── CMakeLists.txt               (px4_add_module)
            └── nano_ros_app.cpp             (module body)

Rename nano_ros_app consistently in all three places when adapting for your own module.

Build

export EXTERNAL_MODULES_LOCATION=$PWD/my-px4-modules
export NANO_ROS_DIR=/path/to/nano-ros
make -C $PX4_AUTOPILOT_DIR px4_sitl_default

PX4’s build picks up the module via <location>/src/CMakeLists.txt. The module CMakeLists pulls in nano-ros C++ headers via $NANO_ROS_DIR.

Reference

The validated end-to-end SITL pattern (with the Rust-side nros-rmw-cffi_register weak-stub trick) lives at packages/testing/nros-px4-register-check/. Use that as the source of truth for the register-check shape; this template is the generic shell for downstreams writing their own modules.

Registry note

PX4 has no central module registry. Downstreams vendor the template via git submodule or cp -r. See Registry Publishing for the cross-ecosystem comparison.

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.

Status. The run half — invoking FVP_BaseR_AEMv8R and piping UART 0–3 to stdout — is landed.

The two standalone talker lanes were retired (issue 0537): their runners had been deleted, so they built images nothing booted. What remains is the part with consumers — the board-crate import surface and the workspace Entry. FVP support is intended to grow back from those. 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 stock-Cyclone-DDS 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

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

The FVP is a license-gated tool: nano-ros checks that it resolves via ARMFVP_BIN_PATH, ARM_FVP_DIR, PATH, or the canonical ~/.nros/sdks/arm-fvp/current/FVP_BaseR_AEMv8R landing path (the [gated.arm-fvp] entry in nros-sdk-index.toml), and warns — never hard-fails — when it can’t.

Contributors: the in-tree doctor cross-check and FVP run recipes are in Per-Platform Contributor Lanes.

Build

Contributors: the in-tree FVP build lanes (and the zephyr.elf paths they produce) are in Per-Platform Contributor Lanes.

Two standalone talker lanes (build-fvp-aemv8r-cyclonedds{,-rust}, over examples/zephyr/{cpp,rust}/talker-aemv8r) used to live here. Their tests were deleted and the lanes later retired, so the chapter no longer documents a lane whose output nobody consumes.

Run

Once the build artifacts and ARM_FVP_DIR / ARMFVP_BIN_PATH are in place:

Contributors: the in-tree FVP run lanes (and what they do under the hood) are in Per-Platform Contributor Lanes.

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)
Publishing: 'Hello World: 1'
Publishing: 'Hello World: 2'
...

For the cpp/cyclonedds recipe, the same banner is followed by Cyclone DDS reader-match logs and std_msgs/String 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/String

The same std_msgs/String payload (Hello World: N) + byte-equal CDR framing must appear on both sides — that’s the stock-RMW interop contract (byte-compatible with rmw_cyclonedds_cpp).

Cross-references

• docs/roadmap/phase-217-arm-fvp-local-runtime.md — the roadmap doc for the FVP runtime slice (contributor detail on what has landed vs what is ongoing).
• docs/roadmap/archived/phase-117-cyclonedds-rmw.md — the Zephyr FVP build smoke + Cyclone DDS port 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/workspaces/realtime-cpp/src/fvp_entry/ — the workspace Entry this chapter builds and boots.

Native (Host) Build

Use the native (host) 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.

native is a role — the host build rather than a cross build — not a reach claim. The reach is linux: the platform layer (nros-platform-posix) is POSIX-clean, but the host board crate’s apply_tier_affinity calls sched_setaffinity with cpu_set_t, which libc does not define for macOS, and only Linux is tested in CI. macOS is not supported (AGENTS.md, phase-260); *BSD is a supported path that no lane exercises.

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 the client stack (and for xrce the Micro-XRCE-DDS agent) into a shared store. The zenoh router is NOT installed: it comes from a ROS 2 install (ros2 run rmw_zenoh_cpp rmw_zenohd, RFC-0075). No ROS 2 on this machine? Use --rmw cyclonedds — it needs no daemon.

# Build the in-tree nros CLI:
./scripts/bootstrap.sh      # builds packages/cli/target/release/nros
source ./activate.sh        # OR: direnv allow / source ./activate.fish

# Provision the native host (zenoh RMW is the default):
nros setup native --rmw zenoh        # or: --rmw xrce / --rmw cyclonedds

native and linux are the two names of this board (native the role, linux the reach); posix names the platform layer underneath it, not the board.

For a colcon consumer workspace that already has nano-ros under src/:

colcon build && source install/setup.bash

Package Layout

For a host application package:

my_native_node/
├── package.xml
├── Cargo.toml          # Rust path
├── CMakeLists.txt      # C / C++ path
└── src/
    └── main.rs         # or main.c / main.cpp

Examples are copy-out ready: for Rust, cp -r the example, run NROS_REPO_DIR=<nano-ros checkout> nros sync, and cargo build; for C/C++, cp -r and configure with -DNANO_ROS_ROOT=<nano-ros checkout> (or export NROS_REPO_DIR) — the example CMakeLists.txt resolves the checkout via its NANO_ROS_ROOT guard.

Code Example

Rust publisher skeleton:

use core::fmt::Write as _;
use nros::prelude::*;
use std_msgs::msg::String as StringMsg;

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::<StringMsg>("/chatter")?;

    let mut count = 0i32;
    loop {
        count += 1;
        let mut msg = StringMsg::default();
        let _ = write!(msg.data, "Hello World: {count}");
        publisher.publish(&msg)?;
        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:

ZENOH_CONFIG_OVERRIDE='listen/endpoints=["tcp/127.0.0.1:7447"];scouting/multicast/enabled=false' ros2 run rmw_zenoh_cpp rmw_zenohd

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

Host 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.

Workflow by Platform and Language

You have a target and a language. This page is the sequence of commands that pair implies, and the one step whose absence is the most common first failure.

The rest of the book is organized by where you are going — a starter page per platform. This page is organized by what you type, because the commands vary along a different axis than the pages do: the builder follows from your language, and the toolchain follows from your platform. Neither table below is a summary of the other.

The step that is easy to miss

Rust leaves need nros sync before their first build. C and C++ leaves do not.

A Rust leaf resolves its nano-ros dependencies through a [patch.crates-io] table in its own .cargo/config.toml, and that table is generated — .gitignore excludes it, so a fresh clone does not have it. Sixty-seven Rust example leaves have such a file on a synced checkout; fifty of them are committed shells that include the generated central table:

include = [ "../../../../../nros-patch.toml", "nros-board.toml"]

Skipping the sync fails in two different ways, and the quieter one is worse. Where the config is committed, cargo treats the missing include as a hard error while parsing the manifest — before it builds anything, and before any message about nano-ros could appear:

error: failed to parse manifest at `<leaf>/Cargo.toml`

Caused by:
  could not load Cargo configuration

Caused by:
  failed to load config include `../../../../../nros-patch.toml` from `<leaf>/.cargo/config.toml`

Caused by:
  failed to read configuration file `<...>/nros-patch.toml`

Caused by:
  No such file or directory (os error 2)

Nothing in those five frames says nros sync. If you see it, this is what it means.

Where the whole config is generated — the native leaves, for instance — there is no file at all in a fresh clone, so there is no error to read. The patch table simply is not there, and the nano-ros crates your leaf names go looking for themselves on crates.io instead of in your checkout. That one does not announce itself.

Contributors (in-tree checkout): the just recipes — just <module> build-fixtures and friends — run nros sync for you, so they work from a fresh clone. It is the hand-run cd <leaf> && cargo build that needs you to run it yourself.

C and C++ leaves have no .cargo/config.toml at all — not committed, not generated. Their message bindings are produced inside CMake by nros_find_interfaces(), and the cargo builds CMake drives resolve against the repo-root config, which carries no include. Running nros sync for a C/C++ build is harmless but buys nothing.

You need it once per checkout location, not once per build. Re-run it after editing a .msg, .srv, or .action file, and — because the central table it writes holds absolute paths — after moving the checkout, or after one of the patched crates moves within it.

Which builder your cell uses

Each cell is the builder that nano-ros’s own CI uses for that pair, read from examples/fixtures.toml — the manifest the fixture builds and the staleness probe both consume. A dash means the pair has no in-tree coverage today, not that it is forbidden.

The row names are the manifest’s, which are shorter than the ones you type: freertos here is the platform whose board is qemu-arm-freertos and whose examples live in examples/qemu-arm-freertos/. The per-platform table further down maps all three spellings.

Where a row lists two builders, both are real and they build different things: on Zephyr, west builds the single-node examples under examples/zephyr/<lang>/, and cargo/cmake build the workspace examples under examples/workspaces/.

The three command shapes

Every cell above is one of these three, plus platform-specific flags that live on the platform’s own starter page.

cargo — Rust, every platform

./scripts/bootstrap.sh          # builds the in-tree nros CLI
source ./activate.sh            # OR: direnv allow / source ./activate.fish
nros setup <board> --rmw zenoh  # toolchain + SDK for the target

cd <leaf>
nros sync                       # ← the step above; once per checkout
cargo build --release

Some leaves also pin their cross target in that same .cargo/config.toml ([build] target = "thumbv7m-none-eabi" on the Cortex-M ones), so no --target on the command line. Others get it from the platform’s recipe instead — contributors: in an in-tree checkout, just --list <module> shows which recipe builds what, and using the recipe avoids having to know.

cmake — C and C++

./scripts/bootstrap.sh
source ./activate.sh
nros setup <board> --rmw zenoh

cd <leaf>
cmake -B build -DCMAKE_TOOLCHAIN_FILE=<toolchain> -DCMAKE_BUILD_TYPE=Release
cmake --build build --parallel

No nros sync. The toolchain file is per platform — see the starter page. -D_NANO_ROS_CODEGEN_TOOL= is not needed when nros is on PATH; CMake resolves it.

west — Zephyr single-node examples

Zephyr owns the build. See Zephyr (west module) for the module wiring; the Rust leaves under examples/zephyr/rust/ still need nros sync first, because west drives cargo and cargo reads the leaf config either way.

In the checkout, or copied out?

The commands above are written as cd <leaf> inside the nano-ros checkout, which is the fastest way to see something run. For anything beyond that, copy the example directory out — examples are standalone copy-out projects with no workspace walk-up, so a copied one builds on its own.

The distinction matters for one reason: a bare cargo build writes target/ next to the leaf. In your project that is exactly right. In the nano-ros checkout it is residue the repo’s own gate rejects (check-example-leaf-target-dirs) — in-tree builds are expected to go through the contributor recipes (just <module> …), which write into a shared build directory instead. One in-repo cargo build --release of a Cortex-M example leaves 269 MB behind.

So: exploring in the checkout, prefer the recipe. Building your own thing, copy the example out and cargo build normally.

Per platform

Multi-node workspace examples do not follow that directory rule: they all live under examples/workspaces/, selected by fixture row rather than by directory. That is why ESP32 has two grid rows — qemu-esp32-baremetal for its single-node examples and esp32 for its share of the workspace ones. Zephyr’s two rows split differently: zephyr and zephyr-cortex-m build the SAME examples for different boards.

Contributors (in-tree checkout): each module’s recipes are discoverable rather than memorized:

just --list freertos          # every FreeRTOS recipe, grouped
just --list zephyr

More than one node

The sequence above builds one leaf. A project with several nodes adds a Bringup package and an Entry package on top of it, and the build is still one of the three shapes above — see Project layout.

If it does not work

• Troubleshooting — First 10 Minutes
• Troubleshooting

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 provides most components prebuilt per platform per RMW; a few without a seeded asset (the vendored submodules — zenoh-pico, mbedtls, RTOS sources) are built from source. nros setup <board> --rmw <rmw> --dry-run shows which is which on your host — see Installation.

It does not provide a zenoh router: that is ROS’s rmw_zenohd, so a multi-process zenoh example needs a ROS 2 install (or NROS_RMW_ZENOHD). --rmw cyclonedds needs no daemon at all.

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 — deps + [package.metadata.nros.*]
│       ├── CMakeLists.txt         # C/C++ — targets (deploy tuple in package.xml)
│       └── 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 (one of five codegen entry points — which to use).
• 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 / cyclonedds. Not every cell is implemented — see the Coverage Matrix.

Runtime configuration (ROS_DOMAIN_ID, NROS_LOCATOR, …) works on POSIX. Embedded targets bake config from [package.metadata.nros.deploy.<t>] (Rust) / the package.xml <nano_ros deploy=…/> tuple (C/C++), plus Kconfig on Zephyr. See Configuration.

5. Build, Test, Deploy

For each canonical entry point:

# Single Rust example — `nros sync` first, once per checkout location:
cd examples/native/rust/talker
nros sync
cargo run

# Single C/C++ example (CMake + add_subdirectory) — no sync needed:
cd examples/qemu-arm-freertos/cpp/talker
cmake -B build -DCMAKE_TOOLCHAIN_FILE=$PWD/../../../../../cmake/toolchain/arm-freertos-armcm3.cmake
cmake --build build

# Contributors: per-platform multi-example fixture build, in-tree
# checkout only (these run `nros sync` for you):
just freertos build-fixtures
just zephyr  build-fixtures
just nuttx   build-fixtures

# Contributors: discover full-matrix commands for a platform:
just --group full-matrix --list zephyr

# Multi-node system — sync, bake the bringup, build the entry:
nros sync
nros codegen-system --bringup <bringup-pkg> --out <out-dir>
cargo build -p <entry>      # or: cmake --build <dir> --target <entry>

# POSIX-only colcon consumer-workspace build:
colcon build && source install/setup.bash

Which of the three build shapes your target uses, and which need the sync step, is Workflow by Platform and Language.

nros codegen-system resolves the bringup’s system.toml (plus its launch files) into a SystemModel under the workspace build tree. SystemModels are build artifacts — never committed, and never named by an entry package; an entry names its input (nros::main!(launch = "bringup"), nano_ros_entry(BRINGUP … LAUNCH …)) and the build locates the artifact. nros model-path prints where a resolved one landed.

nros metadata / nros plan / nros check are the inspection path, not the build path: they produce and validate an nros-plan.json you can read with nros explain. You do not need them to build.

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 one of the two ways to integrate nano-ros into a C or C++ project, and the lower-level one: the repo’s top-level CMakeLists.txt exposes everything via add_subdirectory(...). The higher-level, ament-shaped alternative is find_package(nano_ros REQUIRED) — nano_rosConfig.cmake at the checkout root, located via nano_ros_ROOT (RFC-0048) — which every in-tree example now uses. Either way there is NO install step: phase-140 removed the install prefix and the old find_package(NanoRos) (capital) config pipeline. Vendoring the repo into a company tree (pinning, offline CI, upgrade workflow) has its own page: Integrating into a Vendored Tree.

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 | xrce | cyclonedds

add_subdirectory(third_party/nano-ros nano_ros)

add_executable(my_app main.c)
target_link_libraries(my_app PRIVATE NanoRos::NanoRos)
if(COMMAND nros_platform_link_app)   # defined by zephyr/threadx platforms only
    nros_platform_link_app(my_app)
endif()

# Optional — generate C bindings for ROS 2 .msg / .srv / .action files.
# (LANGUAGE defaults to CPP; full spelling table → user-guide
# "Message Generation".)
nano_ros_generate_interfaces(std_msgs LANGUAGE C
    DEPENDENCIES builtin_interfaces)
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?

Phase-140 deleted every nano-ros-side 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: it resolves the nano-ros checkout root once (-DNANO_ROS_ROOT cache var → NROS_REPO_DIR env var → in-repo walk-up), includes the workspace helpers, generates the message bindings (nros_find_interfaces), and declares the app via nano_ros_entry(...) — ~55 lines including codegen + per-app fixup. All in-tree C/C++ examples follow the same shape.

Integrating nano-ros into a Vendored Tree

This page is for the engineer whose company has its own source tree — a BSP, possibly a forked RTOS, an existing build system — and needs nano-ros to live inside it: pinned, reproducible, buildable offline, upgradable on their schedule. It collects the contracts the other chapters mention in passing into one place.

nano-ros is source-only: nothing is on crates.io, there is no install prefix, and no binary distribution. Vendoring the repository is not a workaround — it is the supported consumption model.

Pinning the checkout

Vendor the repo as a git submodule (or subtree) and pin a release tag:

git submodule add https://github.com/NEWSLabNTU/nano-ros.git third_party/nano-ros
git -C third_party/nano-ros checkout nros-v0.5.0
git add third_party/nano-ros

Rules that keep the pin trustworthy:

• Pin tags (nros-v<X.Y.Z>), not main. A moving branch unships the pairing you tested.
• Move the pin forward only. A rewind silently drops whatever the skipped commits fixed, and two hex strings in a diff cannot be ordered by eye.
• nano-ros’s own submodules are decisions, not lags. The Cyclone DDS fork tracks the Cyclone that ROS ships; zenoh-pico is pinned at a wire-stable version. Never “update to latest” inside the vendored checkout — take what the tag pinned.

Initialize nano-ros’s submodules non-recursively — the launch toolchain’s third-level runtime submodules are never built by nano-ros:

git -C third_party/nano-ros submodule update --init packages/cli/third-party/play_launch

For build-related submodules you normally do nothing: the configure step populates the ones your (platform, RMW) pair needs (see Bootstrap below), or you pre-seed them explicitly for offline builds.

What a fresh vendored checkout needs, in order

Four things, and the order matters:

1. The nros CLI. ./scripts/bootstrap.sh inside the checkout builds packages/cli/target/release/nros. Nothing else works without it.
2. An activated environment for interactive use: source third_party/nano-ros/activate.sh wires nros and the SDK-store tools onto PATH and exports nano_ros_ROOT. CI can skip this and pass paths explicitly (-Dnano_ros_ROOT=…, absolute CLI path).
3. Provisioned toolchains. nros setup <board> --rmw <rmw> fetches the cross-compiler, emulator, and SDK sources for exactly that pair into the shared store at ${NROS_HOME:-~/.nros}/sdk. --dry-run prints the plan first. (The zenoh router is deliberately not provisioned — it comes from a ROS 2 install, ros2 run rmw_zenoh_cpp rmw_zenohd.)
4. Message codegen. NROS_REPO_DIR=<checkout> nros sync from your workspace root — see the next section for why this is not optional.

The Rust side: nros sync is mandatory, and your config is inline

Two things in every Rust leaf are gitignored and generated: the generated/ message crates and the cargo patch machinery that resolves registry-style names (nros = { version = "*" }) to the vendored sources. A fresh clone cannot build a Rust package until nros sync has run — the failure otherwise is cargo dying during manifest parse with an error that never names sync.

For an out-of-tree consumer (your workspace, outside the nano-ros checkout), nros sync writes the [patch.crates-io] table inline into your leaf’s .cargo/config.toml, with absolute paths, and no include line. This is deliberate:

• The in-repo examples use a relative include = ["…/nros-patch.toml"] pointing at a central gitignored file. That shape has three fragile preconditions (cargo ≥ 1.93, a correct relative path, the central file existing) and its failure modes are confusing. Outside the checkout you get the whole table inline, so the only failure mode is loud.
• Never copy an in-repo example’s .cargo/config.toml into your tree. You would be copying the relative include line, which cannot resolve from your directory. Copy the package and run nros sync — it writes the correct config for that location.
• A moved checkout invalidates the absolute paths — re-run nros sync after relocating either the workspace or the vendored nano-ros.

Message dependencies stay path deps pinned 0.0.0 (std_msgs = { path = "generated/std_msgs" } after sync); never registry-name a message crate — a bare std_msgs = "*" can resolve against the public crates.io.

The CMake side

Two entry points, both source-backed:

• find_package(nano_ros REQUIRED) — the ament-shaped entry (nano_rosConfig.cmake at the checkout root). Located via nano_ros_ROOT, which activate.sh exports; CI passes -Dnano_ros_ROOT=<checkout> explicitly.
• add_subdirectory(third_party/nano-ros) — the lower-level shape. See Build as a CMake subdirectory for the cache-variable table.

Either way, at configure time nano-ros’s bootstrap.cmake runs tools/setup.sh to populate the source submodules your (NANO_ROS_PLATFORM, NANO_ROS_RMW) pair needs, and may FetchContent Corrosion from the network if none is installed. That is correct on a developer machine and wrong in hermetic CI — see the next section.

Air-gapped / mirrored CI

The offline contract, all of it:

1. -DNANO_ROS_SKIP_BOOTSTRAP=ON. Disables the configure-time submodule fetch and any network FetchContent. You now own pre-seeding.
2. Pre-seed the submodules your platform/RMW pair needs in your mirror (e.g. zpico-sys/zenoh-pico, the FreeRTOS kernel + lwIP, the Cyclone fork — tools/setup.sh derives the per-target list from nros-sdk-index.toml, which is the single manifest of what comes from where).
3. Pre-install Corrosion: nros setup --tool corrosion stages it into the SDK store, where the configure finds it without the network. Verify the configure line prints nano-ros: Corrosion <ver> via <origin> — never infer the version from having run an installer; a stale store entry can shadow a fresh one.
4. Cache the SDK store. Everything nros setup fetches lands under ${NROS_HOME:-~/.nros}/sdk; point NROS_HOME at a shared or cached location and the store is reusable across jobs and machines of the same host triple.
5. Mirror the asset sources. nros-sdk-index.toml names every asset’s upstream ([tool.*], [source.*] sections). For a full mirror, rehost those URLs and patch the index in your vendored checkout — that patch is part of the carried diff below, and the index is versioned with the tree so the patch rebases cleanly.

The patch set you carry

Be clear-eyed: some extensions live inside the vendored checkout. There is no out-of-tree escape hatch for them today, so a vendored tree carries a small local diff and rebases it across tag bumps: