`fastsim.controllers`

10 classes

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 method

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.

Parameters

Name	Type	Default	Description
`raise_exception`opt	bool	`True`	Raise a RuntimeError when success is False.

Returns

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

class

PriorityLevel

5 methods

fastsim.controllers.command.PriorityLevelextendsIntEnum

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).

Returns

PriorityLevel

MEDIUMproperty

@property def MEDIUM(self) → PriorityLevel

Medium priority (value 5).

Returns

PriorityLevel

HIGHproperty

@property def HIGH(self) → PriorityLevel

High priority (value 10).

Returns

PriorityLevel

MINproperty

@property def MIN(self) → PriorityLevel

Minimum possible priority (value -999).

Returns

PriorityLevel

MAXproperty

@property def MAX(self) → PriorityLevel

Maximum possible priority (value 999).

Returns

PriorityLevel

class

Command

abstract3 methods

fastsim.controllers.command.CommandextendsABC

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.

Returns

None

get_resultmethod

def get_result(self) → Any

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

Returns

Any — Command result, type depends on concrete command.

priorityproperty

@property def priority(self) → PriorityLevel

The priority level of this command.

Returns

PriorityLevel

class

SimpleCommand

1 method

fastsim.controllers.command.SimpleCommandextendsCommand

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

executemethod

def execute(self) → Any

Execute the command logic. Called once by ControllerManager.

Returns

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

Inherited fromCommand3

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 methods

fastsim.controllers.command.MultiCommandextendsCommand

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.

Returns

None

is_finishedmethod

def is_finished(self) → bool

Return True when the command has completed.

Returns

bool

get_resultmethod

def get_result(self) → Any

Return the final result after is_finished() is True.

Returns

Any — Command result.

Inherited fromCommand3

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

static-only4 methods

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.

Parameters

Name	Type	Default	Description
`command`	Command	—	The command to enqueue.

Returns

None

run_all_commandsmethod

def run_all_commands(self) → None

Process all pending commands for the current simulation tick.

Returns

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.

Returns

int — Queue length.

has_commandmethod

def has_command(self) → bool

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

Returns

bool

class

SpawnableController

static-only6 methods

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.

Parameters

Name	Type	Default	Description
`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.

Returns

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.

Parameters

Name	Type	Default	Description
`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.

Returns

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.

Parameters

Name	Type	Default	Description
`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.

Returns

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.

Parameters

Name	Type	Default	Description
`config_dict`	dict	—	Entity configuration following the scene config schema.
`register`opt	bool	`False`	Register the spawned entity in SceneManager.

Returns

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.

Parameters

Name	Type	Default	Description
`spawnable_name`	str	—	Name of the spawnable entity.

Returns

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.

Parameters

Name	Type	Default	Description
`spawnable_name`	str	—	Name of the spawnable entity.

Returns

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

class

RobotController

static-only3 methods

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.

Parameters

Name	Type	Default	Description
`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.

Returns

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.

Parameters

Name	Type	Default	Description
`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].

Returns

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.

Parameters

Name	Type	Default	Description
`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.

Returns

Result

class

MotionPlanController

static-only11 methods

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.

Parameters

Name	Type	Default	Description
`robot_name`	str	—	Target robot name.

Returns

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.

Parameters

Name	Type	Default	Description
`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.

Returns

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.

Parameters

Name	Type	Default	Description
`robot_name`	str	—	Target robot name.
`joint_positions`	list	—	List of joint position values.
`joint_names`	list	—	Matching list of joint names.

Returns

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.

Parameters

Name	Type	Default	Description
`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.

Returns

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.

Parameters

Name	Type	Default	Description
`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.

Returns

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.

Parameters

Name	Type	Default	Description
`robot_name`	str	—	Target robot name.

Returns

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).

Parameters

Name	Type	Default	Description
`robot_name`	str	—	Target robot name.

Returns

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.

Parameters

Name	Type	Default	Description
`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.

Returns

Result

detach_objectsmethod

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

Remove attached objects from a robot link.

Parameters

Name	Type	Default	Description
`robot_name`	str	—	Target robot name.
`link_name`opt	str	`'attached_object'`	The link from which to detach.

Returns

Result

get_world_representationmethod

def get_world_representation(self, robot_name: str) → Result

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

Parameters

Name	Type	Default	Description
`robot_name`	str	—	Target robot name.

Returns

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.

Parameters

Name	Type	Default	Description
`robot_name`	str	—	Target robot name.

Returns

Result — Robot collision representation in data.

class

ActionController

static-only1 method

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.

Parameters

Name	Type	Default	Description
`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.

Returns

Result — Execution result; data contains goal satisfaction status.