# tetheria/aero-hand-open architecture

> Architecture diagram of the GitHub repository tetheria/aero-hand-open, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tetheria/aero-hand-open
- Repository: https://github.com/tetheria/aero-hand-open

## Overview

Aero Hand Open is an open-source tendon-driven dexterous robotic hand with firmware, a Python control SDK, and ROS 2 integrations for teleoperation and policy deployment. The principal ROS workflow streams hand motion from a mocap source, retargets it to hand-joint commands, then sends those commands to the hand node for actuation; the node can also publish actuator feedback. The graph includes the documented Manus, webcam, Apple Vision Pro, and RL branches. Some connections follow documented topics or README capabilities; unsampled implementations are represented only where the tree supports a path.

Main entry points: [`ros2/src/aero_hand_open_retargeting/aero_hand_open_retargeting/dex_retargeting_node.py`](https://github.com/tetheria/aero-hand-open/blob/main/ros2/src/aero_hand_open_retargeting/aero_hand_open_retargeting/dex_retargeting_node.py) (Retargeting node), [`sdk/src/aero_open_sdk/aero_hand.py`](https://github.com/tetheria/aero-hand-open/blob/main/sdk/src/aero_open_sdk/aero_hand.py) (Python hand interface), [`ros2/src/aero_hand_open/aero_hand_open/aero_hand_node.py`](https://github.com/tetheria/aero-hand-open/blob/main/ros2/src/aero_hand_open/aero_hand_open/aero_hand_node.py) (ROS hand node), [`ros2/src/aero_hand_open_rl/aero_hand_open_rl/rl_z_rotation_deploy.py`](https://github.com/tetheria/aero-hand-open/blob/main/ros2/src/aero_hand_open_rl/aero_hand_open_rl/rl_z_rotation_deploy.py) (RL policy deployment)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_capture["Motion capture"]
  node_webcam["Webcam capture<br/>[webcam_mocap.py]"]
  node_manus["Manus glove"]
  node_vision["Vision Pro capture"]
end

subgraph group_ros_control["ROS 2 control"]
  node_mocap_consumer["Retargeting node"]
  node_mediapipe_method["MediaPipe retargeting"]
  node_manus_method["Manus retargeting"]
  node_vision_method["Vision retargeting"]
  node_normalization["Pose normalization<br/>[normalize.py]"]
end

subgraph group_hand_runtime["Hand runtime"]
  node_hand_node["ROS hand node<br/>[aero_hand_node.py]"]
  node_firmware_config["Servo configuration<br/>[HandConfig.h]"]
  node_homing["Servo homing<br/>[Homing.cpp]"]
  node_physical_hand["Aero robotic hand"]
end

subgraph group_python_sdk["Python SDK"]
  node_sdk_gui["Control GUI<br/>[gui.py]"]
  node_sdk_hand["Python hand interface<br/>[aero_hand.py]"]
  node_joint_to_actuation["Joint conversion"]
  node_actuation_to_joint["Actuation conversion"]
end

subgraph group_policy["Policy deployment"]
  node_rl_deploy["RL policy deployment"]
  node_sim_mapping["Simulation mappings"]
  node_simulation["MuJoCo simulation"]
end

node_operator(("Teleoperator"))

node_operator -->|"provides hand motion"| node_webcam
node_webcam -->|"publishes mocap"| node_mocap_consumer
node_manus -->|"publishes glove data"| node_manus_method
node_vision -->|"publishes mocap"| node_vision_method
node_mocap_consumer -->|"retargets pose"| node_mediapipe_method
node_mocap_consumer -->|"retargets glove state"| node_manus_method
node_mocap_consumer -->|"retargets pose"| node_vision_method
node_mocap_consumer -->|"normalizes motion"| node_normalization
node_mocap_consumer -->|"publishes joint control"| node_hand_node
node_hand_node -->|"commands servos"| node_physical_hand
node_homing -->|"homes servos"| node_physical_hand
node_firmware_config -->|"supplies servo settings"| node_homing
node_operator -->|"sets hand targets"| node_sdk_gui
node_sdk_gui -->|"sends control"| node_sdk_hand
node_sdk_hand -->|"converts joint targets"| node_joint_to_actuation
node_sdk_hand -->|"converts feedback"| node_actuation_to_joint
node_sdk_hand -->|"controls over serial"| node_physical_hand
node_simulation -.->|"provides policy environment"| node_rl_deploy
node_rl_deploy -->|"maps simulated actions"| node_sim_mapping
node_rl_deploy -->|"publishes actuator control"| node_hand_node
node_hand_node -->|"publishes actuator feedback"| node_rl_deploy

click node_webcam "https://github.com/tetheria/aero-hand-open/blob/main/ros2/src/webcam_mocap/webcam_mocap/webcam_mocap.py"
click node_manus "https://github.com/tetheria/aero-hand-open/blob/main/ros2/src/manus_glove_pkg/manus_ros2/src/manus_data_publisher.cpp"
click node_vision "https://github.com/tetheria/aero-hand-open/blob/main/ros2/src/apple_vision_pro_mocap/apple_vision_pro_mocap/apple_vision_data_publisher.py"
click node_mocap_consumer "https://github.com/tetheria/aero-hand-open/blob/main/ros2/src/aero_hand_open_retargeting/aero_hand_open_retargeting/dex_retargeting_node.py"
click node_mediapipe_method "https://github.com/tetheria/aero-hand-open/blob/main/ros2/src/aero_hand_open_retargeting/aero_hand_open_retargeting/mediapipe_retargeting.py"
click node_manus_method "https://github.com/tetheria/aero-hand-open/blob/main/ros2/src/aero_hand_open_retargeting/aero_hand_open_retargeting/manus_joint_states_retargeting.py"
click node_vision_method "https://github.com/tetheria/aero-hand-open/blob/main/ros2/src/aero_hand_open_retargeting/aero_hand_open_retargeting/apple_vision_pro_retargeting.py"
click node_normalization "https://github.com/tetheria/aero-hand-open/blob/main/ros2/src/aero_hand_open_retargeting/aero_hand_open_retargeting/utils/normalize.py"
click node_hand_node "https://github.com/tetheria/aero-hand-open/blob/main/ros2/src/aero_hand_open/aero_hand_open/aero_hand_node.py"
click node_firmware_config "https://github.com/tetheria/aero-hand-open/blob/main/firmware/main/HandConfig.h"
click node_homing "https://github.com/tetheria/aero-hand-open/blob/main/firmware/main/Homing.cpp"
click node_sdk_gui "https://github.com/tetheria/aero-hand-open/blob/main/sdk/src/aero_open_sdk/gui.py"
click node_sdk_hand "https://github.com/tetheria/aero-hand-open/blob/main/sdk/src/aero_open_sdk/aero_hand.py"
click node_joint_to_actuation "https://github.com/tetheria/aero-hand-open/blob/main/sdk/src/aero_open_sdk/joints_to_actuations.py"
click node_actuation_to_joint "https://github.com/tetheria/aero-hand-open/blob/main/sdk/src/aero_open_sdk/actuations_to_joints.py"
click node_rl_deploy "https://github.com/tetheria/aero-hand-open/blob/main/ros2/src/aero_hand_open_rl/aero_hand_open_rl/rl_z_rotation_deploy.py"
click node_sim_mapping "https://github.com/tetheria/aero-hand-open/blob/main/ros2/src/aero_hand_open_rl/aero_hand_open_rl/utils/sim_to_real_mappings.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_webcam,node_manus,node_vision toneBlue
class node_mocap_consumer,node_mediapipe_method,node_manus_method,node_vision_method,node_normalization toneAmber
class node_hand_node,node_firmware_config,node_homing,node_physical_hand toneMint
class node_sdk_gui,node_sdk_hand,node_joint_to_actuation,node_actuation_to_joint toneRose
class node_rl_deploy,node_sim_mapping,node_simulation,node_operator toneIndigo
```

## Components

### Motion capture

- [Webcam capture](https://github.com/tetheria/aero-hand-open/blob/main/ros2/src/webcam_mocap/webcam_mocap/webcam_mocap.py): `ros2/src/webcam_mocap/webcam_mocap/webcam_mocap.py`
- [Manus glove](https://github.com/tetheria/aero-hand-open/blob/main/ros2/src/manus_glove_pkg/manus_ros2/src/manus_data_publisher.cpp): `ros2/src/manus_glove_pkg/manus_ros2/src/manus_data_publisher.cpp`
- [Vision Pro capture](https://github.com/tetheria/aero-hand-open/blob/main/ros2/src/apple_vision_pro_mocap/apple_vision_pro_mocap/apple_vision_data_publisher.py): `ros2/src/apple_vision_pro_mocap/apple_vision_pro_mocap/apple_vision_data_publisher.py`

### ROS 2 control

- [Retargeting node](https://github.com/tetheria/aero-hand-open/blob/main/ros2/src/aero_hand_open_retargeting/aero_hand_open_retargeting/dex_retargeting_node.py): `ros2/src/aero_hand_open_retargeting/aero_hand_open_retargeting/dex_retargeting_node.py`
- [MediaPipe retargeting](https://github.com/tetheria/aero-hand-open/blob/main/ros2/src/aero_hand_open_retargeting/aero_hand_open_retargeting/mediapipe_retargeting.py): `ros2/src/aero_hand_open_retargeting/aero_hand_open_retargeting/mediapipe_retargeting.py`
- [Manus retargeting](https://github.com/tetheria/aero-hand-open/blob/main/ros2/src/aero_hand_open_retargeting/aero_hand_open_retargeting/manus_joint_states_retargeting.py): `ros2/src/aero_hand_open_retargeting/aero_hand_open_retargeting/manus_joint_states_retargeting.py`
- [Vision retargeting](https://github.com/tetheria/aero-hand-open/blob/main/ros2/src/aero_hand_open_retargeting/aero_hand_open_retargeting/apple_vision_pro_retargeting.py): `ros2/src/aero_hand_open_retargeting/aero_hand_open_retargeting/apple_vision_pro_retargeting.py`
- [Pose normalization](https://github.com/tetheria/aero-hand-open/blob/main/ros2/src/aero_hand_open_retargeting/aero_hand_open_retargeting/utils/normalize.py): `ros2/src/aero_hand_open_retargeting/aero_hand_open_retargeting/utils/normalize.py`

### Hand runtime

- [ROS hand node](https://github.com/tetheria/aero-hand-open/blob/main/ros2/src/aero_hand_open/aero_hand_open/aero_hand_node.py): `ros2/src/aero_hand_open/aero_hand_open/aero_hand_node.py`
- [Servo configuration](https://github.com/tetheria/aero-hand-open/blob/main/firmware/main/HandConfig.h): `firmware/main/HandConfig.h`
- [Servo homing](https://github.com/tetheria/aero-hand-open/blob/main/firmware/main/Homing.cpp): `firmware/main/Homing.cpp`
- **Aero robotic hand**

### Python SDK

- [Control GUI](https://github.com/tetheria/aero-hand-open/blob/main/sdk/src/aero_open_sdk/gui.py): `sdk/src/aero_open_sdk/gui.py`
- [Python hand interface](https://github.com/tetheria/aero-hand-open/blob/main/sdk/src/aero_open_sdk/aero_hand.py): `sdk/src/aero_open_sdk/aero_hand.py`
- [Joint conversion](https://github.com/tetheria/aero-hand-open/blob/main/sdk/src/aero_open_sdk/joints_to_actuations.py): `sdk/src/aero_open_sdk/joints_to_actuations.py`
- [Actuation conversion](https://github.com/tetheria/aero-hand-open/blob/main/sdk/src/aero_open_sdk/actuations_to_joints.py): `sdk/src/aero_open_sdk/actuations_to_joints.py`

### Policy deployment

- [RL policy deployment](https://github.com/tetheria/aero-hand-open/blob/main/ros2/src/aero_hand_open_rl/aero_hand_open_rl/rl_z_rotation_deploy.py): `ros2/src/aero_hand_open_rl/aero_hand_open_rl/rl_z_rotation_deploy.py`
- [Simulation mappings](https://github.com/tetheria/aero-hand-open/blob/main/ros2/src/aero_hand_open_rl/aero_hand_open_rl/utils/sim_to_real_mappings.py): `ros2/src/aero_hand_open_rl/aero_hand_open_rl/utils/sim_to_real_mappings.py`
- **MuJoCo simulation**

### Other components

- **Teleoperator**

## Connections

- Teleoperator → Webcam capture: provides hand motion
- Webcam capture → Retargeting node: publishes mocap
- Manus glove → Manus retargeting: publishes glove data
- Vision Pro capture → Vision retargeting: publishes mocap
- Retargeting node → MediaPipe retargeting: retargets pose
- Retargeting node → Manus retargeting: retargets glove state
- Retargeting node → Vision retargeting: retargets pose
- Retargeting node → Pose normalization: normalizes motion
- Retargeting node → ROS hand node: publishes joint control
- ROS hand node → Aero robotic hand: commands servos
- Servo homing → Aero robotic hand: homes servos
- Servo configuration → Servo homing: supplies servo settings
- Teleoperator → Control GUI: sets hand targets
- Control GUI → Python hand interface: sends control
- Python hand interface → Joint conversion: converts joint targets
- Python hand interface → Actuation conversion: converts feedback
- Python hand interface → Aero robotic hand: controls over serial
- MuJoCo simulation → RL policy deployment: provides policy environment
- RL policy deployment → Simulation mappings: maps simulated actions
- RL policy deployment → ROS hand node: publishes actuator control
- ROS hand node → RL policy deployment: publishes actuator feedback