Implementation:ARISE Initiative Robosuite Controller Base

Knowledge Sources	ARISE_Initiative_Robosuite
Domains	Robotics, Control
Last Updated	2026-02-15 07:00 GMT

Overview

Concrete tool for defining the abstract base interface for all robot arm part controllers provided by robosuite.

Description

The Controller class is the abstract base class for all robot arm controllers in the robosuite framework. It defines the common interface and shared state management that all concrete controller implementations (such as OSC, IK, joint position, joint velocity, and joint torque controllers) must adhere to. The class uses Python's abc.ABCMeta metaclass to enforce implementation of the run_controller() method in subclasses.

At initialization, the controller takes a reference to the MuJoCo simulator, joint index mappings, and actuator range limits. It initializes and maintains robot state including end-effector position/orientation/velocity, joint positions/velocities, Jacobian matrices (positional, orientational, and full), and the mass matrix. The update() method refreshes all these states from the simulator, with a new_update flag mechanism to prevent redundant computation. A lite_physics mode is available to skip unnecessary sim.forward() calls for performance optimization.

The class also provides utility methods shared across all controllers: scale_action() for input-output range mapping, clip_torques() for enforcing actuator limits, nums2array() for flexible scalar/array parameter handling, and properties for gravity compensation torques, actuator limits, and control limits. Support for single or multiple reference sites enables both single-arm and multi-arm/multi-site control scenarios.

Usage

Use the Controller base class as the parent for any new arm controller implementation in robosuite. It should never be instantiated directly, as it is abstract. All concrete arm controllers (OSC, IK, JointPosition, JointVelocity, JointTorque) inherit from this class and implement the run_controller() and set_goal() methods.

Code Reference

Source Location

Repository: ARISE_Initiative_Robosuite
File: robosuite/controllers/parts/controller.py
Lines: 1-347

Signature

class Controller(object, metaclass=abc.ABCMeta):
    def __init__(
        self,
        sim,
        joint_indexes,
        actuator_range,
        ref_name=None,
        part_name=None,
        naming_prefix=None,
        lite_physics=True,
    ): ...

    @abc.abstractmethod
    def run_controller(self): ...

    def scale_action(self, action) -> np.array: ...
    def update_reference_data(self): ...
    def update(self, force=False): ...
    def update_origin(self, origin_pos, origin_ori): ...
    def update_initial_joints(self, initial_joints): ...
    def clip_torques(self, torques) -> np.array: ...
    def reset_goal(self): ...

    @staticmethod
    def nums2array(nums, dim) -> np.array: ...

    @property
    def torque_compensation(self) -> np.array: ...

    @property
    def actuator_limits(self) -> tuple: ...

    @property
    def control_limits(self) -> tuple: ...

    @property
    def name(self) -> str: ...

Import

from robosuite.controllers.parts.controller import Controller

I/O Contract

Inputs

Name	Type	Required	Description
sim	MjSim	Yes	MuJoCo simulator instance for pulling robot state
joint_indexes	dict	Yes	Dictionary with keys `'joints'`, `'qpos'`, `'qvel'` containing index lists for the controlled joints
actuator_range	2-tuple of array	Yes	(low, high) arrays defining the torque limits for each joint actuator
ref_name	str or list of str	No	Name(s) of the end effector reference site(s) in the MuJoCo XML. If None, no EEF tracking is performed
part_name	str	No	Name of the robot part being controlled (e.g., "right", "left")
naming_prefix	str	No	Prefix used for naming in multi-robot scenarios
lite_physics	bool	No	If True, skips redundant `sim.forward()` calls for performance (default: True)

Outputs

Name	Type	Description
torques	np.array	Joint torques computed by subclass controller (stored as `self.torques`)
ref_pos	np.array	Current end effector position(s) (3,) or (N, 3) for multiple sites
ref_ori_mat	np.array	Current end effector orientation matrix (3,3) or (N, 3, 3)
joint_pos	np.array	Current joint positions
joint_vel	np.array	Current joint velocities
J_full	np.array	Full 6xN Jacobian matrix (positional + orientational rows)
mass_matrix	np.array	Inertia matrix for the controlled joints
torque_compensation	np.array	Gravity compensation torques from MuJoCo bias forces
control_limits	tuple(np.array, np.array)	(min, max) action limits defaulting to input_min/input_max
actuator_limits	tuple(np.array, np.array)	(min, max) actuator torque limits

Usage Examples

# The Controller class is abstract and cannot be instantiated directly.
# Instead, subclass it to create a custom controller:

from robosuite.controllers.parts.controller import Controller
import numpy as np

class MyCustomController(Controller):
    def __init__(self, sim, joint_indexes, actuator_range, **kwargs):
        super().__init__(
            sim=sim,
            joint_indexes=joint_indexes,
            actuator_range=actuator_range,
            ref_name=kwargs.get("ref_name", None),
        )
        self.control_dim = len(joint_indexes["joints"])
        self.input_max = np.ones(self.control_dim)
        self.input_min = -np.ones(self.control_dim)
        self.output_max = np.ones(self.control_dim) * 0.05
        self.output_min = -np.ones(self.control_dim) * 0.05

    def set_goal(self, action):
        self.update()
        self.goal = self.scale_action(action)

    def run_controller(self):
        self.update()
        # Custom torque computation logic here
        self.torques = np.zeros(self.control_dim)
        super().run_controller()
        return self.torques

    def reset_goal(self):
        self.goal = np.zeros(self.control_dim)

    @property
    def name(self):
        return "MY_CUSTOM"

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment