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;
    node.create_timer_repeating(core::time::Duration::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.

What you get

• One node, any board. You write a node once. Moving it to another board is one line, the board = in the image’s system.toml. The target triple, linker flags, backend and pool sizes all follow from that line, so neither your code nor your build files change.
• Talk to ROS 2 as it is. Your nodes join a stock ROS 2 graph: over Zenoh with rmw_zenoh_cpp, or over plain RTPS with rmw_cyclonedds_cpp. Topics, services and actions work in both directions.
• Pick the middleware, keep the code. Zenoh (no agent), XRCE-DDS (agent, micro-ROS compatible) or Cyclone DDS (RTPS). Switching is one line in system.toml, then build again.
• Fits a microcontroller. The core is no_std, with the alloc and std features opt-in, and runs on a bare-metal Cortex-M3. Whether your image needs an allocator depends on the backend you choose: Choosing an RMW Backend says which does.
• Rust, C or C++. The core is Rust, with C and C++ APIs over it; the C API follows rclc conventions. One workspace can mix all three.
• Your ROS 2 install’s messages. Message bindings are generated from the message definitions of the ROS 2 install you build against, so the types and their hashes match your ROS 2 peers. Source ROS 2 once for a project’s first build; later builds reuse what it recorded.
• Real-time you can reason about. Fixed-size pools sized at build time, plus scheduling and safety features for RTOS targets: see Real-Time and Safety.
• Checked, not only tested. Serialization, scheduling and the safety protocol are covered by model checking and machine-checked proofs, and every example is held identical across platforms by a test.

Does it work on the board I have?

Each board’s support status, where it runs (host, emulator or hardware) and how often it is checked come from the board registry, and the book shows them on generated pages: Supported Boards lists every board, Board support levels says what each status means, and each board has its own evidence page. nros board list and nros board show <board> print the same facts from the nros you installed.

A board that is not in the registry can still run nano-ros through the customization ladder: the out-of-tree STM32F4 worked example shows the pattern, and the PX4 module template brings nano-ros into PX4 firmware as an external module (PX4; C++ only, because PX4’s uORB binding is C++-only). MPS2-AN385 bare-metal is Rust-only: the C and C++ APIs need an RTOS for libc and a heap.

The ESP32 (both the ESP-IDF component and the esp-hal bare-metal board) is retired: ESP32 — 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.

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 building again. (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

• Get Started: install, build and run your first project.
• Build a Project: workspace layout, messages, configuration, build profiles.
• Run on a Target: nros run, and each platform’s setup.
• Communicate: choosing a backend, QoS, ROS 2 interop, transports.
• Real-Time and Safety: execution model, scheduling, static memory, production readiness.
• Operate and Debug: logging, time, diagnostics.
• Concepts and Rationale: why nano-ros is shaped the way it is.
• Extending nano-ros: add a board, a platform or an RMW backend from outside the tree.
• Reference: the CLI, APIs, boards, configuration.
• Migrating: moving from an older release.

Changing nano-ros itself is a different job, with its own book: nano-ros Internals.

Choose Your Entry

This book is organized around what you are trying to do with nano-ros, not around who you are. Pick the purpose closest to yours. Each section lists the pages to read, in order.

Everyone: your first project

Every purpose starts the same way:

1. Install the nros CLI.

2. First Project scaffolds a talker for a Cortex-M3 board, runs it in QEMU and shows its messages in ROS 2:

   nros setup mps2-an385-baremetal --rmw zenoh
   nros new sensor_ws --board mps2-an385-baremetal --template talker
   cd sensor_ws
   nros run sensor_node
   

   No QEMU or ROS 2? The same chapter runs it on your Linux host.

3. Anatomy of What You Just Built explains the workspace in nano-ros’s own terms. You do not need to open the bringup package before you have seen it run.

New to ROS entirely? Two ideas carry the whole book. A node is a unit that computes, and nodes talk through named topics (publish/subscribe) and request/reply services. An RMW (“ROS MiddleWare”) backend is the transport that moves the bytes. nano-ros is a small implementation of that model for microcontrollers.

If anything goes wrong in the first steps, see Troubleshooting — First 10 Minutes.

Industrial: reproducible, auditable, offline

You build products where safety and robustness matter. You need the same inputs to give the same image, every fact on a page, and an install that runs with no network.

• What is supported, and how it is checked. Supported Boards and Board support levels are generated from the board registry. nros doctor --report prints the status of every board your bringup’s images name, as a report you can file.
• Pinning and offline builds. Pinning a version (nros pin), and Integrating into a Vendored Tree for a company tree with air-gapped CI. nros build --offline fails, naming what is missing, rather than fetching it.
• Your RTOS and your build tool. How Integration Works: your RTOS keeps its own build tool (west, make, CMake, your IDE) and nano-ros plugs into it. Build as a CMake subdirectory covers a tree with no system.toml.
• Real-time and memory bounds. Execution Model and Two-Layer API, Scheduling Models and the generated Scheduling Wiring Matrix, no_std, alloc, and std, Dispatch Strategy, and the Static Pool Inventory.
• Safety and adoption gates. Safety Protocol (E2E CRC, EN 50159 mapping) and the Production Readiness Checklist.
• Your own board or BSP. Custom Board Package, Vendor Overlay and the STM32F4 out-of-tree worked example. A board of yours lives in your tree (NROS_EXTRA_BOARD_PATH). A new platform (a new RTOS) still means changing nano-ros itself.
• Comparisons. Differences from Standard ROS 2, nano-ros vs micro-ROS, Choosing an RMW Backend and the generated Per-RMW Feature Matrix.

Field solutions: a working system per customer

You build a system for each customer, often on a board you were handed, and you need it publishing data that a ROS 2 system can see, quickly.

1. Your first project (above), on the host.
2. Your board. Find it in Supported Boards; its evidence page says where it runs and which chapter covers it. Then read your platform’s chapter (FreeRTOS, Zephyr, NuttX, ThreadX or bare-metal). Every embedded chapter has a QEMU flow that works without hardware.
3. Run it on the target. The target model and nros run for a host process or an emulator.
4. Talk to ROS 2. Choosing an RMW and ROS 2 Interoperability. Cyclone DDS talks to rmw_cyclonedds_cpp directly, with no router. Zenoh needs the ROS 2 router (rmw_zenoh_cpp) on the host.
5. Grow the system. More nodes, parameters and images: Growing your workspace, and Mixed-language workspaces for other languages. Bridging several networks: Cross-backend Bridges.
6. Coming from rclcpp or rclpy? Setup Compared to Standard ROS 2, Porting a ROS 2 C++ node, C / C++ multi-node workspaces and the Migration Guide.

Education: labs that fit a session

You teach a course or run a lab. Every seat needs the same result, the install must be short, and each lab must fit one session.

1. Install once per seat: Installation. Nothing in the first project needs ROS 2, a router or hardware.
2. The first lab is the first project (above), in C++ or, on the same page, in Rust. The output it prints is the result to check on every seat.
3. Concepts for the lecture. Anatomy, Architecture Overview and Execution Model and Two-Layer API.
4. Embedded labs without hardware. Each platform chapter runs its example under QEMU, for example FreeRTOS or bare-metal.
5. Labs that talk to ROS 2. Choosing an RMW; Cyclone DDS needs no router, which keeps a lab machine simple.

Still not sure?

Read the Introduction for the one-page overview.

Design background

• RFC-0116: adoption purposes and front doors — the three purposes this page routes by

Installation

Three steps take a bare Linux machine to one that builds nano-ros: install a few host packages, install the nros CLI, and let nros setup provision the toolchains for your board.

A release carries everything else. The nros CLI provisions toolchains, scaffolds projects, generates message bindings and drives the build. The library ships inside the release as source, and nros build compiles it into your project. There is no prebuilt library, no system-wide install, and no nano-ros clone: your project never names a path into nano-ros.

Working on nano-ros itself? That needs a checkout and its own build of the CLI; see Contributing.

Host prerequisites

The host needs only the basics: git, curl, a C toolchain, CMake, pkg-config, Python 3, zstd, and the Python packages ROS message generation uses. nros setup provides everything toolchain-shaped later.

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

Arch:

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

Fedora and Arch ship no rosidl packages, so install the Python side with pip (in a venv if your Python is externally managed):

pip install --user catkin_pkg 'empy==3.3.4' lark PyYAML

macOS is not supported. Installation Details says what each package is for.

Install the nros CLI

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

install.sh downloads the newest release for your host, checks its sha256, and installs it under ~/.nros. Add the export PATH=… line to your shell’s startup file. Check the install:

nros version        # the CLI and library versions
nros doctor         # SDK paths, toolchains, environment

Provision your board

nros setup fetches what a board needs: the cross-compiler, the emulator, the RMW host tools and the board’s SDK sources, plus a Rust toolchain if the host has none. You do not install cross-toolchains by hand.

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

For a first project on Linux, use Cyclone DDS. It runs in-process, so it needs no router and no agent:

nros setup linux --rmw cyclonedds

nros board list names every board. nros setup <board> --dry-run prints what a board pulls without fetching anything. Inside a workspace, a bare nros setup provisions every image it declares.

Do I need ROS 2 installed?

Yes, to build. nros build, nros run and nros configure generate your project’s message bindings from the message definitions of your ROS 2 install, so the types and their hashes match the ROS 2 nodes you talk to. Every talker uses std_msgs, so install ROS 2 (the book uses Humble) and source it before the first build of a project:

source /opt/ros/humble/setup.bash

That first configure records the ROS 2 prefix in the project, so later builds and runs of that project work from a shell that has not sourced ROS. Without a sourced ROS 2 and without that record, the build stops with `AMENT_PREFIX_PATH` is unset and no configure of … has recorded one to reuse; Troubleshooting has the fix.

ROS 2 also provides:

• the Zenoh router, ROS’s rmw_zenohd, which two Zenoh nodes meet through (Cyclone DDS needs no router);
• ros2 topic echo and ros2 node list, to watch your nodes;
• the existing ROS 2 graph your nodes interoperate with.

Installation Details covers the router and the XRCE agent.

Next steps

• First Project: scaffold a talker, run it in QEMU, and see it in ROS 2.
• Installation Details: other install options, provisioning in depth, pinning a project to a release, and using nano-ros from your own build.
• First Node in Rust, C or C++: a single talker on Linux.

Installation Details

Installation is the short path. This page is the rest: what each host package is for, other ways to install, provisioning in depth, ROS 2 and the RMW daemons, pinning a project to a release, and using nano-ros from a build that is not a nano-ros workspace.

Host packages

cmake builds the C/C++ quick start and every workspace root. zstd unpacks the release and the prebuilt SDK assets nros setup fetches. python3-dev is only used by a from-source build of the launch resolver, which a release ships prebuilt. The Python packages feed rosidl_adapter, the ROS message-to-IDL step the Cyclone DDS backend uses; empy must stay 3.x. On Arch, base-devel is a package group that covers pkg-config, and ca-certificates ships with the base system. Each tool’s absence produces an error naming it.

These are the only packages 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

The host platform layer is POSIX-clean, but the host board is linux, and only Linux is tested. macOS is not supported: the board’s CPU-affinity code uses cpu_set_t, which macOS’s libc does not define.

Install options

install.sh 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. It refuses an asset whose checksum it cannot verify.

curl -fsSL https://raw.githubusercontent.com/NEWSLabNTU/nano-ros/main/scripts/install.sh \
    | sh -s -- --version 0.6.0-nros4     # a specific release instead of the newest
curl -fsSL https://raw.githubusercontent.com/NEWSLabNTU/nano-ros/main/scripts/install.sh \
    | sh -s -- --dry-run                 # print what would happen, change nothing

NROS_HOME moves the install root away from ~/.nros. The repository’s GitHub Releases page lists every release.

Provisioning 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 tools and any SDK sources a board needs are resolved from the index the release pins and placed in a shared store (~/.nros/sdk). You do not install cross-toolchains by hand. It provides no zenoh router — that is ROS’s rmw_zenohd — and Cyclone DDS needs no daemon.

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 …

nros setup <board> --dry-run prints the whole plan, prebuilt vs source, without fetching anything.

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 host tools + board SDK sources (no zenoh router: that is ROS’s rmw_zenohd). --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.

Provision a whole workspace

Once you have a workspace, you do not need to name its boards. Run nros setup with no board at the workspace root (the directory that holds src/), or pass --workspace <dir>. nros setup --dry-run prints the plan without fetching anything.

For example, a Rust workspace with a Linux image and a FreeRTOS image, both on zenoh:

nros new two_ws --board linux --template talker --lang rust --rmw zenoh
cd two_ws
nros new --image freertos --board mps2-an385-freertos   # adds [image.freertos]

One nros setup provisions both boards:

nros setup

Then every image builds. The first build generates the message bindings from your ROS 2 install, so source it in that shell; the build records the prefix, and later builds of the workspace need no sourced shell:

source /opt/ros/humble/setup.bash
nros build --all

It reads every system.toml in the workspace and provisions each [image.*]‘s board and RMW in one plan. For a zenoh image it reports ROS’s rmw_zenohd: the path it found, or the apt packages that provide it. It then lists the OS packages the workspace itself names, which are its build types’ host tools (for example cmake for ament_cmake) and any <depend> that is a system key, and prints the install command. Add --sudo to run that command. --check only reports.

Every <depend> must resolve before anything is fetched. A name that is not a package in the workspace, a message package, a system key, a package your ROS install provides or a rosdep key stops nros setup. The error names the package.xml that declares it, which is the same check nros build makes.

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.

A distro cross compiler is a fallback with a floor. When the store has no pinned arm-none-eabi-gcc (or riscv-none-elf-gcc), the CMake configure uses one from PATH and says so. Below GCC 11 a C++ image is refused at configure: GCC 10’s newlib libstdc++ has no std::this_thread, which ordinary ROS 2 C++ uses — Ubuntu 22.04’s apt gcc-arm-none-eabi is 10.3. Install the pin with nros setup --tool arm-none-eabi-gcc, or point -DNROS_ARM_NONE_EABI_PREFIX=<dir>/bin/arm-none-eabi at a GCC ≥ 11. A C-only image is not refused; it gets a warning.

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 SDK 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 (see the RMW design). 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.

ROS 2 and the Zenoh router

Building, yes, once per project. Running two zenoh nodes, yes, or use Cyclone. nros build, nros run and nros configure generate the message bindings from the message definitions of the ROS 2 install you sourced, so the generated layouts and type hashes are the ones your ROS 2 peers use. A release does not fall back to a copy of its own: that would pick a ROS 2 distro for you without saying so.

Source ROS 2 before the first build, run or configure of a project:

source /opt/ros/humble/setup.bash

That configure records the prefix (AMENT_PREFIX_PATH) in the project, and every later configure of the same project reuses it, so a later shell, an IDE or a CI step that has not sourced ROS still builds. A project whose packages depend on no message package at all configures without ROS 2. With neither a sourced shell nor a record, configure stops and names the setup step; see Troubleshooting.

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 that router is rmw_zenoh_cpp/rmw_zenohd, which ships with ROS 2. nano-ros does not vendor one. So:

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

The same sourced setup is what makes the router findable. 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.

If your distro has no ROS 2 packages (Arch, for example), install ROS 2 from source or from a container image, and source its setup.bash (or your overlay’s install/setup.bash) the same way: nano-ros reads only AMENT_PREFIX_PATH, wherever the install is.

Pinning a version

A release fixes the whole surface at once: the CLI, the library source in its SDK root, and the nros-sdk-index.toml that pins every toolchain and SDK version nros setup provisions. So pinning nano-ros is pinning a release:

# install a specific release (several can sit side by side in ~/.nros/sdk/nros/):
curl -fsSL https://raw.githubusercontent.com/NEWSLabNTU/nano-ros/main/scripts/install.sh \
    | sh -s -- --version 0.6.0-nros4

# report this project's pin (nros-toolchain.toml), or move it:
nros pin
nros pin 0.6.0-nros4

The pin is a file, nros-toolchain.toml, beside your project — commit it. With one in a directory, every nros you run there (or below it) is the pinned release: the nros on PATH hands the command to the pinned one, fetching it with that release’s own install.sh the first time. A project pinned to an older release than the one you installed, from nothing:

mkdir pinned_app && cd pinned_app
printf '[toolchain]\nversion = "0.6.0-nros4"\n' > nros-toolchain.toml

Ask for the pin. The release that answers is the pinned one, fetched on first use, and it names its own manifest:

nros pin

sdk/nros/0.6.0-nros4/share/nros/manifest.toml

and everything after it builds with that release. The pinned release is older than this page, so it is driven with the scaffold spelling it shipped with, --workspace.

nros new pinned_ws --workspace
cd pinned_ws
nros setup linux --rmw cyclonedds
nros build

nros pin <version> reports the codegen delta between the two releases before it writes anything, so an upgrade that would invalidate already-generated bindings warns first; the next nros build regenerates them. After installing a newer release, re-run nros setup <board> — it reconciles the SDK store against the new index, and packages that are already current are no-ops. See versioning for how the release number is chosen.

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:

~/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 build resolves the launch files, generates what the board choice implies and the entry and build root for each [image.*] under build/, then hands off to CMake, cargo or west:

nros build                     # or: nros build linux

nros new my_robot_ws --board linux --template talker scaffolds that layout with one node package — see First Project — and nros new <pkg> --to <bringup> adds the next. 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 single node is the same shape with one node package; --lang <rust|c|cpp> picks its language (the First Node chapters). system.toml lives only in the bringup, never beside a Cargo.toml or CMakeLists.txt.

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

Pattern B: nano-ros inside an existing CMake tree

For a C/C++ project that is not a nano-ros workspace — an existing CMake tree with its own layout — the platform and backend are cache variables set before nano-ros is added, 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.

Rust-only consumers

Nothing of nano-ros is published to crates.io (decision 2026-05-14); the crates ship as source in the release’s SDK root. The full nros crate can’t be published because it depends transitively on C/C++ sources (zenoh-pico, mbedtls); nros-core isn’t carved out for crates.io either, to avoid a hybrid distribution model with version drift between a crates.io snapshot and the SDK.

So a Rust package declares registry-style names and lets the build redirect them: nros = { version = "*" } (+ msg crates), resolved into the SDK root the nros on PATH carries (--nano-ros-path names a different 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; the next nros build re-points it.

A Rust package carries no build settings of its own — no target triple, no linker flag, no patch table. Its bringup’s system.toml states the board and nros build derives the rest; 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.

Migrating from an older nano-ros

If you used nano-ros from a checkout with the old install-local recipe, see migration-install-local-removal.md for the one-page rewrite.

First Project

Support level: mps2-an385-baremetal and the Linux host. Each page states what nano-ros can show for the board (where it runs, how often, and its breadth), generated from the board support registry; Board Support Levels explains the words.

In this chapter you scaffold a talker for an Arm Cortex-M3 board, run it in QEMU, and watch its messages arrive in ROS 2. You write no code and edit no configuration to get there.

What this assumes: a Linux host with ROS 2 Humble and its Zenoh middleware (ros-humble-rmw-zenoh-cpp) installed, or the container from Installation Details, and the install done, so nros is on your PATH.

What it leaves for later: the board talks to your machine over its serial port, the way a real board’s first program does. The network comes in the board’s own chapter, Bare-metal Cortex-M3. WiFi is not covered yet: it arrives with the Zephyr 4.4 line.

Provision the board

nros setup mps2-an385-baremetal --rmw zenoh

This fetches the Arm cross-compiler, a QEMU that emulates the MPS2-AN385 board, and the Rust target. Nothing is installed system-wide.

Scaffold

nros new sensor_ws --board mps2-an385-baremetal --template talker
cd sensor_ws

That wrote two packages:

sensor_ws/
└── src/
    ├── sensor_node/            # your node: package.xml, Cargo.toml, src/lib.rs
    └── sensor_node_bringup/    # which board it runs on; you don't need to open it yet

sensor_node is the code: a talker that publishes std_msgs/String on /chatter once a second. sensor_node_bringup says what that code runs on. The scaffold filled it in, and this chapter never needs you to open it.

This is the shape of examples/mps2-an385-baremetal/rust/talker/ in the nano-ros repository, the example kept for reading beside this chapter: one node package and a bringup with no launch file of its own, because nros run generates it.

Run

Source ROS 2 first, then build and run. ROS 2 provides the router the board talks to, and its message definitions are what nros run generates the talker’s std_msgs bindings from. This first build records the ROS 2 prefix in the workspace, so a later build of it needs no sourced shell (the router still does):

source /opt/ros/humble/setup.bash
nros run sensor_node --expect 'Publishing:'

Publishing: 'Hello World: 1'
nros run: matched after

nros run does everything between your source and a running board: it builds the firmware (the first build compiles nano-ros for the Cortex-M3 and takes a few minutes; later builds take seconds), boots it in QEMU with the board’s serial port connected to a terminal device on your host, and starts the router on that device. The talker’s own output is the board’s console. With --expect, nros run stops everything and exits 0 the moment the console prints a line containing that text, and exits 1 if the board stops first, which makes it a one-line check that the whole path works.

Without --expect it keeps streaming until you press Ctrl-C, which stops QEMU and the router together. Start it that way in one terminal:

nros run sensor_node

Publishing: 'Hello World: 2'

See it in ROS 2

Leave nros run going. In a second terminal:

source /opt/ros/humble/setup.bash
export RMW_IMPLEMENTATION=rmw_zenoh_cpp
ros2 topic echo /chatter std_msgs/msg/String --qos-reliability best_effort

data: 'Hello World:

The talker publishes best-effort, and ros2 topic echo defaults to reliable, which receives nothing from it. That is why the command asks for best-effort.

Change it

Open src/sensor_node/src/lib.rs, change the "Hello World" text, and run nros run sensor_node again. It rebuilds what changed and boots the new image.

No QEMU, no router: run it on this machine

The same flow runs on your Linux host. Cyclone DDS needs no router, so nothing else has to be running. The build still generates the messages from ROS 2, so source it before the first run (later runs of host_ws need no sourced shell):

source /opt/ros/humble/setup.bash
nros setup linux --rmw cyclonedds
nros new host_ws --board linux --template talker --lang cpp --rmw cyclonedds
cd host_ws
nros run host_node --expect 'Publishing:' --timeout 120

Only the board in the scaffold line changed. The node code is the same shape, and so is every command after it.

If nothing appears

• nros run stops at once and names AMENT_PREFIX_PATH: this shell has not sourced ROS 2, and no earlier build of the workspace recorded it. Run source /opt/ros/humble/setup.bash and run again.
• nros run stops at once and names the router: it could not find the Zenoh router. Source ROS 2 in that shell (and install ros-humble-rmw-zenoh-cpp if it is missing), or point NROS_RMW_ZENOHD at an rmw_zenohd binary.
• No Publishing: line within a minute of boot: the router started but the board did not reach it. nros run names the router’s log when it stops.
• nros run lists several names and refuses: you are in a workspace with more than one thing to run. Name one of the spellings it prints.
• ros2 topic echo prints nothing: check the --qos-reliability best_effort flag and the RMW_IMPLEMENTATION line.

First 10 Minutes has the rest.

Next

• Anatomy of What You Just Built: what each package is for, and what nros run generated.
• Growing your workspace: add a second node, another board, or a launch file.
• Bare-metal Cortex-M3: the same board over its network.

Design background

The chapter follows RFC-0116 D5 and D6 and RFC-0121 D4 and D5. Its pointer to the copy-out talker follows RFC-0122 (behaviour bringups, single-node witnesses, and cadence-backed CI) D3.

Anatomy of What You Just Built

Two packages, two roles. Everything you add to this project later is another package with one of these roles, or a few more lines in the bringup. The shape never changes; it only gains packages.

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

The node package: the code

A node package is one node, as a library. It has no main() and names no board:

src/sensor_node/
├── Cargo.toml          # a library crate; dependencies only
├── package.xml         # ROS package manifest: std_msgs is declared here
└── src/lib.rs          # the Talker: a 1 s timer that publishes on /chatter

lib.rs declares what the node creates (a publisher, a timer) and what its callback does. Message types come from package.xml’s dependencies and are generated during the build; you never write them by hand.

The same node builds for any board. Nothing in this package says mps2-an385, zenoh or serial: those are the bringup’s.

The bringup package: what runs where

src/sensor_node_bringup/ holds no code, only package.xml and system.toml:

[system]
name = "sensor_node"
rmw = "zenoh"                        # which middleware
ros_edition = "humble"               # which ROS 2 your peers run
domain_id = 0

[[component]]                        # which nodes run
pkg = "sensor_node"
class = "sensor_node::Talker"
name = "sensor_node"

[image.baremetal]                    # one block per thing you deploy
board = "mps2-an385-baremetal"
locator = "serial/UART_0#baudrate=115200"

Every configuration choice lives here, never in a node package. Moving the talker to another board is a new [image.*] block; switching middleware is the rmw line. Neither touches src/sensor_node/.

The launch file: generated until you need one

ROS 2 projects describe what to start in a launch file. This bringup has no launch/ directory, so nros run generated one from the [[component]] rows, after the first build. To see it:

cat build/nros/launch/sensor_node_bringup/launch/system.launch.xml

When you need what only a launch file can say (a parameter, a remap, a launch argument), add launch/system.launch.xml to the bringup and it replaces the generated one. The file is the ROS 2 launch XML schema, so a launch file from another ROS 2 project pastes in unchanged.

The entry: the binary, also generated

There is no entry package under src/. nros run (and nros build) reads each [image.*] block and generates the entry for it under build/: a main() that constructs each component, applies the launch file’s parameters, and runs them on one executor. Running the entry is launching the system; there is no separate ros2 launch step.

What is yours and what is generated

Everything under src/ is yours to edit and commit. build/ holds everything derived: generated message code, the launch file, the resolved system and the entry. Nothing in build/ is committed; if you can regenerate it, it does not belong in git.

Next

• Your own message package
• Growing your workspace: a second node, a second board, a launch file.
• First Node in C or C++: the same node package in another language.

Design background

RFC-0121 D1 to D3.

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. Rather not run a router? Use --rmw cyclonedds instead: it needs no router at all (see Choosing an RMW). Either way the build generates its messages from your ROS 2 install, so you need ROS 2 sourced for the first build.

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

Prereqs

The nros CLI on PATH (Installation — install.sh puts it in ~/.nros/bin), then provision the Linux host (installs the zenoh client stack into a shared store; the router itself comes from your ROS 2 install):

nros setup linux --rmw zenoh

Scaffold the talker

nros new talker_ws --board linux --template talker --lang rust --rmw zenoh
cd talker_ws

That wrote a workspace with two packages:

talker_ws/
└── src/
    ├── talker_node/            # node package: the code
    │   ├── package.xml         # ROS manifest: <depend>std_msgs</depend>
    │   ├── Cargo.toml          # a library crate; names no board and no RMW
    │   └── src/lib.rs          # the Talker: a 1 s timer publishing /chatter
    └── talker_node_bringup/    # bringup package: what runs where
        ├── package.xml
        └── system.toml         # the board, the RMW, the node it runs

The node package

talker_node is a library. It has no main(), and nothing in it names a board, an RMW or a ROS edition. src/lib.rs declares what the node creates (a publisher on /chatter, a 1 s timer) and what the timer callback does, and its last line exports the node:

#![allow(unused)]
fn main() {
nros::node!(Talker);
}

The program’s main() is generated by the build, from the bringup. That is what lets the same node package go into a Linux image today and a Cortex-M image later without a second copy. Growing your workspace walks through lib.rs line by line.

Cargo.toml holds Rust facts only: the [lib] target, the class the package registers, and its dependencies.

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

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

[dependencies]
nros = { version = "*", default-features = false, features = ["rmw-cffi", "macros"] }
std_msgs = { path = "../../generated/std_msgs", default-features = false }  # nros-managed

nano-ros crates are declared registry-style (version = "*"), but nothing of nano-ros is on crates.io: the build points them at the SDK the nros on PATH carries. The settings that takes (the [patch.crates-io] table, the target triple, linker flags) are generated under build/ from the bringup, never written by hand and never committed. No path in the package names where nano-ros lives, so the workspace copies anywhere.

Message packages are not listed by hand either: package.xml’s <depend>std_msgs</depend> is the one statement, and the build writes the matching # nros-managed row. To use another message package, add its <depend>; the next nros build adds the row.

The bringup package

talker_node_bringup/system.toml is the whole deployment statement:

[system]
name = "talker_node"
rmw = "zenoh"
ros_edition = "humble"
domain_id = 0

[[component]]
pkg = "talker_node"
class = "talker_node::Talker"
name = "talker_node"

[image.linux]
board = "linux"

The [[component]] row says which node runs; [image.linux] says it runs on this machine. The --rmw you passed to nros new lives here and nowhere else, so switching RMW or ROS edition is editing rmw or ros_edition and building again.

Native (host) images read the locator and 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.

This is the same project as examples/linux/rust/talker/ on GitHub, the copy-out example for Rust on Linux: one node package and a bringup with no launch file of its own, since the build generates it. Its bringup goes further than the scaffold, with one image per RMW and ROS edition.

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

The build generates std_msgs from your ROS 2 install, so source it first. This first build records the ROS 2 prefix in the workspace; later builds and runs of talker_ws need no sourced shell.

source /opt/ros/humble/setup.bash
nros build            # builds the image `[image.linux]` declares

nros build prepares everything first: the message bindings package.xml declares, the generated main() for [image.linux], and the cargo settings derived from board = "linux", all under build/. Then it runs cargo. There is no step to run before it; when nothing changed, the preparation costs a comparison.

First build pulls dependencies (~3 minutes). Re-builds finish in seconds. When it finishes, nros build prints where the binary landed (under build/, never beside your sources) and how to run it.

Driving cargo yourself (an IDE, a CI step, --release) is supported: nros build --dry-run prints the exact cargo line, against the generated entry under build/. Before you open the workspace in an IDE, run the preparation on its own so rust-analyzer finds the generated crates:

nros configure

What it writes under build/ is regenerated on every build; 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

Two 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

# 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 talker_ws
RUST_LOG=info nros run talker_node
# Expected output (on stderr):
#   [INFO  talker_node] Publishing: 'Hello World: 1'
#   [INFO  talker_node] Publishing: 'Hello World: 2'
#   …

nros run talker_node runs the bringup whose only node is talker_node, rebuilding first if anything changed. It keeps running until Ctrl-C.

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 the program starting (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.

Retargeting

To run the same node on a board, add an image for it to src/talker_node_bringup/system.toml, named by that board’s id (Supported Boards), and provision it:

[image.baremetal]
board = "mps2-an385-baremetal"
locator = "serial/UART_0#baudrate=115200"

nros setup mps2-an385-baremetal --rmw zenoh
nros run talker_node_bringup:baremetal

Nothing in src/talker_node/ changes: the board’s descriptor supplies the target triple, the board crate and the memory budgets. With two images the short nros run talker_node no longer picks one, so name the image you mean; nros run lists the spellings when it refuses. The platform chapters scaffold with --board <board> from the start, which writes the image for you.

Next

• Add a subscription: nros new listener_node --template listener --to talker_node_bringup from the workspace root adds a second node package and its component row (Growing your workspace).
• 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).

Design background

• RFC-0121: workspace-first project layout
• RFC-0122: behaviour bringups, single-node witnesses, and cadence-backed CI. The copy-out talker kept for each platform and language, and the language workspaces that hold the paired examples.

First Node — C (Linux)

Build, run, and verify a single nano-ros publisher node on Linux from C. The node is a C library built with CMake; the program around it is generated. Uses the Zenoh backend.

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

Prereqs

The nros CLI on PATH (Installation — install.sh puts it in ~/.nros/bin), then provision the Linux 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

Scaffold the talker

nros new c_talker_ws --board linux --template talker --lang c --rmw zenoh
cd c_talker_ws

That wrote a workspace with two packages:

c_talker_ws/
└── src/
    ├── c_talker_node/            # node package: the code
    │   ├── package.xml           # ROS manifest: <depend>std_msgs</depend>
    │   ├── CMakeLists.txt        # a library and its registration; no board facts
    │   └── src/Talker.c          # the talker: a 1 s timer publishing /chatter
    └── c_talker_node_bringup/    # bringup package: what runs where
        ├── package.xml
        └── system.toml           # the board, the RMW, the node it runs

This is the same project as examples/linux/c/talker/ on GitHub, the copy-out example for C on Linux: one node package and a bringup with no launch file of its own, since the build generates it.

The bringup package

c_talker_node_bringup/system.toml is the whole deployment statement, the same schema whatever language the node is written in:

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

[[component]]
pkg = "c_talker_node"
class = "c_talker_node::Talker"
name = "c_talker_node"

[image.linux]
board = "linux"

The [[component]] row says which node runs; [image.linux] says it runs on this machine. Nothing in the node package 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. Moving the talker to a board is another [image.<id>] block here, with no edit to src/c_talker_node/.

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 in the board network file os_config names) and they are baked at build time (see Configuration).

The node package

A C node package is a library, not a program. The scaffolded CMakeLists.txt is (comments trimmed):

cmake_minimum_required(VERSION 3.22)
project(c_talker_node VERSION 0.1.0 LANGUAGES C)

set(CMAKE_C_STANDARD 11)
set(CMAKE_C_STANDARD_REQUIRED ON)

find_package(nano_ros REQUIRED)
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_node::Talker
    EXECUTABLE c_talker_node
    SHAPE configure
    TYPED)

nano_ros_auto_add_library generates the C bindings the package declares and links nano-ros. nros_components_register_node registers the class the bringup’s [[component]] row names, the CMake spelling of ROS 2’s rclcpp_components_register_node.

There is no main(). The build generates one for each image, which opens the session and executor, creates the node, and hands both to your code. Your code is a state struct and a configure function, exported with RCLC_C_COMPONENT:

#include <stdio.h>
#include <rclc/rclc.h>
#include <std_msgs/msg/string.h>

typedef struct {
    rcl_publisher_t pub;
    rcl_timer_t timer;
    int32_t count;
    char text[32];
} talker_t;

static void on_tick(rcl_timer_t* timer, int64_t last_call_time) {
    talker_t* self = RCLC_CONTAINER_OF(timer, talker_t, timer);
    (void)last_call_time;
    self->count++;
    int n = snprintf(self->text, sizeof self->text, "Hello World: %d", (int)self->count);
    std_msgs__msg__String msg;
    msg.data.data = self->text;          // your buffer; nothing allocates
    msg.data.size = (size_t)n;
    msg.data.capacity = sizeof self->text;
    if (rcl_publish(&self->pub, &msg, NULL) == RCL_RET_OK) {
        printf("Publishing: '%s'\n", self->text);
    }
}

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, String), "/chatter");
    if (rc != RCL_RET_OK) return rc;
    self->timer = rcl_get_zero_initialized_timer();
    rc = rclc_timer_init_default(&self->timer, NULL, 1000000000ULL, on_tick);
    if (rc != RCL_RET_OK) return rc;
    return rclc_executor_add_timer(executor, &self->timer);
}

