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

MoveIt lifecycle

Start, reuse, and replace MoveIt for the selected gripper. Readiness covers action availability, scene loading, and nonempty robot descriptions; real-hardware startup also checks control and joint feedback and applies the payload.

beambot.core.moveit_lifecycle_manager Β· Source

Setup and deployment Β· Guide Β· Symbol index

How it is used

The orchestrator and tool-exchange manager use launch_moveit_with_gripper() to reuse a matching live process or launch the requested model. Real-hardware launches can change tool voltage, restart external control, and set the payload. Payload and voltage values are validated when the beamline configuration loads.

model_revision identifies the gripper and, where configured, its cup profile. The same configuration keeps the same identity across launches; it is not a content hash. Runtime model checks require nonempty URDF/SRDF strings from /move_group. Tool links, groups, states, and collision geometry are checked separately by the offline model tests.

Start here

Callable

Purpose

MoveItLifecycleManager.launch_moveit_with_gripper

Reuse a live process with the requested tool/cup revision, or relaunch and publish nonempty robot descriptions. A failed real-hardware attempt is stopped and retried once; mock mode makes one attempt.

MoveItLifecycleManager.model_revision

Expose the tool/cup model identity only while the launch process is alive.

MoveItLifecycleManager.current_arm_joints

Read cached positions in the arm-joint order recorded during construction.

MoveItLifecycleManager.kill_current_process

Stop the MoveIt launch session: send SIGTERM to its process group, wait up to 3 s for every member to exit, then SIGKILL the group. Clear model identity and optionally drain execute_trajectory discovery.

MoveItLifecycleManager

Owner of the MoveIt launch process, tool/cup model identity, and hardware readiness checks. It uses an existing ROS node and validated gripper mapping. Blocking service calls require another executor thread to deliver responses.

MoveItLifecycleManager.launch_moveit_with_gripper()

Reuse a live process with the requested tool/cup revision, or relaunch and publish nonempty robot descriptions. A failed real-hardware attempt is stopped and retried once; mock mode makes one attempt.

Lifecycle Β· Source

launch_moveit_with_gripper(self, gripper: str) -> bool

Parameter

Meaning

gripper

Configured tool name. cup_override takes precedence over cup_profile only for grippers whose configuration defines that field.

Returns: True when reuse or startup succeeds, otherwise False.

Errors: Unknown gripper raises KeyError; unhandled helper errors propagate. A failed final launch is not automatically killed here.

Side effects: May kill/relaunch processes, configure hardware, load scenes and publish model descriptions. Success assigns the stable prefix + gripper [+ __cup] revision; restarting the same configuration does not create a new identity.

MoveItLifecycleManager.model_revision

Expose the tool/cup model identity only while the launch process is alive.

Method Β· Source

@property
model_revision(self) -> str

Access this as an instance property, without parentheses.

Returns: Stable revision string assigned after successful startup, or an empty string when the process is absent/dead. It identifies configuration names, not model-file content.

Errors: Process polling errors propagate.

Side effects: Polls process status.

MoveItLifecycleManager.current_arm_joints()

Read cached positions in the arm-joint order recorded during construction.

Method Β· Source

current_arm_joints(self)

Returns: Arm positions in radians, or None until every configured joint has a value. Mock mode normally returns None because this manager has no joint-state subscription.

Errors: No explicit validation of numeric values or joint-count assumptions in downstream callers.

Side effects: Reads cached feedback without waiting for fresh messages or rereading configuration.

MoveItLifecycleManager.kill_current_process()

Stop the MoveIt launch session: send SIGTERM to its process group, wait up to 3 s for every member to exit, then SIGKILL the group. Clear model identity and optionally drain execute_trajectory discovery.

Lifecycle Β· Source

kill_current_process(self, drain: bool=True)

Parameter

Meaning

drain

When true (default), wait for /execute_trajectory to leave discovery before returning, so the next launch is not mistaken for ready. Shutdown passes false because no launch follows.

