本文为「启元机器人 PGC 内容共建」架构解读方向投稿。全文基于 PrimebotTech 官方开源仓库与 dev.primebot.com 下载页的真实内容整理所有命令逐字引用官方 README / 快速入门文档参数以官方原文为准未公开的项一律标注【待确认】不做臆测。一、为什么需要一份开发者视角的架构拆解拿到一台启元 T1 或 Q1多数上手教程会直接教你下载 SDK、跑示例。但如果你打算做二次开发——无论是接一个自研视觉算法、写一段自定义步态还是把机器人接入自己的业务系统——你真正需要的是一张能映射到代码仓库的架构图哪一层负责驱动、哪一层开放了接口、仿真和真机之间如何对齐、编译产物最终落在哪里。启元机器人把上述能力拆成了开源仓库 桌面调试台 技能市场三套互补的体系并且全部放在 GitHub 与国内 AtomGit 双仓同步。本文的目的就是把这些散落在不同仓库、不同文档里的信息按硬件 → 固件/SDK → 仿真 → 工具链 → 技能市场的顺序串成一条开发者能照着走的路径。需要提前声明的两点事实边界自由度关节数量Q1 有官方数字——《启元Q1用户手册》第 19 页「参数规格」表列明全身自由度 22 DoF其中手臂 4 DoF×2、腰部 2 DoF旋转、侧摆、腿部 6 DoF×2821222 自洽。本文 §4.2.1 用 MuJoCo 实测官方模型得到 22 个驱动关节与手册数值吻合属两条独立证据互相印证。T1 的自由度官方手册未列出本文仅给出实测值15 个关节 / 14 个力矩电机属实测口径而非官方口径。构型差异官方下载页对 T1 的描述为四足/双足人形机器人而 T1 URDF V3.0 描述包明确写着四足机器人Q1 则被统一描述为双足人形机器人。因此本文把 Q1 定位为双足人形T1 定位为四足并保留双足人形形态以官方页面原文为准。二、整机分层架构五层映射到五个仓库图1 说明PrimebotTech 在 GitHub 的开源组织仓库列表。表中每一层对应的仓库都能在这里找到这也是本文架构分层的事实依据——分层不是笔者的归纳而是官方仓库的实际划分。先把全局架构铺开。下图把每一层对应到具体的官方仓库开发者看到某一层就能直接定位到 GitHub 上该 clone 哪个仓。图2 说明这张分层图不是概念图而是仓库地图——每一层都对应真实存在的官方仓库或工具。从下往上看硬件被 SDK 抽象成 ROS2 接口仿真用 URDF/MuJoCo 在虚拟环境验证工具链决定你在哪台机器上把代码编译成可部署产物最上层的 PrimeHub 则把成果打包成可上架的技能。逐层拆解如下① 硬件层机器人本体。Q1 与 T1 的计算平台均为大脑板 运控板架构官方工具链与下载页明确支持两类主控RK 平台与NVIDIA Jetson Orin平台RK 具体芯片型号【待确认】。机器人本体通过关节、相机、音频、BMS 等硬件抽象接口对外暴露能力开发者不必关心底层协议。② 固件 / ROS2 SDK 层。这是二次开发的核心入口。primebot-q1-sdk与primebot-t1-sdk的 README 开头即声明基于ROS2 FastDDS 去中心化架构统一通过 ROS2 接口即可控制机器人全部能力无需关心底层协议细节开发程序可灵活部署在 PC、运控板或大脑板上透明访问全量机器人能力接口。SDK 内部用aimdk_msgs消息包统一定义了 Agent 层、硬件抽象层HAL、交互层、运控层MC的消息与服务。两个 SDK 在官网下载页标注版本均为v1.0.0.0体积均为 13 MB。③ 仿真层。对应primebot-q1-urdf与primebot-t1-urdf官方下载页描述其为完整 URDF 描述包包含自由度连杆模型、STL 网格文件、MuJoCo XML 配置以及 ROS RViz/Gazebo 仿真 launch 文件适用场景包括运动学分析、运动规划及强化学习训练。版本标注为v1.0.0Q1 URDF 11 MBT1 URDF 17 MB。来源官方下载页仓库元信息与本地下载实测仓库目录结构包含config / launch / meshes / urdf / xml / tools与下载页描述一一对应。④ 工具链层。三个 Docker 编译环境仓库toolchain-arm-nativeARM 原生支持 RK/Orin、toolchain-x86-cross-armx86 主机交叉编译 ARM、toolchain-x86-nativex86 原生用于仿真测试或 x86 部署官网版本均为v1.0.0。官方 ARM 原生指南明确给出镜像体积参考RK 镜像约 2–5 GBOrin 镜像含 CUDA约 44.6 GB交叉编译镜像 RK 约 5.4 GB、Orin 约 44.6 GB。⑤ PrimeHub 技能市场。miracle-techlink/primehub_dev_kit提供从写技能到上架的完整链路是架构图里最上层的能力出口。三、Q1 与 T1 的定位差异双足人形 vs 四足图3 说明《启元Q1用户手册》参数规格页官方 PDF 第 19 页。认证型号 Q1AA2500、站立尺寸 88×39×18 cm、整机 16 kg、电池 215 Wh、续航 3 h、全身 22 自由度均为官方一手数据。很多开发者会同时关注 Q1 和 T1但两者的产品定位并不重叠。基于官方描述差异如下表与下图所示。图4 说明左右两张卡片对照了 Q1 与 T1 在官方仓库/下载页中的描述差异。二者共享同一套 SDK 接口范式ROS2 FastDDS和同一套仿真/工具链体系差异主要在本体构型与配套资源上Q1 明确为双足人形并提供 DIY 外壳 STEP 模型T1 描述为四足/双足人形当前 URDF V3.0 为四足形态且 SDK 示例里额外带了 OpenCV 4.13.0 源码包与 Ruckig 运动规划源码包。具体差异点构型。Q1 双足人形T1 四足/双足人形当前 URDF V3.0 为四足。这一条直接决定你做运动规划时的自由度拓扑。Q1 的自由度有官方手册口径22 DoF见开篇事实边界与 §4.2.1 实测T1 官方手册未列自由度本文只用实测值15 关节 / 14 电机请以官方后续发布的规格书为准。SDK 示例资源。T1 SDK 的examples/目录明确包含opencv/OpenCV 4.13.0 源码包需本机构建与ruckig_for_primebot/Ruckig 源码包供 C/Python 示例构建Q1 SDK 结构相同但下载页对 Q1 的强调点在 DIY 外壳。两者aimdk_msgs的消息分层agent / hal / interaction / mc完全一致。平台。两者都支持 RK 与 NVIDIA Jetson Orin工具链三件套通用不存在某机型只能用某工具链的限制。适用场景。下载页对 URDF 的描述一致运动学分析、运动规划、强化学习训练——这意味着 Q1 与 T1 在算法侧的研究工作流是相通的区别在真机形态。客观说明以上均为官方页面给出的描述本文未对任何第三方机器人产品做对比或评价仅陈述启元自家两条产品线的定位差异。四、开发者工作流从 URDF 仿真到 SDK 二次开发把架构落到第一天该做什么工作流可以分成四步下图是闭环示意。图5 说明四步工作流是实际可执行的开发顺序——先装环境再用 URDF 在仿真里验证逻辑然后用 SDK 写业务并编译最后上真机或借助 PrimeConsole / Docker 工具链调试部署仿真结果可回灌修正形成闭环。4.1 第一步装环境官方《快速入门与集成指南》明确推荐的开发环境为Ubuntu 22.04.x LTSROS2 发行版为ROS2 Humble并注明暂不支持 Mac/Windows。基础依赖安装命令逐字引用官方文档sudo apt update sudo apt install -y \ python3-colcon-common-extensions \ python3-dev \ python3-pip \ ros-humble-rosidl-default-generators \ ros-humble-rosidl-default-runtime环境检查命令逐字引用lsb_release -d echo $ROS_DISTRO pip3 show colcon-core将 ROS2 环境写入~/.bashrc逐字引用if ! grep -q source /opt/ros/humble/setup.bash ~/.bashrc; then echo source /opt/ros/humble/setup.bash ~/.bashrc fi source ~/.bashrc复现仓库规则第 2 条本文涉及的全部示例工程已上传至 AtomGit 公开仓库https://atomgit.com/azhiqiu/primebot-q1-t1-mujoco-repro 。仓库含 4 个可运行脚本render_sim.py/q1_motion_seq.py/viewer_shot.py/find_t1_stance.py、示例渲染图与requirements.txt按 README 指引下载官方 URDF 包后可直接复现本文所有实测数据。4.2 第二步仿真验证在写真机代码前先用 URDF 在 RViz / Gazebo 里验证运动学与轨迹是降低真机调试风险的关键。下载并解压对应 URDF 包primebot-q1-urdf或primebot-t1-urdf其launch/目录提供了 ROS RViz/Gazebo 的 launch 文件meshes/提供 STL 网格xml/提供 MuJoCo XMLconfig/存放关节限位与控制器参数urdf/则是连杆与关节的拓扑定义。对开发者而言这套目录就是机器人的数字孪生你可以在urdf/里确认每个关节的名字与父子关系在meshes/里核对外形在launch/里一键拉起可视化再在 MuJoCoxml/里做接触动力学与强化学习训练。正因为 URDF 与 SDK 共用同一套关节命名仿真里验证过的轨迹理论上可以直接映射到真机的aimdk_msgs/mc运控接口。不过静态渲染图只能证明模型能加载真正调参时用的是交互式调试窗口见 §4.2.2。4.2.1 仿真实测用 MuJoCo 加载 Q1/T1 官方模型为了验证URDF/XML 就是数字孪生这个说法笔者用 MuJoCo 对官方资源包做了实测在不连接任何真机的情况下仅凭资料包里的模型文件完成加载与渲染。实测环境与版本如下组件版本说明Python3.13.12官网安装包mujoco3.17.0pip install mujocoPython 绑定numpy2.5.4依赖自动安装Q1 模型q1_v3.xmlURDF 包 v1.0.0自带地面、光照与statistic场景配置T1 模型scene_plane.xmlURDF 包 v1.0.0通过include引用 T1-V2.xml 机体实测加载结果脚本运行时打印Q1 为 23 个关节、29 维广义坐标nq29其中 22 个驱动关节恰好对应官方手册标称的 22 DoF29 维广义坐标减去浮动基座占用的 7 维无执行器定义nu0纯运动学/动力学模型T1 为 15 个关节、14 个电机nu14力矩执行器增益参数为 1需外接 PD 控制器才能稳定站立。以下截图均由 MuJoCo 离屏渲染器1280×960生成脚本与复现步骤见文末工程仓库图6 说明Q1 官方模型初始姿态渲染。腿部每侧 6 自由度hip pitch/roll/yaw、knee、ankle pitch/roll、腰部 2 自由度旋转、侧摆、手臂每侧 4 自由度——821222与官方手册「全身自由度 22 DoF」逐项对得上。网格地面与阴影由 XML 中预置的光照定义产生。图7 说明Q1 上半身特写。头部、肩部串联的 pitch/roll/yaw 三轴关节与肘部、腕部偏航关节清晰可辨这与 SDK 运控接口中的关节命名一一对应。图8 说明T1 官方模型初始姿态。T1 以趴姿作为初始状态scene_plane.xml场景机体为浅蓝色外壳四肢为白色连杆与 URDF 中 FL/FR/RL/RR 四条腿各 3–4 个关节的定义一致。图9 说明T1 机体特写。可观察髋关节 roll/pitch、膝关节的串联结构以及黄色透明材质的足端连杆。实测结论官方 XML 模型开箱即用——无需修改路径、无需额外资产MjModel.from_xml_path一次加载成功渲染缓冲默认 640×480需在脚本中设置model.vis.global_.offwidth/offheight才能输出高清图这是唯一需要踩的坑。这套模型可以直接作为强化学习训练与轨迹验证的基础与 §4.2 的 ROS RViz/Gazebo 路径互为补充。复现说明上述关节数来自脚本实测打印可复现自由度口径以官方手册为准Q1 手册为 22 DoF。渲染脚本与环境版本见文末工程仓库。4.2.2 交互式调试把 MuJoCo 原生 Viewer 跑起来离屏渲染适合出图调关节限位、看接触点、逐帧查轨迹时要用交互式窗口。MuJoCo 的 Python 绑定自带被动模式 Viewer最小代码如下import mujoco, mujoco.viewer # viewer 是子模块必须单独 import import numpy as np model mujoco.MjModel.from_xml_path(q1_v3.xml) data mujoco.MjData(model) viewer mujoco.viewer.launch_passive(model, data, show_left_uiTrue, show_right_uiTrue) # 默认相机按 statistic 的 center/extent 取景细长机体容易跑偏手动对准 viewer.cam.lookat[:] np.array(model.stat.center) [0, 0, 0.1] viewer.cam.distance max(float(model.stat.extent) * 2.6, 1.6) viewer.cam.azimuth 145 viewer.cam.elevation -14 while viewer.is_running(): mujoco.mj_step(model, data) viewer.sync()三个实测踩到的点按遇到顺序说只写import mujoco会报AttributeError: module mujoco has no attribute viewer——viewer是独立子模块且依赖 GLFWpip install mujoco会一并装上若报缺 glfw补装glfw即可。相机需要手动设。Q1 站姿约 0.88 m 高默认distance取extent会退得太远机身只占画面中间一小块上面那三行把注视点抬到躯干、距离压到extent × 2.6取景才正常。Q1 的nu0模型里没有执行器直接mj_step会因为重力自由落体。演示关节运动时应当直接写data.qpos[...]再调mujoco.mj_forward()走运动学而不是靠data.ctrl。窗口打开后左侧是 File / Option / Simulation / Window / Help 标签栏下方依次为 Info仿真时间、步长、每步耗时、Sensor、Control右侧是 Rendering、Group enable、Joint、Actuator 一类可视化开关。调轨迹时最常按的是 Simulation 里的 Pause 与 Step——逐帧看足端接触比翻日志快得多。图10 说明Q1 在 MuJoCo 原生 Viewer 中的调试界面。左侧标签栏下方为 Info/Sensor/Control 面板右侧为可视化开关区中间 3D 视口显示 Q1 站立姿态与网格地面。注意标题栏显示的模型名为q1_v3即 XML 中mujoco model...的定义值。图11 说明向left/right_shoulder_pitch、shoulder_roll、elbow_pitch六个关节写入按正弦曲线插值的目标角度幅值受官方range限位裁剪Viewer 中 Q1 双臂连续摆动。这种写 qpos 前进仿真的方式正是验证关节命名与正负方向是否与 SDK 一致的最快办法——命名对不上动作就会往反方向走。图12 说明T1 的调试窗口。这里有个值得记一笔的细节标题栏模型名为QD1 scenemesh而不是 T1——官方scene_plane.xml里写的是mujoco modelQD1 scenemesh说明这份场景文件是从另一型号沿用的跨机型共用。T1 与 Q1 的另一个实测差异在驱动方式T1 的nu14是纯力矩电机gainprm1内部不带 PD要让它在仿真里站住得在循环里自己算力矩tau kp*(q_target - q) - kd*qdot写进data.ctrl直接给目标角度无效。官方资料包给出的 URDF/XML 是能直接进 MuJoCo 的而 MuJoCo 的交互式 Viewer 又是免费的、跨平台的、不需要真机的调试入口。对没有 T1 Pro 在手的开发者这条路径是唯一能低成本验证关节命名、限位、运动方向三件事的办法——而这三项恰好是后面写 SDK 运控代码时最容易出错的地方。4.3 第三步SDK 二次开发图13 说明primebot-q1-sdk 仓库页面。SDK 以 ROS2 包形式发布aimdk_msgs定义消息与服务examples/下给出 Python 与 C 两版示例。编译 SDK 的核心命令逐字引用官方《快速入门与集成指南》tar -xzf primebot_sdk.tar.gz cd primebot_sdk colcon build --cmake-args -DCMAKE_BUILD_TYPERelease每次新终端需加载编译产物环境逐字引用source /path/to/your/primebot_sdk/install/setup.bash运行官方示例逐字引用# Python 示例 python3 examples/python/demo.py # C 示例 ros2 run aimdk_examples_cpp demo用 ROS2 原生命令做接口验证是确认节点可见、数据通的最快方式逐字引用ros2 node list ros2 topic list # BMS 状态接收验证 timeout 5 ros2 topic echo /aima/hal/bms/state --once # TTS 语音播报验证 ros2 service call /aimdk_5Fmsgs/srv/PlayTts aimdk_msgs/srv/PlayTts \ {header: {}, tts_req: {text: 你好我是启元机器人, priority_level: {value: 6}, domain: sdk_test, is_interrupted: true}}注意官方文档提示若未持久化内核 UDP 缓冲区参数每次新终端执行 ROS 命令前需先调整逐字引用sudo sysctl -w net.core.rmem_max25165824 sudo sysctl -w net.core.wmem_max251658244.4 第四步调试与部署真机调试有两种路径。其一是直接用官方桌面调试台PrimeConsole1.0.3 实测见 §4.4.1其二是用 Docker 工具链在目标板编译部署。ARM 原生编译的关键命令逐字引用toolchain-arm-native文档# 启动容器RK sudo docker run -it --rm --nethost -v ~/workspace:/workspace -w /workspace native-aarch64-rk bash # 容器内编译 cd sdk_q1 colcon build cd ../sdk_t1 colcon build4.4.1 PrimeConsole 1.0.3 实测装得起来但连不上真机PrimeConsole 是官方桌面调试台。2026-10-28 放出的 1.0.3 版提供 Windows.exe237,803,340 字节、macOSIntel / Apple 芯片两个 dmg与 Linuxdeb239,217,122 字节三平台包都从 dev.primebot.com/download 取。Windows 包是 NSIS 封装的 Electron 应用解包后能看到resources/app.asar378,822,526 字节以及自带的 ffmpeg / mediamtx 二进制——结合主进程代码里ffmpeg -rtsp_transport tcp … -f mpegts的命令行可以确认实时视频流是本地 ffmpeg 拉 RTSP、转 HLS 再喂给渲染层的不是云端转发。在本机Windows跑通的完整流程是这样的PrimeConsole-Windows-1.0.3.exe /S /D路径可静默安装到指定盘默认会落到%LOCALAPPDATA%\Programs。启动后先到「Prime Console · 登录」手机号 短信验证码勾协议后进主界面。没有游客模式也没有跳过登录。一级导航只剩两个「机器人控制」和「Skill 验证」右上角固定挂着连接状态、「连接机器人」、「系统设置」、「登出」。有个和官方宣传对不上的地方值得记一笔下载页写的六大模块 ①–⑥是功能罗列不是软件里的菜单编号。1.0.3 把这些功能全折叠进了「机器人控制」这一页——上方是连接卡片内嵌日志 / 摘要 / JSON三个视图切换中间是实时视频位与语音 TTS下方并排摆着动作库和表情库。写文档时如果照抄下载页的编号去指路读者是找不到对应菜单的。图14 说明未绑定真机时的 PrimeConsole 1.0.3 主界面实机截屏。左上角连接卡片显示未连接、日志区暂无连接日志中部视频位尚未获取图像下方动作库、表情库均显示0 项。这张空状态图本身就是一条有用结论动作库、表情库、视频流、遥测日志四项数据全部依赖真机在线纯仿真环境拿不到。图15 说明连接卡片的「日志」视图。未连接时面板保持暂无连接日志旁边还有「摘要」「JSON」两个视图设计上是给连接态的遥测做结构化展示的空载状态下三者都是空面板——这正是判断设备是否真的在线的第一手依据。图16 说明连接卡片的「摘要」视图未连接时只显示未连接机器人一行字。这个视图在连接态下本应聚合设备型号、固件版本、在线时长等结构化摘要是排查机器人到底什么状态时最先看的面板。图17 说明连接卡片的「JSON」视图面向程序化调用方直接输出原始遥测字段。空载状态下同样无数据可吐——三个视图共用一套数据源进一步印证遥测数据完全由真机侧推送。图18 说明「Skill 验证」页。这是把本地技能推到机器人上跑验证的入口与 PrimeHub 技能市场是上下游关系PrimeHub 负责上架分发PrimeConsole 负责上机前验证。4.4.2 真机门槛SN 码 云端授权校验点「连接机器人」弹出设备选择框没绑定过设备时直接提示暂无设备请先在「设置 → 机器人配置」中添加设备。顺着指引进「系统设置 → 机器人配置 → 添加设备」要求填机器人 SN 码示例格式T1-2024-0052并明确写着PrimeConsole 将向启元机器人校验资产与授权状态。图19 说明设备选择弹窗。设备列表来自账户下已绑定的资产为空时只能先去系统设置添加无法临时直连 IP。图20 说明添加设备需要机身铭牌上的 SN 码提交后由启元云端校验资产与授权。结论很直接——没有真机或真机未授权的开发者动作库和表情库永远是 0 项。这也解释了为什么下面要换一条离线路径来做动作验证。图21 说明「系统设置 → 机器人配置」页“我的设备列表为空提示点击右上角「添加设备」开始”。这是整个真机链路的起点没有这一步录入 SN后面所有依赖设备在线的功能都无从谈起。4.4.3 离线替代方案直接回放 PrimeConsole 内置的动作包连不上真机还有一条更可复现的路子PrimeConsole 安装包里本来就带了一整套机器人资源位置在resources/app.asar解包后的dist/appres-pro/q1_v2/urdf/q1_v2.urdf——Q1 官方 URDF。MuJoCo 3.17 直接加载后得到22 个转动关节、nq 22无浮动基座。对照开源仓那版 q1_v3 的 23 关节 / 29 个广义坐标多出来的 7 维正好是浮动基座两者自洽。preset-actions-q1/index.json——count: 115分 14 类上传上肢动作包 29、对话表达类 15、社交礼仪类 14、情绪反馈类 13、娱乐与生活模仿类 7、思考认知类 7、任务反馈与指引类 7、原厂预设 8、运动模仿类 3、内部播报动作 3、灵创捕捉 5、拖拽示教 2、音乐舞蹈类 1、闲时状态类 1按显示名去重后剩 111 条。preset-actions-q1/motions/*.csv——120 fps 的原始关节角轨迹表头是关节名单位弧度。上半身包固定 10 列waist_roll / waist_yaw 双侧shoulder_pitch/roll/yaw 双侧elbow跟 URDF 里的关节名逐字对得上。既然列名和 qpos 一一对应就可以把 CSV 直接灌进 MuJoCo 的关节角、逐帧mj_forward再离屏渲染得到官方动作的确定性回放——不联网、不依赖真机、任何人拿到安装包都能复现import mujoco, numpy as np model mujoco.MjModel.from_xml_path(q1_v2.urdf) # 22 个转动关节 model.vis.global_.offwidth 1000 # 默认离屏缓冲只有 640×480 model.vis.global_.offheight 800 # 不放大会在 Renderer 构造时就抛 ValueError data mujoco.MjData(model) data.qpos[model.jnt_qposadr[joint_index]] angle_rad # CSV 列 → qpos mujoco.mj_forward(model, data) renderer.update_scene(data, cameracam) img renderer.render()上面是核心片段renderer/joint_index/cam的构造与逐帧循环已略。完整可运行脚本已按征文规则第 2 条上传至 AtomGit 公开仓库https://atomgit.com/azhiqiu/primebot-q1-t1-mujoco-repro 脚本位于仓库scripts/目录克隆后按 README 配置即可运行。回放了官方动作包里四类典型动作参数实测如下帧数按 120 fps 计。数据来源官方动作包 preset-actions-q1 内的关节轨迹 CSV采样率 120 fps时长与帧数为笔者逐条统计所得可用本文工程脚本复现。动作编号 / 分类时长帧数招手3001原厂预设4.00 s480握手3002上传上肢动作包6.67 s800上半身舞蹈 13046原厂预设5.17 s620随意摇摆FB-DAN-001音乐舞蹈类8.19 s983图22 说明原厂预设招手30014.00 s / 480 帧六帧等间隔回放。可以看到右肩 roll 外展、右肘收拢后小臂做往复摆动左臂保持自然下垂——CSV 里左臂那 5 列全程几乎不变与波形图图26一致。图23 说明“握手”30026.67 s / 800 帧六帧回放 。右臂前伸到体前偏右后小幅度上下摆动躯干基本不动。这类动作只动上半身 10 个关节下半身 12 个关节全程保持零位——也就是说官方动作包是上半身动作库不包含步态。图24 说明“上半身舞蹈 1”30465.17 s / 620 帧六帧回放。双臂交替上举配合腰 yaw 小幅扭转是周期性强、幅度大的一类很适合拿来验证关节限位有没有被撞到。图25 说明音乐舞蹈类随意摇摆FB-DAN-0018.19 s / 983 帧六帧回放是本组里时长最长、躯干参与最多的一个。注意它的scope字段是FBfull body但实际 CSV 仍然只有 10 个上半身关节列——字段口径与数据口径不一致引用时以 CSV 实际列数为准。图26 说明四个动作的关节角-时间曲线横轴秒、纵轴弧度直接读自 120 fps 原始 CSV未做平滑。从上到下能看出四类动作的指纹差异招手是右肘单关节高频往复握手是右肩 pitch 的一次慢速单向抬放舞蹈是右肘与右肩 pitch 的反相周期振荡随意摇摆则是腰 yaw 与右肩 roll 的低频大幅摆动。这类曲线可以直接拿来做动作分类或异常检测的特征。把 §4.2.1 的自建 MuJoCo 渲染和这一节的官方动作回放放在一起看能得出一条对开发者更实际的结论启元的官方 URDF 官方动作 CSV 是解耦的——URDF 描述本体CSV 只描述关节角随时间的取值两者靠关节名对齐。这意味着你可以在不碰真机的前提下把动作时序、关节限位、周期特征这些逻辑先在仿真里验完再等真机到位做标定。五、开源生态盘点双仓同步与 PrimeHub 技能市场图27 说明启元机器人在 AtomGit 的组织主页与 GitHub 双仓同步。征文规则要求示例工程上传 AtomGit这里就是最终要落地的位置。启元的开源资产分布在两个地方GitHub 组织PrimebotTech12 个公开仓库与国内AtomGit 组织PrimebotTech同内容加速镜像。下表是仓库职责一览。图28 说明仓库地图把前文提到的所有仓库按职责归类。核心开发四件套q1/t1 SDK q1/t1 URDF是二次开发的必装项三个 toolchain 仓库解决在哪编译PrimeHub dev kit 解决如何上架。mjlab / primebot_rl_mjlab / SuperMimic 三个仓库 README 未给出明确用途描述本文标注【待确认】。PrimeHub 技能开发包miracle-techlink/primehub_dev_kit它把写机器人技能标准化成了可复现的链路。其 README 给出的快速开始自检命令逐字引用python3 primehub_publish.py search 你好 # 自检能搜 网络和传输层 OK官方定义的技能开发顺序是逐字引用 README注册 PrimeHub → 给 AI agent 喂机器人契约 → vibe coding 改示例 → 打包 .rpk → 真机调试 → 提取登录 token → 一条命令发布上架环境要求逐字引用Python 3 pip install gmssl、curl、sshpass、一台同网段的 Q1/T1 机器人SSHrun、本机 Firefox用于 PrimeHub 登录态发布凭证自动提取。仓库内example-jukebox/是一个已上架的真实案例点歌台开发者可复制成自己的技能再改pack.py负责把技能目录打包成.rpkdeploy_test.py负责真机调试primehub_publish.py是发布/删除/查询客户端。客观评价PrimeHub 把算法能力封装为可上架的技能.rpk与底层 ROS2 SDK 形成底层接口 上层应用市场的两层结构开发者既可以深入 SDK 写硬核控制也可以在上层用 AI agent 快速产出技能。这种分层对生态建设是清晰的。关于mjlab、primebot_rl_mjlab、SuperMimic、GMR四个仓库GMR的 GitHub 描述为机器人数据重定向适配 Q1其余三个仓库的 README 在抓取时未提供明确用途说明已知 mjlab / primebot_rl_mjlab 与 MuJoCo/强化学习相关、SuperMimic 为 MIT 协议 Python 项目其具体定位【待确认】建议以仓库后续文档为准。六、给想上手的开发者的第一步建议把全文收敛成可执行的第一天清单先定机型再 clone。双足人形选 Q1四足/双足人形选 T1两者 SDK 接口范式一致可共用学习成本。装 Ubuntu 22.04 ROS2 Humble用 §4.1 的命令把基础依赖与colcon跑通。先用 URDF 在仿真里跑通关节运动再碰真机——这步能把 80% 的运动学错误挡在真机之前。用官方示例demo.py/demoC验证 ROS2 节点可见、topic/service 通再写自己的业务逻辑。编译产物走 Docker 工具链x86 主机用toolchain-x86-cross-arm交叉编译目标板直接用toolchain-arm-native原生编译二者镜像与命令官方已给全。想做可分发的能力走 PrimeHub用primehub_dev_kit从example-jukebox改起打包.rpk上架。复现材料本文用到的渲染与回放脚本render_sim.py/q1_motion_seq.py/viewer_shot.py/find_t1_stance.pyhttps://atomgit.com/azhiqiu/primebot-q1-t1-mujoco-repro 克隆即可复现本文所有命令均来自官方 README请以你下载时的最新版本号为准。最后强调事实边界Q1 的 22 DoF 有官方手册与模型实测两方印证见 §1 与 §4.2.1可以当确定参数用T1 的自由度数量、主控 RK 平台的具体芯片型号、以及 mjlab 等研究型仓库的用途官方当前未公开或文档未覆盖本文已逐项标注【待确认】请勿把这些待确认项当作确定参数使用。本文涉及的 开发资料可通过 启元机器人开发者社区 查阅。欢迎大家交流 
长河君 · 2026/11/4 16:34:57 · 阅读 1.2k 从 URDF 到 SDK：开发者视角拆解启元 T1/Q1 机器人架构
本文为「启元机器人 PGC 内容共建」架构解读方向投稿。全文基于 PrimebotTech 官方开源仓库与 dev.primebot.com 下载页的真实内容整理所有命令逐字引用官方 README / 快速入门文档参数以官方原文为准未公开的项一律标注【待确认】不做臆测。一、为什么需要一份开发者视角的架构拆解拿到一台启元 T1 或 Q1多数上手教程会直接教你下载 SDK、跑示例。但如果你打算做二次开发——无论是接一个自研视觉算法、写一段自定义步态还是把机器人接入自己的业务系统——你真正需要的是一张能映射到代码仓库的架构图哪一层负责驱动、哪一层开放了接口、仿真和真机之间如何对齐、编译产物最终落在哪里。启元机器人把上述能力拆成了开源仓库 桌面调试台 技能市场三套互补的体系并且全部放在 GitHub 与国内 AtomGit 双仓同步。本文的目的就是把这些散落在不同仓库、不同文档里的信息按硬件 → 固件/SDK → 仿真 → 工具链 → 技能市场的顺序串成一条开发者能照着走的路径。需要提前声明的两点事实边界自由度关节数量Q1 有官方数字——《启元Q1用户手册》第 19 页「参数规格」表列明全身自由度 22 DoF其中手臂 4 DoF×2、腰部 2 DoF旋转、侧摆、腿部 6 DoF×2821222 自洽。本文 §4.2.1 用 MuJoCo 实测官方模型得到 22 个驱动关节与手册数值吻合属两条独立证据互相印证。T1 的自由度官方手册未列出本文仅给出实测值15 个关节 / 14 个力矩电机属实测口径而非官方口径。构型差异官方下载页对 T1 的描述为四足/双足人形机器人而 T1 URDF V3.0 描述包明确写着四足机器人Q1 则被统一描述为双足人形机器人。因此本文把 Q1 定位为双足人形T1 定位为四足并保留双足人形形态以官方页面原文为准。二、整机分层架构五层映射到五个仓库图1 说明PrimebotTech 在 GitHub 的开源组织仓库列表。表中每一层对应的仓库都能在这里找到这也是本文架构分层的事实依据——分层不是笔者的归纳而是官方仓库的实际划分。先把全局架构铺开。下图把每一层对应到具体的官方仓库开发者看到某一层就能直接定位到 GitHub 上该 clone 哪个仓。图2 说明这张分层图不是概念图而是仓库地图——每一层都对应真实存在的官方仓库或工具。从下往上看硬件被 SDK 抽象成 ROS2 接口仿真用 URDF/MuJoCo 在虚拟环境验证工具链决定你在哪台机器上把代码编译成可部署产物最上层的 PrimeHub 则把成果打包成可上架的技能。逐层拆解如下① 硬件层机器人本体。Q1 与 T1 的计算平台均为大脑板 运控板架构官方工具链与下载页明确支持两类主控RK 平台与NVIDIA Jetson Orin平台RK 具体芯片型号【待确认】。机器人本体通过关节、相机、音频、BMS 等硬件抽象接口对外暴露能力开发者不必关心底层协议。② 固件 / ROS2 SDK 层。这是二次开发的核心入口。primebot-q1-sdk与primebot-t1-sdk的 README 开头即声明基于ROS2 FastDDS 去中心化架构统一通过 ROS2 接口即可控制机器人全部能力无需关心底层协议细节开发程序可灵活部署在 PC、运控板或大脑板上透明访问全量机器人能力接口。SDK 内部用aimdk_msgs消息包统一定义了 Agent 层、硬件抽象层HAL、交互层、运控层MC的消息与服务。两个 SDK 在官网下载页标注版本均为v1.0.0.0体积均为 13 MB。③ 仿真层。对应primebot-q1-urdf与primebot-t1-urdf官方下载页描述其为完整 URDF 描述包包含自由度连杆模型、STL 网格文件、MuJoCo XML 配置以及 ROS RViz/Gazebo 仿真 launch 文件适用场景包括运动学分析、运动规划及强化学习训练。版本标注为v1.0.0Q1 URDF 11 MBT1 URDF 17 MB。来源官方下载页仓库元信息与本地下载实测仓库目录结构包含config / launch / meshes / urdf / xml / tools与下载页描述一一对应。④ 工具链层。三个 Docker 编译环境仓库toolchain-arm-nativeARM 原生支持 RK/Orin、toolchain-x86-cross-armx86 主机交叉编译 ARM、toolchain-x86-nativex86 原生用于仿真测试或 x86 部署官网版本均为v1.0.0。官方 ARM 原生指南明确给出镜像体积参考RK 镜像约 2–5 GBOrin 镜像含 CUDA约 44.6 GB交叉编译镜像 RK 约 5.4 GB、Orin 约 44.6 GB。⑤ PrimeHub 技能市场。miracle-techlink/primehub_dev_kit提供从写技能到上架的完整链路是架构图里最上层的能力出口。三、Q1 与 T1 的定位差异双足人形 vs 四足图3 说明《启元Q1用户手册》参数规格页官方 PDF 第 19 页。认证型号 Q1AA2500、站立尺寸 88×39×18 cm、整机 16 kg、电池 215 Wh、续航 3 h、全身 22 自由度均为官方一手数据。很多开发者会同时关注 Q1 和 T1但两者的产品定位并不重叠。基于官方描述差异如下表与下图所示。图4 说明左右两张卡片对照了 Q1 与 T1 在官方仓库/下载页中的描述差异。二者共享同一套 SDK 接口范式ROS2 FastDDS和同一套仿真/工具链体系差异主要在本体构型与配套资源上Q1 明确为双足人形并提供 DIY 外壳 STEP 模型T1 描述为四足/双足人形当前 URDF V3.0 为四足形态且 SDK 示例里额外带了 OpenCV 4.13.0 源码包与 Ruckig 运动规划源码包。具体差异点构型。Q1 双足人形T1 四足/双足人形当前 URDF V3.0 为四足。这一条直接决定你做运动规划时的自由度拓扑。Q1 的自由度有官方手册口径22 DoF见开篇事实边界与 §4.2.1 实测T1 官方手册未列自由度本文只用实测值15 关节 / 14 电机请以官方后续发布的规格书为准。SDK 示例资源。T1 SDK 的examples/目录明确包含opencv/OpenCV 4.13.0 源码包需本机构建与ruckig_for_primebot/Ruckig 源码包供 C/Python 示例构建Q1 SDK 结构相同但下载页对 Q1 的强调点在 DIY 外壳。两者aimdk_msgs的消息分层agent / hal / interaction / mc完全一致。平台。两者都支持 RK 与 NVIDIA Jetson Orin工具链三件套通用不存在某机型只能用某工具链的限制。适用场景。下载页对 URDF 的描述一致运动学分析、运动规划、强化学习训练——这意味着 Q1 与 T1 在算法侧的研究工作流是相通的区别在真机形态。客观说明以上均为官方页面给出的描述本文未对任何第三方机器人产品做对比或评价仅陈述启元自家两条产品线的定位差异。四、开发者工作流从 URDF 仿真到 SDK 二次开发把架构落到第一天该做什么工作流可以分成四步下图是闭环示意。图5 说明四步工作流是实际可执行的开发顺序——先装环境再用 URDF 在仿真里验证逻辑然后用 SDK 写业务并编译最后上真机或借助 PrimeConsole / Docker 工具链调试部署仿真结果可回灌修正形成闭环。4.1 第一步装环境官方《快速入门与集成指南》明确推荐的开发环境为Ubuntu 22.04.x LTSROS2 发行版为ROS2 Humble并注明暂不支持 Mac/Windows。基础依赖安装命令逐字引用官方文档sudo apt update sudo apt install -y \ python3-colcon-common-extensions \ python3-dev \ python3-pip \ ros-humble-rosidl-default-generators \ ros-humble-rosidl-default-runtime环境检查命令逐字引用lsb_release -d echo $ROS_DISTRO pip3 show colcon-core将 ROS2 环境写入~/.bashrc逐字引用if ! grep -q source /opt/ros/humble/setup.bash ~/.bashrc; then echo source /opt/ros/humble/setup.bash ~/.bashrc fi source ~/.bashrc复现仓库规则第 2 条本文涉及的全部示例工程已上传至 AtomGit 公开仓库https://atomgit.com/azhiqiu/primebot-q1-t1-mujoco-repro 。仓库含 4 个可运行脚本render_sim.py/q1_motion_seq.py/viewer_shot.py/find_t1_stance.py、示例渲染图与requirements.txt按 README 指引下载官方 URDF 包后可直接复现本文所有实测数据。4.2 第二步仿真验证在写真机代码前先用 URDF 在 RViz / Gazebo 里验证运动学与轨迹是降低真机调试风险的关键。下载并解压对应 URDF 包primebot-q1-urdf或primebot-t1-urdf其launch/目录提供了 ROS RViz/Gazebo 的 launch 文件meshes/提供 STL 网格xml/提供 MuJoCo XMLconfig/存放关节限位与控制器参数urdf/则是连杆与关节的拓扑定义。对开发者而言这套目录就是机器人的数字孪生你可以在urdf/里确认每个关节的名字与父子关系在meshes/里核对外形在launch/里一键拉起可视化再在 MuJoCoxml/里做接触动力学与强化学习训练。正因为 URDF 与 SDK 共用同一套关节命名仿真里验证过的轨迹理论上可以直接映射到真机的aimdk_msgs/mc运控接口。不过静态渲染图只能证明模型能加载真正调参时用的是交互式调试窗口见 §4.2.2。4.2.1 仿真实测用 MuJoCo 加载 Q1/T1 官方模型为了验证URDF/XML 就是数字孪生这个说法笔者用 MuJoCo 对官方资源包做了实测在不连接任何真机的情况下仅凭资料包里的模型文件完成加载与渲染。实测环境与版本如下组件版本说明Python3.13.12官网安装包mujoco3.17.0pip install mujocoPython 绑定numpy2.5.4依赖自动安装Q1 模型q1_v3.xmlURDF 包 v1.0.0自带地面、光照与statistic场景配置T1 模型scene_plane.xmlURDF 包 v1.0.0通过include引用 T1-V2.xml 机体实测加载结果脚本运行时打印Q1 为 23 个关节、29 维广义坐标nq29其中 22 个驱动关节恰好对应官方手册标称的 22 DoF29 维广义坐标减去浮动基座占用的 7 维无执行器定义nu0纯运动学/动力学模型T1 为 15 个关节、14 个电机nu14力矩执行器增益参数为 1需外接 PD 控制器才能稳定站立。以下截图均由 MuJoCo 离屏渲染器1280×960生成脚本与复现步骤见文末工程仓库图6 说明Q1 官方模型初始姿态渲染。腿部每侧 6 自由度hip pitch/roll/yaw、knee、ankle pitch/roll、腰部 2 自由度旋转、侧摆、手臂每侧 4 自由度——821222与官方手册「全身自由度 22 DoF」逐项对得上。网格地面与阴影由 XML 中预置的光照定义产生。图7 说明Q1 上半身特写。头部、肩部串联的 pitch/roll/yaw 三轴关节与肘部、腕部偏航关节清晰可辨这与 SDK 运控接口中的关节命名一一对应。图8 说明T1 官方模型初始姿态。T1 以趴姿作为初始状态scene_plane.xml场景机体为浅蓝色外壳四肢为白色连杆与 URDF 中 FL/FR/RL/RR 四条腿各 3–4 个关节的定义一致。图9 说明T1 机体特写。可观察髋关节 roll/pitch、膝关节的串联结构以及黄色透明材质的足端连杆。实测结论官方 XML 模型开箱即用——无需修改路径、无需额外资产MjModel.from_xml_path一次加载成功渲染缓冲默认 640×480需在脚本中设置model.vis.global_.offwidth/offheight才能输出高清图这是唯一需要踩的坑。这套模型可以直接作为强化学习训练与轨迹验证的基础与 §4.2 的 ROS RViz/Gazebo 路径互为补充。复现说明上述关节数来自脚本实测打印可复现自由度口径以官方手册为准Q1 手册为 22 DoF。渲染脚本与环境版本见文末工程仓库。4.2.2 交互式调试把 MuJoCo 原生 Viewer 跑起来离屏渲染适合出图调关节限位、看接触点、逐帧查轨迹时要用交互式窗口。MuJoCo 的 Python 绑定自带被动模式 Viewer最小代码如下import mujoco, mujoco.viewer # viewer 是子模块必须单独 import import numpy as np model mujoco.MjModel.from_xml_path(q1_v3.xml) data mujoco.MjData(model) viewer mujoco.viewer.launch_passive(model, data, show_left_uiTrue, show_right_uiTrue) # 默认相机按 statistic 的 center/extent 取景细长机体容易跑偏手动对准 viewer.cam.lookat[:] np.array(model.stat.center) [0, 0, 0.1] viewer.cam.distance max(float(model.stat.extent) * 2.6, 1.6) viewer.cam.azimuth 145 viewer.cam.elevation -14 while viewer.is_running(): mujoco.mj_step(model, data) viewer.sync()三个实测踩到的点按遇到顺序说只写import mujoco会报AttributeError: module mujoco has no attribute viewer——viewer是独立子模块且依赖 GLFWpip install mujoco会一并装上若报缺 glfw补装glfw即可。相机需要手动设。Q1 站姿约 0.88 m 高默认distance取extent会退得太远机身只占画面中间一小块上面那三行把注视点抬到躯干、距离压到extent × 2.6取景才正常。Q1 的nu0模型里没有执行器直接mj_step会因为重力自由落体。演示关节运动时应当直接写data.qpos[...]再调mujoco.mj_forward()走运动学而不是靠data.ctrl。窗口打开后左侧是 File / Option / Simulation / Window / Help 标签栏下方依次为 Info仿真时间、步长、每步耗时、Sensor、Control右侧是 Rendering、Group enable、Joint、Actuator 一类可视化开关。调轨迹时最常按的是 Simulation 里的 Pause 与 Step——逐帧看足端接触比翻日志快得多。图10 说明Q1 在 MuJoCo 原生 Viewer 中的调试界面。左侧标签栏下方为 Info/Sensor/Control 面板右侧为可视化开关区中间 3D 视口显示 Q1 站立姿态与网格地面。注意标题栏显示的模型名为q1_v3即 XML 中mujoco model...的定义值。图11 说明向left/right_shoulder_pitch、shoulder_roll、elbow_pitch六个关节写入按正弦曲线插值的目标角度幅值受官方range限位裁剪Viewer 中 Q1 双臂连续摆动。这种写 qpos 前进仿真的方式正是验证关节命名与正负方向是否与 SDK 一致的最快办法——命名对不上动作就会往反方向走。图12 说明T1 的调试窗口。这里有个值得记一笔的细节标题栏模型名为QD1 scenemesh而不是 T1——官方scene_plane.xml里写的是mujoco modelQD1 scenemesh说明这份场景文件是从另一型号沿用的跨机型共用。T1 与 Q1 的另一个实测差异在驱动方式T1 的nu14是纯力矩电机gainprm1内部不带 PD要让它在仿真里站住得在循环里自己算力矩tau kp*(q_target - q) - kd*qdot写进data.ctrl直接给目标角度无效。官方资料包给出的 URDF/XML 是能直接进 MuJoCo 的而 MuJoCo 的交互式 Viewer 又是免费的、跨平台的、不需要真机的调试入口。对没有 T1 Pro 在手的开发者这条路径是唯一能低成本验证关节命名、限位、运动方向三件事的办法——而这三项恰好是后面写 SDK 运控代码时最容易出错的地方。4.3 第三步SDK 二次开发图13 说明primebot-q1-sdk 仓库页面。SDK 以 ROS2 包形式发布aimdk_msgs定义消息与服务examples/下给出 Python 与 C 两版示例。编译 SDK 的核心命令逐字引用官方《快速入门与集成指南》tar -xzf primebot_sdk.tar.gz cd primebot_sdk colcon build --cmake-args -DCMAKE_BUILD_TYPERelease每次新终端需加载编译产物环境逐字引用source /path/to/your/primebot_sdk/install/setup.bash运行官方示例逐字引用# Python 示例 python3 examples/python/demo.py # C 示例 ros2 run aimdk_examples_cpp demo用 ROS2 原生命令做接口验证是确认节点可见、数据通的最快方式逐字引用ros2 node list ros2 topic list # BMS 状态接收验证 timeout 5 ros2 topic echo /aima/hal/bms/state --once # TTS 语音播报验证 ros2 service call /aimdk_5Fmsgs/srv/PlayTts aimdk_msgs/srv/PlayTts \ {header: {}, tts_req: {text: 你好我是启元机器人, priority_level: {value: 6}, domain: sdk_test, is_interrupted: true}}注意官方文档提示若未持久化内核 UDP 缓冲区参数每次新终端执行 ROS 命令前需先调整逐字引用sudo sysctl -w net.core.rmem_max25165824 sudo sysctl -w net.core.wmem_max251658244.4 第四步调试与部署真机调试有两种路径。其一是直接用官方桌面调试台PrimeConsole1.0.3 实测见 §4.4.1其二是用 Docker 工具链在目标板编译部署。ARM 原生编译的关键命令逐字引用toolchain-arm-native文档# 启动容器RK sudo docker run -it --rm --nethost -v ~/workspace:/workspace -w /workspace native-aarch64-rk bash # 容器内编译 cd sdk_q1 colcon build cd ../sdk_t1 colcon build4.4.1 PrimeConsole 1.0.3 实测装得起来但连不上真机PrimeConsole 是官方桌面调试台。2026-10-28 放出的 1.0.3 版提供 Windows.exe237,803,340 字节、macOSIntel / Apple 芯片两个 dmg与 Linuxdeb239,217,122 字节三平台包都从 dev.primebot.com/download 取。Windows 包是 NSIS 封装的 Electron 应用解包后能看到resources/app.asar378,822,526 字节以及自带的 ffmpeg / mediamtx 二进制——结合主进程代码里ffmpeg -rtsp_transport tcp … -f mpegts的命令行可以确认实时视频流是本地 ffmpeg 拉 RTSP、转 HLS 再喂给渲染层的不是云端转发。在本机Windows跑通的完整流程是这样的PrimeConsole-Windows-1.0.3.exe /S /D路径可静默安装到指定盘默认会落到%LOCALAPPDATA%\Programs。启动后先到「Prime Console · 登录」手机号 短信验证码勾协议后进主界面。没有游客模式也没有跳过登录。一级导航只剩两个「机器人控制」和「Skill 验证」右上角固定挂着连接状态、「连接机器人」、「系统设置」、「登出」。有个和官方宣传对不上的地方值得记一笔下载页写的六大模块 ①–⑥是功能罗列不是软件里的菜单编号。1.0.3 把这些功能全折叠进了「机器人控制」这一页——上方是连接卡片内嵌日志 / 摘要 / JSON三个视图切换中间是实时视频位与语音 TTS下方并排摆着动作库和表情库。写文档时如果照抄下载页的编号去指路读者是找不到对应菜单的。图14 说明未绑定真机时的 PrimeConsole 1.0.3 主界面实机截屏。左上角连接卡片显示未连接、日志区暂无连接日志中部视频位尚未获取图像下方动作库、表情库均显示0 项。这张空状态图本身就是一条有用结论动作库、表情库、视频流、遥测日志四项数据全部依赖真机在线纯仿真环境拿不到。图15 说明连接卡片的「日志」视图。未连接时面板保持暂无连接日志旁边还有「摘要」「JSON」两个视图设计上是给连接态的遥测做结构化展示的空载状态下三者都是空面板——这正是判断设备是否真的在线的第一手依据。图16 说明连接卡片的「摘要」视图未连接时只显示未连接机器人一行字。这个视图在连接态下本应聚合设备型号、固件版本、在线时长等结构化摘要是排查机器人到底什么状态时最先看的面板。图17 说明连接卡片的「JSON」视图面向程序化调用方直接输出原始遥测字段。空载状态下同样无数据可吐——三个视图共用一套数据源进一步印证遥测数据完全由真机侧推送。图18 说明「Skill 验证」页。这是把本地技能推到机器人上跑验证的入口与 PrimeHub 技能市场是上下游关系PrimeHub 负责上架分发PrimeConsole 负责上机前验证。4.4.2 真机门槛SN 码 云端授权校验点「连接机器人」弹出设备选择框没绑定过设备时直接提示暂无设备请先在「设置 → 机器人配置」中添加设备。顺着指引进「系统设置 → 机器人配置 → 添加设备」要求填机器人 SN 码示例格式T1-2024-0052并明确写着PrimeConsole 将向启元机器人校验资产与授权状态。图19 说明设备选择弹窗。设备列表来自账户下已绑定的资产为空时只能先去系统设置添加无法临时直连 IP。图20 说明添加设备需要机身铭牌上的 SN 码提交后由启元云端校验资产与授权。结论很直接——没有真机或真机未授权的开发者动作库和表情库永远是 0 项。这也解释了为什么下面要换一条离线路径来做动作验证。图21 说明「系统设置 → 机器人配置」页“我的设备列表为空提示点击右上角「添加设备」开始”。这是整个真机链路的起点没有这一步录入 SN后面所有依赖设备在线的功能都无从谈起。4.4.3 离线替代方案直接回放 PrimeConsole 内置的动作包连不上真机还有一条更可复现的路子PrimeConsole 安装包里本来就带了一整套机器人资源位置在resources/app.asar解包后的dist/appres-pro/q1_v2/urdf/q1_v2.urdf——Q1 官方 URDF。MuJoCo 3.17 直接加载后得到22 个转动关节、nq 22无浮动基座。对照开源仓那版 q1_v3 的 23 关节 / 29 个广义坐标多出来的 7 维正好是浮动基座两者自洽。preset-actions-q1/index.json——count: 115分 14 类上传上肢动作包 29、对话表达类 15、社交礼仪类 14、情绪反馈类 13、娱乐与生活模仿类 7、思考认知类 7、任务反馈与指引类 7、原厂预设 8、运动模仿类 3、内部播报动作 3、灵创捕捉 5、拖拽示教 2、音乐舞蹈类 1、闲时状态类 1按显示名去重后剩 111 条。preset-actions-q1/motions/*.csv——120 fps 的原始关节角轨迹表头是关节名单位弧度。上半身包固定 10 列waist_roll / waist_yaw 双侧shoulder_pitch/roll/yaw 双侧elbow跟 URDF 里的关节名逐字对得上。既然列名和 qpos 一一对应就可以把 CSV 直接灌进 MuJoCo 的关节角、逐帧mj_forward再离屏渲染得到官方动作的确定性回放——不联网、不依赖真机、任何人拿到安装包都能复现import mujoco, numpy as np model mujoco.MjModel.from_xml_path(q1_v2.urdf) # 22 个转动关节 model.vis.global_.offwidth 1000 # 默认离屏缓冲只有 640×480 model.vis.global_.offheight 800 # 不放大会在 Renderer 构造时就抛 ValueError data mujoco.MjData(model) data.qpos[model.jnt_qposadr[joint_index]] angle_rad # CSV 列 → qpos mujoco.mj_forward(model, data) renderer.update_scene(data, cameracam) img renderer.render()上面是核心片段renderer/joint_index/cam的构造与逐帧循环已略。完整可运行脚本已按征文规则第 2 条上传至 AtomGit 公开仓库https://atomgit.com/azhiqiu/primebot-q1-t1-mujoco-repro 脚本位于仓库scripts/目录克隆后按 README 配置即可运行。回放了官方动作包里四类典型动作参数实测如下帧数按 120 fps 计。数据来源官方动作包 preset-actions-q1 内的关节轨迹 CSV采样率 120 fps时长与帧数为笔者逐条统计所得可用本文工程脚本复现。动作编号 / 分类时长帧数招手3001原厂预设4.00 s480握手3002上传上肢动作包6.67 s800上半身舞蹈 13046原厂预设5.17 s620随意摇摆FB-DAN-001音乐舞蹈类8.19 s983图22 说明原厂预设招手30014.00 s / 480 帧六帧等间隔回放。可以看到右肩 roll 外展、右肘收拢后小臂做往复摆动左臂保持自然下垂——CSV 里左臂那 5 列全程几乎不变与波形图图26一致。图23 说明“握手”30026.67 s / 800 帧六帧回放 。右臂前伸到体前偏右后小幅度上下摆动躯干基本不动。这类动作只动上半身 10 个关节下半身 12 个关节全程保持零位——也就是说官方动作包是上半身动作库不包含步态。图24 说明“上半身舞蹈 1”30465.17 s / 620 帧六帧回放。双臂交替上举配合腰 yaw 小幅扭转是周期性强、幅度大的一类很适合拿来验证关节限位有没有被撞到。图25 说明音乐舞蹈类随意摇摆FB-DAN-0018.19 s / 983 帧六帧回放是本组里时长最长、躯干参与最多的一个。注意它的scope字段是FBfull body但实际 CSV 仍然只有 10 个上半身关节列——字段口径与数据口径不一致引用时以 CSV 实际列数为准。图26 说明四个动作的关节角-时间曲线横轴秒、纵轴弧度直接读自 120 fps 原始 CSV未做平滑。从上到下能看出四类动作的指纹差异招手是右肘单关节高频往复握手是右肩 pitch 的一次慢速单向抬放舞蹈是右肘与右肩 pitch 的反相周期振荡随意摇摆则是腰 yaw 与右肩 roll 的低频大幅摆动。这类曲线可以直接拿来做动作分类或异常检测的特征。把 §4.2.1 的自建 MuJoCo 渲染和这一节的官方动作回放放在一起看能得出一条对开发者更实际的结论启元的官方 URDF 官方动作 CSV 是解耦的——URDF 描述本体CSV 只描述关节角随时间的取值两者靠关节名对齐。这意味着你可以在不碰真机的前提下把动作时序、关节限位、周期特征这些逻辑先在仿真里验完再等真机到位做标定。五、开源生态盘点双仓同步与 PrimeHub 技能市场图27 说明启元机器人在 AtomGit 的组织主页与 GitHub 双仓同步。征文规则要求示例工程上传 AtomGit这里就是最终要落地的位置。启元的开源资产分布在两个地方GitHub 组织PrimebotTech12 个公开仓库与国内AtomGit 组织PrimebotTech同内容加速镜像。下表是仓库职责一览。图28 说明仓库地图把前文提到的所有仓库按职责归类。核心开发四件套q1/t1 SDK q1/t1 URDF是二次开发的必装项三个 toolchain 仓库解决在哪编译PrimeHub dev kit 解决如何上架。mjlab / primebot_rl_mjlab / SuperMimic 三个仓库 README 未给出明确用途描述本文标注【待确认】。PrimeHub 技能开发包miracle-techlink/primehub_dev_kit它把写机器人技能标准化成了可复现的链路。其 README 给出的快速开始自检命令逐字引用python3 primehub_publish.py search 你好 # 自检能搜 网络和传输层 OK官方定义的技能开发顺序是逐字引用 README注册 PrimeHub → 给 AI agent 喂机器人契约 → vibe coding 改示例 → 打包 .rpk → 真机调试 → 提取登录 token → 一条命令发布上架环境要求逐字引用Python 3 pip install gmssl、curl、sshpass、一台同网段的 Q1/T1 机器人SSHrun、本机 Firefox用于 PrimeHub 登录态发布凭证自动提取。仓库内example-jukebox/是一个已上架的真实案例点歌台开发者可复制成自己的技能再改pack.py负责把技能目录打包成.rpkdeploy_test.py负责真机调试primehub_publish.py是发布/删除/查询客户端。客观评价PrimeHub 把算法能力封装为可上架的技能.rpk与底层 ROS2 SDK 形成底层接口 上层应用市场的两层结构开发者既可以深入 SDK 写硬核控制也可以在上层用 AI agent 快速产出技能。这种分层对生态建设是清晰的。关于mjlab、primebot_rl_mjlab、SuperMimic、GMR四个仓库GMR的 GitHub 描述为机器人数据重定向适配 Q1其余三个仓库的 README 在抓取时未提供明确用途说明已知 mjlab / primebot_rl_mjlab 与 MuJoCo/强化学习相关、SuperMimic 为 MIT 协议 Python 项目其具体定位【待确认】建议以仓库后续文档为准。六、给想上手的开发者的第一步建议把全文收敛成可执行的第一天清单先定机型再 clone。双足人形选 Q1四足/双足人形选 T1两者 SDK 接口范式一致可共用学习成本。装 Ubuntu 22.04 ROS2 Humble用 §4.1 的命令把基础依赖与colcon跑通。先用 URDF 在仿真里跑通关节运动再碰真机——这步能把 80% 的运动学错误挡在真机之前。用官方示例demo.py/demoC验证 ROS2 节点可见、topic/service 通再写自己的业务逻辑。编译产物走 Docker 工具链x86 主机用toolchain-x86-cross-arm交叉编译目标板直接用toolchain-arm-native原生编译二者镜像与命令官方已给全。想做可分发的能力走 PrimeHub用primehub_dev_kit从example-jukebox改起打包.rpk上架。复现材料本文用到的渲染与回放脚本render_sim.py/q1_motion_seq.py/viewer_shot.py/find_t1_stance.pyhttps://atomgit.com/azhiqiu/primebot-q1-t1-mujoco-repro 克隆即可复现本文所有命令均来自官方 README请以你下载时的最新版本号为准。最后强调事实边界Q1 的 22 DoF 有官方手册与模型实测两方印证见 §1 与 §4.2.1可以当确定参数用T1 的自由度数量、主控 RK 平台的具体芯片型号、以及 mjlab 等研究型仓库的用途官方当前未公开或文档未覆盖本文已逐项标注【待确认】请勿把这些待确认项当作确定参数使用。本文涉及的 开发资料可通过 启元机器人开发者社区 查阅。欢迎大家交流