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 Cargo.toml metadata (Rust) or the CMake nano_ros_* functions (C/C++), a universal system.toml, package.xml, and launch XML — plus Kconfig for the embedded build (Zephyr). This guide covers what each file owns, the embedded deploy config both languages bake at build time, and the standalone config.toml for hand-written no_std apps.

Two files you may find in old material are retired: the nros.toml per-package/workspace file (rejected by the CLI; see below) and the old config.toml [network]/[zenoh]/[scheduling] schema. Design of record: RFC-0004.

One home per concern

Boundary rule. If a knob changes what is compiled/linked, it lives in the build file (Cargo.toml feature / CMakeLists.txt option). If it changes the system topology (components, deploy, domain, RMW), it lives in system.toml. If it is the physical link + router address a target boots with, it lives in the deploy config ([package.metadata.nros.deploy.<t>] for Rust / the package.xml <export><nano_ros deploy=… rmw=…/> tuple for C/C++).

Config home by language × scale

Mirrors RFC-0004 §3:

Where a concern has both a native-idiom projection and a system.toml, the resolution is a fixed precedence ladder, not a merge: explicit CLI/build flag (--rmw / -DNANO_ROS_*) > system.toml ([image.<id>] > [system])

the per-package projection ([package.metadata.nros.*] / CMake) > built-in default. nros config show prints the resolved effective config with per-value provenance; nros check flags values still sourced from legacy files.

Full design rationale: RFC-0004 (configuration & transports); RMW backend selection & lowering is RFC-0031. For the multi-RMW runtime topic-forwarding bridge (a separate file/feature), see nros-bridge.toml.

Embedded deploy config (codegen apps — the common case)

An embedded app built through nros::main!() (Rust) or the CMake entry codegen (C/C++) declares its network + router config per deploy target in its build manifest. The toolchain bakes it at compile time — there is no config file on the device and nothing is parsed at runtime.

Rust — [package.metadata.nros.deploy.<target>] in the app’s Cargo.toml. nros::main!() bakes the block into a DeployOverlay that BoardEntry::run_with_deploy applies onto the board’s boot Config:

# Cargo.toml (e.g. examples/qemu-arm-baremetal/rust/talker)
[package.metadata.nros.node]
class = "talker_pkg::Talker"
name  = "talker"

[package.metadata.nros.deploy.mps2-an385]
board   = "mps2-an385"         # board crate (optional where unambiguous)
rmw     = "zenoh"
locator = "tcp/192.168.1.1:7447"
ip      = "192.168.1.10"
gateway = "192.168.1.1"
netmask = "255.255.255.0"
# domain_id = 0

C/C++ — the <export><nano_ros …/> tuple in the package’s package.xml (RFC-0048 §4; the retired nano_ros_deploy() cmake call’s successor). Domain/locator ride the build config (config.toml / -DNROS_ENTRY_LOCATOR), not the tuple:

<!-- package.xml (e.g. examples/qemu-arm-freertos/c/talker) -->
<export>
  <build_type>ament_cmake</build_type>
  <nano_ros deploy="freertos" board="mps2-an385-freertos" rmw="zenoh"/>
</export>

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 ([tiers.<name>.<rtos>] + [[node_overrides]]) — see RFC-0015.

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. Rationale and the measurements: RFC-0002 § 4.4a.

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 carrying [node] / [[transport]] / [node.rt], compile-baked with include_str! and parsed by the board crate’s Config::from_toml.

# config.toml

[node]
domain_id = 0              # ROS 2 domain ID (0–232)
# namespace = "/"
# rmw = "zenoh"            # ACTIVE backend; must match a LINKED backend
                           # (the build file picks what is linked)

# One transport per session. A single ethernet/wifi/serial entry is the
# common case. In-process topic forwarding is the separate [[bridge]] path.
[[transport]]
kind    = "ethernet"       # ethernet | wifi | serial | can
ip      = "10.0.2.10/24"   # CIDR — the prefix rides the address
mac     = "02:00:00:00:00:00"
gateway = "10.0.2.2"
locator = "tcp/10.0.2.2:7447"