Returns: None.

Errors: ProcessLookupError from signalling is suppressed; other signalling, wait or discovery errors propagate.

Side effects: Clears the model revision first. The launch was started in its own session, so its PID is the process-group ID. Polls every 50 ms until no group member remains, sends SIGKILL to the group after 3 s, waits for the launch parent and logs the stop time. Processes that start their own session are outside this group. With drain, waits up to 10 s for DDS graph cleanup; timeout only warns. Cached voltage is retained.

Referenced in source (1)

MoveItLifecycleManager.__init__()

Initialize process/model/voltage state, cache the configured arm-joint order, and create managed-model publishers and a move_group parameter client.

Lifecycle Β· Source

__init__(
    self,
    node: Node,
    grippers: dict,
    robot_ip: str,
    callback_group = None,
    use_mock_hardware: bool = False,
    enable_joystick: bool = False,
)

Parameter

Meaning

node

Owning ROS node/logger.

grippers

Validated gripper mapping containing MoveIt package, tool, payload and model settings.

robot_ip

UR controller address for pre-launch voltage commands.

callback_group

ROS callback group for clients/subscriptions; blocking calls need another executor thread to process responses.

use_mock_hardware

Skip the real joint-state subscription and hardware gates when true.

enable_joystick

Forward joystick/Servo enablement to robot bringup.

Errors: ROS resource construction errors propagate.

Side effects: Reads arm-joint configuration, creates publishers/parameter client and, on real hardware, a persistent joint subscription; initializes a program-running event. Does not launch MoveIt yet. The owning orchestrator stops MoveIt when its node is destroyed.

Referenced in source (1)

MoveItLifecycleManager.is_moveit_alive()

Poll the stored launch process to determine whether it remains running.

Method Β· Source

is_moveit_alive(self) -> bool

Returns: True when a process exists and poll returns None; False otherwise.

Errors: Process polling errors propagate.

Side effects: Polls/reaps process status as provided by subprocess.Popen.

Referenced in source (2)

MoveItLifecycleManager.get_moveit_exit_info()

Describe an absent or exited launch process after is_moveit_alive() reports False.

Method Β· Source

get_moveit_exit_info(self) -> str

Returns: A not-started message or an exit-code message. Calling while the process is alive yields an exit-code message containing None.

Errors: Process polling errors propagate.

Side effects: Polls process status.

MoveItLifecycleManager.notify_voltage_change()

Record a voltage changed through another control path so the next launch can avoid an unnecessary secondary-interface command.

Method Β· Source

notify_voltage_change(self, voltage: int)

Parameter

Meaning

voltage

New tool voltage in volts; stored without local validation.

Returns: None.

Errors: No explicit validation/failure path.

Side effects: Updates cached voltage only; sends no hardware command.

Internal callbacks and helpers

MoveItLifecycleManager._call_service()

Create a temporary service client, wait for availability, make a blocking call, and destroy the client.

Internal helper Β· Source

_call_service(self, srv_type, name: str, request, timeout_sec: float=5.0)

Parameter

Meaning

srv_type

ROS service type used to create the client.

name

Service name.

request

Request instance for srv_type.

timeout_sec

Response timeout in seconds, default 5.0; service discovery separately allows 5.0 seconds.

Returns: Service response, or None when unavailable or when the call returns no response.

Errors: Client creation, service calls and cleanup exceptions propagate. Unavailability and a missing response are logged. Another executor thread must process the reply while this call blocks.

Side effects: Creates and destroys a ROS client and invokes the named service, whose effects depend on the request.

Referenced in source (3)

MoveItLifecycleManager._joint_state_cb()

Copy known arm joint positions from a JointState while ignoring gripper/other joints; zip truncates unequal name/position lengths.

Callback Β· Source

_joint_state_cb(self, msg)

Parameter

Meaning

msg

JointState names and radian positions.

