feathersdk.robot.actuator_systems.arms_system Module

feathersdk.robot.actuator_systems.arms_system.get_arm_pin_config_indices(model, joint_names)

TODO: make better docstring explaining what’s going on here.

Parameters:

  • model (pin.Model)

  • joint_names (List[str])

Return type:

Tuple[ndarray, ndarray]

class feathersdk.robot.actuator_systems.arms_system.Robstride7MArmConfig(*, module_name='arm', requires_urdf=True, safe_stop_policy=SafeStopPolicy.CANNOT_ENTER_SAFE_STOP, operating_frequency=50.0, actuators_share_same_endpoint=True, side, shoulder_pitch_motor, shoulder_roll_motor, shoulder_yaw_motor, elbow_motor, wrist_yaw_motor, wrist_pitch_motor, wrist_roll_motor, require_approval_for_calibration=True, on_abort_action='disable', apply_gravity_compensation=True)

Bases: ActuatorSystemConfig

Configuration for a single Robstride arm.

Parameters:
requires_urdf: bool

Whether this system requires the robot URDF to be loaded.

operating_frequency: float

The operating frequency of the arm system.

module_name: str

The name of the module.

side: Literal['left', 'right']

The side of the robot that the arm is on.

shoulder_pitch_motor: RobstrideMotorConfig

Configuration for the shoulder pitch motor.

shoulder_roll_motor: RobstrideMotorConfig

Configuration for the shoulder roll motor.

shoulder_yaw_motor: RobstrideMotorConfig

Configuration for the shoulder yaw motor.

elbow_motor: RobstrideMotorConfig

Configuration for the elbow motor.

wrist_yaw_motor: RobstrideMotorConfig

Configuration for the wrist yaw motor.

wrist_pitch_motor: RobstrideMotorConfig

Configuration for the wrist pitch motor.

wrist_roll_motor: RobstrideMotorConfig

Configuration for the wrist roll motor.

require_approval_for_calibration: bool

Whether to require approval for calibration by prompting the user for permission. Should always be True for production systems for safety!

on_abort_action: Literal['disable', 'freeze']

What to do when the arm is aborted. “disable” to home/disable motors, “freeze” to freeze the arm in place.

apply_gravity_compensation: bool

Whether to apply gravity compensation to the arm. If True, will add gravity torque to the motor when applying torque.

model_config: ClassVar[ConfigDict] = {'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class feathersdk.robot.actuator_systems.arms_system.RobstrideArmMotorTargets(*, motor, kp=0.0, kd=0.0, position=0.0, additional_torque=0.0, target_velocity=0.0, target_acceleration=0.0, max_velocity=0.0, max_acceleration=0.0, max_jerk=0.0, curr_position=0.0, curr_velocity=0.0, curr_acceleration=0.0)

Bases: PyDBaseModel

Targets for a single Robstride arm motor.

Parameters:
model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'frozen': False}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

motor: RobstrideMotor

The motor to set targets for.

kp: float

The proportional gain to use.

kd: float

The derivative gain to use.

position: float

The target position angle to reach.

additional_torque: float

The additional torque to apply.

target_velocity: float

The target velocity to have when reaching the target position.

target_acceleration: float

The target acceleration to have when reaching the target position.

max_velocity: float

The maximum velocity to reach.

max_acceleration: float

The maximum acceleration to reach.

max_jerk: float

The maximum jerk to reach.

curr_position: float

The current position of the motor.

curr_velocity: float

The current velocity of the motor.

curr_acceleration: float

The current acceleration of the motor.

class feathersdk.robot.actuator_systems.arms_system.ArmsControlMode(value)

Bases: UniqueEnum

The control mode for the arm.

Targets = 'targets'

Arms will move to specified target positions.

Impedance = 'impedance'

Arms will attempt to hold their current position unless moved around by external (non-gravity) forces.

class feathersdk.robot.actuator_systems.arms_system.Robstride7MArm(config, *args, **kwargs)

Bases: ActuatorSystem[Robstride7MArmConfig, RobstrideMotor]

A single Robstride arm with 7 motor design.

Parameters:
set_targets(positions=None, max_velocities=None, max_accelerations=None, max_jerks=None, kps=None, kds=None, target_velocities=None, target_accelerations=None, additional_torques=None)

Sets the target values for one or more motors in the arm.

Motion is controlled using Robstride’s Operation Command mode. Each arm motor will apply torque according to the following formula:

torque = kp * (target_position - current_position) + kd * (target_velocity - current_velocity) + offset

Where:

  • target_position is the target position angle to reach.

  • current_position is the last-received position angle of the motor.

  • target_velocity is the target angular velocity to reach. (This is computed automatically. See below.)

  • current_velocity is the last-received angular velocity of the motor.

  • kp is the proportional gain, applied to the position error.

  • kd is the derivative gain, applied to the velocity error.

  • offset is extra torque applied as needed. It will consist of: * Gravity compensation if config.apply_gravity_compensation is True. * Plus any additional torque to apply in the offset parameter to this function call.

