# 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.
**Warning**: **This SDK can only be used on the onboard NUC computer located in the robot's torso.**
## 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(lejuclaw): position, velocity, torque, grasp status
- Dexterous hand(qiangnao): position, velocity, torque
- Touch Dexterous hand(qiangnao_touch): position, velocity, torque, touch state
- 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
**Note: There are currently two versions of this SDK, the stable version and the beta version. Their differences are:**
- stable version: corresponding to the functionality provided by the `master` branch of [kuavo-ros-opensource](https://gitee.com/leju-robot/kuavo-ros-opensource/).
- Beta version: This version is more aggressive than the official version and also provides richer functionality, corresponding to the functionality provided by the `beta` branch of [kuavo-ros-opensource](https://gitee.com/leju-robot/kuavo-ros-opensource/).
**Friendly reminder: Please be clear about which version you need to install. If your SDK version does not match `kuavo-ros-opensource`, some features may not be available.**
Install the latest **stable version** of Kuavo Humanoid SDK using pip:
```bash
pip install kuavo-humanoid-sdk-ws
```
Install the latest **beta version** of Kuavo Humanoid SDK using pip:
```bash
pip install --pre kuavo-humanoid-sdk-ws
```
For local development installation (editable mode), use:
```bash
cd src/kuavo_humanoid_sdk_ws
chmod +x install.sh
./install.sh
```
## Upgrade Instructions
Before upgrading, you can check the currently installed version with:
```bash
pip show kuavo-humanoid-sdk-ws
# Output:
Name: kuavo-humanoid-sdk-ws
Version: 0.1.2
...
```
**Note: If the version number contains the letter b, it indicates a beta version, e.g., Version: 0.1.2b113**
To upgrade from a stable version to the latest stable version:
```bash
pip install --upgrade kuavo-humanoid-sdk-ws
```
To upgrade from a beta version to the latest stable version:
```bash
pip install --upgrade --force-reinstall kuavo-humanoid-sdk-ws
# or
pip uninstall kuavo-humanoid-sdk-ws && pip install kuavo-humanoid-sdk-ws
```
To upgrade from a stable/beta version to the latest beta version:
```bash
pip install --upgrade --pre kuavo-humanoid-sdk-ws
```
## Package Information
You can check the package information using pip:
```bash
pip show kuavo-humanoid-sdk-ws
```
## 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()
```
## Docs
The documentation is available in two formats:
- HTML format: [docs/html](docs/html), **needs to be generated by running the script**
- Markdown format: [docs/markdown](docs/markdown)
We recommend that you generate the documentation locally by running the documentation script. The documentation will be output to the `docs/html` and `docs/markdown` folders:
```bash
cd <kuavo-ros-opensource>/src/kuavo_humanoid_sdk_ws
chmod +x gen_docs.sh
./gen_docs.sh
```
**We recommend that you view the documentation using `html` for a better experience.**
For Markdown documentation at:
https://gitee.com/leju-robot/kuavo-ros-opensource/tree/master/src/kuavo_humanoid_sdk/docs/markdown/index.md
## 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)
## 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
Raw data
{
"_id": null,
"home_page": "https://gitee.com/leju-robot/kuavo-ros-opensource/",
"name": "kuavo-humanoid-sdk-ws",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "kuavo, humanoid, robot, robotics, lejurobot, ros",
"author": "['lejurobot']",
"author_email": "edu@lejurobot.com",
"download_url": "https://files.pythonhosted.org/packages/5c/82/70364802ea41e26419e582fea680c1826b97b9aa79d426222c45df9022b9/kuavo_humanoid_sdk_ws-1.2.0.tar.gz",
"platform": null,
"description": "# Kuavo Humanoid SDK\n\nA 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.\n\n**Warning**: This SDK currently only supports **ROS1**. ROS2 support is not available.\n\n**Warning**: **This SDK can only be used on the onboard NUC computer located in the robot's torso.** \n\n\n\n## Features\n\n- Robot State Management\n - IMU data (acceleration, angular velocity, euler angles)\n - Joint/motor states (position, velocity, torque)\n - Torso state (position, orientation, velocity)\n - Odometry information\n - End-effector states:\n - Gripper(lejuclaw): position, velocity, torque, grasp status\n - Dexterous hand(qiangnao): position, velocity, torque\n - Touch Dexterous hand(qiangnao_touch): position, velocity, torque, touch state\n - End-effector position and orientation\n - Motion states: stand, walk, step_control, trot\n\n- Motion Control\n - Arm Control\n - Joint position control\n - End-effector 6D control via inverse kinematics\n - Forward kinematics (FK) for computing end-effector pose\n - Keyframe sequence control for complex motions\n - End-effector Control\n - Gripper control (position control with configurable velocity and torque)\n - Dexterous hand control\n - Position control\n - Pre-defined hand gestures (OK, 666, fist, etc.)\n - Head Control\n - Position control\n - Torso Control\n - Height control (squatting)\n - Forward/backward tilt control\n - Dynamic Motion Control\n - Stance\n - Trot\n - Walking (xy and yaw velocity control)\n - Stepping (gait switching)\n\n- Robot Basic Information\n - Robot type (kuavo)\n - Robot version\n - End-effector type\n - Joint names\n - Total degrees of freedom (28)\n - Arm degrees of freedom (7 per arm)\n - Head degrees of freedom (2)\n - Leg degrees of freedom (12)\n\n## Installation\n\n**Note: There are currently two versions of this SDK, the stable version and the beta version. Their differences are:**\n\n- stable version: corresponding to the functionality provided by the `master` branch of [kuavo-ros-opensource](https://gitee.com/leju-robot/kuavo-ros-opensource/).\n- Beta version: This version is more aggressive than the official version and also provides richer functionality, corresponding to the functionality provided by the `beta` branch of [kuavo-ros-opensource](https://gitee.com/leju-robot/kuavo-ros-opensource/).\n\n**Friendly reminder: Please be clear about which version you need to install. If your SDK version does not match `kuavo-ros-opensource`, some features may not be available.**\n\nInstall the latest **\u200bstable version** of Kuavo Humanoid SDK using pip:\n```bash\npip install kuavo-humanoid-sdk-ws\n```\n\nInstall the latest **\u200bbeta version** of Kuavo Humanoid SDK using pip:\n```bash\npip install --pre kuavo-humanoid-sdk-ws\n```\n\nFor local development installation (editable mode), use:\n```bash\ncd src/kuavo_humanoid_sdk_ws \nchmod +x install.sh \n./install.sh \n```\n## Upgrade Instructions\nBefore upgrading, you can check the currently installed version with:\n```bash\npip show kuavo-humanoid-sdk-ws\n# Output: \nName: kuavo-humanoid-sdk-ws \nVersion: 0.1.2 \n... \n```\n\n**Note: If the version number contains the letter b, it indicates a beta version, e.g., Version: 0.1.2b113**\n\nTo upgrade from a stable version to the latest stable version:\n```bash\npip install --upgrade kuavo-humanoid-sdk-ws\n```\n\nTo upgrade from a beta version to the latest stable version:\n```bash\npip install --upgrade --force-reinstall kuavo-humanoid-sdk-ws\n# or \npip uninstall kuavo-humanoid-sdk-ws && pip install kuavo-humanoid-sdk-ws\n```\n\nTo upgrade from a stable/beta version to the latest beta version:\n```bash\npip install --upgrade --pre kuavo-humanoid-sdk-ws\n```\n\n## Package Information\n\nYou can check the package information using pip:\n```bash\npip show kuavo-humanoid-sdk-ws\n```\n\n## Quick Start\n\nHere's a simple example to get started with Kuavo Humanoid SDK:\n\n> **Warning**: Before running any code, make sure to start the robot first by executing either:\n> - For simulation: `roslaunch humanoid_controllers load_kuavo_mujoco_sim.launch` (Example command)\n> - For real robot: `roslaunch humanoid_controllers load_kuavo_real.launch` (Example command)\n```python3\n# Copyright (c) 2025 Leju Robotics. Licensed under the MIT License.\nimport time\nfrom kuavo_humanoid_sdk import KuavoSDK, KuavoRobot\n\ndef main():\n if not KuavoSDK().Init(): # Init! !!! IMPORTANT !!!\n print(\"Init KuavoSDK failed, exit!\")\n exit(1)\n robot = KuavoRobot() \n \n \"\"\" arm reset \"\"\"\n print(\"Switching to arm reset mode...\")\n robot.arm_reset()\n \n \"\"\" stance \"\"\"\n print(\"Switching to stance mode...\")\n robot.stance()\n\n \"\"\" trot \"\"\"\n print(\"Switching to trot mode...\")\n robot.trot()\n \n \"\"\" walk forward \"\"\"\n print(\"Starting forward walk...\")\n duration = 4.0 # seconds\n speed = 0.3 # m/s\n start_time = time.time()\n while (time.time() - start_time < duration):\n robot.walk(linear_x=speed, linear_y=0.0, angular_z=0.0)\n time.sleep(0.1) # Small sleep to prevent busy loop\n \nif __name__ == \"__main__\":\n main()\n```\n\n## Docs\nThe documentation is available in two formats:\n- HTML format: [docs/html](docs/html), **needs to be generated by running the script**\n- Markdown format: [docs/markdown](docs/markdown)\n\nWe recommend that you generate the documentation locally by running the documentation script. The documentation will be output to the `docs/html` and `docs/markdown` folders:\n```bash\ncd <kuavo-ros-opensource>/src/kuavo_humanoid_sdk_ws\nchmod +x gen_docs.sh\n./gen_docs.sh\n```\n\n**We recommend that you view the documentation using `html` for a better experience.**\n\nFor Markdown documentation at:\n\nhttps://gitee.com/leju-robot/kuavo-ros-opensource/tree/master/src/kuavo_humanoid_sdk/docs/markdown/index.md\n\n## Examples\n\n#### WARNING\nBefore running any code examples, make sure to start the robot first by executing either:\n\n- For simulation: `roslaunch humanoid_controllers load_kuavo_mujoco_sim.launch` (Example command)\n- For real robot: `roslaunch humanoid_controllers load_kuavo_real.launch` (Example command)\n\n### Robot Info\n\nExamples showing how to get basic robot information.\n\n[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)\n\n### Basic Robot Control\n\nA basic example showing how to initialize the SDK and control the robot\u2019s movement.\n\n[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)\n\n### End Effector Control\n\n#### LejuClaw Gripper\n\nExamples demonstrating how to control the LejuClaw gripper end effector, including position, velocity and torque control.\n\n[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)\n\n#### QiangNao DexHand\n\nExamples showing how to control the QiangNao DexHand, a dexterous robotic hand with multiple degrees of freedom for complex manipulation tasks.\n\n[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)\n\n### Arm Control\n\nExamples showing arm trajectory control and target pose control.\n\n[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)\n\n### Forward and Inverse Kinematics\n\nExamples 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.\n\n[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)\n\n### Head Control\n\nExamples showing how to control the robot\u2019s head movements, including nodding (pitch) and shaking (yaw) motions.\n\n[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)\n\n### Step-by-Step Control\n\nExamples showing how to control the robot\u2019s movements step by step, including individual foot placement and trajectory control.\n\n[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)\n\n\n## License\n\nThis project is licensed under the MIT License - see the LICENSE file for details.\n\n## Contact & Support\n\nFor any questions, support, or bug reports, please contact:\n- Email: edu@lejurobot.com\n- Website: https://gitee.com/leju-robot/kuavo-ros-opensource/\n- Source Code: https://gitee.com/leju-robot/kuavo-ros-opensource/\n- Issue Tracker: https://gitee.com/leju-robot/kuavo-ros-opensource/issues\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A Python SDK for kuavo humanoid robot.",
"version": "1.2.0",
"project_urls": {
"Documentation": "https://gitee.com/leju-robot/kuavo-ros-opensource/",
"Homepage": "https://gitee.com/leju-robot/kuavo-ros-opensource/",
"Source Code": "https://gitee.com/leju-robot/kuavo-ros-opensource/"
},
"split_keywords": [
"kuavo",
" humanoid",
" robot",
" robotics",
" lejurobot",
" ros"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "a23a9a2d2c3e82b746e870c8f767813690c57854174bb9997b821d0748c93577",
"md5": "43a64968d9ab0d9a2d8826004e296fae",
"sha256": "0f5ed30f2dd9e368368a1d6504218e12440026d2cc9e04f675a058f93d76b67b"
},
"downloads": -1,
"filename": "kuavo_humanoid_sdk_ws-1.2.0-20250714105233-py3-none-any.whl",
"has_sig": false,
"md5_digest": "43a64968d9ab0d9a2d8826004e296fae",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 71405,
"upload_time": "2025-07-14T02:52:35",
"upload_time_iso_8601": "2025-07-14T02:52:35.112651Z",
"url": "https://files.pythonhosted.org/packages/a2/3a/9a2d2c3e82b746e870c8f767813690c57854174bb9997b821d0748c93577/kuavo_humanoid_sdk_ws-1.2.0-20250714105233-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "5c8270364802ea41e26419e582fea680c1826b97b9aa79d426222c45df9022b9",
"md5": "6dc5405c5d48579780ade3512a1821e7",
"sha256": "943587ffee31e651716fb6cb3c94a640376eb356a3dc59e44d90dd736cd0a716"
},
"downloads": -1,
"filename": "kuavo_humanoid_sdk_ws-1.2.0.tar.gz",
"has_sig": false,
"md5_digest": "6dc5405c5d48579780ade3512a1821e7",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 60043,
"upload_time": "2025-07-14T02:52:36",
"upload_time_iso_8601": "2025-07-14T02:52:36.297439Z",
"url": "https://files.pythonhosted.org/packages/5c/82/70364802ea41e26419e582fea680c1826b97b9aa79d426222c45df9022b9/kuavo_humanoid_sdk_ws-1.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-14 02:52:36",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "kuavo-humanoid-sdk-ws"
}
JSON