Module map

Find the modules responsible for execution, perception, the GUI, and hardware integration. Module links open the function reference; architecture links explain how the components work together.

Open the full-size diagram

Main execution package

Paths in this table are relative to src/beambot/.

Source	Responsibility	Called by or consumed by
`beambot/action_servers/orchestrator.py`	Main JSON action, execution state, dispatch and coordination	GUI, JSON client, MCP-dispatched actions and Bluesky
`beambot/action_servers/base_action_server.py`	Shared action-server lifecycle and admission behavior	Individual task servers
`beambot/action_servers/move_to_server.py`, `beambot/action_servers/end_effector_server.py`	Direct motion and gripper actions	Orchestrator; direct action clients
`beambot/action_servers/sample_pick_place_server.py`, `beambot/action_servers/tool_exchange_server.py`, `beambot/action_servers/pipettor_server.py`	Sample, tool exchange and pipettor action boundaries	Orchestrator
`beambot/action_servers/vision_scan_server.py`, `beambot/action_servers/vision_task_server.py`	Scan and unified vision-task actions	Orchestrator and perception clients
`beambot/core/task_script.py`	Request parsing, task and pose handling	Orchestrator
`beambot/core/task_batching.py`, `beambot/core/plan_cache.py`	Group eligible tasks; manage reusable plans	Orchestrator
`beambot/core/moveit_lifecycle_manager.py`, `beambot/core/tool_exchange_manager.py`	Robot-stack lifetime and tool-change coordination	Orchestrator
`beambot/core/vacuum_monitor.py`	Retained vacuum bookkeeping class; subscription branch is disabled	Orchestrator integration is commented out; no instance is created
`beambot/stages/base_stages.py`	Shared MTC, planner, pose and motion helpers	Task stages and vision engine
Other files in `beambot/stages/`	Motion, end-effector, pick/place, exchange, pipettor and vision execution	Corresponding action servers
`beambot/config_loader.py`	Beamline selection and shared configuration access	Launch files, execution, GUI and tools

The task name moveto and filename move_to_server.py differ deliberately. The full endpoint-to-action mapping is in the action reference.

Perception and auxiliary programs

The perception code has three main source areas:

Directory	Responsibility
`vision/camera/`	Backend acquisition
`vision/detection/`	Algorithms and parameter types
`vision/`	Detector/goal-computer dispatch dictionaries, motion-target types and `VisionEngine`

VisionEngine provides camera capture, TF, approach geometry, tag caching and detected collision objects. VisionTaskStages.run() looks up detector and goal-computer callables. The vision code also serves the remaining scan and hardcoded sample paths; see perception.

Source	Role
`beambot/mapping/pointcloud_relay.py`	Feed the mapping cloud path
`beambot/mapping/octomap_to_planning_scene.py`	Bridge Octomap messages into MoveIt scene updates
`scripts/beambot_client.py`	Read task JSON and submit the main action
`scripts/capture_octomap.py`	Execute selected scan poses and trigger captures for the Octomap workflow
`scripts/perf_trace_run.sh`	Launch a tracing-enabled run
`scripts/perf_trace_summarize.py`	Summarize ROS trace callback timing
`mcp_server/beambot_mcp_server.py`	Custom beamline MCP tools
`beambot/agent/robot_agent.py`, `beambot/agent/__main__.py`	Shared direct agent and command-line entry

The standalone survey scripts are outside this package. Their live runner calls the move action directly; capture_octomap.py instead sends one-task orchestrator goals. Both programs can move the robot and trigger camera capture.

GUI modules

Paths below are relative to src/mtc_gui/mtc_gui/.

Source	Responsibility
`main.py`	Application startup, Qt event loop and ROS bridge cleanup
`main_window.py`	Panels, task-document ownership and execution controls; agent disconnection on window close
`theme.py`	Shared appearance and `toggle_dark_mode()`
`task_forms.py`	GUI task serialization: input dialogs and JSON construction
`step_list_panel.py`	Queue rows, selection/reordering and execution progress
`ros2_bridge.py`	ROS messages, actions and services translated into Qt signals; cancellation tracking through the final action result
`pose_io.py`	Qt-independent YAML reading and atomic replacement on save
`poses_panel.py`, `pose_dialogs.py`	Pose browsing, editing, importing and saving
`camera_panel.py`	Image display and detection overlays
`visualization_panel.py`	QWebEngine viewer, model/mesh resolution and trajectory display
`chat_panel.py`, `agent_bridge.py`, `agent_modes.py`	Conversation presentation, asynchronous agent bridge and Plan/Run tool policy

resources/viewer.html runs the browser scene. Three.js provides rendering, OrbitControls provides navigation, URDFLoader builds the link/joint model, and STLLoader/ColladaLoader read mesh formats. VisualizationPanel serves these resources and package meshes over an ephemeral loopback HTTP port. Its path resolver confines requests to configured roots. Updating that code requires preserving both the resource mapping and path boundary.

For GUI task serialization, start with open_task_form() to select the dialog. On Save, BaseTaskForm._on_save() calls the form’s collect_values() method and stores the edited task dictionary in dialog.result. The task parser is the receiving contract; form fields and parser defaults must agree.

Models, tools and teaching packages

The four CMS/LIX description and MoveIt packages own models, planning configuration and bringup. CMS additionally compiles cms_servo_node, the C++ Servo implementation used by optional joystick control. Three local end-effector packages supply the ePick overlay and OnRobot model/driver; hardware explains them.

hello_orchestrator_py is a separate teaching example with print, move and orchestrator servers plus matching stages and a JSON client. Its companion interface package defines PrintMessage, MoveToNamedState and OrchestratorTask. The demo uses {"type": "move"} rather than the main application’s task_type schema. It requires a configured MoveIt planning group and named state; its move example can execute motion.