[node.rt]                  # scheduling / real-time (RTOS); omit for defaults
app_priority         = 12
app_stack_bytes      = 65536
zenoh_read_priority  = 16
zenoh_lease_priority = 16
poll_priority        = 16
poll_interval_ms     = 5

Per-kind transport fields:

ip is CIDR (10.0.2.10/24) — the board derives the prefix or netmask from it. A serial locator carrying # (serial/UART_0#baudrate=115200) is fine — quote it.

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 → deploy metadata (above); hand-written main() → config.toml. Only the old config.toml schema ([network]/[zenoh]/[scheduling]) is retired.

Retired files

• nros.toml — retired in full. A workspace-root nros.toml is rejected by the CLI (NrosTomlNotSupported; migrate with the nros-v0.5.0 tag’s nros migrate workspace — the one-shot verb is retired on newer trees, #186); the legacy per-package overlay is a deprecated fallback that nros check flags; the embedded-runtime role never shipped (no example ever declared one). If a doc tells you to write nros.toml, it predates the migration — the content belongs in deploy metadata or system.toml.
• Old config.toml schema ([network]/[zenoh]/[scheduling]) — retired; superseded by the deploy class (net) + board features / Kconfig (RT). The direct-mode config.toml above is the kept, supported shape.

Build-time environment variables

Read during cargo build (by build.rs) or by justfile recipes. Set in .env or export in your shell.

SDK paths

Auto-resolved by nros setup <board>; override if SDKs live elsewhere.

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

Binary-size knobs (embedded)

On a constrained MCU, two build-time env vars (set in the example’s .cargo/config.toml [env], like the other NROS_* tuning) shed the parts a brokered client doesn’t need:

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

Measured footprint

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

• strip, see 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 — set in the example’s .cargo/config.toml [env] and read by nros-rmw-xrce-cffi’s build.rs: NROS_XRCE_STREAM_HISTORY=4, NROS_XRCE_CUSTOM_TRANSPORT_MTU=512, NROS_XRCE_MAX_SUBSCRIBERS=1, NROS_XRCE_MAX_SERVICE_SERVERS=1, NROS_XRCE_MAX_SERVICE_CLIENTS=1, NROS_XRCE_SUBSCRIBER_RING_DEPTH=1, NROS_XRCE_BUFFER_SIZE=256. Vendor defaults grow xrce_session_state_t to ~390 KB (which wouldn’t fit a 24 KB heap); these knobs drop it to ~12 KB. Defaults are unchanged for hosted / non-tight-RAM consumers — the env vars are pure opt-in.

How to read this:

• The size profile (opt-s) shrinks .text by ~10–26 % with .bss/.data unchanged (opt-level doesn’t touch static buffers — those are the env knobs above). -Oz is not used — on smoltcp examples it grows .bss +24 KB by defeating opt-3’s per-socket dead-buffer DCE (see 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 (qemu-arm-baremetal serial talker, 116 KB text / 101 KB RAM):

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

# .cargo/config.toml — gc + serial knobs
[target.thumbv7m-none-eabi]
rustflags = [
    "-C", "link-arg=--gc-sections",   # 204.8 — strip unreferenced fns/data
    "-C", "link-arg=-Tlink.x",
]

[env]
NROS_LINK_IP        = "0"      # 204.7 — drop zenoh-pico TCP/UDP link C
ZPICO_NO_SMOLTCP    = "1"      # skip smoltcp glue on bare-metal
# Heap floor: the per-entry executor backing is a single ~75 KB
# allocation, so a `nros::main!` image needs ≥128 KB (the #176 board
# default) — the pre-271 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.
NROS_HEAP_SIZE      = "131072"
NROS_SMOLTCP_MAX_SOCKETS     = "1"   # 204.2 — brokered client multiplexes
NROS_SMOLTCP_MAX_UDP_SOCKETS = "1"

Build with cargo build --profile size, or fleet-wide via NROS_CARGO_PROFILE=size just <plat> build. nros new --platform baremetal already scaffolds the [profile.size] + the .cargo/config.toml shape (Phase 204.7/204.8); uncomment the serial block when you swap to a serial transport.

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

Cargo features (which RMW/platform is linked)

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

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

Runtime environment (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

.env

cp .env.example .env   # uncomment + adjust; gitignored; auto-loaded by just + direnv