micro_ros_setup: cross-compiling micro-ROS for FreeRTOS and Zephyr from the standard ROS 2 tooling

A ROS 2 package whose job is to be the entry point

micro_ros_setup is described as a ROS 2 package that is the entry point for building micro-ROS apps for different embedded platforms. The mechanism is described in one sentence in the README: this package provides tools and utils to crosscompile micro-ROS with just the common ROS 2 tools.

That framing defines the audience better than any feature list would. micro-ROS is the middleware side of ROS 2 pushed down onto microcontrollers, and the usual way in has been through a vendor toolchain such as STM32CubeMX or the ESP-IDF environment. micro_ros_setup offers the alternative: use the ROS 2 tooling you already have, point it at a board, and let the package handle the cross-compilation.

The README is unusually direct about who that suits. Its note states that the package provides basic support only, intended in particular for ROS developers who are new to microcontrollers, and it says that micro-ROS components for each platform are available and provide a deeper and more flexible integration with the platform-specific build systems.

So the honest reading is that this is an on-ramp, not a production integration layer. That framing matters when you evaluate it, because the limitations below are not oversights in a tool promising everything, they are the boundaries of a tool promising a first step.

The supported board table pins an RTOS version for every entry

The README carries a table of RTOS, platform, version and example, and it is the most informative part of the documentation. The FreeRTOS entries cover the ST Nucleo F446RE, F446ZE, F746ZG and F767ZI boards on STM32CubeMX latest, the Espressif ESP32 on v8.2.0, and the Crazyflie 2.1 on v10.2.1 - CF 2020.06. The Zephyr entries cover the Olimex STM32-E407, the ST Nucleo F446RE and the ST B-L475E-IOT01A, all on v2.6.0.

Each entry also carries an example identifier, such as `freertos nucleo_f446re`, `freertos esp32`, `freertos crazyflie21`, `zephyr olimex-stm32-e407` and `zephyr discovery_l475_iot1`. These are the shape of the platform selector values that a user supplies when choosing a target.

The version column is the part to read carefully. The table does not say it supports any version of FreeRTOS or Zephyr; it names specific ones, and for the ST boards it names STM32CubeMX latest, which is a moving target by definition. A build that works today against a board the table lists may need attention when the STM32CubeMX release moves, and the README gives no guidance on pinning or overriding that value.

The table also shows that the coverage is not uniform. The Crazyflie 2.1 row is the one entry without a recommended alternative component named in the table, so a Crazyflie user has fewer documented options for going deeper.

Every platform row points at a deeper component

The last column of the table is the most useful part for a decision. For the ST Nucleo boards under FreeRTOS, the recommended alternative is the micro-ROS utils for STM32CubeMX and STM32CubeIDE, in the repository micro_ros_stm32cubemx_utils. For the Espressif ESP32, it is the micro-ROS component for ESP-IDF, in micro_ros_espidf_component. For the Zephyr rows, it is the micro-ROS module for Zephyr RTOS, in micro_ros_zephyr_module.

Read that as a map of the ecosystem rather than as a recommendation against this package. The README's own wording is that the per-platform components provide a deeper and more flexible integration with the platform-specific build systems, which is the honest reason to reach for them.

The difference in approach is specific. micro_ros_setup works from the common ROS 2 tools, so you are running standard cross-compilation and standard tooling on a board that has an established vendor workflow. The per-platform components instead plug micro-ROS into the vendor build system itself, which is what you want when you need that vendor IDE, its debugging and its board support in the loop.

For a first firmware, the common-tooling path is a smaller commitment. For a product, the vendor-integrated path is usually where you end up anyway, and this table tells you which route to take.

scripts/ and config/ carry the actual work

Based on the repository layout, this is a package with a shell backbone and a build file rather than a large source tree. The primary language is Shell, and the top-level entries are .github/, .gitignore, .images/, 3rd-party-licenses.txt, CHANGELOG.rst, CMakeLists.txt, CONTRIBUTING.md, LICENSE, NOTICE, README.md, config/, package.xml and scripts/.

