Implementation:ARISE Initiative Robosuite JointPositionController
| Knowledge Sources | |
|---|---|
| Domains | Robotics, Control |
| Last Updated | 2026-02-15 07:00 GMT |
Overview
Concrete tool for controlling robot joints via impedance-based position control provided by robosuite.
Description
The JointPositionController class implements joint-level position control using impedance (PD) control. It extends the abstract Controller base class and computes joint torques that drive the robot's joints toward desired position setpoints. The controller operates in joint space, making it suitable for tasks where direct joint angle targets are more natural than task-space commands.
The torque computation follows the standard impedance control law: tau = M * (kp * pos_error + kd * vel_error) + gravity_compensation, where M is the joint-space mass matrix, kp is the proportional gain, kd is the derivative gain (computed as 2 * sqrt(kp) * damping_ratio), and gravity compensation comes from MuJoCo's bias forces. The controller supports both delta and absolute input modes. In delta mode, actions are interpreted as relative displacements from current joint positions, scaled through configurable input/output ranges. In absolute mode, actions directly specify target joint positions.
Three impedance modes are supported: "fixed" with constant gains, "variable" where both kp and damping_ratio become part of the action space, and "variable_kp" where only kp is variable with critically damped behavior. An optional interpolator can smooth the transition between successive goal setpoints. Gravity compensation can be toggled via the use_torque_compensation keyword argument.
Usage
Use the JointPositionController when you need direct control over robot joint angles with compliant impedance behavior. It is also the underlying controller for the InverseKinematicsController, which converts task-space commands to joint position targets. Instantiate via the controller factory with the name "JOINT_POSITION".
Code Reference
Source Location
- Repository: ARISE_Initiative_Robosuite
- File: robosuite/controllers/parts/generic/joint_pos.py
- Lines: 1-312
Signature
class JointPositionController(Controller):
def __init__(
self,
sim,
joint_indexes,
actuator_range,
ref_name=None,
input_max=1,
input_min=-1,
output_max=0.05,
output_min=-0.05,
kp=50,
damping_ratio=1,
impedance_mode="fixed",
kp_limits=(0, 300),
damping_ratio_limits=(0, 100),
policy_freq=20,
lite_physics=True,
qpos_limits=None,
interpolator=None,
input_type: Literal["delta", "absolute"] = "delta",
**kwargs,
): ...
def set_goal(self, action, set_qpos=None): ...
def run_controller(self) -> np.array: ...
def reset_goal(self): ...
@property
def control_limits(self) -> tuple: ...
@property
def name(self) -> str: ... # Returns "JOINT_POSITION"
Import
from robosuite.controllers.parts.generic.joint_pos import JointPositionController
I/O Contract
Inputs
| Name | Type | Required | Description |
|---|---|---|---|
| sim | MjSim | Yes | MuJoCo simulator instance for reading robot state |
| joint_indexes | dict | Yes | Dictionary with keys 'joints', 'qpos', 'qvel' mapping to index lists
|
| actuator_range | 2-tuple of array | Yes | (low, high) joint actuator torque limit arrays |
| ref_name | str | No | End effector reference site name (optional for joint-space control) |
| input_max | float or Iterable | No | Maximum input action clipping value (default: 1) |
| input_min | float or Iterable | No | Minimum input action clipping value (default: -1) |
| output_max | float or Iterable | No | Maximum scaled output value per joint (default: 0.05 rad) |
| output_min | float or Iterable | No | Minimum scaled output value per joint (default: -0.05 rad) |
| kp | float or Iterable | No | Proportional gain for position error (default: 50) |
| damping_ratio | float or Iterable | No | Damping ratio for computing kd (default: 1, critically damped) |
| impedance_mode | str | No | One of "fixed", "variable", "variable_kp" (default: "fixed")
|
| kp_limits | 2-tuple | No | Min/max bounds for variable kp (default: (0, 300)) |
| damping_ratio_limits | 2-tuple | No | Min/max bounds for variable damping (default: (0, 100)) |
| policy_freq | int | No | Policy action frequency in Hz (default: 20) |
| qpos_limits | 2-list or None | No | Joint position limits in radians for goal clipping |
| interpolator | Interpolator | No | Interpolator for smooth goal transitions |
| input_type | str | No | "delta" or "absolute" (default: "delta"). Absolute only supported in fixed impedance mode
|
Outputs
| Name | Type | Description |
|---|---|---|
| torques | np.array | Computed joint torques including mass matrix scaling and gravity compensation |
| name | str | Controller identifier: "JOINT_POSITION"
|
| control_limits | tuple(np.array, np.array) | (min, max) action limits, varying by impedance mode |
Usage Examples
# Typical usage via the controller factory
from robosuite.controllers.parts.controller_factory import arm_controller_factory
import numpy as np
controller_params = {
"sim": sim,
"ref_name": "gripper0_grip_site",
"joint_indexes": {
"joints": [0, 1, 2, 3, 4, 5, 6],
"qpos": [0, 1, 2, 3, 4, 5, 6],
"qvel": [0, 1, 2, 3, 4, 5, 6],
},
"actuator_range": (np.array([-87]*7), np.array([87]*7)),
"policy_freq": 20,
"ndim": 7,
"interpolation": None,
"ramp_ratio": 0.2,
}
controller = arm_controller_factory("JOINT_POSITION", controller_params)
# Delta mode: small joint angle change
action = np.array([0.01, -0.01, 0.0, 0.0, 0.0, 0.0, 0.0])
controller.set_goal(action)
# Compute torques
torques = controller.run_controller()
# Absolute mode: set specific joint positions directly
# (requires input_type="absolute" at construction)
# controller.set_goal(target_joint_positions)