This release is a pre-release and may not be stable for production use.
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)
- Arm Control
-
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
masterbranch of 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
betabranch of 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:
pip install kuavo-humanoid-sdk-ws
Install the latest beta version of Kuavo Humanoid SDK using pip:
pip install --pre kuavo-humanoid-sdk-ws
For local development installation (editable mode), use:
cd src/kuavo_humanoid_sdk_ws
chmod +x install.sh
./install.sh
Upgrade Instructions
Before upgrading, you can check the currently installed version with:
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:
pip install --upgrade kuavo-humanoid-sdk-ws
To upgrade from a beta version to the latest stable version:
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:
pip install --upgrade --pre kuavo-humanoid-sdk-ws
Package Information
You can check the package information using pip:
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)
# 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, needs to be generated by running the script
- Markdown format: 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:
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:
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.
Basic Robot Control
A basic example showing how to initialize the SDK and control the robot’s movement.
End Effector Control
LejuClaw Gripper
Examples demonstrating how to control the LejuClaw gripper end effector, including position, velocity and torque control.
QiangNao DexHand
Examples showing how to control the QiangNao DexHand, a dexterous robotic hand with multiple degrees of freedom for complex manipulation tasks.
Arm Control
Examples showing arm trajectory control and target pose control.
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.
Head Control
Examples showing how to control the robot’s head movements, including nodding (pitch) and shaking (yaw) motions.
Step-by-Step Control
Examples showing how to control the robot’s movements step by step, including individual foot placement and trajectory control.
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
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distributions
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file kuavo_humanoid_sdk_ws-1.4.5b776.tar.gz.
File metadata
- Download URL: kuavo_humanoid_sdk_ws-1.4.5b776.tar.gz
- Upload date:
- Size: 234.7 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/6.1.0 CPython/3.8.10
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
dfcf6e32f0fd0b5745f026a9101d0f5376dc0cfa812db4e217a686375a491bdb
|
|
| MD5 |
04f8a73872cc7a5dfee437fbeb90d60e
|
|
| BLAKE2b-256 |
37b23e59c60d4430195d72714275552730ba9a6c92b5c89854e5ae636bbe5d55
|
File details
Details for the file kuavo_humanoid_sdk_ws-1.4.5b776-20260806113636-py3-none-any.whl.
File metadata
- Download URL: kuavo_humanoid_sdk_ws-1.4.5b776-20260806113636-py3-none-any.whl
- Upload date:
- Size: 308.0 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/6.1.0 CPython/3.8.10
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
200a3be2f08a9127e638e002e31a853f80f70e6f901406e1d18a657ad7ea8653
|
|
| MD5 |
82b8657a6b5faf74802c8a5a7be33fa9
|
|
| BLAKE2b-256 |
9e63a57a76309596185749b1fda07c5d55f09f727234e6501b2713db66d5cc18
|
File details
Details for the file kuavo_humanoid_sdk_ws-1.4.5b776-20260806083020-py3-none-any.whl.
File metadata
- Download URL: kuavo_humanoid_sdk_ws-1.4.5b776-20260806083020-py3-none-any.whl
- Upload date:
- Size: 308.0 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/6.1.0 CPython/3.8.10
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
e57d6b2e2a8b4b6745dc4ef27a12546d41f5dd87cccf0f2d98f8daeaa2a4833a
|
|
| MD5 |
b7b2956331ea77cf0c5870c6a20c926c
|
|
| BLAKE2b-256 |
e8c07b18dee5740f2f753711c14172bfc8def67d623f9730aba96bb349680646
|
File details
Details for the file kuavo_humanoid_sdk_ws-1.4.5b776-20260805210818-py3-none-any.whl.
File metadata
- Download URL: kuavo_humanoid_sdk_ws-1.4.5b776-20260805210818-py3-none-any.whl
- Upload date:
- Size: 308.0 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/6.1.0 CPython/3.8.10
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
dcf64d8b9a26a56d9d83c290758a12fa1a0ca9ff14a5c89947eda6862ca23d17
|
|
| MD5 |
67d4eac1815198b1d3c7c825a7aa2a51
|
|
| BLAKE2b-256 |
c25628d252fb27833c4b79f0a12964bd3fa8a7a20e892127bfc79af5719432b6
|
