Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Board Integration

How you consume nano-ros depends on what your project’s build system looks like, not on what RTOS you’re targeting. This page maps user profile → recommended path. Pick your row, follow the linked guide.

The architecture behind the matrix lives in docs/design/0012-board-bsp-integration-architecture.md (layered model, vendor-BSP scaling, plan).

Consumption matrix

ProfileWorkflowRecommended path
Cargo-first Rust user (have RTOS sources)cargo build --target <triple> produces a single ELF. RTOS kernel built in-tree by Cargo.Generic board crate + env vars pointing at FREERTOS_DIR / THREADX_DIR / etc.
Vendor-IDE user (STM32CubeIDE, MCUXpresso IDE, etc.)Vendor’s existing FreeRTOS / ThreadX project; nano-ros as an add_subdirectory() library.add_subdirectory(third_party/nano-ros) from the vendor’s project.
Zephyr user (any board)west + DTS overlays. Vendor HALs come as Zephyr modules.Zephyr integration shell — projects: entry in your west.yml.
ESP-IDF user (any ESP32 chip)idf.py build.ESP-IDF integration shell — idf.py add-dependency nano-ros.
NuttX user (any board)NuttX apps/external/ + Kconfig.NuttX integration shell — symlink under apps/external/.
PX4 userPX4 build pipeline.PX4 integration shell — EXTERNAL_MODULES_LOCATION.
Niche RTOS / vendor forkStock RTOS kernel + vendor driver SDK. Cargo-driven build.Generic board crate + vendor overlay crate (~50 LOC). See the Vendor Overlay cookbook.

Generic board crate

For Cargo-first users targeting one of the four supported kernel families:

KernelCrateSDK env vars you set
FreeRTOS + lwIPnros-board-freertosFREERTOS_DIR, FREERTOS_PORT, LWIP_DIR, FREERTOS_CONFIG_DIR
ThreadX + NetX-Duonros-board-threadxTHREADX_DIR, THREADX_CONFIG_DIR, NETX_DIR, NETX_CONFIG_DIR
NuttXnros-board-nuttxNUTTX_DIR (kernel built by NuttX itself)
bare-metal Cortex-M + smoltcp(no family crate — copy nros-board-mps2-an385)BOARD_LINKER_SCRIPT_DIR
 
# user_app/Cargo.toml — registry-style names resolved by the
# `nros sync`-managed [patch.crates-io] table (nano-ros is source-only;
# nothing is on crates.io):
[dependencies]
nros-board-freertos = { version = "*", default-features = false }
nros = { version = "*", default-features = false, features = ["rmw-cffi", "platform-freertos", "ros-humble"] }
nros-rmw-zenoh = { version = "*", default-features = false, features = ["platform-freertos"] }
std_msgs = { path = "generated/std_msgs", default-features = false }

#![allow(unused)]
fn main() {
// user_app/src/main.rs — the macro form; it expands to
// `nros_board_freertos::run_entry::<Board, _, _>(...)` dispatch.
#![no_std]
#![no_main]
nros::main!(spin = "forever");

// Manual form, for full control:
// nros_board_freertos::run_entry::<Mps2An385, _, _>(
//     Config::default(), None, |runtime| { /* register nodes */ Ok(()) })
}
export FREERTOS_DIR=$HOME/sdk/freertos/kernel
export FREERTOS_PORT=GCC/ARM_CM3
export LWIP_DIR=$HOME/sdk/freertos/lwip
cargo build --release --target thumbv7m-none-eabi

The generic crate’s build.rs compiles the kernel + network stack

  • nano-ros platform glue into a single ELF. No vendor driver glue — that’s what overlay crates are for.

Vendor overlay crate

When your board needs vendor-specific drivers (STM HAL, NXP fsl_*, NVIDIA FSP, Renesas Synergy SSP, …) on top of one of the generic crates, write a small (~50 LOC) overlay crate that:

  1. Depends on the matching generic board crate.
  2. Defines a board marker type and implements the nros_platform board traits on it (BoardInit::init_hardware() and siblings); re-exports Config.
  3. Provides strong definitions of the generic crate’s weak C network hooks (nros_board_register_netif, nros_board_poll_netif).
  4. Pulls vendor HAL .c sources via its own build.rs cc-rs invocation.

The full cookbook + the working precedent (nros-board-mps2-an385-freertos) live in Vendor Overlay Board Crate.

Why so many paths

Per the architecture doc, each RTOS already has its own package manager (Zephyr’s west + DTS, ESP-IDF’s component registry, NuttX’s apps/external/, PX4’s EXTERNAL_MODULES_LOCATION). nano-ros rides those rails instead of trying to re-invent a single “embedded library” mechanism that fits no vendor ecosystem cleanly.

The Cargo-first profile (with optional vendor overlay crates) covers the gap where a user is NOT inside an existing RTOS-IDE project and wants to drive their build from Cargo end-to-end. That’s the two-and-a-half rows at the top + bottom of the matrix.

Not on the matrix

  • No common driver HAL. STM HAL_*, NXP fsl_*, Espressif esp_*, Renesas R_* all stay vendor-owned. Overlay crates wrap them; nano-ros doesn’t abstract over them.
  • No DTS-equivalent for non-Zephyr platforms. Zephyr owns its board contract; everywhere else, board config is whatever your vendor IDE produces (CubeMX .ioc, NuttX defconfig, ESP-IDF sdkconfig).
  • No board crate per SKU. Generic + overlay covers the long tail. If you have an exotic board with custom HAL, write a ~50 LOC overlay; nano-ros doesn’t catalog every vendor SKU.