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

Shared action server

Provide shared ROS action-server startup, goal admission, and execution callbacks. A busy reservation limits each server to one goal. Child actions reject cancellation by default.

beambot.action_servers.base_action_server · Source

Task execution · Guide · Symbol index

How it is used

Start here when adding an operation server. Subclass BaseActionServer, choose the ROS node and action names in __init__(), and implement create_stages(). The returned object must provide run(goal): None means success; an error string means failure. Override _execute() when the action needs additional result fields.

run_server() supplies the ROS executor and shutdown cleanup. Goal admission and result callbacks belong to the base class; clients send ROS action goals instead of calling those callbacks directly. The action server uses the node’s default callback group; the busy flag has no separate lock.

Start here

Callable	Purpose
run_server	Initialize ROS, construct an action node, attach it to MultiThreadedExecutor and spin so downstream responses can progress during blocking execution waits.
BaseActionServer.create_stages	Supply the operation stages when implementing a server subclass. The base implementation raises NotImplementedError.
BaseActionServer._execute	Run the goal through stages.run(): None becomes success; an error string becomes failure.

Example

The existing MoveToActionServer supplies only the endpoint identity and stage factory. This class-definition excerpt illustrates the extension contract; the normal launch path starts the server.

class MoveToActionServer(BaseActionServer):
    def __init__(self):
        super().__init__(
            node_name="beambot_moveto_server",
            action_name="beambot_moveto",
            action_type=MoveToAction,
        )

    def create_stages(self):
        return MoveToStages(self)

The inherited _execute() calls MoveToStages.run(goal). The base callbacks turn its error string or None into the final action result. The stage implementation requires ROS/MTC libraries and installed planning configuration. Constructing the first stage initializes the shared native node; this excerpt does not start a server.

Functions

run_server()

Initialize ROS, construct an action node, attach it to MultiThreadedExecutor and spin so downstream responses can progress during blocking execution waits.

Entry point · Source

run_server(server_class, args=None)

Parameter	Meaning
server_class	Zero-argument node class to construct.
args	Optional arguments forwarded to rclpy.init.

Returns: None after shutdown.

Errors: KeyboardInterrupt and ExternalShutdownException during spin are logged; other spin errors propagate after cleanup. Failures before the try block do not receive its cleanup.

Side effects: Initializes rclpy. On spin exit, ignores further SIGINT and SIGTERM so a repeated Ctrl+C cannot interrupt cleanup, destroys the node, then calls rclpy.try_shutdown() because the signal handler may already have shut the context down. Does not explicitly call executor.shutdown.

Referenced in source (8)

• main — beambot.action_servers.end_effector_server
• main — beambot.action_servers.move_to_server
• main — beambot.action_servers.orchestrator
• main — beambot.action_servers.pipettor_server
• main — beambot.action_servers.sample_pick_place_server
• main — beambot.action_servers.tool_exchange_server
• main — beambot.action_servers.vision_scan_server
• main — beambot.action_servers.vision_task_server

BaseActionServer

ROS node base for one operation action. It reserves one goal at a time, runs subclass stages, finalizes the result, and releases the reservation even after an exception. Subclasses supply stages and may customize result construction.

Inherits from: Node.

BaseActionServer.create_stages()

Supply the operation stages when implementing a server subclass. The base implementation raises NotImplementedError.

Extension hook · Source

create_stages(self)

Returns: Does not return in the base implementation.

Errors: Always raises NotImplementedError.

Referenced in source (1)

• BaseActionServer.__init__ — beambot.action_servers.base_action_server

BaseActionServer._execute()

Run the goal through stages.run(): None becomes success; an error string becomes failure.

Extension hook · Source

_execute(self, goal_handle: ServerGoalHandle)

Parameter	Meaning
goal_handle	Accepted action handle whose request is forwarded unchanged.

Returns: Typed success Result or failed Result carrying the stage error.

Errors: Stage exceptions propagate to _execute_callback.

Side effects: Runs operation stages, which may plan and actuate hardware.

Referenced in source (1)

• BaseActionServer._execute_callback — beambot.action_servers.base_action_server

BaseActionServer.__init__()

Create the ROS endpoint and the operation-specific stages supplied by the subclass.

Lifecycle · Source

__init__(self, node_name: str, action_name: str, action_type)

Parameter	Meaning
node_name	ROS node name.
action_name	ROS action endpoint name.
action_type	Generated action type providing Goal/Result messages.

Errors: Subclass stage or ROS action construction errors propagate.

Side effects: Creates a node, stages and action server in the default callback group; records an empty initial model revision and logs startup.

Internal callbacks and helpers

BaseActionServer._goal_callback()

Reserve an idle server before accepting the goal. For goals carrying robot_model_revision, record the supplied revision or a fresh UUID for an unversioned goal.

Callback · Source

_goal_callback(self, goal_request) -> GoalResponse

Parameter	Meaning
goal_request	Incoming action goal request.

Returns: GoalResponse.ACCEPT after reservation, or REJECT when already executing.

Errors: No field/type validation beyond optional revision attribute; unexpected access/logging errors propagate.

Side effects: Sets _executing and possibly _robot_model_revision; logs admission/rejection.

Referenced in source (1)

• BaseActionServer.__init__ — beambot.action_servers.base_action_server

BaseActionServer._execute_callback()

Run the operation, mark the action succeeded or aborted from result.success, convert execution exceptions to a failed result and always release the busy reservation.

Callback · Source

_execute_callback(self, goal_handle: ServerGoalHandle)

Parameter	Meaning
goal_handle	Accepted ROS ServerGoalHandle.

Returns: Typed action result returned by _execute, or failed result with exception text.

Errors: Catches operation/finalization exceptions, logs traceback and attempts abort; errors during exception logging/abort can still propagate.

Side effects: Executes operation stages, changes ROS goal status and clears the shared _executing flag in finally.

Referenced in source (1)

• BaseActionServer.__init__ — beambot.action_servers.base_action_server