OutdoorNav API Examples

Welcome to the Clearpath Robotics OutdoorNav examples repository! These examples outline how to use the API to define and execute missions.

Building the Examples

Use the steps below to download and build the examples. This can be performed directly on the target robot or on a separate computer with ROS Noetic installed.

mkdir -p ~/outdoornav_ws/src
cd ~/outdoornav_ws
catkin_init_workspace src
cd src
git clone https://github.com/cpr-application/clearpath_onav_examples.git cpr_outdoornav
cd ~/outdoornav_ws
rosdep update
rosdep install -y --from-paths src --ignore-src -r
catkin_make

Running the First Example

The commands below outline how to run one of the example programs when the examples have been downloaded and built on the target robot directly. The remaining examples can be run in a similar manner. If the examples have been downloaded and built on a remote computer, following the instructions at this tutorial to have the remote computer point to the ROS Master on the target robot.

source ~/outdoornav_ws/devel/setup.bash
rosrun clearpath_onav_api_examples simple_mission_1

Running an Inspection Example

The commands below outline how to run an example program that represents a simple inspection mission in the Ag World in which the robot drives between rows of solar panels and collects inspection data at a few key points along the route.

source ~/outdoornav_ws/devel/setup.bash
rosrun clearpath_onav_api_examples inspection_mission_1

The time to run the mission will depend on the speed of your simulation, but will normally be in the range of 5-20 minutes, depending on the compute power of the node running the simulation. The console output should be similar to:

$ rosrun clearpath_onav_api_examples inspection_mission_1
[INFO] [1674669519.255228, 234.054000]: Solar Panel ID: 26.000000 Status: Operating normally
[INFO] [1674669708.237271, 272.053000]: Solar Panel ID: 21.000000 Status: Fault detected
Mission completed successfully

If the UI is open while the mission is running, you should see something similar to the following sequence of images. Note how the robot navigates between two rows of solar panels and stops at two specific panels (one near the midpoint and one near the end of the row) to allow an inspection to be performed.

Running an Area Coverage Example

The commands below outline how to run an example program that represents a simple area coverage mission in the Ag World in which the user defines a bounding region and then the robot drives back and forth to ensure that the simulated scanner provides coverage of the entire area.

source ~/outdoornav_ws/devel/setup.bash
rosrun clearpath_onav_api_examples simple_area_coverage

The time to run the mission will depend on the speed of your simulation, but will normally be in the range of 5-20 minutes, depending on the compute power of the node running the simulation. The console output should be similar to:

$ rosrun clearpath_onav_api_examples simple_area_coverage
[INFO] [1675994738.888331, 45.537000]: Computing waypoints for (-65.134179, -0.264033), (-65.134179, 14.735967), (-25.134179, 14.735967), (-25.134179, -0.264033)
[INFO] [1675996427.370797, 260.487000]: Adding result: 99 at (50.109474, -97.319886)
[INFO] [1675996477.491238, 271.487000]: Adding result: 92 at (50.109458, -97.319889)
...
Mission completed successfully. Scanner hits:
Scanner reading 99 at Lat: 50.109474 Lon: -97.319886
Scanner reading 92 at Lat: 50.109458 Lon: -97.319889
...

If the UI is open while the mission is running, you should see something similar to the following images.

Reading and Writing Mission Configuration

Missions can be saved to and loaded from YAML configuration files. Refer to the mission_from_yaml_file example for details.

Obtaining Goalpoint and Viapoint Coordinates

Missions are made up of one or more Goals, each of which has a Goalpoint (the endpoint of the path to the Goal) and zero or more Viapoints (intermediate points leading to the Goal). The essential properties of both Goalpoints and Viapoints are the coordinates of the point. When using the Web UI, the coordinates are determined based on the map location where the operator clicks to add points. However, since there is no UI for the API, how does a user get coordinates to build and run missions via the API? There are several options.

1. Use a third party resource, such as Google Maps, to manually identify the coordinates for your points. See simple_mission_1 and simple_mission_2 for examples of mission that rely on external sources for coordinates and use those to build up the mission.

2. Build the mission using the Web UI, then import the saved Web UI configuration into your API code. Refer to the mission_from_webui_config example.

3. Manually navigate the robot through the mission one time, collecting the coordinates at the points of interest.

* Use the joystick or the Web UI to teleoperate the robot. Begin at the
  starting point, record the coordinates, drive to the next point,
  record the coordinates, and so on.

* To collect the coordinates, you can use the **getRobotPosition** tool,
  which extracts the current coordinates and can be used to append to a
  CSV file. For goalpoints, also provide a name; for viapoints, omit the
  name. See **sample_mission.csv** for an example CSV file.

      # Drive the robot to the start point
      getRobotPosition > mission1.csv
      # Drive the robot to the next viapoint for Goal A
      getRobotPosition >> mission1.csv
      # Drive the robot to the goalpoint A
      getRobotPosition A >> mission.csv
      ## Drive the robot to a new goalpoint B (assume no viapoints)
      getRobotPosition B >> mission.csv

* Once the CSV has been created, import it as a mission. Refer to the
  **mission\_from\_csv\_config** example.

Using the API Examples Library

In clearpath_onav_api_examples_lib, there is a python wrapper for the ROS API, which makes it easier to get started in building applications. To generate HTML documentation for the library using Sphinx:

1. Complete the steps above for Building the Examples.

2. pip install sphinx

3. cd ~/outdoornav_ws/src/cpr_outdoornav/clearpath_onav_api_examples_lib/docs

4. make html

5. Open ~/outdoornav_ws/src/cpr_outdoornav/clearpath_onav_api_examples_lib/docs/_build/html/index.html in your browser.