Skip to content

Latest commit

 

History

History
151 lines (109 loc) · 9.91 KB

README.md

File metadata and controls

151 lines (109 loc) · 9.91 KB
Raw

mros2

mros2 (formally mROS 2) realizes an agent-less and lightweight runtime environment compatible with ROS 2 for embedded devices. It consists of basic APIs for pub/sub communication, RTPS protocol, UDP/IP stack, and real-time kernel. Embedded nodes can now communicate directly with native ROS 2 nodes via topic!

This repository maintains the communication layer of mROS 2, that mainly offers pub/sub APIs compatible with rclcpp for embedded devices. ROS 2 is a de-fact platform for the robot system development and provides pub/sub communication infrastructure with the DDS/RTPS protocol.

Features

  • Agent-less: A node on mROS 2 autonomously discovers communication nodes on the host. No agent/bridge is required for pub/sub communication from the embedded devices.
  • Lightweight: mROS 2 APIs are implemented by C++ to be operated on the embedded devices. All software stacks are also implemented only in C/C++.
  • Real-time: mROS 2 uses the real-time kernel (e.g., TOPPERS kernel, Mbed OS) as the runtime platform in order to enhance the real-time capability.

Functionalities and limitations

Here are the functionalities that mROS 2 offers for you, and current limitations (a.k.a call for your contributions!).

  • Pub/Sub communication via Topic is supported
    • Built-in-types
      • wstring (UTF-16) is not provided due to its difficulty in verification, but it is unlikely to be used.
      • array types are not supported
    • Some custom message types (e.g., Twist, Pose)
      • Please check #generating-header-files-for-custom-msgtypes for more details.
      • Fragmented message types (that exceed one packet) are experimentally supported. See PR#36 for more details.
      • We think variable-length types cannot be handled, probably due to the limitation of lwIP.
  • Service, Actions, and Parameters are not supported
    • Please let us know if you want to use them as soon as possible. We can consider raising the priority of these supports.
  • mros2 node name cannot be observed from ROS 2 host (see Issue#44)

Supported platform

Since this repository itself only maintains the communication layer of mROS 2, we also publish the implementation on the embedded board using this layer and the embedded kernel. Please see each repository to learn how to use it.

name kernel board support status
mros2-asp3-f767zi TOPPERS/ASP3 STM32 NUCLEO-F767ZI currently supported up to v0.3.2 (see status)
mros2-mbed Mbed OS 6 Mbed enabled boards having an Ethernet port (See detail) well maintained and easy to try
mros2-esp32 ESP-IDF FreeRTOS ESP32 boards with 2.4 GHz Wi-Fi (See detail) well maintained
mros2-posix POSIX (pthread) any machine that runs Linux partly maintained

Please let us know if you have a request for support for other boards/kernels, or if you could implement this layer on other platforms.

Generating header files for custom MsgTypes

You can use almost any built-in-types in ROS 2 on the embedded device. Not that array types are not supported yet.

You can also use following message types that are commonly used. We have prepared and located them in mros2_msgs/.

In additon, you can define a customized message type in the same way as in ROS 2, and use its header file for your application.
The rest of this section describes how to generate header files for your own MsgTypes. The example assumes the location as <this_repo_dir>/mros2_msgs/ and target as geometry_msgs::msg::Twist. The location is arbitrary, but be careful with the paths of the Python script and the .msg file.

Prepare .msg files

.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 <this_repo_dir>/mros2_msgs/geometry_msgs/msg/.

$ pwd
<this_repo_dir>/mros2_msgs

$ cat 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 geometry_msgs/msg/Vector3.msg
float64 x
float64 y
float64 z

Generate header files

To generate header files for Twist and Vector3, run the following command in <this_repo_dir>/mros2_msgs/ (again, be careful about the paths!).

$ cd <this_repo_dir>/mros2_msgs
$ python3 ../mros2_header_generator/header_generator.py geometry_msgs/msg/Twist.msg

Make sure header files for custom MsgType are generated in geometry_msgs/.

$ ls -R geometry_msgs/
geometry_msgs:
msg

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 "mros2-platform.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.>

When you generated your own header files at an arbitrary location, you need to add its path as an include path for build (e.g., CMakeLists.txt).

If you generated new header files at <this_repo_dir>/mros2_msgs/, we are very welcome to your PR!!

License

The source code of this repository itself is published under Apache License 2.0.
Please note that this repository contains embeddedRTPS and its third-party libraries as the submodule, and also check their Licenses.

Publications/References

English

Japanese ;(