This release is a pre-release and may not be stable for production use.
Kuavo Humanoid SDK
一个用于控制 Kuavo 人形机器人的 Python SDK，提供了机器人状态管理、机械臂和头部控制以及末端执行器操作的接口, 它设计用于在 ROS 环境中工作。
警告: 该SDK目前仅支持ROS1。暂不支持ROS2。
特性
-
机器人状态管理
- IMU数据(加速度、角速度、欧拉角)
- 关节/电机状态(位置、速度、力矩)
- 躯干状态(位置、姿态、速度)
- 里程计信息
- 末端执行器状态:
- 夹爪(lejuclaw): 位置、速度、力矩、抓取状态
- 灵巧手(qiangnao): 位置、速度、力矩
- 触觉灵巧手(qiangnao_touch): 位置、速度、力矩、触觉状态
- 末端执行器位置和姿态
- 运动状态: 站立、行走、自定义单步控制
-
运动控制
- 手臂控制
- 关节位置控制
- 通过逆运动学(IK)的末端执行器6D控制
- 用于计算末端执行器位姿的正运动学(FK)
- 复杂动作的关键帧序列控制
- 末端执行器控制
- 夹爪控制(可配置速度和力矩的位置控制)
- 灵巧手控制
- 位置控制
- 预定义手势(OK、666、握拳等)控制
- 头部控制
- 位置控制
- 躯干控制
- 高度控制(下蹲)
- 前/后倾控制
- 动态运动控制
- 站立
- 踏步
- 行走(xy 和 yaw 偏航速度控制)
- 自定义单步控制
- 手臂控制
-
机器人基本信息
- 机器人类型(kuavo)
- 机器人版本
- 末端执行器类型
- 关节名称
- 总自由度(28)
- 手臂自由度(每臂7个)
- 头部自由度(2个)
- 腿部自由度(12个)
-
音频接口
- 播放指定的音频文件
- 停止播放音频
- TTS 文本合成音频
-
视觉接口
- 获取指定坐标系下的 AprilTag 检测数据
-
观测接口
- 获取机器人控制指令
-
搬箱子策略模块
- 查找 Apriltag
- 到达世界坐标系下的目标点位姿
- 搬箱子
- 放置箱子
安装
注意：目前SDK有两个版本，稳定版和测试版。它们的区别如下：
- 稳定版：对应 kuavo-ros-opensource 仓库
master分支提供的功能。 - 测试版：比官方版本更激进，也提供更丰富的功能，对应 kuavo-ros-opensource 仓库
beta分支提供的功能。
友情提醒：请明确您需要安装的版本。如果您的SDK版本与 kuavo-ros-opensource 不匹配，某些功能可能无法使用。
使用 pip 安装最新的 稳定版 Kuavo Humanoid SDK：
pip install kuavo-humanoid-sdk
可选功能依赖（按需安装）：
# 仅语音/ASR相关功能
pip install kuavo-humanoid-sdk[audio]
# 仅视觉/YOLO相关功能
pip install kuavo-humanoid-sdk[vision]
# 全量功能（包含音频 + 视觉依赖）
pip install kuavo-humanoid-sdk[full]
使用 pip 安装最新的 测试版 Kuavo Humanoid SDK：
pip install --pre kuavo-humanoid-sdk
对于本地开发安装（可编辑模式），请使用：
cd src/kuavo_humanoid_sdk
chmod +x install.sh
./install.sh
# 如需安装可选功能依赖：
# ./install.sh --extras audio
# ./install.sh --extras vision
# ./install.sh --extras full
版本升级
在升级版本之前，您可以使用以下命令查看当前安装的版本：
pip show kuavo-humanoid-sdk
# Output:
Name: kuavo-humanoid-sdk
Version: 1.1.6
...
提示：如果版本号包含字母 b，则表示是测试版，例如，Version: 0.1.2b113
从稳定版本更新到最新的稳定版本：
pip install --upgrade kuavo_humanoid_sdk
从测试版更新到最新的稳定版本：
pip install --upgrade --force-reinstall kuavo_humanoid_sdk
# or
pip uninstall kuavo_humanoid_sdk && pip install kuavo_humanoid_sdk
从测试版/稳定版更新到最新的测试版：
pip install --upgrade --pre kuavo_humanoid_sdk
安装包信息
您可以使用 pip 来查看包信息：
pip show kuavo-humanoid-sdk
快速开始
以下是一个简单的示例，用于快速使用 Kuavo Humanoid SDK：
警告: 在运行任何代码示例之前，请确保已经启动机器人， 否则 SDK 无法正常工作：
- 如果是命令行启动，则请确保类似下面的命令已经执行:
- 仿真模式:
roslaunch humanoid_controllers load_kuavo_mujoco_sim.launch(示例命令)- 真实机器人:
roslaunch humanoid_controllers load_kuavo_real.launch(示例命令)- 如果是 h12 遥控器等启动方式，也请确保已经让机器人启动(站立)
# 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()
文档
我们提供两种文档格式：
- HTML 格式: docs/html, 但是需要您自己在SDK目录下执行
gen_docs.sh脚本生成 - Markdown 格式: docs/markdown
您可以在 SDK 的源码目录下执行以下命令生成文档， 文档会输出到 docs/html 和 docs/markdown 文件夹中：
cd <kuavo-ros-opensource>/src/kuavo_humanoid_sdk
chmod +x gen_docs.sh
./gen_docs.sh
我们强烈推荐您阅读 html 文档， 因为它更适合阅读。
对于Markdown 文档， 请访问：
使用示例
警告: 在运行任何代码示例之前，请确保已经启动机器人， 否则 SDK 无法正常工作：
- 如果是命令行启动，则请确保类似下面的命令已经执行:
- 仿真模式:
roslaunch humanoid_controllers load_kuavo_mujoco_sim.launch(示例命令)- 真实机器人:
roslaunch humanoid_controllers load_kuavo_real.launch(示例命令)- 如果是 h12 遥控器等启动方式，也请确保已经让机器人启动(站立)
基本信息示例
一个获取机器人基本信息的示例。
运动控制示例
一个基本示例，用于初始化 SDK 并控制机器人运动。
末端执行器控制示例
LejuClaw 夹爪
展示如何控制 LejuClaw 夹爪末端执行器的示例，包括位置、速度和力矩控制。
QiangNao 灵巧手
展示如何控制 QiangNao 灵巧手的示例，这是一个具有多个自由度的灵巧机器人手，可用于复杂的操作任务。
手臂控制示例
展示手臂轨迹控制和目标姿态控制的示例。
手臂正向运动学和逆向运动学示例
展示如何使用正向运动学(FK)从关节角度计算末端执行器位置，以及如何使用逆向运动学(IK)计算实现期望末端执行器姿态所需的关节角度的示例。
头部控制示例
展示如何控制机器人头部运动的示例，包括点头(俯仰)和摇头(偏航)动作。
单步控制示例
展示如何控制机器人按照自定义落足点轨迹运动的示例。
许可证
本项目使用 MIT 许可证授权，详情信息请查看 LICENSE 文件。
联系与支持
如有任何问题、支持需求或错误报告，请通过以下方式联系我们：
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-1.4.5b829.tar.gz.
File metadata
- Download URL: kuavo_humanoid_sdk-1.4.5b829.tar.gz
- Upload date:
- Size: 358.3 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/6.1.0 CPython/3.8.10
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
a0e227c1880b5c2d18ae2d9f4dd34f012e02fb2670d7ca4406c385b9602f8dc0
|
|
| MD5 |
2bbcf8932298221ebbccd65ef02b2aed
|
|
| BLAKE2b-256 |
15a51c8eb8dedd83bc94a4e44f1ae0589d375c1bd2c02773ce3a895799e97daa
|
File details
Details for the file kuavo_humanoid_sdk-1.4.5b829-20260810120115-py3-none-any.whl.
File metadata
- Download URL: kuavo_humanoid_sdk-1.4.5b829-20260810120115-py3-none-any.whl
- Upload date:
- Size: 676.6 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 |
ac8e1f95f5b1583ec4c41dd2e07b20f902afd96a55a6a45f399c60814e5d70cb
|
|
| MD5 |
2b184d379bf59bafea318838df234521
|
|
| BLAKE2b-256 |
ccac241fcbcd20908058ef343863eb03571248c3759f144e8d5736cf3537a14c
|
File details
Details for the file kuavo_humanoid_sdk-1.4.5b829-20260810080720-py3-none-any.whl.
File metadata
- Download URL: kuavo_humanoid_sdk-1.4.5b829-20260810080720-py3-none-any.whl
- Upload date:
- Size: 676.6 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 |
bcd9d4c2d12388849de7f833f0f6a3fe1ad8408fbab0bfce876da648bec19b51
|
|
| MD5 |
4cf7e14af0cc939b6c59de22d4ba14d4
|
|
| BLAKE2b-256 |
48106fae5195160fd50e4be1bf78b749484fc0e291b5c2351ee0269bec044741
|
File details
Details for the file kuavo_humanoid_sdk-1.4.5b829-20260809104526-py3-none-any.whl.
File metadata
- Download URL: kuavo_humanoid_sdk-1.4.5b829-20260809104526-py3-none-any.whl
- Upload date:
- Size: 676.6 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 |
0dce8e84a7eade7e76edc9e05c56b67316dcd5aa0cfcff3d653e951882f699f2
|
|
| MD5 |
4e12591c12e640307ac97bccae122290
|
|
| BLAKE2b-256 |
0eab004452482fd01b544515a2188376084da12a1af523e49b33558eec069a8b
|
File details
Details for the file kuavo_humanoid_sdk-1.4.5b829-20260809081426-py3-none-any.whl.
File metadata
- Download URL: kuavo_humanoid_sdk-1.4.5b829-20260809081426-py3-none-any.whl
- Upload date:
- Size: 676.6 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 |
e020d6377661e3b223a10ff8426853f6fcd694954b97d024b2567e29fcbca294
|
|
| MD5 |
097227fde1e44f8007f46bbfd5fc8706
|
|
| BLAKE2b-256 |
dff997c1cca419bf0de75dc6b13ea11361d2659b5ace7d7e3127304e25c30956
|
File details
Details for the file kuavo_humanoid_sdk-1.4.5b829-20260808203601-py3-none-any.whl.
File metadata
- Download URL: kuavo_humanoid_sdk-1.4.5b829-20260808203601-py3-none-any.whl
- Upload date:
- Size: 676.6 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 |
bbe28d68bdbc476c5e1a7b144ea886e3691860998677026d07c2483cd58d2b00
|
|
| MD5 |
e240736e06eb779569cea1dc739bd816
|
|
| BLAKE2b-256 |
1591bc15ac7eb47c634db9f285cc994aa920e23314f30ab185bba2eab1e4007c
|
