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 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 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 mapmonitor_odom_intent: print the robot's odometry and planning data as it navigatesget_map_info: get information about the map saved on the robot
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
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.