How leap-hand/leap_hand_api works
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.