`fastsim.controllers`

10 个类

High-level controller classes decorated with @apiclass. Each controller wraps one or more backend capabilities and returns a structured Result object. The command queue system allows multi-step actions to be dispatched and awaited.

Result PriorityLevel Command SimpleCommand MultiCommand ControllerManager SpawnableController RobotController MotionPlanController ActionController

class

Result

1 个方法

fastsim.controllers.result.Result

Typed dict returned by every controller method: success flag, message, and payload.

Result inherits from dict and always contains the keys 'success' (bool), 'msg' (str), and 'data' (Any). Use unwrap() for safe payload extraction.

unwrapmethod

def unwrap(self, raise_exception: bool = True) → Any

Return the data payload, raising RuntimeError on failure if raise_exception=True.

参数

参数名	类型	默认值	说明
`raise_exception`opt	bool	`True`	Raise a RuntimeError when success is False.

返回值

Any — The value stored in Result['data'].

class

PriorityLevel

5 个方法

fastsim.controllers.command.PriorityLevel继承自IntEnum

Integer enum defining standard command priority levels used by ControllerManager.

Values: LOW=0, MEDIUM=5, HIGH=10, MIN=-999, MAX=999. Higher value means higher priority in the command queue.

LOWproperty

@property def LOW(self) → PriorityLevel

Low priority (value 0).

返回值

PriorityLevel

MEDIUMproperty

@property def MEDIUM(self) → PriorityLevel

Medium priority (value 5).

返回值

PriorityLevel

HIGHproperty

@property def HIGH(self) → PriorityLevel

High priority (value 10).

返回值

PriorityLevel

MINproperty

@property def MIN(self) → PriorityLevel

Minimum possible priority (value -999).

返回值

PriorityLevel

MAXproperty

@property def MAX(self) → PriorityLevel

Maximum possible priority (value 999).

返回值

PriorityLevel

class

Command

抽象类3 个方法

fastsim.controllers.command.Command继承自ABC

Abstract base command with a priority level. Commands are queued and executed by ControllerManager.

wait_for_resultmethod

def wait_for_result(self) → None

Block the calling thread until this command finishes.

返回值

None

get_resultmethod

def get_result(self) → Any

Return the result of the command (may be None if not yet finished).

返回值

Any — Command result, type depends on concrete command.

priorityproperty

@property def priority(self) → PriorityLevel

The priority level of this command.

返回值

PriorityLevel

class

SimpleCommand

1 个方法

fastsim.controllers.command.SimpleCommand继承自Command

Single-step command that executes entirely within one simulation tick.

executemethod

def execute(self) → Any

Execute the command logic. Called once by ControllerManager.

返回值

Any — Command result stored for retrieval via get_result().

继承自Command3

wait_for_resultmethod

def wait_for_result(self) → None

Block the calling thread until this command finishes.

get_resultmethod

def get_result(self) → Any

Return the result of the command (may be None if not yet finished).

priorityproperty

@property def priority(self) → PriorityLevel

The priority level of this command.

class

MultiCommand

3 个方法

fastsim.controllers.command.MultiCommand继承自Command

Multi-step command that spans multiple simulation ticks.

ControllerManager calls step() every tick until is_finished() returns True, then calls get_result().

stepmethod

def step(self) → None

Execute one tick of the command. Called by ControllerManager each simulation step.

返回值

None

is_finishedmethod

def is_finished(self) → bool

Return True when the command has completed.

返回值

bool

get_resultmethod

def get_result(self) → Any

Return the final result after is_finished() is True.

返回值

Any — Command result.

继承自Command3

wait_for_resultmethod

def wait_for_result(self) → None

Block the calling thread until this command finishes.

get_resultmethod

def get_result(self) → Any

Return the result of the command (may be None if not yet finished).

priorityproperty

@property def priority(self) → PriorityLevel

The priority level of this command.

class

ControllerManager

静态类4 个方法

fastsim.controllers.controller_manager.ControllerManager

Manages a priority-ordered command queue and drives command execution each tick.

ControllerManager is the runtime dispatcher for Command objects. Add commands from controller threads; the manager executes them in priority order on the simulation thread.

add_commandmethod

def add_command(self, command: Command) → None

Enqueue a command for execution.

参数

参数名	类型	默认值	说明
`command`	Command	—	The command to enqueue.

返回值

None

run_all_commandsmethod

def run_all_commands(self) → None

Process all pending commands for the current simulation tick.

返回值

None

Called automatically by FastSim.step() — users should not call this directly.

get_command_queue_lengthmethod

def get_command_queue_length(self) → int

Return the number of commands currently waiting in the queue.

返回值

int — Queue length.

has_commandmethod

