Togo Containerized Workspace

Basic workflow for the EG Husky Togo. The contents of the src directory should be treated similarly to a "normal" ROS workspace. That is, source code can be imported and added as needed to src/, then be built and run inside of an isolated, ROS enabled environment.

This workflow has been tested against the jazzy ROS distro. To change ROS versions, update the ROS2_DISTRO variable in your environment. Note the 2! As this is intended to be isolated from your system.

Quick Development Setup

1. Install Docker, if it is not already available

   • Don't worry about Docker Desktop
   • For installing docker on Ubuntu we recommend using the utility script
   • After running the utility script, you should run the post-installation steps for linux, which helps manage the user settings and running without root access.
   • Most importantly - make sure you are in the computer's docker usergroup with sudo usermod -aG docker $USER (requires logging out/logging back in)

2. VERY IMPORTANT Recursively initialize all submodules. Note that the fixposition and seyond driver packages contain many nested submodules, so the --recursive flag is critical.

   git submodule update --init --recursive

3. Setup additional source code for the src/ directory (if you need them)

   • ie, git submodule add ...

4. Set your user information for the project build

   • We recommend just putting this in your ~/.bashrc:

     export USER_UID=$(id -u $USER)
     export USER_GID=$(id -g $USER)

   • Alternatively, open the .env file in the root of this repo and update each line with your information

     • USER_UID and USER_GID
       • found using id -u and id -g respectively

Using the Images

VERY IMPORTANT Apply the required pre-build steps on the host by running the following script from the repo root:

./scripts/pre_build.sh

We provide two Togo images, one for local development and one for development on hardware. The images can be used the same way; the hardware container just includes different volume mounts and brings up the micro-ROS agent for Togo.

Once you're attached to the container, you can use it as a regular colcon workspace (see building the workspace). The contents of the src/ directory will be mounted into /home/er4-user/ws/src.

Development Image

Build the development image from the repo root, and then launch it:

# Compile the image
docker compose build dev

# Start it
docker compose up dev -d

# Start a bash session in the container
docker compose exec dev bash

# Or optionally connect to the console by launching a terminator session (requires a display):
docker compose exec dev terminator

It is possible for multiple devs to work on the same machine, if users:

1. Comment out line 23 (network_mode: host) of docker_compose.yml
2. Accept that you will not be able to use this computer to run the robot - only sim

Hardware Development Image

Build the hardware development image from the repo root, and then launch it:

# Compile the image
docker compose build hw-dev

# Start it; this container will automatically start the micro-ROS agent docker container as well
docker compose up hw-dev -d

# Connect to the console
docker compose exec hw-dev terminator

Warning

Especially on the robot hardware, it will be helpful to somewhat regularly rebuild the docker images (transport and hw-dev) to update the packages (especially Clearpath packages) used within the containers. Rebuilding the docker images will ensure the latest package updates are pulled down and used on the hardware.

Building the Togo Workspace

Once you're attached to the container, build the workspace as normal:

colcon build

This workspace depends drivers for several sensors, namely fixposition and seyond. These packages will complain when building, and will include messages marked "fatal". Ignore this; the build should complete just fine, the packages are just whiny.

For awareness, both the fixposition and seyond require extra build steps. These are handled by the pre_build.sh script run before building the docker images. By the time you attach to the container, these packages can be built as expected within a ROS workspace.

For more information on running applications refer to Togo's README.md. To get started, we recommend Gazebo instructions for the dev image and hardware instructions for the hardware image.

Other Things to Note

• Build logs, compiled artifaces, and the .ccache are also mounted in the workspace/user home. This ensure artifacts are persisted even when restarting or recreating the container.

• The .bash folder gets mounted into your workspace, and the environment variable HISTFILE is set in the docker compose file. This points the bash to keep the history in this folder, which will persist between docker container sessions so that your history is kept.

• Your host's DDS configuration (either cyclone or fastrtps) will be mounted into the image if set in your environment. For more information refer to the compose specification.

• Defaults for colcon build are set for the user. To change or modify, refer to the defaults file.

• We use MuJoCo for many of our dynamic simulations, so we include installing in the Dockerfile.

Troubleshooting

Common pitfalls and troubleshooting tips are documented in the troubleshooting guide.