RCLC_C_COMPONENT(talker_t, talker_configure)

configure runs once at startup, on the generated entry’s own node and executor; after that the executor calls on_tick once a second. Because the entry owns startup, the same file runs on Linux and on a board whose C runtime never calls main (Zephyr, an RTOS startup task).

--template picks a different node: listener, server / client (AddTwoInts) or action-server / action-client (Fibonacci).

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 above and 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

The build generates std_msgs from your ROS 2 install, so source it first. This first build records the ROS 2 prefix in the workspace; later builds and runs of c_talker_ws need no sourced shell.

source /opt/ros/humble/setup.bash
nros build

nros build prepares the build from the bringup (the generated main() for [image.linux] and a CMake root that adds your package), configures it with the SDK root and the toolchain file the board names, and builds it. The C message bindings are generated during that CMake configure, from the package’s declared dependencies. There is no step to run before it.

When it finishes, nros build prints what it built and how to run it:

nros build: next for `c_talker_node_bringup:linux`:
  artifact: /home/you/c_talker_ws/build/posix-zenoh-linux/cmake/linux_entry
  run:
    nros run c_talker_node

Driving CMake yourself. The CMake root nros build configures is generated under build/, never at the workspace root, and nros build --dry-run prints the exact cmake lines it would run. To have that root in place without building (before opening the workspace in an IDE, or to run those lines by hand), prepare it on its own:

nros configure

For a CMake tree that is not a nano-ros workspace at all, see Build as a CMake subdirectory.

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

# 2. Run the talker:
cd c_talker_ws
nros run c_talker_node
# Expected output, once a second:
#   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 (session open + the first 1 s timer tick), the talker prints Publishing: 'Hello World: 1' on stdout — Rust + C + C++ all start the count at 1, matching the official ROS 2 demo talker. If it does not appear in 30 seconds:

1. Confirm the router is running (terminal 1). Without it, the generated entry’s session open fails at once with -4 (RCLC_RET_NOT_FOUND — connection refused) and the program stops, naming the step.
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.

Next

• Add a subscriber: from the workspace root, nros new c_listener_node --lang c --template listener --to c_talker_node_bringup adds a second node package and its component row to the bringup (Growing your workspace).
• Service / action shapes, and a workspace of several C node packages: the C language workspace, examples/workspaces/c/. The paired examples are image rows there, one bringup per behaviour (pubsub_bringup, service_bringup, action_bringup), and nros run service_bringup:linux_service_server runs one role.
• Custom .msg / .srv / .action: Message Generation
• Cross-compile for an RTOS: pick the right Embedded Starter from the next section.

Design background

• RFC-0121: workspace-first project layout
• RFC-0122: behaviour bringups, single-node witnesses, and cadence-backed CI. The copy-out talker kept for each platform and language, and the language workspaces that hold the paired examples.

First Node — C++ (Linux)

Build, run, and verify a single nano-ros publisher node on Linux from C++. The node is a C++ library built with CMake, in the ament shape; the program around it is generated. Uses the Zenoh backend.

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

Prereqs

The nros CLI on PATH (Installation — install.sh puts it in ~/.nros/bin), then provision the Linux 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

Scaffold the talker

nros new cpp_talker_ws --board linux --template talker --lang cpp --rmw zenoh
cd cpp_talker_ws

That wrote a workspace with two packages:

cpp_talker_ws/
└── src/
    ├── cpp_talker_node/            # node package: the code
    │   ├── package.xml             # ROS manifest: <depend>std_msgs</depend>
    │   ├── CMakeLists.txt          # a library and its registration; no board facts
    │   ├── include/cpp_talker_node/Talker.hpp
    │   └── src/Talker.cpp          # the talker: a 1 s timer publishing /chatter
    └── cpp_talker_node_bringup/    # bringup package: what runs where
        ├── package.xml
        └── system.toml             # the board, the RMW, the node it runs

This is the same project as examples/linux/cpp/talker/ on GitHub, the copy-out example for C++ on Linux: one node package and a bringup with no launch file of its own, since the build generates it.

cpp_talker_node_bringup/system.toml is the whole deployment statement — [system] for the RMW and domain, one [[component]] row naming the node, and one [image.<id>] per target naming its board. No line of the node package names a platform, a board or an RMW, so moving the talker to a board is another [image.<id>] block in the bringup; First Node — C shows the file in full. The package.xml <nano_ros deploy=… board=… rmw=…/> export that used to carry that tuple is retired and refused.

The node package

The CMakeLists is the ament shape you already know — this is the scaffolded file, comments trimmed (the message-package Find-stubs make find_package(std_msgs) generate bindings on the fly):

cmake_minimum_required(VERSION 3.22)
project(cpp_talker_node VERSION 0.1.0 LANGUAGES C CXX)

set(CMAKE_CXX_STANDARD 14)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

find_package(nano_ros REQUIRED)
find_package(std_msgs REQUIRED)

nano_ros_auto_add_library(talker_lib STATIC src/Talker.cpp)

nros_components_register_node(talker_lib
    PLUGIN cpp_talker_node::Talker
    EXECUTABLE cpp_talker_node
    SHAPE configure)

nros_components_register_node has rclcpp_components_register_node’s keywords: the class the bringup’s [[component]] row names, and its executable name.

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 the bringup, not CMake code and not a configure-line cache variable.

There is no main(). The node is a class with a configure(rclcpp::Node&) method, the shape of a composable node: the generated entry initialises nano-ros, creates the node, constructs your class in static storage and calls configure on it, then spins the executor.

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

namespace cpp_talker_node {

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

    void on_tick();   // bound by &Talker::on_tick, not by a name

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

}  // namespace cpp_talker_node

// src/Talker.cpp
#include "cpp_talker_node/Talker.hpp"
#include <cstdio>

namespace cpp_talker_node {

void Talker::on_tick() {
    char payload[64];
    std::snprintf(payload, sizeof payload, "Hello World: %d", ++count_);
    std_msgs::msg::String m;
    m.data = payload;
    if (pub_.publish(m).ok()) std::printf("Publishing: '%s'\n", m.data.c_str());
}

::rclcpp::Result Talker::configure(::rclcpp::Node& node) {
    ::rclcpp::Result r = node.create_publisher(pub_, "/chatter");
    if (!r.ok()) return r;
    return node.create_wall_timer<Talker, &Talker::on_tick>(timer_, 1000, this);
}

}  // namespace cpp_talker_node

The publisher and timer are typed wrappers over the C ABI, and every call returns a Result rather than throwing: every nano-ros build is -fno-exceptions. configure returns the first failure, and the generated entry halts naming the node that failed, so there is no unchecked construction to forget. Porting a ROS 2 C++ node covers the rclcpp-shaped constructors, shared_from_this() and rclcpp::TimerBase.

--template picks a different node: listener, server / client (AddTwoInts) or action-server / action-client (Fibonacci).

Configure

Three runtime knobs:

On a hosted target the generated entry takes the locator and domain from the build, then from the environment variables. An embedded image declares its locator in its own [image.<id>] table and its address in the board network file os_config names, and bakes them at build time.

Build

The build generates std_msgs from your ROS 2 install, so source it first. This first build records the ROS 2 prefix in the workspace; later builds and runs of cpp_talker_ws need no sourced shell.

source /opt/ros/humble/setup.bash
nros build

nros build prepares the build from the bringup (the generated main() for [image.linux] and a CMake root that adds your package), configures it with the SDK root and the board’s toolchain file, and builds it. The C++ message bindings are generated during that CMake configure. There is no step to run before it.

When it finishes, nros build prints what it built and how to run it:

nros build: next for `cpp_talker_node_bringup:linux`:
  artifact: /home/you/cpp_talker_ws/build/posix-zenoh-linux/cmake/linux_entry
  run:
    nros run cpp_talker_node

Driving CMake yourself. The CMake root is generated under build/, and nros build --dry-run prints the exact cmake lines it would run. To have that root in place without building (before opening the workspace in an IDE, or to run those lines by hand), prepare it on its own:

nros configure

For a CMake tree that is not a nano-ros workspace at all, see Build as a CMake subdirectory.

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

# 2. Run the talker:
cd cpp_talker_ws
nros run cpp_talker_node
# Expected output:
#   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 (session open + the first 1 s timer tick), the talker prints Publishing: 'Hello World: 1' — Rust + C

• C++ all start the count at 1, matching the official ROS 2 demo talker. If it does not appear in 30 seconds:

1. Confirm the router is running (terminal 1). Without it, the generated entry’s session open fails with -100 (TransportError) and the program stops, naming the step.
2. -3 / -100 on stderr both mean the transport did not open: check NROS_LOCATOR and the router’s port.
3. See Troubleshooting — First 10 Minutes.

Next

• Add a subscriber: from the workspace root, nros new cpp_listener_node --lang cpp --template listener --to cpp_talker_node_bringup adds a second node package and its component row (Growing your workspace).
• Services, actions and several C++ node packages in one workspace: the C++ language workspace, examples/workspaces/cpp/, where each paired example is an image row under its behaviour’s bringup (pubsub_bringup, service_bringup, action_bringup), and C / C++ multi-node workspaces.
• Custom .msg / .srv / .action: Message Generation
• Cross-compile for an RTOS: pick the right Embedded Starter from the next section.

Design background

• RFC-0121: workspace-first project layout
• RFC-0122: behaviour bringups, single-node witnesses, and cadence-backed CI. The copy-out talker kept for each platform and language, and the language workspaces that hold the paired examples.

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 build tools run: even the rclcpp-shaped consumer below compiles against nano-ros’s own rclcpp CMake package. nros build still reads message definitions from your ROS 2 install, so source it for the first build (below).
• 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()

Build it with nros build

There is no nano-ros-specific file to add: a workspace has no root build file. With no bringup, nros build builds it the way colcon build does — every package it finds by its package.xml, in <depend> order, each in its own build/<pkg>/. For my_app it generates the CMake root that used to be hand-written (nano-ros, NROS_INTERFACE_SEARCH_PATH at ./src/, the rclcpp / ament surface); my_msgs is not built on its own — its bindings are generated into the package that uses it.

The first nros build of the workspace needs ROS 2 sourced: it generates the bindings against your ROS 2 install’s message definitions, and refuses without one. It records the prefix, so later builds need no sourced shell.

source /opt/ros/humble/setup.bash
nros build
./build/my_app/cmake/pkg/my_app/my_app

In a workspace that also has a bringup (what nros new <ws> --board <board> writes), the same nros build builds my_msgs into whichever image’s packages depend on it.

Escape hatch — a hand-written umbrella. For a CMake tree that is not a nano-ros workspace, one top-level CMakeLists.txt pulls nano-ros in as a subdirectory, naming the SDK root on the configure line (Build as a CMake subdirectory has the mechanism):

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