Motor telemetry should update at around config.operating_frequency Hz.

The target velocity is computed automatically for time-optimal motion planning using Ruckig.

NOTE: Values will be clamped to the motor’s limits before sending commands to the motor. EG: using a max_velocity higher than the motor’s config.max_velocity will be clamped to the motor’s config.max_velocity.

NOTE: All parameters are optional. If None, then none of the motors’ parameters for that value will be changed. Otherwise it should be a dictionary with keys being either 1) the string name of the motor or 2) the RobstrideMotor object itself. Values are the new target values for that parameter. Any missing motor keys will not have their parameters changed. Any parameter values that are None will not be changed.

NOTE: If the arm is not in target control mode, then there may be restrictions on which parameters can be set. If in Impedance control mode, then only kps, kds, and additional_torques can be set.

Parameters:

  • positions (Dict[str | RobstrideMotor, float] | None) – New target position angles. See Note above for format details.

  • max_velocities (Dict[str | RobstrideMotor, float] | None) – New target maximum velocities. See Note above for format details.

  • max_accelerations (Dict[str | RobstrideMotor, float] | None) – New target maximum accelerations. See Note above for format details.

  • max_jerks (Dict[str | RobstrideMotor, float] | None) – New target maximum jerks. See Note above for format details.

  • kps (Dict[str | RobstrideMotor, float] | None) – New proportional gains. See Note above for format details.

  • kds (Dict[str | RobstrideMotor, float] | None) – New derivative gains. See Note above for format details.

  • target_velocities (Dict[str | RobstrideMotor, float] | None) – New target velocities. These are the velocities we want the motors to have when reaching the target position. Set to 0 to have motor stop at target position. See Note above for format details.

  • target_accelerations (Dict[str | RobstrideMotor, float] | None) – New target accelerations. These are the accelerations we want the motors to have when reaching the target position. Set to 0 not have instantaneous acceleration change upon reaching target. See Note above for format details.

  • additional_torques (Dict[str | RobstrideMotor, float] | None) – New additional torques to apply. See Note above for format details.

Return type:

None

capture_position(trigger_feedback=False)

Returns a dictionary mapping motor name to last-received angular position.

Parameters:

trigger_feedback (bool) – Whether to trigger a feedback frame for the motors. You should only need to set this to True if you want to get telemetry from an arm that is currently disabled. This will send a request to the motor to respond with current telemetry.

Return type:

Dict[str, float]

enable()

Enable the arm.

Return type:

None

disable()

Disable the arm. Moves to home position first.

Return type:

None

home(clean_parameters=False, block=True)

Home the arm.

Will switch to target control mode before homing.

Parameters:

  • clean_parameters (bool) – If True, will overwrite all movement parameters with defaults. This way, we will still home nicely even if bad parameters are set.

  • block (bool) – Whether to block the current thread until the home is complete.

Return type:

None

clean_parameters()

Clean the parameters of the arm.

This will overwrite all movement parameters with defaults except for the position.

Return type:

None

freeze(clean_parameters=True)

Attempt to freeze the arm in it’s current position.

Switches to using high kp/kd and target velocity of 0 to keep it in place. If gravity compensation is disabled, then this may not freeze well!

Parameters:

clean_parameters (bool) – If True, will overwrite all movement parameters with defaults. This way, we will still freeze nicely even if bad parameters are set.

Return type:

None

set_control_mode(control_mode)

Sets the control mode for the arm.

If switching to target control mode from a different control mode, will freeze the arms in place. Does nothing if control_mode is already the current control mode.

If switching to impedance control mode, the arms will decelerate to a stop and attempt to hold their position. However, if external (non-gravity) forces are applied, the arms will move around.

Parameters:

control_mode (ArmsControlMode | Literal['targets', 'impedance']) – The new control mode to set. Can be a string or an ArmsControlMode enum.

Return type:

None

recalibrate(allow_load=None)

Recalibrate the arm.

Parameters:

allow_load (bool | None)

Return type:

None

class feathersdk.robot.actuator_systems.arms_system.ArmsSystemConfig(*, module_name='arms_system', requires_urdf=True, safe_stop_policy=SafeStopPolicy.CANNOT_ENTER_SAFE_STOP, operating_frequency=30, actuators_share_same_endpoint=True, right_arm, left_arm)

Bases: ActuatorSystemConfig

Configuration for a full Robstride arm system.

