Skip to main content

Appendix A: IndoorNav ROS 2 API

In addition to the Web GUI, IndoorNav provides a ROS 2 API for programmatic interactions. Documentation for this API is included in the clearpath-api package, installable with apt:

sudo apt install clearpath-api

Once the package is installed, the documentation can be found at /opt/clearpath/ros2-api-1.3.3/share/public. Alternatively, the documentation can be downloaded directly from docs.ottomotors.com (requires an OTTO Motors account to log in).

API Summary

The ROS 2 API is separated into 3 main categories, each operating on a separate ROS 2 Domain, as outlined in the table below:

ROS 2 API Domain IDs

Domain IDDescription
100Fleet API
110Autonomy API
95Platform API

The Fleet API is intended to allow the robot to be controlled by an external fleet manager.

The Autonomy API enables control of a single robot's autonomy and navigation.

The Platform API is not available for use with IndoorNav. Instead of using the Platform API, developers should use the base robot's ROS 1 nodes to interact with the robot hardware.

Additional details on the Fleet, Autonomy, and Platform APIs can be found on docs.ottomotors.com.

API Examples

OTTO Motors provides examples of working with their ROS 2 API. These examples can be found in /opt/clearpath/ros2-api-1.3.3/share/clearpath_api/examples/

To build the examples, create a Colcon workspace, copy (or symlink) the examples folder into the src folder, and build using the colcon build command:

mkdir -p $HOME/example_ws/src
cd $HOME/example_ws/src
ln -s /opt/clearpath/ros2-api-1.3.3/share/clearpath_api/examples/ $(pwd)/examples
cd ..
source /opt/ros/foxy/setup.bash
source /opt/clearpath/ros2-api-1.3.3/local_setup.bash
colcon build

The examples folder contains 3 programs:

  • send_move_goal: command the robot to drive to an (X, Y, Yaw) position on the map
  • monitor_odom_intent: print the robot's odometry and planning data as it navigates
  • get_map_info: get information about the map saved on the robot
note

At the time of writing there is a known bug in the get_map_info example; it always returns an empty array. This will be corrected ASAP.

Refer to the source code for the examples for more information about their use. All examples should be run using the Fleet API domain ID.

Accessing Noetic Topics in ROS 2

The Clearpath Robotics base platform is configured to bridge sensor data, velocity control, wireless connection status, power information, and other basic topics into ROS 2 on domain ID 121. The bridged topics are prefaced with the robot's hostname (with any hyphens replaced with underscores). For example:

export ROS_DOMAIN_ID=121
ros2 topic list
/cpr_dora/battery_status
/cpr_dora/cmd_vel
/cpr_dora/front/scan
/cpr_dora/gx5/imu/data
/cpr_dora/imu/data
/cpr_dora/navsat/fix
/cpr_dora/rear/scan
/cpr_dora/wireless/connected

Publishing to the {hostname}/cmd_vel topic will drive the robot:

ros2 topic pub /cpr_dora/cmd_vel geometry_msgs/msg/Twist '{linear: {x: 0.1}}' -r 10

All other topics are read-only and will publish sensor/power/wireless information at the same rate as their ROS 1 topics.

Using the ROS 2 API with ROS Noetic

note

At present the ROS 2 API is unstable when bridged into ROS 1 Noetic. You are welcome to experiment with developing ROS 1 nodes that use the bridged topics, but Clearpath Robotics can only offer minimal support.

To enable bridging the ROS 2 Fleet and Platform APIs into the ROS 1 Noetic master, set the INDOORNAV_ENABLE_ROS2_TO_ROS1_BRIDGE envar to 1 in /etc/ros/setup.bash:

export INDOORNAV_ENABLE_ROS2_TO_ROS1_BRIDGE=1

This will start 2 ros1_bridge nodes (one for domain 110 and one for domain 95). Bridged topics will be visible in the fleet_api and autonomy_api namespaces when rostopic list is run.

You will need to build or install the clearpath_api messages and service definitions for Noetic.