Home

Getting Started

See below for a cheat sheet of basic commands that may be helpful in getting started. Documentation is also available throughout the project as READMEs in the various packages.

Not sure what to work on? See the list of challenges on the right. These offer guided challenges with reference implementations, which might be especially helpful if you are relatively new to ROS programming.

Basic Commands Cheat Sheet

1. Cloning the Repository

To get started with the Orca4 project, clone the repository from GitHub:

git clone https://github.com/WHOIGit/orca4.git
cd orca4

This command creates a local copy of the Orca4 project on your machine and changes your current directory to the project root.

2. Docker Basics and Usage

Docker is a platform for developing, shipping, and running applications in containers. It provides a consistent environment across different machines, making it easier to develop and deploy software.

• Image: A lightweight, standalone, executable package that includes everything needed to run a piece of software, including the code, runtime, libraries, and system tools.
• Container: A runtime instance of an image. It's a lightweight, isolated environment that runs the application.

Running Docker in Orca4

Orca4 provides convenient scripts to run the Docker container:

./docker_run.sh

For systems with NVIDIA GPUs:

./docker_run_nvidia.sh

These scripts do several important things:

1. Pulls the Docker image from Docker Hub if it doesn't exist.
2. Sets up X11 forwarding to allow GUI applications from inside the container.
3. Mounts the current directory into the container workspace.
   • Your orca4 directory will be mounted in the container at /home/orca4/colcon_ws/src/orca4
   • This allows you to edit files on your host machine and have those changes reflected inside the container.
4. Sets up NVIDIA GPU passthrough (in the case of docker_run_nvidia.sh).

Note: This project assumes your host CPU supports AMD64 architecture. If you are using an ARM device (e.g. M series Macbook) you will need to modify docker_run.sh to pull the arm64 version of the image: whoi/orca4:arm64.

Container Ephemerality

It's important to understand that Docker containers are ephemeral by default. This means:

• Any changes made inside the container that are not in a mounted directory will be lost when the container stops.
• Each time you run the script, you get a fresh container based on the image.
• Simply exiting the shell where you started the container will stop and delete the container.

Executing Commands in a Running Container

If you have orca4 running in one terminal and want to start a second session in the same container, simply open another terminal on the host and run:

docker exec -it orca4 bash

This opens another bash shell inside the container, allowing you to run commands as if you were in a regular terminal.

Other helpful Docker commands

• docker image ls List images
• docker container ls List containers
• docker pull [image]:[tag] Pull an image from Docker Hub
• docker container stop [container name or ID] Stop a running container
• docker/build.sh This is a script provided by orca4 for rebuilding the image. Helpful if there are changes you want to persist to the image.

3. ROS2 Basic CLI Commands

ROS2 (Robot Operating System 2) is a set of software libraries and tools for building robot applications. Here are some essential commands:

Inspecting Nodes and Topics

• List all nodes: ros2 node list This shows all the running ROS2 nodes in the system.

• List all topics: ros2 topic list This displays all the topics currently being published or subscribed to.

• Echo messages on a topic: ros2 topic echo /topic_name This allows you to see the messages being published on a specific topic in real-time.

• View info about a node: ros2 node info /node_name This provides detailed information about a specific node, including its publications, subscriptions, and services.

Launch vs. Run

• Launch: Starts multiple nodes and configures parameters

  ros2 launch package_name launch_file.py

  Launch files are used to start complex systems with multiple nodes and specific configurations.

• Run: Starts a single node

  ros2 run package_name node_name

  This is used to run individual nodes for testing or simple setups.

Launching Orca4

To launch the Orca4 simulation:

ros2 launch orca_bringup sim_launch.py

This command starts the entire Orca4 simulation environment, including Gazebo, RViz, and all necessary ROS2 nodes.

To run a mission:

ros2 run orca_bringup mission_runner.py

This executes a predefined mission for the Orca4 AUV.

4. Colcon build system

Colcon is the build system used in ROS2. Orca4 is built on the Humble distribution of ROS2, specifically. To build any changes you make to orca4, simply run the following from the /home/orca4/colcon_ws directory:

colcon build

This builds the project and propagates changes to the install directory of the colcon_ws workspace. Now when you launch the project, your changes should be reflected in the simulation.

Remember: The docker_run.sh scripts mount the project directory so that any changes you make to the project are already available in the container, and vice versa. So you can develop on the host machine using your preferred IDE, and just run colcon build when you're ready to test your changes.

For more information about the Colcon build system, see the ROS2 Colcon tutorial.

Testing

ROS and Colcon also provide tools for running tests on your packages. Here's how to use them:

Running Tests for a Specific Package

To run tests for a specific package (e.g. orca_extend), use:

colcon test --packages-select orca_extend

This command runs all the tests defined in the orca_extend package. To view the results of the tests, use:

colcon test-result --verbose

This command shows detailed output from the tests, including any failures or errors.

Continuous Integration

The Orca4 project uses GitHub Actions for continuous integration. Every pull request triggers a build and test process, ensuring that changes don't break existing functionality.

5. Git Versioning Basics

Git is a distributed version control system. Here are some basic operations:

Pulling Changes

git pull origin main

This fetches changes from the remote 'main' branch and merges them into your current branch.

Committing Changes

git add .
git commit -m "Your commit message"

This stages all changes in the current directory and creates a commit with the specified message.

Creating and Switching Branches

git branch new-branch-name
git checkout new-branch-name

Or in one command:

git checkout -b new-branch-name

This creates a new branch and switches to it. Branches are useful for developing features or fixing bugs without affecting the main codebase.

Pushing Changes

git push origin branch-name

This pushes your local commits to the remote repository.

6. Additional Tips

• Use rqt to open a GUI for inspecting ROS at runtime through various plugins. rqt_graph will directly open the node graphing plugin, useful for tracing the flow of messages.

• Monitor ROS2 logs: ros2 run rqt_console rqt_console This opens a graphical console for viewing ROS2 log messages.

• Check ROS2 parameter values: ros2 param list This lists all parameters of running nodes.

• Set ROS2 parameters: ros2 param set /node_name param_name param_value This allows you to change parameters of running nodes dynamically.

Remember, when using the Orca4 Docker container, the necessary setup is already done for you, so you don't need to source ROS2 setup files manually.

For Orca4-specific commands and workflows, always refer to the project documentation and README files for the most up-to-date information.