Skip to content
/ micro_ros_setup Public
forked from micro-ROS/micro_ros_setup

Support macros for building micro-ROS-based firmware.

License

Apache-2.0 license
0 stars 138 forks Branches Tags Activity
Star
Notifications You must be signed in to change notification settings

mROS-base/micro_ros_setup

BranchesTags
 
 

Repository files navigation

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

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:

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

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:

Dependencies

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.

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 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:

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

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.

About

Support macros for building micro-ROS-based firmware.

Resources

Readme

License

Apache-2.0 license
Activity
Custom properties

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

1 tags

Packages

No packages published

Languages

  • Shell 97.2%
  • CMake 2.2%
  • Python 0.6%