def has_command(self) → bool

Return True if there is at least one command in the queue.

返回值

bool

class

SpawnableController

静态类6 个方法

fastsim.controllers.spawnable_controller.SpawnableController

Generic controller for sending commands to robots, objects, and sensors, plus spawning and introspection.

control_robotmethod

def control_robot(self, robot_name: str, function: str, parameters: dict | None = None, sync: bool = True) → Result

Send a named function call to a robot entity.

参数

参数名	类型	默认值	说明
`robot_name`	str	—	Target robot name.
`function`	str	—	The robot method/function name to invoke.
`parameters`opt	dict\|None	`None`	Optional keyword arguments forwarded to the function.
`sync`opt	bool	`True`	If True, block until the operation completes.

返回值

Result — Execution result with success flag and data payload.

control_objectmethod

def control_object(self, object_name: str, function: str, parameters: dict | None = None, sync: bool = True) → Result

Send a named function call to an object entity.

参数

参数名	类型	默认值	说明
`object_name`	str	—	Target object name.
`function`	str	—	The object method/function name to invoke.
`parameters`opt	dict\|None	`None`	Optional keyword arguments.
`sync`opt	bool	`True`	Block until done.

返回值

Result

control_sensormethod

def control_sensor(self, sensor_name: str, function: str, parameters: dict | None = None, sync: bool = True) → Result

Send a named function call to a sensor entity.

参数

参数名	类型	默认值	说明
`sensor_name`	str	—	Target sensor name.
`function`	str	—	Sensor method name.
`parameters`opt	dict\|None	`None`	Optional kwargs.
`sync`opt	bool	`True`	Block until done.

返回值

Result

spawn_with_configmethod

def spawn_with_config(self, config_dict: dict, register: bool = False) → Result

Dynamically spawn an entity from a config dict at runtime.

参数

参数名	类型	默认值	说明
`config_dict`	dict	—	Entity configuration following the scene config schema.
`register`opt	bool	`False`	Register the spawned entity in SceneManager.

返回值

Result — Success plus the spawned entity handle in data.

get_spawnable_datamethod

def get_spawnable_data(self, spawnable_name: str) → Result

Retrieve the state data dict for a named spawnable.

参数

参数名	类型	默认值	说明
`spawnable_name`	str	—	Name of the spawnable entity.

返回值

Result — State dict in data.

get_bounding_boxmethod

def get_bounding_box(self, spawnable_name: str) → Result

Get the axis-aligned bounding box of a spawnable.

参数

参数名	类型	默认值	说明
`spawnable_name`	str	—	Name of the spawnable entity.

返回值

Result — Bounding box (min, max corners) in data.

class

RobotController

静态类3 个方法

fastsim.controllers.robot_controller.RobotController

High-level robot motion primitives: trajectory following, IK (no collision), and direct EE pose commands.

move_robot_along_trajectorymethod

def move_robot_along_trajectory(self, robot_name: str, trajectory: list, joint_names: list, step_size: int = 1, sync: bool = True) → Result

Command the robot to follow a pre-computed joint trajectory.

参数

参数名	类型	默认值	说明
`robot_name`	str	—	Target robot name.
`trajectory`	list	—	Sequence of joint position waypoints.
`joint_names`	list	—	Ordered list of joint names corresponding to trajectory columns.
`step_size`opt	int	`1`	Number of trajectory waypoints to advance per simulation step.
`sync`opt	bool	`True`	Block until the trajectory completes.

返回值

Result

solve_ik_no_collision_checkmethod

def solve_ik_no_collision_check(self, robot_name: str, base_frame_ee_pose: list) → Result

Solve IK for a target end-effector pose without collision checking.

参数

参数名	类型	默认值	说明
`robot_name`	str	—	Target robot name.
`base_frame_ee_pose`	list	—	Target EE pose in the robot base frame [x, y, z, qw, qx, qy, qz].

返回值

Result — Joint positions in data.

move_robot_to_ee_pose_no_collision_checkmethod

def move_robot_to_ee_pose_no_collision_check(self, robot_name: str, base_frame_ee_pose: list, sync: bool = True) → Result

Move robot to an EE pose using IK without collision avoidance.

参数

参数名	类型	默认值	说明
`robot_name`	str	—	Target robot name.
`base_frame_ee_pose`	list	—	Target EE pose [x, y, z, qw, qx, qy, qz].
`sync`opt	bool	`True`	Block until motion completes.

返回值

Result

class

MotionPlanController

静态类11 个方法

fastsim.controllers.motion_plan_controller.MotionPlanController

Motion planning controller: IK, FK, collision-aware trajectory generation, joint state queries, and object attachment.

get_joint_statemethod

