kuavo-humanoid-sdk 0.1.0__tar.gz

kuavo_humanoid_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,213 @@
+Metadata-Version: 2.1
+Name: kuavo_humanoid_sdk
+Version: 0.1.0
+Summary: A Python SDK for kuavo humanoid robot.
+Home-page: https://gitee.com/leju-robot/kuavo-ros-opensource/
+Author: ['lejurobot']
+Author-email: ['edu@lejurobot.com']
+License: MIT
+Project-URL: Documentation, https://gitee.com/leju-robot/kuavo-ros-opensource/
+Project-URL: Source Code, https://gitee.com/leju-robot/kuavo-ros-opensource/
+Description: # Kuavo Humanoid SDK
+        
+        A comprehensive Python SDK for controlling Kuavo humanoid robots. This SDK provides interfaces for robot state management, arm and head control, and end-effector operations. It is designed to work with ROS (Robot Operating System) environments.
+        
+        **Warning**: This SDK currently only supports **ROS1**. ROS2 support is not available.
+        
+        ![Kuavo 4Pro Robot](https://kuavo.lejurobot.com/manual/assets/images/kuavo_4pro-cf84d43f1c370666c6e810d2807ae3e4.png)
+        
+        ## Features
+        
+        - Robot State Management
+          - IMU data (acceleration, angular velocity, euler angles)
+          - Joint/motor states (position, velocity, torque)
+          - Torso state (position, orientation, velocity)
+          - Odometry information
+          - End-effector states:
+            - Gripper: position, velocity, torque, grasp status
+            - Dexterous hand: position, velocity, torque
+            - End-effector position and orientation
+          - Motion states: stand, walk, step_control, trot
+        
+        - Motion Control
+          - Arm Control
+            - Joint position control
+            - End-effector 6D control via inverse kinematics
+            - Forward kinematics (FK) for computing end-effector pose
+            - Keyframe sequence control for complex motions
+          - End-effector Control
+            - Gripper control (position control with configurable velocity and torque)
+            - Dexterous hand control
+              - Position control
+              - Pre-defined hand gestures (OK, 666, fist, etc.)
+          - Head Control
+            - Position control
+          - Torso Control
+            - Height control (squatting)
+            - Forward/backward tilt control
+          - Dynamic Motion Control
+            - Stance
+            - Trot
+            - Walking (xy and yaw velocity control)
+            - Stepping (gait switching)
+        
+        - Robot Basic Information
+          - Robot type (kuavo)
+          - Robot version
+          - End-effector type
+          - Joint names
+          - Total degrees of freedom (28)
+          - Arm degrees of freedom (7 per arm)
+          - Head degrees of freedom (2)
+          - Leg degrees of freedom (12)
+        
+        ## Installation
+        
+        To install Kuavo Humanoid SDK, you can use pip:
+        ```bash
+         pip install kuavo-humanoid-sdk
+        ```
+        
+        For development installation (editable mode), use:
+        ```bash
+         pip install -e .
+        ```
+        
+        ## Package Information
+        
+        You can check the package information using pip:
+        ```bash
+        pip show kuavo-humanoid-sdk
+        ```
+        
+        ## Quick Start
+        
+        Here's a simple example to get started with Kuavo Humanoid SDK:
+        
+        > **Warning**: Before running any code, make sure to start the robot first by executing either:
+        > - For simulation: `roslaunch humanoid_controllers load_kuavo_mujoco_sim.launch` (Example command)
+        > - For real robot: `roslaunch humanoid_controllers load_kuavo_real.launch` (Example command)
+        ```python3
+        # Copyright (c) 2025 Leju Robotics. Licensed under the MIT License.
+        import time
+        from kuavo_humanoid_sdk import KuavoSDK, KuavoRobot
+        
+        def main():
+            if not KuavoSDK().Init():  # Init! !!! IMPORTANT !!!
+                print("Init KuavoSDK failed, exit!")
+                exit(1)
+            robot = KuavoRobot()    
+            
+            """ arm reset """
+            print("Switching to arm reset mode...")
+            robot.arm_reset()
+            
+            """ stance """
+            print("Switching to stance mode...")
+            robot.stance()
+        
+            """ trot """
+            print("Switching to trot mode...")
+            robot.trot()
+            
+            """ walk forward """
+            print("Starting forward walk...")
+            duration = 4.0  # seconds
+            speed = 0.3     # m/s
+            start_time = time.time()
+            while (time.time() - start_time < duration):
+                robot.walk(linear_x=speed, linear_y=0.0, angular_z=0.0)
+                time.sleep(0.1)  # Small sleep to prevent busy loop
+            
+        if __name__ == "__main__":
+            main()
+        ```
+        
+        ## Examples
+        
+        #### WARNING
+        Before running any code examples, make sure to start the robot first by executing either:
+        
+        - For simulation: `roslaunch humanoid_controllers load_kuavo_mujoco_sim.launch` (Example command)
+        - For real robot: `roslaunch humanoid_controllers load_kuavo_real.launch` (Example command)
+        
+        ### Robot Info
+        
+        Examples showing how to get basic robot information.
+        
+        [https://gitee.com/leju-robot/kuavo-ros-opensource/tree/master/src/kuavo_humanoid_sdk/examples/robot_info_example.py](https://gitee.com/leju-robot/kuavo-ros-opensource/tree/master/src/kuavo_humanoid_sdk/examples/robot_info_example.py)
+        
+        ### Basic Robot Control
+        
+        A basic example showing how to initialize the SDK and control the robot’s movement.
+        
+        [https://gitee.com/leju-robot/kuavo-ros-opensource/tree/master/src/kuavo_humanoid_sdk/examples/motion_example.py](https://gitee.com/leju-robot/kuavo-ros-opensource/tree/master/src/kuavo_humanoid_sdk/examples/motion_example.py)
+        
+        ### End Effector Control
+        
+        #### LejuClaw Gripper
+        
+        Examples demonstrating how to control the LejuClaw gripper end effector, including position, velocity and torque control.
+        
+        [https://gitee.com/leju-robot/kuavo-ros-opensource/tree/master/src/kuavo_humanoid_sdk/examples/lejuclaw_example.py](https://gitee.com/leju-robot/kuavo-ros-opensource/tree/master/src/kuavo_humanoid_sdk/examples/lejuclaw_example.py)
+        
+        #### QiangNao DexHand
+        
+        Examples showing how to control the QiangNao DexHand, a dexterous robotic hand with multiple degrees of freedom for complex manipulation tasks.
+        
+        [https://gitee.com/leju-robot/kuavo-ros-opensource/tree/master/src/kuavo_humanoid_sdk/examples/dexhand_example.py](https://gitee.com/leju-robot/kuavo-ros-opensource/tree/master/src/kuavo_humanoid_sdk/examples/dexhand_example.py)
+        
+        ### Arm Control
+        
+        Examples showing arm trajectory control and target pose control.
+        
+        [https://gitee.com/leju-robot/kuavo-ros-opensource/tree/master/src/kuavo_humanoid_sdk/examples/ctrl_arm_example.py](https://gitee.com/leju-robot/kuavo-ros-opensource/tree/master/src/kuavo_humanoid_sdk/examples/ctrl_arm_example.py)
+        
+        ### Forward and Inverse Kinematics
+        
+        Examples demonstrating how to use forward kinematics (FK) to compute end-effector positions from joint angles, and inverse kinematics (IK) to calculate joint angles needed to achieve desired end-effector poses.
+        
+        [https://gitee.com/leju-robot/kuavo-ros-opensource/tree/master/src/kuavo_humanoid_sdk/examples/arm_ik_example.py](https://gitee.com/leju-robot/kuavo-ros-opensource/tree/master/src/kuavo_humanoid_sdk/examples/arm_ik_example.py)
+        
+        ### Head Control
+        
+        Examples showing how to control the robot’s head movements, including nodding (pitch) and shaking (yaw) motions.
+        
+        [https://gitee.com/leju-robot/kuavo-ros-opensource/tree/master/src/kuavo_humanoid_sdk/examples/ctrl_head_example.py](https://gitee.com/leju-robot/kuavo-ros-opensource/tree/master/src/kuavo_humanoid_sdk/examples/ctrl_head_example.py)
+        
+        ### Step-by-Step Control
+        
+        Examples showing how to control the robot’s movements step by step, including individual foot placement and trajectory control.
+        
+        [https://gitee.com/leju-robot/kuavo-ros-opensource/tree/master/src/kuavo_humanoid_sdk/examples/step_control_example.py](https://gitee.com/leju-robot/kuavo-ros-opensource/tree/master/src/kuavo_humanoid_sdk/examples/step_control_example.py)
+        
+        
+        ## Docs
+        
+        https://gitee.com/leju-robot/kuavo-ros-opensource/tree/master/src/kuavo_humanoid_sdk/docs/markdown/index.md
+        
+        ## License
+        
+        This project is licensed under the MIT License - see the LICENSE file for details.
+        
+        ## Contact & Support
+        
+        For any questions, support, or bug reports, please contact:
+        - Email: edu@lejurobot.com
+        - Website: https://gitee.com/leju-robot/kuavo-ros-opensource/
+        - Source Code: https://gitee.com/leju-robot/kuavo-ros-opensource/
+        - Issue Tracker: https://gitee.com/leju-robot/kuavo-ros-opensource/issues
+        
+Keywords: kuavo,humanoid,robot,robotics,lejurobot,ros
+Platform: UNKNOWN
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown

kuavo_humanoid_sdk-0.1.0/README.md

@@ -0,0 +1,67 @@
+
+
+# Kuavo Humanoid SDK
+
+A comprehensive Python SDK for controlling Kuavo humanoid robots. This SDK provides interfaces for robot state management, arm and head control, and end-effector operations. It is designed to work with ROS (Robot Operating System) environments.
+
+**Warning**: This SDK currently only supports **ROS1**. ROS2 support is not available.
+
+PyPI Package: https://pypi.org/project/kuavo-humanoid-sdk/
+
+## Installation
+
+To install Kuavo Humanoid SDK, you can use pip:
+```bash
+ pip install kuavo-humanoid-sdk
+```
+
+For development installation (editable mode), use:
+```bash
+ pip install -e .
+```
+
+## Description
+
+For detailed SDK documentation and usage examples, please refer to [sdk_description.md](sdk_description.md).
+
+## Documentation
+
+The documentation is available in two formats:
+- HTML format: [docs/html](docs/html)
+- Markdown format: [docs/markdown](docs/markdown)
+
+
+## For Maintainers
+
+### Package the SDK
+### Version Status Levels
+
+When updating the `setup.py` classifiers, use the appropriate Development Status:
+- `5 - Production/Stable `
+- `4 - Beta `
+
+To package the SDK for distribution, follow these steps:
+```bash
+python3 setup.py sdist bdist_wheel
+
+ls -lh ./dist/
+总用量 76K
+-rw-rw-r-- 1 lab lab 41K 2月  22 17:37 kuavo_humanoid_sdk-0.1.0-py3-none-any.whl
+-rw-rw-r-- 1 lab lab 32K 2月  22 17:37 kuavo_humanoid_sdk-0.1.0.tar.gz
+```
+
+### Upload to PyPI
+First, create or edit `~/.pypirc` with your API token:
+```
+[testpypi]
+username = __token__
+password = pypi-<your-token>
+```
+
+To upload the package to PyPI, use twine:
+```bash
+pip install --upgrade requests-toolbelt
+pip install "urllib3<=1.26.16" "twine<4.0.0" pyopenssl cryptography
+
+twine upload --repository testpypi dist/* --verbose
+```

kuavo_humanoid_sdk-0.1.0/kuavo_humanoid_sdk/__init__.py

@@ -0,0 +1,3 @@
+from .interfaces import *
+from .kuavo import *
+from kuavo_humanoid_sdk.common.logger import SDKLogger, disable_sdk_logging

kuavo_humanoid_sdk-0.1.0/kuavo_humanoid_sdk/common/logger.py

@@ -0,0 +1,42 @@
+import logging
+import os
+from pathlib import Path
+from logging.handlers import RotatingFileHandler
+def setup_logger():
+    logger = logging.getLogger('kuavo-humanoid-sdk')
+    logger.setLevel(logging.DEBUG)
+    log_suffix = f'log/kuavo_humanoid_sdk'
+    log_dir = f'/var/{log_suffix}'
+    try:
+        Path(log_dir).mkdir(parents=True, exist_ok=True)
+    except Exception as e:
+        # If creation in /var fails, create in current directory
+        log_dir = f'./{log_suffix}'
+        Path(log_dir).mkdir(parents=True, exist_ok=True)        
+    log_file = f'{log_dir}/kuavo_humanoid_sdk.log'
+
+    print(f'kuavo-humanoid-sdk log_file: {log_file}')
+
+    fh = RotatingFileHandler(log_file, maxBytes=2*1024*1024, backupCount=5)  # 每个日志文件最大 2 MB，保留 5 个备份文件
+    fh.setLevel(logging.DEBUG)
+    
+    ch = logging.StreamHandler()
+    ch.setLevel(logging.DEBUG)
+    
+    formatter = logging.Formatter('%(asctime)s - %(levelname)s - %(message)s')
+    fh.setFormatter(formatter)
+    ch.setFormatter(formatter)
+    
+    logger.addHandler(fh)
+    logger.addHandler(ch)
+    return logger
+
+def disable_sdk_logging():
+    """
+        Disable SDK logging.
+    """
+    logging.disable()
+
+
+""" Logger """
+SDKLogger = setup_logger()

kuavo_humanoid_sdk-0.1.0/kuavo_humanoid_sdk/interfaces/__init__.py

@@ -0,0 +1,4 @@
+from .data_types import *
+from .robot import *
+from .end_effector import *
+from .robot_info import *

kuavo_humanoid_sdk-0.1.0/kuavo_humanoid_sdk/interfaces/data_types.py

@@ -0,0 +1,122 @@
+from typing import Tuple
+from enum import Enum
+from dataclasses import dataclass
+
+@dataclass
+class KuavoJointData:
+    """Data class representing joint states of the robot.
+
+    Args:
+        position (list): List of joint positions (angles) in radians
+        velocity (list): List of joint velocities in radians/second
+        torque (list): List of joint torques/efforts in Newton-meters or Amperes
+        acceleration (list): List of joint accelerations in radians/second^2
+    """
+    position: list
+    velocity: list
+    torque: list
+    acceleration:list
+
+@dataclass
+class KuavoImuData:
+    """Data class representing IMU (Inertial Measurement Unit) data from the robot.
+
+    Args:
+        gyro (Tuple[float, float, float]): Angular velocity around x, y, z axes in rad/s
+        acc (Tuple[float, float, float]): Linear acceleration in x, y, z axes in m/s^2
+        free_acc (Tuple[float, float, float]): Free acceleration (gravity compensated) in x, y, z axes in m/s^2
+        quat (Tuple[float, float, float, float]): Orientation quaternion (x, y, z, w)
+    """
+    gyro : Tuple[float, float, float]
+    acc : Tuple[float, float, float]
+    free_acc: Tuple[float, float, float]
+    quat: Tuple[float, float, float, float]
+
+@dataclass
+class KuavoOdometry:
+    """Data class representing odometry data from the robot.
+
+    Args:
+        position (Tuple[float, float, float]): Robot position (x, y, z) in world coordinates in meters
+        orientation (Tuple[float, float, float, float]): Robot orientation as quaternion (x, y, z, w)
+        linear (Tuple[float, float, float]): Linear velocity (x, y, z) in world coordinates in m/s
+        angular (Tuple[float, float, float]): Angular velocity (x, y, z) in world coordinates in rad/s
+    """
+    position: Tuple[float, float, float]
+    orientation: Tuple[float, float, float, float]
+    linear: Tuple[float, float, float]
+    angular: Tuple[float, float, float]
+
+class KuavoArmCtrlMode(Enum):
+    """Enum class representing the control modes for the Kuavo robot arm.
+
+    Attributes:
+        ArmFixed: The robot arm is fixed in position (value: 0)
+        AutoSwing: The robot arm is in automatic swinging mode (value: 1)
+        ExternalControl: The robot arm is controlled by external commands (value: 2)
+    """
+    ArmFixed = 0
+    AutoSwing = 1 
+    ExternalControl = 2
+
+
+@dataclass
+class EndEffectorState:
+    """Data class representing the state of the end effector.
+
+    Args:
+        position (float): Position of the end effector, [0, 100]
+        velocity (float): ...
+        effort (float): ...
+    """
+    position: float
+    velocity: float
+    effort: float
+    class GraspingState(Enum):
+        """Enum class representing the grasping states of the end effector.
+
+        Attributes:
+            ERROR: Error state (value: -1)
+            UNKNOWN: Unknown state (value: 0)
+            REACHED: Target position reached (value: 1)
+            MOVING: Moving to target position (value: 2)
+            GRABBED: Object successfully grasped (value: 3)
+        """
+        ERROR = -1
+        UNKNOWN = 0
+        MOVING = 1
+        REACHED = 2
+        GRABBED = 3
+
+    state: GraspingState # gripper grasping states
+
+class EndEffectorSide(Enum):
+    """Enum class representing the sides of the end effector.
+
+    Attributes:
+        LEFT: The left side of the end effector (value: 'left')
+        RIGHT: The right side of the end effector (value: 'right')
+        BOTH: Both sides of the end effector (value: 'both')
+    """
+    LEFT = 'left'
+    RIGHT = 'right'
+    BOTH = 'both'
+
+@dataclass
+class KuavoPose:
+    """Data class representing the pose of the robot."""
+    position: Tuple[float, float, float] # x, y, z
+    orientation: Tuple[float, float, float, float] # x, y, z, w
+
+@dataclass
+class KuavoIKParams:
+    """Data class representing the parameters for the IK node."""
+    # snopt params
+    major_optimality_tol: float = 1e-3
+    major_feasibility_tol: float = 1e-3  
+    minor_feasibility_tol: float = 1e-3
+    major_iterations_limit: float = 100
+    # constraint and cost params
+    oritation_constraint_tol: float = 1e-3
+    pos_constraint_tol: float = 1e-3 # 0.001m, work when pos_cost_weight==0.0
+    pos_cost_weight: float = 0.0 # If U need high accuracy, set this to 0.0 !!!

kuavo_humanoid_sdk-0.1.0/kuavo_humanoid_sdk/interfaces/end_effector.py

@@ -0,0 +1,43 @@
+from abc import ABC, abstractmethod
+from typing import Tuple
+from kuavo_humanoid_sdk.interfaces.data_types import EndEffectorSide, EndEffectorState
+    
+class EndEffector(ABC):
+    def __init__(self, joint_names: list):
+        self.joint_names = joint_names
+        
+    @abstractmethod
+    def control(self, target_positions:list, target_velocities:list, target_torques:list)->bool:
+        pass
+
+    @abstractmethod
+    def control_right(self, target_positions:list, target_velocities:list, target_torques:list)->bool:
+        pass
+
+    @abstractmethod
+    def control_left(self, target_positions:list, target_velocities:list, target_torques:list)->bool:
+        pass    
+
+    @abstractmethod
+    def open(self, side:EndEffectorSide)->bool:
+        pass
+
+    @abstractmethod
+    def get_state(self)->Tuple[EndEffectorState, EndEffectorState]:
+        pass
+
+    @abstractmethod
+    def get_position(self)->Tuple[float, float]:
+        pass
+
+    @abstractmethod
+    def get_velocity(self)->Tuple[float, float]:
+        pass
+
+    @abstractmethod
+    def get_effort(self)->Tuple[float, float]:
+        pass
+
+    @abstractmethod
+    def get_grasping_state(self)->Tuple[EndEffectorState.GraspingState, EndEffectorState.GraspingState]:
+        pass

kuavo_humanoid_sdk-0.1.0/kuavo_humanoid_sdk/interfaces/robot.py

@@ -0,0 +1,22 @@
+
+from abc import ABC, abstractmethod
+
+class RobotBase(ABC):
+    def __init__(self, robot_type: str = "kuavo"):
+        self._robot_type = robot_type
+
+    @property
+    def robot_type(self) -> str:
+        return self._robot_type
+
+    @abstractmethod
+    def trot(self):
+        pass
+
+    @abstractmethod
+    def stance(self):
+        pass
+
+    @abstractmethod
+    def jump(self):
+        pass

kuavo_humanoid_sdk-0.1.0/kuavo_humanoid_sdk/interfaces/robot_info.py

@@ -0,0 +1,56 @@
+from abc import ABC, abstractmethod
+
+class RobotInfoBase(ABC):
+    def __init__(self, robot_type: str = "kuavo"):
+        self._robot_type = robot_type
+
+    @property
+    def robot_type(self) -> str:
+        """
+            Get the robot type, e.g. "kuavo"
+        """
+        return self._robot_type
+    
+    @property
+    @abstractmethod
+    def robot_version(self) -> str:
+        """
+            Get the robot version, e.g. "42", "43"
+        """
+        pass
+
+    @property
+    @abstractmethod
+    def end_effector_type(self) -> str:
+        """
+            Get the end effector type, e.g. "lejuclaw"...
+        """
+        pass
+
+    @property
+    @abstractmethod
+    def joint_names(self) -> list:
+        """
+            Get the joint names, e.g. ["joint1", "joint2", ...]
+        """
+        pass
+
+    @property
+    @abstractmethod
+    def joint_dof(self) -> int:
+        """
+            Get the joint degrees of freedom, e.g. 28
+        """
+        pass
+
+    @property
+    @abstractmethod
+    def arm_joint_dof(self) -> int:
+        """
+            Get the arm joint degrees of freedom, e.g. 14
+        """
+        pass
+
+    def __str__(self) -> str:
+       pass
+    

kuavo_humanoid_sdk-0.1.0/kuavo_humanoid_sdk/kuavo/__init__.py

@@ -0,0 +1,7 @@
+from .robot import KuavoSDK, KuavoRobot  
+from .robot_info import KuavoRobotInfo
+from .robot_state import KuavoRobotState
+from .robot_arm import KuavoRobotArm
+from .robot_head import KuavoRobotHead
+from .dexterous_hand import DexterousHand
+from .leju_claw import LejuClaw