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:

Install the nros CLI.
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.
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.

Your first project (above), on the host.
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.
Run it on the target. The target model and nros run for a host process or an emulator.
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.
Grow the system. More nodes, parameters and images: Growing your workspace, and Mixed-language workspaces for other languages. Bridging several networks: Cross-backend Bridges.
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.

Install once per seat: Installation. Nothing in the first project needs ROS 2, a router or hardware.
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.
Concepts for the lecture. Anatomy, Architecture Overview and Execution Model and Two-Layer API.
Embedded labs without hardware. Each platform chapter runs its example under QEMU, for example FreeRTOS or bare-metal.
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

Keyboard shortcuts