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

Architecture

EROBS coordinates robot motion, tool changes, and vision from an ordered JSON task script. The orchestrator manages the sequence; task stages build motion plans; MoveIt and device drivers carry them out.

The platform uses ROS 2 Jazzy, MoveIt 2, and MoveIt Task Constructor (MTC). The operator GUI communicates with the runtime through ROS actions, services, and topics.

From task requests to robot motion Task clients send JSON goals to the orchestrator, which runs batch stages or child action servers; direct clients can also call child actions. EROBS / ARCHITECTUREFrom task requests to robot motionCLIENTSTASK EXECUTIONMOTION / DEVICESGOALPLANDISPATCHDIRECT ACTIONEXECUTETask clientsGUI · JSON · MCPDirect clientsactions · surveysOrchestratorbeambot_executionBatch stagesmoveto ·end_effectorTask action serversvision · tool ·devicesMTC / MoveItplan and executeRobot and toolscontrollers /device I/OSolid arrows show principal calls. Device actions may bypass MoveIt; perception details are shown separately.
Open the full-size diagram

From task script to execution

  1. Submit. The GUI or another client sends the script to /beambot_execution.

  2. Prepare. The orchestrator validates the script, resolves named poses, and prepares MoveIt for the selected tool.

  3. Plan and execute. Compatible MoveTo and end-effector steps share an MTC task. Other operations run through their task servers or orchestrator helpers. Vision tasks first turn camera measurements into motion targets.

  4. Report. The orchestrator publishes progress and returns a result to the client. Pause and cancellation take effect at execution boundaries; see execution controls.

Main components

The main runtime package is src/beambot/beambot/. Paths in this table are relative to that directory.

Component

Responsibility

Main files or folders

Orchestrator

Validate and coordinate a complete task sequence

action_servers/orchestrator.py

Task preparation

Parse scripts, resolve poses, and group compatible steps

core/task_script.py, core/task_batching.py

Task servers and stages

Accept individual action goals and implement motion, gripper, tool-exchange, and vision operations

action_servers/, stages/

MoveIt and tool management

Start and replace the tool-specific robot stack; coordinate tool exchange and plan reuse

core/moveit_lifecycle_manager.py, core/tool_exchange_manager.py, core/plan_cache.py

Vision

Acquire camera data, detect features, and calculate motion targets

vision/, with vision/camera/ and vision/detection/

Mapping

Relay point clouds and pass Octomap updates to MoveIt’s planning scene

mapping/

Configuration

Load the selected beamline YAML and resolve its file paths

config_loader.py

The GUI lives in src/mtc_gui/mtc_gui/. Robot descriptions and MoveIt configurations live in src/custom-ur-descriptions/; local tool drivers and overlays live in src/end_effectors/. The module guide connects these components to their function reference.

Process boundaries

The orchestrator owns MoveIt startup. It starts the robot stack when a task needs it and manages model changes during tool exchange. See MoveIt lifecycle.

Task servers run separately. Most use BaseActionServer to accept one goal at a time. The sample server shares that limit across its pick and place endpoints. Batched MoveTo and end-effector stages run inside the orchestrator process instead of sending child action goals.

Caches belong to their owning process. The vision-scan and unified vision-task servers keep separate marker caches. A scan result is not automatically available to a later unified vision task.

Vision and pipettor servers are optional launch groups. Mapping uses the separate octomap_mapping.launch.py launch file. See configuration and deployment boundaries for how these components are enabled.

Explore the architecture