API Documentation

In addition to the Web GUI, IndoorNav provides a ROS2 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 ROS2 API is separated into 3 main categories, each operating on a separate ROS2 Domain, as outlined in the table below:

ROS2 API Domain IDs

Domain ID

Description

100

Fleet API

110

Autonomy API

95

Platform 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 ROS1 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 ROS2 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 ROS2

The Clearpath Robotics base platform is configured to bridge sensor data, velocity control, wireless connection status, power information, and other basic topics into ROS2 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 ROS1 topics.

Using the ROS2 API with ROS Noetic

Note

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

To enable bridging the ROS2 Fleet and Platform APIs into the ROS1 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.