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

Choose your path

How-to · Level 1: First contact

Pick the card that matches your work and follow its route in order. Each step needs only the steps above it, so you never read a page that assumes one you skipped. Each card also states its budget: the time or the property the route is written and tested to meet.

Every route starts with Install. If you are not sure which card fits, start with Education: its first chapters are the common start of every other route.

Education

For: instructors and students in a course or lab on robotics or embedded systems.

Budget: a 15-minute install on each seat, labs that fit a two-hour session, and the same result on every seat.

Route:

  1. Install on each seat.
  2. Run a talker on an emulated board. The output it prints is the result to check on every seat.
  3. What you just built: the node package and the workspace around it.
  4. Add a second node, in Rust, C or C++.
  5. Pick and configure the RMW. Cyclone DDS needs no router, which keeps a lab machine simple.
  6. Your own message.
  7. Services and actions: the server, client and action templates in the C node chapter.
  8. Parameters and launch files.
  9. The lab’s board: its page under Get started on your board, such as Nucleo-F767ZI, or its entry in Supported Boards.

Field solutions

For: engineers and technicians who build a system for each customer, often on a board they were handed.

Budget: 30 minutes from an unopened box to ros2 topic echo showing the board’s data.

Route:

  1. Install.
  2. Your board’s page under Get started on your board. It runs the board’s emulated twin first, then the board itself: Nucleo-F767ZI. For any other board, find it in Supported Boards; its page names the chapter that runs it.
  3. Talk to ROS 2: the board’s topics in your ROS 2 graph, in both directions.

Industrial

For: teams who build products where safety and robustness matter.

Budget: reproducible, auditable and offline. The same inputs give the same image, every fact about a board is on a page, and the build runs with no network.

Route:

  1. Install.
  2. Background: the execution model, static memory and pools and safety.
  3. User guide: pin a release and work offline, build inside a vendor tree for air-gapped CI, and deploy to production.
  4. Reference: board support levels and the configuration keys. nros doctor --report prints the support level of every board your images name, as a report you can file with a review.

ROS 2 developer porting nodes

For: developers with existing rclcpp nodes who want them on a microcontroller.

Budget: Install’s 15 minutes, then the first chapter’s run. The port itself depends on your node, so this route sets no time for it.

Route:

  1. Install.
  2. Run a talker on an emulated board, to see the toolchain work before your own code is in it.
  3. How nano-ros differs from ROS 2.
  4. Port a C++ node.
  5. Move a ROS 2 project over.

Board porter

For: developers who bring nano-ros to a board, a platform or a transport it does not support yet.

Budget: Install’s 15 minutes, then the first chapter’s run. Porting is development work, so this route sets no time for it.

Route:

  1. Install.
  2. Run a talker on an emulated board and What you just built.
  3. How a build becomes an image.
  4. Extending nano-ros: Add a board. A board of yours lives in your own tree.
  5. nano-ros Internals, when the port needs a change inside nano-ros itself, such as a new platform.

If none of these fit

Read Welcome for what nano-ros is and what it is not, then follow the Education route as far as you need. Its first two chapters are the shortest way to see nano-ros run. If a step fails, Troubleshooting lists the problems readers meet in their first ten minutes.

Design background

The three purposes and their budgets are RFC-0116 D1. The five cards are RFC-0124 D10.