启元 T1 机器人 SDK 探秘：安装配置、六种变形动作与双机型共存实测

摘要

启元有两台消费级机器人------Q1（纯双足）与 T1（轮足人形/四足变形）。两者的 SDK 包同名、同源、结构几乎一致，但 T1 的接口文档比 Q1 多出约 1200 行------多出的部分正是"变形"二字的接口实现：6 种形态切换动作（含双向前空翻）、一整套四足状态机。本文记录 T1 SDK 的完整探秘过程：编译实测（21左右秒，与 Q1 几乎一致）、一个"三周前能编译 Q1、今天编 T1 报错"的环境漂移坑、变形动作枚举的全家福验证、同名包覆盖的实锤测试，以及双机型 SDK 的隔离方案。全部验证脚本开源可复现。

**环境：**Windows 10 + WSL2 / Ubuntu 22.04.5 / ROS2 Humble / T1 SDK v1.0.0.0 / Q1 SDK v1.0.0.0 / setuptools 58.2.0

仓库： https://atomgit.com/capybarala/t1-sdk-lab

一、双机型 SDK 的第一天：编译坑点

T1 是启元的另一台消费级机器人，与纯双足的 Q1 不同，它支持轮足人形与四足形态切换。拿到 T1 SDK（v1.0.0.0）的第一件事照例是编译消息包。过程出乎意料地不顺：

cd ~/workspace/sdk_t1
source /opt/ros/humble/setup.bash
colcon build --packages-select aimdk_msgs --cmake-args -DCMAKE_BUILD_TYPE=Release

# TypeError 报错
# TypeError: canonicalize_version() got an unexpected keyword argument 'strip_trailing_zero'

aimdk_msgs 的 Python egg 构建直接崩了。同一个环境，三周前编译 Q1 SDK 一次通过 。排查后发现这是教科书级的"环境漂移"：之前我为了装 MuJoCo、Stable-Baselines3 等库，pip 把 setuptools 升到了 78.1.0。而 ROS2 Humble 的 ament 构建依赖旧版 setuptools 的 canonicalize_version****接口，新版里这个参数已被移除。

修复一行：

pip3 install --user "setuptools==58.2.0"
pip3 show setuptools # 查看 setuptools 版本

这里是我修 bug 时已经把 setuptools 降到 58.2.0，所以现在重编是一次通过；如果遇到相似的问题，可以尝试查看一下setuptools版本是否兼容。

重编：20.3 秒通过------与 Q1 的 21.7 秒几乎一致。两台机器人、两份 SDK，编译耗时一致到秒级，因为它们的消息包本来就是同一套代码。

注意点 ：ROS2（colcon/ament）与 pip 混用的环境里，任何一次 pip install 都可能悄悄升级 setuptools 等基础库、破坏构建链。固定关键包版本（或用 venv 隔离 pip 环境）是双保险。

二、T1 SDK 安装配置：完整流程

先补全"从零到可用"的安装配置（与 Q1 SDK 流程一致，唯路径与版本注意点不同），以下命令可直接照做：

# 1. 下载 T1 SDK（开发者社区下载页，约 13 MB）
cd ~/workspace
wget "https://csdn-tos.primebot.com/qiyuan/2026/10/10/2e3bb755cda84b37af425af186c54ea8.zip" -O sdk_t1.zip
unzip sdk_t1.zip        # 得到 sdk_t1-v1.0.0.0 目录

# 2. 依赖体检（关键！见第一节的环境漂移坑）
pip3 show setuptools | grep Version      # 需要 ≤ 58.x，否则降级：
pip3 install --user "setuptools==58.2.0" # 版本符合要求的话不用执行

# 3. 编译消息包
source /opt/ros/humble/setup.bash
cd ~/workspace/sdk_t1
colcon build --packages-select aimdk_msgs --cmake-args -DCMAKE_BUILD_TYPE=Release

# 4. 环境加载
source install/setup.bash
ros2 interface show aimdk_msgs/msg/McAction | grep FRONTFLIP

最后一步能看到 QUADRUPED_TO_BIPED_FRONTFLIP = 12 等枚举即安装成功。两个 T1 特有的注意点：

• 目录隔离 ：T1 与 Q1 的 SDK 不要解压到同一目录，建议分放 ~/workspace/sdk_t1 与 ~/workspace/sdk_q1；
• 环境互斥：同名包决定了同一终端只能"生效"一套 SDK------source 顺序的坑见第六节。

三、一套代码，两种机型：SDK diff 考古

编译通过后做了件更有意思的事：把 T1 与 Q1 两份 SDK 逐文件 diff，结果出乎意料：

