Phoebe Bridgeback Workspace

Docker enabled ROS 2 workspace for building and running applications with the Phoebe Bridgeback robot. Phoebe Bridgeback is a dual armed, mobile manipulation platform maintained in the iMETRO Facility at NASA's Johnson Space Center.

The platform includes a Clearpath Ridgeback base, 2x Ewellix column lifts, and 2x UR5e serial manipulators. Peripherals include wrist mounted Realses D435 cameras along with Robotiq Hand-E grippers. This workspace includes packages for baseline operation of the hardware system, along with a supported kinematic and dynamic simulation built with MuJoCo.

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

   • Don't worry about Docker Desktop
   • For Ubuntu recommend using the utility script

2. Install git sudo apt install git

3. Clone this repo with submodules

   git clone --recursive https://github.com/NASA-JSC-Robotics/phoebe_bridgeback_ws.git
   cd phoebe_bridgeback_ws

   Or to update submodules if you do not do a recursive clone,

   cd phoebe_bridgeback_ws
   git submodule update --init

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

Build the base images using the compose specification.

To build the development image from the repo root, and then launch it

# Compile the image
docker compose build

# Start it
docker compose up dev -d

# Connect to the console
docker compose exec dev bash

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

To run the things, do the following

# build the ROS workspace
colcon build

# Start Phoebe ros2 control software with mock_hardware
# Note - the imu broadcaster controller will fail to load here, and that is ok.
ros2 launch phoebe_deploy control_mock_hardware.launch.py

# start moveit with rviz!
ros2 launch phoebe_moveit_config phoebe_moveit.launch.py

For running things in mujoco, follow these steps. Note that for the phoebe_mujoco and phoebe_moveit launches, you can use the launch args left_hand_type:=2f85 and right_hand_type:=2f85 to switch either or both hands to be robotiq 2f85 grippers instead of robotiq handes (just make sure those two launch files match).

# build the ROS workspace
colcon build

# Start Phoebe ros2 control software with mujoco sim
ros2 launch phoebe_mujoco_config phoebe_mujoco.launch.py

# start moveit with rviz!
ros2 launch phoebe_moveit_config phoebe_moveit.launch.py use_sim_time:=true

# launch nav2
ros2 launch phoebe_nav2_config phoebe_nav.launch.py use_sim_time:=true

The Pixi Workflow

Warning

The pixi workflow is experimental and intended for development use only.

We also provide a pixi/robostack build for compiling on baremetal in consistent, isolated environments. Be sure to install the latest (after 0.65.0) release of the tool. The build relies on the pixi-build-ros backend for compatibility with our ROS projects.

This is an experimental workflow that is not as tested as the Docker build methods. For more information on pixi refer to the instructions.

To install and run with pixi:

# Install the frozen environment and configure colcon
pixi install --frozen
pixi run setup-colcon

# Build and test
pixi run build
pixi run test

# Or launch an interactive shell and do things "normally"
pixi shell
colcon build

Note that any package we are building from source must be included in pixi.toml.

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.

Citation

This project falls under the purview of the iMETRO project. If you use this in your own work, please cite the following paper:

@INPROCEEDINGS{imetro-facility-2025,
  author={Dunkelberger, Nathan and Sheetz, Emily and Rainen, Connor and Graf, Jodi and Hart, Nikki and Zemler, Emma and Azimi, Shaun},
  booktitle={2025 22nd International Conference on Ubiquitous Robots (UR)},
  title={Design of the iMETRO Facility: A Platform for Intravehicular Space Robotics Research},
  year={2025},
  volume={},
  number={},
  pages={390-397},
  keywords={NASA;Moon;Seals;Maintenance engineering;Maintenance;Robots;Standards;Open source software;Testing;Logistics},
  doi={10.1109/UR65550.2025.11077983}}