The SimFinger Class

The SimFinger class provides a simulation environment for the different finger robots: these include the TriFingerEdu, our reproducible open-source robot platform; the TriFingerPro, and the TriFingerOne. See trifinger_simulation.finger_types_data.get_valid_finger_types() for a complete list of supported robots.

The interface of SimFinger mimics that of the real robot frontend (see Real Robot Interface), which makes it easy to transfer code between simulation and real robot.

When using the TriFinger platform, see also TriFingerPlatform, which is a wrapper around SimFinger.

Desired vs Applied Action

The action given by the user is called the desired action. This action may be altered before it is actually applied on the robot, e.g. by some safety checks limiting torque and velocity. This altered action is called the applied action. You may use get_applied_action() to see what action actually got applied on the robot.

API Documentation

class trifinger_simulation.SimFinger(finger_type, time_step=0.001, enable_visualization=False, robot_position_offset=(0, 0, 0))[source]

PyBullet simulation environment for the single and the tri-finger robots.

Parameters:

finger_type (str) – Name of the finger type. Use get_valid_finger_types() to get a list of all supported types.
time_step (float) – Time (in seconds) between two simulation steps. Don’t set this to be larger than 1/60. The gains etc. are set according to a time_step of 0.001 s.
enable_visualization (bool) – Set this to ‘True’ for a GUI interface to the simulation.
robot_position_offset (Sequence[float]) – (x, y, z)-Position offset with which the robot is placed in the world. Use this, for example, to change the height of the fingers above the table.

Action(torque=None, position=None)[source]

Fill in the fields of the action structure.

This is a factory go create an Action instance with proper default values, depending on the finger type.

Parameters:

torque (_SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes] | None) – Torques to apply to the joints. Defaults to zero.
position (_SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes] | None) – Angular target positions for the joints. If set to NaN for a joint, no position control is run for this joint. Defaults to all NaN.

Returns:

The resulting action.

Return type:

Action

append_desired_action(action)[source]

Pass an action on which safety checks will be performed and then the action will be applied to the motors.

This method steps the simulation!

Parameters:: action (Action) – Action to be applied on the robot.
Returns:: The current time index t at which the action is applied.
Return type:: int

get_applied_action(t)[source]

Get the actually applied action of time step ‘t’.

The actually applied action can differ from the desired one, e.g. because the position controller affects the torque command or because too big torques are clamped to the limits.

Parameters:: t (int) – Index of the time step. The only valid value is the index of the current step (return value of the last call of append_desired_action()).
Returns:: The applied action of time step t.
Raises:: ValueError – If invalid time index t is passed.
Return type:: Action

get_current_timeindex()[source]

Get the current time index.

Return type:: int

get_desired_action(t)[source]

Get the desired action of time step ‘t’.

Parameters:: t (int) – Index of the time step. The only valid value is the index of the current step (return value of the last call of append_desired_action()).
Returns:: The desired action of time step t.
Raises:: ValueError – If invalid time index t is passed.
Return type:: Action

get_observation(t)[source]

Get the observation at the time of applying the action, so the observation actually corresponds to the state of the environment due to the application of the previous action.

Parameters:: t (int) – Index of the time step. The only valid value is the index of the current step (return value of the last call of append_desired_action()).
Returns:: Observation of the robot state.
Raises:: ValueError – If invalid time index t is passed.
Return type:: Observation

get_timestamp_ms(t)[source]

Get timestamp of time step ‘t’.

Parameters:: t (int) – Index of the time step. The only valid value is the index of the current step (return value of the last call of append_desired_action()).
Returns:: Timestamp in milliseconds. The timestamp starts at zero when initializing and is increased with every simulation step according to the configured time step.
Raises:: ValueError – If invalid time index t is passed.
Return type:: float

reset_finger_positions_and_velocities(joint_positions, joint_velocities=None)[source]

Reset the finger(s) to have the desired joint positions (required) and joint velocities (defaults to all zero) “instantaneously”, that is w/o calling the control loop.

Parameters:

joint_positions (Sequence[float]) – Angular position for each joint.
joint_velocities (Sequence[float] | None) – Angular velocities for each joint. If None, velocities are set to 0.

max_motor_torque: The maximum allowable torque that can be applied to each motor.

position_gains: Sequence[float]: The kp gains for the pd control of the finger(s). Note, this depends on the simulation step size and has been set for a simulation rate of 250 Hz.

safety_kd: The kd gains used for damping the joint motor velocities during the safety torque check on the joint motors.

velocity_gains: Sequence[float]: The kd gains for the pd control of the finger(s). Note, this depends on the simulation step size and has been set for a simulation rate of 250 Hz.

class trifinger_simulation.Action(torque, position, kp=None, kd=None)[source]

Robot action.

All parameters are expected to be of same length N, where N is the number of joints of the robot (e.g. 9 for TriFinger robots).

Parameters:

torque (ndarray) – See torque.
position (ndarray) – See position.
kp (_SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes] | None) – See position_kp. If not set, default gains are used for all joints.
kd (_SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes] | None) – See position_kd. If not set, default gains are used for all joints.

torque: ndarray: Torque commands for the joints.

position: ndarray: Position commands for the joints. Set to NaN to disable position control for the corresponding joint.

position_kp: ndarray: P-gain for position controller. Set to NaN to use default gain for the corresponding joint.

position_kd: ndarray: D-gain for position controller. Set to NaN to use default gain for the corresponding joint.

class trifinger_simulation.Observation[source]

Robot state observation.

position: ndarray: Angular joint positions in radian. Shape = (n_joints,)

velocity: ndarray: Joint velocities in rad/s. Shape = (n_joints,)

torque: ndarray: Joint torques in Nm. Shape = (n_joints,)

tip_force: ndarray: Measurement of the push sensors on the finger tips. Shape = (n_fingers,)