• aimdk_msgs 消息包：仅 2 个文件不同 ------McAction.msg（枚举微调）与 FastDDS 环境钩子；
• examples/：约 10 个 Python 示例有细微差异，18 个示例的文件名完全一致；
• 差异最大的反而是文档：T1 的《接口说明.md》有 14,064 行，比 Q1 的 12,858 行多出约 1,200 行。

多出的 1200 行是什么？翻到运控模块的状态机章节，答案一目了然：一整套四足状态机 ------QUADRUPED_GET_DOWN_DEFAULT（四足趴下）、QUADRUPED_SIT_DOWN_DEFAULT（四足坐下）、QUADRUPED_STAND_DEFAULT（四足位控站立）、QUADRUPED_RECOVERY（四足恢复）......双足世界之外，T1 的文档里还住着一个完整的四足世界。

这就是启元 SDK 的架构决策：消息包双机型共用 （所以同名、所以编译耗时一致、所以 diff 几乎为空），机型差异全部收敛到状态机与文档层。对二开者的影响直接而具体：学会了 Q1 的接口，T1 的接口一节课就能上手------反之亦然。

四、变形的钥匙：六种形态切换动作

T1 的"变形"不是宣传语，是可以调用的接口。McAction 消息里登记了六种形态切换动作：

4.1 枚举验证：六个动作全部存在

|----------------------------------|--------|-------------|
| 动作 | 编号 | 说明 |
| QUADRUPED_TO_BIPED | 10 | 四足 → 双足（常规） |
| QUADRUPED_TO_BIPED_ROTATE | 11 | 带旋转变身 |
| QUADRUPED_TO_BIPED_FRONTFLIP | 12 | 前空翻变身 |
| BIPED_TO_QUADRUPED | 20 | 双足 → 四足 |
| BIPED_TO_QUADRUPED_ROTATE | 21 | 带旋转变回 |
| BIPED_TO_QUADRUPED_FRONTFLIP | 22 | 前空翻变回四足 |

逐个用 ros2 interface show 验证，全部存在（验证脚本已开源，一键复现）。最意外的是两个 FRONTFLIP：变形的过程可以带一个前空翻 ------四足趴下翻起身成双足，或双足翻个跟头变回四足。此外还发现了 QUADRUPED_LOCOMOTION_FRONTFLIP = 105：四足形态本身就有前空翻动作。

这些枚举是接口层的"预言"：Q1 的消息包里同样登记着这批四足动作（接口层双机型共用），Q1 自己用不上------它们是给 T1 准备的。读消息包，能读出一条产品线的规划。

4.2 核心功能调用：触发一次形态切换

枚举验证只是"存在性检查"，真正的核心功能是调用 。形态切换走的是通用动作服务 SetMcAction，把枚举值写进 command.action.value 即可（仓库 examples/set_transform.py，已开源）：

cli = self.create_client(SetMcAction, "/aimdk_5Fmsgs/srv/SetMcAction")
req = SetMcAction.Request()
req.header.stamp = self.get_clock().now().to_msg()
req.source = "transform_demo"
req.command.action.value = 10          # QUADRUPED_TO_BIPED：四足→双足
future = self.cli.call_async(req)

支持参数化选择全部六种变形（python3 set_transform.py 22 即触发前空翻变回四足）。两个使用要点：其一 ，变形动作要求 T1 处于对应起始形态（调 10 需当前是四足形态），运控层会按状态机校验；其二，无真机时这段代码照常运行------服务调用会因无运控应答而超时退出，这个"超时"反过来可以作为环境判据用。

T1 的六种形态切换动作：双向的常规/旋转/前空翻变形，外加四足本体的前空翻动作（105）------变形能力在接口层的完整落点。

五、同名包的战争：生效方不可靠，自检是唯一解

双机型共用消息包，代价也在这里：两个 SDK 的包都叫 aimdk_msgs。同一个终端里先后加载两套环境，哪套生效？

# 终端 A：source T1 → source Q1
python3 -c "import aimdk_msgs.msg as m; print(m.__file__)"
# 实测输出：.../sdk_t1/install/.../aimdk_msgs/msg/__init__.py   ← T1 版本生效！

# 终端 B：同样操作，不同的 source 历史
# 实测输出：.../sdk_q1/install/...   ← Q1 版本生效

同一个终端里查 AMENT_PREFIX_PATH，可以看到两套路径都在列表里，且排序规则完全可预测：source 是"插队到最前"（prepend）语义------谁后 source，谁的路径就排在查找队列最前面，谁就生效。本文实测的四组数据全部吻合这一机制：只 source T1 的终端 T1 生效；先 T1 后 Q1 的终端 Q1 生效；先 Q1 后 T1 的终端 T1 生效------无一例外。

