🚧 Work in progress: this documentation is still being written and reviewed. Check details against the source code.

Installation

Set up EROBS on Ubuntu 24.04 with ROS 2 Jazzy. The steps below install the robot software and GUI for a first run with mock hardware. Camera support is optional.

1. Install ROS 2

Follow the official ROS 2 Jazzy installation guide. Complete both Desktop Install and Install development tools (ros-dev-tools). The development-tools step supplies Git, CMake, colcon, rosdep, and vcstool for building EROBS.

After installation, load ROS in your terminal:

source /opt/ros/jazzy/setup.bash

Use Ubuntu’s Python 3.12 and a desktop session for the GUI and RViz.

2. Clone EROBS and run setup

Choose where you want to keep EROBS and open a terminal in that directory:

git clone --branch pr_jazzy_dev https://github.com/bondada-a/erobs.git
cd erobs

Run the remaining commands from the repository root—the directory containing setup.sh and src/.

On first-time setup, run sudo rosdep init once. Skip this if rosdep is already initialized.

Then run the repository’s setup script:

bash setup.sh

setup.sh imports the repository’s existing driver manifests and installs the declared ROS dependencies, including planning and GUI packages. It does not build EROBS or install camera SDKs.

If you already have an EROBS checkout, use it instead of cloning a new one.

3. Build and load the workspace

From the EROBS repository root:

colcon build --merge-install --symlink-install \
  --packages-skip-regex 'zivid_(camera|samples)|zed_.*'
source install/setup.bash

This builds EROBS without the camera drivers that require vendor SDKs. Camera model and interface packages remain available for the robot descriptions.

setup.sh prepares dependencies; install/setup.bash loads the built workspace. Open each new terminal in your EROBS checkout, then run:

source /opt/ros/jazzy/setup.bash
source install/setup.bash

For an existing workspace, keep its current install layout. The package index lists what each package installs.

4. Check the installation

ros2 pkg prefix beambot
ros2 pkg prefix mtc_gui
ros2 interface show beambot_interfaces/action/MTCExecution

Both package paths should point into this workspace’s install/ directory. The final command should display the MTCExecution action definition.

Continue with Run your first task to select a mock configuration, open the GUI, preview a movement, and execute it. For a physical installation, follow beamline configuration.

Optional: Zivid camera

For camera capture, install the SDK and GPU drivers required by src/vision/zivid-ros/README.md. Follow Zivid’s Ubuntu installation guide, choosing an SDK version compatible with that checkout.

Then build the camera packages from your EROBS repository root:

colcon build --merge-install --symlink-install \
  --packages-up-to zivid_camera zivid_samples
source install/setup.bash

Configure the camera network and calibration, then enable vision with enable_vision:=true when launching EROBS. See cameras and detection for the complete camera workflow and ZED limitations.

Optional Python features

These packages support learned vision, chat, and experiment integrations. They are not needed for the manual GUI or the first mock task.

Prepare the Python environment

Keep these packages outside Ubuntu’s managed Python installation:

sudo apt install python3-venv
/usr/bin/python3 -m venv --system-site-packages ~/.venvs/erobs
source ~/.venvs/erobs/bin/activate
python -m pip install --upgrade pip

After sourcing ROS and the workspace, expose this environment’s packages to ROS entry points that use /usr/bin/python3:

export PYTHONPATH="$HOME/.venvs/erobs/lib/python3.12/site-packages${PYTHONPATH:+:$PYTHONPATH}"

Repeat the activation and export in terminals that launch these optional features. Keep the core ROS build on the system interpreter.

Learned vision and mapping

Install PyTorch using its platform-specific installation guide, choosing the appropriate CPU or GPU build. Then install the feature packages in the environment above:

python -m pip install 'numpy<2' 'opencv-python<4.12' ultralytics open3d
/usr/bin/python3 -c 'import cv2, cv_bridge, torch, ultralytics, open3d'

The NumPy/OpenCV constraints keep this Python stack compatible with Jazzy’s NumPy 1.x image bridge. Ultralytics supports learned sample detection; Open3D supports point-cloud processing. Camera calibration, model weights, and detector configuration are covered in perception.

Chat and MCP

python -m pip install anthropic mcp
/usr/bin/python3 -c 'import anthropic, mcp'

Install uv so the configured uvx MCP process is available. Start the client from the EROBS checkout so it finds .mcp.json, select the beamline, and supply AIFAPIM_API_KEY through your credential environment. Verify that robot_operation.md exists next to the imported beambot.agent.robot_agent module. Read MCP and the direct agent for gateway settings and runtime-file requirements. Manual task editing does not require chat credentials.

Bluesky and EPICS

python -m pip install bluesky ophyd pyepics
# Run from the repository root.
export PYTHONPATH="$PWD/src${PYTHONPATH:+:$PYTHONPATH}"
/usr/bin/python3 -c 'import bluesky, ophyd, epics, bluesky_ros'

Configure the site’s EPICS network and devices separately. The Bluesky and EPICS guide explains the adapters and their current limitations; installing them does not validate an experiment workflow.

If setup fails

If setup or a check fails, resolve the reported error before continuing. The troubleshooting guide covers missing packages, Python imports, and configuration paths.