Returns: None.

Errors: Malformed messages can raise; values are not validated for finiteness.

Side effects: Updates the persistent name-to-position mapping using the arm names cached during construction.

Referenced in source (1)

MoveItLifecycleManager._publish_verified_model()

Read nonempty move_group URDF/SRDF strings and publish them on the managed model topics.

Internal helper Β· Source

_publish_verified_model(self, gripper: str) -> bool

Parameter

Meaning

gripper

Requested gripper name, used in diagnostics; this method does not inspect tool-specific XML content.

Returns: True after publishing both descriptions, or False if descriptions are unavailable.

Errors: Parameter request and publication errors propagate.

Side effects: Queries parameters and publishes two transient-local String messages. The caller assigns the model revision after success.

Referenced in source (1)

MoveItLifecycleManager._wait_for_verified_model()

Read move_group robot_description and semantic parameters within one monotonic deadline until both are nonempty strings. Tool-specific XML structure is checked by offline tests.

Internal helper Β· Source

_wait_for_verified_model(
    self,
    gripper: str,
    timeout_sec: float = 10.0,
) -> tuple[str, str] | None

Parameter

Meaning

gripper

Requested gripper name for the final error message.

timeout_sec

Overall parameter-service/response deadline in seconds, default 10.0.

Returns: (URDF, SRDF) string tuple, or None after unavailable services or deadline expiry.

Errors: Response/conversion exceptions are caught and retried; service/request errors outside the response block can propagate.

Side effects: Calls parameter services, waits on a completion event, pauses 50 ms between unsuccessful responses, and logs a final failure. Requires the caller’s executor to process responses.

Referenced in source (1)

MoveItLifecycleManager._attempt_launch()

Set changed real tool voltage and wait for power-up, spawn robot bringup in its own process session, wait for MoveIt and load obstacles. On hardware, also restart external control, verify joints, and set the payload. Configuration validation occurs before this method.

Internal helper Β· Source

_attempt_launch(self, gripper: str, cup_profile: str) -> bool

Parameter

Meaning

gripper

Configured gripper name.

cup_profile

Resolved cup-profile override forwarded only when nonempty.

Returns: True when all applicable readiness gates succeed; False at the first handled failure.

Errors: Process-spawn exceptions are caught. Gripper/config conversion and some helper exceptions propagate. Failure after spawning leaves cleanup to the caller.

Side effects: May send voltage commands, sleep 2 s, spawn ros2 launch, apply collision scene, restart robot control and set physical payload.

Referenced in source (1)

MoveItLifecycleManager._set_payload()

Convert a previously validated payload to a UR SetPayload request and require a successful response.

Internal helper Β· Source

_set_payload(self, config: dict) -> bool

Parameter

Meaning

config

Validated payload_mass in kg and payload_cog x/y/z in metres.

Returns: True after service success; False for service absence, a missing response, rejection, or a caught service exception.

Errors: Configuration reads, numeric conversion, imports and request construction precede the try block and can propagate. Service-phase exceptions become False; a created client is destroyed by _call_service().

Side effects: Waits up to 5 s for service availability and 10 s for its response, sends the robot’s mass in kg and centre of gravity in metres, and logs the outcome.

Referenced in source (1)

MoveItLifecycleManager._drain_stale_execute_trajectory()

Poll the ROS discovery graph until /execute_trajectory disappears, avoiding creation of action-client endpoints during teardown.

Internal helper Β· Source

_drain_stale_execute_trajectory(self, max_wait_sec: float=10.0)

Parameter

Meaning

max_wait_sec

Maximum drain wait in seconds, default 10.0.

Returns: None whether the action disappears or the deadline expires.

Errors: Graph API errors propagate; deadline expiry logs a warning rather than raising.

Side effects: Reads discovery and sleeps at 0.1 s intervals.

Referenced in source (1)

MoveItLifecycleManager._wait_for_moveit_ready()

