# leap-hand/leap_hand_api architecture

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

- Interactive diagram: https://gitdiagram.com/leap-hand/leap_hand_api
- Repository: https://github.com/leap-hand/leap_hand_api

## Overview

This project is an SDK for a robotic hand (the “LEAP Hand”) that integrates multiple languages and platforms. The SDK provides native C++ components (using Eigen for math and the Dynamixel SDK for motor control), Python modules, and ROS as well as ROS2 interfaces. In other words, it is a multi-language, multi-API software stack that abstracts hardware (Dynamixel-driven LEAP Hand) control into several software “views” to support various application and research needs.

##### Main Components
a. Hardware Layer: Include the physical LEAP Hand with its Dynamixel motors, power supply, and USB connection. (External component.)
b. Low-Level Communication and Drivers: Represent the Dynamixel SDK (found in the “cpp/dynamixel_sdk” directories) which talks directly with the motor hardware. Also note the use of Eigen (in the “cpp/Eigen” folder) for matrix math—this supports computation tasks in C++.
c. Core Utilities and Libraries: The “leap_hand_utils” modules available in both the C++ (“cpp/leap_hand_utils”) and Python (“python/leap_hand_utils”) directories. These provide common abstractions such as “dynamixel_client” and “leap_hand_utils” for interfacing with the motors, converting between motor commands, and handling joint angle mapping.
d. Interface/API Layers:
- Python API: Located in the “python” folder. This module (particularly main.py and the supporting utils) exposes a high-level API to interact with the hand.
- ROS Module: The “ros_module” directory includes launch files, service definitions (.srv), ROS nodes, and helper libraries to control the hand via ROS.
- ROS2 Module: Similar to ROS but updated for ROS2 (“ros2_module”) with its own launch configuration, packages, and service definitions.
e. Example Applications and Useful Tools: The “useful_tools” folder (mano_to_leap_mapping.py) shows additional support utilities and examples using the SDK. Also, examples in the “cpp/dynamixel_sdk/example” folders illustrate different operational scenarios (like bulk reading, synchronized writing, pinging, etc.).

##### Out Relationships and Data Flow
a. At the bottom, the Hardware Layer (the physical hand with Dynamixel motors) communicates via USB with a computer.
b. The Low-Level Dynamixel SDK (C++ libraries) acts as a gateway by encapsulating the USB communication, reading sensor values (position, velocity, current) and sending commands.
c. The core utilities (“leap_hand_utils” and “dynamixel_client”) build on top of the low-level library to offer higher-level abstractions (such as PID control, joint angle scaling, etc.).
d. On top of the core libraries, there are several API layers:
- The native C++ application (main.cpp) can use these libraries directly.
- The Python API wraps the C++ functionality, making it accessible to Python developers.
- The ROS and ROS2 modules further wrap these libraries as nodes and services, exposing the functionality over the robot operating system middleware.

##### Architectural Patterns and Design Principles
a. Layered Architecture: Clearly show a separation between hardware, low-level drivers, core processing libraries, and API/application layers.
b. Modularity: Separate modules for each language (C++ vs. Python vs. ROS/ROS2) but sharing a common core.
c. Abstraction and Reusability: Notice that both the C++ implementation and Python wrappers call similar “leap_hand_utils” functions, reinforcing code reuse across technologies.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% API Layer
    subgraph "API Layer"
        A1("C++ Application"):::cpp
        A2("Python API"):::python
        A3("ROS Module"):::ros
        A4("ROS2 Module"):::ros
    end

    %% Core Libraries
    subgraph "Core Libraries"
        B1("Leap Hand Utils (C++)"):::cpp
        B2("Leap Hand Utils (Python)"):::python
    end

    %% Low-Level Drivers
    subgraph "Low-Level Drivers"
        C1("Dynamixel SDK"):::cpp
        C2("Eigen Math Library"):::cpp
    end

    %% Hardware Layer
    subgraph "Hardware Layer"
        D1("LEAP Hand Hardware – Dynamixel Motors"):::hardware
    end

    %% Examples & Tools
    subgraph "Examples & Tools"
        E1("C++ Examples"):::cpp
        E2("Mapping Tool"):::python
    end

    %% Connections from API Layer to Core Libraries
    A1 -->|"calls"| B1
    A2 -->|"calls"| B2
    A3 -->|"calls"| B1
    A4 -->|"calls"| B1

    %% Connections from Core Libraries to Low-Level Drivers
    B1 -->|"uses"| C1
    B1 -->|"uses"| C2
    B2 -->|"uses"| C1

    %% Connection from Low-Level Drivers to Hardware Layer
    C1 -->|"communicates"| D1

    %% Examples & Tools connections
    E1 -->|"demonstrates"| C1
    E2 -->|"utilizes"| A2

    %% Click Events
    click C1 "https://github.com/leap-hand/leap_hand_api/tree/main/cpp/dynamixel_sdk"
    click C2 "https://github.com/leap-hand/leap_hand_api/tree/main/cpp/Eigen"
    click B1 "https://github.com/leap-hand/leap_hand_api/tree/main/cpp/leap_hand_utils"
    click B2 "https://github.com/leap-hand/leap_hand_api/tree/main/python/leap_hand_utils"
    click A2 "https://github.com/leap-hand/leap_hand_api/blob/main/python/main.py"
    click A3 "https://github.com/leap-hand/leap_hand_api/tree/main/ros_module"
    click A4 "https://github.com/leap-hand/leap_hand_api/tree/main/ros2_module"
    click E1 "https://github.com/leap-hand/leap_hand_api/tree/main/cpp/dynamixel_sdk/example"
    click E2 "https://github.com/leap-hand/leap_hand_api/blob/main/useful_tools/mano_to_leap_mapping.py"

    %% Styles
    classDef cpp fill:#add8e6,stroke:#0000FF,stroke-width:2px;
    classDef python fill:#90ee90,stroke:#008000,stroke-width:2px;
    classDef ros fill:#ffcc99,stroke:#ff8c00,stroke-width:2px;
    classDef hardware fill:#e0e0e0,stroke:#808080,stroke-width:2px;
```
