This ROS 2 package is the entry point for building micro-ROS apps for different embedded platforms.

• Supported platforms
  • Standalone build system tools
• Dependencies
• Quick start
• Building
  • Creating micro-ROS firmware
  • Configuring micro-ROS firmware
  • Building micro-ROS firmware
  • Flashing micro-ROS firmware
• Building micro-ROS-Agent
• Contributing
• Purpose of the Project
• License
• Known Issues / Limitations

Supported platforms

This package is the official build system for micro-ROS. It provides tools and utils to crosscompile micro-ROS with just the common ROS 2 tools for these platforms:

¹ Community supported, may have lack of official support

² Support for compiling apps in a native Linux host for testing and debugging

³ a valid CMake toolchain with custom crosscompilation definition is required

Standalone build system tools

micro-ROS also offers some other ways to crosscompile it for different platforms. These other options are secondary tools and may not have full support for all features. Currently micro-ROS is also available as:

• a standalone micro-ROS component for Renesas e² studio and RA6M5: this package enables the integration of micro-ROS in Renesas e² studio and RA6M5 MCU family.
• a standalone micro-ROS component for ESP-IDF: this package enables the integration of micro-ROS in any Espressif ESP32 IDF project.
• a standalone micro-ROS module for Zephyr RTOS: this package enables the integration of micro-ROS in any Zephyr RTOS workspace.
• a standalone micro-ROS module for Mbed RTOS: this package enables the integration of micro-ROS in any Mbed RTOS workspace.
• a standalone micro-ROS module for NuttX RTOS: this package enables the integration of micro-ROS in any NuttX RTOS workspace.
• a standalone micro-ROS module for Microsoft Azure RTOS: this package enables the integration of micro-ROS in a Microsoft Azure RTOS workspace.
• a set of micro-ROS utils for STM32CubeMX and STM32CubeIDE: this package enables the integration of micro-ROS in STM32CubeMX and STM32CubeIDE.
• a precompiled set of Arduino IDE libraries: this package enables the integration of micro-ROS in the Arduino IDE for some hardware platforms.
• a precompiled set of Raspberry Pi Pico SDK libraries: this package enables the integration of micro-ROS in the Raspberry Pi Pico SDK.

Dependencies

This package targets the ROS 2 installation. ROS 2 supported distributions are:

Some other prerequisites needed for building a firmware using this package are:

sudo apt install python3-rosdep

Quick start

Download here the micro-ROS docker image that contains a pre-installed client and agent as well as some compiled examples.

Building

Create a ROS 2 workspace and build this package for a given ROS 2 distro (see table above):

source /opt/ros/$ROS_DISTRO/setup.bash

mkdir uros_ws && cd uros_ws

git clone -b $ROS_DISTRO https://github.com/micro-ROS/micro_ros_setup.git src/micro_ros_setup

rosdep update && rosdep install --from-path src --ignore-src -y

colcon build

source install/local_setup.bash

Once the package is built, the firmware scripts are ready to run.

You can find tutorials for moving your first steps with micro-ROS on an RTOS in the micro-ROS webpage.

Creating micro-ROS firmware

Using the create_firmware_ws.sh [RTOS] [Platform] command, a firmware folder will be created with the required code for building a micro-ROS app. For example, for our reference platform, the invocation is:

# Creating a NuttX + micro-ROS firmware workspace
ros2 run micro_ros_setup create_firmware_ws.sh nuttx olimex-stm32-e407

# Creating a FreeRTOS + micro-ROS firmware workspace
ros2 run micro_ros_setup create_firmware_ws.sh freertos olimex-stm32-e407

# Creating a Zephyr + micro-ROS firmware workspace
ros2 run micro_ros_setup create_firmware_ws.sh zephyr olimex-stm32-e407

Configuring micro-ROS firmware

By running configure_firmware.sh command the installed firmware is configured and modified in a pre-build step. This command will show its usage if parameters are not provided:

ros2 run micro_ros_setup configure_firmware.sh [configuration] [options]

By running this command without any argument the available demo applications and configurations will be shown.

Common options available at this configuration step are:

• --transport or -t: udp, serial or any hardware specific transport label
• --dev or -d: agent string descriptor in a serial-like transport (optional)
• --ip or -i: agent IP in a network-like transport (optional)
• --port or -p: agent port in a network-like transport (optional)

Please note that each RTOS has its configuration approach that you might use for further customization of these base configurations. Visit the micro-ROS webpage for detailed information about RTOS configuration.

In summary, the supported configurations for transports are:

¹ Community supported, may have lack of official support

Building micro-ROS firmware

By running build_firmware.sh the firmware is built:

ros2 run micro_ros_setup build_firmware.sh

Flashing micro-ROS firmware

In order to flash the target platform run flash_firmware.sh command. This step may need some platform-specific procedure to boot the platform in flashing mode:

ros2 run micro_ros_setup flash_firmware.sh

Building micro-ROS-Agent

Using this package is possible to install a ready to use micro-ROS-Agent:

ros2 run micro_ros_setup create_agent_ws.sh
ros2 run micro_ros_setup build_agent.sh
source install/local_setup.sh
ros2 run micro_ros_agent micro_ros_agent [parameters]

Contributing

As it is explained along this document, the firmware building system takes four steps: creating, configuring, building and flashing.

New combinations of platforms and RTOS are intended to be included in config folder. For example, the scripts for building a micro-ROS app for Crazyflie 2.1 using FreeRTOS is located in config/freertos/crazyflie21.

This folder contains up to four scripts:

• create.sh: gets a variable named $FW_TARGETDIR and installs in this path all the dependencies and code required for the firmware.
• configure.sh: modifies and configure parameters of the installed dependencies. This step is optional.
• build.sh: builds the firmware and create a platform-specific linked binary.
• flash.sh: flashes the binary in the target platform.

Some other required files inside the folder can be accessed from these scripts using the following paths:

# Files inside platform folder
$PREFIX/config/$RTOS/$PLATFORM/

# Files inside config folder
$PREFIX/config

Purpose of the Project

This software is not ready for production use. It has neither been developed nor tested for a specific use case. However, the license conditions of the applicable Open Source licenses allow you to adapt the software to your needs. Before using it in a safety relevant setting, make sure that the software fulfills your requirements and adjust it according to any applicable safety standards, e.g., ISO 26262.

License

This repository is open-sourced under the Apache-2.0 license. See the LICENSE file for details.

For a list of other open-source components included in ROS 2 system_modes, see the file 3rd-party-licenses.txt.

Known Issues / Limitations

There are no known limitations.

If you find issues, please report them.