# Pull nano-ros — the installed SDK root, passed as -DNANO_ROS_SDK=….
set(NROS_PLATFORM posix)
set(NROS_RMW "zenoh" CACHE STRING "Active RMW.")
set(NROS_RMW "${NROS_RMW}")
add_subdirectory("${NANO_ROS_SDK}" 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("${NANO_ROS_SDK}/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)

cmake -B build -S . -DNANO_ROS_SDK="$(nros locate nano-ros)"
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 run nros build from the workspace root — that is the whole change. The package index finds src/my_msgs/ by its package.xml, generates the generated/my_msgs crate, and writes the manifest row itself (my_msgs = { path = "../../generated/my_msgs", default-features = false } # nros-managed). 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: Add a node package.

Troubleshooting — First 10 Minutes

Every first build of a project needs ROS 2 sourced, because the messages are generated from it (A10). The First Project runs a talker in QEMU over Zenoh, so it also needs ROS 2 for the router; its Linux section runs on Cyclone DDS, where no router exists, so “no output” there is never a router problem. The First Node pages run on Linux over Zenoh and assume nros setup linux --rmw zenoh has run and the ROS 2 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. Cargo cannot find nros

error: no matching package named `nros` found

A node package’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 the nano-ros SDK is GENERATED, under build/, and nros build hands it to cargo with --config. nros build and nros run write it themselves, so this error means cargo ran without it: a plain cargo build in a package, or an IDE that opened the workspace before anything was generated. Fix:

cd <the workspace root>
nros build        # or, to prepare without building: nros configure

nros configure writes the generated settings without building; nros build --dry-run prints the cargo line that uses them. Either is also what ties a copied-out workspace to an SDK (the nros binary’s own, or the one --nano-ros-path names), and runs again by itself on the next build after you move 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 CLI not found

nros (codegen tool) not found on PATH or in packages/cli/target/release/
or ${NROS_HOME:-~/.nros}/bin. …

(The rest of the message names how a contributor builds the CLI from a checkout; as a user you install it instead.)

The nros binary is not installed, or not on PATH. Install a release and put ~/.nros/bin on PATH:

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

If ~/.nros/bin/nros exists but PATH doesn’t see it — that’s the [PATH] doctor status (D2 below), not this branch.

The nros binary ships the codegen — there is no separate nros-codegen build step. CMake projects auto-resolve nros from PATH / ${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 nros-cargo.toml under build/, which nros build writes from the board your bringup’s 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 bringup’s system.toml.

[system]
rmw = "cyclonedds"

cd my_ws                          # a workspace with C or C++ node packages
nros build

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.

A Rust node package does not take --features rmw-cyclonedds at all: its RMW is its image’s. A bringup that declares a linux_cyclonedds image (as examples/linux/rust/talker does) builds it with nros build linux_cyclonedds — 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 bringup 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 (mps2-an385-baremetal, baremetal and bare-metal all name one descriptor).

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

this workspace declares no `[image.*]`. An image is the buildable unit: add `[image.<id>] board = "<board>"` to system.toml.
…/system.toml: names no board; add `[image.<id>] board = "<board>"`

The first means no bringup in the workspace has a system.toml with an image, so there is nothing for nros build to plan. The second means the file is there and its [image.<id>] table has no board key.

A8. system.toml next to code

nros build refuses a system.toml in a directory that also holds a Cargo.toml or a CMakeLists.txt. A system.toml belongs to a bringup package, never to the package with the code, because it says where that code runs and the code itself must not.

To fix it, give the configuration its own package:

1. Make src/<pkg>_bringup/ beside your node package, with a package.xml.
2. Move system.toml into it.
3. Delete any main that only starts the node; the entry is generated.

nros new <ws> --board <board> --template talker writes this shape, so a scaffolded project never hits it.

A9. 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; “direnv allow” and “build via just” in it refer to a contributor checkout.) nros build passes these to cargo from the board’s settings, so a build driven by nros build — or by cargo with the generated --config file — does not hit it. If a cargo command you drive yourself does, you skipped the --config build/<image>/nros-cargo.toml argument.

A10. AMENT_PREFIX_PATH is unset

nros build, nros run or nros configure stops before building anything:

Error: configure: `AMENT_PREFIX_PATH` is unset and no configure of `/home/you/sensor_ws` has recorded one to reuse. Run the setup step once from a shell that has ROS 2: `source /opt/ros/<distro>/setup.bash` (or your overlay's `install/setup.bash`), then `nros configure`; later runs without a sourced shell reuse what it records.

The project has messages to generate (every talker uses std_msgs), and nano-ros generates them from the message definitions of your ROS 2 install, so the types and their hashes match your ROS 2 peers. This shell has not sourced ROS 2, and no earlier configure of the project ran in one that had. It happens on every board and every RMW, Linux and Cyclone DDS included.

Source ROS 2 once, in this shell, and run the same command again:

source /opt/ros/humble/setup.bash   # or your overlay's install/setup.bash
nros build

That configure records the prefix in the project. Later builds and runs of the same project reuse it, from any shell, an IDE or a CI step. A new project records its own, so its first build needs a sourced shell again.

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 reports this distinct from [MISSING] when the binary is installed at ${NROS_HOME:-~/.nros}/bin/nros but PATH doesn’t see it. Put the directory on PATH (and in your shell’s startup file):

export PATH="$HOME/.nros/bin:$PATH"

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

Building and Configuring

nros build is the recommended way to build an image: it prepares everything the build needs (generated messages, the resolved system, the image’s build settings) and then runs the host build tool, as cargo build does. A project that stays in west, CMake, NuttX make or an IDE runs the preparation step, nros configure, from that tool’s own configure step instead.

This page is coming soon.

Design background

• RFC-0120: one resolver for every build road

Growing your workspace

First Project left you with a workspace of two packages: a node and the bringup that says what it runs on. A project grows from there by one path, in four steps, and you take only the ones you need:

1. add a node package;
2. add its component row to the bringup;
3. add launch/ when you need a launch argument, a remap or a parameter;
4. add an image for another board.

Each step adds a package or a few lines to the bringup. The shape of the workspace never changes, so nothing you did in an earlier step has to be undone.

Where you start

sensor_ws/
└── src/
    ├── sensor_node/            # node package: package.xml, Cargo.toml (a library), src/lib.rs
    └── sensor_node_bringup/    # package.xml and system.toml; no launch/ yet

The two roles, and what each one never holds:

There is no third package to write. For each [image.*] block in the bringup’s system.toml, nros build and nros run generate the program’s entry (its main()) under build/. A workspace has no root Cargo.toml or CMakeLists.txt either: like a colcon workspace, it is a directory of packages.

system.toml lives only in a bringup package. A system.toml beside a Cargo.toml or CMakeLists.txt is refused, and the message says where to move it.

1. Add a node package

From the workspace root:

nros new monitor_node --template listener --to sensor_node_bringup

Inside a workspace, nros new adds a package under src/ instead of writing a new workspace. --to also adds the node’s component row to the bringup (step 2). Pass --lang c or --lang cpp for a C or C++ node; the rest of this page is the same in every language.

A node package is a library with three files:

src/monitor_node/
├── package.xml          # ROS 2 manifest: one <depend> per message package
├── Cargo.toml           # a [lib] crate and its dependencies, nothing else
└── src/lib.rs           # the node; its last line is nros::node!(Listener);

It has no fn main() and names no board, RMW or board crate. That is what lets one node package go into a Cortex-M image and a Linux image unchanged: the difference between them is an [image.*] block, not a second copy of the node.

The manifests

package.xml is a standard ROS 2 manifest. Each message package the node uses is one <depend>:

<depend>std_msgs</depend>

That line is all you write for a message package. The build turns each <depend> on a message package into a dependency row in Cargo.toml, tagged # nros-managed, pointing at the crate it generates under generated/. Removing the <depend> removes the row. A row without the tag is yours and is never touched, so to override a generated row, delete its tag.

Cargo.toml registers the node class the package exports:

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

[package.metadata.nros.node]
class = "monitor_node::Listener"
name = "monitor_node"

[dependencies]
nros = { version = "*", default-features = false, features = [
    "alloc",
    "rmw-cffi", "macros"] }
std_msgs = { path = "../../generated/std_msgs", default-features = false }  # nros-managed

This registration is the Rust spelling of nros_components_register_node(... PLUGIN pkg::Class ...) in a C or C++ package’s CMakeLists.txt. A package registers its class once, however many bringups run it. Which bringup runs it is the component row’s business (step 2). nros is never fetched from a registry: the build points it at your installed nano-ros, so no path in the manifest names where nano-ros lives and the package copies anywhere.

src/lib.rs

A Rust node implements Component (what the node creates, declared once at startup) and ExecutableNode (what each callback does), then exports both with nros::node!. The essential shape, from examples/workspaces/rust/src/talker_pkg/src/lib.rs:

#![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";

    // Per-instance slots, 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 node; this is the last line
}

• register declares; it does not run. It is called once at startup to declare publishers, subscriptions, timers and which callback publishes what. No message flows here.
• on_callback is the body. The image’s executor calls it each time a callback fires; state is the node’s own mutable storage.
• The node is the same type everywhere. ctx.create_node(...) returns the nros::Node a standalone program gets, with rclrs’s methods (create_publisher, create_subscription, timers, logger(), the graph queries). use nros::DeclarativeNode; adds the constructors that bind a callback by name, which is what lets the board run callbacks from its own tasks and lets the build measure the node without running it.
• ENTITY_BOUNDS is static RAM. nros::node! emits a static sized from it, and a publisher slot carries a loan arena. The default (8 of each kind) measured 50,824 bytes of .bss for a one-service node, against 568 bytes when the node declared what it creates. Count the five kinds in your register(); timers and subscriptions need no slot here. Declaring fewer than register() creates is an error at boot, never a silent drop, so the exact number is safe.
• Timers. In a timer callback, ctx.timer_info() returns the activation’s expected_call_time and actual_call_time (lateness_ns() is their difference). create_timer_for_callback_name_with_autostart(name, period, clock, false) declares a stopped timer; any callback starts it with ctx.reset_timer(nros::EntityId::new("on_tick")) and stops it with ctx.cancel_timer(..). To control timers by id, add .with_timers(n) to ENTITY_BOUNDS (16 bytes a timer).

Calling a service from a node

A node cannot make a blocking service or action call from on_callback: the executor is mid-dispatch there, and the call would deadlock it. Client calls go in ExecutableNode::tick, which the executor runs once per spin between callbacks. Arm the call in the callback and make it in tick:

#![allow(unused)]
fn main() {
fn on_callback(state: &mut State, cb: Callback<'_>, ctx: &mut CallbackCtx<'_>) {
    state.want_call = true;          // decide; do not call here
}

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 is safe here
    }
}
}

A service server needs no such split: requests arrive in on_callback like any other callback. In C++, rclcpp::bind_service<Svc, T, &T::method>(node, "/add_two_ints", this) binds a typed member that takes the generated Svc::Request and returns Svc::Response.

2. Add a component row

--to sensor_node_bringup added this to src/sensor_node_bringup/system.toml, beside the row the scaffold wrote for sensor_node:

[[component]]
pkg = "monitor_node"
class = "monitor_node::Listener"
name = "monitor_node"

It also added <exec_depend>monitor_node</exec_depend> to the bringup’s package.xml. To add a row by hand (for a node package you copied in), write both.

Run the system. The workspace’s first build, in First Project, recorded your ROS 2 prefix, so a shell that has not sourced ROS 2 builds it too; a workspace you start fresh needs ROS 2 sourced for its first build, because the messages are generated from it:

source /opt/ros/humble/setup.bash   # only needed for a fresh workspace's first build
nros run

With nothing named, nros run runs the workspace’s only image, which now now holds both nodes in one program. nros run sensor_node no longer works. That spelling means “the bringup whose only node is sensor_node”, and this bringup now has two, so it refuses and prints the spellings that would resolve, here sensor_node_bringup:baremetal.

The bringup still has no launch/, so the build generates its launch file from the two rows. After a build, it is at:

cat build/nros/launch/sensor_node_bringup/launch/system.launch.xml

Before a build, two checks catch most mistakes in a bringup (a [[component]] row naming a package or class that does not exist, a stray build file in the bringup):

nros check --bringup src/sensor_node_bringup
nros check --workspace .

3. Add a launch file when you need one

The generated launch file starts every component with its default name and nothing else. When you need a launch argument, a remap, a namespace or a parameter, the bringup gets a launch/ directory. Start from the generated file, so that adding it changes nothing until you edit it:

mkdir -p src/sensor_node_bringup/launch
cp build/nros/launch/sensor_node_bringup/launch/system.launch.xml \
   src/sensor_node_bringup/launch/system.launch.xml

From then on launch/system.launch.xml is used instead of the generated one. Deleting launch/ goes back to generation.

Keep each <node>’s pkg and exec as the generated file wrote them; the examples below write exec="…" for that value.

The file is the ROS 2 launch XML schema, read with the same parser, so a launch file from another ROS 2 project pastes in. For example, a launch argument that moves both nodes to another topic:

<launch>
  <arg name="topic" default="/chatter"/>

  <node pkg="sensor_node" exec="…" name="sensor_node">
    <remap from="/chatter" to="$(var topic)"/>
  </node>
  <node pkg="monitor_node" exec="…" name="monitor_node">
    <remap from="/chatter" to="$(var topic)"/>
  </node>
</launch>

Substitutions: $(var <arg>) expands a launch argument, $(find <pkg>) a package’s path, $(env <name>) an environment variable.

There is no ros2 launch step. The launch file is resolved when the image is built, and its result is compiled into the program. An image binds launch arguments, and can name another launch file in the same bringup:

[image.baremetal]
board = "mps2-an385-baremetal"
args = { topic = "/sensor" }

[image.baremetal_sim]
board = "mps2-an385-baremetal"
launch = "sim.launch.xml"

Parameters

<param from="…"/> takes a standard ROS parameter file, relative to the launch file:

# launch/sensor.param.yaml
/**:                      # every node
  ros__parameters:
    use_sim_time: false
sensor_node:              # this node only
  ros__parameters:
    rate_hz: 25
    limits:
      max_accel: 1.5      # reaches the node as `limits.max_accel`

<node pkg="sensor_node" exec="…" name="sensor_node">
  <param from="sensor.param.yaml"/>
  <param name="rate_hz" value="50"/>   <!-- wins over the file -->
</node>

Precedence is ROS’s: the /** block, then the node’s own block (keyed sensor_node, /ns/sensor_node or /**/sensor_node), then inline <param name= value=>. The values are baked into the program at build time, so an embedded board reads no file at run time; editing the YAML rebuilds. A from= naming a missing file is a build error.

Two capabilities in [system] features decide what the image does with them:

params suits a small board whose nodes only read their configuration: each of the six services costs a queryable per node. What it gives up is ros2 param get|set|list|describe|dump and the use_sim_time switch.

4. Add an image

An image is one program: the bringup’s nodes, built for one board with one RMW. It is a block in system.toml, not a package. Your bringup has one, written by the scaffold:

[image.baremetal]
board   = "mps2-an385-baremetal"
locator = "serial/UART_0#baudrate=115200"

Running the same two nodes on your Linux machine is one more block:

[image.linux]
board = "linux"
rmw   = "cyclonedds"       # this image only; needs no router on a host

nros run linux

Nothing in either node package changes. The board’s descriptor supplies the target triple, linker flags, cross compiler and memory budgets, so retargeting is the board line and nothing else.

[image_defaults] holds what every image shares, so eight images do not repeat their RMW eight times. A specific block’s values replace it; args merge, and os_config and features add up:

[image_defaults]
rmw = "zenoh"

The RMW, like the board, is chosen at build time; embedded targets have no RMW_IMPLEMENTATION switch. On a Linux image, ROS_DOMAIN_ID and NROS_LOCATOR still work at run time; an embedded image bakes the values from its block. See Configuration.

Naming what to run

With two images, nros run alone refuses and lists them. The target argument of nros run, nros build and nros flash accepts, in this order:

Anything else refuses and lists the <bringup>:<image> spellings that would resolve; a shortcut never picks one of several. --why says which row resolved. To make a bare nros build build a chosen set, declare it:

[system]
default_images = ["linux"]

Zephyr images

A Zephyr image also carries Zephyr’s own configuration (prj.conf, overlays), which nothing can derive. It lives in the bringup, one directory per board, and the image names the fragments it adds:

src/sensor_node_bringup/boards/native_sim_native_64/
├── prj.conf
└── prj-zenoh.conf               # named by [image.<id>] os_config

nros build writes the Zephyr application itself under build/ and runs west build on it. The board id is still nano-ros’s (zephyr), never Zephyr’s spelling. Configuring an image has the rest. A Zephyr application that keeps its own CMakeLists.txt and prj.conf and is built with plain west build is not a workspace image; it has its own chapter.

What nros build generates

Everything generated lands under build/, and none of it is yours to edit or commit:

• the generated launch file of each bringup without launch/;
• the resolved system for each image (build/nros/models/);
• the generated message crates;
• each image’s entry and the build root that compiles it: a cargo package when every node is Rust, a CMake project when any node is C or C++, a Zephyr application for a Zephyr board.

nros build then runs that host tool, so compiler errors are the compiler’s. nros build --dry-run prints the command for an image, and running it yourself works too. Where each binary lands is What nros build Produces.

Customising an entry

The generated entry is one nros::main!(…) call, and the macro does a lot: it opens the executor at the size the image declares, registers every node in the launch file, and adds the lifecycle, parameter services and tiers the system asks for. Take the smallest step that does what you need:

before_boot names a function in one of the image’s node packages:

[image.linux]
board = "linux"
before_boot = "sensor_node::prepare"

#![allow(unused)]
fn main() {
// src/sensor_node/src/lib.rs
pub fn prepare() -> Result<(), &'static str> {
    // open the device, check the calibration, wait for the peripheral
    Ok(())
}
}

The entry calls it first, before the board does anything, so nothing has booted when it runs: no executor, no session, and on bare metal no hardware setup yet. Returning Err("reason") stops the image with that reason. It works in Rust images only; a C or C++ image that sets it is refused, and so is a board whose framework owns the first statement. The worked example is image linux_rust_before_boot in examples/workspaces/features.

nros materialize is the last resort. It copies an image’s generated entry into src/<image>_entry/, and from then on nros build uses your copy and does not regenerate it:

$ nros build linux
$ nros materialize linux
wrote …/src/linux_entry

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

What you get is the same nros::main!(…) call inside its crate root. While you keep the macro, launch-file changes still reach the program; what you own is the shell around it. Replacing the macro with your own main means writing the boot, node registration, executor sizing and every capability yourself, and keeping them in step with the launch file by hand. Deleting src/<image>_entry/ returns the image to generation.

Coming from ROS 2

One image is one program, which runs its nodes in one process on one board. Several processes are several images.

Other languages

Nothing on this page is Rust-specific except the node’s source file. C and C++ node packages, and workspaces that mix languages, are C / C++ multi-node workspaces and Mixed-language workspaces. Role reference lists every field of the three roles.

Design background

• RFC-0121: workspace-first project layout: why every project is a workspace, why system.toml lives only in a bringup, and the target spellings nros run accepts.
• RFC-0120: one resolver for every build road: why nros build prepares the build itself.

C / C++ multi-node workspaces

Growing your workspace describes 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. 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 What nros build generates. 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 -Dnano_ros_ROOT=<sdk-root>, or a cmake --preset from nros setup presets) or as part of the workspace; the per-pkg CMakeLists doesn’t change between modes.

Node pkg

A typed component — 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)

# 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 a typed 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 bringup with no launch/ writes the same file at <bringup>/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; the build carries this one to where the resolver looks. That is how a one-node bringup states its QoS — and stating it is worth real memory: one sub: { chatter: { qos: { history: keep_last, depth: 1 } } } row takes a one-node Rust listener on Linux 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.

The build folds it into the resolved SystemModel, and the entry passes that model to the sizing automatically — nothing here takes an argument for it.

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 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 linux) checks it before it configures: the host 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. nros build does: before it plans a cross image, it takes that image’s census. Taking it 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). A build driven some other way (a hand-run west build or cmake) with no census, or a stale one, REFUSES at configure and prints the command that takes it; running nros build once for the image takes it too. 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 my_talker --lang cpp --template talker --to demo_bringup

From the workspace root this adds src/my_talker/ (class my_talker::Talker) and, with --to, its [[component]] row in demo_bringup.

Bringup pkg

Language-agnostic — copy verbatim from the bringup steps. package.xml + system.toml, and launch/system.launch.xml when you want one (without it the launch file is generated from the [[component]] rows). 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 asks the nros CLI to generate the entry and 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. The build 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 build re-resolves the model whenever the bringup’s launch XML or system.toml changed; with nothing changed it costs a digest comparison.

Writing the entry yourself

One case needs a hand-written one: startup the declarations cannot express. nros materialize <bringup>:<image> writes the generated entry out to src/<image>_entry/, as a package with nano_ros_entry(NAME … ) in its own CMakeLists.txt, and nros build then leaves it alone. (A Rust image has a smaller step first, [image.*] before_boot; the C/C++ entry has no such hook yet.)

A Zephyr image is not a second case. nros build and nros run generate its Zephyr application under build/ from the image, like every other entry, and nros materialize is the way to own it there too (the Zephyr chapter).

The materialized package needs no source file of its own: the cmake function generates the whole body (the main above), so its CMakeLists.txt names the bringup and launch file and nothing else.

Build + boot

nros build linux
nros run linux        # or run ./build/posix-zenoh-linux/cmake/linux_entry

nros build prepares everything first: the generated message bindings, the SystemModel (via the pinned nros-launch-resolve helper), and build/<coordinate>/CMakeLists.txt. Then it configures and builds. Each piece is redone only when its inputs changed, so there is no step to run before it. 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. Run nros configure first to write it without building; nros build linux --dry-run prints the exact cmake lines.

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 the entry generator 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

--lang c scaffolds a pure-C Node pkg the same way. Pure-C and mixed C/C++ workspace examples live under examples/workspaces.

See also

• examples/workspaces/cpp/ — the canonical reference workspace, all C++: the talker, listener, service and action Node pkgs, and one bringup per behaviour (pubsub_bringup, service_bringup, action_bringup) whose image rows are the paired examples, one per platform and role.
• C++ Entry-pkg roadmap doc — full landing order + acceptance bar.
• Multi-node workspace layout design §11 — LOCKED canonical shape (Bringup + Node + Entry).

Design background

• RFC-0122: behaviour bringups, single-node witnesses, and cadence-backed CI. The paired examples as image rows of behaviour bringups in the language workspaces.

Mixed-language workspace

Languages mix per package, not per file. A bringup’s [[component]] row names a package and a class whatever language implements it, and node packages are linked through a C ABI register trampoline, so one image can compose node packages written in C, C++ and Rust. The workspace shape does not change with the language. 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/             # package.xml + system.toml (+ launch/)

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. So a mixed workspace builds exactly like the C++ one:

$ cd my_mixed_ws              # e.g. a copy of examples/workspaces/mixed
$ source /opt/ros/humble/setup.bash   # the first build generates messages from ROS 2
$ nros build linux
$ nros run linux

The first build records the ROS 2 prefix in the workspace, so later shells need not source ROS 2.

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, and neither the root nor the entry is yours to write.

C Node pkg

A C Node pkg is a typed component: 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)

#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, int64_t last_call_time) {
    c_talker_pkg_t* self = RCLC_CONTAINER_OF(timer, c_talker_pkg_t, timer);
    (void)last_call_time;
    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_default(&self->timer, NULL, 1000000000ULL, on_tick);
    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 (here an authored launch/system.launch.xml; without one, the file generated from the [[component]] rows) 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 resolved system is a build artifact, resolved from the launch file under build/. Naming it in a build file is a deprecated expert override, and committing one is refused.

Per-language notes

Rust. A Rust node package is a library crate ending in nros::node!(YourNode). Its message crates and the settings cargo needs (the board’s target triple, link flags, environment) are generated under build/, never beside your packages, and nros build prepares them before it hands off. In a mixed workspace the Rust packages are built through CMake (by corrosion), so their compiler errors are still cargo’s.

C. A C node package is the configure component shape above, built by the same per-package CMake as C++. Its message bindings are generated during the CMake configure.

The RMW is spelled once, whatever the languages: [system] rmw in the bringup’s system.toml, or rmw = on one [image.*] block when one image differs. The features each package needs follow from it, so switching backend is a one-word edit: Switching RMW in Config.

Scaffolding

Inside a workspace, nros new adds a node package in the language you name, and --to adds its component row to a bringup:

nros new c_talker_pkg --lang c --template talker --to demo_bringup
nros new cpp_listener_pkg --lang cpp --template listener --to demo_bringup
nros new rust_heartbeat_pkg --lang rust --to demo_bringup

To start from a complete mixed tree, copy examples/workspaces/mixed/ out instead. It runs a C talker, a C++ listener, a Rust heartbeat, and C and C++ service and action pairs, composed into one program per image.

Design background

