CLR Demonstration Workspace

This workspace includes open source resources for using the ChonkUR L Rail-E robot system, part of the iMETRO Facility at NASA's Johnson Space Center.

The system consists of a UR10e robot mounted on top of an Ewellix column lift and Vention rail. Peripherals include a Robotiq Hand-E gripper with custom printed fingers and a wrist mounted Realsense camera. Descriptions of commonly used environmental components are also included, such as hatches, storage benches, or Merlin Freezes. The mock-ups here can be used by anyone to develop or test robot applications for space logistics in our hardware environment.

This workspace bundles all required git submodules into a Docker containerized workflow that is identical to that which we run on hardware. While not required, we recommend using our Dockerfiles for consistent environment setup. Alternatively, individual packages and submodules can be added or extracted from the src directory as needed by the user.

In addition to the base packages, it adds multiple submodules for running basic demonstrations with the CLR system. Many of these have been tested both on hardware and with the dynamic MuJoCo simulation. For more information, refer to the documentation in clr_demos.

This workflow has been tested against the jazzy ROS distro. 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. Fork or copy the contents of this repository as needed. NASA internal users should refer to confluence for how to setup authentication to GitHub.

   NOTE: This repository uses LFS for mesh file storage, be sure it is installed with:

   sudo apt-get install git-lfs

   Then,

   # Clone with submodules
   git clone --recursive https://github.com/NASA-JSC-Robotics/clr_ws.git
   
   # Or initialize them from the repo's root
   cd clr_ws
   git submodule update --init --recursive

3. Copy .env.default in the root of this repo to a new file named just .env

   cp .env.default .env

4. Set your user information for the project build

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

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

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

   Alternatively, edit the contents of the newly created .env.

Then follow the instructions below to build and run the application.

Using the Demo Image

The demo image is based of pre-built images that are pushed to DockerHub.

These images contain the fully compiled workspace and can be run out of the box.

To build and launch the demo image, from the workspace root run:

# Compile (pull) the image
docker compose build

# Start the demo service in the background
docker compose up -d demo

# Launch a bash session in the container
docker compose exec demo bash

The demo container will source the installed environment, and can be used to launch pre-compiled applications,

Launch files for our supported simulation environments are included:

• CLR kinematic sim

  # In one terminal launch the kinematic simulation environment
  ros2 launch clr_deploy clr_sim.launch.py
  
  # Then open another session and launch MoveIt,
  ros2 launch clr_moveit_config clr_moveit.launch.py

• MuJoCo CLR dynamic sim

  # In one terminal launch the MuJoCo dynamic simulation environment and CLR controllers
  ros2 launch clr_mujoco_config clr_mujoco.launch.py
  
  # In another session launch MoveIt, including the environment and sim time
  ros2 launch clr_moveit_config clr_moveit.launch.py include_mockups_in_description:=true use_sim_time:=true

Using the Development Image

The development image is built locally starting from a baseline ros:jazzy image.

This image is not setup to run once built.

Instead, the user's local workspace is mounted into the container and must be compiled manually.

To build and launch the development image, from the workspace root run:

# Compile the image
docker compose build dev

# Start it
docker compose up -d dev

# Connect to the console shell
docker compose exec dev bash

Once attached to the container, is is usable as a regular colcon workspace. The contents of the src/ directory will be mounted into /home/er4-user/ws/src.

For example:

cd ${HOME}/ws
colcon build
source install/setup.bash

Once the workspace is built and sourced within the container, ROS 2 executables and launch files can be run.

Using the Hardware

Running the system on hardware is more involved than running simulations.

Refer to internal documentation for more details.

The Pixi Workflow

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

Alternatively, launch an interactive shell and do things "normally":

# Launch the shell and compile the workspace
pixi shell
colcon build

# Source the workspace and launch an application
source install/setup.bash
ros2 launch clr_mujoco_config clr_mujoco.launch.py

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

Important Notes

• 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.

• If you have an NVIDIA or other graphics card, you will have to complete additional configuration steps to use the docker container. Please refer to the troubleshooting guide for more information.

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}}