mROS 2 (formly mros2
) realizes a agent-less and lightweight runtime environment compatible with ROS 2 for embedded devices.
mROS 2 mainly offers pub/sub APIs compatible with rclcpp for embedded devices.
mROS 2 consists of communication library for pub/sub APIs, RTPS protocol, UDP/IP stack, and real-time kernel. This repository provides the reference implementation of mROS 2 that can be operated on the embedded board. Please also check mros2 repository for more details and another implementations.
- Embedded device
- Board: STM32 NUCLEO-F767ZI
- Kernel: TOPPERS/ASP3
- Host environment
- ROS 2 Foxy Fitzroy on Ubuntu 20.04 LTS
- ROS 2 Dashing Diademata on Ubuntu 18.04 LTS
- Install ROS 2 Foxy Fitzroy on the host with Ubuntu 20.04 LTS.
- You can also use Docker as the host environment instead. Please check "Tips 1" section.
- Install arm-none-eabi v7.3.1.
- There are two ways to install the appropriate version.
- Download and unzip the prebuilt archive of GNU Arm Embedded Toolchain from official Arm website. Please select "GNU Arm Embedded Toolchain: 7-2018-q2-update June 27, 2018" and "Linux 64-bit" as the archive.
Then, unzip the downloaded archive to any location (/usr/local/
is recommended) and set <unzipped_dir>/bin to$PATH
. - Install STM32CubeIDE v1.5.0. It contains v7.3.1 cross-compiler.
If you did not change the default location to be installed,
$PATH
to be set will be /opt/st/stm32cubeide_1.5.0/plugins/com.st.stm32cube.ide.mcu.externaltools.gnu-tools-for-stm32.7-2018-q2-update.linux64_1.5.0.202011040924/tools
- Download and unzip the prebuilt archive of GNU Arm Embedded Toolchain from official Arm website. Please select "GNU Arm Embedded Toolchain: 7-2018-q2-update June 27, 2018" and "Linux 64-bit" as the archive.
- Currently, we confirmed issue that v6.3.1 (which will be installed via
apt
) cannot be operated successfully. See also #36.
- There are two ways to install the appropriate version.
- Connet the board and the host with LAN cable and micro-USB cable (CN1 connector on the board, opposite side of LAN connector). Please set the IP address and Netmask of the host to
192.168.11.x
and255.255.255.0
, respectively.- The IP address of the board will be assigned to
192.168.11.2
. If you want to change the IP settings, you need to modify src/config/lwip.c and src/config/rtps/config.h as you want. - You can also connect the network with the board through the router when you can set the IP and Netmask as the above.
- The firewall on the host (Ubuntu) needs to be disabled for ROS 2 (DDS) communication (e.g.
$ sudo ufw disable
) - If the host is connected to the Internet other than wired network (e.g., Wi-Fi), communication with mros2 may not work properly. In that case, please turn off them.
- The IP address of the board will be assigned to
This section explains how to build and execute mROS 2 with TOPPERS/ASP3 kernel, using echoreply_string
application as an example.
This example only uses a built-in-type (string
a.k.a std_msgs::msg::String
), so you can skip the generation of header files for custom msg types. Please see Generating header files for custom MsgTypes for more detail.
First of all, clone this repository. Note that --recursive is mandatory.
$ git clone --recursive https://github.com/mROS-base/mros2-asp3-f767zi
Move to workspace and operate make
with the target app name (please see workspace/ for another examples).
$ cd mros2-asp3-f767zi
$ cd workspace
$ make clean
$ make app=echoreply_string
Once build process can be completed, you can find asp.bin
and asp.elf
as the binary. Please copy the binary to the board for the deployment.
$ ls asp*
asp.bin asp.elf
$ cp asp.bin /media/$USER/NODE_F767ZI/
We also provide the implemenation of ROS 2 nodes that communicate to the embedded device. (You can also use Docker as the host environment instead. Please check "Tips 1" section).
Clone the repository and build in <your_ros2_ws>.
$ cd <your_ros2_ws>/src
$ git clone https://github.com/mROS-base/mros2-host-examples
$ cd <your_ros2_ws>
$ colcon build --packages-select mros2_echoback_string
$ source install/local_setup.bash
- Connect the serial port of the board with
picocom
, and then push RESET button. Please wait a while until the message "mROS2 init complete
" is confirmed. It means that the initiation process for mROS 2 has completed successfully.
$ picocom -b 115200 /dev/ttyACM0
(skip)
Terminal ready
TOPPERS/ASP3 Kernel Release 3.5.0 for NUCLEO(STM32F767ZI:ARM Cortex-M7) (Aug 19 2021, 12:33:55)
Copyright (C) 2000-2003 by Embedded and Real-Time Systems Laboratory
Toyohashi Univ. of Technology, JAPAN
Copyright (C) 2004-2019 by Embedded and Real-Time Systems Laboratory
Graduate School of Information Science, Nagoya Univ., JAPAN
System logging task is started.
mROS 2 application is started
mROS 2 initialization is completed
[MROS2LIB] create_node
[MROS2LIB] start creating participant
[MROS2LIB] mros2_init task start
[MROS2LIB] Initilizing lwIP complete
[MROS2LIB] successfully created participant
[MROS2LIB] create_publisher complete.
[MROS2LIB] create_subscription complete. data memory address=0x2001d628
ready to pub/sub message
[MROS2LIB] Initilizing Domain complete
- Launch ROS 2 nodes on the host on another terminal.
$ cd <your_ros2_ws>
$ source install/local_setup.bash
$ ros2 launch mros2_echoback_string pubsub.launch.py
[INFO] [launch]: Default logging verbosity is set to INFO
[INFO] [pub_node-1]: process started with pid [21232]
[INFO] [sub_node-2]: process started with pid [21233]
[pub_node-1] [INFO] [pub_mros2]: Publishing msg: 'Hello, world! 0'
[sub_node-2] [INFO] [mros2_sub]: Subscribed msg: 'Hello, world! 0'
[pub_node-1] [INFO] [pub_mros2]: Publishing msg: 'Hello, world! 1'
[sub_node-2] [INFO] [mros2_sub]: Subscribed msg: 'Hello, world! 1'
[pub_node-1] [INFO] [pub_mros2]: Publishing msg: 'Hello, world! 2'
[sub_node-2] [INFO] [mros2_sub]: Subscribed msg: 'Hello, world! 2'
[pub_node-1] [INFO] [pub_mros2]: Publishing msg: 'Hello, world! 3'
[sub_node-2] [INFO] [mros2_sub]: Subscribed msg: 'Hello, world! 3'
<cont.>
- Now, you can confirm the message of the board (on
picocom
terminal) 🎉
<continue from 1.>
[MROS2LIB] publisher matched with remote subscriber
[MROS2LIB] subscriber matched with remote publisher
subscriber matched with remote publisher
publisher matched with remote subscriber
subscribed msg: 'Hello, world! 0'
publishing msg: 'Hello, world! 0'
subscribed msg: 'Hello, world! 1'
publishing msg: 'Hello, world! 1'
subscribed msg: 'Hello, world! 2'
publishing msg: 'Hello, world! 2'
subscribed msg: 'Hello, world! 3'
publishing msg: 'Hello, world! 3'
<cont.>
NOTE: due to the current implementation, the order of operation is very important. We need to start up the mROS 2 node at first, and then operate ROS 2 nodes on the host.
Please see workspace/ for example applications.
You can use almost any built-in-types in ROS 2 on the embedded device.
In additon, you can define a customized message type (e.g., Twist.msg
) in the same way as in ROS 2, and use its header file for your application. This section describes how to generate header files for your own MsgTypes (geometry_msgs::msg::Twist
as an example).
.msg
files are simple text files that describe the fields of a ROS message (see About ROS 2 interface). In mros2, they are used to generate header files for messages in embedded applications.
Prepare Twist.msg
file and make sure it is in workspace/custom_msgs/geometry_msgs/msg/
.
$ cat workspace/custom_msgs/geometry_msgs/msg/Twist.msg
geometry_msgs/msg/Vector3 linear
geometry_msgs/msg/Vector3 angular
In this example, Twist
has a nested structure with Vector3
as a child element. So you also need to prepare its file.
$ cat workspace/custom_msgs/geometry_msgs/msg/Vector3.msg
float64 x
float64 y
float64 z
To generate header files for Twist
and Vector3
, execute make gen-msg msg=geometry_msgs/msg/Twist.msg
in workspace/
.
$ cd workspace
$ make gen-msg msg=geometry_msgs/msg/Twist.msg
header file for custom message was generated from geometry_msgs/msg/Twist.msg
Make sure header files for custom MsgType are generated in custom_msgs/
$ ls -R custom_msgs/
custom_msgs/:
geometry_msgs
custom_msgs/geometry_msgs:
msg
custom_msgs/geometry_msgs/msg:
twist.hpp vector3.hpp Twist.msg Vector3.msg
You can now use them in your applicaton like this.
#include "mros2.hpp"
#include "geometry_msgs/msg/vector3.hpp"
#include "geometry_msgs/msg/twist.hpp"
int main(int argc, char * argv[])
{
<snip.>
pub = node.create_publisher<geometry_msgs::msg::Twist>("cmd_vel", 10);
<snip.>
There are two files for network configulation.
- src/startup/include/lwipots.h for lwIP
- src/config/rtps/config.h for embeddedRTPS
Currently, we are unable to communicate large size of messages probably due to these configurations. We should seek the appropreate configurations or how to fit them to the demand of applications.
Please let us know about this if you have any opinions or awesome knowledges! #60
If you do not want to prepare ROS 2 environment on your PC, using Docker is a good alternative to check the operation of mros2 just in 5 minutes. Type the command below.
docker run --rm -it --net=host ros:foxy /bin/bash \
-c "source /opt/ros/foxy/setup.bash &&
cd &&
git clone https://github.com/mROS-base/mros2-host-examples &&
cd mros2-host-examples &&
colcon build --packages-select mros2_echoback_string &&
source install/setup.bash &&
ros2 launch mros2_echoback_string pubsub.launch.py"
We offer a comfortable development environment with Visual Studio Code (VS Code). Building, flashing and debugging the application can be done with simple operations in one window.
- Visual Studio Code
- VS Code Extensions
- OpenOCD (
$ sudo apt install openocd
)
- Build project for mros2 application
- Just type
Ctrl+Shift+B
or [Terminal] -> [Run Build Task...] - The binary will be copied to the board at the final step when the board is connected to the host.
- You can change the target application name by editing
"app=echoreply_string"
in.vscode/tasks.json
.
- Just type
- Clean project
- [Terminal] -> [Run Task...] and then select Clean project
- Flashing program (ELF-format) to the board
- [Terminal] -> [Run Task...] and then select Flash program
- Debugging
- Just type
F5
or [Run] -> [Start Debugging] - You need to rebuild project manually before debugging when you edit code.
- Just type
The source code of this repository itself is published under Apache License 2.0.
Please note that this repository contains the following stacks as the submodules, and also check their Licenses.
- mros2: the pub/sub APIs compatible with ROS 2 Rclcpp
- embeddedRTPS: RTPS communication layer (including lwIP and Micro-CDR)
- asp3-f767zi: TOPPERS/ASP3 kernel for STM32 NUCLEO-F767ZI
- cmsis-asp3: interface layer between CMSIS OS API and TOPPERS kernel
- STM32CubeF7: STM32Cube MCU package for the STM32F7 series