Parameters:
model_config: ClassVar[ConfigDict] = {'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

module_name: str

The name of the arms system.

requires_urdf: bool

Whether this system requires the robot URDF to be loaded.

right_arm: Robstride7MArmConfig | None

Configuration for the right arm. Leave None to not include a right arm.

left_arm: Robstride7MArmConfig | None

Configuration for the left arm. Leave None to not include a left arm.

class feathersdk.robot.actuator_systems.arms_system.ArmsSystem(config, *args, **kwargs)

Bases: ActuatorSystem[ArmsSystemConfig, RobstrideMotor]

A system that controls 1-2 Robstride arms.

Parameters:
right_arm: Robstride7MArm | None

The right arm. None if not using a right arm.

left_arm: Robstride7MArm | None

The left arm. None if not using a left arm.

recalibrate(allow_load=None)

Recalibrate the arms system.

Parameters:

allow_load (bool | None)

Return type:

None

capture_position(trigger_feedback=False)

Capture the position of the arms.

Parameters:

trigger_feedback (bool) – Whether to trigger a feedback frame for the motors. You should only need to set this to True if you want to get telemetry from an arm that is currently disabled. This will send a request to the motor to respond with current telemetry.

Returns:

Dict mapping each motor name to its current position. Combines both arms together.

Return type:

Dict[str, float]

set_targets(positions=None, max_velocities=None, max_accelerations=None, max_jerks=None, kps=None, kds=None, target_velocities=None, target_accelerations=None, additional_torques=None)

Sets the target values for one or more motors in the arm.

Motion is controlled using Robstride’s Operation Command mode. Each arm motor will apply torque according to the following formula:

torque = kp * (target_position - current_position) + kd * (target_velocity - current_velocity) + offset

Where:

  • target_position is the target position angle to reach.

  • current_position is the last-received position angle of the motor.

  • target_velocity is the target angular velocity to reach. (This is computed automatically. See below.)

  • current_velocity is the last-received angular velocity of the motor.

  • kp is the proportional gain, applied to the position error.

  • kd is the derivative gain, applied to the velocity error.

  • offset is extra torque applied as needed. It will consist of: * Gravity compensation if config.apply_gravity_compensation is True. * Plus any additional torque to apply in the offset parameter to this function call.

Motor telemetry should update at around config.operating_frequency Hz.

The target velocity is computed automatically for time-optimal motion planning using Ruckig.

NOTE: Values will be clamped to the motor’s limits before sending commands to the motor. EG: using a max_velocity higher than the motor’s config.max_velocity will be clamped to the motor’s config.max_velocity.

NOTE: All parameters are optional. If None, then none of the motors’ parameters for that value will be changed. Otherwise it should be a dictionary with keys being either 1) the string name of the motor or 2) the RobstrideMotor object itself. Values are the new target values for that parameter. Any missing motor keys will not have their parameters changed. Any parameter values that are None will not be changed.

Parameters:

  • positions (Dict[str | RobstrideMotor, float] | None) – New target position angles. See Note above for format details.

  • max_velocities (Dict[str | RobstrideMotor, float] | None) – New target maximum velocities. See Note above for format details.

  • max_accelerations (Dict[str | RobstrideMotor, float] | None) – New target maximum accelerations. See Note above for format details.

  • max_jerks (Dict[str | RobstrideMotor, float] | None) – New target maximum jerks. See Note above for format details.

  • kps (Dict[str | RobstrideMotor, float] | None) – New proportional gains. See Note above for format details.

  • kds (Dict[str | RobstrideMotor, float] | None) – New derivative gains. See Note above for format details.

  • target_velocities (Dict[str | RobstrideMotor, float] | None) – New target velocities. These are the velocities we want the motors to have when reaching the target position. Set to 0 to have motor stop at target position. See Note above for format details.

  • target_accelerations (Dict[str | RobstrideMotor, float] | None) – New target accelerations. These are the accelerations we want the motors to have when reaching the target position. Set to 0 not have instantaneous acceleration change upon reaching target. See Note above for format details.

  • additional_torques (Dict[str | RobstrideMotor, float] | None) – New additional torques to apply. See Note above for format details.

Return type:

None

enable()

Enable the arms system.

Return type:

None

disable()

Disable the arms system. Moves to home position first.

Return type:

None

home(block=True)

Home the arms system. Will home both arms at the same time.

Parameters:

block (bool) – Whether to block the current thread until the home is complete. If False, will return immediately.

Return type:

None

freeze()

Freeze the arms system. The arms will hold their current position at the time of this call.

Return type:

None

set_control_mode(control_mode)

Sets the control mode for the arms system.

If switching to target control mode from a different control mode, will freeze the arms in place. Does nothing if control_mode is already the current control mode.

If switching to impedance control mode, the arms will decelerate to a stop and attempt to hold their position. However, if external (non-gravity) forces are applied, the arms will move around.

Parameters:

control_mode (ArmsControlMode | Literal['targets', 'impedance']) – The new control mode to set. Can be a string or an ArmsControlMode enum.

Return type:

None