def get_joint_state(self, robot_name: str) → Result

Read the current joint positions of a robot.

参数

参数名	类型	默认值	说明
`robot_name`	str	—	Target robot name.

返回值

Result — Joint positions dict in data.

solve_ikmethod

def solve_ik(self, robot_name: str, base_frame_ee_pose: list, enable_retract: bool = False) → Result

Solve IK with optional retract pose for singularity avoidance.

参数

参数名	类型	默认值	说明
`robot_name`	str	—	Target robot name.
`base_frame_ee_pose`	list	—	Target EE pose [x, y, z, qw, qx, qy, qz].
`enable_retract`opt	bool	`False`	Use a retract joint position as the seed for IK.

返回值

Result — Solved joint positions in data.

solve_fkmethod

def solve_fk(self, robot_name: str, joint_positions: list, joint_names: list) → Result

Compute forward kinematics for a given joint configuration.

参数

参数名	类型	默认值	说明
`robot_name`	str	—	Target robot name.
`joint_positions`	list	—	List of joint position values.
`joint_names`	list	—	Matching list of joint names.

返回值

Result — End-effector pose in data.

gen_motion_planmethod

def gen_motion_plan(self, robot_name: str, start_position: list, joint_names: list, base_frame_ee_pose: list) → Result

Generate a collision-free joint trajectory from a start state to an EE target.

参数

参数名	类型	默认值	说明
`robot_name`	str	—	Target robot name.
`start_position`	list	—	Start joint positions.
`joint_names`	list	—	Joint names for the start position.
`base_frame_ee_pose`	list	—	Target EE pose.

返回值

Result — Planned trajectory in data.

move_robot_to_ee_posemethod

def move_robot_to_ee_pose(self, robot_name: str, base_frame_ee_pose: list, step_size: int = 1, sync: bool = True) → Result

Plan and execute a collision-free motion to a target EE pose.

参数

参数名	类型	默认值	说明
`robot_name`	str	—	Target robot name.
`base_frame_ee_pose`	list	—	Target EE pose.
`step_size`opt	int	`1`	Waypoints advanced per tick.
`sync`opt	bool	`True`	Block until motion completes.

返回值

Result

get_plannable_joint_namesmethod

def get_plannable_joint_names(self, robot_name: str) → Result

Return the list of joint names the planner can control for a robot.

参数

参数名	类型	默认值	说明
`robot_name`	str	—	Target robot name.

返回值

Result — List of joint name strings in data.

get_locked_jointmethod

def get_locked_joint(self, robot_name: str) → Result

Return joints that are locked (excluded from planning).

参数

参数名	类型	默认值	说明
`robot_name`	str	—	Target robot name.

返回值

Result — List of locked joint names in data.

attach_objectsmethod

def attach_objects(self, robot_name: str, object_names: list, link_name: str = 'attached_object', attach_offset: list | None = None) → Result

Virtually attach objects to a robot link for collision-aware planning.

参数

参数名	类型	默认值	说明
`robot_name`	str	—	Target robot name.
`object_names`	list	—	Names of the objects to attach.
`link_name`opt	str	`'attached_object'`	The robot link to attach to.
`attach_offset`opt	list\|None	`None`	Optional [x, y, z, qw, qx, qy, qz] offset from the link origin.

返回值

Result

detach_objectsmethod

def detach_objects(self, robot_name: str, link_name: str = 'attached_object') → Result

Remove attached objects from a robot link.

参数

参数名	类型	默认值	说明
`robot_name`	str	—	Target robot name.
`link_name`opt	str	`'attached_object'`	The link from which to detach.

返回值

Result

get_world_representationmethod

def get_world_representation(self, robot_name: str) → Result

Get the planner's world collision model for a robot.

参数

参数名	类型	默认值	说明
`robot_name`	str	—	Target robot name.

返回值

Result — World collision representation in data.

get_robot_representationmethod

def get_robot_representation(self, robot_name: str) → Result

Get the planner's robot self-collision model.

参数

参数名	类型	默认值	说明
`robot_name`	str	—	Target robot name.

返回值

Result — Robot collision representation in data.

class

ActionController

静态类1 个方法

fastsim.controllers.action_controller.ActionController

High-level action execution: dispatch a named action with parameters and optionally verify goal satisfaction.

actmethod

def act(self, action_config_params: dict, check_goal_satisfied: bool = True) → Result

Execute a configured action and optionally verify the goal condition.

参数

参数名	类型	默认值	说明
`action_config_params`	dict	—	Parameters for the action, keyed by the action schema.
`check_goal_satisfied`opt	bool	`True`	Verify the goal state after execution.

返回值

Result — Execution result; data contains goal satisfaction status.