micro-ROS for Arduino

This is a micro-ROS library for baremetal projects based on Arduino IDE or Arduino CLI.

As the build process for ROS 2 and micro-ROS is based on custom meta-build system tools and CMake, this library is provided as a precompiled library. However, users can rebuild their own precompiled libraries in order to modify the micro-ROS configuration or RMW parameters by customizing the respective .meta file.

• micro-ROS for Arduino
  • Supported boards
  • How to use the precompiled library
    • Arduino IDE
    • PlatformIO
  • How to build the precompiled library
  • Patch Arduino board for support precompiled libraries
    • Patch Teensyduino
    • Patch SAM
  • Custom Messages in MicroROS
  • Increase the number of Publishers and Subscribers Limit
  • Purpose of the Project
  • License
  • Known Issues/Limitations

Supported boards

Supported boards are:

Board	Min version	State	Details	.meta file
Arduino Portenta H7 M7 Core	v1.8.5	Supported	Official Arduino support	colcon.meta
Arduino Nano RP2040 Connect	v1.8.5	Supported	Official Arduino support	colcon_verylowmem.meta
OpenCR	v1.4.16	Supported	Based on custom board	colcon.meta
Teensy 4.0	v1.8.5	Not tested	Based on Teensyduino (1.58.x)	colcon.meta
Teensy 4.1	v1.8.5	Supported	Based on Teensyduino (1.58.x)	colcon.meta
Teensy 3.2/3.1	v1.8.5	Supported	Based on Teensyduino (1.58.x)	colcon_lowmem.meta
Teensy 3.5	v1.8.5	Not tested	Based on Teensyduino (1.58.x)	colcon_lowmem.meta
Teensy 3.6	v1.8.5	Supported	Based on Teensyduino (1.58.x)	colcon_lowmem.meta
ESP32 Dev Module	v1.8.5	Supported	Arduino core for the ESP32 (v2.0.2)	colcon.meta

Community contributed boards are:

Board	Min version	Contributor	Details	.meta file
Arduino Due	-	@lukicdarkoo		colcon_verylowmem.meta
Arduino Zero	-	@lukicdarkoo		colcon_verylowmem.meta
Kakute F7	-	@amfern		colcon.meta
STM32-E407	-	@dominikn		colcon.meta
Wio Terminal	-	@maehara-keisuke		colcon.meta
Raspberry Pi Pico	-	@maehara-keisuke	with ESP-AT	colcon_verylowmem.meta
Seeed Studio XIAO SAMD21	-	@maehara-keisuke	with ESP-AT	colcon_verylowmem.meta
Seeed Studio XIAO RP2040	-	@maehara-keisuke	with ESP-AT	colcon_verylowmem.meta

You can find the available precompiled ROS 2 types for messages and services in available_ros2_types.

How to use the precompiled library

Arduino IDE

Go to link to release section and download the last release of micro-ROS library for Arduino.

Include it in your project using Sketch -> Include library -> Add .ZIP Library...

You can test micro-ROS examples located in this repo examples folder.

Remember that is possible to use a micro-ROS Agent just with this docker command:

# Serial micro-ROS Agent
docker run -it --rm -v /dev:/dev --privileged --net=host microros/micro-ros-agent:iron serial --dev [YOUR BOARD PORT] -v6

PlatformIO

PlatformIO support for this repository has been deprecated in favor of its own build system: micro_ros_platformio

How to build the precompiled library

If you need to add custom packages or types, or customize any internal parameter of the micro-ROS stack, you will need to recompile this library from source code:

docker pull microros/micro_ros_static_library_builder:iron
docker run -it --rm -v $(pwd):/project --env MICROROS_LIBRARY_FOLDER=extras microros/micro_ros_static_library_builder:iron

Optionally a specific single target can be built using the -p <LIBRARY_TARGET> argument like this:

docker run -it --rm -v $(pwd):/project --env MICROROS_LIBRARY_FOLDER=extras microros/micro_ros_static_library_builder:iron -p <LIBRARY_TARGET>

Available targets LIBRARY_TARGETS are available on the top of the extras/library_generation/library_generation.sh file

Folders added to extras/library_generation/extra_packages and entries added to extras/library_generation/extra_packages/extra_packages.repos will be taken into account by this build system. This should be used for example when adding custom messages types or custom micro-ROS packages.

You can configure many parameters of the library by editing the respective .meta file in the extras/library_generation/ directory.

Patch Arduino board for support precompiled libraries

Patch Teensyduino

Go inside your Arduino + Teensyduino installation and replace platform.txt:

export TEENSYDUINO_VERSION=[Your Teensyduino library version, e.g: 1.58.0]
export ARDUINO_PATH=[Your Arduino + Teensyduino path]
cd $ARDUINO_PATH/hardware/avr/$TEENSYDUINO_VERSION/
curl https://raw.githubusercontent.com/micro-ROS/micro_ros_arduino/iron/extras/patching_boards/platform_teensy.txt > platform.txt

The patch applies the changes detailed on the first two sections of this post: Solution for adding support for pre-compiled Libraries

Patch SAM

Go inside your Arduino installation and replace platform.txt:

export ARDUINO_PATH=[Your Arduino path]
cd $ARDUINO_PATH/hardware/sam/1.6.12/
curl https://raw.githubusercontent.com/micro-ROS/micro_ros_arduino/iron/extras/patching_boards/platform_arduinocore_sam.txt > platform.txt

Custom Messages in MicroROS

You can find detailed information on creating custom messages in MicroROS here

This is a stepwise procedure to make changes in the arduino library:

1. Make library_generation.sh Executable

cd ~/Arduino/libraries/micro_ros_arduino-2.0.5-iron/extras/library_generation
chmod +x library_generation.sh

2. Pull Docker Image for Library Building

cd ~/Arduino/libraries/micro_ros_arduino-2.0.5-iron
docker pull microros/micro_ros_static_library_builder:iron

3. Access Extra Packages Directory

cd ~/Arduino/libraries/micro_ros_arduino-2.0.5-ironextras/library_generation/extra_packages/

4. Create a New Package for Custom Interface

ros2 pkg create --build-type ament_cmake my_custom_message
cd my_custom_message
mkdir msg
touch msg/MyCustomMessage.msg

5. Update CMakeLists.txt for Message Generation

Open CMakeLists.txt in the newly created package and add the following lines just before ament_package():

find_package(rosidl_default_generators REQUIRED)

rosidl_generate_interfaces(${PROJECT_NAME}
  "msg/MyCustomMessage.msg"
)

6. Define Custom Message Content

Note

Edit msg/MyCustomMessage.msg with the desired message content. Ensure the message type name does not contain uppercase letters.

7. Update package.xml

Add the following lines to package.xml:

<build_depend>rosidl_default_generators</build_depend>
<exec_depend>rosidl_default_runtime</exec_depend>
<member_of_group>rosidl_interface_packages</member_of_group>

8. Rebuild Libraries

cd ~/Arduino/libraries/micro_ros_arduino-2.0.5-iron
docker run -it --rm -v $(pwd):/project --env MICROROS_LIBRARY_FOLDER=extras microros/micro_ros_static_library_builder:iron -p esp32

Increase the number of Publishers and Subscribers Limit

You can find detailed information on creating custom messages in MicroROS here

This is a stepwise procedure to make changes in the arduino library:

1. Adjust Parameters in colcon.meta

Open ~/Arduino/libraries/micro_ros_arduino-2.0.5-iron/extras/library_generation/colcon.meta and locate the section:

"rmw_microxrcedds": {
    "cmake-args": [
        "-DRMW_UXRCE_MAX_NODES=1",
        "-DRMW_UXRCE_MAX_PUBLISHERS=5",
        "-DRMW_UXRCE_MAX_SUBSCRIPTIONS=5",
        "-DRMW_UXRCE_MAX_SERVICES=1",
        "-DRMW_UXRCE_MAX_CLIENTS=1",
        "-DRMW_UXRCE_MAX_HISTORY=4",
        "-DRMW_UXRCE_TRANSPORT=custom"
    ]
}

Modify the parameters as needed.

2. Rebuild Libraries

cd ~/Arduino/libraries/micro_ros_arduino-2.0.5-iron
docker run -it --rm -v $(pwd):/project --env MICROROS_LIBRARY_FOLDER=extras microros/micro_ros_static_library_builder:iron -p esp32

Supported Boards and Corresponding Meta Files

Board	.meta file
Arduino Portenta H7 M7 Core	colcon.meta
Arduino Nano RP2040 Connect	colcon_verylowmem.meta
OpenCR	colcon.meta
Teensy 4.0	colcon.meta
Teensy 4.1	colcon.meta
Teensy 3.2/3.1	colcon_lowmem.meta
Teensy 3.5	colcon_lowmem.meta
Teensy 3.6	colcon_lowmem.meta
ESP32 Dev Module	colcon.meta

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 this repository, see the file 3rd-party-licenses.txt.

Known Issues/Limitations

• When using provided precompiled libraries, users should take into account the already configured static memory pools in middleware layers. More info here.
• micro-ROS transports should be refactored in order to provide a pluggable mechanisms. Only USB serial transports are provided.
• Teensyduino support files have to be patched in order to use precompiled libraries.
• To solve Python errors on ESP32 compilation: apt install python-is-python3 && pip3 install pyserial