在多终端多历史下，容易忘记哪个终端是哪套顺序 。你在 T1 终端里写的代码，拿到一个"最后 source 的是 Q1"的终端里跑，接口就对不上了------而且终端不会给你任何提示。可靠的做法只有自检，不要同一终端混淆开发

# 开发前跑一下看看环境
python3 -c "import aimdk_msgs.msg as m; print(m.__file__)"

输出路径指向哪套 SDK，当前生效的就是哪套。隔离方案也随之明确：日常开发用两个终端分别固定机型 ；必须在同一工程用两套接口时，把 source 顺序固化进启动脚本，并用自检命令做最终确认。

六、双状态机：接口文档里的四足世界

T1 文档多出的 1200 行，值得单独一节。Q1 的运控状态机是纯双足逻辑（被动/阻尼/站立/走跑/全身控制......），T1 的状态机在这之上叠加了四足分支：四足趴下、四足坐下、四足位控站立、四足恢复、四足基础运动......两套状态机通过六个变形动作互达。

对二开者的意义：写 T1 的控制逻辑，要先想清楚"它现在是什么形态"。形态不同，可用的动作集、控制接口、甚至能力边界都不同（比如轮足模式下的移动方式与四足完全两样）。接口文档里的状态机图把这条规则画得很清楚：变形动作是两套状态机之间仅有的几座桥。

另一个细节：T1 的 McAction 枚举里有一个 Q1 没有的 BIPED_NPZ_MIMIC = 304（NPZ 模仿动作）------两台机器人在模仿动作的支持上也有差异。这类"枚举级差异"只有逐文件 diff 才能发现，也正是双机型开发需要 diff 考古的原因。

T1 数字分身的两种形态（MuJoCo 渲染）：左侧四足姿态（默认）、右侧为摆拍出的"双足化"姿态预览。这不是物理仿真，而是用关节角摆出的姿态示意。真正的形态切换是硬件结构级的：四足模型上用关节角度摆不出双足站立，这正是"变形"作为 T1 硬件能力的仿真边界。

七、验证：一键脚本

本文的所有验证已脚本化。开源仓库里的 t1_verify.sh 一键完成四项体检：setuptools 版本体检、T1 消息包编译、变形枚举验证、同名包覆盖测试：

git clone https://atomgit.com/capybarala/t1-sdk-lab.git
cd t1-sdk-lab
bash t1_verify.sh

预期输出四段：编译 PASS、形态切换枚举 6 个 PASS、T1 特有枚举 PASS、覆盖测试实锤。脚本运行中还会撞到一个小坑：验证脚本里不能写 set -u------ROS 的 setup.bash 内部有未保护的变量展开，nounset 模式会直接报 unbound variable 崩掉。这是 ROS 脚本兼容性的老问题，记录在此。

一键验证脚本：编译、变形枚举、特有枚举、覆盖测试 四段全过*。*

八、总结：一套 SDK 战略的得与失

把 T1 SDK 从编译 到状态机 ，对启元"一套 SDK 服务双机型"的打法有了具体的判断。得 很清楚：消息包零冗余、双机型开发体验一致（编译耗时一致到秒级）、学会了 Q1 就等于学会了 T1 的接口语法；T1 的"变形"作为最高级的能力，在接口层的落点清晰（六个变形动作 + 四足状态机），不是宣传噱头。失也要说：同名包导致双机型环境必须人工隔离，对同时开发两台机器人的团队是个持续的纪律要求；文档差异（+1200 行四足内容）藏在各自的包里，官方没有提供双机型差异说明------本文的 diff 考古算是补上了这块。

T1 的形态切换（尤其是那两个前空翻变形）在接口层已经就绪。需要说明的一个实测边界：我们曾尝试在 MuJoCo 里用关节角把四足模型摆出双足站姿------摆不出来（形态是硬件结构级的，模型几何本身就是四足设计）；viewer 交互演示的行为也偏混沌（弹跳与自恢复交替）。形态切换的完整仿真演示，需要双形态模型或硬件级的变形描述，验证脚本与实测记录开源，可自取。

参考资料

1. 启元机器人开发者社区（T1/Q1 SDK 下载）：https://dev.primebot.com/
2. 启元机器人官方开源组织（AtomGit）：https://atomgit.com/primebot
3. 本文配套仓库 t1-sdk-lab：https://atomgit.com/capybarala/t1-sdk-lab
4. ROS 2 Humble 文档（环境叠加与包管理）：https://docs.ros.org/en/humble/

---