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 hosts. 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(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 one line of configuration, the board = in the image’s system.toml, not the code you write. Everything that choice implies — the triple, the linker flags, the backend, the pool sizes — is generated from it, so the build files stay free of target facts too. 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 gone (phase-468 W2) — integrations/nano-ros/ and nros-platform-esp-idf were deleted, and esp_idf is no longer an accepted NROS_PLATFORM value. This row said “Ready” and “nightly lane” until 2026-09-25, when it was measured: no workflow under .github/ ran its module, and examples/fixtures.toml had no row naming it. The claim sat two sentences after this table’s own warning that “keeping a row that says ‘Verified’ for a board nothing verifies is the failure mode the tier registry exists to prevent” — the same mistake, one status word over, and measuring it is what retired the path. The row stays as a Retired marker so the next reader does not re-add it from the old claim. The esp-hal row above it is the ESP32 path with a booting CI lane, and is unaffected: esp-idf and esp32 are different platforms. Detail: ESP32 (ESP-IDF component) — retired.

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 naming one in system.toml:

• 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 — switching is editing [system] rmw and re-running nros sync. (Zephyr keeps Kconfig as its own front-end, as it does for every other build knob.)

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 — what builds unchanged, 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 linux --rmw cyclonedds, one scaffold command, then nros sync and nros build.
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 linux --rmw cyclonedds. Those set up the machine; the per-project step comes next.
2. First Project — one scaffolded workspace, then nros sync and nros build, publishing with nothing else running. Rust variant on the same page: same two commands, same system.toml, only the node bodies differ.
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

The library 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 and no find_package(NanoRos).

The nros CLI is a separate question with a separate answer, and which one you want depends on who you are:

That is not a preference. Inside a nano-ros checkout the tree’s own build is the only correct binary: a released nros run against a checkout is refused outright, because it emits its own generated code and this tree’s runtime is the one that has to compile it (RFC-0090).

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

(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 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 or pacman — 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 here. These four steps are the contributor flow — they start by cloning the repository, so step 2 is the checkout’s own build, which is the only binary that may be used against it.

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 needed one question to have 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, and every arm of it refuses at compile time.

No release has been cut yet. The machinery is in place (scripts/install.sh and a manual release workflow), and cutting one is a deliberate act rather than a consequence of a version bump — so until the first one exists, building from the checkout is how everyone gets nros. install.sh says so itself if you run it early, and points you back here.

# 1. Pull the source at a pinned version (or `main` for latest):
git clone --branch nros-v0.6.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 scaffold a project and build it: nros new, then nros sync and nros build — First Project walks it end to end. Your project says what it deploys to with a board name in its system.toml; it does not name a path, a triple or a backend crate in any build file. Consuming nano-ros below has the shape, and Pinning a version 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.

build-as-subdirectory.md is the lower-level CMake escape hatch, for a C/C++ tree that is not a nano-ros workspace. 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.

Consuming nano-ros

Pattern A: your project is a nano-ros workspace

This is the supported shape, in any language. A workspace is a directory of packages — node packages plus one bringup package — and it has no root build file at all, neither CMakeLists.txt nor Cargo.toml (RFC-0098 D9):

~/my_robot/
├── .colcon_workspace          # marks the root
└── src/
    ├── pkg_a/                 # your node package(s)
    ├── pkg_b/
    └── my_robot_bringup/      # system.toml + launch files, no code

The bringup’s system.toml names the board once per deploy target:

[system]
name = "my_robot"
rmw  = "cyclonedds"

[image.linux]
board = "linux"

nros sync resolves the launch files and generates what the board choice implies; nros build generates the entry and the build root for each [image.*] under build/, then hands off to CMake, cargo, west or idf.py:

nros sync
nros build                     # or: nros build linux

nros new my_robot --workspace scaffolds exactly that layout — see First Project. A POSIX C++ workspace that already uses colcon can still be built by colcon build; the packages keep their package.xml and their own CMakeLists.txt.

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

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

For a C/C++ project that is not a nano-ros workspace — an existing CMake tree with its own layout, that wants nano-ros as a subdirectory and nothing else:

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

There the platform and backend are cache variables set before add_subdirectory(), because there is no system.toml for the build to read them from. That is the lower-level shape and it has its own page, with the full variable table: Build as a CMake subdirectory. Reach for it when Pattern A does not fit your tree, not before.

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

If you only want to use nano-ros, install a release — no checkout, no cargo, no just:

curl -fsSL https://raw.githubusercontent.com/NEWSLabNTU/nano-ros/main/scripts/install.sh | sh
export PATH="$HOME/.nros/bin:$PATH"   # install.sh prints this line too

It verifies the download’s sha256 (and refuses an asset it cannot verify), installs into ~/.nros/sdk/nros/<version>/ and points ~/.nros/bin/nros at the newest version installed — so however many versions accumulate, nros means one command. Put ~/.nros/bin on your PATH. Until the first release is cut it will tell you so and send you to the source build below.

If you are working on nano-ros itself, build the CLI from the checkout — that binary is the only one this tree accepts. 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, THREADX_DIR, …) not being loaded. Harmless — nothing in the user flows reads them, and embedded builds go through nros sync + nros build, which drives cargo, cmake, west or idf.py for you. 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). It exports no checkout root: the in-tree nros knows the checkout it was built in.

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. For every board with a CMake build road (all of them except Zephyr, which builds with west) it also installs the pinned Corrosion, the CMake-to-cargo bridge a C/C++ configure needs: a configure never fetches it, and without it in the SDK store the configure stops and names this command.

Every board also needs a Rust toolchain, whatever language you write: the runtime your project links is compiled from source when you first configure. If the host has neither rustup nor rustc + cargo, nros setup installs rustup (a pinned, checksum-verified installer) into ~/.cargo with the stable toolchain as the default — where cmake finds it without any PATH change. A host that already has Rust is left as it is. For cargo in a shell afterwards: . "$HOME/.cargo/env".

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 resolve the names into the SDK root (the checkout the project sits in, else the nros binary’s own; --nano-ros-path names one). The [patch.crates-io] block it writes goes into the generated settings file under build/, not into your package — nros build hands that file to cargo with --config, and a cargo command you drive yourself passes the same path. 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"] }

A Rust package carries no build settings of its own — no target triple, no linker flag, no patch table. It states its board in system.toml and nros sync derives the rest (RFC-0098); see examples/templates/multi-package-workspace/src/pkg_rust_publisher/ for a package in that shape, and Integrating into a Vendored Tree for the CI spelling.

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.6.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.6.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 mps2-an385-freertos
just setup nuttx              # → nros setup qemu-armv7a-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 linux --rmw cyclonedds run once).

Scaffold

nros new my_robot --workspace
cd my_robot

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

my_robot/
├── .colcon_workspace           # marks the workspace root; there is no root build file
└── 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

There is no entry package and no root CMakeLists.txt: the binary is generated from the bringup’s system.toml when you build. What each directory is for is the next chapter, Anatomy of What You Just Built. You don’t need it to run.

Build

nros sync
nros build

nros sync resolves the launch file into the system model; nros build generates the entry for each [image.*] in system.toml and drives CMake under build/. The first build compiles nano-ros’s runtime into the build tree (~3 minutes); rebuilds are seconds. Inside a nano-ros checkout that checkout is used; anywhere else nros uses its own SDK (a release’s share/nano-ros, or the checkout an in-tree nros was built in), and --nano-ros-path <dir> names one explicitly. Nothing is exported. nros sdk-root --explain prints the root it would use and where that came from.

Run

./build/posix-cyclonedds-linux/cmake/linux_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 sync
nros build
RUST_LOG=info ./build/posix-cyclonedds/linux_entry/target/debug/linux_entry

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

(The Rust talker ticks at 1 s.)

Known issue (1295). On CycloneDDS — the scaffold’s default RMW — the generated Rust entry currently stops at startup with NodeError::Transport(PublisherCreationFailed). The C++ path above is not affected.

