system.toml keys

The keys a bringup’s system.toml takes for an image, the files beside it, and a bridge binary’s nros-bridge.toml. The page is hand-kept; a gate holds the [image.<id>] table’s key set to the CLI’s own schema, both ways, so a key the CLI accepts cannot be missing here and a key it refuses cannot be listed. The Kconfig symbols an image can also set are in Configuration surface.

Where each setting lives

A system.toml beside a Cargo.toml or CMakeLists.txt is refused. Precedence, highest first: a command-line or build flag, [image.<id>], [system], the board descriptor’s [knobs], the built-in default. nros config show prints the resolved values with where each came from.

[image.<id>]

Retired and refused by name: ip, gateway, netmask, transport, [image.<id>.net.<if>], and the old [deploy.<id>] table.

Folding over [image_defaults]

[system] default_images = ["<id>", …] is what a bare nros build builds. Without it, a workspace with more than one image lists them and stops.

Board network file

Named by os_config, beside system.toml. One table per interface, and any network other than the built-in qemu:

The built-in qemu network is QEMU user-mode networking, 10.0.2.0/24, with gateway and router host 10.0.2.2. An interface on qemu with no address takes 10.0.2.15. The resolved answer is written to build/nros/net/<image>.toml.

Refused, naming the image: an address outside its subnet or equal to the gateway; a network no file defines; two images with one static address or MAC on a network other than qemu; two files defining one network differently; a board network file on a board whose network belongs to the host OS (linux, freertos-posix, threadx-linux) or that declares no interfaces (Zephyr boards take their address from Kconfig).

[image.<id>.run], .flash and .console

An image on a network other than qemu with no nic is physical only, and launching it under QEMU is refused.

The middleware’s own file

[system] rmw_config names another default file; [image.<id>] rmw_config names one image’s. A named file that does not exist is refused. An image with a zenoh file that also states a locator is refused. The flat rmw/zenoh.conf is retired.

[image.<id>.knobs.<group>]

The same shape as a board descriptor’s [knobs.<group>]. The key is the knob registry row’s board key where it has one (executor.max_cbs); otherwise the NROS_* name without NROS_, split at the first _ (NROS_ZEPHYR_HEAP_SIZE is zephyr.heap_size). An unknown key, a wrong type or an out-of-range value stops nros build, naming the key. The image rung sits above the board and below an exported variable.

Standalone config.toml

Read with Config::from_toml(include_str!("../config.toml")). A file in the retired [[transport]] shape panics at boot, naming the new spelling.

Cargo features of the nros crate

The generated entry selects these from the image. rmw in system.toml picks which linked backend is active.

nros-bridge.toml

A bridge binary’s own file, beside system.toml’s keys because it configures the same thing, a running image, but read at run time by the program, not by the build.

Consumed by nros::run_from_config (Rust) and the future C/C++ mirror (nros::run_from_config in nros-cpp).

Not the orchestration nros.toml. This is the bridge runtime config (multi-RMW byte forwarding). It is named nros-bridge.toml to avoid colliding with the orchestration nros.toml (component/system build config) — different lifecycle, different schema.

The file lives next to the binary (or anywhere the program can read it) and selects:

1. Which RMW backends to open, under what locator / domain.
2. How those backends are wired into bridge entries that forward traffic between them.

The binary’s Cargo.toml (or target_link_libraries) still selects which backends are linked — the TOML file selects which of the linked backends are used in this run. Backend names in the file that don’t match a linked backend surface as ConfigError::OpenSession.

Top-level structure

# nros-bridge.toml — sibling of the binary
[[node]]
name    = "field"
rmw     = "zenoh"
locator = "tcp/10.0.0.1:7447"

[[node]]
name    = "control"
rmw     = "cyclonedds"
locator = "domain=0"

[[bridge]]
type      = "std_msgs/Int32"
type_hash = "RIHS01_..."
from      = { node = "field",   topic = "/sensor/raw" }
to        = { node = "control", topic = "/sensor/raw" }

Run via:

fn main() -> Result<(), nros_bridge::ConfigError> {
    nros_bridge::run_from_config("nros-bridge.toml")
    // or, via the umbrella feature: nros::run_from_config("nros-bridge.toml")
}

[[node]]

One block per backend session. The first [[node]] becomes the primary session (extra_sessions[0] in Executor::open_multi); the rest open as extras keyed by rmw.

Locator scheme grammar (zenoh)

DDS / XRCE follow their native locator conventions; consult each backend’s docs for the exact form.

[[bridge]]

One block per topic forwarded between two [[node]]s. Each bridge creates a RawSubscription on the source side and an EmbeddedRawPublisher on the destination side and pumps bytes once per executor tick.

Bidirectional bridges are two [[bridge]] entries — one in each direction. The runtime stamps a bridge_origin attachment field on forwarded frames and drops on receive when the origin matches the local backend, so an echo pair does not loop.

Error semantics

run_from_config returns ConfigError:

Any error short-circuits the runtime; bridges that opened cleanly before the failure are not pumped.

Linked-backend matrix

Add a backend to your Cargo.toml (or target_link_libraries) to make its name available in the TOML; remove it to fence off use even when the TOML file lists it (yields OpenSession at startup).

Design background

• RFC-0004: configuration and transports
• RFC-0065: colcon-like workspace builder
• RFC-0098: generated leaf build config
• RFC-0109: network config layers
• RFC-0118: target execution model