Create a temporary ExecuteTrajectory client and wait for /execute_trajectory advertisement. This checks action availability, not payload, model correctness or hardware feedback.

Internal helper Β· Source

_wait_for_moveit_ready(self, timeout_sec: float=45.0) -> bool

Parameter

Meaning

timeout_sec

Action discovery timeout in seconds, default 45.0.

Returns: True when server is advertised, False on timeout.

Errors: Client construction/wait errors propagate; a successfully created client is destroyed in finally. If teardown left an old server advertised, this method may accept that stale endpoint.

Side effects: Creates/destroys action endpoints, waits and logs readiness.

Referenced in source (1)

MoveItLifecycleManager._verify_hardware_connected()

Clear previous joint feedback and wait for every configured arm joint, requiring the summed absolute position to exceed 0.01 radians.

Internal helper Β· Source

_verify_hardware_connected(self, timeout_sec: float=10.0) -> bool

Parameter

Meaning

timeout_sec

Feedback timeout in seconds, default 10.0.

Returns: True when the complete-joint/nonzero heuristic passes; False on timeout.

Errors: No broad exception handling; legitimate all-zero/near-zero poses fail this heuristic.

Side effects: Clears shared feedback state, waits in 0.1 s intervals using monotonic time and logs diagnostics.

Referenced in source (1)

MoveItLifecycleManager._load_collision_obstacles()

Read the beamline scene_file, translate box/cylinder/sphere obstacles to an additive PlanningScene diff and require /apply_planning_scene acknowledgement. Pose RPY values are passed as radians. Unknown shape types are skipped.

Internal helper Β· Source

_load_collision_obstacles(self) -> bool

Returns: True when no scene/obstacles are configured or the diff is accepted; False on missing file, service/response failure or exception.

Errors: Catches all load/build/service exceptions and logs traceback. Service discovery and response each have 5 s limits.

Side effects: Reads YAML, creates/destroys a service client and updates MoveIt collision objects by configured IDs. An empty scene does not remove previously loaded objects.

Referenced in source (1)

MoveItLifecycleManager._set_tool_voltage()

Send a set_tool_voltage URScript command to the robot secondary interface at TCP port 30002. Allowed values are validated when the beamline configuration loads.

Internal helper Β· Source

_set_tool_voltage(self, voltage: int) -> bool

Parameter

Meaning

voltage

Previously validated tool supply setting: 0, 12 or 24 volts. This helper formats it with int() and does not recheck the allowed set.

Returns: True after bytes are sent; False for missing robot IP or a caught socket/conversion/send failure. No controller acknowledgement is read.

Errors: Connection timeouts and other OSError failures are logged and return False; other exceptions inside the connection/send block also return False.

Side effects: Opens a TCP socket with 2 s timeout and sends a voltage command; the context manager closes the socket on both success and exceptions. Receipt may change the tool supply and stop external_control.

Referenced in source (1)

MoveItLifecycleManager._restart_external_control()

Create a fresh program-running subscription, call dashboard play, then require a True robot_program_running message before success.

Internal helper Β· Source

_restart_external_control(self) -> bool

Returns: True after accepted play and observed running state; False for timeout/rejection or caught service-phase exception.

Errors: Service availability, response and running-signal waits each allow 5 s. Subscription construction errors precede the try block and propagate; service-phase exceptions become False.

Side effects: Clears the program-running event, creates a fresh subscription, calls dashboard play through a temporary client, waits for a True signal and destroys the subscription.

Referenced in source (1)

MoveItLifecycleManager._robot_program_cb()

Latch the program-running event when a True UR status message arrives.

Callback Β· Source

_robot_program_cb(self, msg)

Parameter

Meaning

msg

Bool message from io_and_status_controller.

Returns: None.

Errors: Malformed messages can raise AttributeError.

Side effects: Sets _robot_program_running on True; False messages do not clear it. The next restart explicitly clears the event.

Referenced in source (1)