Skip to content

Latest commit

 

History

History
227 lines (142 loc) · 6.84 KB

getting_started.rst

File metadata and controls

227 lines (142 loc) · 6.84 KB
Raw

Getting started micro-ROS

Table of Contents

Overview

This tutorial provides step-by-step instructions to use Vulcanexus micro tools to build and execute a micro-ROS publisher/subscriber demo.

Prerequisites

Ensure that the Vulcanexus installation includes Vulcanexus micro (either vulcanexus-iron-desktop, vulcanexus-iron-micro, or vulcanexus-iron-base). Also, remember to source the environment in every terminal in this tutorial.

source /opt/vulcanexus/iron/setup.bash

Create a micro-ROS workspace

A workspace is a directory containing ROS 2 packages. Before using ROS 2, it's necessary to source your ROS 2 installation workspace in the terminal you plan to work in. This makes ROS 2's packages available for you to use in that terminal.

source /opt/vulcanexus/iron/setup.bash

# Best practice is to create a new directory for every new workspace.
mkdir -p ~/microros_ws/src
# Another best practice is to put any packages in your workspace into the src directory.
cd ~/microros_ws/src

Build micro-ROS library

The first step is to download and build micro-ROS sources into the created workspace. Vulcanexus micro includes the micro_ros_setup tool, which will handle all the needed steps.

Let's begin using the create_firmware_ws.sh command with host as target:

# Create firmware step.
ros2 run micro_ros_setup create_firmware_ws.sh host

This command will download all needed sources and tools to build micro-ROS as a library. A folder named firmware must be present in your workspace, which will old platform specific tools and source code:

~/microros_ws/src/
├── firmware
│   └── dev_ws
└── src
    ├── eProsima
    │   ├── Micro-CDR
    │   └── Micro-XRCE-DDS-Client
    ├── ros2
    │   ├── common_interfaces
    │   ├── example_interfaces
    │   ├── rcl_interfaces
    │   └── unique_identifier_msgs
    └── uros
        ├── micro-ROS-demos
        ├── micro_ros_msgs
        ├── micro_ros_utilities
        ├── rclc
        ├── rmw_microxrcedds
        └── rosidl_typesupport_microxrcedds

As there is no need for extra configuration steps usually needed for cross-compilation or RTOS configuration, let's build:

# Build step.
ros2 run micro_ros_setup build_firmware.sh

This completes the micro-ROS library build. Remember sourcing this workspace before building or running a micro-ROS app.

# Source micro-ROS installation.
source install/local_setup.bash

Note

A set of examples apps for Linux is also present and build under the src/uros/micro-ROS-demos/rclc directory.

Create a package

Recall that packages should be created in the src directory, not the root of the workspace. So, navigate into microros_ws/src, and run the package creation command:

ros2 pkg create --build-type ament_cmake micro_pubsub
micro_pubsub/
├── CMakeLists.txt
├── package.xml
├── include
│   └── micro_pubsub
└── src

Add micro-ROS apps to the workspace

After the workspace is ready and sourced, micro-ROS applications can be added, build and run.

Note

Certain topics as message memory handling or micro-ROS API details are not covered on this tutorial. Check the micro-ROS User API tutorial for more details.

Write the micro-ROS publisher

On this example app, a publisher will send a periodic string message using a configurable timer.

Add the publisher source code on micro_pubsub/src/micro_publisher.c:

.. literalinclude:: /resources/micro/getting_started/micro_publisher.c
    :language: c

Write the micro-ROS subscriber

This subscriber example is very similar to the publisher, but here the message reception will be handle by the subscriber callback if there is enough memory available.

Add the subscriber source code on micro_pubsub/src/micro_subscriber.c:

.. literalinclude:: /resources/micro/getting_started/micro_subscriber.c
    :language: c

Add dependencies

Before building this examples, micro-ROS used headers and tools need to be included on the created ROS2 package:

  1. Open package.xml on microros_ws/src/micro_pubsub directory
  2. make sure to fill in the <description>, <maintainer> and <license> tags:
<description>Examples of minimal publisher/subscriber using rclcpp</description>
<maintainer email="you@email.com">Your Name</maintainer>
<license>Apache License 2.0</license>
  1. Add a new line after the ament_cmake buildtool dependency and paste the following dependencies corresponding to your node's include statements:
<depend>rcl</depend>
<depend>rclc</depend>
<depend>std_msgs</depend>
<depend>rmw_microxrcedds</depend>
  1. Add the dependencies to the CMakeLists.txt file, the following example can be used:
.. literalinclude:: /resources/micro/getting_started/CMakeLists.txt

Build

Once the source code is ready, build your new package:

# ~/microros_ws
colcon build --packages-select micro_pubsub

Run

Start the Agent

The agent is included on Vulcanexus micro tool set. The default transport configuration for micro-ROS is UDPv4 with the Agent on 127.0.0.1:8888:

# Start the agent
ros2 run micro_ros_agent micro_ros_agent udp4 --port 8888 -v5

This command will start the Agent, allowing communication between our micro-ROS apps and ROS2 environment.

Note

At the top of the apps main function, micro-ROS is initialized using the rclc_support_init method. It is important that the Agent is reachable on this step, as the method will fail if a connection cannot be established.

Run the apps

Before running the apps, set Micro XRCE-DDS as RMW implementation for each terminal:

# Set Micro XRCE-DDS as RMW implementation
export RMW_IMPLEMENTATION=rmw_microxrcedds

Run the publisher in one terminal:

# ~/microros_ws
ros2 run micro_pubsub publisher

Then run listener in another terminal:

# ~/microros_ws
ros2 run micro_pubsub subscriber

The listener will start printing messages to the console. Notice how the creation of entities and each publication appears on the Agent log.