Copybara import of the project:

--
1c079ef by Nan Wang <nanwang@tetheria.ai>:

add tetheria aero hand open example

--
068c1d6 by Nan Wang <nanwang@tetheria.ai>:

update license and update the action scale config

--
cc92835 by Nan Wang <nanwang@tetheria.ai>:

Remove stray CSV and ignore it

--
eaa5587 by Nan Wang <nanwang@tetheria.ai>:

rm gitignore

--
b385d4c by Nan Wang <nanwang@tetheria.ai>:

add back gitignore

--
892705c by Nan Wang <nanwang@tetheria.ai>:

update README

--
0c5fe74 by Nan Wang <nanwang@tetheria.ai>:

update README

--
9841c98 by Nan Wang <nanwang@tetheria.ai>:

rm unneeded pics

--
49504c0 by Nan Wang <nanwang@tetheria.ai>:

rm urdf

--
f33113b by Nan Wang <nanwang@tetheria.ai>:

rm format changes

--
8eb257d by Nan Wang <nanwang@tetheria.ai>:

Apply isort fixes; resolve previous comments

--
0c4f806 by Nan Wang <nanwang@tetheria.ai>:

correct weird format

--
2983abb by Nan Wang <nanwang@tetheria.ai>:

update naming to match convention

--
9662241 by Nan Wang <nanwang@tetheria.ai>:

update a cube

--
04f5b6c by Nan Wang <nanwang@tetheria.ai>:

update license heading, remove gifs, add small pngs, and move assets to menagerie

--
2f2cb95 by Nan Wang <nanwang@tetheria.ai>:

dir error for mesh

--
0afef9d by Nan Wang <nanwang@tetheria.ai>:

update mesh dir remove other materials

--
b2dd13e by Nan Wang <nanwang@tetheria.ai>:

remove unnecessary png

--
bbd21b1 by Nan Wang <nanwang@tetheria.ai>:

remove unworking dir

--
0567cd5 by Nan Wang <nanwang@tetheria.ai>:

remove configs about impl but use it as flag

--
b843526 by Nan Wang <nanwang@tetheria.ai>:

update menagerie sha

FUTURE_COPYBARA_INTEGRATE_REVIEW=#223 from TetherIA:main b843526

DO NOT SUBMIT

PiperOrigin-RevId: 836394388
Change-Id: I7044aaa6fa335404a23a8437c5c9e50a8cb62891

Author: Nan-Tetheria

mujoco_playground/_src/manipulation/__init__.py

@@ -28,7 +28,7 @@
 from mujoco_playground._src.manipulation.franka_emika_panda_robotiq import push_cube as robotiq_push_cube
 from mujoco_playground._src.manipulation.leap_hand import reorient as leap_cube_reorient
 from mujoco_playground._src.manipulation.leap_hand import rotate_z as leap_rotate_z
-
+from mujoco_playground._src.manipulation.aero_hand import rotate_z as aero_hand_rotate_z
 
 _envs = {
     "AlohaHandOver": aloha_handover.HandOver,
@@ -40,6 +40,7 @@
     "PandaRobotiqPushCube": robotiq_push_cube.PandaRobotiqPushCube,
     "LeapCubeReorient": leap_cube_reorient.CubeReorient,
     "LeapCubeRotateZAxis": leap_rotate_z.CubeRotateZAxis,
+    "AeroCubeRotateZAxis": aero_hand_rotate_z.CubeRotateZAxis,
 }
 
 _cfgs = {
@@ -52,11 +53,13 @@
     "PandaRobotiqPushCube": robotiq_push_cube.default_config,
     "LeapCubeReorient": leap_cube_reorient.default_config,
     "LeapCubeRotateZAxis": leap_rotate_z.default_config,
+    "AeroCubeRotateZAxis": aero_hand_rotate_z.default_config,
 }
 
 _randomizer = {
     "LeapCubeRotateZAxis": leap_rotate_z.domain_randomize,
     "LeapCubeReorient": leap_cube_reorient.domain_randomize,
+    "AeroCubeRotateZAxis": aero_hand_rotate_z.domain_randomize,
 }
 
 

mujoco_playground/_src/manipulation/aero_hand/README.md