Same workspace shape, same system.toml, same launch file, same two commands — only the node implementations and the driver nros build picks (cargo instead of CMake) differ. Neither workspace has a root build file: the entry is generated per image under build/.

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/posix-cyclonedds-linux/cmake/linux_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(rclcpp::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          # create_wall_timer<C,&C::m> → 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.linux]                       # one block per BUILDABLE image
board = "linux"

[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.depth" value="5"/>
</node>

An override changes how the two ends MATCH as well as how one end behaves. Setting the publisher to reliability = best_effort here would look harmless and deliver nothing on CycloneDDS: DDS never pairs a best-effort writer with a reliable reader, and the listener’s subscription is reliable by default. (ros2 topic echo --qos-reliability best_effort is the same rule seen from the other side.)

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

The entry — the deliverable, and it is generated

There is no entry directory under src/. nros build reads each [image.<id>] in system.toml and generates its entry under build/ (for the scaffold’s [image.linux], the binary is build/posix-cyclonedds-linux/cmake/linux_entry). That entry resolves the bringup’s launch file and has 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 binary per deployable image — and image is a row, not a directory. A robot with a perception image and a control image is one workspace, one bringup, and two [image.*] blocks in its system.toml; nros build derives each entry from (launch, args, board) and generates it under build/. Everything a hand-written entry used to carry — its board, its RMW locator — is a key in that block. See Images.

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 · Images

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 own rclcpp CMake package.
• 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:
    rclcpp::TimerBase::SharedPtr timer_;
    rclcpp::Publisher<my_msgs::msg::MyMsg>::SharedPtr 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(NROS_PLATFORM posix)
set(NROS_RMW "zenoh" CACHE STRING "Active RMW.")
set(NROS_RMW "${NROS_RMW}")
add_subdirectory(/path/to/nano-ros nano_ros)

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

# nano-ros's ament / rclcpp surface (find_package(rclcpp), ament_* verbs).
include(/path/to/nano-ros/cmake/NanoRosAmentSurface.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 message-package resolver (cmake/find/_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 linux --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. You built before nros sync

… has not been synced — missing the resolved model under `build/nros/models/`,
the generated message crate `std_msgs` (generated/std_msgs).
  Run `nros sync` in … (RFC-0098 D2), then build again.

The example’s Cargo.toml declares nano-ros crates registry-style (nros = { version = "*" } — they are not published to crates.io); the [patch.crates-io] block that resolves them into a nano-ros checkout is GENERATED, into build/<image>/nros-cargo.toml, which nros build hands cargo with --config (RFC-0098 D1). This error means that file has not been written yet, or its relative paths no longer reach a checkout (typical right after copying the example somewhere else). Fix:

cd <the example dir>
nros sync        # or: nros sync --nano-ros-path /path/to/nano-ros

Driving cargo directly skips that refusal and gets cargo’s own version of it instead — no matching package named 'nros' found, or an unresolved import. Same cause, same fix: sync, then pass the generated file with --config. nros sync is what ties a copied-out example to an SDK (the nros binary’s own, or the one --nano-ros-path names), so re-run it after moving the directory.

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

The triple is the board’s, not the example’s — you will not find it in any file you wrote. Read it back from the [build] target line of the generated build/<image-id>/nros-cargo.toml, which nros sync writes from the board your system.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 mps2-an385-freertos       # or qemu-armv7a-nuttx / mps2-an385-baremetal / …

A5. Cyclone DDS runtime missing

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

The Cyclone DDS runtime wasn’t provisioned:

nros setup linux --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_named from a CMake-built target — wired through CMakeLists.txt + Corrosion. Use the cmake build path instead, and choose the backend where backends are chosen: [system] rmw in the leaf’s system.toml.

[system]
rmw = "cyclonedds"

cd examples/linux/c/talker        # (or cpp)
cmake -B build-cyclone -Dnano_ros_ROOT="$(nros sdk-root)"
cmake --build build-cyclone

A single-package C / C++ leaf needs no nros sync — its message bindings are a CMake-time output. There is no -DNROS_RMW= to pass: a backend selected on the command line disagrees with the one the rest of the build resolves from system.toml, which is the drift RFC-0098 removes.

A Rust example does not take --features rmw-cyclonedds at all: its RMW is its image’s (issue 1305). examples/linux/rust/talker declares linux_cyclonedds, and nros sync --image linux_cyclonedds && nros build linux_cyclonedds builds it — the board crate’s rmw-cyclonedds builds Cyclone through nros-rmw-cyclonedds-sys.

A7. The board name is a typo

…/system.toml: board `mps2-an358` is claimed by no board descriptor under /…/nano-ros

[image.<id>] board is where a leaf names its board, and a typo there is refused by name rather than guessed at. The legal spellings are the names = [...] arrays of the board descriptors, one per board crate at packages/boards/*/nros-board.toml; several are aliases for the same board (qemu-mps2-an385 and rtic-mps2-an385 are two entry shapes on one descriptor).

The neighbouring refusals, when the image is missing rather than misspelt:

this workspace declares no `[image.*]`. An image is the buildable unit — see RFC-0065 D6.
…/system.toml: names no board (RFC-0098 D3: `[image.<id>] board = "<board>"`)

The first means there is no system.toml beside the package at all — a leaf without one is not a leaf nros build can plan. The second means the file is there and its [image.<id>] table has no board key.

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: RCLC_CHECK failed: rclc_support_init(...) -> -4

RCLC_CHECK failed at src/main.c:92: rclc_support_init(&app.support, argc, argv, &allocator) -> -4

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

The C API entry point is rclc_support_init (rclc’s (&support, argc, argv, &allocator)) or, with an explicit locator, rclc_support_init_with_locator — not nros_init or nros::init, which don’t exist in the C API.

B3. C++: process exits 156 after a rclcpp::init_in 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 RCLCPP_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
ROS_DOMAIN_ID=7 ./build/c_talker         # also overridable

The native Rust / C / C++ talkers all read NROS_LOCATOR, then fall back to the build-time default. The retired ZENOH_LOCATOR / ZENOH_MODE are REFUSED at startup with an error naming NROS_LOCATOR / NROS_SESSION_MODE — unset them. Embedded targets have no runtime env — their locator is compile-baked from system.toml ([image.<id>] locator, or [system] locator for an image that does not state one), so editing that file and rebuilding 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/linux/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/linux/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 (in a checkout, the tree’s own build is the binary this tree accepts — RFC-0090 / phase-431).

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 linux --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. Four files matter:

examples/linux/rust/talker/
├── system.toml         # WHAT this deploys to — the one file you edit
├── Cargo.toml          # registry-style deps; no board facts
├── package.xml         # ROS-style manifest (drives codegen tooling)
├── generated/          # auto-generated message bindings (gitignored)
├── build/              # everything `nros sync` generates (gitignored)
└── src/
    ├── main.rs         # one line: nros::main!(spin = "forever")
    └── lib.rs          # the ~65-line talker node body

system.toml is the whole deployment statement — the same schema a multi-node workspace’s bringup package uses (RFC-0098):

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

[[component]]
pkg   = "native_talker"
class = "native_rs_talker::Talker"
name  = "talker"

[image.linux]
board = "linux"

You never hand-write a build setting. No target triple, no linker flag, no [patch.crates-io] table, no .cargo/config.toml: nros sync derives every one of those from board = "linux" and writes them to build/linux/nros-cargo.toml, which nros build hands cargo with --config.

Retargeting is therefore one line. This native talker names no board crate: it depends on a generated <pkg>_nros_selection package that nros sync writes for the image’s board (with that image’s RMW and ROS edition), so the board = line is the whole edit (issue 1305). Everything else the board implies — the triple, the link group, the QEMU runner, the cross compiler — follows the system.toml edit on its own. A multi-node workspace has no such caveat: its entry is generated, so there the board really is one line.

Native (host) images read the locator / domain from environment variables (NROS_LOCATOR — the retired ZENOH_LOCATOR is refused at startup — and ROS_DOMAIN_ID). Embedded images bake theirs from the same [image.<id>] table (locator, and the address in net) — the shape shows up under the Embedded Starters section.

The Cargo.toml is the contract that wires nano-ros into your package, and it holds Rust facts only. 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 [patch.crates-io] block that resolves them into a nano-ros checkout is GENERATED by nros sync, into build/<image>/nros-cargo.toml beside the package — nothing about the build is committed, and nothing about it is hand-edited (RFC-0098 D1). Verbatim from examples/linux/rust/talker/Cargo.toml (trimmed to the docs-relevant fields — the in-tree file also keeps a zenoh-only link-tls feature):

[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"

[dependencies]
nros = { version = "*", default-features = false,
         features = ["std", "alloc", "env", "rmw-cffi", "macros"] }
# The image's board crate, RMW backend and ROS edition — GENERATED by
# `nros sync` / `nros build` from `system.toml`.
native_rs_talker_nros_selection = { path = "build/nros/selection" }
# 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]

Nothing in it names a board, an RMW or a ROS edition. Those are the image’s (system.toml), and nros sync writes them into the generated <pkg>_nros_selection package the manifest depends on (RFC-0098 D6, RFC-0031). The talker declares one image per RMW and edition — linux (zenoh, Humble, the default), linux_xrce, linux_cyclonedds, linux_jazzy, … — so picking another backend is a command, not an edit:

nros sync --image linux_xrce && nros build linux_xrce

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 a generated [patch.crates-io] block, and nros sync rewrites it (plus the generated message crates, and the board settings the copied system.toml still names) for wherever the directory lives now:

cp -r examples/linux/rust/talker ~/my-talker && cd ~/my-talker
nros sync
nros build
RUST_LOG=info ./build/linux/target/debug/talker

Nothing in the copied directory names a path into the checkout, so the copy is a checkout-independent starter: nros finds the SDK it belongs to (the checkout an in-tree nros was built in, or a release’s own share/nano-ros), and --nano-ros-path <dir> names another on the command line, never in a file.

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:

On native these stay environment variables — [image.linux] declares no locator. An embedded image bakes them from its own [image.<id>] table instead; see the Configuration Guide.

Build

cd examples/linux/rust/talker
nros sync             # writes generated/ message bindings and
                      # build/linux/nros-cargo.toml from system.toml
nros build            # builds the image `[image.linux]` declares

First build pulls dependencies (~3 minutes). Re-builds finish in seconds. The binary lands at build/linux/target/debug/talker — under build/, never beside your sources.

Driving cargo yourself (an IDE, a CI step, --release) is supported: run nros sync first, then point cargo at the generated settings file. Run it from the directory above the package, so the package’s own .cargo/ is not read a second time — phase-445 W6 deletes that directory, after which the working directory stops mattering:

cd examples/linux/rust
cargo build --manifest-path talker/Cargo.toml \
            --config talker/build/linux/nros-cargo.toml

That file is regenerated on every nros sync; never edit it, and never add a .cargo/config.toml of your own to carry board facts. Your own Rust-toolchain preferences go where cargo already looks for them — a parent directory or $CARGO_HOME.

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/linux/rust/talker
RUST_LOG=info ./build/linux/target/debug/talker
# 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 starting the binary (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 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/linux/rust/talker/

Copy the directory, run nros sync inside it, rename the package, and your starter is ready to modify. To aim it at a board, change [image.linux] board in system.toml to that board’s name (nros board list prints them), swap the board crate in [dependencies] to match (issue 1305 — or start from a bare-metal, FreeRTOS, NuttX or ThreadX-Linux example, whose board crate is generated), and re-run nros sync.

Next

• Add a subscription: examples/linux/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 and the Zenoh backend, with one find_package(nano_ros).

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 (in a checkout, the tree’s own build is the binary this tree accepts — RFC-0090 / phase-431).

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 linux --rmw zenoh

See Install + first build (Linux) for more.

Project layout

The talker is a standalone CMake project. Four files matter:

examples/linux/c/talker/
├── system.toml         # WHAT this deploys to — the one file you edit
├── CMakeLists.txt      # find_package + targets; no board facts
├── package.xml         # ROS-style manifest (drives codegen tooling)
└── src/
    └── main.c          # ~100-line talker

system.toml is the whole deployment statement — the same schema a Rust leaf and a multi-node workspace bringup use (RFC-0098):

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

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

[image.linux]
board = "linux"

find_package(nano_ros) reads it, derives the platform from the board, and configures the build accordingly. Nothing in CMakeLists.txt names a platform, a board or an RMW — and the package.xml <nano_ros deploy=… board=… rmw=…/> export that used to carry that tuple is retired and refused. Switching this example to a board is editing [image.linux] board and re-running cmake; a C or C++ leaf names no board crate, so that is the only edit to the project — a cross build still passes its -DCMAKE_TOOLCHAIN_FILE on the command line.

nano_ros_add_executable still accepts DEPLOY and BOARD keywords, for a project with no system.toml. Beside one they are redundant at best: a keyword that names a different deploy or board than the leaf’s [image.<id>] stops the configure and names both files, rather than quietly building the CMakeLists.txt one.

On native, locator + domain come from env vars (NROS_LOCATOR, ROS_DOMAIN_ID) with built-in defaults; an embedded image declares them in its own [image.<id>] table (locator, and its address as net = { eth0 = { network = "qemu", host = N } }) and they are baked at build time (see Configuration).

The CMakeLists.txt is, verbatim from examples/linux/c/talker/CMakeLists.txt:

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

set(CMAKE_C_STANDARD 11)
set(CMAKE_C_STANDARD_REQUIRED ON)

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)

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

nano_ros_add_executable does the wiring the old five-set() preamble did by hand: it generates the C bindings the package declares, links NanoRos::NanoRos and the platform, and pulls in the active RMW’s strong nros_app_register_backends() stub (calling nros_rmw_zenoh_register() for the zenoh image above). Which RMW that is comes from [system] rmw, not from a -D on the command line.

The C entry point is int main(int argc, char **argv), as in any rclc program. On a board the C runtime does not call main, so the build compiles yours under another name and reaches it from the platform’s own entry (Zephyr’s main(void), an RTOS startup task); on Linux it is the process entry. You write main either way.

#include <rcl/rcl.h>
#include <rclc/executor.h>
#include <rclc/rclc.h>
#include <std_msgs/msg/int32.h>

int main(int argc, char** argv) {
    // 1. rclc_support_init() — opens the zenoh session
    // 2. rclc_executor_init() / rclc_node_init_default()
    // 3. rclc_publisher_init_default(&pub, &node,
    //        ROSIDL_GET_MSG_TYPE_SUPPORT(std_msgs, msg, Int32), "/chatter")
    // 4. rclc_timer_init_with_context() with a 1 Hz period; the callback calls
    //        rcl_publish(&pub, &msg, NULL)
    // 5. rclc_executor_spin() until SIGINT
}

Generated messages take rosidl’s C names and member shape (std_msgs__msg__String in <std_msgs/msg/string.h>, msg.data.data / .size / .capacity). Their strings and sequences point at memory you own: wire them with the generated <Msg>__init_in(&msg, &storage) over a <Msg>__Storage, or point data at your own buffer as micro-ROS code does. Nothing on this path allocates, so rosidl’s allocating <Msg>__init / __fini are not declared.

Configure

Three runtime knobs:

On an embedded image the same knobs are compile-baked from that image’s [image.<id>] table in system.toml (see Configuration).

Build

cd examples/linux/c/talker
cmake -B build -Dnano_ros_ROOT="$(nros sdk-root)"
cmake --build build

No nros sync here, and that is a property of the language, not an oversight: a C or C++ leaf’s message bindings are generated inside CMake, at configure time, from the package’s own declared dependencies. A Rust leaf needs sync because its message crates and its build settings must exist before cargo parses anything. Measured: a copy of this directory outside the checkout configures and builds with no nros sync at all. See Workflow by Platform and Language.

nros build works here too: in a single-package C or C++ leaf it runs the same two cmake lines, into build/<image>/cmake, with the toolchain file the board names (issue 1296). In a multi-node workspace it is the only build verb.

A raw cmake must be told where nano-ros is, as above — -Dnano_ros_ROOT=/path/to/nano-ros, or "$(nros sdk-root)", which prints the SDK root the nros on PATH resolves. nros build (and the CMakePresets nros init writes) passes it for you; activate.sh does not export it.

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/linux/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, rclc_support_init returns immediately with -4 (RCLC_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/linux/c/talker/

Next

• Add a subscription: examples/linux/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 (in a checkout, the tree’s own build is the binary this tree accepts — RFC-0090 / phase-431).

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 linux --rmw zenoh

See Install + first build (Linux) for more.

Project layout

The talker is a standalone CMake project. Three files matter:

examples/linux/cpp/talker/
├── system.toml         # WHAT this deploys to — the one file you edit
├── CMakeLists.txt      # find_package + targets; no board facts
├── package.xml         # ROS-style manifest
└── src/
    └── main.cpp        # ~70-line talker

system.toml is the whole deployment statement — [system] for the RMW and domain, [[component]] for what runs, and one [image.<id>] per target naming its board (RFC-0098). find_package(nano_ros) reads it and derives the platform from the board, so no line of CMakeLists.txt names a platform, a board or an RMW. Switching this example to a board is editing [image.linux] board and re-running cmake; see First Node — C for the file in full.

Native (host) talkers read the locator + domain from arguments passed to rclcpp::init_in(...); no other config is needed. An embedded image declares its locator and its address (net = { eth0 = { network = "qemu", host = N } }) in its own [image.<id>] table and bakes them at build time. The package.xml <nano_ros deploy=… board=… rmw=…/> export that used to carry that tuple is retired and refused.

The CMakeLists is the ament shape you already know — this is the complete canonical file at examples/linux/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 17)
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 [system] rmw in system.toml, not CMake code and not a configure-line cache variable.

The C++ entry point is int main(int argc, char** argv), as in any rclcpp program; the build reaches it from the platform’s entry, as for C. Write that exact signature: the build declares the renamed function with it, so another form fails at link naming nros_ported_main(int, char**).

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

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

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

int main(int argc, char** argv) {
    RCLCPP_TRY_RET(rclcpp::init_in(), 1);

    rclcpp::Node node;
    RCLCPP_TRY_RET(rclcpp::create_node(node, "talker"), 1);

    rclcpp::Publisher<std_msgs::msg::String> pub;
    RCLCPP_TRY_RET(node.create_publisher(pub, "/chatter"), 1);

    // ... register a timer + spin
}

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

If you write the rclcpp::Node constructor instead

rclcpp::create_node(node, "talker") above returns a Result, and RCLCPP_TRY_RET checks it. The rclcpp-shaped constructor has no return value to check — and on a -fno-exceptions target, which every nano-ros build is (RFC-0018), it cannot throw the way upstream’s does either. It records the failure and reports it through ok():

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

Skip that line and main runs on with a node that never came up. The object exists either way, node.create_publisher(...) on it still compiles and still returns, and nothing ever reaches the wire. There is no diagnostic and no crash — not throwing is the point, so asking is your job.

A generated entry already asks, and halts naming the node that failed, so a workspace component needs none of this. It is only on you in a hand-written main like the one above.

The two-phase form carries the same obligation:

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

with one difference in your favour: init() returns a Result, which is [[nodiscard]], so dropping it on the floor is a compiler warning. ok() on a constructed node is a question nothing can force you to ask.

Full compatibility notes, including what shared_from_this() and rclcpp::TimerBase do differently here: Porting a ROS 2 C++ node.

Configure

Three runtime knobs:

With no arguments, rclcpp::init_in() (and rclcpp::init(argc, argv)) takes the locator and domain from the build, then the NROS_LOCATOR and ROS_DOMAIN_ID environment variables on a hosted target, so an example needs neither argument.

Build

cd examples/linux/cpp/talker
cmake -B build -Dnano_ros_ROOT="$(nros sdk-root)"
                        # raw cmake names the root; `nros build` (or the
                        # CMakePresets `nros init` writes) passes it for you
cmake --build build

No nros sync here: a C++ leaf’s message bindings are generated inside CMake, at configure time. (A Rust leaf needs sync, because its message crates and its build settings have to exist before cargo parses anything.) nros build in the leaf runs these same two cmake lines, into build/<image>/cmake, with the board’s toolchain file (issue 1296); in a multi-node workspace it is the only build verb.

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/linux/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, rclcpp::init_in returns -100 (TransportError) — the RCLCPP_TRY_RET macro logs the failed call to stderr.
2. Check stderr for [nros] …/main.cpp:LINE rclcpp::init_in(...) -> -N diagnostics. -3 / -100 both indicate transport open failed.
3. See Troubleshooting — First 10 Minutes.

GitHub source

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

Next

• Add a subscription: examples/linux/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, and the backend allocates only when a session or entity is created — never per message. (It is not heap-free: each allocation goes through nros_platform_alloc, and their number follows the entities you declare.)
• 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.

Workspace (C, C++, mixed or Rust)

One edit, in the bringup’s system.toml:

[system]
rmw = "cyclonedds"          # zenoh | xrce | cyclonedds

or, for one image only, rmw = "…" inside its [image.<id>] block. Then

nros sync
nros build

A workspace has no root build file to edit (RFC-0098 D9): nros build writes the CMake root under build/ with BACKEND taken from the image’s rmw, and for a Rust image nros sync writes the selection facade that gives the board crate the backend feature. Each image builds into its own directory, so no object files from another backend linger.

Known issue (1295). A Rust image on cyclonedds also needs the nros crate’s rmw-cyclonedds feature — the type-descriptor gate: Cyclone DDS resolves topic types through a runtime descriptor registry, and this feature registers a message’s descriptor before its topic is created. The generated facade does not name it yet, so such an entry builds and then fails PublisherCreationFailed at startup. Zenoh and XRCE need no such feature, and C/C++ images are not affected.

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 -Dnano_ros_ROOT, which nros build passes; RFC-0048) or a raw add_subdirectory — for example a copied-out leaf like examples/linux/c/talker/ — picks its backend on the configure line:

cmake -S . -B build -Dnano_ros_ROOT="$(nros sdk-root)" \
    -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.

Single Rust package

A single Rust package with its own system.toml (no bringup) is the same one edit — rmw in that system.toml — followed by nros sync and a rebuild. The Rust workspace case is covered by the section above: a workspace entry is generated, so there is no entry Cargo.toml to edit.

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, the image’s rmw in system.toml is rendered into a Kconfig choice (CONFIG_NROS_RMW_ZENOH / CONFIG_NROS_RMW_XRCE / CONFIG_NROS_RMW_CYCLONEDDS, exactly one), never written in a conf file (phase-481).

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
• Small, bounded heap use on the MCU: the backend allocates when a session or entity is created, never per message (each is a nros_xrce_calloc in an open/create path, through nros_platform_alloc; each XRCE_MAX_SUBSCRIBERS slot is heap, so size it to what you declare)
• 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 -DNROS_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 — subscription_event_init / publisher_event_init / publisher_assert_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 -DNROS_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 (-DNROS_RMW=cyclonedds / [image.<id>] 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).

Two worked examples declare the bridge in system.toml instead of writing it: examples/workspaces/bridge-cyclonedds/ (zenoh → Cyclone DDS) and examples/workspaces/bridge-xrce/ (zenoh → XRCE Agent). The hand-written form above has no example of its own; the walkthrough points at the e2e gateway fixtures that use it.

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

You write none of it. The board crate’s rmw-<x> feature is the lowered form of the declared RMW (RFC-0031’s phase-248 C5b amendment: the board crate is the selection point, and brings the backend and the platform), and the CLI writes it:

• in a WORKSPACE, [image.<id>].rmw in the bringup’s system.toml is the declaration, and the Entry pkg’s generated manifest carries the lowered form;
• in a single-package example, the same key in the example’s own system.toml, lowered into its generated <pkg>_nros_selection package (build/nros/selection, issue 1305). An example that runs on several backends declares one image per RMW and builds the one it names:

# system.toml
[system]
name = "native_talker"
rmw = "zenoh"
default_images = ["linux"]

[image_defaults]
board = "linux"

[image.linux]

[image.linux_cyclonedds]
rmw = "cyclonedds"

nros sync --image linux_cyclonedds && nros build linux_cyclonedds

The example’s Cargo.toml names only <pkg>_nros_selection = { path = "build/nros/selection" } — never rmw-<x> / ros-<edition> features. (The nros umbrella’s rmw-cyclonedds is a MARKER the generated package adds for a Cyclone image: the generic path then registers type descriptors.) No example calls <backend>::register() either: nros::main! boots through the board crate, whose rmw-<x> feature links the backend and registers it.

For C++ consumers, the declared RMW lowers to the CMake cache var:

cmake -S . -B build -Dnano_ros_ROOT="$(nros sdk-root)" \
    -DNROS_RMW=cyclonedds  # zenoh / xrce / cyclonedds

Zephyr

The image’s rmw in system.toml, like every other platform. The nano-ros module renders it into the Kconfig choice (CONFIG_NROS_RMW_ZENOH / _XRCE / _CYCLONEDDS, exactly one), so it is never written in prj.conf (phase-481). One image per backend, picked with -DNROS_IMAGE:

[image.zephyr_zenoh]
board = "zephyr"
rmw = "zenoh"
conf = ["prj-zenoh.conf"]       # Zephyr-native settings that backend needs

[image.zephyr_cyclonedds]       # Cyclone: Cortex-A/R and native_sim targets
board = "zephyr"
rmw = "cyclonedds"
conf = ["prj-cyclonedds.conf"]

See Configuring an image.

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/linux/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 alongside C++ or Rust ones. The Node-pkg register ABI is language-neutral, so a C Node pkg links into the same 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/
├── .colcon_workspace           # the tracked marker: this directory IS a workspace root
└── 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 + [image.*]

Two kinds of package, and that is the whole tree. A workspace has no root build file at all — no Cargo.toml, no CMakeLists.txt — the way a colcon workspace is just a directory of packages (RFC-0098 D9). There is no binary package to write either: from the [image.*] table in the Bringup pkg, nros build generates the entry and the build root that compiles it, both under build/. The cargo root is the generated entry itself, build/<coordinate>/<entry>/Cargo.toml; the cmake root is build/<coordinate>/CMakeLists.txt. Nothing generated is ever written beside your source.

A typical product has many Node pkgs, one Bringup pkg per logical system, and one [image.*] row per board or deploy target. The same talker_pkg and listener_pkg are linked into a native host image for integration testing and a Cortex-M image for hardware, with nothing duplicated between them.

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. Images — the [image.*] row that becomes a program, and the one platform that still needs a package of its own.
5. C / C++ multi-node workspaces — the same structure through CMake.
6. Mixed-language workspaces — C Node pkgs beside C++ and Rust ones.
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 (in a checkout, the tree’s own build is the binary this tree accepts — RFC-0090 / phase-431).

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 linux --rmw zenoh

The three roles in practice

Node pkg — a lib crate that contains one node’s logic. It declares nros::node!(T); its Cargo.toml carries Rust-toolchain facts only, and the node’s identity — which package, which class, what it is called — is a [[component]] row in the Bringup pkg’s system.toml. It has no fn main() — no package you write has one. 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 and the images built from it. It contains a package.xml, a system.toml (which nodes run, how they’re wired, and an [image.<id>] row per program), and a launch/ directory with ROS 2 launch XML. No Cargo.toml, no compiled code. Naming convention <system>_bringup, matching nav2 / Autoware / turtlebot3.

Image — not a package. [image.linux] board = "linux" is a row in that system.toml, and nros build linux turns it into a program: it generates, under build/, the entry that links the Node pkgs and the board crate and hands control to the nano-ros runtime. A second board is a second row, not a second directory.

Two commands, in this order, and they are the same two everywhere in this group:

nros sync      # generated message bindings + the generated build settings
nros build     # every [image.*]; or name one: nros build linux

nros sync is yours to run once per workspace, and again whenever you edit a .msg or move the checkout. A workspace that has never been synced makes nros build stop at preflight with one line naming it.

The app-node shape you already know (examples/linux/rust/talker/) is a single package that is both the logic and the boot point — no bringup and no entry, but the same system.toml beside its Cargo.toml, stating its board in an [image.*] row (RFC-0098 D3). nros::main!() reads it. 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:

nros build hands off rather than taking over: it generates what the build system needs and then runs your platform’s own tool (cargo, cmake, west, idf.py), so compiler errors stay the compiler’s, unchanged. Running the tool yourself keeps working. One image = one binary = one process; multi-process orchestration (the equivalent of several ros2 launch nodes in separate processes) is several images plus a shell script or 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. Images — declare the [image.*] row that becomes a runnable program.
4. C / C++ multi-node workspaces — use the same project shape with CMake.

For C Node pkgs alongside C++ and Rust ones, 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). An image 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 (in a checkout, the tree’s own build is the binary this tree accepts — RFC-0090 / phase-431).

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 linux --rmw zenoh

Scaffolding a Node pkg

Use nros new to create a skeleton:

nros new node talker_pkg

nros new node writes the package under src/ and adds its [[component]] row to the bringup. There is no member list to maintain and no workspace root to maintain it in: a workspace is a directory of packages (RFC-0098 D9), and nros build discovers them under src/, generating the entry that names them as path dependencies under build/.

(nros new <name> --platform linux --lang rust is the other verb, and a different output — a standalone runnable project that states its own board in its own system.toml. Use it for a copy-out example, not for a workspace member.)

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] + dependencies — Rust-toolchain facts only
└── src/lib.rs           # impl Component + ExecutableNode; ends with nros::node!(Talker);

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

Declaring the node — the [[component]] row

A Node pkg’s Cargo.toml is an ordinary Rust manifest: a [lib] target and its dependencies, and nothing that describes a deployment. Who this node is — which package provides it, which type implements it, what it is called — is one [[component]] row in the Bringup pkg’s system.toml, beside the rows for every other node in the system (RFC-0098 D5). From examples/workspaces/rust/src/demo_bringup/system.toml:

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

The node package’s own manifest REGISTERS the class it exports, in a [package.metadata.nros.node] table. That is not a deployment and not a second copy of the row above: it is the Rust spelling of node registration, the counterpart of a C/C++ package’s nros_components_register_node(<target> PLUGIN pkg::Class …) in its CMakeLists.txt (itself ROS’s rclcpp_components_register_node). The metadata pipeline reads it — nros sync’s probe, nros check’s dispatch lint — and a package registers once however many bringups launch it, whereas a [[component]] row is one bringup’s choice to run it. It names no namespace: that is the launch file’s to give, as it is for a C/C++ node (issue 1289).

The manifest beside src/lib.rs is then just this:

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

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

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

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 the generated entry 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 — the difference between them is an [image.*] row, not a second copy of anything.

src/lib.rs — the node implementation

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

The node is the same type everywhere. ctx.create_node(...) returns an nros::Node, the type a standalone program gets from executor.create_node(name), with rclrs’s methods: create_publisher, create_subscription(topic, callback), timers, name(), logger(), the graph queries. A function written against &mut nros::Node serves both. What a component adds is the DeclarativeNode extension (bring it into scope with use nros::DeclarativeNode;): constructors that declare an entity by stable id and bind its callback by NAME, which is what lets the board dispatch callbacks from its own tasks and lets nros sync measure the component without running it.

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, Component, NodeContext, DeclarativeNode, NodeOptions, NodeResult,
    TimerDuration,
};

pub struct Talker;

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

    // What this class's per-instance registries hold, in order: publishers,
    // service servers, service clients, action clients, action servers.
    const ENTITY_BOUNDS: nros::EntityBounds = nros::EntityBounds::exact(1, 0, 0, 0, 0);

    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:

• Component::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 image’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.
• ENTITY_BOUNDS is static RAM you either pay or do not (issue 0857). nros::node! emits a static sized from it, and a publisher slot carries a loan arena — so the default (NROS_RUNTIME_MAX_CELL_ENTITIES, 8 per kind) measured 50,824 bytes of .bss for a one-service component against 568 bytes for the same component declaring what it creates. Count the five kinds in your own register(); a timer or a subscription needs no slot here (they claim an executor callback slot instead). Declaring FEWER than register() creates is a registration error at boot, never a silent drop, so the number is safe to make exact.

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 Component::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 rclcpp::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;
  }
  ::rclcpp::Result configure(::rclcpp::Node& node) {
      return ::rclcpp::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

You never build a Node pkg on its own — you build an image, and it links the Node pkgs its launch file names:

# From examples/workspaces/rust/ (or your workspace root):
nros sync
nros build linux

nros sync writes the generated message crates and the build settings each image needs; run it once per workspace, and again after editing a .msg.

No per-Node-pkg invocation is needed, and no cross-compile flags either: the image’s board carries the rustc triple, so building for an embedded target is another row rather than another command line.

[image.freertos]
board = "mps2-an385-freertos"

nros build freertos

Next steps

• Bringup packages — wire the Node pkgs together into a topology.
• Images — the [image.*] row that becomes a binary, on real hardware or a host process.
• Role reference — the full reference for the package roles, metadata fields, and the nros::main!() forms.

Bringup packages

A Bringup pkg is the declarative glue that ties your Node packages together into runnable programs. It owns the launch file, the wiring between nodes, and the [image.*] table saying which programs get built out of them — 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 that turns them into something you can build and run.

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 (in a checkout, the tree’s own build is the binary this tree accepts — RFC-0090 / phase-431).

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

A multi-node workspace needs exactly one per logical system. It is where [image.*] lives, so it is the package that gives a workspace images to build — nros build reads that table to decide what programs exist. A workspace with no bringup still builds, colcon-style: every package in dependency order, each into its own build/<pkg>/, with no images. (The single-package copy-out shape under examples/<platform>/<lang>/ has no bringup package, but it writes the same system.toml beside its own Cargo.toml or CMakeLists.txt — one schema either way, RFC-0098 D3 — and boots itself with a bare nros::main!().)

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.linux]
board = "linux"

[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 into the node’s parameter store. Two capability axes in [system] features decide what else the image gets:

declared	store (declare_parameter, launch seeds, --ros-args -p)	ros2 param services
params	yes	no — nothing is served, and the image claims no queryable for it
param_services	yes	six per node (get, set, list, describe, …)

Pick params on a small target that only needs its nodes to read their configuration: the six services cost a queryable each per node, plus their buffers. What it gives up: ros2 param get|set|list|describe|dump finds nothing for the image’s nodes, and the use_sim_time runtime switch has nothing to set it. Which parameters exist is a contract fact; whether they are served is this bringup fact.

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: sync → check → run

Once your Bringup pkg is written, nros sync prepares what the build needs, nros check validates the declarations, and nros build turns one of its images into a program:

# 1. Sync. Once per workspace, and again after editing a .msg: it writes the
#    generated message crates and each image's generated build settings.
nros sync

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

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

# 4. Build an image. With no name, `nros build` lists what this workspace declares.
nros build linux

# 5. Run it. Zenoh needs a router first, 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 &

Sync comes first because everything after it reads what it wrote. A workspace that has never been synced makes nros build stop at preflight with one line naming it:

Error: missing prerequisites for this build:
  - generated message bindings (this workspace has never been synced)
      run: nros sync

The binary boots every node the launch file names, composed into one process. It lands under build/, never beside your source: build/<coordinate>/cmake/ on the cmake driver, build/<coordinate>/<entry>/target/ on the cargo one.

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 workspace that pairs with this guide. Copy the whole directory out and rename the packages, then:

nros setup linux
nros sync            # once per workspace — message bindings + build settings
nros build linux

nros build walks the packages, resolves the image, checks the toolchain, generates the entry and the build root that compiles it — both under build/, neither beside your source — and hands off to cargo. nros check still works and is worth running; it is just no longer something you have to type.

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

Naming a launch file from an entry

The nros::main! macro’s launch = argument names the bringup package and, optionally, a launch file within it — the SAME inputs you author, and the same pair an [image.*] row names. You will read this in a generated entry, and write it yourself only in a single-package project or a materialized one. The build resolves the pair 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")]);
}

The Images page covers the macro forms and the generated entry in full.

Where to go next

• Images — the [image.*] row that becomes a program
• Role reference — full reference for the package roles and the image table
• Project layout — start here if you haven’t read it yet

Images

An image is one buildable program: a topology, a board, and a backend. You declare it as a row in your Bringup pkg’s system.toml —

[image.linux]
board = "linux"

— and build it by name:

nros sync
nros build linux

There is no package to write. nros build discovers your Node pkgs, reads the [image.*] table, and generates the entry that boots the topology, under build/. An image is a row, not a directory.

That is the whole model. The rest of this page is what goes in the row, where the generated pieces land, and the one case that still needs a package of its own.

Prereqs

Pick one path from a fresh checkout:

A. Front door (bare machine OK — no Rust):

./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 (in a checkout, the tree’s own build is the binary this tree accepts — RFC-0090 / phase-431).

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 image target; for Zephyr / FreeRTOS / ESP32 swap in the matching nros setup board):

nros setup linux --rmw zenoh
nros sync                     # generated message bindings, once per workspace

What a workspace looks like

The four reference workspaces in examples/workspaces/ all have the same shape. Node pkgs, one Bringup pkg, and nothing else:

examples/workspaces/c/
├── .colcon_workspace         # the tracked marker: this directory IS a workspace root
├── .gitignore
├── README.md
└── src/
    ├── talker_pkg/           # Node pkg
    ├── listener_pkg/         # Node pkg
    ├── service_server_pkg/   # Node pkg
    ├── … three more …
    ├── demo_bringup/         # Bringup pkg: package.xml + system.toml + launch/
    └── zephyr_entry/         # the one exception — see below

No CMakeLists.txt, no Cargo.toml at the root — and none is generated there either. A workspace is a directory of packages, exactly as a colcon workspace is, and everything the build produces lives under build/, dist/ and log/ (RFC-0098 D9). The tracked marker that this directory is a workspace root is .colcon_workspace.

And no entry packages, except the Zephyr one. Fourteen images ship out of that directory. nros build with no argument lists them:

$ cd examples/workspaces/c
$ nros build
Error: this workspace declares 14 images and no default.

  demo_bringup:freertos
  demo_bringup:freertos_posix
  demo_bringup:linux
  demo_bringup:linux_action_client
  demo_bringup:linux_action_server
  demo_bringup:linux_cyclonedds
  demo_bringup:linux_robot1
  demo_bringup:linux_robot2
  demo_bringup:linux_service_client
  demo_bringup:linux_service_server
  demo_bringup:linux_xrce
  demo_bringup:nuttx
  demo_bringup:threadx
  demo_bringup:zephyr

  build one:   nros build freertos
  build all:   nros build --all
  or declare:  [system] default_images = ["freertos"]

Fourteen programs, one launch tree, six node packages, one entry directory. Under the old shape that was fourteen directories.

Declaring an image

Images live in the Bringup pkg beside the topology they boot — examples/workspaces/c/src/demo_bringup/system.toml:

[image_defaults]
rmw = "zenoh"

[image.linux]
board = "linux"

[image.freertos]
board = "mps2-an385-freertos"

[image.freertos_posix]
board = "freertos-posix"
# NOT the `[image_defaults]` zenoh. zenoh-pico's FreeRTOS backend is lwIP-only
# and this board has no lwIP.
rmw = "cyclonedds"

[image.linux_service_server]
board = "linux"
launch = "service_server.launch.xml"

[image.linux_robot1]
board = "linux"
launch = "multihost.launch.xml"
args = { host = "robot1" }

[image.zephyr]
board = "zephyr"
conf = ["prj-zenoh.conf"]

Read it as a table of variants over one topology. linux and linux_cyclonedds differ in a backend; linux and linux_service_server differ in a launch file; linux_robot1 and linux_robot2 differ in one launch argument. Nothing is duplicated to express any of that.

Switching a workspace image to another board is that one board line and nros sync — nothing in any package you wrote mentions a board crate, because the entry that depends on it is generated (RFC-0098 D6). A single-package leaf is its own entry and does not yet get that: see Role reference.

[image_defaults] is the base every block folds over (RFC-0065 D5.1): scalars are replaced by the specific block, args merges, conf and features concatenate. Without it an eight-image workspace repeats its RMW eight times, and eight copies of one fact is how they start disagreeing.

[system] default_images = ["linux"] is what a bare nros build then builds.

What nros build generates

Everything it generates lands under build/ — build output, gitignored, none of it yours to edit:

An earlier shape kept the cargo root at <ws>/Cargo.toml, on the grounds that cargo resolves a package’s workspace by walking up and refuses a member above its root. That constraint binds only while a workspace exists: with no root manifest anywhere there is nothing to walk up to, and a path dependency need not sit below anything. So the generated entry is the root, and the workspace keeps no build file of its own (RFC-0098 D9, superseding RFC-0065 D3).

Beside the generated entry sits nros-cargo.toml, the settings file nros sync writes per image (RFC-0098 D1): the board’s rustc triple and link flags, that image’s target-dir, the resolved [env], and the in-repo patch rows. Cargo reads it through --config, which is why each image compiles with its own settings and nothing generated ever appears beside a package — no leaf .cargo/config.toml, no board projection to commit.

The coordinate is the platform and the RMW, plus — for cmake, which pins one compiler per configure — the board. So [image.linux] in examples/workspaces/c configures build/posix-zenoh-linux/ into build/posix-zenoh-linux/cmake/ and leaves its binary at build/posix-zenoh-linux/cmake/linux_entry. On the cargo driver nros build names the entry package it wrote as it goes:

nros build:   entry → …/build/posix-zenoh/linux_entry

The generated cmake root lists every image on that coordinate, not just the one being built: what a coordinate contains is a property of the workspace, and making it depend on which image you asked for would reconfigure on every switch.

An image with its own configuration gets its own configure

One cmake configure builds the nano-ros runtime (nros-c / nros-cpp and the RMW) once for every image on it, so a knob only one image states — a [image.<id>.knobs] row such as [knobs.log] max_level = "warn" — would have no build to land in. So an image whose resolved configuration differs gets its own configure, keyed by a hash of that configuration (RFC-0098 D12, phase-481 W4):

[image.plain]            # states nothing -> build/posix-zenoh-linux/
board = "linux"

[image.warn]             # -> build/posix-zenoh-linux-cfga50aa93c83/
board = "linux"

[image.warn.knobs.log]
max_level = "warn"

[image.warn.knobs.executor]
max_cbs = 13

(packages/testing/nros-tests/fixtures/image_config_ws; each binary prints what its runtime compiled in.) Images whose configuration is the SAME share one configure, -cfg suffix and all, and a workspace whose images state nothing keeps today’s build/<coordinate>/ paths exactly. The cost is one more configure and one more runtime build per distinct configuration — the reason to put a knob that every image on a board shares in the board’s [knobs] instead, where it changes no image’s hash. nros image-facts prints each image’s cmake_build_dir; never derive it by hand.

On Zephyr the same env rows are rendered into the image’s Kconfig fragment instead (see Configuring an image).

The generated entry is the same few lines you would have written. RFC-0065 D4 measured them before deciding to derive them: every Rust entry in the tree was ≤ 6 non-comment lines, every embedded C/C++ entry had zero source files. Three parts, all derivable —

— which is why adding a board adds a descriptor rather than a branch in the emitter, and why the generated entry calls nros::main! rather than its own expansion: the macro reads the launch XML at expansion time, so adding a node to the launch file is picked up by the next compile with nothing regenerated.

The exception: when a framework owns the application

An entry package survives in exactly one situation — an external build system that demands a real application directory. That is Zephyr.

A Zephyr app is the app target that find_package(Zephyr) creates, and it carries authored Kconfig that nothing can derive: prj.conf, the per-RMW prj-<rmw>.conf fragments, boards/*.overlay. RFC-0065 D5 draws the line there — “west and ESP-IDF apps keep their own files because those are Kconfig overlays — user intent, not derivable.”

The Kconfig is the exception; the application is not (issue 1288). nros build writes the west application too — build/<coord>/<image>_entry/ CMakeLists.txt, with find_package(Zephyr), project(), one add_subdirectory per node package your launch file names, and the single nano_ros_add_executable(...) (or rust_cargo_application() for a Rust image) — and then runs west build against it. What you author is the Kconfig, and it lives with the bringup:

src/demo_bringup/boards/native_sim_native_64/
├── prj.conf                            # APPLICATION_CONFIG_DIR
├── prj-zenoh.conf                      # named by [image.<id>] conf
└── boards/
    └── native_sim_native_64.conf       # Zephyr's own per-board discovery

That directory is what [image.<id>] board selects, and switching boards selects a different one rather than editing a package. Every Zephyr image in examples/workspaces/{rust,c,cpp,mixed,derived-tiers-cpp,realtime-c,realtime-cpp} is built this way. realtime-c shows the two-bringup case: demo_bringup declares [image.zephyr] (native_sim) and smp_bringup declares [image.zephyr_smp] (qemu-cortex-a53), so each image names its own bringup and gets its own generated application and its own boards/<board>/ directory.

A board PACKAGE can carry Zephyr files of its own beside its descriptor — a base prj.conf, boards/<board>.conf and boards/<board>.overlay. nros build hands those to the generated application as the first EXTRA_CONF_FILE / EXTRA_DTC_OVERLAY_FILE entries, by the same rule nano_ros_use_board() applies to a hand-written one. They merge AFTER the bringup’s prj.conf (Zephyr’s CONF_FILE) and BEFORE the image’s conf fragments, so a value that must beat the board goes in a conf fragment. realtime-cpp’s [image.fvp] (fvp-aemv8r-smp) is the in-tree case: it lists its own prj.conf in conf again so that its CONFIG_RUST=n lands after the board’s CONFIG_RUST=y.

For a Rust workspace whose image needs a hand-written application after all — Kconfig nros build cannot express, a nano_ros_use_board() preamble — the scaffold is still there:

nros new entry zephyr_entry --platform zephyr

That writes Cargo.toml, CMakeLists.txt and prj.conf, and the [image.*] row — the two halves are one declaration, and every Zephyr build failure worth having is the two disagreeing. A package written this way SUPPRESSES generation for the image that would carry its name, which is what makes the migration in either direction a file operation rather than a flag. Zephyr is the only platform the verb accepts, which is the rule stated by the tool itself:

`nros new entry` currently scaffolds Zephyr entries only (got --platform linux).
Every other platform builds through cargo or cmake, where the entry is
GENERATED from the image and needs no package of its own (RFC-0065 D3).

Running on Zephyr

The Zephyr image names its application and its RMW overlay; nothing else in the row is Zephyr-specific:

[image.zephyr]
board = "zephyr"
conf  = ["prj-zenoh.conf"]

nros sync                              # generated message bindings, once
nros build demo_bringup:zephyr         # resolves the app + overlays, runs west build
nros build demo_bringup:zephyr -- -t run

Plain west keeps working and stays the primary flow — nros build is the convenience that applies an image’s overlays for you, never a required layer between you and west:

west build -b native_sim/native/64 build/zephyr-zenoh/zephyr_entry \
    -- -DAPPLICATION_CONFIG_DIR=src/demo_bringup/boards/native_sim_native_64
west build -t run                      # native_sim; `west flash` for hardware

(nros build demo_bringup:zephyr --dry-run prints that command for your image, which is the reliable way to get it: the application path carries the coordinate, and --dry-run reads it off the image rather than asking you to spell it.)

One workspace covers every Zephyr board. Zephyr owns its board abstraction, so the board is chosen by the image’s board key and never baked into a package. That key is a nano-ros board id (zephyr), never Zephyr’s own spelling: its board descriptor states the Zephyr id ([board.zephyr] west_board = "native_sim/native/64"), and that is what west build -b receives. Writing board = "native_sim/native/64" on the image is refused, naming the id to use. To target another Zephyr board, name a descriptor that states its west_board — nrf52840dk/nrf52840, say, from a board package in your workspace — and swap prj-zenoh.conf for prj-xrce.conf: what changes is which boards/<board>/ directory is read, and nothing in src/ at all.

The entry key exists for the case where several packages could answer to one image. An application package no longer declares the board it serves — that direction is reversed: the image claims the entry, by naming it (entry = "zephyr_entry") or, when it names none, by being the image whose generated entry would carry that name (RFC-0098 D5, phase-445 W5). So the application reads its deployment — board, RMW, locator, domain — off the image that claims it, and a [package.metadata.nros.entry] deploy left in a Cargo.toml is now an error naming the file to write instead.

Two images claiming one entry is refused rather than resolved by first match — which image’s locator the entry bakes is not a coin toss, so nros build names the candidates instead of picking one. That arm is reachable for C/C++ entries, which are matched by their DEPLOY token; a Rust entry names its image in its own system.toml, so it is never a candidate for a sibling image.

The other reason to set entry is that NO package claims the board — then nros build falls back to the Bringup directory and you see a conf fragment “not found” in a path that is not your application’s. A hand-written application that takes its board from nano_ros_use_board(...) in its own CMakeLists.txt is that case, because the DEPLOY scan does not read the call (issue 1517). Everywhere else, leave entry out and let the name match.

The full Zephyr path — west workspaces, freestanding applications, west nros, sysbuild — is Zephyr (west module).

If you already have entry packages

nros build keeps a hand-written entry: if src/<image_id>_entry/ carries a Cargo.toml or a CMakeLists.txt, it is used as-is and nothing is generated over it. Migration is therefore a deletion, one image at a time — remove the directory, and the next build generates its replacement.

Move these out first, since deleting the package deletes them too:

nros::main!() — what the generated entry contains

You will read this in a generated entry, and write it by hand only in a single-package project or a materialized entry.

#![allow(unused)]
fn main() {
// 1. Single-node self-bringup: reads the board from the `[image.*]` row in
//    the `system.toml` beside this package's Cargo.toml, and boots the Node
//    pkg that is the only member of this package.
nros::main!();

// 2. RETIRED (phase-484 W8c): `nros::main!(board = LinuxBoard)` is a
//    compile error. The board belongs in `system.toml`; an out-of-tree board
//    crate states its own type in
//    `[package.metadata.nros.board] type = "::my_board::MyBoard"`, which
//    form 1 reads.

// 3. Multi-node (CANONICAL): name your INPUT — the Bringup pkg, and
//    optionally a launch file inside it; the default is its default launch.
nros::main!(launch = "demo_bringup");
nros::main!(launch = "demo_bringup:variant_b.launch.xml");

// 4. Multi-host slice: 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.
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: 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.

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

nros sync re-resolves a model whenever a bringup’s launch XML or system.toml is newer than it, and nros build runs it for you. SystemModels are build artifacts — never commit one (the check-no-tracked-models gate enforces this). Under the hood nros sync runs the pinned nros-launch-resolve helper (RFC-0060 layer 2) by absolute path, never by a bare name on $PATH, because an unrelated ROS 2 play_launch on PATH used to win that race.

The macro reads the image’s board at compile time to select the board crate and executor backend, and 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 the crate root stays a single line — as in examples/mps2-an385-baremetal/rust/talker-rtic/src/main.rs:

#![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 — take ownership of the generated entry:

$ nros build linux          # generate it first — materialize copies, it does not re-emit
$ nros materialize linux
wrote …/src/linux_entry

This entry is YOURS now — `nros build` will not regenerate it.

It lands at src/<image_id>_entry/, carries a stamp recording the shape it was cut for, and nros build warns if that shape later moves. Its derivation stays live — nros::main! still reads the launch file at compile time, so adding a node needs no change here; what is frozen is the shell: the panic policy, the board boilerplate, the crate type. Inside it you can bypass nros::main!() entirely:

#![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. Reach for either only after the declarative escapes — an [image.*] key, a conf fragment, a support package — have actually run out.

Running a native image

Build it, start a router if your backend needs one, run the binary:

cd examples/workspaces/c
nros sync
nros build linux

# in another shell, for the zenoh backend:
ZENOH_CONFIG_OVERRIDE='listen/endpoints=["tcp/127.0.0.1:7447"];scouting/multicast/enabled=false' ros2 run rmw_zenoh_cpp rmw_zenohd &

./build/posix-zenoh-linux/cmake/linux_entry

The binary opens the executor, registers talker + listener composed into a single process, and runs the topology. The launch product is the binary — there is no separate launch step.

examples/workspaces/{c,cpp,rust,mixed}/ are the four canonical workspaces and each carries a README with the commands verified green today.

C / C++ images

Nothing above is Rust-specific: the driver is chosen by the board, not by the language mix, and cmake wins whenever the package graph crosses languages (corrosion makes cargo consumable from cmake; nothing makes cmake consumable from cargo). examples/workspaces/c and examples/workspaces/cpp declare their images exactly as shown here. See C / C++ multi-node workspaces.

Where to go next

• Bringup packages — the system.toml and launch XML an image is declared in.
• Node packages — the Node pkgs an image links.
• Zephyr (west module) — the exception, in full.
• Role reference — reference for the package roles and the macro forms.

C / C++ multi-node workspaces

The four previous chapters (project layout, node packages, bringup packages, images) describe the canonical node pkgs + bringup pkg + [image.*] 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 inside each Node pkg — and, at the root, nothing at all:

my_ws/
├── .colcon_workspace             # tracked marker; there is no root build file
└── 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           #          [system] + [[component]] + [image.*]
        └── launch/system.launch.xml

No entry package, and nothing at the root: a workspace is a directory of packages (RFC-0098 D9). nros build <image> writes a CMakeLists.txt and the entry’s nano_ros_add_executable(…) call into build/<coordinate>/, configures that into build/<coordinate>/cmake/, and builds — see Images. The exception is a Zephyr application, which keeps a package because west needs a real application directory.

The generated cmake root

You do not write this; nros build does, from the packages it discovered and the image it resolved. It is the cmake root — and it lives in build/<coordinate>/, not at the workspace root, which is why its first argument says where the workspace actually is. It is worth reading once, because everything below happens inside it:

cmake_minimum_required(VERSION 3.22)
project(my_ws LANGUAGES C CXX)
find_package(nano_ros REQUIRED COMPONENTS workspace)

nano_ros_workspace(
    WORKSPACE_ROOT "../.."               # this file lives in build/<coord>/
    BACKEND        zenoh                 # zenoh | xrce | cyclonedds
    PLATFORM       "posix"
    SYSTEM         demo_bringup
    ORDER_FROM_DEPENDS
    SUBDIRS        "../../src/talker_pkg"
                   "../../src/listener_pkg"
)

nano_ros_workspace() does the heavy lifting in one call:

1. Sets NROS_PLATFORM=posix + NROS_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 -DNROS_REPO_DIR=<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(::rclcpp::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 generated entry 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

Telling the build what the component creates

NROS_EXECUTOR_MAX_CBS, the subscriber slots and the arena are const sizes compiled into nros-node before a component TU is compiled, while an RFC-0043 component wires itself in its CONSTRUCTOR, at runtime. Nothing the macros emit can supply those sizes — it exists only after linking. So somebody has to state what the image creates, ahead of the build.

That statement is a contract sidecar beside the launch file, not something in this CMakeLists. <stem>.contract.yaml next to <stem>.launch.xml in the bringup package:

# src/demo_bringup/launch/system.contract.yaml
version: 1

nodes:
  talker:
    paths:
      on_timer:                                  # a path with a timer trigger
        trigger: { timer: { rate_hz: 1 } }       # IS the periodic callback
        output: [chatter]
    pub:
      chatter: {}
  listener:
    sub:
      chatter: {}

topics:
  /chatter:
    type: std_msgs/msg/Int32
    pub: [talker/chatter]
    sub: [listener/chatter]

nodes: keys are LOCAL endpoint names — an absolute path there is concatenated onto the node’s FQN and matches no topic. topics:, services: and actions: wire those endpoints to absolute names and carry the type. paths: is where timers live: the model records a path with no input as the periodic callback.

A single-package example writes the same file at <leaf>/system.contract.yaml, beside its system.toml. Its launch file is generated from the [[component]] rows, so there is no launch/ directory to put a sidecar in; nros sync carries this one to where the resolver looks. That is how a standalone leaf states its QoS — and stating it is worth real memory: one sub: { chatter: { qos: { history: keep_last, depth: 1 } } } row takes examples/linux/rust/listener from 273,802 to 172,298 bytes of static RAM, because the zenoh backend then sizes its payload pools for the one sample the image keeps instead of the four it might have.

The name you write must be the name the code registers, ABSOLUTELY. A contract states RESOLVED names; a call site writing "chatter" or a node the launch file remaps is one the build cannot match with certainty, so it refuses that endpoint by name and the image keeps its configured pools rather than being sized from a guess.

nros sync folds it into the resolved SystemModel, and the entry passes that model to the sizing automatically — nothing here takes an argument for it. Inspect the composed answer with:

$ nros ws entity-inventory --metadata <build>/nros-metadata.json       --model <ws>/build/nros/models/demo_bringup/system_model.yaml

The derivation is all-or-nothing per image: a component the contract does not describe makes that image derive nothing and keep its configured NROS_EXECUTOR_MAX_CBS. 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 — so “some of them” is refused rather than guessed at.

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

Earlier versions stated this per component, as nano_ros_node_register(ENTITIES ...). That keyword is retired (phase-412) and now fails with a pointer here. It was a list beside the code with nothing comparing the two, and on the safety island one of them declared six subscriptions for a node that creates seven: every pool derived from it was short by one, and the eleventh subscription failed at boot with a transport error that named nothing.

The census: the contract checked against the code

Since the contract is still a statement beside the code, a CROSS image (any image whose board is not native) checks it before it configures: the native image generated from the same launch file is run once in census mode — it constructs every component against a recording backend, writes what they created, and exits without spinning or dialling a router — and the configure compares that census with the contract row by row. An endpoint the code creates and the contract omits refuses as missing-in-contract (not waivable: it is the short pool); one the contract declares and the code never creates refuses as phantom (waivable per row under [census.waive]).

The configure never builds the native image itself, so a cross build takes the census first:

$ nros ws entity-census take --image demo_bringup:zephyr
$ nros build zephyr

take does nothing when there is nothing to do — a model with no contract, or a census that still matches the code (freshness is by content: touching a file changes nothing, adding a subscription does). With no census, or a stale one, the configure REFUSES and prints that command. A bringup that wants the old behaviour writes [census] on_missing = "warn" / on_stale = "warn" in its system.toml, and gets a CMake WARNING instead.

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

namespace talker_pkg {

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

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

  public:
    ::rclcpp::Result configure(::rclcpp::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);
}

::rclcpp::Result Talker::configure(::rclcpp::Node& node) {
    ::rclcpp::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 node.create_wall_timer<Talker, &Talker::on_tick>(timer_, 1000, this);
}

}  // namespace talker_pkg

The generated entry constructs Talker in static storage and calls configure(node) on the real executor — the same component model the Rust nros::node!(Talker) + the C RCLC_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>

The image, and the entry it generates

Declare the program you want in the bringup’s system.toml —

[image_defaults]
rmw = "zenoh"

[image.linux]
board = "linux"

— and nros build linux emits this into that generated root. BOARD and DEPLOY come from the resolved image, so a generated entry cannot disagree with the board it was generated for; there is no SOURCES, because the verb generates the translation unit carrying main:

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

At configure time the cmake fn shells nros codegen entry --lang cpp --typed, emits ${CMAKE_BINARY_DIR}/linux_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, never the artifact

BRINGUP + LAUNCH name 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, and a committed model is banned outright.

nros sync resolves/refreshes the model whenever the bringup’s launch XML or system.toml is newer than it, and nros build runs it for you.

Writing the entry yourself

Two cases need a hand-written one, and both use nano_ros_entry(NAME … ) in a package’s own CMakeLists.txt:

• A Zephyr application, which west requires as a real directory — scaffold it with nros new entry <name> --platform zephyr.
• Startup the declarations cannot express — nros materialize <image> writes the generated entry out to src/<image>_entry/ and nros build then leaves it alone.

Either way the entry package needs no source file of its own: the cmake function generates the whole body (the main above), so an entry’s CMakeLists.txt names the bringup and launch file and nothing else.

Build + boot

nros sync
nros build linux
./build/posix-zenoh-linux/cmake/linux_entry

nros build resolves the SystemModel for you (via the pinned nros-launch-resolve helper, whenever the launch XML or system.toml is newer), writes build/<coordinate>/CMakeLists.txt, configures, and builds. It does not run nros sync: a workspace that has never been synced has no generated message bindings, and nros build refuses at preflight naming nros sync as the remedy. Sync once per workspace; after that only a .msg edit needs it again. The coordinate directory names what it contains: platform, RMW, board. Driving cmake yourself against that generated root — build/<coordinate>/CMakeLists.txt, never a file at the workspace root — still works.

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.
• linux_entry — the image’s executable, 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 two package roles.

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 + a table of images, 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 image can compose Node pkgs written in different languages. The native reference shape is:

• C Node pkgs for C code you want to keep in C.
• C++ and Rust Node pkgs beside them, in the same workspace.
• One Bringup pkg with the normal ROS 2 launch XML and the [image.*] rows.

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

Layout

my_ws/
├── .colcon_workspace             # tracked marker; there is no root build file
└── src/
    ├── c_talker_pkg/             # C Node pkg
    ├── cpp_listener_pkg/         # C++ Node pkg
    ├── rust_heartbeat_pkg/       # Rust Node pkg
    └── demo_bringup/             # launch XML + system.toml (+ [image.*])

Mixed is not a special case. The driver is chosen by the board, and cmake wins whenever the package graph crosses languages — corrosion makes cargo consumable from cmake, and nothing makes cmake consumable from cargo (RFC-0024 §6.3). So a mixed workspace builds exactly like the C++ one:

$ cd examples/workspaces/mixed
$ nros sync
$ nros build linux

nros build writes a CMakeLists.txt — a nano_ros_workspace(…) call listing the discovered packages, plus one nano_ros_add_executable(…) per image on that coordinate — into build/<coordinate>/, configures it into build/<coordinate>/cmake/, and builds. That generated file is the cmake root; the workspace itself has no build file at all (RFC-0098 D9), and neither the root nor the entry is yours to write.

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 RCLC_C_COMPONENT(StateT, configure_fn) — the typed Entry creates the node and runs configure on the real executor. The component is written against the C API: configure receives an rcl_node_t * and an rclc_executor_t * over the entry’s own node and executor, so a C and a C++ component in one image share both.

# std_msgs is declared in package.xml (`<depend>std_msgs</depend>`), which
# generates its C bindings for this package.
find_package(std_msgs REQUIRED)
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 linux)

#include <stdint.h>
#include <rclc/rclc.h>
#include <std_msgs/msg/int32.h>

typedef struct {
    rcl_publisher_t pub;
    rcl_timer_t timer;
    int32_t count;
} c_talker_pkg_t;

static void on_tick(rcl_timer_t* timer, void* ctx) {
    (void)timer;
    c_talker_pkg_t* self = (c_talker_pkg_t*)ctx;
    std_msgs__msg__Int32 msg = {.data = self->count};
    (void)rcl_publish(&self->pub, &msg, NULL);
    self->count++;
}

static rcl_ret_t talker_configure(rcl_node_t* node, rclc_executor_t* executor,
                                  c_talker_pkg_t* self) {
    self->count = 0;
    self->pub = rcl_get_zero_initialized_publisher();
    rcl_ret_t rc = rclc_publisher_init_default(
        &self->pub, node, ROSIDL_GET_MSG_TYPE_SUPPORT(std_msgs, msg, Int32), "/chatter");
    if (rc != RCL_RET_OK) return rc;
    self->timer = rcl_get_zero_initialized_timer();
    rc = rclc_timer_init_with_context(&self->timer, 1000000000ULL, on_tick, self);
    if (rc != RCL_RET_OK) return rc;
    return rclc_executor_add_timer(executor, &self->timer);
}

RCLC_C_COMPONENT(c_talker_pkg_t, talker_configure)

nano_ros_auto_add_library injects NROS_PKG_NAME (language inferred from the sources), so RCLC_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.

The image

Nothing about the language mix reaches the image declaration. One row per program, in src/demo_bringup/system.toml:

[image_defaults]
rmw = "zenoh"

[image.linux]
board = "linux"

The launch file names the Node pkgs, whatever they are written in:

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

From that pair, nros build emits this into the generated root. LANG follows the workspace’s own sources; BOARD and DEPLOY come from the resolved image, so a generated entry cannot disagree with the board it was generated for. There is no SOURCES, because the verb generates the translation unit carrying main:

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

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.

Note there is no MODEL here. The SystemModel is a build artifact resolved from the launch file by nros sync; naming it in a build file is the deprecated expert override, and a committed one is banned outright (gate check-no-tracked-models).

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, and nros build generates one entry per image under build/. This page is what changes — per language — inside that fixed shape.

Two commands build any of them, in this order:

nros sync
nros build

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). You write no entry: the one nros build generates for each image collapses to one line, and this is what it holds —

#![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 — per image — the settings file cargo is handed with --config: the board’s rustc triple, the link flags, the [env], the patch rows (RFC-0098 D1). Nothing of that is written beside your packages, and cargo cannot resolve the build without it. A C or C++ workspace runs nros sync too; what it does not get from it is the message codegen, which runs inside CMake.
• The RMW is spelled once — [system] rmw = "zenoh" in the bringup’s system.toml, or rmw = on a single [image.*] row when one image differs. The board crate’s feature and the nros facade feature are generated from it, so switching backend is a one-word edit plus nros sync: 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 rclc/rclc.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, composed into one binary:

mixed/src/
├── c_talker_pkg/          # C — publishes std_msgs/Int32 on /chatter
├── cpp_listener_pkg/      # C++ — subscribes
├── rust_heartbeat_pkg/    # Rust — a timer callback
├── …                      # more C and C++ node pkgs: service + action pairs
├── demo_bringup/          # one system.toml for all of them
└── zephyr_entry/          # the one hand-written application: west needs a directory

There is no entry package for the native images and no root build file: the entry for each [image.*] is generated under build/, and the driver is cmake because the package graph crosses languages. Copy the workspace 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 pkgs, Bringup pkgs, and Images

A nano-ros workspace has two kinds of package you write, and a third thing that is not a package at all:

• 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 the images built from it. Contains a package.xml, system.toml, launch/*.launch.xml, and optional config/ + boards/. No Cargo.toml, no compiled code. Named <system>_bringup.
• Image — a row, not a directory. [image.<id>] in that system.toml names a board, a launch file, and a backend; nros build <id> generates the entry package from it, under build/, and hands off to cargo / cmake / west / idf.py. The workspace itself has no root build file (RFC-0098 D9).

The split exists because a node’s logic is portable across boards, but boot + transport + deploy config is not. One Node pkg is reused across native POSIX, FreeRTOS, and Zephyr by adding an [image.*] row per target — never a package per target.

Single-package projects (the copy-out examples under examples/<platform>/<lang>/) skip both packages but keep the declaration: one package carries the node and nros::main!(), and states its board in a system.toml beside its own Cargo.toml — the same file a bringup writes. See Single-package convenience below.

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"] — Rust-toolchain
│                       # facts only; the node is declared by a [[component]] row
│                       # in the bringup's system.toml
├── package.xml         # ROS 2 package manifest (<exec_depend> etc.)
├── src/
│   └── lib.rs          # impl Component 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 the entry the build generates. 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(::rclcpp::Node&) method, C a RCLC_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

A Bringup pkg is pure declarative — it owns the launch topology and the image table, 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
├── boards/                 # optional — per-board RTOS overlays (prj.conf, *.overlay, sdkconfig.defaults)
└── config/                 # optional — params.yaml, etc.

No Cargo.toml, no CMakeLists.txt, no src/. Naming convention <system>_bringup (alias <system>_launch), matching nav2 / Autoware / turtlebot3. A multi-node workspace needs one: [image.*] lives here, so it is the package that gives a workspace images to build. (A workspace with no bringup at all still builds — every package in dependency order, each into its own build/<pkg>/, which is colcon’s default; there are simply no images. A single-package project has no bringup package either, but keeps the system.toml — see below.)

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.

Image

An image is one buildable program: a topology, a board, and a backend. It is a table row in the Bringup pkg’s system.toml:

[image_defaults]           # base every block folds over (RFC-0065 D5.1)
rmw = "zenoh"

[image.linux]
board = "linux"

[image.freertos]
board = "mps2-an385-freertos"
panic = "own"

[image.linux_robot1]
board  = "linux"
launch = "multihost.launch.xml"
args   = { host = "robot1" }

Folding is per-key: scalars are replaced by the specific block, args merges, conf and features concatenate base-then-specific. [system] default_images = ["native"] is what a bare nros build builds; without it, nros build lists the declared images and stops.

Build one, all, or ask what would run:

$ nros build linux
$ nros build --all
$ nros build linux --dry-run     # print the handoff, run nothing

[image.<id>] says what is BUILT; [host.<name>] says where nodes RUN — which machine a node runs on. An image needs no host and a host needs no image (RFC-0065 D6). The old [deploy.<id>] table conflated the two and is refused by name, pointing at both (phase-486 W8).

The generated entry

The entry package is derived from (launch, args, board) and generated — RFC-0065 D4, “A workspace contains no entry packages.” On the cargo driver it lands at <ws>/build/<coordinate>/<image_id>_entry/, and that package’s own Cargo.toml is the cargo root: with no workspace root to walk up to, a generated entry is simply a package with path dependencies (RFC-0098 D9). On the cmake driver the generated <ws>/build/<coordinate>/CMakeLists.txt is the root, and emits a nano_ros_add_executable(…) call per image on that coordinate. Beside a cargo entry sits nros-cargo.toml, the per-image settings file nros sync writes — triple, link flags, [env], patch rows — which cargo reads through --config.

All of it is build output under build/, and none of it is written beside your source: no root build file, no leaf .cargo/config.toml. The tracked marker that a directory is a workspace root is .colcon_workspace.

Three parts, all derivable, which is why adding a board adds a descriptor rather than a branch in the emitter:

The generated entry calls nros::main! rather than an expanded form on purpose: the macro reads the launch XML at expansion time, so adding a node to the launch file is picked up by the next compile with nothing regenerated.

nros::main!() forms

nros::main!();                                          // single-package: reads [image.*] board from system.toml
// RETIRED (phase-484 W8c): `nros::main!(board = X)` is a compile error — an
// out-of-tree board states `[package.metadata.nros.board] type` instead.
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");

The 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 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. launch and model are mutually exclusive.

Escape hatch: nros materialize <image> copies the generated entry to src/<image_id>_entry/ and stamps it; nros build then leaves it alone and warns if the shape it was cut for moves. Inside it you can skip the macro and call <LinuxBoard as BoardEntry>::run(|runtime| { ... }), or go fully manual with nros::Executor::open(&ExecutorConfig::default()). Reach for it only after the declarative escapes — an [image.*] key, a conf fragment, a support package — have run out.

C++ / C analogue: the generated cmake root emits one nano_ros_add_executable(<name> BOARD … BRINGUP … LAUNCH … LANG … TYPED DEPLOY …) per image — no SOURCES, because the verb generates the translation unit that carries main. nano_ros_entry(NAME … LANG … BRINGUP … LAUNCH …) is the hand-written spelling, and you write it yourself only in a Zephyr application (below). MODEL on either is the deprecated artifact-naming override, mirroring the macro. Metadata flows through ${BUILD}/nros-metadata.json rather than a sidecar TOML.

The one entry package that survives

An entry package is still required where an external build system demands a real application directory. That is Zephyr: a Zephyr app is the app target find_package(Zephyr) creates, and it carries authored Kconfig (prj.conf, prj-<rmw>.conf, boards/*.overlay) that nothing derives — RFC-0065 D5, “west and ESP-IDF apps keep their own files because those are Kconfig overlays — user intent, not derivable.”

src/zephyr_entry/
├── CMakeLists.txt      # find_package(Zephyr) + nano_ros_add_executable(… DEPLOY zephyr)
├── package.xml
├── prj.conf
└── prj-zenoh.conf      # no src/ — the entry TU is generated into `app`

Scaffold it with nros new entry <name> --platform zephyr, which writes the package and its [image.*] row together. The verb accepts no other platform, and says why:

`nros new entry` currently scaffolds Zephyr entries only (got --platform linux).
Every other platform builds through cargo or cmake, where the entry is
GENERATED from the image and needs no package of its own (RFC-0065 D3).

One Zephyr entry covers every Zephyr board — Zephyr owns its board abstraction, so the board comes from the image’s board key — a nano-ros board id, which the descriptor it resolves to turns into the string west build -b receives.

Set the image’s entry key when the derivation cannot answer. Either several packages claim one board (a coin flip, so nros build refuses and names the candidates; reachable for C/C++ entries, matched by their DEPLOY token) or none does, which falls back to the Bringup directory and surfaces as a conf fragment “not found” in the wrong path. A hand-written application that takes its board from nano_ros_use_board(...) in its own CMakeLists.txt is the second case, because the DEPLOY scan does not read the call (issue 1517).

Migrating off a hand-written entry is a deletion. nros build keeps src/<image_id>_entry/ when it carries a Cargo.toml or CMakeLists.txt; remove the directory and the next build generates its replacement. Move the board / launch / RMW / panic facts to the [image.*] row and the RTOS overlays to the Bringup pkg’s boards/<board>/ first.

Workspace shape

my_ws/
├── .colcon_workspace   # tracked marker; there is no root Cargo.toml / CMakeLists.txt
└── src/
    ├── talker_pkg/         # Node pkg (lib, nros::node!)
    ├── listener_pkg/       # Node pkg
    └── demo_bringup/       # Bringup pkg (declarative; system.toml carries [image.*])

nros sync writes the generated message crates and the per-image build settings; nros build <image> then generates the entry and its build root under build/ and runs the platform’s own tool. nros plan takes the sole bringup when there is one, or you name it: nros plan demo_bringup.

examples/workspaces/{c,cpp,rust,mixed}/ are the four canonical workspaces — each is exactly this shape, plus one zephyr_entry for the Zephyr images.

Single-package convenience

For tiny fixtures, host-side dev loops, and the copy-out examples under examples/<platform>/<lang>/, one package is both the node and the boot point. There is no bringup package — but the declaration is the same file, written beside the manifest (RFC-0098 D3), and src/main.rs collapses to one line:

# system.toml, beside Cargo.toml
[system]
name = "native_talker"
rmw = "zenoh"
domain_id = 0

[[component]]
pkg = "native_talker"
class = "native_rs_talker::Talker"
name = "talker"

[image.linux]
board = "linux"

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

The macro reads the board from that [image.*] row, 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.

Switching board here is the same one-line edit it is in a workspace, provided the package depends on its generated selection package instead of a board crate: <pkg>_nros_selection = { path = "build/nros/selection" }, which nros sync / nros build write for the image’s board (RFC-0098 D6) and nros::main! reaches the board through. The in-tree bare-metal, FreeRTOS, NuttX, ThreadX-Linux, RTIC and native examples do (a native example declares one image per RMW and ROS edition). A package that still names its board crate in [dependencies] has to move that line with [image.*] board; nros sync refuses the mismatch, naming both crates. See issue 1305.

Build it the same two ways a workspace is built:

nros sync            # generated/ message crates + build/<image>/nros-cargo.toml
nros build           # or: nros build <image-id>

The binary lands at build/<image-id>/target/[<triple>/]<profile>/<bin>. To drive cargo yourself, sync first and pass the generated settings file — and run cargo from the directory above the package, because until phase-445 W6 deletes the leaf’s own .cargo/ directory cargo would read it a second time and join the two sets of link flags:

cd <leaf-parent>
cargo build --manifest-path <leaf>/Cargo.toml \
            --config <leaf>/build/<image-id>/nros-cargo.toml

Once W6 lands, the working directory stops mattering. cargo run through the same file works for a QEMU board — the board’s runner is in the generated file.

A single-package C or C++ leaf is simpler still: its own CMake is unchanged, and it needs no sync, because its message bindings are a CMake-time output.

cd <leaf>
cmake -B build -Dnano_ros_ROOT="$(nros sdk-root)"
cmake --build build

What changed for it is where the facts come from: the board, RMW, domain and network identity are in system.toml, not in a package.xml <nano_ros …/> tuple and not on the cmake command line. nros build in the leaf runs the same pair into build/<image>/cmake, with the board’s toolchain file (issue 1296).

This is a project shape, not a workspace shortcut: one system.toml, one package, and that is what makes a copy-out example copy out (RFC-0026). Two or more nodes means a workspace with a Bringup pkg.

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)
• ESP32-C3: ESP32 (esp-hal) — bare-metal. The ESP-IDF component shell is retired
• 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 mps2-an385-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 mps2-an385-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/mps2-an385-freertos/<lang>/<example>/.

examples/mps2-an385-freertos/
├── rust/talker/             # Cargo package
│   ├── system.toml                 # WHAT this deploys to — the one file you edit
│   ├── Cargo.toml                  # Rust deps only; nothing here names a board
│   ├── package.xml
│   ├── generated/                  # generated message bindings (gitignored)
│   ├── build/                      # everything `nros sync` generates (gitignored)
│   └── src/lib.rs                  # the component class; nros::main! generates the entry
├── c/talker/                 # CMake project, add_subdirectory consumption
│   ├── system.toml                 # the same file, same schema
│   ├── CMakeLists.txt              # targets only
│   ├── package.xml
│   └── src/Talker.c
└── cpp/talker/               # CMake C++14 project
    ├── system.toml
    ├── CMakeLists.txt
    ├── package.xml
    └── src/Talker.cpp

All three languages state their deployment in the same system.toml, and nothing else does. The Rust leaf has no .cargo/ to edit — the thumbv7m-none-eabi triple, the -Tmps2_an385.ld --nmagic --gc-sections link group, the QEMU runner and the [patch.crates-io] rows all come from the board and are written by nros sync into build/mps2-an385-freertos/nros-cargo.toml (RFC-0098). The C / C++ leaves have no <nano_ros deploy=… board=… rmw=…/> tuple in their package.xml: find_package(nano_ros) reads system.toml instead, and derives the platform from the board.

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.

Configure

Board, RMW, domain and network identity are declared in system.toml and baked at compile time — there is no config file on the device. Verbatim from the in-tree examples/mps2-an385-freertos/rust/talker/system.toml:

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

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

[image.mps2-an385-freertos]
board = "freertos"
locator = "tcp/10.0.2.2:7800"
net = { eth0 = { network = "qemu", host = 15 } }

The C and C++ leaves carry the same file, in the same schema — only the names and the locator differ. Nothing about the deployment lives in Cargo.toml, in CMakeLists.txt, or in the package.xml <export> block any more.

For a C or C++ leaf, switching board really is editing [image.<id>] board (a cross build still passes its own -DCMAKE_TOOLCHAIN_FILE). The Rust leaf switches on the same one line: it names no board crate, only freertos_rs_talker_nros_selection = { path = "build/nros/selection" }, a package nros sync and nros build generate for the image’s board (with nros-board-mps2-an385-freertos, its RMW and nros-platform’s FreeRTOS feature). Its image also states panic = "platform", as its main.rs does, so that package does not add the board’s own panic handler. See issue 1305.

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: read your image’s own locator. The shipped Rust talker dials host port 7800; the C and C++ talkers declare a [system] locator of their own.

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 build/<image>/nros-cargo.toml, which
# carries this board's triple, link group and [patch.crates-io] table
# (RFC-0098 D1). Without it cargo builds for the host, or fails while
# PARSING the manifest with an error that never names sync (see below).
cd examples/mps2-an385-freertos/rust/talker
nros sync
nros build          # or: cargo build --config build/<image>/nros-cargo.toml

# C / C++ — the leaf's own CMake, with the cross-toolchain file (the `nros`
# CLI on PATH auto-resolves the codegen tool — no `-D_NANO_ROS_CODEGEN_TOOL=`
# needed, and no `-DNROS_BOARD=` / `-DNROS_RMW=`: both come from
# system.toml). The toolchain file path is relative to the nano-ros SDK root,
# which `nros sdk-root` prints:
toolchain="$(nros sdk-root)/cmake/toolchain/arm-freertos-armcm3.cmake"
cd examples/mps2-an385-freertos/c/talker
cmake -B build -DCMAKE_TOOLCHAIN_FILE="$toolchain" \
              -Dnano_ros_ROOT="$(nros sdk-root)" \
              -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); the ELF lands at build/mps2-an385-freertos/target/thumbv7m-none-eabi/debug/talker. The C / C++ build also compiles FreeRTOS kernel + lwIP — first run ~3 min.

Driving cargo yourself (an IDE, a CI step, --release) is supported: run nros sync first, then point cargo at the generated settings file. Run it from the directory above the package, so the package’s own .cargo/ is not read a second time — phase-445 W6 deletes that directory, after which the working directory stops mattering:

cd examples/mps2-an385-freertos/rust
cargo build --manifest-path talker/Cargo.toml \
            --config talker/build/mps2-an385-freertos/nros-cargo.toml

If you skipped nros sync, the Rust build stops at its preflight with one line naming what is missing and telling you to run sync in that directory — not with a cargo error four frames down. The single-package C / C++ builds above do not need sync at all: their message bindings are a CMake-time output. 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 7800 —
#    the locator the Rust example bakes from its system.toml
#    ([image.mps2-an385-freertos] locator, shown above).
#    Slirp forwards guest 10.0.2.2:<p> → host:<p>.
ZENOH_CONFIG_OVERRIDE='listen/endpoints=["tcp/127.0.0.1:7800"];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 + Slirp wiring the example expects — the board's own cargo
#    runner is bare `-kernel`, so booting through it gives you QEMU
#    without networking:
cd examples/mps2-an385-freertos/rust/talker
qemu-system-arm -cpu cortex-m3 -machine mps2-an385 -nographic \
    -icount shift=auto \
    -semihosting-config enable=on,target=native \
    -kernel build/mps2-an385-freertos/target/thumbv7m-none-eabi/debug/talker \
    -nic user,model=lan9118

# 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 — the locator in its system.toml (7800 for the Rust talker; Slirp forwards 10.0.2.2:7800 → host:7800). 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/mps2-an385-freertos/rust/talker/
• C: examples/mps2-an385-freertos/c/talker/
• C++: examples/mps2-an385-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, NuttX, ESP32-C3, 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
        ├── system.toml                # nano-ros config: RMW, endpoint, knobs
        ├── prj.conf                   # Zephyr's own Kconfig (+ CONFIG_NROS=y)
        ├── 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(NROS_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 publisher on `/chatter` + a timer that
// publishes an Int32 counter each tick, with the C API. `RCLC_C_COMPONENT`
// emits the C-ABI factory/configure the Zephyr typed Entry carrier calls.
#include <stddef.h>
#include <stdint.h>
#include <stdio.h>

#include <rclc/rclc.h>
#include <std_msgs/msg/int32.h>

typedef struct {
    rcl_publisher_t pub;
    rcl_timer_t timer;
    int32_t count;
} talker_t;

static void on_tick(rcl_timer_t* timer, void* ctx) {
    (void)timer;
    talker_t* self = (talker_t*)ctx;
    std_msgs__msg__Int32 msg = {.data = self->count};
    if (rcl_publish(&self->pub, &msg, NULL) == RCL_RET_OK) {
        printf("Published: %d\n", (int)self->count);
    }
    self->count++;
}

static rcl_ret_t talker_configure(rcl_node_t* node, rclc_executor_t* executor, talker_t* self) {
    self->count = 0;
    self->pub = rcl_get_zero_initialized_publisher();
    rcl_ret_t rc = rclc_publisher_init_default(
        &self->pub, node, ROSIDL_GET_MSG_TYPE_SUPPORT(std_msgs, msg, Int32), "/chatter");
    if (rc != RCL_RET_OK) {
        return rc;
    }
    self->timer = rcl_get_zero_initialized_timer();
    rc = rclc_timer_init_with_context(&self->timer, 500000000ULL, on_tick, self);
    if (rc != RCL_RET_OK) {
        return rc;
    }
    return rclc_executor_add_timer(executor, &self->timer);
}

RCLC_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/ publishes std_msgs/String the same way). The component uses the C API only: configure is handed an rcl_node_t * and an rclc_executor_t * over the carrier’s own node and executor, so it shares both with a C++ component.

Its configuration is in Configure below. You do not choose the language API: the module renders it from the app, and the typed Zephyr carrier that drives this component’s configure is C++, so the nros-cpp header surface is 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.6.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, nano-ros’s half of the configuration goes in a system.toml beside the CMakeLists.txt (RFC-0098 D10, phase-481), and Zephyr’s own half in prj.conf:

# system.toml
[system]
name = "my_app"
rmw = "zenoh"
domain_id = 0

[image.zephyr]
board = "zephyr"            # the concrete board is west's `-b`
rmw = "zenoh"               # zenoh | xrce | cyclonedds
# locator = "tcp/192.0.2.10:7447"
# [image.zephyr.knobs.zenoh]
# max_publishers = 4

# prj.conf — Zephyr settings only; never a CONFIG_NROS_* knob here
CONFIG_NROS=y               # enables the module; everything else is the image's
CONFIG_NETWORKING=y
CONFIG_NET_IPV4=y
CONFIG_NET_TCP=y

The module renders the image into a Kconfig fragment merged after prj.conf: the RMW from rmw, the language API from your app, the endpoint from locator, the domain from domain_id, and every env knob (any symbol in the Kconfig reference, spelled without CONFIG_). A CONFIG_NROS_* line in prj.conf would be overridden by it, so it is at best dead. Several images in one file — one per RMW — are picked with west build … -- -DNROS_IMAGE=<id>; see Configuring an image. An app with NO system.toml gets no rendering and is configured by Kconfig defaults and the RMW snippets alone.

CONFIG_NROS=y activates the shell, which maps Kconfig values to NROS_* 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 linux 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 (its own build dir: build/<coordinate>/<bringup>__<image>_west).
./build/zephyr-zenoh/demo_bringup__zephyr_west/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 the image’s locator = "tcp/…" in system.toml 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 = "zephyr"
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 a nano-ros board id, which nano-ros resolves to the Zephyr board target. See below.
• entry names the application package. Normally leave it out: an entry declares the deploy target it serves — its own system.toml in Rust, nano_ros_add_executable(... DEPLOY zephyr) in CMakeLists.txt — and one package usually claims a given board. Set it when the derivation cannot answer, which happens two ways and says which:
  • several packages claim the board — deriving would be a coin flip, so nros build lists the candidates rather than picking one. Reachable for C/C++ entries, which are matched by their DEPLOY token;
  • none does — nros build falls back to the Bringup directory, and you see a conf fragment “not found” in a path that is not your application’s. A hand-written application that picks its board with nano_ros_use_board(...) inside its own CMakeLists.txt is this case: the DEPLOY scan does not read that call (issue 1517). Usually the better fix is to delete the application — nros build generates one and hands it the board package’s own Kconfig and devicetree overlay, which is all nano_ros_use_board added (issue 1288).

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. west nros is now the only nano-ros west extension: west fvp shared that route until RFC-0064 revision 5 retired it, since its body was environment wiring in front of the stock west build -t run. 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 names a board in nano-ros’s catalog, and the board’s descriptor states the Zephyr id west build -b receives:

# packages/boards/zephyr/nros-board.toml
names = ["zephyr"]                        # what your images say

[board.zephyr]
west_board = "native_sim/native/64"       # what west is given

So an image writes board = "zephyr", never board = "native_sim/native/64": the Zephyr spelling is the descriptor’s to state, and an image that authors it is refused with the id to write instead (issue 1519).

Nor is it 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, which is also what the shipped Zephyr descriptors do (under [board.zephyr]). Leave it out only when your board name already is the west board target and you have no other name for it.

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 and the dependency wiring for YOUR layout. From your app dir, run (after the Prerequisites nros setup, which provides the codegen toolchain + message sources):

   nros sync --nano-ros-path <path-to-your-nano-ros-module>
   

   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, …). In-tree examples commit no .cargo/config.toml at all (phase-445 W6): their equivalent is generated into build/<image>/nros-cargo.toml and is likewise repo-relative, so it is no more copyable than the old file was.

Run

# 1. Start the router (ROS's `rmw_zenohd` — nano-ros ships no router
#    of its own) on port 7447, the port your app dials by default
#    (an image with no `locator` gets "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. It is for an app with NO system.toml: with one, the image’s rmw decides and merges after the snippet, so a snippet that agrees is redundant and one that names a different RMW is refused at configure time (phase-481). 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
# (GITIGNORED, never committed — phase-445 W6) .cargo/config.toml
# includes. Zephyr is the one lane that still needs that file rather than
# build/<image>/nros-cargo.toml: west drives cargo through
# zephyr-lang-rust's rust_cargo_application, which passes no --config
# (issue 1288). 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 "$NROS_REPO_DIR"`), 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

Configuring an image: system.toml, not prj.conf

An application’s nano-ros configuration lives in ONE place, its system.toml (RFC-0098 D10, phase-481). The nano-ros Zephyr module renders the selected image into a Kconfig fragment and merges it last, after every conf file. So the prj*.conf files hold Zephyr’s own settings only (networking, POSIX, stacks, heaps) and never a CONFIG_NROS_* line: one there is either dead (the image overrides it) or a second source that can disagree with the first. A gate (check-leaf-conf-nros-knobs) refuses one in the tree.

What the module renders, and from where:

An env row with no Kconfig symbol is not lost: it reaches the image’s cargo builds as an [env] row instead (issue 1712). A row whose type does not fit its symbol, or that only exists under another RMW, is refused at configure time, naming the system.toml line.

One image per RMW

An application built for several backends states one image per RMW, and picks one at build time. From examples/zephyr/c/talker/system.toml:

[system]
name = "nros_zephyr_talker_c"
rmw = "zenoh"
domain_id = 0
default_images = ["zephyr_zenoh"]

[image.zephyr_zenoh]
board = "zephyr"
rmw = "zenoh"
conf = ["prj-zenoh.conf"]

[image.zephyr_xrce]
board = "zephyr"
rmw = "xrce"
conf = ["prj-xrce.conf"]
locator = "udp/127.0.0.1:2018"

[image.zephyr_xrce.knobs.xrce]
max_subscribers = 0
max_service_servers = 0
max_service_clients = 0

[image.zephyr_cyclonedds]
board = "zephyr"
rmw = "cyclonedds"
conf = ["prj-cyclonedds.conf"]

west build -b native_sim/native/64 ../examples/zephyr/c/talker                       # default_images: zenoh
west build -b native_sim/native/64 ../examples/zephyr/c/talker -- -DNROS_IMAGE=zephyr_xrce

-DNROS_IMAGE is a CMake cache variable like any -D: re-running west build on the same build directory WITHOUT it keeps the image it last built, exactly as -b keeps the board. Pass it every time, or use -p when switching. A name the system.toml does not declare is refused, listing the ones it does.

Precedence, last wins: the conf files, then a 4.x -S nros-<rmw> snippet, then the image’s rendering, then any -DCONFIG_… on the command line (how a test harness passes a per-run port). A snippet naming a DIFFERENT RMW than the image is refused rather than silently overridden; one that agrees is redundant. An application with no system.toml gets no rendering, so for it the snippets and Kconfig defaults still choose.

What each RMW’s Zephyr-native fragment needs

The image’s conf file carries what the backend needs from Zephyr itself:

• Zenoh (the Kconfig default): TCP and POSIX threads for zenoh-pico — CONFIG_NET_TCP=y, CONFIG_POSIX_API=y, and pthread pools big enough for it (examples/zephyr/rust/talker/prj-zenoh.conf uses CONFIG_MAX_PTHREAD_MUTEX_COUNT=64, CONFIG_MAX_PTHREAD_COND_COUNT=16).
• XRCE-DDS: CONFIG_NET_TCP=y, on top of the BSD sockets (CONFIG_NET_SOCKETS=y) every image’s shared prj.conf enables. The agent endpoint is the image’s locator.
• Cyclone DDS: brokerless RTPS, wire-compatible with stock ROS 2 (rmw_cyclonedds_cpp). Its source is C++, so CONFIG_CPP=y even for Rust callers; it needs a large stack (CONFIG_MAIN_STACK_SIZE=524288), pthread pools, and CONFIG_NET_IPV4_IGMP=y for SPDP multicast. The bool prerequisites (thread-local storage, dynamic threads, NET_TCP, …) are selected by CONFIG_NROS_RMW_CYCLONEDDS. Its ddsrt_malloc draws on the nano-ros platform heap, 1 MiB by default under Cyclone — raise it with [image.<id>.knobs.zephyr] heap_size = … on the image, not in the conf.

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

API Selection

The language API comes from the package itself — the module renders CONFIG_NROS_RUST_API, CONFIG_NROS_C_API or CONFIG_NROS_CPP_API from the package’s entry language, so you never set it. What differs is the CMakeLists.txt.

Rust

prj.conf needs Zephyr’s own Rust support (CONFIG_RUST=y, CONFIG_RUST_ALLOC=y), and 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

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. They are what the module RENDERS from system.toml, never from a conf file: a registry knob as [image.<id>.knobs.<group>] <name> ([image.zephyr.knobs.zenoh] max_publishers = 4), any other option as an image env row with the CONFIG_ dropped (env = { NROS_BOOT_REPORT = "1" }). An env row naming a registry knob is refused, naming its knobs spelling. The RMW, API, endpoint and domain rows have their own system.toml keys (table above).

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 image’s env, 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)

Every option in this table except the agent address and port is a knob-registry row: a project with a system.toml states it as [image.<id>.knobs.xrce] <name> — the option without CONFIG_NROS_XRCE_, lowercased (transport_mtu = 512, subscriber_ring_depth = 1) — not in prj.conf, where the symbol has no prompt.

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-armv7a-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-armv7a-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
├── system.toml                          # WHAT this deploys to — the one file you edit
├── package.xml
├── Cargo.toml | CMakeLists.txt          # language-toolchain facts only
├── generated/                           # generated message bindings (gitignored)
└── src/main.{rs,c,cpp}

Wire the shell into your NuttX apps tree. Two commands, both run once:

nros setup qemu-armv7a-nuttx --rmw zenoh    # toolchain + NuttX sources + SDK
# from the nano-ros checkout:
scripts/nuttx/stage-external-apps.sh "$NUTTX_APPS_DIR"

The staging script 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.

Contributors (in-tree checkout): just setup nuttx runs both of the above in one step against this repository’s own NuttX checkout.

The script stages the integration shell only. A NuttX workspace image (a bringup with several components) is not built through the apps tree: add an [image.<id>] with board = "qemu-armv7a-nuttx" to the bringup’s system.toml and run nros build — see examples/workspaces/rust [image.nuttx]. The script’s old --bringup <dir> / --image <id> flags staged a per-bringup app that could not build an image, and now refuse (issue 1883).

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.

Those Kconfig knobs govern what the integration shell compiles into libnros_c.a — NuttX’s build owns that, the way Zephyr’s Kconfig owns its lane. They are not where your application states its deployment, and the two must name the same RMW.

Your application’s deployment — board, RMW, domain id, and an optional locator — is declared in system.toml beside the package and baked at compile time. Verbatim from the in-tree examples/qemu-armv7a-nuttx/rust/talker/system.toml:

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

[[component]]
pkg = "nuttx_talker"
class = "nuttx_rs_talker::Talker"
name = "talker"

[image.qemu-armv7a-nuttx]
board = "nuttx"
locator = "tcp/10.0.2.2:8200"

The C / C++ variants carry the same file, in the same schema — their package.xml has no <nano_ros …/> tuple and their CMakeLists.txt names no board. Nor does anything here name a target triple: armv7a-nuttx-eabihf is a fact about the board, and it lives in the board descriptor. Run nros sync in the application directory after editing this file; it writes the generated message bindings and the build settings the board choice implies.

The guest network shape (eth0 10.0.2.15, Slirp gateway 10.0.2.2 — QEMU’s own network, which the board’s [board.net] network = "qemu" names) comes from the board; add a locator = "tcp/10.0.2.2:<port>" field to [image.<id>] 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

NuttX owns the build verb here — make, from the configured kernel — the way Zephyr owns west build. nros sync still runs first, in the application directory, because the generated message bindings must exist before anything compiles against them:

cd my_app
nros sync                           # bindings + settings from system.toml

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.15 (the board’s default on QEMU’s network; an image’s net address overrides it).
3. Confirm zenohd reachable; the image’s locator (or the rclc_support_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 plus kconfig-tweak. If you wire the integration shell into your own NuttX tree 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/. 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-armv7a-nuttx/rust/, examples/qemu-armv7a-nuttx/c/, examples/qemu-armv7a-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-armv7a-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-armv7a-nuttx --rmw zenoh

As a contributor, just setup nuttx remains available and now delegates to nros setup qemu-armv7a-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-armv7a-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-armv7a-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 rv-virt-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 rv-virt-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/rv-virt-threadx/ (<lang>/<example>/ under each):

examples/threadx-linux/
├── rust/talker/                 # Cargo package
│   ├── system.toml               # WHAT this deploys to — the one file you edit
│   ├── Cargo.toml                # Rust deps only; nothing here names a board
│   ├── package.xml
│   ├── generated/                # generated message bindings (gitignored)
│   ├── build/                    # everything `nros sync` generates (gitignored)
│   └── src/lib.rs                # the component class; nros::main! generates the entry
└── c/talker/                    # CMake, add_subdirectory
    ├── system.toml               # the same file, same schema
    ├── CMakeLists.txt            # targets only
    ├── package.xml
    └── src/Talker.c

examples/rv-virt-threadx/
├── rust/talker/                 # identical shape; `board = "rv-virt-threadx"`
│   └── ...
└── c/talker/
    └── ...

The two flavours differ in the board = line of their system.toml — plus, on the Rust side, how the board crate is reached. A threadx-linux Rust leaf names no board crate: it depends on a generated <pkg>_nros_selection package that nros sync writes for the image’s board (issue 1305), so its board switch is the one line. The rv-virt-threadx Rust leaves are static libraries a CMake image links, and still name nros-board-threadx-qemu-riscv64 by hand. The C leaves have no board crate and really do switch on the one line.

Everything else follows the board. threadx-linux builds for the host triple (its Rust entry is still #![no_std], issue 1759), so its board contributes no target triple; rv-virt-threadx cross-compiles, and its triple, link group and emulator all come from the board descriptor — never from a leaf. nros sync resolves the choice into build/<image-id>/nros-cargo.toml, which is what the build reads (RFC-0098).

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

Deployment is declared per flavour in system.toml and baked at compile time. Both shipped shapes, verbatim:

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

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

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

[image.threadx-linux]
board = "threadx-linux"
locator = "tcp/127.0.0.1:9000"

threadx-riscv64 — examples/rv-virt-threadx/rust/talker/system.toml adds the guest’s network identity, because it boots behind QEMU Slirp:

[image.rv-virt-threadx]
board = "rv-virt-threadx"
locator = "tcp/10.0.2.2:9400"
net = { eth0 = { network = "qemu", host = 15 } }

The C leaves carry the same file with the same keys; their CMakeLists.txt declares targets and nothing about the deployment, and their package.xml carries no <nano_ros …/> tuple. Anything the image does not state — the rest of the network shape — 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` writes the generated message bindings and
# build/threadx-linux/nros-cargo.toml from system.toml; `nros build` builds
# the image that file declares.
cd examples/threadx-linux/rust/talker
nros sync
nros build

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. The binary lands under the image’s own directory — build/threadx-linux/target/debug/talker for the hosted flavour, with the cross triple as an extra path segment for rv-virt-threadx.

Driving cargo yourself (an IDE, a CI step, --release) is supported: run nros sync first, then point cargo at the generated settings file. Run it from the directory above the package, so the package’s own .cargo/ is not read a second time — phase-445 W6 deletes that directory, after which the working directory stops mattering:

cd examples/threadx-linux/rust
cargo build --manifest-path talker/Cargo.toml \
            --config talker/build/threadx-linux/nros-cargo.toml

Skipping nros sync is not a mysterious failure: nros build stops at its preflight with one line naming what is missing and telling you to run sync in that directory. 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 `locator` the talker bakes from
# `[image.threadx-linux]`. 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 && nros build
./build/threadx-linux/target/debug/talker
# 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 &

# Build it the same way (`system.toml` names `board = "rv-virt-threadx"`,
# so the riscv64 triple and link group come from the board):
cd examples/rv-virt-threadx/rust/talker && nros sync && nros build

# 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 build/rv-virt-threadx/target/riscv64gc-unknown-none-elf/debug/talker \
    -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 starting the binary on a warm cache; a cold first nros build compiles 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 image’s 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/rv-virt-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) — select it with [system] rmw = "cyclonedds" in system.toml and re-run nros sync; 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) — dormant

Dormant (issue 1525). ESP32 support is parked: the code below is kept in the tree for future use, but nothing builds, tests or provisions it — the esp32 just module is not mounted, nros setup no longer carries the ESP32 board or tools, the CI job and fixture rows are gone, and nros new --platform does not offer esp32. The rest of this page records how the path worked, for whoever revives it.

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). This is the only ESP32 path nano-ros ships: the ESP-IDF component shell was retired in phase-468 W2.

Prereqs. nros setup esp32-c3-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 esp32-c3-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/esp32-c3-baremetal/rust/talker/
├── system.toml                # WHAT this deploys to — the one file you edit
├── Cargo.toml                 # Rust deps only; nothing here names a board
├── package.xml
├── generated/                 # generated message bindings (gitignored)
├── build/                     # everything `nros sync` generates (gitignored)
└── src/                       # lib.rs component class + main.rs entry

There is no .cargo/ to edit. The riscv32imc-unknown-none-elf triple, the -Tlinkall.x link group, the [unstable] build-std that compiles core and alloc from source, ESP_LOG, the DRAM budgets and the [patch.crates-io] rows all come from the board, and nros sync writes them into build/esp32-c3-baremetal/nros-cargo.toml — a generated file the build reads with --config (RFC-0098).

Configure

The whole deployment statement is system.toml, beside the manifest, and it is 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/esp32-c3-baremetal/rust/talker/system.toml:

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

[[component]]
pkg = "esp32_qemu_talker"
class = "esp32_qemu_talker::Talker"
name = "talker"
entities = ["publisher:std_msgs/msg/String:/chatter", "timer"]

[image.esp32-c3-baremetal]
board = "esp32-c3-baremetal"
net = { eth0 = { network = "qemu", host = 50 } }
locator = "tcp/10.0.2.2:9800"

The entities line is this board’s one extra obligation. Pool sizes are normally probed from a host build of the component, and this leaf has no host build — a foreign triple, build-std, and a board crate that only exists for the target. So the image states what the node creates, and nros sync sizes the pools from that (RFC-0098 D8). On .bss-tight ESP32-C3 that matters: the stack is whatever the linker leaves after .bss, so a pool sized for an entity this node never creates is stack it cannot use.

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 — message bindings + the generated
# build/esp32-c3-baremetal/nros-cargo.toml:
# (`nros` finds the SDK it belongs to; `--nano-ros-path <dir>` names another)
nros sync

# nros build hands cargo the generated settings file. That file asks for
# `[unstable] build-std`, so a nightly carrying `rust-src` must be the ACTIVE
# toolchain — nros build picks no channel for you. The pinned channel is
# tools/rust-toolchain.toml's; any recent nightly works:
#   rustup toolchain install nightly && rustup component add rust-src --toolchain nightly
#   rustup target add riscv32imc-unknown-none-elf --toolchain nightly
#   rustup override set nightly          # in this directory
# Release, because ESP32-C3 DRAM is tight: anything after `--` goes to cargo
# verbatim.
nros build -- --release

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

Driving cargo yourself — for an IDE or a CI step — run nros sync first, then point cargo at the same generated file. Run it from the directory above the package, so the package’s own .cargo/ is not read a second time; phase-445 W6 deletes that directory, after which the working directory stops mattering:

cd examples/esp32-c3-baremetal/rust
cargo +nightly build --release \
      --manifest-path talker/Cargo.toml \
      --config talker/build/esp32-c3-baremetal/nros-cargo.toml

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 image's `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 the image really is the C3 one — [image.<id>] board should read esp32-c3-baremetal, and the [build] target in the generated build/esp32-c3-baremetal/nros-cargo.toml should read riscv32imc-unknown-none-elf. The tutorial does not support ESP32-S3 (Xtensa) yet.
3. See Troubleshooting — First 10 Minutes.

GitHub source

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

Next

• Subscriber + service + action peer directories under the same examples/esp32-c3-baremetal/rust/.
• C / C++ apps on an ESP32 have no in-tree path today — the ESP-IDF component shell is retired, and so is the idf.py build driver. nros build says so rather than failing later (issue 1525).
• 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) — retired

The ESP-IDF integration has been removed (phase-468 W2). This page is kept so the links that point at it still resolve; the instructions it used to carry have been deleted rather than left to be followed.

What was here, and why it went

integrations/nano-ros/ was an ESP-IDF component shim, driven by a just-module of its own. Measured on 2026-09-25, before removing it:

• no workflow under .github/ built it;
• examples/fixtures.toml had no row naming it;
• it was the only one of six pure-C platform ports with neither an nros-platform.toml descriptor nor a package.xml;
• it had never been published to the Espressif Component Registry — the release doc records the publication step as not performed.

The book had nonetheless advertised it as Ready in two support tables, on the strength of a nightly lane that did not exist. That claim was the reason to look, and looking is what retired it.

What still works: ESP32 bare-metal

The ESP32 support that has a booting CI lane is unaffected, and it is a different thing one hyphen away. esp32 is the ESP32-C3 QEMU bare-metal path over esp-hal, with its own board crate, fixtures and nightly lane:

• ESP32 (esp-hal)
• examples/esp32-c3-baremetal/

If you are targeting an ESP32-C3, that is the page you want.

The idf.py build driver went too (2026-09-28)

W2 left one piece standing: nros build still had an idf.py driver, chosen for an ESP32 board whose package graph crossed languages, on the reasoning that it would hand off to a project that was now necessarily yours. RFC-0065 D3’s 2026-09-28 amendment deleted it, because it could not have worked — with the component shell gone there was nothing for your project to depend on, nothing emitted an ESP-IDF project for idf.py to find, no mechanism carried a resolved nano-ros setting into that build, and nros setup could not install ESP-IDF in the first place.

That combination now refuses, naming the four reasons, the ESP32 road that does work, and issue 1525, instead of running a tool that had no project to build.

If you need ESP-IDF

Nothing here forbids an out-of-tree ESP-IDF integration — the C API and the platform ABI are unchanged, and packages/platform/nros-platform-api/ still describes what a port must provide. What is gone is an in-tree component that nothing built and nobody could tell was unbuilt.

Issue 1525 lists what an in-tree road would have to bring back: a component, a knob carrier for that build, an nros setup entry, and a lane that builds it. That is the same bar library.json already sets for re-advertising the espidf PlatformIO framework — “re-add only alongside a real integration”.

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 mps2-an385-baremetal --rmw zenoh

One key, not two. qemu-arm-baremetal and mps2-an385 were the same entry under two spellings until phase-437 W5 collapsed them (RFC-0093: a board name states the reach of its build, and this build is true for one silicon part). Nothing extra is provisioned for physical hardware — no probe/flash tooling. For a real STM32F4 see the out-of-tree worked example.

Project layout

examples/mps2-an385-baremetal/rust/talker/
├── system.toml                # WHAT this deploys to — the one file you edit
├── Cargo.toml                 # Rust deps only; nothing here names a board
├── package.xml                # ROS-style manifest (drives codegen tooling)
├── generated/                 # generated message bindings (gitignored)
├── build/                     # everything `nros sync` generates (gitignored)
└── src/                       # lib.rs component class + main.rs entry

There is no .cargo/ to edit. The target triple, the linker script, the --gc-sections flag, the QEMU runner and the [patch.crates-io] rows that resolve nano-ros’s crates all come from the board, and nros sync writes them into build/mps2-an385-baremetal/nros-cargo.toml — a generated file nros build hands cargo with --config (RFC-0098).

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. Both are names of the same board descriptor, so you pick the entry shape in system.toml and the matching Cargo feature — never a different board crate:

The in-tree RTIC peers (listener-rtic/, service-client-rtic/, action-server-rtic/, …) differ from their direct-exec siblings in exactly those two lines. (This talker no longer writes the row at all: its generated selection package, described below, derives board-entry or rtic from the board name.)

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 stated by the board: its nros-board.toml says [board.net] network = "qemu", so Config::default() sits on QEMU’s own user-mode network (10.0.2.15/24, gateway and router 10.0.2.2) — the network every QEMU board shares. Config::qemu_slirp() is the same network at the RTIC entry’s own address (10.0.2.10, router port 7450). Either way, an image that sets its locator and its address (net = { eth0 = { network = "qemu", host = N } }) in its [image.<id>] table overrides the default — which every in-tree example does, and which you should too.

Configure

The whole deployment statement is system.toml, beside the manifest — the same schema a multi-node workspace’s bringup package uses. It is baked at compile time: nros::main!() folds the image’s network identity into a DeployOverlay the board’s boot Config applies. Verbatim from the in-tree examples/mps2-an385-baremetal/rust/talker/system.toml:

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

[[component]]
pkg = "qemu_bsp_talker"
class = "qemu_bsp_talker::Talker"
name = "talker"
dispatch = "deferred"

[image.mps2-an385-baremetal]
board = "qemu-mps2-an385"
locator = "tcp/10.0.2.2:10500"
net = { eth0 = { network = "qemu", host = 10 } }

board picks the silicon and everything that follows from it; rmw picks the backend. Everything the board implies — triple, linker script, runner, cross compiler, [patch.crates-io] — follows the board = line on the next nros sync, so no linker flag and no triple ever moves by hand.

That includes the board crate. This leaf’s Cargo.toml names no board: its image-only dependencies (the board crate with the features its entry needs, the RMW backend, the runtime and the panic handler) come from one generated path dependency,

[target.'cfg(target_os = "none")'.dependencies]
qemu_bsp_talker_nros_selection = { path = "build/nros/selection" }