This ROS 2 package is the entry point for building micro-ROS apps for different embedded platforms.
- Supported platforms
- Dependencies
- Quick start
- Building
- Building micro-ROS-Agent
- Contributing
- Purpose of the Project
- License
- Known Issues / Limitations
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:
| RTOS | Platform | Version | Example |
|---|---|---|---|
| Azure RTOS / FreeRTOS / Bare metal | Renesas RA6M5 | Renesas e2 studio | renesas_ra ra6m5 |
| FreeRTOS | Olimex STM32-E407 | STM32CubeMX latest | freertos olimex-stm32-e407 |
| FreeRTOS | ST Nucleo F446RE 1 | STM32CubeMX latest | freertos nucleo_f446re |
| FreeRTOS | ST Nucleo F446ZE 1 | STM32CubeMX latest | freertos nucleo_f446ze |
| FreeRTOS | ST Nucleo F746ZG 1 | STM32CubeMX latest | freertos nucleo_f746zg |
| FreeRTOS | ST Nucleo F767ZI 1 | STM32CubeMX latest | freertos nucleo_f767zi |
| FreeRTOS | Espressif ESP32 | v8.2.0 | freertos esp32 |
| FreeRTOS | Crazyflie 2.1 | v10.2.1 - CF 2020.06 | freertos crazyflie21 |
| Zephyr | Olimex STM32-E407 | v2.6.0 | zephyr olimex-stm32-e407 |
| Zephyr | ST B-L475E-IOT01A | v2.6.0 | zephyr discovery_l475_iot1 |
| Zephyr | ST Nucleo H743ZI 1 | v2.6.0 | zephyr nucleo_h743zi |
| Zephyr | Zephyr emulator | v2.6.0 | zephyr host |
| Mbed | ST B-L475E-IOT01A | v6.6 | mbed disco_l475vg_iot01a |
| - | Static library (.a) and headers (.h) 3 | - | generate_lib |
| Linux | Host 2 | Ubuntu 18.04/20.04 | host |
| Android | AOSP 4 | Latest | android generic |
1 Community supported, may have lack of official support
2 Support for compiling apps in a native Linux host for testing and debugging
3 a valid CMake toolchain with custom crosscompilation definition is required
4 Community supported, may have lack of official support
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 e2 studio and RA6M5: this package enables the integration of micro-ROS in Renesas e2 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 library builder for PlatformIO: this package enables the integration of micro-ROS in PlatformIO.
- 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.
This package targets the ROS 2 installation. ROS 2 supported distributions are:
| ROS 2 Distro | State | Branch |
|---|---|---|
| Crystal | EOL | crystal |
| Dashing | EOL | dashing |
| Foxy | Supported | foxy |
| Galactic | Supported | galactic |
| Rolling | Supported | main |
Some other prerequisites needed for building a firmware using this package are:
sudo apt install python3-rosdep
Building for Android needs Latest Android NDK to be installed and the following environment variables to be set:
ANDROID_ABI: CPU variant, refer here for details.ANDROID_NATIVE_API_LEVEL: Android platform version, refer here for details.ANDROID_NDK: root path of the installed NDK.
Download here the micro-ROS docker image that contains a pre-installed client and agent as well as some compiled examples.
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-paths src --ignore-src -y
colcon build
source install/local_setup.bashOnce 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.
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 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-e407By 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:
--transportor-t:udp,serialor any hardware specific transport label--devor-d: agent string descriptor in a serial-like transport (optional)--ipor-i: agent IP in a network-like transport (optional)--portor-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:
| FreeRTOS | Zephyr | Mbed | |
|---|---|---|---|
| Olimex STM32-E407 | UART, Network | USB, UART | - |
| ST B-L475E-IOT01A | - | USB, UART, Network | UART |
| Crazyflie 2.1 | Custom Radio Link | - | - |
| Espressif ESP32 | UART, WiFI UDP | - | - |
| ST Nucleo F446RE 1 | UART | - | - |
| ST Nucleo F446ZE 1 | UART | - | - |
| ST Nucleo H743ZI 1 | - | UART | - |
| ST Nucleo F746ZG 1 | UART | UART | - |
| ST Nucleo F767ZI 1 | UART | - | - |
1 Community supported, may have lack of official support
By running build_firmware.sh the firmware is built:
ros2 run micro_ros_setup build_firmware.sh
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
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]
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_TARGETDIRand 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/configThis 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.
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.
There are no known limitations.
If you find issues, please report them.