feathersdk.robot.motors.motors_manager Module

class feathersdk.robot.motors.motors_manager.CalibrationState(*values)

Bases: Enum

Represents the calibration and health state of a motor system.

CALIBRATION_FAILED = 'calibration_failed'
HEALTHY = 'healthy'
OUT_OF_RANGE = 'out_of_range'
RECALIBRATING = 'recalibrating'
UNCALIBRATED = 'uncalibrated'
UNINITIALIZED = 'uninitialized'
class feathersdk.robot.motors.motors_manager.CalibrationWarnings(*values)

Bases: Flag

HOMING_POSITION_NONZERO = 2
LOWER_LIMIT_MISMATCH = 4
NONE = 0
RANGE_MISMATCH = 1
UPPER_LIMIT_MISMATCH = 8
class feathersdk.robot.motors.motors_manager.FamilyConfig

Bases: TypedDict

safe_stop_policy: SafeStopPolicy
exception feathersdk.robot.motors.motors_manager.MotorCalibrationError(*args: Any, **kwargs: Any)

Bases: Exception

Raised when motor calibration fails or motor doesn’t respond as expected during calibration.

exception feathersdk.robot.motors.motors_manager.MotorNotFoundError(*args: Any, **kwargs: Any)

Bases: Exception

Raised when attempting to access a motor that does not exist in the motors map.

class feathersdk.robot.motors.motors_manager.MotorsManager

Bases: object

Handles sending commands to and receiving feedback from motors. Handles caching the state of the motors. Abstractions to make it easy to work with motors.

activate_compliance_mode_deceleration_stop(family_name: str, motor_name: str, safe_stop_policy: SafeStopPolicy = SafeStopPolicy.COMPLIANCE_MODE) → None
add_motors(motors_map: Dict[str, RobstrideMotor], family_name: str, family_config: FamilyConfig = {}) → None

Add a group of motors to the manager as a motor family.

Parameters:

  • motors_map – Dictionary mapping motor names to RobstrideMotor instances

  • family_name – Name identifier for this motor family

  • family_config – Configuration options for the motor family

check_motors_in_range(motor_names: List[str], target_angle: float | None = None, raise_error: bool = True) → bool

Check if motors are within valid range.

Validates that motors’ current positions and optionally a target angle are within their calibrated limits (upper_limit and lower_limit).

Parameters:

  • motor_names – List of motor names to check

  • target_angle – Optional target angle to validate against limits

  • raise_error – If True, raise exceptions on violations; if False, return False

Returns:

True if all motors are in range, False otherwise

Raises:

  • ValueError – If target_angle is out of range and raise_error is True

  • Exception – If current motor position is out of range and raise_error is True

compliance_mode_main(family_name: str, motor_name: str) → None

Main loop for compliance mode that adjusts motor positions based on torque feedback.

Parameters:

family_name (str) – Name of the motor family

disable(motor_name_or_id: str | int) → None

Disable the specified motor.

Parameters:

motor_name_or_id – Motor name (str) or motor ID (int)

enable(motor_name_or_id: str | int) → None

Enable the specified motor.

Parameters:

motor_name_or_id – Motor name or ID

find_motors(names: List[str] | None = None, allow_not_found: bool = False, progress: bool = False) → None

Find the motors on the physical CAN interfaces.

Parameters:

  • names (Optional[List[str]]) – The names of the motors to find. If not provided, find all motors in the motors map.

  • allow_not_found (bool) – If True, do not raise an error if a motor is not found.

  • progress (bool) – If True (and tqdm is installed), show a progress bar.

get_motor(motor_name_or_id: str | int) → RobstrideMotor

Get a motor instance by name or ID.

Parameters:

motor_name_or_id (Union[str, int]) – Motor name or motor ID

Returns:

The RobstrideMotor instance

Raises:

MotorNotFoundError – If the motor is not found in the motors map

motor_families: Dict[str, Dict[str, RobstrideMotor]]
motor_families_compliance_threads: Dict[str, FeatherThread]
motor_families_config: Dict[str, FamilyConfig]
motors: Dict[str, RobstrideMotor]
motors_by_id: Dict[int, RobstrideMotor]
motors_in_mode(motor_names: List[str], mode: RobstrideMotorMode) → bool

Check if all specified motors are in the given run mode.

Parameters:

  • motor_names – List of motor names to check

  • mode – The run mode to check for

Returns:

True if all motors are in the specified mode, False otherwise

on_abort() → None

Stop compliance mode for all motor families.

on_can_message(result: SocketResult) → None

Callback to handle incoming CAN messages.

on_fork()
on_motor_message(result: SocketResult) → None

Callback to handle incoming motor messages.

on_tcp_message(result: SocketResult) → None

Callback to handle incoming TCP messages.

operation_command(motor_name_or_id: str | int, target_torque: float, target_angle: float, target_velocity: float, kp: float, kd: float) → None

Send an operation command to a motor with torque, angle, velocity, and PD gains.

Parameters:

  • motor_name_or_id – Motor name (str) or motor ID (int)

  • target_torque – Target torque in Nm

  • target_angle – Target angle in radians

  • target_velocity – Target velocity in radians per second

  • kp – Proportional gain

  • kd – Derivative gain

ping(motor_name_or_id: str | int) → bool

Ping the motor to get back the current state of the motor.

