EROBS — Extensible Robotic Beamline Scientist

A platform for UR-arm–based autonomous sample handling at synchrotron beamlines. Currently deployed at NSLS-II CMS; designed to generalize to other UR-based beamline setups.

The system pairs a UR5e with swappable end effectors, a Zivid 3D camera, and a ROS 2 / MoveIt Task Constructor stack behind a JSON task interface, so experiments can be authored manually, driven by an LLM over MCP, or — eventually — orchestrated by Bluesky.

Documentation: https://bondada-a.github.io/erobs/ — installation, operator guides, architecture, and the function reference. The docs are still being written and reviewed.

Hardware at a glance

• Robot: Universal Robots UR5e 6-DOF arm (fixed 20 % velocity / acceleration scaling)
• Precision camera: Zivid 2+ 3D, eye-in-hand, single-shot (ArUco + contour detection)
• External camera: ZED stereo — present, not reliably wired up today
• End effectors (swappable via tool_exchange): Robotiq Hand-E, Robotiq ePick (vacuum), OnRobot 2FG7, and a custom pipettor

Software stack

• ROS 2 Jazzy on Ubuntu 24.04 (branch: jazzy_dev, migrating to main; humble-dev kept as legacy archive)
• MoveIt 2 + MoveIt Task Constructor for planning
• Python orchestrator (beambot package): one action server per task type plus a central orchestrator that tracks gripper state, manages MoveIt lifecycle across tool swaps, and batches consecutive simple tasks
• JSON task format dispatched through /beambot_execution — see src/beambot/beambot/agent/robot_operation.md for the authoritative schema, error taxonomy, and MCP tool reference (also loaded by the robot-operation Claude Code skill)

How to interact

Four entry points — honest labels:

1. PyQt6 GUI — primary manual interface. ros2 run beambot_gui beambot_gui_client. Per-task dialogs, camera overlays, pose editor, experiment runner. Also hosts an experimental chat panel backed by the beambot.agent module.
2. MCP + Claude Code — LLM-assisted operation. ./utils/start_mcp.sh launches rosbridge + beambot_bringup. Two MCP servers (generic ros-mcp-server and the custom beambot-mcp-server) expose task dispatch, vision, pose registry, and diagnostics to an LLM driving the robot. .mcp.json wires them up for Claude Code.
3. beambot.agent CLI — experimental. A direct Anthropic / Bedrock + MCP loop (python -m beambot.agent). Same system prompt as Claude Code, no Claude Code overhead. Parallel to path 2, not production-hardened yet.
4. Bluesky RunEngine — planned / currently broken. src/bluesky_ros/ holds an Ophyd device wrapper for the orchestrator but it has not been kept in sync with the current action set; running it end-to-end will fail. Targeted for revival.

Packages

Path	What it contains
src/beambot	Orchestrator, per-task action servers, MTC task builders, MCP server, beambot.agent, detection algorithms, batch planner
src/beambot_interfaces	9 ROS 2 action definitions (BeambotExecution, MoveTo, EndEffector, PickSample, PlaceSample, ToolExchange, VisionTask, VisionScan, Pipettor)
src/beambot_gui	PyQt6 operator GUI (see its README)
src/custom-ur-descriptions	UR5e URDF/xacro and MoveIt configs (one generic config that branches per gripper)
src/end_effectors	Gripper drivers + epick_config overlay (README)
src/vision	External vision repos (Zivid; ZED listed but not currently launched)
src/cms	CMS beamline assets — poses.yaml and task JSONs. CMS is the live beamline; some paths are hardcoded here today
src/lix	Placeholder for LIX beamline
src/demos	hello_orchestrator_py tutorial package
src/bluesky_ros	Ophyd + Bluesky integration (see "How to interact" — currently broken)

Quick setup

Prerequisites: ROS 2 Jazzy, MoveIt 2, Zivid SDK (for vision), Python 3.12.

These steps assume an already prepared ROS host, including colcon, vcstool and rosdep. The separate setup.sh installs/imports declared dependencies from the repository root; it does not install ROS/SDKs, build the workspace or select a beamline.

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

# Import external dependencies
vcs import src/end_effectors < src/end_effectors/end_effectors.repos
vcs import src/vision    < src/vision/vision.repos

# Build
source /opt/ros/jazzy/setup.bash
colcon build
source install/setup.bash

See src/end_effectors/README.md and src/vision/README.md for SDK and driver requirements.

Launch

From the repository root, select the deployment site in each terminal before launching:

# CMS example; use the configuration for your deployment site
export BEAMBOT_BEAMLINE_CONFIG="$(realpath src/beambot/config/cms_beamline.yaml)"

# Real hardware, vision + pipettor enabled (defaults)
ros2 launch beambot beambot_bringup.launch.py

# Mock UR hardware with camera and pipettor servers disabled
ros2 launch beambot beambot_bringup.launch.py \
  use_mock_hardware:=true enable_vision:=false enable_pipettor:=false

# Disable vision/pipettor if those subsystems aren't plugged in
ros2 launch beambot beambot_bringup.launch.py enable_vision:=false enable_pipettor:=false

# Primary operator GUI
ros2 run beambot_gui beambot_gui_client

# MCP stack (rosbridge on :9090 + beambot_bringup + rosbag recording)
./utils/start_mcp.sh

beambot_bringup.launch.py starts all action servers and the Zivid camera (conditionally); the orchestrator launches MoveIt lazily on the first goal based on the attached gripper. See CLAUDE.md for development architecture and robot_operation.md for task and robot-side troubleshooting details.

Tests

./test.sh              # Hardware-free unit tests, including the offscreen GUI
./test.sh pure         # Parser, batching, cache and geometry; no ROS required
./test.sh integration  # Isolated ROS actions, model reload and process cleanup
./test.sh all          # Unit and integration suites

Unit tests block ROS startup, subprocesses and external connections. Integration tests use private localhost-only ROS domains, synthetic models and inert action task builders; they never launch the robot or camera drivers. They do not validate physical clearance, calibration, controller timing or hardware reliability. Use the prepared Jazzy workspace for the full suite; pure needs pytest, PyYAML, NumPy and OpenCV with ArUco support. Results are written under log/tests. The deferred shutdown-child bug is exercised and reported as a known-issue skip, not a pass; fixture or cleanup failures still fail the suite.

After building with BUILD_TESTING=ON, colcon test --packages-select beambot beambot_gui also discovers these tests. Do not run workspace-wide test discovery on a hardware host: external driver packages have their own test requirements.

Further reading

• EROBS documentation — full guides and function reference (work in progress)
• CLAUDE.md — development brief auto-loaded by Claude Code (repo layout, build/test commands, invariants)
• src/beambot/beambot/agent/robot_operation.md — authoritative robot-operation reference: task JSON schema, MCP tool inventory, error taxonomy, gotchas (also loaded by the robot-operation skill)

License

BSD-3-Clause (NSLS-II / Brookhaven National Laboratory). See LICENSE and LICENSE_README.