That structure is worth reading as a description of how the package works. The scripts/ directory is where the per-platform tooling lives, config/ is where the configuration for those platforms is described, and CMakeLists.txt with package.xml is what makes the whole thing consumable as a ROS 2 package inside a colcon workspace. The .images/ directory holds the logo referenced by the README, and CHANGELOG.rst is the record of changes.

The README's own table of contents lists the workflow it documents: quick start, then a building section that covers creating micro-ROS firmware, configuring micro-ROS firmware, building micro-ROS firmware and flashing micro-ROS firmware, followed by a separate section for building the micro-ROS-Agent. The agent is the host-side counterpart, and having it documented as its own step tells you the intended workflow spans both ends of the link.

What the README text does not do is print the commands for any of those steps. There is no clone line, no colcon invocation and no flash command in it. Anyone planning to adopt this needs the upstream micro-ROS documentation for the concrete invocations, because the repository README stops at the outline.

Release tags encode the ROS 2 distribution, and that is the upgrade contract

The release list is short and revealing. There is 6.1.0 from 2026-08-11, then 4.1.0 with the name micro-ROS Iron from 2023-06-22, and 3.1.0 with the name micro-ROS Humble from 2022-05-26. The default branch is named kilted.

So this package is versioned against ROS 2 distributions rather than on its own schedule. The tag naming tells you which ROS 2 release a given tag is meant for, and the branch name tells you which one the tree currently targets. That is a sensible scheme for a package whose whole purpose is to be built inside a ROS 2 workspace, since it removes the question of which pairing of package and distribution you are looking at.

It also defines the upgrade cost. Moving between ROS 2 distributions means moving between the matching branches and tags here, and the notes in CHANGELOG.rst are where the differences between them will be recorded. The gaps in the list, from 2022 to 2023 to 2026, suggest the tags follow the distribution cadence rather than a steady release rhythm.

On maintenance activity, the last push was on 2026-10-09, so work is still landing on the kilted branch.

Apache 2.0 with a third-party inventory

The licence is Apache 2.0, and the repository root carries the matching pieces: a LICENSE file, a NOTICE file and a file named 3rd-party-licenses.txt.

That third file is the one to look at. A cross-compilation package like this pulls in vendor SDKs and RTOS sources, and each of those carries its own terms. The presence of a dedicated inventory means the project tracks what it vendors. The licence file set also tells you the shape of the grant: a permissive licence with attribution and notice obligations, which is the usual choice for a package that hardware vendors and robotics companies intend to drop into their own stacks.

This is a description of the terms rather than a legal opinion, and the inventory is the file to read if you plan to ship firmware images to customers rather than build them for your own lab.

The package also carries CONTRIBUTING.md, and the README table of contents ends with sections for the purpose of the project and for papers, which is a hint about who is expected to use it and why.

Where this is the wrong tool

There are three clear cases for choosing something else.

The first is a custom board. Every entry in the table is a specific commercial board or a specific reference platform, and the package cross-compiles those. If your hardware is not in the list, you have no documented path here, and the per-platform components are the more likely route since they plug into a vendor build system you control.

The second is a production product that needs deep integration, per the README's own wording. If you need the vendor IDE in the loop, its debug configuration and its peripheral setup, then micro_ros_setup is a detour and the micro_ros_stm32cubemx_utils, micro_ros_espidf_component or micro_ros_zephyr_module route is the one that ends with the integration you need.

The third is a team that needs a support contract. This is a community package with three release tags spread over four years and documentation that stops at an outline. Its own note calls the support basic. If your firmware ships to customers and a broken build blocks a release, the assumption that this package will be maintainable for you is doing a lot of work.

For a student or a prototype bringing up a first micro-ROS node on a Nucleo board, none of that applies and the package does what it says.

Editorial conclusion

micro_ros_setup suits a ROS 2 developer who wants a first micro-ROS firmware on one of the listed boards without learning a vendor IDE, and it does not suit a product team that needs deep platform integration, custom board support or a long-term pin, because the README itself calls the support basic and every platform in the table points at a more capable component. Verify first which of those components your board needs, which RTOS version the table pins for it, and whether the ROS 2 distribution named in your release tag matches the one on your workstation before you run the build.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. micro-ROS/micro_ros_setup on GitHub
4. README
5. Releases