@@ -0,0 +1,114 @@
+# Tetheria Aero Hand Open with Tendon-Driven Actuation
+
+This directory introduces a tendon-driven manipulation example that extends MuJoCo Playground with support for tendon-level control and observation in reinforcement learning tasks.
+
+The model is adapted from the [Tetheria Aero Hand Open](https://docs.tetheria.ai/), featuring a physically accurate tendon system that emulates cable-driven actuation. In this setup, both the policy inputs and observations are defined in the tendon space, providing a complete example of training and deploying tendon-driven controllers and under-actuated fingers in MuJoCo.
+
+An overview of the hand is shown below:
+
+| ![Rock](imgs/rock.png) | ![Paper](imgs/paper.png) | ![Scissor](imgs/scissor.png) |
+|------------------------|------------------------|------------------------|
+
+
+## 1. Tendon-Driven MuJoCo Model
+
+### 1.1 Modeling
+
+The mechanical design is derived from URDF files, ensuring accurate representation of the real hand structure. The actuation system in the simulator models the cable design in the real hand through three key components:
+
+#### 1.1.1 Tendon Drives
+The tendons drive the hand to close the fingers and control the thumbs. These are modeled as spatial tendons in MuJoCo that follow the exact routing paths of the real cables.
+
+#### 1.1.2 Springs
+The springs, which are also modeled by tendon components in MuJoCo, provide the forces to pull the fingers in the backward direction. This creates the restoring forces necessary for finger extension.
+
+#### 1.1.3 Pulleys
+The pulleys, which are modeled as cylinders, organize the cables and springs to ensure they are routed in a similar way to the real hand. Careful placement of these pulleys ensures accurate tendon routing.
+
+| front view| close-up of index|
+|------------------------|------------------------|
+| ![skeleton](imgs/skeleton.png) | ![index](imgs/index_close_up.png)
+
+### 1.2 Parameters
+
+#### 1.2.1 Mechanical Parameters
+- **Joint limits, mass, and inertia**: Come directly from URDF and are accurate to the real hand
+- **Pulley placement**: Positioned precisely where they are placed in the real hand, ensuring cable and spring routes match the real system
+- **Validation**: The range of tendon between fully open and fully closed fingers in simulation (0.0459454) closely matches the real hand (0.04553) without manual adjustment
+
+#### 1.2.2 Tendon and Spring Specifications
+- **Tendon properties**: Use the same specifications as those in the real hand
+- **Spring properties**: Match real hand specifications, except for the spring on the DIP joint, which is adjusted as a compromise to achieve similar joint space behavior as the real hand
+
+#### 1.2.3 Control Parameters
+All remaining parameters, including:
+- Joint damping values
+- Actuator gains
+- Joint-specific damping coefficients
+
+These are fine-tuned to satisfy both similar joint behaviors in simulation and the real world.
+
+
+## 2. Training your own policy
+
+We introduce a **z-axis rotation task** for the **Tetheria Aero Hand Open**, optimized using the following reward formulation:
+
+$$
+\text{reward} = 1.0 \times \text{angular velocity}
+               - 1.0 \times \text{action rate}
+               + \text{termination} (-100.0)
+$$
+
+The optimization variables include the **tendon lengths** and the **thumb abduction joint**, which correspond to the real hand’s actuation system.
+This setup ensures that the same control inputs and sensory data can be directly applied for **sim-to-real deployment** on the physical Tetheria Aero Hand Open.
+
+
+To train policies for the Tetheria Hand:
+
+```bash
+
+# Run the training script
+python learning/train_jax_ppo.py --env_name TetheriaCubeRotateZAxis
+```
+
+Although the reward curves from different training runs may vary due to stochasticity in the learning process, they consistently **converge toward a positive reward**.
+
+## 3. Running a pretrained policy
+
+
+To test trained policies in simulation:
+
+```bash
+# Run the simulation rollout script
+python learning/train_jax_ppo.py   --env_name TetheriaCubeRotateZAxis   --play_only   --load_checkpoint_path path/to/checkpoints
+```
+
+This will:
+- Load the trained policy
+- Run episodes in the MuJoCo simulation
+- Display the hand performing manipulation tasks
+
+## File Structure
+
+### Core Implementation
+- **`tetheria_hand_tendon_constants.py`** - Constants and configuration
+- **`rotate_z.py`** - Cube rotation task implementation
+
+### XML Models
+- **`xmls/right_hand.xml`** - Main hand model with tendon system
+- **`xmls/scene_mjx_cube.xml`** - Manipulation scene
+- **`xmls/reorientation_cube.xml`** - Cube reorientation task
+
+## Key Features
+
+- **Accurate tendon modeling**: Direct translation from real hand cable system
+- **Precise pulley placement**: Matches real hand routing exactly
+- **Validated parameters**: Tendon ranges match real hand within 0.1%
+
+---
+
+*This implementation provides a high-fidelity tendon-driven hand model that closely matches the real robotic hand, enabling effective sim-to-real transfer for manipulation tasks.*
+
+## Acknowledgements
+Our code is built upon
+- MuJoCo playground - https://github.com/google-deepmind/mujoco_playground

mujoco_playground/_src/manipulation/aero_hand/__init__.py

@@ -0,0 +1,15 @@
+# Copyright 2025 TetherIA Inc.
+# Copyright 2025 DeepMind Technologies Limited
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ==============================================================================

mujoco_playground/_src/manipulation/aero_hand/aero_hand_constants.py

@@ -0,0 +1,87 @@
+# Copyright 2025 TetherIA Inc.
+# Copyright 2025 DeepMind Technologies Limited
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ==============================================================================
+
+"""Constants for TetherIA Aero Hand Open."""
+
+from mujoco_playground._src import mjx_env
+
+ROOT_PATH = mjx_env.ROOT_PATH / "manipulation" / "aero_hand"
+CUBE_XML = ROOT_PATH / "xmls" / "scene_mjx_cube.xml"
+
+NQ = 16
+NV = 16
+NU = 7
+
+JOINT_NAMES = [
+    # index
+    "right_index_mcp_flex",
+    "right_index_pip",
+    "right_index_dip",
+    # middle
+    "right_middle_mcp_flex",
+    "right_middle_pip",
+    "right_middle_dip",
+    # ring
+    "right_ring_mcp_flex",
+    "right_ring_pip",
+    "right_ring_dip",
+    # pinky
+    "right_pinky_mcp_flex",
+    "right_pinky_pip",
+    "right_pinky_dip",
+    # thumb
+    "right_thumb_cmc_abd",
+    "right_thumb_cmc_flex",
+    "right_thumb_mcp",
+    "right_thumb_ip",
+]
+
+ACTUATOR_NAMES = [
+    # index
+    "right_index_A_tendon",
+    # middle
+    "right_middle_A_tendon",
+    # ring
+    "right_ring_A_tendon",
+    # pinky
+    "right_pinky_A_tendon",
+    # thumb
+    "right_thumb_A_cmc_abd",
+    "right_th1_A_tendon",
+    "right_th2_A_tendon",
+]
+
+FINGERTIP_NAMES = [
+    "if_tip",
+    "mf_tip",
+    "rf_tip",
+    "pf_tip",
+    "th_tip",
+]
+
+
+SENSOR_TENDON_NAMES = [
+    "len_if",
+    "len_mf",
+    "len_rf",
+    "len_pf",
+    "len_th1",
+    "len_th2",
+]
+
+SENSOR_JOINT_NAMES = [
+    "len_th_abd",
+]

mujoco_playground/_src/manipulation/aero_hand/base.py

@@ -0,0 +1,129 @@
+# Copyright 2025 TetherIA Inc.
+# Copyright 2025 DeepMind Technologies Limited
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ==============================================================================
+
+"""Base classes for TetherIA Aero Hand Open."""
+
+from typing import Any, Dict, Optional, Union
+
+from etils import epath
+import jax
+import jax.numpy as jp
+from ml_collections import config_dict
+import mujoco
+from mujoco import mjx
+
+from mujoco_playground._src import mjx_env
+from mujoco_playground._src.manipulation.aero_hand import aero_hand_constants as consts
+
+
+def get_assets() -> Dict[str, bytes]:
+  assets = {}
+  path = mjx_env.MENAGERIE_PATH / "tetheria_aero_hand_open"
+  mjx_env.update_assets(assets, path / "assets")
+  mjx_env.update_assets(assets, consts.ROOT_PATH / "xmls", "*.xml")
+  mjx_env.update_assets(
+      assets, consts.ROOT_PATH / "xmls" / "reorientation_cube_textures"
+  )
+  mjx_env.update_assets(assets, consts.ROOT_PATH / "xmls" / "assets")
+  return assets
+
+
+class AeroHandEnv(mjx_env.MjxEnv):
+  """Base class for Aero Hand environments."""
+
+  def __init__(
+      self,
+      xml_path: str,
+      config: config_dict.ConfigDict,
+      config_overrides: Optional[Dict[str, Union[str, int, list[Any]]]] = None,
+  ) -> None:
+    super().__init__(config, config_overrides)
+    self._model_assets = get_assets()
+    self._mj_model = mujoco.MjModel.from_xml_string(
+        epath.Path(xml_path).read_text(), assets=self._model_assets
+    )
+    self._mj_model.opt.timestep = self._config.sim_dt
+
+    self._mj_model.vis.global_.offwidth = 3840
+    self._mj_model.vis.global_.offheight = 2160
+
+    self._mjx_model = mjx.put_model(self._mj_model)
+    self._xml_path = xml_path
+
+  # Sensor readings.
+
+  def get_palm_position(self, data: mjx.Data) -> jax.Array:
+    return mjx_env.get_sensor_data(self.mj_model, data, "palm_position")
+
+  def get_cube_position(self, data: mjx.Data) -> jax.Array:
+    return mjx_env.get_sensor_data(self.mj_model, data, "cube_position")
+
+  def get_cube_orientation(self, data: mjx.Data) -> jax.Array:
+    return mjx_env.get_sensor_data(self.mj_model, data, "cube_orientation")
+
+  def get_cube_linvel(self, data: mjx.Data) -> jax.Array:
+    return mjx_env.get_sensor_data(self.mj_model, data, "cube_linvel")
+
+  def get_cube_angvel(self, data: mjx.Data) -> jax.Array:
+    return mjx_env.get_sensor_data(self.mj_model, data, "cube_angvel")
+
+  def get_cube_angacc(self, data: mjx.Data) -> jax.Array:
+    return mjx_env.get_sensor_data(self.mj_model, data, "cube_angacc")
+
+  def get_cube_upvector(self, data: mjx.Data) -> jax.Array:
+    return mjx_env.get_sensor_data(self.mj_model, data, "cube_upvector")
+
+  def get_cube_goal_orientation(self, data: mjx.Data) -> jax.Array:
+    return mjx_env.get_sensor_data(self.mj_model, data, "cube_goal_orientation")
+
+  def get_cube_goal_upvector(self, data: mjx.Data) -> jax.Array:
+    return mjx_env.get_sensor_data(self.mj_model, data, "cube_goal_upvector")
+
+  def get_fingertip_positions(self, data: mjx.Data) -> jax.Array:
+    """Get fingertip positions relative to the grasp site."""
+    return jp.concatenate([
+        mjx_env.get_sensor_data(self.mj_model, data, f"{name}_position")
+        for name in consts.FINGERTIP_NAMES
+    ])
+
+  # Accessors.
+
+  @property
+  def xml_path(self) -> str:
+    return self._xml_path
+
+  @property
+  def action_size(self) -> int:
+    return self._mjx_model.nu
+
+  @property
+  def mj_model(self) -> mujoco.MjModel:
+    return self._mj_model
+
+  @property
+  def mjx_model(self) -> mjx.Model:
+    return self._mjx_model
+
+
+def uniform_quat(rng: jax.Array) -> jax.Array:
+  """Generate a random quaternion from a uniform distribution."""
+  u, v, w = jax.random.uniform(rng, (3,))
+  return jp.array([
+      jp.sqrt(1 - u) * jp.sin(2 * jp.pi * v),
+      jp.sqrt(1 - u) * jp.cos(2 * jp.pi * v),
+      jp.sqrt(u) * jp.sin(2 * jp.pi * w),
+      jp.sqrt(u) * jp.cos(2 * jp.pi * w),
+  ])