Zephyr Emulator

Installing ROS 2 and the micro-ROS build system

# Source the ROS 2 installation
source /opt/ros/$ROS_DISTRO/setup.bash

# Create a workspace and download the micro-ROS tools
mkdir microros_ws
cd microros_ws
git clone -b $ROS_DISTRO https://github.com/micro-ROS/micro_ros_setup.git src/micro_ros_setup

# Update dependencies using rosdep
sudo apt update && rosdep update
rosdep install --from-paths src --ignore-src -y

# Install pip
sudo apt-get install python3-pip

# Build micro-ROS tools and source them
colcon build
source install/local_setup.bash

Creating a new firmware workspace

Once the build system is installed, let’s create a firmware workspace that targets all the required code and tools:

# Create step
ros2 run micro_ros_setup create_firmware_ws.sh zephyr host

This step is in charge, among other things, of downloading a set of micro-ROS apps for the specific platform you are addressing. In the case of Zephyr, these are located at firmware/zephyr_apps/apps. Each app is represented by a folder containing the following files:

• src/main.c: This file contains the logic of the application.

• app-colcon.meta: This file contains the micro-ROS app specific colcon configuration. Detailed info on how to configure the RMW via this file can be found here.

• CMakeLists.txt: This is the CMake file containing the script to compile the application.

• <transport>.conf: This is a Zephyr specific and transport-dependent app configuration file. <transport> can be serial, serial-usb and host-udp.

Configuring the firmware

The configuration step will set up the main micro-ROS options and select the desired application. It can be executed with the following command:

# Configure step
ros2 run micro_ros_setup configure_firmware.sh [APP] [OPTIONS]

The options available for 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

• --ip or -i: agent IP in a network-like transport

• --port or -p: agent port in a network-like transport

In this tutorial, we will use a UDP transport that looks for the agent on the port UDP/8888 at localhost, and focus on the out-of-the-box ping_pong application located at firmware/zephyr_apps/apps/ping_pong. To execute this application with the chosen transport, run the configuration command above by specifying the [APP] and [OPTIONS] parameters as below:

# Configure step
ros2 run micro_ros_setup configure_firmware.sh ping_pong --transport udp --ip 127.0.0.1 --port 8888

You can check the complete content of the ping_pong app here.

This example showcases a micro-ROS node with two publisher-subscriber pairs associated with a ping and a pong topics, respectively. The node sends a ping package with a unique identifier, using a ping publisher. If the ping subscriber receives a ping from an external node, the pong publisher responds to the incoming ping with a pong. To test that this logic is correctly functioning, we implement communication with a ROS 2 node that:

• Listens to the topics published by the ping subscriber.

• Publishes a fake_ping package, that is received by the micro-ROS ping subscriber. As a consequence, the pong publisher on the micro-ROS application will publish a pong, to signal that it received the fake_ping correctly.

The diagram below clarifies the communication flow between these entities:

The contents of the Zephyr app specific files can be found here: main.c, app-colcon.meta, CMakeLists.txt and host-udp.conf. A thorough review of these files is illustrative of how to create a micro-ROS app in this RTOS.

Building the firmware

When the configuring step ends, just build the firmware:

# Build step
ros2 run micro_ros_setup build_firmware.sh

Now you have a Zephyr + micro-ROS app ready to run on your own computer. Notice that in this case, the steps of flashing the firmware and running the micro-ROS app go together.

Creating the micro-ROS agent

The micro-ROS app is now ready to be connected to a micro-ROS agent to start talking with the rest of the ROS 2 world. To do that, let’s first of all create a micro-ROS agent:

# Download micro-ROS-Agent packages
ros2 run micro_ros_setup create_agent_ws.sh

Now, let’s build the agent packages and, when this is done, source the installation:

# Build step
ros2 run micro_ros_setup build_agent.sh
source install/local_setup.bash

Running the micro-ROS app

At this point, you have both the client and the agent correctly installed in your host machine.

To give micro-ROS access to the ROS 2 dataspace, run the agent:

# Run a micro-ROS agent
ros2 run micro_ros_agent micro_ros_agent udp4 --port 8888

Flashing the firmware

Finally, in order to run the micro-ROS node inside of the Zephyr RTOS emulator, open a new command shell and execute the flash step by means of the flashing command:

source /opt/ros/$ROS_DISTRO/setup.bash
source install/local_setup.bash

# Flash/run step
ros2 run micro_ros_setup flash_firmware.sh

Testing the micro-ROS app

Now, we want to check that everything is working.

Open a new command line. We are going to listen to the ping topic with ROS 2 to check whether the micro-ROS Ping Pong node is correctly publishing the expected pings:

source /opt/ros/$ROS_DISTRO/setup.bash

# Subscribe to micro-ROS ping topic
ros2 topic echo /microROS/ping