read_current_state_async(motor_name_or_id: str | int) → dict

Asynchronously trigger a feedback frame from the motor and wait for fresh motor data.

This method sends a command to the motor (via _disable_active_reporting) that triggers a feedback response. It then waits for the feedback frame to arrive and be processed, retrying the command if necessary.

The method will retry sending the command every 100ms (10 iterations) if no feedback is received. After 300ms (30 iterations) with no feedback, a TimeoutError is raised to indicate that the motor is not responding. This ensures that stale feedback data is not used, as the method guarantees fresh feedback or an error.

Parameters:

motor_name_or_id – Name or ID of the motor

Raises:

TimeoutError – If no feedback frame is received within 300ms (after up to 3 retries)

Note

This method has a side-effect of disabling active reporting, which is not the true purpose. Since we are not using active reporting, this is not a problem for now. But if we start using active reporting, we need to revisit this. There was a Motor Data Save command in the Robstride manual for the motor, however, that did not work as expected.

read_current_state_sync(motor_name_or_id: str | int) → dict

Asynchronously trigger a feedback frame from the motor and wait for fresh motor data.

This method sends a command to the motor (via _disable_active_reporting) that triggers a feedback response. It then waits for the feedback frame to arrive and be processed, retrying the command if necessary.

The method will retry sending the command every 100ms (10 iterations) if no feedback is received. After 300ms (30 iterations) with no feedback, a TimeoutError is raised to indicate that the motor is not responding. This ensures that stale feedback data is not used, as the method guarantees fresh feedback or an error.

Parameters:

motor_name_or_id – Name or ID of the motor

Raises:

TimeoutError – If no feedback frame is received within 300ms (after up to 3 retries)

Note

This method has a side-effect of disabling active reporting, which is not the true purpose. Since we are not using active reporting, this is not a problem for now. But if we start using active reporting, we need to revisit this. There was a Motor Data Save command in the Robstride manual for the motor, however, that did not work as expected.

read_param(motor_name_or_id: str | int, param_id: int | str) → None

Read a parameter from the specified motor.

read_param_async(motor_name_or_id: str | bytes, param_id: int | str) → float

Asynchronously reads a motor parameter, waiting for the value to be updated. Replaces blocking time.sleep with non-blocking asyncio.sleep.

read_param_sync(motor_name_or_id: str | bytes, param_id: int | str) → float

Synchronously read a parameter from the motor, waiting for the value to be updated.

Parameters:

  • motor_name_or_id – Motor name (str) or motor ID (int)

  • param_id – Parameter ID or name

Returns:

The parameter value

Raises:

TimeoutError – If the parameter is not read within the timeout period

recover_from_power_cycle(motor_name: str) → None

Recover motor calibration after a power cycle where the encoder was reset.

Parameters:

motor_name – Name of the motor to recover

Raises:

UnsafeCommandError – If the motor is not a dual encoder motor or has no calibration

send_operation_commands(operation_commands: List[RobstrideOperationCommand], from_compliance_mode: bool = False) → None

Send operation commands to multiple motors.

Parameters:

operation_commands – List of RobstrideOperationCommand instances to send

set_run_mode(motor_name_or_id: str | int, run_mode: RobstrideRunMode) → None

Set the run mode for the specified motor.

Parameters:

  • motor_name_or_id – Motor name (str) or motor ID (int)

  • run_mode – The run mode to set (Position, Operation, or Torque)

set_target_position(motor_name_or_id: str | int, target_position: float) → None

Set the target position (loc_ref) for the specified motor.

This is a convenience method that wraps write_param for setting loc_ref. It provides a clearer API for position control.

Parameters:

  • motor_name_or_id – Name or ID of the motor

  • target_position – Target position in radians

Raises:

  • MotorDisabledError – If the motor is in Reset mode (disabled)

  • MotorModeInconsistentError – If the motor is not in Position run mode

set_target_velocity(motor_name_or_id: str | int, target_velocity: float) → None

Set the target velocity (spd_ref) for the specified motor.

This is a convenience method that wraps write_param for setting spd_ref. It provides a clearer API for velocity control.

Parameters:

  • motor_name_or_id – Name or ID of the motor

  • target_velocity – Target velocity in radians per second

Raises:

  • MotorDisabledError – If the motor is in Reset mode (disabled)

  • MotorModeInconsistentError – If the motor is not in Speed run mode

stop_compliance_mode(family_name: str) → None

Stop compliance mode for all motors in the specified family.

Parameters:

family_name (str) – Name of the motor family

trigger_compliance_mode(family_name: str, motor_name: str) → None

Enable compliance mode for all motors in the specified family.

Parameters:

family_name (str) – Name of the motor family

write_param(motor_name_or_id: str | int, param_id: int | str, param_value: float | int) → None

Write a parameter value to the specified motor.

Parameters:

  • motor_name_or_id – Name or ID of the motor

  • param_id – Parameter ID

  • param_value – Parameter value

zero_position(motor_name_or_id: str | int) → None

Set the current position of the motor as zero.

Parameters:

motor_name_or_id – Motor name (str) or motor ID (int)

class feathersdk.robot.motors.motors_manager.SafeStopPolicy(*values)

Bases: Enum

COMPLIANCE_MODE = 2
DISABLE_MOTORS = 1