rmw_email

ROS 2 over email. rmw_email contains a middleware that sends & receives strings over email and an RMW implementation that allows ROS 2 to use this middleware to exchange messages.

For an overview of the motivation and process behind this project, see this blog post: christophebedard.com/ros-2-over-email.

1. Overview
2. Packages
3. Supported features
   1. Platform support
4. Performance
5. How to use
6. Configuration
7. Tracing
8. Logging
9. email examples

Overview

rmw_email_cpp uses type support introspection to convert messages to YAML objects. This is done for both C and C++ type supports using the dynmsg package. The YAML objects are then converted to strings.

Those strings are sent via email using the email package. The topic name is used as the email subject; the email body contains the YAML string representing the message. Messages can therefore easily be read.

To receive messages, this process is repeated in the opposite direction.

Successive messages on the same topic generally end up in the same email thread (depending on the client). Service responses are email replies to the corresponding email request (this is handled by email).

email also has an intraprocess communication mode to bypass actually sending and receiving emails.

Packages

This repository contains a few packages:

• email: simple publish/subscribe & service middleware using emails to exchange strings
  • See the API documentation.
  • See the design document (rendered version).
  • This package claims to be in the Quality Level 4 category, see the Quality Declaration for more details.
  • 
• email_examples: various examples using email
  • See email examples.
  • This package claims to be in the Quality Level 4 category, see the Quality Declaration for more details.
• rmw_email_cpp: ROS 2 rmw implementation using email as the middleware
  • See supported features.
  • This package claims to be in the Quality Level 4 category, see the Quality Declaration for more details.
  • 

Supported features

The following table shows the features currently supported/unsupported by rmw_email_cpp.

Platform support

rmw_email was primarily developed on Ubuntu. However, it should work on macOS and Windows without too much effort. See REP 2000.

Performance

We can use performance_test to compare the performance of rmw_email_cpp to another RMW implementation.

See the perf_test.sh and perf_plot.sh scripts to run performance_test and generate a plot like the one above.

How to use

1. Clone this repo into your ROS 2 workspace

   $ cd ~/ws/src/
   $ git clone https://github.com/christophebedard/rmw_email.git
   

1. Clone dependencies

   $ cd ~/ws/
   $ vcs import src --input https://raw.githubusercontent.com/christophebedard/rmw_email/rolling/dependencies.repos
   

1. Build

   $ cd ~/ws/
   $ colcon build  # ...
   

1. Create email configuration file(s) for your executable(s)
   See configuration.
2. Use by setting the RMW_IMPLEMENTATION environment variable to rmw_email_cpp and the EMAIL_CONFIG_FILE environment variable to your configuration file, e.g.

   $ cd ~/ws/
   $ source install/setup.bash
   $ export RMW_IMPLEMENTATION=rmw_email_cpp
   $ export EMAIL_CONFIG_FILE=path/to/email.yml
   $ ros2 run demo_nodes_cpp talker
   $ # ...
   

Configuration

In order to send & receive emails, a YAML configuration file must be provided. By default, the path to the config file is email.yml, relative to the current working directory. However, the path can be changed using the EMAIL_CONFIG_FILE environment variable, e.g., EMAIL_CONFIG_FILE=other/dir/myemail.yml. If that file does not exist, ~/email.yml will be used as a backup if it exists.

A sample configuration file is provided: email.yml. As for the values:

• url-smtp: SMTP server URL
  • for Gmail: smtp.gmail.com
• url-imap: IMAP server URL
  • for Gmail: imap.gmail.com
• username: your email address
• password: your password
  • it is recommended to generate a “unique” password. For Gmail, that is an app password. Under Select app, click Other (Custom name) and simply enter something like rmw_email. Copy the generated password and paste it in the config file.
• to/cc/bcc: recipients
  • either as simple string values or as an array of string values, e.g.:

         to: my@email.com
         cc:
           - some@email.com
           - another@email.com
         

  * `to` must be defined and must contain at least one email address, but `cc` and `bcc` are optional    * `polling-period`: email polling period in nanoseconds
  * optional; by default, polling will be done as fast as possible    * `intraprocess`: enable intraprocess mode by setting to `true`
  * optional; by default, intraprocess is disabled
  * this makes `email` act as if it was sending emails to itself and entirely bypasses actually sending and receiving emails
  * all other options are optional and have no effect in practice if intraprocess is enabled

Using the same configuration file with the same email for the username and to fields (i.e., same email address for sending & receiving) for multiple executables should work. Alternatively, you can use two different configuration files for two different executables, e.g., if they’re sending emails to each other.

Tracing

email has LTTng tracepoints for publishers and subscriptions. See email/include/email/lttng.hpp. Tracepoints are automatically included if LTTng is installed and detected. To completely remove them, build with --cmake-args -DEMAIL_ENABLE_TRACING=OFF.

rmw_email_cpp supports the ros2_tracing tracepoints for the rmw layer. It also has another LTTng tracepoint in order to link ROS 2 messages to email messages. See rmw_email_cpp/include/rmw_email_cpp/lttng.hpp. See ros2_tracing’s README for information on how to enable or disable tracepoints.

Logging

There are a few logging options for email itself:

1. Set the console logging level through the EMAIL_LOG_LEVEL environment variable, e.g., EMAIL_LOG_LEVEL=debug.
   • The logging levels are: off, debug, info, warn, error, and fatal.
   • The default level is info.
2. Write all logs to a file by setting the EMAIL_LOG_FILE environment variable to a file path.
   • This writes all logs to the file, independently of the logging level set through EMAIL_LOG_LEVEL.
   • A leading ~ is expanded to the user’s home directory.
3. Set the EMAIL_CURL_VERBOSE environment variable to be non-empty, e.g., EMAIL_CURL_VERBOSE=y. This will enable libcurl’s verbose option.
   • Generally produces too much output to be useful.

As for rmw_email_cpp, simply use the existing logging configuration options, including:

1. CLI option

   $ ros2 run $pkg $exec --ros-args --log-level debug
   $ ros2 run $pkg $exec --ros-args --log-level rmw_email_cpp:=debug
   

email examples

The email_examples package contains simple examples using email:

• email sender
• email receiver
• publisher
  • simple publisher
• subscription
  • simple subscription with busy waiting
  • subscription using wait utilities
  • subscription using a wait set directly
  • subscription with message info
• service client
  • simple service client with busy waiting
  • service client using wait utilities
  • service client with response info
• service server
  • simple service server with busy waiting
  • service server using wait utilities
  • service server with request info
• intraprocess (meant to be used with the intraprocess option enabled)
  • publisher & subscription
    • simple publisher with a subscription with message info in the same process
  • service client & service server
    • service client and service server with service info in the same process

Any contribution that you make to this repository will be under the Apache 2 License, as dictated by that license:

5. Submission of Contributions. Unless You explicitly state otherwise,
   any Contribution intentionally submitted for inclusion in the Work
   by You to the Licensor shall be under the terms and conditions of
   this License, without any additional terms or conditions.
   Notwithstanding the above, nothing herein shall supersede or modify
   the terms of any separate license agreement you may have executed
   with Licensor regarding such Contributions.

Contributors must sign-off each commit by adding a Signed-off-by: ... line to commit messages to certify that they have the right to submit the code they are contributing to the project according to the Developer Certificate of Origin (DCO).