• RFC-0121: workspace-first project layout

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 and system.toml, and optionally launch/*.launch.xml, config/ and 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.

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.

Every project is a workspace, including one with a single node: one node package plus one bringup package, which nros new <ws> --board <board> writes together. system.toml lives only in a bringup; one beside a Cargo.toml or CMakeLists.txt is refused. See One node, one bringup 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 prefix rule (class starting with the pkg dir name) is retired — 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 …) (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. 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. [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.)

launch/ is optional. A bringup without it gets a launch file generated from its [[component]] rows, written to build/nros/launch/<bringup>/launch/system.launch.xml and resolved exactly as an authored one. Adding launch/system.launch.xml replaces it. A bringup with neither launch/ nor a [[component]] row is refused.

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 the build too (the launch resolver executes them). See Add a launch file.

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
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, os_config 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 The old [deploy.<id>] table conflated the two and is refused by name, pointing at both.

The generated entry

The entry package is derived from (launch, args, board) and generated: 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. 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 the build writes — triple, link flags, [env], patch rows — which cargo reads through --config. nros build writes all of it before it hands off; nros configure writes it without building, for an IDE or a hand-run cargo.

All of it is build output under build/, and none of it is written beside your source: no root build file, no .cargo/config.toml beside a package. 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

// RETIRED: `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 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; the build 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 hatches, smallest first: an [image.*] key (panic, profile, os_config, features); before_boot = "<pkg>::<fn>" for one step before the runtime starts; the board’s init_hardware for hardware every image on that board needs; and, last, nros materialize <bringup>:<image>, which copies the generated entry to src/<image_id>_entry/ for you to own. See Customising an entry.

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, which you meet only in an entry you have taken over with nros materialize. MODEL on either is the deprecated artifact-naming override, mirroring the macro. Metadata flows through ${BUILD}/nros-metadata.json rather than a sidecar TOML.

Zephyr images

A Zephyr image is no exception. Its entry is a Zephyr application — the app target find_package(Zephyr) creates — and nros build generates it under build/ like any other entry, then runs west build on it. 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.

What Zephyr adds is authored Kconfig (prj.conf, prj-<rmw>.conf, boards/*.overlay), which nothing derives. It lives in the Bringup pkg, one directory per board, and the image names the fragments it adds:

src/demo_bringup/boards/native_sim_native_64/
├── prj.conf
└── prj-zenoh.conf      # named by [image.<id>] os_config

A change the image keys cannot express goes through the same last resort as on every other platform: nros materialize <bringup>:<image> writes the generated application into src/<image_id>_entry/ as a package you own. The Zephyr chapter has the details.

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 build <image> writes the generated message crates and the per-image build settings, generates the entry and its build root under build/, and runs the platform’s own tool; there is no step to run before it. 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, Zephyr images included.

The language workspaces (rust, c, cpp) also hold the paired examples, one bringup per behaviour: pubsub_bringup (talker and listener), service_bringup (service server and client) and action_bringup (action server and client). Each holds one [image.<platform>_<role>] row per platform and role, with a _<rmw> suffix for any RMW other than zenoh, so every role stays its own image. Run one role by naming its bringup and image:

nros run pubsub_bringup:linux_listener

A variant with different code (a callback-style client, a polling listener) is its own node package with its own image row; a configuration (a serial link, a custom transport) is an image row that states the knob over the same packages.

One node, one bringup

The smallest project is still this shape, with one node package. The scaffold writes both packages:

nros new host_ws --board linux --template talker

host_ws/
└── src/
    ├── host_node/              # Node pkg: package.xml, Cargo.toml (a library), src/lib.rs
    └── host_node_bringup/      # Bringup pkg: package.xml and system.toml; no launch/

# src/host_node_bringup/system.toml
[system]
name = "host_node"
rmw = "zenoh"
domain_id = 0

[[component]]
pkg = "host_node"
class = "host_node::Talker"
name = "host_node"

[image.linux]
board = "linux"

There is no src/main.rs and no selection or board crate in the node’s manifest: the image’s generated entry names the board. nros run host_node builds and runs it. The node spelling means “the bringup whose only node is host_node, with its only image”; once the bringup has a second node or a second image, name <bringup>:<image> instead. --lang c or --lang cpp writes a C or C++ node package; the bringup is the same.

The copy-out example for each platform and language, examples/<platform>/<lang>/talker/, has this shape too: one node package and one bringup with no launch/, so its launch file is generated. It is the project to start from; the paired examples are the image rows above.

nros build (and nros configure) refuse a system.toml in a directory that also holds a Cargo.toml or CMakeLists.txt, and the message says where to move it. Projects that own their build and have no system.toml (a CMake add_subdirectory consumer, a vendor tree, a Zephyr application you build with west) are not affected: see Build as a CMake subdirectory, Vendored tree and A Zephyr App You Build with West.

Quick reference

Design background

• RFC-0121: workspace-first project layout
• RFC-0065: colcon-like workspace builder (images, hosts, generated entries)
• RFC-0098: generated leaf build config
• RFC-0057: ament-parity component registration
• RFC-0060: launch toolchain
• RFC-0026: example directory layout
• RFC-0122: behaviour bringups, single-node witnesses, and cadence-backed CI. The paired examples as image rows of behaviour bringups, and the single-node talker kept per platform and language.

Message Binding Generation

nros uses generated Rust bindings for ROS 2 message types. nros build generates no_std compatible bindings from each package’s package.xml dependencies before it builds (nros configure does that step alone, and nros interface generate rust the codegen alone).

Overview

The binding generator is part of the nros CLI and provides:

• Pure Rust, no_std compatible output using heapless types
• Automatic dependency resolution through your ROS 2 install’s ament index
• the [patch.crates-io] rows that point the nano-ros runtime crates at the SDK root, written into the image’s generated build settings

Prerequisites

1. package.xml in each node package - Declares ROS interface dependencies

   <?xml version="1.0"?>
   <package format="3">
     <name>my_package</name>
     <version>0.1.0</version>
     <description>My nros package</description>
     <maintainer email="dev@example.com">Developer</maintainer>
     <license>Apache-2.0</license>
     <depend>std_msgs</depend>
     <depend>geometry_msgs</depend>
     <export>
       <build_type>ament_cargo</build_type>
     </export>
   </package>
   

2. nros tool built + on PATH

   Install a release; install.sh puts nros in ~/.nros/bin:

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

   See Installation for the full walkthrough.

3. A ROS 2 install, sourced for the first build

   The bindings are generated from the message definitions of your ROS 2 install, std_msgs included, so the generated layouts and type hashes match the ROS 2 nodes you talk to. Source it before the first nros build, nros run or nros configure of a project:

   source /opt/ros/humble/setup.bash
   

   That configure records the prefix (AMENT_PREFIX_PATH) in the project, and later configures reuse it, so later shells need not source ROS. With neither, configure refuses and names this step. A project whose packages depend on no message package at all needs no ROS 2.

Workflow

Step 1: Create package.xml

Declare your ROS interface dependencies in <depend> tags:

<depend>std_msgs</depend>      <!-- For std_msgs::msg::Int32, String, etc. -->
<depend>example_interfaces</depend>  <!-- For service types -->

Step 2: Build

cd my_ws
source /opt/ros/humble/setup.bash   # the first build of the workspace only
nros build

Before it builds, this will:

1. Parse package.xml to find dependencies
2. Resolve transitive dependencies through the ament index
3. Filter to interface packages (those with msg/srv/action)
4. Generate bindings into the workspace’s generated/ directory
5. Resolve the bringup’s launch file into the system model
6. Write each image’s build settings under build/, carrying the board’s triple and flags, the resolved pool budgets, and the [patch.crates-io] rows for the nano-ros runtime crates

Each step is redone only when its inputs changed. To run them without building (before opening the workspace in an IDE, for instance), use nros configure. nros interface generate rust is the codegen-only step underneath — steps 1–4 and nothing else — and is useful when you want bindings without a workspace.

Step 3: there is no step 3 — package.xml is the dependency list

A generated message crate is a path dependency on its own directory, and nros build writes that row for you, before it plans: one per <depend> / <build_depend> / <exec_depend> that names a message package, tagged # nros-managed:

[dependencies]
std_msgs = { path = "../../generated/std_msgs", default-features = false }  # nros-managed
example_interfaces = { path = "../../generated/example_interfaces", default-features = false }  # nros-managed

So adding a message package is one edit — the <depend> — exactly as on the C/C++ road, and deleting the <depend> deletes the row on the next build. A row without the tag is yours: the build never edits or removes it, so deleting the tag is how you take a row over. The nros row is not managed — it carries a feature choice that is yours to make.

Never name a message crate by registry version (std_msgs = "*"): those crates are generated per host from your ament install, they are not published, and a bare name resolves against the public crates.io instead.

The nano-ros runtime crates are the other case — nros, nros-board-<board>, the backends — and they are registry-named with version = "*", because the build writes the [patch.crates-io] rows that redirect them into the nano-ros SDK root.

Why msg crates are RMW-agnostic

Generated msg crates carry only the wire-format data type — no backend-specific code, no per-RMW Cargo feature. A user manifest is the plain pair:

[dependencies]
std_msgs = { path = "../../generated/std_msgs", default-features = false }  # nros-managed
nros     = { version = "*" }

Transport choice and message schema are orthogonal concerns and the manifest reflects that. (Which backend you actually get is [system] rmw in the bringup’s system.toml, not a feature you pick here — see Switching RMW in Config.) This matches upstream rclcpp + rclrs, which both ship msg packages RMW-agnostic and let the RMW pick which descriptor representation it wants at runtime.

For DDS-based backends that need a per-type descriptor on the wire (Cyclone DDS today), the nros-rmw-cyclonedds shim builds those descriptors lazily on first pub/sub for a given message type, walks the static field schema exposed by nros-serdes (the Message trait with const TYPE_NAME + const FIELDS), and caches the result in a bounded no_std registry. No per-msg-pkg backend code is required.

The registry is bounded by the NROS_CYCLONEDDS_MAX_TYPES sizing knob.

Where the nano-ros sources come from

A project uses the SDK root the nros binary belongs to — a release’s own share/nano-ros — so a plain nros build works anywhere. To name a different SDK root, pass it:

nros build --nano-ros-path <sdk-root>

The build then writes the [patch.crates-io] rows into each image’s generated settings, pointing each nros* requirement at a directory in the SDK root. Nothing about the location is baked into a tracked file, so moving the workspace, or installing another release, needs no edit: the next build re-points it.

Use in code

#![allow(unused)]
fn main() {
use std_msgs::msg::Int32;
use example_interfaces::srv::{AddTwoInts, AddTwoIntsRequest, AddTwoIntsResponse};

let msg = Int32 { data: 42 };
}

Command Options

nros interface generate rust is the codegen step alone — it writes bindings and nothing else:

nros interface generate rust [OPTIONS]

Options:
      --manifest <PATH>         Path to package.xml [default: package.xml]
  -o, --output <DIR>            Output directory [default: generated]
      --ros-edition <EDITION>   humble | iron | jazzy [default: humble]
      --codegen-config <PATH>   Explicit per-field capacity config (nros-codegen.toml)
      --rename <OLD=NEW>        Rename a generated package
      --force                   Overwrite existing bindings
  -v, --verbose                 Enable verbose output

It also still accepts --generate-config / --nano-ros-path / --nano-ros-git, which write a .cargo/config.toml beside a package by hand. Those are the old shape and are not the path to use: nros build writes the patches into the generated settings instead, where they are regenerated rather than committed.

Generated Output Structure

my_ws/
├── src/
│   ├── my_node/
│   │   ├── package.xml      # Your dependency declarations
│   │   ├── Cargo.toml       # Your package manifest (a library)
│   │   └── src/lib.rs       # Your code using generated types
│   └── my_node_bringup/
│       ├── package.xml
│       └── system.toml      # Board, RMW, components
├── generated/               # Generated bindings (do not edit)
│   ├── std_msgs/
│   │   ├── Cargo.toml
│   │   └── src/
│   │       ├── lib.rs       # #![no_std]
│   │       └── msg/
│   │           ├── mod.rs
│   │           └── int32.rs
│   └── builtin_interfaces/  # Transitive dependency
│       └── ...
└── build/                   # Build output (do not commit)
    └── …/<image>_entry/     # each image's generated entry and its cargo settings, incl. the patches

Generated Code Features

no_std by default:

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

fn main() {
pub mod msg;
}

std feature for optional std support:

[features]
default = []
std = ["nros-core/std", "nros-serdes/std"]

heapless types for embedded:

#![allow(unused)]
fn main() {
pub struct String {
    pub data: heapless::String<256>,
}

pub struct Arrays {
    pub data: heapless::Vec<i32, 64>,
}
}

Service types with Request/Response:

#![allow(unused)]
fn main() {
pub struct AddTwoInts;
pub struct AddTwoIntsRequest { pub a: i64, pub b: i64 }
pub struct AddTwoIntsResponse { pub sum: i64 }

impl RosService for AddTwoInts {
    type Request = AddTwoIntsRequest;
    type Reply = AddTwoIntsResponse;
}
}

A timestamp message gets SecNanosecMsg, so Time::to_ros_msg() can return it:

#![allow(unused)]
fn main() {
impl nros_core::SecNanosecMsg for Time {
    fn from_sec_nanosec(sec: i32, nanosec: u32) -> Self { Self { sec, nanosec } }
}
}

Emitted for every message whose field set is exactly { int32 sec, uint32 nanosec } — builtin_interfaces/msg/Time, its Duration twin, and any message of yours with that shape. It is what makes the call a publisher writes work:

#![allow(unused)]
fn main() {
msg.header.stamp = node.now().to_ros_msg();
}

nros-core cannot name a message type — every generated crate depends on it, and your message crates are generated from your packages — so the conversion is implemented on the generated side and the trait is the seam. The C++ side spells the same thing as a template (node.now().to_msg(msg.header.stamp)); Rust has no structural bound, so it needs the named trait. There is no Result: nros’s Time already is { sec, nanosec }, so nothing can fail. (rclrs returns Result<_, TryFromIntError> because its Time is i64 nanoseconds; a ported t.to_ros_msg()? will not compile here, and deleting the ? is the fix.)

Examples

Each example on GitHub is a workspace that carries its own bringup and resolves on its own, so it builds wherever it lives. Build each from its own root:

cd my_talker_ws && nros build
cd my_service_client_ws && nros build

Regenerating Bindings

To regenerate after ROS package updates or dependency changes:

nros interface generate rust --force

Where the definitions come from

nros build reads message definitions from the ROS 2 install you sourced (or the one the project’s first configure recorded), through AMENT_PREFIX_PATH. The release carries copies of a few standard packages, but they only fill gaps under a ROS 2 install, never stand in for one: with no prefix set and none recorded, configure refuses rather than build from them, because they would silently fix a ROS 2 distro and the types would stop matching a peer on another one. A message package in your own workspace shadows the installed one of the same name.

Troubleshooting

“AMENT_PREFIX_PATH is unset and no configure of … has recorded one to reuse”

• This shell has not sourced ROS 2, and this project has never been configured from one that had. Run source /opt/ros/humble/setup.bash (or your overlay’s install/setup.bash), then build again.

“Package ‘X’ not found in ament index or bundled interfaces”

• Source the ROS 2 environment: source /opt/ros/humble/setup.bash
• Check package is installed: ros2 pkg list | grep X
• Install if missing: sudo apt install ros-humble-X

Build errors with generated code

• Regenerate with --force flag
• Check nros crate compatibility

Which CMake spelling (one table)

Five codegen entry points exist in the CMake surface. They are NOT interchangeable spellings of one thing — each serves one audience, and two are back-compat only. Pick by what you are doing:

C Code Generation (CMake)

nano_ros_generate_interfaces(… LANGUAGE C) generates C bindings for .msg, .srv, and .action files (the function defaults to C++ — the LANGUAGE C argument is what makes it the C generator). It uses a bundled codegen library — no external nros binary needed.

Prerequisites

nano_ros_generate_interfaces() becomes available automatically once the consumer’s CMakeLists.txt invokes add_subdirectory(nano-ros). The codegen tool ships inside the in-tree nros CLI binary (packages/cli/target/release/nros; the old nros-codegen submodule is retired); cmake auto-resolves it from PATH / packages/cli/target/release/ / the transitional ${NROS_HOME:-~/.nros}/bin/. No separate build step.

Usage

For a complete example, see the features workspace, examples/workspaces/features: its custom_msgs package defines a message, and c_reading_talker_pkg and c_reading_listener_pkg use the generated C bindings. The custom-message feature demo is a node package there, with its own image row.

Design background

• RFC-0067: environment-invariant message dependency identity
• RFC-0048: CMake ament consumption
• RFC-0122: behaviour bringups, single-node witnesses, and cadence-backed CI. Feature demos as node packages of the features workspace.

Configuration Guide

nano-ros config is language-agnostic and has one home per concern — no setting lives in two places, and nothing is merged across files. The authored surfaces are a universal system.toml, package.xml, and launch XML — plus Kconfig for the embedded build (Zephyr). Cargo.toml and CMakeLists.txt carry language-toolchain facts and nothing else. This guide covers what each file owns, the network identity an embedded image bakes at build time, and the standalone config.toml for hand-written no_std apps.

Retired surfaces you may find in old material: the nros.toml per-package/workspace file (rejected by the CLI), the old config.toml [network]/[zenoh]/[scheduling] schema, every [package.metadata.nros.{node,entry,component,deploy.*}] table, and the package.xml <nano_ros deploy=… board=… rmw=…/> tuple. The last two moved into system.toml; readers refuse them rather than reading them. The design records are listed under Design background.

One home per concern

Boundary rule. If a knob changes what is compiled/linked as a language choice — a C++ standard, an RMW feature the entry may select — it lives in the build file. Everything else about the deployment (components, board, domain, RMW, and the physical link + router address a target boots with) lives in system.toml. Nothing a board implies is authored anywhere: it is derived from the board descriptor into the generated settings file.

Config home by language × scale

This table has one answer in all four cells, which is the point of it:

A system.toml beside a Cargo.toml or CMakeLists.txt is refused, so the resolver has one input shape and you have one thing to learn. Resolution is a fixed precedence ladder, not a merge: explicit CLI/build flag (--rmw / -DNROS_*) > system.toml ([image.<id>] > [system]) > the board descriptor’s [knobs] > built-in default. nros config show prints the resolved effective config with per-value provenance; nros check flags values still sourced from legacy files.

For the multi-RMW runtime topic-forwarding bridge (a separate file/feature), see nros-bridge.toml.

Embedded image config (codegen apps — the common case)

An embedded app built through nros::main!() (Rust) or the CMake entry codegen (C/C++) declares its board and its network + router config per image, in system.toml. The toolchain bakes it at compile time — there is no config file on the device and nothing is parsed at runtime. The file is the same in both languages:

# system.toml (e.g. examples/mps2-an385-baremetal/rust/talker)
[system]
name      = "qemu_bsp_talker"
rmw       = "zenoh"
domain_id = 0

[[component]]
pkg      = "qemu_bsp_talker"
class    = "qemu_bsp_talker::Talker"
name     = "talker"
dispatch = "deferred"          # optional: callbacks hand off to a ring

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

The [image.<id>] key is the image’s name — what you pass to nros build <image> — and board is the only thing that has to change to retarget it. nros::main!() bakes the image’s network fields into a DeployOverlay that BoardEntry::run_with_deploy applies onto the board’s boot Config; the C/C++ entry codegen bakes the same values into its generated glue. Nothing is written in Cargo.toml, in package.xml or on a cmake command line.

Networks and addresses

An image’s address is a layer-1 fact: the operating system owns the network device. On Linux that is the kernel; on Zephyr and NuttX it is their own configuration (Kconfig, devicetree, defconfig); on a board where nano-ros is the OS (the reference FreeRTOS, ThreadX and bare-metal boards) it is the board package, through a small board network file the image names with os_config — one table per interface:

[image.talker]
board = "mps2-an385-baremetal"
os_config = ["board-net.toml"]

# board-net.toml, beside system.toml
[eth0]
network = "qemu"
host = 10                      # 10.0.2.10 on QEMU's network

qemu is built in: QEMU’s own user-mode (SLIRP) network, 10.0.2.0/24 with gateway and router host 10.0.2.2. Every -nic user makes a private copy of it, so two images on qemu never meet. Any other network is defined in the board network file beside the interface on it, and the image states its router as its own locator:

# board-net-sensor.toml
[eth0]
network = "lab"
address = "192.168.50.20"

[network.lab]                  # e.g. a switch or a Linux bridge with boards on it
subnet  = "192.168.50.0/24"
gateway = "192.168.50.1"

[image.sensor]
board = "mps2-an385-baremetal"
os_config = ["board-net-sensor.toml"]
locator = "tcp/192.168.50.1:7447"

Two images on one network each define it in their own file, and the files must agree: one network has one subnet, gateway and lease policy.

Per interface:

• network defaults to the board’s (qemu on every QEMU board), so [eth0] host = 10 is enough there.
• host is the last octet within the network’s subnet; address is the full IPv4, or "dhcp" on a network with dhcp = true (and a board whose interface runs a DHCP client). An interface on qemu that states no address takes 10.0.2.15, the address a plain -nic user guest picks.
• mac is optional. Left out, it is derived from the board interface’s mac_prefix and the system, image, network and interface names, so two images never share one by accident.
• The gateway and netmask come from the network, so an interface never states them.
• An image dials its own locator, else [system] locator. On a network other than qemu one of the two must be stated.

A board may have several interfaces. An image addresses each on its own network, one table each: [eth0], [eth1].

These fail the build, naming the image (and, for a duplicate, both images):

• an address outside its subnet, equal to the gateway, or on a network no file defines;
• two images with the same static address, or the same MAC, on one network other than qemu, or two files defining one network differently;
• a board network file on a board whose network belongs to the host operating system (linux, freertos-posix, threadx-linux), or on a board that declares no interfaces (Zephyr boards take their address from Kconfig);
• the retired spellings, each refused naming its new home: [network.<name>] and [image.<id>.net.<if>] in system.toml, and the flat ip / gateway / netmask keys on [image.<id>].

The board’s half is [board.net] in its descriptor: stack (who owns the network: host, os or board), links, network (its default network) and interfaces, each a kind (eth0 = "ethernet") or a table (eth0 = { kind = "ethernet", mac_prefix = "52:54:00", dhcp = true }). A board states no address: [board.net] ip / mac are refused.

The resolved answer for an image is written to build/nros/net/<image>.toml (under the workspace) and reaches the firmware as NROS_IMAGE_NET.

How an emulated image joins its network is a fact about how it is RUN, not built, so it has its own table, read only by the QEMU launchers and the test harness:

[image.sensor.run]
nic = { bridge = "qemu-br" }   # QEMU: -nic bridge,br=qemu-br,…

nic is "slirp" (QEMU’s own user-mode network, the default on qemu), { bridge = "<dev>" } or { tap = "<dev>" } on the host, and applies to the image’s first interface. An image on any other network with no nic is physical only, and launching it under QEMU is refused. nros run passes the -nic value to QEMU when it boots the image.

The same goes for a board that is flashed and watched on a serial port: the board’s descriptor states its flasher and console ([board.flash], [board.console], see the descriptor section), and an image overrides any key of them in its own tables:

[image.lab.flash]
command = "pyocd flash -t stm32f767zi {hex}"     # replaces the board's method
prepare = [{ say = "Set BOOT0 to 1, then press RESET", wait_for = "usb:0483:df11" }]

[image.lab.console]
baud = 921600                                     # kind stays the board's

Both are checked when system.toml is read (an unknown key, wait_for event or {placeholder} is refused) and are read by nros flash and nros monitor.

The middleware’s own file

How a session finds its peers — which router to dial, which endpoints to listen on — is the middleware’s own configuration, written in its own language. A bringup ships it beside its system.toml, and it applies to every image of that backend:

// rmw/zenoh.json5
{
  mode: "client",
  connect: { endpoints: ["tcp/192.168.50.1:7447"] },
}

zenoh-pico has no json5 parser, so the build reads the file on the host, lowers each key to a zenoh-pico session property and bakes the result into the image. A key zenoh-pico cannot take is refused, naming the key — never dropped. With a file, the file IS the wiring: the image’s connect list replaces the default router, and an image that also states a locator is refused (a [system] locator is simply not used). On a hosted build ZENOH_SESSION_CONFIG_URI replaces the baked file at run time, whole, as it does for rmw_zenoh.

The flat rmw/zenoh.conf list (key = value) is retired and refused, naming the json5 that replaced it.

The names above are the default. To ship a different file — one per site, one for a QEMU run and one for the lab — name it:

[system]
rmw_config = "rmw/zenoh-lab.json5"      # every image's default session

[image.qemu]
board = "mps2-an385-freertos"
rmw_config = "rmw/zenoh-qemu.json5"     # this image's own

A named file that does not exist is refused. XRCE has no file format; its endpoint is the image’s locator.

A bridge opens one session per [[domain]], and each domain names its own file, so one image can speak to a CAN zenoh network and an Ethernet DDS one with two documents:

[[domain]]
name = "zen"
rmw = "zenoh"
config = "rmw/zenoh-zen.json5"

[[domain]]
name = "dds"
rmw = "cyclonedds"
id = 5
config = "rmw/cyclonedds-dds.xml"

[[bridge]]
name = "gw"
from = "zenoh:zen"
to = "cyclonedds:dds"

A domain with a config states no locator (the file is its wiring), and a domain config that no [[bridge]] opens is refused, since nothing would read it. An image overrides one domain’s file with a table, rmw_config = { dds = "rmw/cyclonedds-lab.xml" }: the build then writes that image its own bridge configuration (nros-bridge.<image>.toml) beside the bringup’s, and the other images keep the shared one. At run time ZENOH_SESSION_CONFIG_URI and CYCLONEDDS_URI still replace a hosted bridge’s files, and NROS_BRIDGE_<SESSION>_LOCATOR replaces that session’s file whole.

Per-image build knobs

A build knob that one image needs, and that its board does not state, goes in [image.<id>.knobs.<group>]. The table has the same shape as a board descriptor’s [knobs.<group>]:

[image.zephyr_xrce.knobs.zephyr]
heap_size = 98304            # NROS_ZEPHYR_HEAP_SIZE

[image.zephyr_xrce.knobs.xrce]
max_subscribers = 1          # NROS_XRCE_MAX_SUBSCRIBERS (-1, the default, derives it)

[image.linux.knobs.log]
max_level = "warn"           # NROS_LOG_MAX_LEVEL (a level name or 0..6)

[image.linux.knobs.executor]
max_cbs = 16                 # NROS_EXECUTOR_MAX_CBS

Each key is a row of the knob registry (packages/tooling/nros-zephyr-build/knobs.toml). The key is the row’s board key where it has one (executor.max_cbs, zenoh.tx.batch); otherwise it is the env name without NROS_, split at the first _ (NROS_ZEPHYR_HEAP_SIZE becomes zephyr.heap_size). An unknown key, a value of the wrong type or a value outside the knob’s range stops nros build with an error that names the key. The value reaches the build exactly as the knob’s NROS_* variable would: through the generated cargo config on the cargo road, the image env file on the cmake road, and the Kconfig defaults on west. It sits on the image rung (above the board, below an exported variable).

[image.<id>] env = { NAME = "value" } still carries an application’s own build variable, a name the registry does not hold. An env row that names a registry knob is an error that names its knobs spelling (release 0.6.0 accepted it with a warning).

RT/stack/priority for a single-node embedded app comes from board-crate Cargo features + Kconfig (prj*.conf on Zephyr), not a config file. Multi-node RT is declared in system.toml ([tasks.<name>.<rtos>] + [[node_overrides]]).

Periodic timers after a stall

If a tier is preempted past several periods of a periodic timer, the backlog is coalesced, not replayed: the timer fires ONCE and the missed periods are counted. Phase is preserved, so activations stay on the declared cadence grid rather than drifting by each stall. This is the default (TimerOverrunPolicy::Skip) and matches rclcpp and Zephyr’s k_timer.

Replay is available — Executor::set_timer_overrun_policy(.., CatchUp) — and is the right choice for a counter or accumulator, where every tick carries state that must not be lost. It is the wrong choice for a control loop: the replayed activations compute with stale inputs and emit a burst of commands inside a fraction of a period.

Overruns are counted per timer (Executor::timer_overruns) and reported as the timer-overrun-runtime violation. Watch that rather than a publish-rate check: under CatchUp a replayed burst makes the achieved rate look nominal — measured 100.03 Hz on a declared 100 Hz loop while the tier was stalling for up to 611 ms at a time — so a rate monitor reports health during exactly the fault it exists to catch. The rationale and the measurements are in the execution-model design record (see Design background).

Timer periods are microseconds throughout, including across the C ABI.

Standalone config.toml — hand-written no_std apps (no codegen)

A hand-written single-node app that writes its own main() and bypasses nros::main!() keeps its net config in a file, not hardcoded in Rust: a sibling config.toml, compile-baked with include_str! and parsed by the board crate’s Config::from_toml. It is the board package’s network file — the same [<interface>] / [network.<name>] shape an image’s os_config file has — plus a [node] table that stands in for the session a system.toml would declare.

# config.toml

[node]
domain_id = 0                    # ROS 2 domain ID (0–232)
locator = "tcp/10.0.2.2:7447"    # the router the firmware dials

[eth0]
network = "qemu"                 # built in: QEMU user-mode, 10.0.2.0/24, gateway 10.0.2.2
host = 10                        # the address within that network → 10.0.2.10
# address = "10.0.2.10"          # or the whole address
mac = "02:00:00:00:00:00"

# A network of your own: name it on the interface instead of `qemu`.
# [network.lab]
# subnet = "192.168.50.0/24"
# gateway = "192.168.50.1"

[node.rt.freertos]               # FreeRTOS boards: raw task priorities; omit for defaults
app_priority = 3
zenoh_read_priority = 4

A board reads its own facts from the interface table: a serial link’s [uart0] baud, ThreadX Linux’s host veth as [eth0] device. One interface is brought up; a direct-mode board takes no DHCP lease, so state the address.

A file in the retired shape ([[transport]] with ip, gateway and locator) panics at boot naming the new spelling, rather than booting on the board’s defaults: ip = "10.0.2.10/24" + gateway = "10.0.2.2" is [eth0] network = "qemu" + host = 10, and the locator moves to [node].

Consumption (compile-baked; no filesystem on the target):

use nros_board_mps2_an385::{Config, run};

fn main() -> ! {
    run(Config::from_toml(include_str!("../config.toml")), |config| {
        let exec = ExecutorConfig::new(config.zenoh_locator)
            .domain_id(config.domain_id);
        // ...
    })
}

Pick by whether the app uses codegen: nros::main!() app → system.toml [image.<id>] (above); hand-written main() → config.toml.

Files that used to carry configuration and no longer do are listed in Retired configuration files.

Build-time environment variables

Read during cargo build (by build.rs). Export them in your shell.

SDK paths

You normally set none of these. nros setup puts each vendored source tree in the shared store, and every build finds it through one ladder: an environment override, then your project’s [sources] in system.toml, then a checkout submodule you are editing, then the store, then the checkout’s own copy. Ask where a tree came from with nros locate <name> --why.

Set one of these variables only to build against a tree of your own:

For a tree that belongs to one project, prefer [sources] <name> = "<path>" in its system.toml (project-relative) over an exported variable, which every build in that shell inherits.

FREERTOS_PORT, FREERTOS_CONFIG_DIR, THREADX_CONFIG_DIR and NETX_CONFIG_DIR are not yours to set: they are facts about the board, stated in its nros-board.toml and carried to the build from there.

Buffer-tuning vars (ZPICO_*, XRCE_*, NROS_*) are optional — see the Environment Variables Reference.

Binary-size knobs (embedded)

On a constrained MCU, two build-time env vars — carried in the image’s generated build/<image>/nros-cargo.toml [env], like the other NROS_* tuning, and set there from the board descriptor’s [knobs] or from your own environment — shed the parts a brokered client doesn’t need:

Static-heap sizing by backend (bare-metal FreeListHeap, set via NROS_HEAP_SIZE):

Measured footprint

Honest, reproducible numbers per (platform, transport, backend, profile) — built with the in-tree examples, the release profile is cargo’s default (opt-3), the size profile is the scaffolded [profile.size] (opt-s + lto

• strip, see the size-tuned release profile notes). RAM = data + bss. All cells are after --gc-sections + the size knobs above are applied where noted; the serial cell ships with the recipe below.

¹ The two stm32f4 rows are historical: the board crates left the tree in a later cleanup, so nothing in-tree reproduces them today. They stay because a Cortex-M4F-with-its-own-stack data point is still the closest published figure for that class, and deleting a measurement is worse than dating it. The chip crate the numbers were built against (nros-platform-stm32f4) is still here.

The XRCE row uses tight per-session XRCE pools — delivered through the image’s generated [env] and read by nros-rmw-xrce-cffi’s build.rs: NROS_XRCE_STREAM_HISTORY=4, NROS_XRCE_CUSTOM_TRANSPORT_MTU=512, NROS_XRCE_MAX_SUBSCRIBERS=1, NROS_XRCE_MAX_SERVICE_SERVERS=1, NROS_XRCE_MAX_SERVICE_CLIENTS=1, NROS_XRCE_SUBSCRIBER_RING_DEPTH=1, NROS_XRCE_BUFFER_SIZE=256. Vendor defaults grow xrce_session_state_t to ~390 KB (which wouldn’t fit a 24 KB heap); these knobs drop it to ~12 KB. Defaults are unchanged for hosted / non-tight-RAM consumers — the env vars are pure opt-in.

How to read this:

• The size profile (opt-s) shrinks .text by ~10–26 % with .bss/.data unchanged (opt-level doesn’t touch static buffers — those are the env knobs above). -Oz is not used — on smoltcp examples it grows .bss +24 KB by defeating opt-3’s per-socket dead-buffer DCE (see the size-tuning notes above).
• Switching ethernet → serial sheds ~50 KB text + ~42 KB .data (no smoltcp stack, no IP link C, tuned heap) — the structural lever.
• FreeRTOS + lwIP cells .bss is dominated by lwIP’s heap + FreeRTOS task stacks (3 MB is the configured headroom, not nano-ros overhead).
• The micro-ROS / XRCE row is a reference, not a nano-ros measurement — no bare-metal XRCE example ships yet (needs a custom-transport injection); the path to parity is XRCE + serial + static pools.

Size-minimal recipe

Smallest measured nano-ros configuration today (mps2-an385-baremetal serial talker, 116 KB text / 101 KB RAM):

# Cargo.toml
[profile.size]
inherits = "release"
opt-level = "s"
lto = "fat"
codegen-units = 1
debug = false
strip = true

The gc-sections and link-script rustflags are not yours to write — they are the board’s, and they arrive in the generated build/<image>/nros-cargo.toml [target.<triple>] block:

# build/<image>/nros-cargo.toml — GENERATED, shown for orientation
[target.thumbv7m-none-eabi]
rustflags = [
    "-C", "link-arg=-Tlink.x",
    "-C", "link-arg=--gc-sections",   # 204.8 — strip unreferenced fns/data
]

The knobs that are yours are ordinary environment variables. The generated [env] never uses force, so a value you set in the calling environment wins:

NROS_LINK_IP=0 \
ZPICO_NO_SMOLTCP=1 \
NROS_HEAP_SIZE=131072 \
NROS_SMOLTCP_MAX_SOCKETS=1 \
NROS_SMOLTCP_MAX_UDP_SOCKETS=1 \
    nros build <image>

The profile is not one of them: name it on the image, as [image.<id>] profile = "size", and nros build passes it to whichever tool it drives.

NROS_LINK_IP=0 drops zenoh-pico’s TCP/UDP link C and ZPICO_NO_SMOLTCP=1 skips the smoltcp glue on bare-metal. On the heap floor: the per-entry executor backing is a single ~75 KB allocation, so a nros::main! image needs ≥128 KB (the board default) — the older 24 KB “zenoh-pico working set” figure OOMs at boot. HEAP is .bss (no flash cost); shrink below the default only on a non-nros::main! direct-mode image with a measured smaller peak. A knob you always want for a board belongs in that board’s descriptor [knobs], not on every command line.

nros new --platform baremetal already scaffolds the [profile.size] shape.

The deeper RAM win waits on XRCE on bare-metal (the ~3 KB-class client + static pools, with discovery offloaded to the agent) — tracked separately; zenoh-pico’s SUBSCRIBER_BUFFERS + alloc-based session are what keep this row’s .bss ~76 KB.

Cargo features (which RMW/platform is linked)

Features select the linked RMW backend, platform, and ROS edition. The system.toml rmw ([image.<id>], else [system]) picks which linked backend is active — the two are different layers (link vs run). Matrix + mutual-exclusion rules: Platform Model.

[dependencies]
nros = { path = "…/nros", default-features = false, features = [
    "rmw-cffi",            # generic C-vtable runtime registry
    "platform-bare-metal", # or platform-{freertos,nuttx,threadx,zephyr,posix}
    "ros-humble",          # or ros-iron
    "std", "alloc",        # optional, target-dependent
] }
# Exactly one RMW backend crate; its registration runs before main:
nros-rmw-zenoh = { path = "…/nros-rmw-zenoh", features = ["platform-bare-metal", "link-tcp", "ros-humble"] }
# …or nros-rmw-xrce-cffi / the cyclonedds CMake backend

Runtime environment (native host only)

On the native host build, ExecutorConfig::from_env() reads at process start (embedded targets bake their config at build time instead):

By deployment scenario

Design background

• RFC-0004: configuration and transports
• RFC-0098: generated leaf build config
• RFC-0031: RMW selection and lowering
• RFC-0109: network config layers
• RFC-0015: RTOS orchestration (multi-node RT tiers)
• RFC-0002: RT execution model (timer overrun policy, § 4.4a)
• RFC-0103: one owner per fact (source lookup ladder)

Build Profiles

nano-ros builds both C/C++ and Rust code on your behalf. You choose the optimization level once, and nano-ros propagates it to every crate and library it builds for you.

The image is where you say it, beside the board it is built for:

[image_defaults]
profile = "nros-relwithdebinfo"   # the base every image folds over

[image.linux]
board = "linux"

[image.mps2]
board   = "mps2-an385-baremetal"
profile = "nros-minsizerel"       # this one is going on a board

nros build carries that through to whichever tool builds the image — the cargo profile flag on the cargo driver, CMAKE_BUILD_TYPE on the cmake one. You do not repeat it on the command line, and you do not define the nros-* profiles anywhere: the build writes them into the image’s generated cargo settings file under build/ (build/linux/nros-cargo.toml for a single-package project), along with everything else the board choice implies.

From a CMake build type

When you drive CMake yourself — a single-package C or C++ project builds with its own CMake configure (from the CMakePresets.json that nros setup presets writes, which names the SDK root; nros build passes it for you), and needs no sync — set CMAKE_BUILD_TYPE as you would in any CMake project. nano-ros derives the cargo profile for the Rust it builds underneath from it:

cmake --preset linux -DCMAKE_BUILD_TYPE=MinSizeRel
cmake --build build/linux

Your C/C++ sources get -Os from CMake as usual, and the Rust nano-ros builds for you gets --profile nros-minsizerel. You do not need to add anything to any Cargo.toml — nano-ros supplies the definition of its own nros-* profiles.

An unrecognized build type is an error rather than a guess, so a custom type never silently produces an optimization level you did not ask for.

Choosing the Rust profile separately

NROS_CARGO_PROFILE overrides the mapping when you want the two halves to differ — for example a small C/C++ image with debuggable Rust:

cmake --preset linux \
    -DCMAKE_BUILD_TYPE=MinSizeRel -DNROS_CARGO_PROFILE=nros-relwithdebinfo

Using your own profile

Name any profile you like. When the name is not one of nano-ros’s nros-* profiles, you own the definition — nano-ros passes the name through and injects nothing, so your settings are authoritative:

[profile.prod]
inherits = "release"
opt-level = 3
lto = "fat"

Put that where cargo already looks for a profile: the package’s own Cargo.toml for a single-package project, or a .cargo/config.toml in a directory above your project. There is no workspace-root Cargo.toml to put it in — a nano-ros workspace has no root build file, and the cargo root is the generated entry under build/, which is regenerated on every build.

A config file is a first-class home for a profile, not a workaround: it is exactly how the nros-* presets reach cargo. An undefined name still fails the way it always did — error: profile 'prod' is not defined — while a name the generated settings file defines resolves and builds.

cmake --preset linux \
    -DCMAKE_BUILD_TYPE=Release -DNROS_CARGO_PROFILE=prod

Which profile is active?

A CMake configure prints it, with the target/ subdirectory it builds into:

-- nano-ros: cargo profile `nros-minsizerel` (CMAKE_BUILD_TYPE=MinSizeRel) → target/nros-minsizerel

Notes for embedded targets

• Images grow at the default. nros-relwithdebinfo trades size for build speed. For flashing to a constrained board, build MinSizeRel.
• Two platforms pin their own profile regardless of what you choose, and will say so: NuttX Rust images (a codegen miscompile at lto = "off") and FreeRTOS QEMU images (the emulated Cortex-M3 misses zenoh-pico’s handshake window at low optimization).

What nros build Produces

nros build ends at an artifact and stops. It discovers your packages, resolves the image, checks the toolchain, generates the root build file and the entry, and then hands off to the native tool — cargo, cmake or west. The last stage is an exec, so the artifact is exactly the one that tool would have produced had you run it yourself.

This page answers the question the build does not: what are you holding, and where is it?

Running it: nros run and nros flash

nros run starts an image whose board is a host process or an emulator: it builds the image if it is stale, starts the router the image’s link needs, streams the console and stops everything when it ends (--expect <text> grades the console, --dry-run --why prints the plan it would execute). How a board is launched is stated once, in its descriptor’s [board.run], so the command nros build prints as its next step is the one nros run executes.

Real silicon is flashed, not run: nros run refuses a hardware image and names nros flash --monitor. nros flash builds the image if stale, runs the board’s human steps ([board.flash] prepare), flashes through the method its descriptor’s [board.flash] names (west, or a command template), and with --monitor watches the console on the same port; --expect <text> grades it as nros run does. nros monitor opens the console of a board that is already running. The port comes from --port, NROS_PORT, the bench file (nros bench scan) or the one attached device that matches the board.

The commands quoted below are the board tooling’s, reproduced here as a reference for a board no flash method covers yet.

There is also no install step: nros build never runs cmake --install, writes no install/ prefix and stages nothing. Whatever the native tool wrote in its own build tree is the deliverable.

Where it lands

Which tool builds an image is decided by its platform and by whether the workspace crosses languages:

The coordinate is the platform and the RMW — posix-zenoh, freertos-cyclonedds — plus, for CMake, the board, because CMake pins one compiler per configure and two boards on one platform would otherwise share a cache: posix-zenoh-linux, freertos-zenoh-mps2-an385-freertos.

Everything above is under build/, and that is the rule rather than a coincidence: a workspace has no root Cargo.toml and no root CMakeLists.txt. It is a directory of packages, like a colcon workspace, and every generated thing — the entry, the root build file, the cargo settings, the compiled output — lives in build/.

After a successful build nros build prints the artifact itself, and the board’s own command that runs or flashes it — never running either:

nros build: next for `c_talker_node_bringup:linux`:
  artifact: /home/you/c_talker_ws/build/posix-zenoh-linux/cmake/linux_entry
  run:
    /home/you/c_talker_ws/build/posix-zenoh-linux/cmake/linux_entry

What the run: (or flash) line is depends on the board: the binary for a host board, the board’s QEMU runner with the provisioned qemu-system-* for an emulated one, west build -d <dir> -t run / west flash -d <dir> for Zephyr. --dry-run and --check build nothing, so they print no such block.

One path the build also prints is easy to mistake for the binary:

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

That is the generated entry package — source that nano-ros wrote for you, under build/ because it is build output. The compiled program is elsewhere; see below.

cargo

Every image gets its own cargo settings file, build/<coordinate>/<entry>/nros-cargo.toml, and nros build points cargo at it:

cargo build --manifest-path build/posix-zenoh/linux_entry/Cargo.toml \
            --config build/posix-zenoh/linux_entry/nros-cargo.toml

That file states the image’s target-dir, so each image compiles into its own tree rather than sharing one target/. It also carries the board’s triple, linker flags and cross compiler, the resolved pool budgets as [env], the in-repo [patch.crates-io] rows, and the nros-* build profiles. It is generated on every build — read it, never edit it.

The artifact is the generated entry’s binary, inside that entry’s own target dir:

<ws>/build/<coordinate>/<image>_entry/target/[<triple>/]<profile-dir>/<image>_entry

The triple level appears whenever the board pins one — which it does in the generated [build] target, not on your command line.

A Linux image on Cyclone DDS, for instance, is build/posix-cyclonedds/linux_entry/target/debug/linux_entry.

<profile-dir> is debug unless the image declares [image.<id>] profile = …, in which case it is that profile’s directory (cargo’s rule: a profile builds into the directory of its own name, and dev into debug).

Next step: on a host board, run it. It is an ordinary executable.

./build/linux/target/debug/talker

For a QEMU board, the generated settings file also carries that board’s runner, so cargo run through the same --config boots the image — see Build Profiles for driving cargo yourself.

A multi-process zenoh example also needs a router; that is ROS’s rmw_zenohd, not something nano-ros ships — see Deployment Workflow and Install.

C, C++ and mixed workspaces (cmake)

CMake is chosen whenever the package graph contains anything that is not Rust, on the host and when cross-compiling alike. The generated root is <ws>/build/<coordinate>/CMakeLists.txt, it is configured into <ws>/build/<coordinate>/cmake/, and each image’s executable lands at the top of that directory:

<ws>/build/<coordinate>/cmake/<image>_entry

For example, examples/workspaces/c builds [image.linux] to build/posix-zenoh-linux/cmake/linux_entry and its FreeRTOS image to build/freertos-zenoh-mps2-an385-freertos/cmake/freertos_entry. (Node packages also build their own executables, under cmake/pkg/<pkg>/<pkg>; the image is the one at the top level.)

The file has no extension in either case. On the host it is a host executable; for a cross board it is a statically linked ELF for that architecture — the FreeRTOS one above is ELF 32-bit LSB executable, ARM, EABI5, statically linked.

Next step:

• host — run it directly.
• QEMU — the ELF is what -kernel takes, with the machine and CPU your board’s guide names.
• hardware — hand the ELF to your flasher (probe-rs, OpenOCD, a vendor tool). nano-ros has no opinion about which.

Zephyr (west)

nros build resolves your application and its overlays and runs west build from the workspace root with each image’s OWN build directory, <ws>/build/<coordinate>/<bringup>__<image>_west (west’s default, build/ under the cwd, would put every image of a workspace in one tree and refuse the second). Pass -- -d <dir> to choose another. Zephyr writes its image under zephyr/ inside it; for demo_bringup:zephyr on zenoh:

<ws>/build/zephyr-zenoh/demo_bringup__zephyr_west/zephyr/zephyr.elf   # always
<ws>/build/zephyr-zenoh/demo_bringup__zephyr_west/zephyr/zephyr.exe   # native_sim — a host executable
<ws>/build/zephyr-zenoh/demo_bringup__zephyr_west/zephyr/zephyr.bin   # cross targets — the raw image
<ws>/build/zephyr-zenoh/demo_bringup__zephyr_west/zephyr/zephyr.map   # the link map

Which of .exe and .bin appears is Zephyr’s choice, not nano-ros’s: a native_sim build produces zephyr.exe, a Cortex-M build produces zephyr.bin.

Next step — Zephyr’s own verbs, against the image’s build directory (nros build prints whichever the board supports):

west build -d build/zephyr-zenoh/demo_bringup__zephyr_west -t run   # native_sim and emulated boards
west flash -d build/zephyr-zenoh/demo_bringup__zephyr_west          # hardware: the board's flash runner
./build/zephyr-zenoh/demo_bringup__zephyr_west/zephyr/zephyr.exe    # native_sim: the same as -t run

The -d is not optional here: without it west uses build/ under the current directory, which is not where nros build put the image. west flash picks its runner from the board’s own board.cmake; nano-ros adds nothing to it.

Finding it yourself

When in doubt, ask the build what it is about to do. --dry-run prints the stages and the exact command, and performs no I/O:

nros build <image> --dry-run

The tool named in that command owns the output location, and its own documentation is the authority — which is the whole point of handing off rather than wrapping.

For the generation side of this — which root file is written, why the entry is derived rather than hand-written, and what the coordinate directory holds — see What nros build generates.

Integrating nano-ros into a Vendored Tree

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

nano-ros is distributed as a release: one archive holding the nros CLI and the library source it builds against (the SDK root). Nothing is on crates.io and there is no prebuilt library. So “vendoring” nano-ros means pinning and mirroring a release, not copying its repository into your tree: your tree holds your packages and the bringup’s system.toml, and the release supplies everything else.

Pinning the release

Install the exact release your tree is tested against:

curl -fsSL https://raw.githubusercontent.com/NEWSLabNTU/nano-ros/main/scripts/install.sh \
    | sh -s -- --version 0.6.0-nros4
export PATH="$HOME/.nros/bin:$PATH"
nros pin 0.6.0-nros4          # record it in the project's nros-toolchain.toml

Rules that keep the pin trustworthy:

• Pin a version, never “latest”. A moving target unships the pairing you tested.
• Move the pin forward only. nros pin <newer> reports the codegen delta before it writes anything, so an upgrade that invalidates generated bindings warns first.
• A release’s toolchain pins are decisions, not lags. Its nros-sdk-index.toml fixes the cross-compilers, the Cyclone DDS that ROS ships, a wire-stable zenoh-pico. Take what the release pinned.

What a fresh machine needs, in order

Three things, and the order matters:

1. The nros CLI, installed as above. Nothing else works without it.
2. ~/.nros/bin on PATH for interactive use. CI can skip this and call $NROS_HOME/bin/nros by absolute path.
3. Provisioned toolchains. nros setup <board> --rmw <rmw> fetches the cross-compiler, emulator, and SDK sources for exactly that pair into the shared store at ${NROS_HOME:-~/.nros}/sdk. --dry-run prints the plan first. (The zenoh router is deliberately not provisioned — it comes from a ROS 2 install, ros2 run rmw_zenoh_cpp rmw_zenohd.)

Then nros build from the workspace root. It produces the message bindings and the build settings each [image.*] implies before it builds — see the next section.

The Rust side: everything the build reads is generated, outside your source tree

Two things a Rust node package needs are generated, not authored: the message crates, and every build setting the target implies — the triple, the runner, the link flags, the resolved [env], and the [patch.crates-io] table that resolves registry-style names (nros = { version = "*" }) to the release’s SDK root. You state the target once, as a board name in the bringup’s system.toml, and the build derives the rest:

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

[image.linux]
board = "linux"

nros build writes those settings under build/, one set per [image.*] row, beside the entry it generates for that image and never beside your package, then hands them to cargo:

nros build            # or: nros build <image-id> for one image

A CI job that drives cargo itself prepares the same files first, without building, and runs the line nros build --dry-run prints:

nros configure                  # prepares every image, builds nothing
nros build <image-id> --dry-run # prints the cargo line, with its --config

nros configure is also the step to cache on: a run with nothing changed is a no-op, and its stamp under build/nros/configured/<image>/ holds the digest of every input that image read, which makes a CI cache key.

This is what makes a tree cheap to move: there is no .cargo/config.toml to copy, no include line whose relative path cannot resolve from your directory, and no table of absolute paths under version control to invalidate. After relocating the workspace or installing another release, the next build rewrites what is under build/ and touches nothing you track. Switching an image to another board is editing its one board = line.

Message dependencies are path deps that the build writes for you from package.xml’s <depend>s (std_msgs = { path = "../../generated/std_msgs", default-features = false } # nros-managed); never registry-name a message crate — a bare std_msgs = "*" can resolve against the public crates.io.

The CMake side

Two entry points, both source-backed:

• find_package(nano_ros REQUIRED) — the ament-shaped entry (nano_rosConfig.cmake at the SDK root). Located via -Dnano_ros_ROOT=<sdk-root>, which nros build and the CMakePresets nros setup presets writes pass; a raw cmake names it (no shell exports it). The SDK root is the installed release’s share/nano-ros (nros locate nano-ros prints it, for the version the project is pinned to).
• add_subdirectory(<sdk-root> nano_ros) — the lower-level shape. See Build as a CMake subdirectory for the cache-variable table.

Corrosion is never fetched at configure time: without it in the SDK store the configure stops and names nros setup --tool corrosion. nros setup <board> installs it too, for every board with a CMake road.

Air-gapped / mirrored CI

The offline contract, all of it:

1. Mirror the release asset. install.sh takes NROS_INSTALL_URL=<url> — a mirror, an air-gapped copy, a test server. The asset’s .sha256 must sit beside it and is still required.
2. Mirror or pin the SDK index. nros setup reads the index the release ships; NROS_INDEX_URL=<url> fetches a newer one from a mirror, nros setup --index <path> uses a copy you already have, and NROS_OFFLINE=1 forbids the fetch, and also runs every cargo that nros starts with CARGO_NET_OFFLINE=true, so dependencies come from cargo’s own cache (item 5). The index names every asset’s upstream ([tool.*], [source.*] sections); for a full mirror, rehost those URLs in your copy.
3. Pre-install Corrosion: nros setup --tool corrosion (or the nros setup <board> you already run) stages it into the SDK store, where the configure finds it without the network. Verify the configure line prints nano-ros: Corrosion <ver> via <origin> — never infer the version from having run an installer.
4. Cache NROS_HOME and the Rust toolchain. The CLI, the SDK root and every SDK nros setup fetches land under ${NROS_HOME:-~/.nros}; point NROS_HOME at a shared or cached location and it is reusable across jobs and machines of the same host triple. The Rust toolchain is the exception: nros setup installs it with rustup, which keeps it in ${RUSTUP_HOME:-~/.rustup} and ${CARGO_HOME:-~/.cargo} (the crate registry cache too). Cache those two directories beside NROS_HOME, or the offline host’s nros setup tries to download rustup again.
5. Prepare each workspace while online. nros configure in the workspace fetches the crates its images need into cargo’s cache and writes everything generated, so the offline build has nothing left to download.

What lives in your tree, and what does not

An application, a message package, a board overlay crate, and a custom transport all live entirely in your tree. A board the tooling can see does too: point NROS_EXTRA_BOARD_PATH (env, or CMake cache var for nano_ros_use_board()) at a directory of board crates in your tree, laid out like the SDK’s packages/boards/. Board keys stay global (a name under two roots errors).

A new platform (your own RTOS port) is the one extension that still edits nano-ros itself (nros-platform’s feature list and type alias, plus a cmake/platform/ module). That is a fork of nano-ros, built and maintained the way Contributing describes — see Custom Platform for the edits.

Upgrading the pin

curl -fsSL https://raw.githubusercontent.com/NEWSLabNTU/nano-ros/main/scripts/install.sh \
    | sh -s -- --version <newer>
nros pin <newer>              # reports the codegen delta first
nros setup <board>            # reconcile the SDK store with the new index
nros build                    # in each consuming workspace

What nros build generates is keyed to the CLI that wrote it, so the first build after a pin move regenerates it; there is no separate step to remember.

Checklist

• One release version, installed with --version, recorded with nros pin, moved forward only
• CI drives nros build (or a raw cmake --preset from the CMakePresets.json that nros setup presets writes) — no reliance on an interactive shell
• CI runs nros configure before any cargo line it drives itself (nros build needs nothing before it); no build setting hand-written into a package
• Air-gapped: release asset mirrored (NROS_INSTALL_URL), index pinned (--index / NROS_OFFLINE), Corrosion staged, NROS_HOME cached
• Your own boards found through NROS_EXTRA_BOARD_PATH, not copied into the SDK
• Router comes from the ROS 2 install on the host that runs it — nothing in the release provides one

Related

• Build as a CMake subdirectory — cache variables, link targets
• How Integration Works — per-RTOS build hosting
• Vendor Overlay Board Crate — board glue that lives in your tree
• Worked Example — STM32F4 Out of Tree
• Install — the interactive first-time flow this page assumes you are automating

Build as a CMake subdirectory

This is the escape hatch, not the path. If your project is a nano-ros package or workspace, you state the board once in the bringup’s system.toml and let nros build drive CMake — you never set a cache variable by hand, because the build root it generates sets them from that one board name. Start at First Project and Growing your workspace instead.

This page is for the C or C++ project that is not a nano-ros workspace: an existing CMake tree with its own layout and its own conventions, that wants nano-ros as a subdirectory and nothing else. There the cache variables below are how you say what you are building for, because there is no system.toml to read it from. nros build sets exactly these variables in the root it generates.

The SDK root’s top-level CMakeLists.txt (the SDK root is the share/nano-ros directory of the installed release, nros locate nano-ros prints it) exposes everything via add_subdirectory(...). The higher-level, ament-shaped alternative is find_package(nano_ros REQUIRED) — nano_rosConfig.cmake at the SDK root, located via -Dnano_ros_ROOT=<root>, which nros build and the CMakePresets nros setup presets writes pass for you (a raw cmake names it; no shell exports it) — which every in-tree example reaches through the workspace helpers. Either way there is NO install step: there is no install prefix and no find_package(NanoRos) (capital) config pipeline. Pinning a release for a company tree (offline CI, upgrade workflow) has its own page: Integrating into a Vendored Tree.

Layout

my_app/
├── CMakeLists.txt
└── main.c

nano-ros itself is the installed SDK root; the configure names it:

cmake -B build -DNANO_ROS_SDK="$(nros locate nano-ros)"
cmake --build build

User project CMakeLists.txt

cmake_minimum_required(VERSION 3.22)
project(my_app C)

# Pick platform + RMW BEFORE add_subdirectory.
set(NROS_PLATFORM posix)   # posix | freertos | nuttx | threadx | zephyr | baremetal
set(NROS_RMW     zenoh)    # zenoh | xrce | cyclonedds

add_subdirectory("${NANO_ROS_SDK}" nano_ros)

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

# Optional — generate C bindings for ROS 2 .msg / .srv / .action files.
# (LANGUAGE defaults to CPP; full spelling table → user-guide
# "Message Generation".)
nano_ros_generate_interfaces(std_msgs LANGUAGE C
    DEPENDENCIES builtin_interfaces)
target_link_libraries(my_app PRIVATE std_msgs__nano_ros_c)

That’s the whole story for the host-POSIX / zenoh case. CMake’s transitive target propagation pulls in libnros_c.a, libnros_rmw_zenoh_staticlib.a, the POSIX platform shim, system libraries (pthread, dl, m), and the per-build nros_config_generated.h header automatically.

Cache variables

Variables MUST be set(...) BEFORE add_subdirectory(...) — the sub-project consumes them at include time.

In a nano-ros package or workspace none of these are yours to set. The CMake root nros build generates writes NROS_PLATFORM and NROS_BOARD itself, both derived from the one [image.<id>] board you named in system.toml, and passes the backend from [system] rmw through the workspace helper. Setting them by hand there means two answers to one question.

What about installing?

nano-ros has no install(...) rules. It is consumed in source form — never out of an installed prefix. If you need a shippable artefact, your user project owns the install layout; ship your binary, not nano-ros itself.

For RTOS users who want a more idiomatic surface than raw add_subdirectory, see the integration shells under integrations/<rtos>/ in the SDK root — they translate NuttX / PX4 manifests into the same root CMake. Each shell is a ~20-line wrapper around add_subdirectory(<sdk root>).

What the in-tree examples do instead

Worth reading as the contrast, because it is the shape most projects want. The C node package nros new c_talker_ws --board linux --template talker --lang c scaffolds is a dozen lines and sets no cache variable at all:

cmake_minimum_required(VERSION 3.22)
project(c_talker_node LANGUAGES C)

find_package(nano_ros REQUIRED)
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_node::Talker
    EXECUTABLE c_talker_node
    SHAPE configure
    TYPED)

The board, the RMW, the domain and the network identity are not in that file — they are in the bringup’s system.toml, and the build reads them from there. nros build generates the CMake root that adds the package and the image’s entry, under build/, and passes the board’s toolchain file; its message bindings are a CMake-time output.

All the C/C++ examples follow that shape. The add_subdirectory mechanism on this page sits underneath it.

The Target Model

Every place an image can run is described the same way: a launcher or a flasher (a host process, an emulator, or a tool that programs a board), a console (where the image’s output appears), and a link (how its middleware reaches the rest of the system). nros reads these from the board’s descriptor, so the same commands work on every board.

• nros run launches an image on the host or in an emulator.
• nros flash programs a real board, and nros monitor attaches to its console.
• nros bench records which board on your machine is on which port.

This page is coming soon. Until then, see the nros CLI reference.

Design background

• RFC-0118: target execution model

Running an Image: nros run

nros run builds the image if it is stale, starts what its link needs, and streams the console, for host images and emulators. nros run --expect '<line>' exits successfully when that line appears, which makes it a one-line smoke test. On a real board it refuses and names the flashing step instead.

This page is coming soon. Until then, see nros run in the nros CLI reference and Deployment Workflow.

Design background

• RFC-0118: target execution model

Flashing and Monitoring a Board

nros flash programs a real board with a built image, and nros monitor attaches to its console. Both read how to do it from the board’s descriptor.

This page is coming soon. Until those verbs are available for your board, flash with the board vendor’s own tools; see Deployment Workflow.

Design background

• RFC-0118: target execution model

Your Bench: nros bench

nros bench records which board on this machine is connected to which serial port and debug probe, so nros flash and nros monitor find it without being told each time.

This page is coming soon.

Design background

• RFC-0118: target execution model

Run Plans

Before it runs anything, nros run resolves a run plan: which launcher or flasher, which console and which link, and where each fact came from. The facts come from five levels, highest first: the command line, the image, your machine’s bench file, the board’s descriptor, and the runner’s defaults. --plan prints the plan without running it.

This page is coming soon.

Design background

• RFC-0118: target execution model

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.

When nros build drives the build

The rows above are for a project whose build already exists. A nano-ros workspace (Growing your workspace) has no build of its own to integrate into: nros build generates each image’s entry and the build root that compiles it under build/, then runs the platform’s own tool on it. Which tool follows from the image:

The tool is not hidden behind nano-ros. Compiler errors are the compiler’s, unchanged. nros build <image> --dry-run prints the exact command for an image, and running it yourself works. No command line names a --target: the board’s triple, linker flags and QEMU runner are in the settings generated for that image. On Zephyr, nros build prints Zephyr’s next command for the image’s own build directory, west build -d <dir> -t run for an emulated board or west flash -d <dir> for one with a flash runner.

Per platform

The nros setup name to provision each platform, where its copy-out talkers live, and its chapter:

Each platform directory holds one copy-out talker per language, at <lang>/talker/: a workspace with one node package and a bringup with no launch/, whose launch file is generated. Copy its directory anywhere and build it there; it is the example to start from.

The paired examples are not separate directories. Talker and listener, service server and client, and action server and client are image rows of the language workspaces examples/workspaces/{rust,c,cpp}, under one bringup per behaviour: pubsub_bringup, service_bringup and action_bringup. An image id is <platform>_<role>, plus _<rmw> for any RMW other than zenoh, so one role on one platform is one command:

nros run pubsub_bringup:freertos_listener
nros run service_bringup:zephyr_service_server_xrce

Variants with different code are node packages of their own, configurations such as a serial link are image rows that state the knob, and the Linux feature demos (logging, parameters, lifecycle, custom messages) live in examples/workspaces/features. The multi-node workspace examples all live under examples/workspaces. Coverage Matrix shows which platform, language and RMW combinations have examples.

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
• A project with several nodes or boards: Growing your workspace
• If the first build fails: Troubleshooting — First 10 Minutes

Design background

• RFC-0122: behaviour bringups, single-node witnesses, and cadence-backed CI. The copy-out talker per platform and language, and the paired examples as image rows of behaviour bringups.

Native (Host) Build

Use the host (linux) board for first experiments, CI smoke tests, and ROS 2 interoperability checks on Linux. It uses OS sockets, the host process environment, and the same project layout as the embedded targets.

The host board is named linux ([image.<id>] board = "linux") because that is all it supports: the platform layer (nros-platform-posix) is POSIX, but the host board crate’s apply_tier_affinity calls sched_setaffinity with cpu_set_t, which libc does not define for macOS, Windows or FreeBSD. Only Linux is supported. Neither native (every general-purpose host) nor posix (the platform) names a board: board = "…", nros setup, and nros new --board refuse both with a hint naming linux.

When to Use It

• You want the shortest path to a working nano-ros publisher or subscriber.
• You are validating message generation, CMake integration, or ROS 2 interop before moving to an RTOS.
• Your deployment target is Linux or an embedded Linux system.

Setup

Install the nros CLI (Installation), then provision the native host. For a host build there is no cross-toolchain to fetch — nros setup linux installs the client stack (and for xrce the Micro-XRCE-DDS agent) into a shared store. The zenoh router is NOT installed: it comes from a ROS 2 install (ros2 run rmw_zenoh_cpp rmw_zenohd). Rather not run a router? Use --rmw cyclonedds — it needs no daemon. Either way the first build generates the messages from your ROS 2 install, so it needs ROS 2 sourced.

With the nros CLI on PATH (Installation — install.sh puts it in ~/.nros/bin):

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

linux is this board’s one name; posix names the platform layer underneath it, and native names no board at all (Retired names).

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

colcon build && source install/setup.bash

Workspace Layout

A host project is a workspace, like every other board’s:

nros new host_ws --board linux --template talker --lang rust   # or --lang c / cpp
cd host_ws

host_ws/
└── src/
    ├── host_node/              # node package: package.xml + Cargo.toml (or CMakeLists.txt), the node
    └── host_node_bringup/      # package.xml and system.toml: board, rmw, domain, components

The node package is a library with no main(); the bringup’s [image.linux] block (board = "linux") is what makes it a host program. The examples on GitHub are copy-out ready: nothing in one names a path into the SDK. nros finds its own SDK; --nano-ros-path names another.

Code Example

A Rust node package’s src/lib.rs declares what the node creates and what its callbacks do, and exports the node; the entry that opens the executor and spins it is generated:

pub struct Talker;

impl Component for Talker {
    const NAME: &'static str = "talker";
    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::<StringMsg>("/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 { … the timer callback publishes "Hello World: N" … }

nros::node!(Talker);

Use the full First Node — Rust walkthrough for generated messages and runnable commands, and Growing your workspace for each line of lib.rs.

Build and Run

Start the RMW host daemon (the router comes from ROS 2). For zenoh:

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

Then build and run the node from the workspace root, in a shell that has sourced ROS 2. The first build generates the messages from it and records the prefix, so later runs need no sourced shell:

source /opt/ros/humble/setup.bash
nros run host_node

nros run builds first if anything changed. nros build alone prints the binary’s path under build/, which runs directly too. For a workspace that lives in a colcon consumer workspace, colcon build && source install/setup.bash && ros2 run … works as well.

Configuration

Native examples can read runtime settings from the shell:

export ROS_DOMAIN_ID=0
export NROS_LOCATOR=tcp/127.0.0.1:7447

The same fields are compiled into embedded targets through their platform-specific configuration files. See Configuration for the full layering.

Deployment

Host deployment is normal process deployment: install the workspace, source install/setup.bash, set environment, and run the binary. For ROS 2 interop, run ROS 2 Interoperability and set the ROS side to rmw_zenoh_cpp.

Design background

• RFC-0075: zenoh router provenance

FreeRTOS (QEMU MPS2-AN385)

Support level: mps2-an385-freertos, freertos-posix, s32z270-freertos, mps3-an536-freertos. Each page states what nano-ros can show for the board (where it runs, how often, and its breadth), generated from the board support registry; Board Support Levels explains the words.

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 are on GitHub as reading material; this page scaffolds your own.

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

With the nros CLI on PATH (Installation — install.sh puts it in ~/.nros/bin), 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.

Project layout

nros new scaffolds a workspace for the board, in any of the three languages:

nros new fr_ws --board mps2-an385-freertos --template talker --lang c      # or --lang cpp
cd fr_ws

nros new fr_ws --board mps2-an385-freertos --template talker --lang rust
cd fr_ws

fr_ws/
└── src/
    ├── fr_node/                 # node package: package.xml + CMakeLists.txt (or Cargo.toml), the talker
    └── fr_node_bringup/         # package.xml and system.toml: the board, the RMW, the node

fr_node is a library: no main(), no board, no RMW. The bringup’s system.toml holds one image, [image.freertos], with board = "mps2-an385-freertos". The program’s entry, the FreeRTOS startup task that runs your node, is generated from that image at build time.

Nothing else states the deployment. The Rust side 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 build under build/. A C or C++ node package has no <nano_ros deploy=… board=… rmw=…/> tuple in its package.xml and names no board in its CMakeLists.txt.

The board crate (nros-board-mps2-an385-freertos) wraps the kernel + lwIP + LAN9118 driver build; the generated entry depends on it, so nothing you write names it.

Configure

Board, RMW, domain and network identity are declared in the bringup’s system.toml and baked at compile time — there is no config file on the device. With a locator and an address added, src/fr_node_bringup/system.toml reads:

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

[[component]]
pkg = "fr_node"
class = "fr_node::Talker"
name = "fr_node"

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

locator is where the router is (the QEMU guest reaches the host’s router through the Slirp gateway 10.0.2.2); os_config names the board network file, board-net.toml beside system.toml in the bringup. The file is the same whatever language the node is written in. Nothing about the deployment lives in Cargo.toml, in CMakeLists.txt, or in the package.xml <export> block.

Switching board is editing [image.<id>] board and rebuilding: nros build picks the cross-toolchain file the board names, and the generated entry brings the board crate, its RMW and nros-platform’s FreeRTOS feature.

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 image above dials host port 7800; with no locator, as scaffolded, an image dials the board’s default (tcp/10.0.2.2:7447).

Changing this in the tree: see Internals → per-platform lanes.

Build

The build generates the message bindings from your ROS 2 install, so source it in this shell first. This first build records the ROS 2 prefix in the workspace, so later builds and runs of it need no sourced shell.

In the workspace root (fr_ws/, where nros new left you), whatever the language:

source /opt/ros/humble/setup.bash
nros build

nros build prepares the build first (message bindings, the resolved launch model, the generated entry for [image.freertos]), then hands off to cargo or CMake with the board’s cross-toolchain file and the SDK root. There is no step to run before it.

The first build cross-compiles nano-ros’s dependencies and the FreeRTOS kernel

• lwIP (~3 min for C / C++, ~5 min for Rust). The ELF lands under build/. nros build --dry-run prints the native commands without building.

After a successful build nros build prints what it built and the command that runs it — a block like

nros build: next for `fr_node_bringup:freertos`:
  artifact: /home/you/fr_ws/build/…/freertos_entry
  run:
    nros run fr_node

Driving the native tool yourself is the escape hatch, not the path. nros build --dry-run prints the exact cargo build … or cmake lines, run against the generated entry under build/. To write that entry without building (an IDE, a CI cache step), run:

nros configure

For a CMake tree that is not a nano-ros workspace at all, see Build as a CMake subdirectory.

See When nros build drives the build for which tool builds each image.

Run on QEMU

Three terminals: the router, the board, and a stock ROS 2 peer.

1. The router — ROS’s rmw_zenohd, on the port your image’s locator names (7447 when it names none, as a scaffolded image; 7800 in the example shown above). It must listen on 0.0.0.0 for the Slirp gateway: Slirp forwards the guest’s 10.0.2.2:<p> to the host’s <p>.

source /opt/ros/humble/setup.bash
ZENOH_CONFIG_OVERRIDE='listen/endpoints=["tcp/0.0.0.0:7447"];scouting/multicast/enabled=false' \
    ros2 run rmw_zenoh_cpp rmw_zenohd

Started Zenoh router with id

2. The board — from the workspace root:

nros run fr_node

nros run rebuilds if anything changed, then boots the image in QEMU with the board’s runner: the store’s patched qemu-system-arm (nros setup mps2-an385-freertos installed it), the LAN9118 on Slirp, and -icount shift=auto, which keeps the board’s timer in step with Slirp’s I/O. It streams the semihosting console until you press Ctrl-C.

The scaffolded talker publishes std_msgs/String once a second, in every language:

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

3. A stock ROS 2 peer. The talker publishes best-effort; stock ros2 topic echo defaults to RELIABLE, so the QoS-mismatched echo silently delivers nothing. Force best-effort to receive:

source /opt/ros/humble/setup.bash
export RMW_IMPLEMENTATION=rmw_zenoh_cpp
ros2 topic echo /chatter std_msgs/msg/String --qos-reliability best_effort

It prints a data: line per message:

data:

Ctrl-C stops nros run and QEMU with it.

Readiness signal. Within ~20 seconds of QEMU boot, the image prints Publishing: 'Hello World: 1' on its semihosting stdout — a std_msgs/String counted from 1, like 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 (Slirp forwards 10.0.2.2:<p> → host:

   ). Without it the talker makes one connection attempt and stops with Failed to open session; a board that should wait for a late router sets [knobs.zenoh.limits] connect_forever = true (or connect_timeout_ms for a bounded wait).

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.

Run on the POSIX simulator

The freertos-posix board runs the FreeRTOS kernel as an ordinary Linux process (FreeRTOS’s POSIX port) — no QEMU, host networking. It is a C / C++ board (it has no Rust entry shape). Provision it, point the image of a C or C++ workspace at it, and run:

nros setup freertos-posix --rmw zenoh
# in src/fr_node_bringup/system.toml:  [image.freertos] board = "freertos-posix"
nros run fr_node

The image dials the router on the host directly (no Slirp gateway), so start rmw_zenohd on the port its locator names, as in Run on QEMU step 1.

Flash a real board

No in-tree FreeRTOS board is flashed by a documented flow, and none is claimed: the MPS2-AN385 boards above are QEMU machines.

• NXP S32Z270 (s32z270-freertos; its status is on its board page). No emulator models its Cortex-R52 RTU, so nothing here boots it. It builds like the other boards — the licensed pieces (NXP’s GCC/ARM_CR52_GIC FreeRTOS port, the RTD NETC Ethernet driver, the S32 Config Tools PBcfg) are yours to supply, as its descriptor explains — and the ELF is flashed with your own S32 tooling (S32 Design Studio, a Lauterbach/PEmicro probe); nano-ros adds no flash step:

  nros setup s32z270-freertos --rmw zenoh
  # in src/fr_node_bringup/system.toml, a second image:
  #   [image.s32z] board = "s32z270-freertos"
  nros build s32z
  # → nros build prints the ELF path; flash it with your S32 tooling
  

• Your own FreeRTOS board is a board package of your own — see Adding a FreeRTOS Board — and is flashed with whatever that board’s vendor uses (probe-rs, OpenOCD, a vendor IDE).

Neither flash path is run by any probe (a CI runner has no board): both stand unverified until run against a named board. How often the QEMU line above runs is on each board’s page under Supported Boards.

GitHub source

The copy-out talkers for this board, one per language. Each is the same project this page scaffolds: one node package and a bringup with no launch file of its own.

• Rust: examples/mps2-an385-freertos/rust/talker/
• C: examples/mps2-an385-freertos/c/talker/
• C++: examples/mps2-an385-freertos/cpp/talker/

Next

• Subscriber, services and actions: the freertos_* image rows of the language workspaces, examples/workspaces/{rust,c,cpp}, one bringup per behaviour (pubsub_bringup, service_bringup, action_bringup). nros run pubsub_bringup:freertos_listener runs the listener; freertos_listener_xrce is the same role over XRCE.
• No RTOS: the Bare-metal Cortex-M3 page is the same board without FreeRTOS.
• 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.

Design background

• RFC-0122: behaviour bringups, single-node witnesses, and cadence-backed CI. The copy-out talker per platform and language, and the paired examples as image rows of behaviour bringups.

Zephyr (west module)

Support level: native_sim, mps2_an385, the S32K344 safety island. Each page states what nano-ros can show for the board (where it runs, how often, and its breadth), generated from the board support registry; Board Support Levels explains the words.

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.

Changing this in the tree: see Internals → in-tree examples.

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. nros build generates the messages from your ROS 2 install, so its first build of a workspace needs ROS 2 sourced. 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; the lanes are in Internals → Zephyr in-tree examples.

Project layout

A nano-ros project on Zephyr is a workspace like on every other platform, beside the west workspace that holds Zephyr. Your code is node packages; the bringup’s system.toml names the board. The Zephyr application is generated: nros build writes it under build/ and runs west build on it.

my_zephyr_ws/                          # the west workspace: Zephyr and its modules
├── .west/
├── manifest/west.yml
├── zephyr/                            # cloned by `west update`
└── modules/
c_ws/                                  # the nano-ros workspace
├── src/
│   ├── c_node/                        # your node package
│   └── c_node_bringup/
│       ├── package.xml
│       └── system.toml                # [image.zephyr] board = "zephyr"
└── build/                             # generated, the Zephyr application among it

Quick start builds exactly this. An application that owns its west build and has no bringup (its own CMakeLists.txt and prj.conf, with nano-ros added as one more module) is the subject of its own chapter, A Zephyr App You Build with West.

Prerequisites

nros setup zephyr provisions what the index declares for the board — the Zephyr SDK ([board.zephyr] packages = ["zephyr-sdk"]) and the RMW transport sources (zenoh-pico + mbedtls for zenoh, the cyclonedds fork) — from a pinned index into ${NROS_HOME:-~/.nros}/sdk. The Zephyr sources and modules themselves are a west workspace, which you keep the standard Zephyr way. It provides no zenoh router: that is ROS’s rmw_zenohd (see the RMW design); Cyclone DDS needs no daemon at all.

1. Get the nros CLI — install a release with scripts/install.sh (Installation); it lands in ~/.nros/bin.
2. Provision the board + RMW:

   nros setup zephyr --rmw zenoh       # Zephyr SDK + zenoh-pico + mbedtls
   nros setup --source px4-rs          # workspace cargo-load dep
   

3. Point Zephyr at the SDK if your shell does not already find it — export ZEPHYR_SDK_INSTALL_DIR="$(nros locate tool zephyr-sdk)", which prints where nros setup installed it (or register it via the SDK’s setup.sh -c).
4. Source ROS 2 for the first build. nros build generates the message bindings from your ROS 2 install’s definitions, std_msgs included, so the types match your ROS 2 peers: source /opt/ros/humble/setup.bash before the first nros build, nros run or nros configure of a workspace. That configure records the prefix, so later shells need not source ROS.

The zenoh router must be running before an example connects (ZENOH_CONFIG_OVERRIDE='listen/endpoints=["tcp/127.0.0.1:7447"];scouting/multicast/enabled=false' ros2 run rmw_zenoh_cpp rmw_zenohd); for xrce, the Micro-XRCE-DDS agent nros setup … --rmw xrce installed; for cyclonedds, nothing.

Quick start: a talker on native_sim, from nothing

The sections after this one explain each piece; this is the whole path in order, for a C talker on native_sim (a host executable, so no emulator). Zephyr’s own host tools come first — west and the build tools Zephyr’s Getting Started lists; nros setup installs no system packages. On Debian/Ubuntu:

sudo apt-get install -y --no-install-recommends git cmake ninja-build gperf \
    device-tree-compiler python3-pip python3-venv xz-utils file wget
pip3 install --user west
export PATH="$HOME/.local/bin:$PATH"

Provision the board and RMW (the Zephyr SDK, zenoh-pico, mbedtls):

nros setup zephyr --rmw zenoh
export ZEPHYR_SDK_INSTALL_DIR="$(nros locate tool zephyr-sdk)"

A west workspace that pins Zephyr 3.7 and fetches only the modules nano-ros’s boards build with (nros setup zephyr lists them; import: true would fetch every vendor HAL, ~2.5 GB more):

mkdir -p my_zephyr_ws/manifest && cd my_zephyr_ws
cat > manifest/west.yml <<'WEST_YML'
manifest:
  remotes:
    - name: zephyrproject-rtos
      url-base: https://github.com/zephyrproject-rtos
  projects:
    - name: zephyr
      remote: zephyrproject-rtos
      revision: v3.7.0
      import:
        name-allowlist: [cmsis, picolibc, mbedtls, tinycrypt, mcuboot, net-tools]
    # Rust support: only a Rust app builds with it. Pinned to the revision
    # nano-ros's own west.yml pins for the 3.7 line (it has no release tags).
    - name: zephyr-lang-rust
      remote: zephyrproject-rtos
      revision: 404fcefdbab0f2711cd342a1fab9d2eda52a1ba9
      path: modules/lang/rust
  self:
    path: manifest
WEST_YML
west init -l manifest
west update --narrow -o=--depth=1
pip3 install --user -r zephyr/scripts/requirements-base.txt
export ZEPHYR_BASE="$PWD/zephyr"

Scaffold a workspace beside the west workspace: a C talker node package and its bringup, whose image runs on board zephyr (Zephyr’s native_sim/native/64). nros build writes the Zephyr application for that image under build/ and runs west build on it, from the west workspace NROS_ZEPHYR_WORKSPACE names. You write no CMakeLists.txt and no prj.conf.

The board package also applies nano-ros’s nros-nsos snippet, which routes the image’s sockets to the host’s (Zephyr’s NSOS) instead of a TAP interface. Without it native_sim tries to create one (eth_posix: Cannot create zeth), which needs privileges a container or an ordinary user does not have, and the image never reaches the router.

The first build generates the message bindings from your ROS 2 install, so source it in this shell first. It records the ROS 2 prefix in the workspace, so later builds and runs of it need no sourced shell.

source /opt/ros/humble/setup.bash
export NROS_ZEPHYR_WORKSPACE="$PWD"
cd ..
nros new c_ws --board zephyr --template talker --lang c --rmw zenoh
cd c_ws
nros build

That wrote two packages, the same shape every platform’s scaffold has:

c_ws/
└── src/
    ├── c_node/            # the talker: package.xml, CMakeLists.txt, its C source
    └── c_node_bringup/    # package.xml, and system.toml: [image.zephyr] board = "zephyr"

Run it against a router on the host’s loopback — native_sim uses the host’s sockets, and the image dials tcp/127.0.0.1:7447 unless the bringup’s system.toml states a locator:

source /opt/ros/humble/setup.bash
ZENOH_CONFIG_OVERRIDE='listen/endpoints=["tcp/127.0.0.1:7447"];scouting/multicast/enabled=false' \
    ros2 run rmw_zenoh_cpp rmw_zenohd

Started Zenoh router with id

With the router running, run the talker:

nros run c_node

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

An application you already build with west. A Zephyr application that keeps its own CMakeLists.txt and prj.conf and has no bringup is not a workspace image: it adds the nano-ros module to a plain west build, as A Zephyr App You Build with West shows.

The same talker in Rust. The scaffold is the same with --lang rust, and so is everything nros build does with it. Make it beside the west workspace above.

zephyr-lang-rust needs three things the C app does not: the Rust target the Zephyr board implies (x86_64-unknown-none for native_sim/64 on an x86_64 host), rustup’s clippy (it lints every Rust app as part of the build), and clang and libclang, for the bindings it generates from Zephyr’s headers. nros setup in the workspace installs the target and clippy, and with --sudo the two packages (without it, it prints the install command). nros build refuses a Rust Zephyr image that lacks any of them, naming the command.

source /opt/ros/humble/setup.bash
. "$HOME/.cargo/env"     # the cargo `nros setup` installed (Installation)
export NROS_ZEPHYR_WORKSPACE="$PWD"
cd ..
nros new rs_ws --board zephyr --template talker --lang rust --rmw zenoh
cd rs_ws
nros setup --sudo
nros build

With the router above running, run it:

nros run rs_node

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

Configure

nano-ros’s Zephyr module ships in the installed SDK — the SDK root (the release’s share/nano-ros; nros locate nano-ros prints it) holds its zephyr/module.yml. You do not add nano-ros to your west.yml: nros build names the module on the west build line it runs (-DZEPHYR_EXTRA_MODULES=<sdk root>), and a west build you run yourself passes the same:

west build -b native_sim/native/64 apps/my_app -- \
    -DZEPHYR_EXTRA_MODULES="$(nros locate nano-ros)"

Your west.yml pins Zephyr itself (and whatever modules your application uses) the standard Zephyr way:

manifest:
  remotes:
    - 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

The transport sources the module compiles (zenoh-pico, mbedtls, the Cyclone DDS fork) come from nros setup zephyr --rmw <rmw>, not from west.

Then nano-ros’s half of the configuration goes in the bringup’s system.toml, and Zephyr’s own half in prj.conf fragments (in a workspace, under the bringup’s boards/<board>/, as Growing your workspace shows):

# src/c_node_bringup/system.toml
[system]
name = "c_node_bringup"
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 in its own prj.conf (A Zephyr App You Build with West).

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.

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

An image’s nano-ros configuration lives in ONE place, the bringup’s system.toml. 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. 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

A bringup 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"
os_config = ["prj-zenoh.conf"]

[image.zephyr_xrce]
board = "zephyr"
rmw = "xrce"
os_config = ["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"
os_config = ["prj-cyclonedds.conf"]

nros build                    # the default_images: zephyr_zenoh
nros build zephyr_xrce        # another image — its own west build dir

Each image builds into its own directory, build/<platform>-<rmw>/<package>__<image>_west, so switching images never reuses another image’s cache.

To run west yourself on one image, nros build zephyr_xrce --dry-run prints the west build line for that image’s generated application and its own build directory.

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

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 Zephyr + its modules 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

On every platform nros build generates the image’s entry under build/ and runs the platform’s tool on it. On Zephyr the entry is a Zephyr application and the tool is west build. What stays yours is the west workspace: west init / west update populate it, it pins your Zephyr, and nano-ros never writes into it.

So for a Zephyr image nros build:

1. writes the application for that image under build/, from the image’s board and the bringup’s nodes (or uses src/<image>_entry/, if you have taken it over with nros materialize);
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 lets the application live under your workspace’s build/, outside the west workspace;
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 …/build/…/demo_bringup__zephyr_west

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.

nros build is the flow this chapter teaches: it applies the image’s overlays, picks the build directory and, when it finishes, prints the artifact and the Zephyr command that runs or flashes it. It never becomes a required layer between you and west — a Zephyr app you build with west stays the escape hatch, for an application that owns its west build and has no bringup.

Starting from nothing: nros new

nros new rs_ws --board zephyr --template talker writes a workspace whose bringup already has a Zephyr image, as in the quick start. Inside a workspace, a further 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 talker_pkg --template talker --to demo_bringup

It writes the package and, with --to, adds the [[component]] row to that bringup. There is no Zephyr application to scaffold: nros build and nros run generate it from the image.

Owning the application: nros materialize

The generated application takes the image’s keys (board, os_config, the RMW) and the board package’s Kconfig and devicetree overlay, and most changes are one of those. When a change is none of them, and the application’s own CMakeLists.txt or prj.conf has to change, take it over:

nros materialize zephyr

That writes the generated application into src/zephyr_entry/ as a package of yours, and from then on nros build builds that copy and does not regenerate it. Deleting src/zephyr_entry/ returns the image to generation. It is the last resort, for the reasons Customising an entry gives.

The whole flow, end to end

Four 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. build. This generates the message bindings the workspace's packages
#    depend on, resolves the application, applies the image's overlays and
#    runs `west build` for you.
nros build demo_bringup:zephyr

# 2. 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

# 3. run the image — `nros build` printed this, with its own build dir
#    (build/<coordinate>/<bringup>__<image>_west):
west build -d build/zephyr-zenoh/demo_bringup__zephyr_west -t run
#    (on native_sim that runs ./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: Publishing: 'Hello World: 1'
<inf> rust: talker_pkg: Publishing: 'Hello World: 2'

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: 'Hello World: 6'
---

Step 2 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"
conf  = ["prj-zenoh.conf"]      # the RMW overlay this app requires

None of them sets entry: nros build generates each image’s application.

• os_config 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. 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.

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 — a checkout of this repository, or a mirror of a release you vendor (see Pin and mirror a release). With the installed SDK alone there is no west nros: west reads extension commands from a manifest project, and the installed SDK root is a versioned directory under ~/.nros that no west.yml can name. Name the Zephyr workspace to nros instead, which is what west nros does for you:

nros build --zephyr-workspace ~/zephyr-workspace demo_bringup:zephyr

west nros is the only nano-ros west extension; to run an image, use 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.

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. nros build runs a plain west build, so the extension points are untouched. The first row edits the application’s CMakeLists.txt, so it needs an application you own (nros materialize); the rest do not:

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]
os_config = ["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: Publishing: 'Hello World: 1'

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.

Driving west yourself

An application with no bringup, built with a plain west build and configured in its own prj.conf, is covered in A Zephyr App You Build with West: adding the module, the Kconfig settings that replace system.toml, messages, and running it.

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 before the first west build, which does not run nano-ros’s preparation for a Rust app. From your app dir, run (after the Prerequisites nros setup, which provides the codegen toolchain), in a shell that has sourced ROS 2 (the message definitions come from it; this configure records the prefix for later runs):

   source /opt/ros/humble/setup.bash
   nros configure
   

   This writes generated/<pkg>/ (the message crates) and a .cargo/config.toml whose [patch.crates-io] points the nros-* crates into the nano-ros SDK root and the generated interfaces at generated/*. --nano-ros-path <dir> names another root (the SDK ROOT, the directory holding nano_rosConfig.cmake).

Run

nros build ends by printing what to type next, read from the finished build itself — the emulators Zephyr’s board declares (run_<emu> targets in build.ninja) and its flash runner (zephyr/runners.yaml). For an image in build directory <dir> that is one or both of

west build -d <dir> -t run        # an emulated board: native_sim, QEMU
west flash -d <dir>               # a board with a flash runner

Both are Zephyr’s own commands; nano-ros adds nothing to them. The router comes first either way:

# 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 &

Run on native_sim

board = "zephyr" is Zephyr’s native_sim/native/64: the image is a host executable, and its sockets are the host’s (NSOS), so it reaches the router on loopback with no network setup.

nros build demo_bringup:zephyr
west build -d build/zephyr-zenoh/demo_bringup__zephyr_west -t run
# — the same as running the executable directly:
./build/zephyr-zenoh/demo_bringup__zephyr_west/zephyr/zephyr.exe

(A build you drove with plain west build, into west’s default build/: west build -t run, or ./build/zephyr/zephyr.exe.)

Run on QEMU (mps2-an385)

The Cortex-M3 witness is Zephyr’s mps2/an385 under QEMU, with Zephyr’s own IP stack on the emulated SMSC911x. An image names it board = "mps2-an385-zephyr"; west build -t run boots it under the QEMU the Zephyr SDK ships (nros setup zephyr installed it). In the Rust workspace above, a second image is that board. nros setup board comes first: it applies nano-ros’s patch set to your west workspace, without which zephyr-lang-rust’s cargo command carries none of nano-ros’s settings for the board (among them the C cross compiler the zenoh-pico crate builds with), and adds the board’s Rust target. The image is one more block in the bringup:

nros setup board mps2-an385-zephyr --zephyr-workspace "$NROS_ZEPHYR_WORKSPACE"
cat >> src/rs_node_bringup/system.toml <<'TOML'

[image.zephyr_m3]
board = "mps2-an385-zephyr"
TOML
nros setup --sudo
nros build zephyr_m3

The guest sits on QEMU’s user-mode network, and the board package states it: its prj.conf gives the image 10.0.2.15 (gateway 10.0.2.2) and the locator tcp/10.0.2.2:7447, and nros build applies it, so there is nothing to set. The Slirp gateway 10.0.2.2 is the host, so the router above is reachable. An image whose router listens elsewhere states its own locator in system.toml.

With two images in the bringup, name the one to run:

nros run zephyr_m3

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

Verify from stock ROS 2

# The scaffolded talker publishes std_msgs/String (the talker in
# "A Zephyr App You Build with West" 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

The Zephyr boot banner runs first, then the talker fires: it prints Publishing: 'Hello World: 1', Publishing: 'Hello World: 2', … (Rust + C + C++ all count from 1, matching the official ROS 2 demo talker).

Readiness signal. On native_sim, expect the first publish line (Publishing: 'Hello World: 1') within 5 seconds of boot; on a QEMU board (mps2-an385-zephyr, or a qemu_cortex_a9 you built yourself) 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).

Flash a real board

The boards above are native_sim and QEMU machines, and the ARM FVP is a model (its chapter). The hardware boards nano-ros ships a package for are the Nucleo-F767ZI (board = "nucleo-f767zi-zephyr"), whose Renode twin boots the same image (its chapter), and the Raspberry Pi Pico W (board = "rpi-pico-w-zephyr"), whose Wokwi twin does; the Pico W’s own chapter is still to come. Any board Zephyr supports is reached with a board package that names it (west_board, see Which boards you can name), and flashed with the runner Zephyr’s own board definition declares:

# src/my_board/nros-board.toml names west_board = "nucleo_f767zi" (say);
# in system.toml:  [image.nucleo] board = "my-board"
nros build demo_bringup:nucleo
west flash -d build/zephyr-zenoh/demo_bringup__nucleo_west

Not replayed. No probe runs this flash line (a CI runner has no board), so it is written from the board’s runner, not measured (tracking issue).

nros build prints that west flash line when the build’s zephyr/runners.yaml names a flash runner. The runner (J-Link, nrfjprog, OpenOCD, pyOCD, …) and its probe are Zephyr’s and your bench’s; nano-ros adds nothing to them. The board must also have a network nano-ros can use.

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. 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. Both lines now use the provisioner. Cyclone-DDS-on-Zephyr patches stay baked into the pinned cyclonedds submodule, not delivered through patches.yml.)

Start from an example

The copy-out talkers under examples/zephyr/<lang>/talker/ on GitHub, one per language, are copy-out clean, with no reference back into the nano-ros repository. Each is the same project as the quick start’s: one node package and a bringup with no launch file of its own, whose launch file is generated. Their node sources are a starting point to copy into your own node packages.

The other roles are image rows of the language workspaces, examples/workspaces/{rust,c,cpp}, one bringup per behaviour: pubsub_bringup, service_bringup and action_bringup. A Zephyr image id is zephyr_<role>, plus _<rmw> for any RMW other than zenoh, so

nros run pubsub_bringup:zephyr_listener_xrce

builds and runs the XRCE listener. The release does not ship examples/; nros new <ws> --board zephyr --template <role> --lang <c|cpp|rust> writes any role as a workspace of your own.

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/
• Copy-out talkers: examples/zephyr/rust/talker/, examples/zephyr/c/talker/, examples/zephyr/cpp/talker/
• The other roles: the zephyr_* image rows of the language workspaces’ pubsub_bringup, service_bringup and action_bringup
• Module manifest: zephyr/module.yml
• Kconfig surface (canonical — every CONFIG_NROS* symbol the doc cites lives here): zephyr/Kconfig
• Patches applied by nros setup zephyr (the west patch flow is retired): zephyr/patches.yml

Next

• Pick a real board (Nordic, NXP, STM32, …): a board package naming its west_board, then Flash a real board.
• 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 in-tree examples (contributor).

Design background

• RFC-0122: behaviour bringups, single-node witnesses, and cadence-backed CI. The copy-out talker per platform and language, and the paired examples as image rows of behaviour bringups.

A Zephyr App You Build with West

Support level: native_sim. Each page states what nano-ros can show for the board (where it runs, how often, and its breadth), generated from the board support registry; Board Support Levels explains the words.

In this chapter you add a ROS 2 talker to a Zephyr application that you already build with west build, run it on native_sim against a ROS 2 router, and then flash the same application to a real board. The application keeps its own CMakeLists.txt and prj.conf; nano-ros joins it as one more Zephyr module.

What this assumes: a Linux host with ROS 2 Humble and its Zenoh middleware (ros-humble-rmw-zenoh-cpp), the install done so nros is on your PATH, and some familiarity with west: a manifest, west update, west build -b <board>.

What it leaves for later: a project with several nodes, several boards, or a launch file. That is a nano-ros workspace, which the Zephyr chapter builds.

When to choose this

There are two ways to put a ROS 2 node on Zephyr.

• A nano-ros workspace (nros new my_ws --board zephyr). Your code is node packages; a bringup package says which board each image runs on. nros build writes the Zephyr application for you and runs west build on it, and nros run starts it. You write no CMakeLists.txt for Zephyr and no prj.conf. Start there if you are starting fresh, or if the project will grow past one node. The Zephyr chapter covers it.
• Your own west application (this chapter). The Zephyr application already exists, owns its build, and has its own drivers, devicetree and prj.conf. You want a ROS 2 node inside it, and you want west build and west flash to stay the commands you type.

The second road has no bringup and no system.toml. Everything nano-ros needs to know about the image comes from prj.conf, the way any Zephyr module is configured.

Set up the host and the west workspace

Zephyr’s host tools come first: west and the build tools Zephyr’s Getting Started lists. nros setup installs no system packages. On Debian or Ubuntu:

sudo apt-get install -y --no-install-recommends git cmake ninja-build gperf \
    device-tree-compiler python3-pip python3-venv xz-utils file wget
pip3 install --user west
export PATH="$HOME/.local/bin:$PATH"

Provision the Zephyr SDK and the zenoh transport sources nano-ros compiles, then point Zephyr at that SDK:

nros setup zephyr --rmw zenoh
export ZEPHYR_SDK_INSTALL_DIR="$(nros locate tool zephyr-sdk)"

nros locate tool zephyr-sdk prints where nros setup installed the Zephyr SDK version this release of nano-ros pins, so the line keeps working when that version changes. If you already have a Zephyr SDK that your workspace builds with, keep using it: set ZEPHYR_SDK_INSTALL_DIR to that one instead, or register it with the SDK’s own setup.sh -c.

If you already have a west workspace, skip the next block. This one pins Zephyr 3.7 and fetches only the modules nano-ros’s boards use:

mkdir -p my_zephyr_ws/manifest && cd my_zephyr_ws
cat > manifest/west.yml <<'WEST_YML'
manifest:
  remotes:
    - name: zephyrproject-rtos
      url-base: https://github.com/zephyrproject-rtos
  projects:
    - name: zephyr
      remote: zephyrproject-rtos
      revision: v3.7.0
      import:
        name-allowlist: [cmsis, picolibc, mbedtls, tinycrypt, mcuboot, net-tools]
    - name: zephyr-lang-rust
      remote: zephyrproject-rtos
      revision: 404fcefdbab0f2711cd342a1fab9d2eda52a1ba9
      path: modules/lang/rust
  self:
    path: manifest
WEST_YML
west init -l manifest
west update --narrow -o=--depth=1
pip3 install --user -r zephyr/scripts/requirements-base.txt
export ZEPHYR_BASE="$PWD/zephyr"

The last project, zephyr-lang-rust, is Zephyr’s Rust support, at the revision nano-ros builds with on Zephyr 3.7. Only a Rust application uses it; leave it out if you write none.

nano-ros supports both the Zephyr 3.7 LTS line and the 4.x line; the version table lists what differs between them.

Add nano-ros to the build

nano-ros’s Zephyr module ships inside your nano-ros install. nros locate nano-ros prints the directory that holds it, and you hand that directory to west as an extra module:

west build -b native_sim/native/64 apps/my_app -- \
    -DZEPHYR_EXTRA_MODULES="$(nros locate nano-ros)"

You do not add nano-ros to west.yml, and nothing is cloned. The command needs no network, so it is also safe inside your own scripts and CI.

If you would rather not type the option on every build, ask for the path once in the application’s CMakeLists.txt, before find_package(Zephyr):

execute_process(COMMAND nros locate nano-ros
    OUTPUT_VARIABLE NROS_MODULE_DIR
    OUTPUT_STRIP_TRAILING_WHITESPACE
    COMMAND_ERROR_IS_FATAL ANY)
list(APPEND ZEPHYR_EXTRA_MODULES "${NROS_MODULE_DIR}")

With either form, a plain west build picks the module up.

Write the application

The application is a stock Zephyr application with four files:

my_zephyr_ws/
├── zephyr/
├── modules/
└── apps/
    └── my_app/
        ├── CMakeLists.txt     # find_package(Zephyr), then the node
        ├── package.xml        # the message packages the node uses
        ├── prj.conf           # Zephyr's settings and nano-ros's
        └── src/
            └── Talker.c       # the node

The node, in C

The node is a component: a struct that holds its state and a configure function that creates its publishers, subscriptions and timers. You do not write main(). The module generates the application’s entry point, which initialises the RMW session, creates the node and executor, calls your configure, and then spins the executor.

mkdir -p apps/my_app/src
cat > apps/my_app/src/Talker.c <<'EOF'
#include <stddef.h>
#include <stdint.h>
#include <stdio.h>

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

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

static void on_tick(rcl_timer_t* timer, int64_t last_call_time) {
    talker_t* self = RCLC_CONTAINER_OF(timer, talker_t, timer);
    (void)last_call_time;
    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) {
    setvbuf(stdout, NULL, _IONBF, 0);
    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_default(&self->timer, NULL, 1000ULL * 1000000ULL, on_tick);
    if (rc != RCL_RET_OK) {
        return rc;
    }
    return rclc_executor_add_timer(executor, &self->timer);
}

RCLC_C_COMPONENT(talker_t, talker_configure)
EOF

It publishes a counter as std_msgs/Int32 on /chatter once a second. RCLC_C_COMPONENT registers the struct and its configure function with the generated entry point. The rest is the ROS 2 rclc API.

The build file

cat > apps/my_app/CMakeLists.txt <<'EOF'
cmake_minimum_required(VERSION 3.20.0)
find_package(Zephyr REQUIRED HINTS $ENV{ZEPHYR_BASE})
project(my_app)

find_package(nano_ros REQUIRED)
find_package(std_msgs REQUIRED)

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

find_package(nano_ros) and find_package(std_msgs) are provided by the module. nano_ros_auto_add_library compiles your node source. nros_components_register_node registers the component, and DEPLOY zephyr is what makes the module generate the entry point into Zephyr’s app target. Your application’s other sources still go into app with target_sources, as before; nothing else about the file changes.

The C++ form

The same node in C++ is a class with a configure member. In place of Talker.c, write its header and its source:

mkdir -p apps/my_app/src
cat > apps/my_app/src/Talker.hpp <<'EOF'
#pragma once
#include <rclcpp/rclcpp.hpp>
#include "std_msgs.hpp"

namespace my_app {
class Talker {
    ::rclcpp::Publisher<std_msgs::msg::Int32> pub_;
    ::rclcpp::Timer timer_;
    int count_ = 0;
    void on_tick();

  public:
    ::rclcpp::Result configure(::rclcpp::Node& node);
};
}  // namespace my_app
EOF

cat > apps/my_app/src/Talker.cpp <<'EOF'
#include "Talker.hpp"
#include <cstdio>

namespace my_app {
void Talker::on_tick() {
    std_msgs::msg::Int32 m;
    m.data = count_;
    if (pub_.publish(m).ok()) {
        std::printf("Published: %d\n", count_);
    }
    ++count_;
}

::rclcpp::Result Talker::configure(::rclcpp::Node& node) {
    ::setvbuf(stdout, nullptr, _IONBF, 0);
    ::rclcpp::Result r = node.create_publisher(pub_, "/chatter");
    if (!r.ok()) return r;
    return node.create_wall_timer<Talker, &Talker::on_tick>(timer_, 1000, this);
}
}  // namespace my_app
EOF

::setvbuf turns off stdout’s buffering, so each line shows as soon as it is printed. It is the global one because Zephyr’s C++ library declares it only there.

The build file differs from the C one in two places: the project declares C++, and the registration names the class’s header.

cat > apps/my_app/CMakeLists.txt <<'EOF'
cmake_minimum_required(VERSION 3.20.0)
find_package(Zephyr REQUIRED HINTS $ENV{ZEPHYR_BASE})
project(my_app LANGUAGES C CXX)

find_package(nano_ros REQUIRED)
find_package(std_msgs REQUIRED)

nano_ros_auto_add_library(talker_lib STATIC src/Talker.cpp)

nros_components_register_node(talker_lib
    HEADER Talker.hpp
    PLUGIN my_app::Talker
    EXECUTABLE talker
    SHAPE configure
    TYPED
    DEPLOY zephyr)
EOF

Everything after this point is the same for the C and the C++ node.

Configure

nano-ros reads its settings from Kconfig, so they go in prj.conf beside Zephyr’s own, and west build -t menuconfig shows them under nros ROS 2 client library:

cat > apps/my_app/prj.conf <<'EOF'
# Zephyr: console and networking
CONFIG_LOG=y
CONFIG_PRINTK=y
CONFIG_NETWORKING=y
CONFIG_NET_IPV4=y
CONFIG_NET_UDP=y
CONFIG_NET_TCP=y
CONFIG_NET_SOCKETS=y
CONFIG_NET_L2_ETHERNET=y
CONFIG_NET_MAX_CONTEXTS=16
CONFIG_DNS_RESOLVER=n
CONFIG_SYS_CLOCK_TICKS_PER_SEC=1000

# zenoh-pico runs on POSIX threads and wants room
CONFIG_POSIX_API=y
CONFIG_MAX_PTHREAD_MUTEX_COUNT=64
CONFIG_MAX_PTHREAD_COND_COUNT=16
CONFIG_POSIX_THREAD_THREADS_MAX=16
CONFIG_MAIN_STACK_SIZE=16384
CONFIG_HEAP_MEM_POOL_SIZE=65536
CONFIG_SYSTEM_WORKQUEUE_STACK_SIZE=4096
CONFIG_NET_PKT_RX_COUNT=32
CONFIG_NET_PKT_TX_COUNT=32
CONFIG_NET_BUF_RX_COUNT=64
CONFIG_NET_BUF_TX_COUNT=64

# nano-ros
CONFIG_NROS=y
CONFIG_NROS_CPP_API=y
CONFIG_STD_CPP17=y
CONFIG_NROS_RMW_ZENOH=y
CONFIG_NROS_ZENOH_LOCATOR="tcp/127.0.0.1:7447"
CONFIG_NROS_DOMAIN_ID=0
EOF

The nano-ros lines, one by one:

CONFIG_NROS_C_API is for an application that calls the C API (rclc/*.h) from its own main and registers no component. An application that registers its node with nros_components_register_node(... DEPLOY zephyr) is driven by the generated entry point, which is C++, so it sets CONFIG_NROS_CPP_API=y even when the node is C.

For XRCE-DDS, set CONFIG_NROS_RMW_XRCE=y and name the agent with CONFIG_NROS_XRCE_AGENT_ADDR and CONFIG_NROS_XRCE_AGENT_PORT instead of a locator. Each middleware also needs some Zephyr settings of its own; What each RMW’s Zephyr-native fragment needs lists them.

Every other nano-ros setting (executor slots, buffer sizes, the zenoh session’s limits) is a Kconfig symbol too, set the same way. The Kconfig reference lists them with their defaults. Do not set CONFIG_NROS_ROS_EDITION: there is no such symbol, and Zephyr stops the build on a symbol it does not know.

On Zephyr 4.x you can also select the middleware on the build line with one of the module’s snippets, -S nros-zenoh, -S nros-xrce or -S nros-cyclonedds, instead of the CONFIG_NROS_RMW_* line (Zephyr 4.x: select the RMW with a snippet).

Messages

You do not run a generator. The build generates the C or C++ types for every message package the application depends on, and package.xml is where you list those packages, the same file a ROS 2 package uses:

cat > apps/my_app/package.xml <<'EOF'
<?xml version="1.0"?>
<package format="3">
  <name>my_app</name>
  <version>0.1.0</version>
  <description>A Zephyr application with a ROS 2 talker</description>
  <maintainer email="you@example.com">You</maintainer>
  <license>Apache-2.0</license>

  <depend>std_msgs</depend>

  <export>
    <build_type>nros_cmake</build_type>
  </export>
</package>
EOF

Each <depend> also gets a find_package(<pkg> REQUIRED) line in CMakeLists.txt. The C node then includes <std_msgs/std_msgs.h> and the C++ node "std_msgs.hpp".

The message definitions come from the first of these that has the package: the directories in NROS_INTERFACE_SEARCH_PATH, then a sourced ROS 2 install (AMENT_PREFIX_PATH), then copies nano-ros carries of a few standard packages. Those copies are one ROS 2 distro’s, so build from a shell that has sourced your ROS 2 install (source /opt/ros/humble/setup.bash): the types then match your ROS 2 peers. A Rust application’s nros configure (below) does not fall back to the copies at all. For your own messages, keep them in a ROS 2 interface package (its package.xml and msg/ directory) anywhere on disk, add the directory that holds it to NROS_INTERFACE_SEARCH_PATH, and depend on it like any other.

Build

From the top of the west workspace, build for native_sim:

west build -b native_sim/native/64 -S nros-nsos apps/my_app -- \
    -DZEPHYR_EXTRA_MODULES="$(nros locate nano-ros)"

native_sim builds the application as a program for your machine, so there is no emulator. The nros-nsos snippet routes its sockets to the host’s (Zephyr’s NSOS). Without it, native_sim tries to create a TAP interface (eth_posix: Cannot create zeth), which needs privileges an ordinary user or a container does not have, and the talker never reaches the router.

Run on native_sim

ROS 2 provides the router. Start it on the port the talker dials:

source /opt/ros/humble/setup.bash
ZENOH_CONFIG_OVERRIDE='listen/endpoints=["tcp/127.0.0.1:7447"];scouting/multicast/enabled=false' \
    ros2 run rmw_zenoh_cpp rmw_zenohd

Started Zenoh router with id

With the router running, in another terminal, start the talker:

./build/zephyr/zephyr.exe

Published: 1
Published: 2

west build -t run does the same. To see the messages from ROS 2, in a third terminal:

source /opt/ros/humble/setup.bash
export RMW_IMPLEMENTATION=rmw_zenoh_cpp
ros2 topic echo /chatter std_msgs/msg/Int32 --qos-reliability best_effort

The talker publishes best-effort. ros2 topic echo asks for reliable delivery unless told otherwise, and then receives nothing.

Flash a real board

The board here is ST’s Nucleo-F767ZI (Zephyr’s nucleo_f767zi). Its ST-LINK debugger is also a USB serial port, so the talker can reach the router over that cable, with no network on the board at all. Zenoh calls this a serial link.

Provision the board, and add its HAL, hal_stm32, to the west workspace. nros setup board applies nano-ros’s changes for the board to the workspace:

nros setup nucleo-f767zi-zephyr --rmw zenoh
sed -i 's/net-tools]/net-tools, hal_stm32]/' manifest/west.yml
west update --narrow -o=--depth=1
nros setup board nucleo-f767zi-zephyr --zephyr-workspace "$PWD"

Zephyr reads boards/<board>.conf and boards/<board>.overlay from the application directory after prj.conf, for that board only, so the native_sim build stays as it is. The settings turn the IP stack off, carry zenoh over USART3 (the ST-LINK port), move the console to USART6 (pins D0 and D1, for a USB-to-UART adapter), and size the image for the board’s 384 KiB of RAM:

mkdir -p apps/my_app/boards
cat > apps/my_app/boards/nucleo_f767zi.conf <<'EOF'
# zenoh over USART3, the ST-LINK USB serial port; no IP stack
CONFIG_NETWORKING=n
CONFIG_NROS_TRANSPORT_SERIAL=y
CONFIG_NROS_ZENOH_LOCATOR="serial/serial@40004800#baudrate=115200"
CONFIG_SERIAL=y
CONFIG_UART_INTERRUPT_DRIVEN=y
CONFIG_RING_BUFFER=y
CONFIG_MAIN_THREAD_PRIORITY=5

# no network driver brings up the RNG, so zenoh's session id uses this one
CONFIG_TEST_RANDOM_GENERATOR=y

# 384 KiB of RAM
CONFIG_HEAP_MEM_POOL_SIZE=16384
CONFIG_NROS_MAX_LARGE_SUBSCRIBERS=0
EOF
cat > apps/my_app/boards/nucleo_f767zi.overlay <<'EOF'
/ {
	chosen {
		zephyr,console = &usart6;
		zephyr,shell-uart = &usart6;
	};
};
EOF

Build for the board, into its own build directory:

west build -p always -b nucleo_f767zi -d build-board apps/my_app -- \
    -DZEPHYR_EXTRA_MODULES="$(nros locate nano-ros)"

Zephyr warns that prj.conf’s networking settings (NET_IPV4, NET_TCP and the rest) were assigned y but got n. That is expected: the board file turned networking off, and the warnings do not stop the build.

Plug the board in, start the router on its serial port (the ST-LINK port is usually /dev/ttyACM0), and flash it with Zephyr’s own runner:

source /opt/ros/humble/setup.bash
ZENOH_CONFIG_OVERRIDE='listen/endpoints=["serial//dev/ttyACM0#baudrate=115200"];scouting/multicast/enabled=false' \
    ros2 run rmw_zenoh_cpp rmw_zenohd

west flash -d build-board

ros2 topic echo, as on native_sim, then shows the counter:

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

Without the board, the same image runs in the board’s emulator: the probe for this chapter boots build-board/zephyr/zephyr.elf in Renode’s nucleo_f767zi machine, with USART3 on a host serial port, instead of flashing it, and checks that ros2 topic echo hears it. The flash runner (OpenOCD, pyOCD, J-Link and so on) and the probe are Zephyr’s and your bench’s; nano-ros adds nothing to them.

To use the board’s Ethernet instead, leave out the serial lines: keep CONFIG_NETWORKING=y with the board’s Ethernet driver and an address, and set CONFIG_NROS_ZENOH_LOCATOR to the router’s address on that network, for example "tcp/192.0.2.10:7447", with the router listening on tcp/0.0.0.0:7447.

A Rust application

A Rust application is built by Zephyr’s Rust support (zephyr-lang-rust, the last project in the manifest above): its CMakeLists.txt calls rust_cargo_application(), which builds the application’s crate with cargo and links it into the image. The node is the same talker, written as a nano-ros Rust component.

zephyr-lang-rust needs three things a C application does not: the Rust target the Zephyr board implies (x86_64-unknown-none for native_sim/native/64 on an x86_64 host), rustup’s clippy (it lints every Rust application as part of the build), and clang with libclang, for the bindings it generates from Zephyr’s headers. nros setup board adds the target and applies nano-ros’s changes to the west workspace, without which zephyr-lang-rust’s cargo command carries none of nano-ros’s settings for the board. From the top of the west workspace:

. "$HOME/.cargo/env"     # the cargo the install set up
sudo apt-get install -y --no-install-recommends clang libclang-dev
rustup component add clippy
nros setup board zephyr --zephyr-workspace "$PWD"

The application is a crate whose library is named rustapp and built as a static library: rust_cargo_application() links librustapp.a, whatever the package is called. In place of the C application’s source and build file, write the crate, its build script and its node:

mkdir -p apps/my_app/src
cat > apps/my_app/CMakeLists.txt <<'EOF'
cmake_minimum_required(VERSION 3.20.0)
find_package(Zephyr REQUIRED HINTS $ENV{ZEPHYR_BASE})
project(my_app)

rust_cargo_application()
EOF
cat > apps/my_app/Cargo.toml <<'EOF'
[package]
name = "my_app"
version = "0.1.0"
edition = "2021"

[lib]
name = "rustapp"
crate-type = ["staticlib"]

[dependencies]
zephyr = "0.1.0"
log = "0.4"
nros = { version = "*", default-features = false, features = ["alloc", "rmw-cffi", "macros"] }
nros-platform = { version = "*", default-features = false, features = ["platform-zephyr"] }
nros-rmw-zenoh = { version = "*", default-features = false, features = ["platform-zephyr"] }
std_msgs = { version = "*", default-features = false }

[build-dependencies]
zephyr-build = "0.1.0"
nros-zephyr-build = "*"

[profile.release]
opt-level = "s"
lto = true
debug = false
EOF
cat > apps/my_app/build.rs <<'EOF'
fn main() {
    zephyr_build::export_kconfig_bool_options();
    nros_zephyr_build::bake_nros_config();
}
EOF
cat > apps/my_app/src/lib.rs <<'EOF'
#![no_std]

extern crate zephyr;

use nros::{
    Callback, CallbackCtx, Component, DeclarativeNode, ExecutableNode, NodeContext, NodeOptions,
    NodeResult, TimerDuration,
};
use std_msgs::msg::Int32;

pub struct Talker;

impl Component for Talker {
    const NAME: &'static str = "talker";
    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::<Int32>("/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;
    const HAS_TICK: bool = false;

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

    fn on_callback(count: &mut Self::State, callback: Callback<'_>, ctx: &mut CallbackCtx<'_>) {
        if callback.as_str() == "on_tick" {
            let msg = Int32 { data: *count };
            if ctx.publish_to_topic::<Int32, 16>("/chatter", &msg).is_ok() {
                log::info!("Published: {}", *count);
            }
            *count += 1;
        }
    }
}

nros::node!(Talker);

// Keeps the zenoh backend in the static library, then generates the
// application's entry point around the component.
nros::force_link_backend!(nros_rmw_zenoh);
nros::zephyr_component_main!(crate::Talker);
EOF

Write prj.conf and package.xml as for the C application (Configure, Messages), then change two lines of prj.conf: a Rust application selects CONFIG_NROS_RUST_API (which needs CONFIG_RUST, Zephyr’s switch for zephyr-lang-rust) instead of CONFIG_NROS_CPP_API, and needs no C++ standard:

sed -i -e '/^CONFIG_NROS_CPP_API=y$/d' -e '/^CONFIG_STD_CPP17=y$/d' apps/my_app/prj.conf
cat >> apps/my_app/prj.conf <<'EOF'
CONFIG_RUST=y
CONFIG_NROS_RUST_API=y
EOF
``` The other settings stay as they are. `build.rs` hands the Kconfig
values to the crate, among them the locator and the domain, so they are still
set in `prj.conf` alone.

The crate names the nano-ros crates and `std_msgs` but does not say where they
come from. `nros configure`, run in the application directory, generates the
Rust types for the message packages `package.xml` lists, under `generated/`,
and writes `.cargo/config.toml`, which points the nano-ros crates at your
nano-ros install and the message crates at `generated/`. Run it before the
first `west build`, and again when `package.xml` changes. It generates the
types from your ROS 2 install, so source it first; the configure records the
prefix, and a later `nros configure` of the application needs no sourced
shell:

```bash probe=49 track=installed variant=west-app-rust
source /opt/ros/humble/setup.bash
cd apps/my_app && nros configure && cd ../..

From there the application builds and runs as the C one does: the same west build line, and the same run on native_sim. The log line reads <inf> nros: rustapp: Published: 1, from Zephyr’s logger.

If it doesn’t work

Could not find a package configuration file provided by "nano_ros". The module is not in the build. Check that nros locate nano-ros prints a directory, and that the build line passes it as -DZEPHYR_EXTRA_MODULES after the --.

attempt to assign the value ... to the undefined symbol NROS_.... The symbol is misspelled or does not exist. Search for it in west build -t menuconfig (/ searches). CONFIG_NROS_ROS_EDITION is a common one: it does not exist.

No Published: line within 30 seconds.

1. Check that the router is running and listening on the port in CONFIG_NROS_ZENOH_LOCATOR.
2. On native_sim, check that the build line has -S nros-nsos. A line eth_posix: Cannot create zeth in the output means it did not.
3. Check CONFIG_NETWORKING=y, CONFIG_NET_IPV4=y and CONFIG_NET_TCP=y in prj.conf. Zephyr’s networking is opt-in.

A message with an unbounded string or sequence field fails to generate, asking for a bound. nano-ros sizes its buffers at build time, so a field with no stated maximum needs one. Put it in an nros-codegen.toml beside package.xml:

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

The Zephyr 4.x line says Could NOT find Python3 ... required is at least "3.12". Zephyr 4.x needs Python 3.12 or newer for west and its build scripts.

For anything else, Troubleshooting: First 10 Minutes walks through the common failures.

Design background

A nano-ros project is normally a workspace, and its bringup’s system.toml says what runs where. An application that owns its own build stays outside that model on purpose (RFC-0121 D6): nano-ros joins the build the way any library would, and asks the build for nothing back. For Zephyr, that application is a guest (RFC-0085 D14): it loads nano-ros as a module, states the middleware, locator and domain in Kconfig, and builds with west alone. With no system.toml beside it, the module gives every nano-ros setting its Kconfig prompt, so prj.conf, menuconfig and -DCONFIG_* are the one source of its configuration.

• RFC-0121: workspace-first project layout
• RFC-0085: Zephyr workspace and west handoff

Nucleo-F767ZI (Zephyr, Renode twin)

Support level: nucleo-f767zi-zephyr. Each page states what nano-ros can show for the board (where it runs, how often, and its breadth), generated from the board support registry; Board Support Levels explains the words.

One talker on an ST Nucleo-F767ZI (STM32F767ZI, Cortex-M7) running Zephyr 3.7, talking to ROS 2 over the board’s USB serial port. You do not need the board: Renode emulates it on your machine, and its USART3, the UART the Nucleo’s ST-LINK carries to your USB port, is wired to your host the way the cable would be. No network is configured anywhere in this chapter; ethernet comes after it.

This chapter assumes a Linux x86_64 host (or the container the install page describes) with a C/C++ compiler, ROS 2 Humble with ros-humble-rmw-zenoh-cpp, and the install done, so nros is on your PATH. It uses Zephyr’s own tools the way the Zephyr chapter does; read that one for what each piece is. WiFi is deferred to the Zephyr 4.4 line, where the Pico W’s WiFi driver exists, so no chapter here opens over WiFi yet.

Provision the board

Zephyr’s host tools first: west and the build tools Zephyr’s Getting Started lists (nros setup installs no system packages). On Debian/Ubuntu:

sudo apt-get install -y --no-install-recommends git cmake ninja-build gperf \
    device-tree-compiler python3-pip python3-venv xz-utils file wget
pip3 install --user west
export PATH="$HOME/.local/bin:$PATH"

Then the board:

nros setup nucleo-f767zi-zephyr --rmw zenoh
export ZEPHYR_SDK_INSTALL_DIR="$(nros locate tool zephyr-sdk)"

That fetches what the board needs into a shared store under ~/.nros: the Zephyr SDK, the zenoh-pico sources, the Rust target, and Renode, the emulator the board runs in here. It installs no router: the router is ROS’s rmw_zenohd, from the ROS 2 install above.

A west workspace that pins Zephyr 3.7 and fetches only the modules this board builds with, hal_stm32 among them (import: true would fetch every vendor HAL):

mkdir -p nucleo_ws/manifest && cd nucleo_ws
cat > manifest/west.yml <<'WEST_YML'
manifest:
  remotes:
    - name: zephyrproject-rtos
      url-base: https://github.com/zephyrproject-rtos
  projects:
    - name: zephyr
      remote: zephyrproject-rtos
      revision: v3.7.0
      import:
        name-allowlist: [cmsis, picolibc, mbedtls, tinycrypt, mcuboot, net-tools, hal_stm32]
  self:
    path: manifest
WEST_YML
west init -l manifest
west update --narrow -o=--depth=1
pip3 install --user -r zephyr/scripts/requirements-base.txt
export ZEPHYR_BASE="$PWD/zephyr"

Last, give the workspace the patches nano-ros carries for Zephyr 3.7:

nros setup board nucleo-f767zi-zephyr --zephyr-workspace .

Scaffold the talker

nros new nucleo_ws --board nucleo-f767zi-zephyr --template talker --lang c
cd nucleo_ws

That wrote a workspace with two packages: src/nucleo_node/, the C talker, and src/nucleo_node_bringup/, whose system.toml ends in the [image.zephyr] block naming the board. The Zephyr application itself is generated under build/ when you build. The board reaches the zenoh router on your host through USART3, which Zephyr calls serial@40004800, at 115200 baud. Say so with one line at the end of the bringup’s system.toml:

echo 'locator = "serial/serial@40004800#baudrate=115200"' >> src/nucleo_node_bringup/system.toml

The line lands in the [image.zephyr] block, under the board = "nucleo-f767zi-zephyr" line the scaffold wrote. The board’s own configuration already turns Zephyr’s IP stack off and gives USART3 to zenoh; its console is USART6.

Run in the twin

Source ROS 2, then build and run. ROS 2 provides the router, and its message definitions are what the build generates the talker’s std_msgs code from. This first run records the ROS 2 prefix in the workspace, so later runs of it need no sourced shell:

source /opt/ros/humble/setup.bash
nros run nucleo_node --expect 'Publishing:'

Publishing: 'Hello World: 1'
nros run: matched after

nros run generates what the build reads (the message code and the board’s build settings, under build/), builds the firmware through west (the first build takes a few minutes; later ones take seconds), boots it in Renode’s nucleo_f767zi machine with USART3 on a terminal device of your host, starts rmw_zenohd on that device, and then lets the board run. What it prints is the board’s console, USART6: *** Booting Zephyr OS build v3.7.0 ***, then the talker’s Publishing: 'Hello World: 1' and on. With --expect it stops everything and exits 0 at the first console line containing that text, and exits 1 if the board stops first.

Without --expect it keeps running until you press Ctrl-C. Start it that way in one terminal:

nros run nucleo_node

Publishing: 'Hello World: 2'

See it from ROS 2

In a second terminal, ask ROS 2 for the topic. The router nros run started also listens where a ROS 2 node on this machine looks for one, so nothing needs to be configured:

source /opt/ros/humble/setup.bash
export RMW_IMPLEMENTATION=rmw_zenoh_cpp
ros2 topic echo /chatter std_msgs/msg/String --qos-reliability best_effort

data: 'Hello World:

The talker publishes best-effort, so the echo asks for best-effort too. Ctrl-C in the first terminal stops Renode and the router together.

Ethernet

The Nucleo’s on-chip ethernet MAC works in Renode: the talker reached a router over tcp/ with Zephyr’s eth_stm32_hal driver in an early spike. That run needed a host tap device bridged to Renode’s virtual switch, which takes CAP_NET_ADMIN (the spike made one inside a rootless network namespace), and nros run does not set one up yet. So this chapter stops at serial; the ethernet chapter comes with that support.

Flash a real board

On the bench, nros flash programs the same image through Zephyr’s own runner for the board, OpenOCD over the Nucleo’s ST-LINK:

nros flash

Not replayed. No probe runs this flash line (a CI runner has no board), so it is written from the board’s runner, not measured (tracking issue).

On the real board USART3 is the ST-LINK’s virtual COM port, so the zenoh link arrives on your host as a USB serial device (/dev/ttyACM0, say), and the router listens there instead of on Renode’s terminal device. The console, USART6, is on the board’s pins rather than on the USB cable.

If it didn’t work

• nros run names what failed and the log it wrote. no runner package drives or the plan's tools name no renode: run the nros setup nucleo-f767zi-zephyr step again, which installs Renode.
• A router that would not start usually means rmw_zenohd was not found (source your ROS 2 setup in that terminal) or another router already holds port 7447 on this machine.
• A build that cannot find hal_stm32: the west workspace predates the hal_stm32 line in its allowlist; add it and run west update again.
• Everything else: Troubleshooting - First 10 Minutes.

Where to go next

• What each Zephyr piece is - Zephyr (west module).
• The same talker on QEMU, with no Zephyr - First Project.
• Talk to a real ROS 2 system - ROS 2 Interoperability.

NuttX (apps/external)

Support level: qemu-armv7a-nuttx, rv-virt-nuttx. Each page states what nano-ros can show for the board (where it runs, how often, and its breadth), generated from the board support registry; Board Support Levels explains the words.

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.

Changing this in the tree: see Internals → in-tree examples.

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 and the NuttX sources — so you do not hand-install a cross-toolchain. The zenoh router is ROS’s rmw_zenohd and comes from a ROS 2 install; the xrce path needs only the Micro-XRCE-DDS agent, which nros setup … --rmw xrce installs:

nros setup qemu-armv7a-nuttx --rmw zenoh

(nros is the installed CLI — Installation.)

The NuttX-managed road below (apps/external, NuttX’s own make) also needs a NuttX ≥ nuttx-12 checkout of your own with an apps/ sibling; the nros build road does not.

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 to the SDK root's
        ├── Make.defs                    #   integrations/nuttx/
        ├── Makefile
        ├── CMakeLists.txt               #   (cmake-driven NuttX builds)
        └── Kconfig
nx_ws/                                   # your application: a workspace
└── src/
    ├── nx_node/                         # node package: package.xml, Cargo.toml | CMakeLists.txt, the node
    └── nx_node_bringup/                 # package.xml and system.toml: the board, the RMW, the node

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

nros setup qemu-armv7a-nuttx --rmw zenoh    # toolchain + NuttX sources + SDK
sdk="$(nros locate nano-ros)"   # this project's nano-ros SDK root
"$sdk/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. (The SDK root carries integrations/ in releases cut after 0.6.0-nros4.) Menuconfig surfaces it under Application Configuration → External Modules.

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

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

ln -s "$sdk/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.