-
Notifications
You must be signed in to change notification settings - Fork 39
Using OceanWATERS
The following instructions assume familiarity with Unix/Linux and the Bash shell command line.
The minimum recommended hardware configuration is as follows:
- 2.0 GHz quad core x86-64 CPU
- 16 GB memory
- Nvidia graphics card. GeForce GTX 750-Ti, GeForce GTX 960M, Quadro M1200, or better.
The following minimum software set is required to build and run OceanWATERS (version numbers and identifiers are listed where specific versions are required):
- The Ubuntu 18.04 (Bionic) Linux operating system, with:
- The Bash command shell
- The git version control system
- Virtual machines (e.g., VMware, Parallels, VirtualBox) work to some degree, but tend to have limited graphics support. They are not recommended for OceanWATERS testbed development.
- The Robot Operating System (ROS), Melodic Morenia distribution, with:
- Gazebo 9.13
- The Catkin build system
In addition to the above software, it is highly recommended that the following optional software be installed for initial familiarization and development with the OceanWATERS testbed:
- The Plan Execution Interchange Language (PLEXIL), a plan language and executive
In the following instructions, we assume the default command shell is Bash.
The OceanWATERS distribution includes an optional example autonomy module that depends on PLEXIL, an open-source plan authoring language and autonomy executive implementation (see http://plexil.sourceforge.net/wiki/index.php/Main_Page). If you do not wish to use the provided autonomy module (e.g., with the intention of implementing your own autonomy solution), PLEXIL installation may be skipped. However, the autonomy module is a useful working example of how to interface to the testbed.
For use within OceanWATERS, PLEXIL must be installed prior to building OceanWATERS. PLEXIL binary and source downloads are available here:
See Appendix C for detailed PLEXIL installation instructions.
Installation of OceanWATERS requires prior installation of ROS Melodic. ROS binary downloads for Ubuntu Linux are available here:
and instructions for installing ROS are available here:
By default, ROS is installed in /opt/ros/<release>. In the following installation instructions, we assume that ROS is installed in /opt/ros/melodic.
Installation of OceanWATERS requires creation of a ROS workspace – a directory where you can build multiple, interdependent ROS packages (http://wiki.ros.org/catkin/workspaces). ROS provides custom tools, catkin and wstool, to manage, build, and install ROS packages in a workspace. Catkin is a build system that sits on top of the CMake build system (https://cmake.org) and wstool is a meta–version control system tool that allows you to manage multiple source repositories.
To create a ROS workspace for OceanWATERS first use the setup.bash script provided in the ROS installation to set required ROS environment variables:
source /opt/ros/melodic/setup.bash
For convenience users may want to add the above command to their ~/.bashrc file.
Next create a workspace directory for OceanWATERS with a src subdirectory, and go to the src subdirectory:
mkdir -p oceanwaters_ws/src
cd oceanwaters_ws/src
Then checkout the top level OceanWATERS git repository:
git clone https://github.com/nasa/OceanWATERS
ROS’ wstool will be used to checkout additional repositories containing the source code files making up OceanWATERS. The wstool utility will look for a file, oceanwaters_ws/src/.rosinstall, that contains a list of repositories to check out or update. The OceanWATERS repository contains a number of .rosinstall files for different uses. Create a link to the default repository list:
ln -s oceanwaters/workspaces/oceanwaters_v1.rosinstall .rosinstall
Note: if use of the provided autonomy module is not desired, and PLEXIL is not installed, comment out or remove the line referencing the ow_autonomy package in oceanwaters_v1.rosinstall to avoid build errors.
Now use wstool to checkout/update the source code:
wstool up
The workspace will be built using catkin. Go to the top-level workspace directory and execute the catkin build command:
cd ..
catkin build
Finally set OceanWATERS specific environment variables using the provided script:
source devel/setup.bash
At this point you should see Gazebo related variables such as GAZEBO_MODEL_PATH set in your environment.
To run OceanWATERS, execute the following command:
roslaunch ow europa_terminator_workspace.launch
this will result in the production of a fair amount of console output as well as display of rqt, RViz, and Gazebo windows that are useful for debugging and system understanding. The rqt_gui tool provides a customizable GUI for inspecting inter-process messaging and viewing simulated camera images. RViz provides interactive 3D visualization showing planned lander arm trajectories and executed arm trajectories, and the Gazebo GUI provides interactive 3D visualization of the lander operating within the planetary surface environment.
ROS inter-process communication is in the form of messages published and subscribed to on named channels, or topics, in ROS terminology. In addition to topics, ROS implements concepts of services and actions. Processes communicating via ROS topics, services, or actions are referred to as nodes.
ROS provides a number of tools in addition to rqt_gui for monitoring message traffic as well as understanding system configuration and node connectivity. The following command:
rosnode list
will list all running nodes. The rostopic command-line tool provides a means of interacting with the ROS topics of a running network of ROS nodes. For example:
rostopic list
will list the current active topics, and:
rostopic echo /topic_name
will display messages published to the /topic_name topic. The rostopic tool also provides the capability to manually publish a message on a topic. Similar to rostopic, the rosservice command line tool provides information on active services. For example:
rosservice list
will list current active services. The rqt_gui tool can display a graph of ROS nodes with topics, this facility is also available in the standalone rqt_graph tool.
Event logging in OceanWATERS utilizes ROS's existing logging capabilities. During runtime the ROS topic rosout_agg provides an aggregated feed of all events logged by OceanWATERS nodes, and this feed can provide moment-to-moment updates on events as they occur in the simulation.
The GUI rqt_console can be used during runtime to view logged events as they are published, and events can be filtered by verbosity level.
Each simulation run will generate a rosout.log that contains, in text format, the aggregated feed in its entirety. The rosout.log for the most recently ran simulation can be found inside the ~/.ros/log/latest directory, or if you've set the ROS_HOME environment variable it can be found in $ROS_HOME/log/latest.
Recording of any other type of ROS message (images, joint angles, ect.) can be accomplished in OceanWATERS with the bag recorder node. In ROS, messages of any type published by a topic can be recorded to a bag file, which can then be played back in sequence using either rosbag play from the command line or with the rqt_bag GUI. The data contained in the bag file can also be analyzed or even modified using the rosbag C++ and Python APIs.
To record a bag file in OceanWATERS the configuration files located in ow_simulator/ow_bag_recorder/config should be set to the desired recording settings. The bag recorder node will save messages published by any topic listed in topics.yaml. The other configuration file, options.yaml, contains options to customize the operation of the bag recorder node. A complete description of these options can be found in the ow_simulator/ow_bag_recorder/README.md file.
Once configuration files are set, launch the simulation using the method described in 2.3 only set the record_bag flag to true.
roslaunch ow europa_terminator_workspace.launch record_bag:=true
A file with the extension ".bag.active" should now appear in your ~/.ros directory, or $ROS_HOME. When the simulation ends, this file's extension will be changed to ".bag" and can now be analyzed or played back using the ROS utilities described above.
Note that setting the options record_all and node to a value that's not their default will override the topic list in topics.yaml.