Core Package

so101_nexus provides shared types, configuration classes, scene objects, observation components, asset helpers, and the environment registry. The MuJoCo backend lives under so101_nexus.mujoco and is registered by importing it.

import so101_nexus

Exports by Category

Type Aliases

Name	Definition
`ColorName`	`Literal["red", "orange", "yellow", "green", "blue", "purple", "black", "white", "gray"]`
`ColorConfig`	`ColorName \| list[ColorName]`
`ControlMode`	`Literal["pd_joint_pos", "pd_joint_delta_pos", "pd_joint_target_delta_pos"]`
`ObsMode`	`Literal["state", "visual"]`
`MoveDirection`	`Literal["up", "down", "left", "right", "forward", "backward"]`
`YcbModelId`	Literal union of 10 YCB object IDs (see Assets and Geometry)

Constants

Name	Type	Description
`SO101_JOINT_NAMES`	`tuple[str, ...]`	Ordered joint names for the SO-101 arm
`DIRECTION_VECTORS`	`dict[MoveDirection, tuple]`	Maps direction names to unit vectors
`COLOR_MAP`	`dict[str, list[float]]`	Maps color names to RGBA values
`YCB_OBJECTS`	`dict[str, str]`	Maps YCB model IDs to human-readable names
`ROBOT_CAMERA_PRESETS`	`dict[str, RobotCameraPreset]`	Named camera mounting presets for SO-100 and SO-101
`ASSETS_DIR`	`Path`	Root directory for bundled assets
`SO_ARM100_DIR`	`Path`	Asset directory for the SO-100 arm
`SO101_DIR`	`Path`	Asset directory for the SO-101 arm (URDF/XML retained for teleop calibration; the MuJoCo backend loads the menagerie MJCF)

Configuration Classes

All configuration classes have sensible defaults. See Configuration Classes for full reference.

Class	Purpose
`RenderConfig`	Render camera resolution (visualization only, not observations)
`RobotConfig`	Rest pose, grasp force threshold, velocity threshold
`RobotCameraPreset`	Named preset combining camera mounting parameters
`RewardConfig`	Reward component weights with a `compute()` method
`EnvironmentConfig`	Base environment parameters (spawn region, obs mode, episode length)
`PickConfig`	Extends `EnvironmentConfig` for pick/lift tasks
`PickAndPlaceConfig`	Extends `EnvironmentConfig` for pick-and-place tasks
`TouchConfig`	Extends PickConfig for touch-an-object tasks
`LookAtConfig`	Extends `EnvironmentConfig` for look-at tasks
`MoveConfig`	Extends `EnvironmentConfig` for directional move tasks

Observation Components

See Observations for conceptual overview and Configuration Classes for full parameter reference.

Class	Type	Description
`Observation`	Abstract base	Base class for all observation components
`JointPositions`	State (6-dim)	Current joint angles
`EndEffectorPose`	State (7-dim)	TCP position + quaternion orientation
`TargetOffset`	State (3-dim)	Vector from gripper to goal
`GazeDirection`	State (3-dim)	Unit vector toward target
`GraspState`	State (1-dim)	Binary grasp flag
`ObjectPose`	State (7-dim)	Object position + quaternion orientation
`ObjectOffset`	State (3-dim)	Vector from gripper to object
`TargetPosition`	State (3-dim)	Absolute goal position
`WristCamera`	Camera	RGB image from wrist-mounted camera
`OverheadCamera`	Camera	RGB image from stationary overhead camera

Scene Objects

See Scene Objects for full reference.

Class	Description
`SceneObject`	Abstract base for all scene objects
`CubeObject`	A colored cube with configurable size and mass
`YCBObject`	A YCB benchmark object loaded from mesh assets
`MeshObject`	A custom mesh object (MuJoCo only)

Functions

Color

Function	Signature	Description
`sample_color`	`(colors: ColorConfig, rng: Generator \| None = None) -> list[float]`	Resolve a ColorConfig to an RGBA list, sampling uniformly if given a list of colors

Asset Paths

Function	Returns	Description
`get_so101_simulation_dir()`	`Path`	Path to SO-101 `SO101/` assets (URDF/XML, retained for teleop calibration)
`get_so101_mujoco_model_dir()`	`Path`	Directory of the vendored menagerie MJCF (loaded by the MuJoCo backend)
`get_so101_mujoco_model_path()`	`Path`	Path to the menagerie `so101.xml` (loaded by the MuJoCo backend)
`get_so100_simulation_dir()`	`Path`	Path to SO-100 simulation assets

YCB Asset Management

See Assets and Geometry for full reference.

Function	Description
`ensure_ycb_assets(model_id)`	Download and cache YCB assets, return cache path
`get_ycb_mesh_dir(model_id)`	Path to mesh directory for a YCB model
`get_ycb_collision_mesh(model_id)`	Path to `collision.obj`
`get_ycb_visual_mesh(model_id)`	Path to `visual.obj`
`get_mujoco_ycb_rest_pose(verts)`	Rest orientation and spawn height for MuJoCo

Environment Registry

Function	Description
`all_registered_env_ids()`	Returns all registered Gymnasium environment IDs

See Environment Registry for details on how registration works.

Processor APIs

The optional so101_nexus.processors subpackage provides LeRobot-style action and observation processor steps and a Gym wrapper that emits LeRobot-shaped observations. It requires the teleop extra (pip install so101-nexus[teleop]). See LeRobot Processors for the full reference.

Core Package

On this page