把 Q1 从折叠收储的状态叫起来让它走到你面前。对用户来说这是一句话。对机器人来说这句话要穿过五层技能层决定“做什么”智能层理解“在哪、是谁”运动控制层决定“怎么动”通信层把指令送到板子上本体层把电流变成力矩。这篇文章不按模块清单罗列。指令本身是从上往下走的但我们要理解它为什么能走通得反过来从最底下的身体开始一层层往上先看身体能做什么再看两块板怎么把指令送到关节然后是小脑、大脑最后回到技能。每到一个新层先问它解决了下面哪一层解决不了的问题再看它对外暴露什么最后指出开发者最容易卡住的地方。一、先看全景五层各管一段图是从上往下画的因为指令确实从上往下走正文从 1 往上讲因为每一层都踩在下一层上。这张图里有两组关系值得先记住。从上往下是指令的翻译过程。技能层把“走过来”拆成若干阶段智能层判断人在哪、要不要跟进运动控制层把“向前 0.3 米每秒”翻译成关节目标通信层把目标送到运控板本体层把目标变成电流。每往下一层语义少一分实时性高一分。从下往上是状态的反馈过程。关节状态、电池电量、触摸事件、相机画面沿着相反的方向往上走最后变成智能层的一次判断、技能层的一次状态迁移。上层之所以能“知道”机器人现在怎么样靠的是下面四层把状态一层层交上来。还有一条边界第 3 层是分水岭。第 1、2 层主要由固件和系统守住开发者一般只动配置第 3 层能一直管到关节第 4、5 层负责任务是二次开发主要发生的地方。启元的开发者模式本质上就是在控制这条边界开放到什么程度。接下来按 1 到 5 走。走到第 3 层会停得久一点因为“谁能让电机转”这件事主要在这一层决定。二、身体层参数会变成上层的常量先看本体。Q1 身高 88 厘米整机约 16 公斤22 个自由度电池 215 Wh标称续航 3 小时日常最大移动速度 1 m/s。自由度拆开是腿 6×2、臂 4×2、腰 2来源Q1 参数页。关节是 QDD 准直驱。官方给的数字是齿圈电机与外壳一体化粉末冶金减重到 260 克2.5 mm 中空走线峰值扭矩密度 85 N·m/kg。翻译成开发者能用的信息是三个词体积小、能反驱、力控响应快。前两个决定它能不能塞进 88 厘米的身体第三个决定它能不能做柔顺交互。这些本体参数不是产品页上的装饰。它们会变成上层代码里的常量。我把官方 URDFq1_v3拉下来算了一遍26 个 link、25 个 joint其中 22 个是可动关节所有mass加起来是 16.917 kg髋、膝关节的effort上限是 36 N·m踝关节是 22 N·m。后来在速度控制那一层看到“线速度绝对值要么是 0要么不低于 0.2 m/s”就不难理解低于硬件的低速下限关节会抖整机会为了平衡触发代偿。所以身体层虽然改不动却必须读懂。它决定了上层哪些参数是“物理上做不到”哪些只是“软件上没开放”。三、通信与计算层两块板一条总线指令离开本体层往上先碰到的是计算与通信。启元用的是双板运控板10.1.1.100大脑板10.1.1.101开发机建议设成10.1.1.99三者在10.1.1.0/24网段来源SDK《快速入门与集成指南》第 2.1.2 节。接上网线、打开开发者模式之后ros2 node list能同时看到两块板上的节点比如hal_camera、hal_audio、mc_ros2_node。为什么要分两块板因为实时性和算力是两种资源。运控板要在一个固定的控制周期里算完关节目标晚一毫秒都不行大脑板要跑视觉、语音、Agent算得久一点没关系但不能抖到控制环里。分成两块板中间用网线隔开实时控制就不会被推理任务拖累。两块板之间跑的是 ROS2 HumbleRMW 固定为rmw_fastrtps_cppFastDDS。你可以把 DDS 理解成一条总线节点往总线上发消息谁关心谁订阅不需要知道对方在哪块板、哪个进程。这套机制的好处是解耦代价是调优。调优的参数写在 SDK 自带的fastdds_profiles.xml里UDP 收发缓冲 20 MB20971520开发机内核参数要跟着抬到 24 MB25165824否则ros2 topic echo会时通时不通。配置文件里还有一个 200 MB 的共享内存段但默认 participant 只启用 UDP同机多进程部署时才去开 SHM。QoS 也不是一套参数打天下数据频率QoS速度话题/aima/mc/locomotion/velocity50–100 HzReliable / Volatile / Depth10上肢关节/aima/mc/custom/joint/command100 HzBest Effort / Volatile / Depth10关节指令/aima/hal/joint/command1000 HzBest Effort / Volatile / Depth10关节状态/aima/hal/joint/state500 HzBest Effort / Volatile / Depth10电池/aima/hal/bms/state1 HzBest Effort / Volatile / Depth10速度用 Reliable因为它是“持续意图”丢一帧可能意味着机器人突然收不到“继续走”关节指令 1 kHz 用 Best Effort因为下一帧马上补上重传反而制造延迟。这个取舍在别的机器人栈里也能看到但启元把它写进了默认配置开发者不用自己猜。通信层不产生动作但它决定动作能不能及时、完整地到达。调不好上层逻辑再对表现出来也是“时好时坏”。四、运动控制层三个问题三道关指令到了运控板MC 要连续回答三个问题现在允许动吗谁有权动动多快4.1 现在允许动吗状态机Q1 的运动状态不是一组可以随便跳的枚举而是一张有向图。官方McAction.msg给 Q1 列了 22 个动作常量示例代码mc_action_switcher.py里的_ACTION_RULES把其中 18 个状态写成了 55 条有向边。为什么要有这张图因为人形机器人的动作有物理先后。趴着不能直接走必须先撑起来躺着不能直接跑必须先经过收储或站立。状态机把这些物理约束写成规则不合法的跳转直接拒绝返回-1001到-1006这样的错误码。回到我们的指令。Q1 现在在STORE_DEFAULT折叠收储目标是BIPED_WALK_RUN走跑。官方规划器给的是两步STORE_DEFAULT - BIPED_WALK_RUN: 2 次 SetMcAction 1. BIPED_GROUND_POSE 2. STAND_UP - BIPED_WALK_RUN(auto)第一步BIPED_GROUND_POSE把身体撑起来第二步STAND_UP执行站起。站起完成后MC 会自动把状态更新到走跑不需要再发第三次。这个“自动落到走跑”的规则写在官方代码的_AUTOMATIC_NEXT_ACTIONS里注释的原话是 “STAND_UP is the Q1 recovery action: its runner updates MC to BIPED_WALK_RUN”。这里有两个新手最容易踩的点。第一两次SetMcAction的间隔不能小于 500 ms否则返回-10001。第二GetMcAction的status在切换期间是200TRANSITION切完才是100RUNNING必须轮询到100再发下一条否则两条轨迹会叠在一起。我把这张图抽成 JSON穷举了所有有序状态对306 对里 209 对可达97 对不可达可达的里面89 对一步105 对两步15 对三步最长的一条最短路是 8 步。不可达不代表机器人坏了只代表“这两个状态之间没有合法的物理路径”比如从躺姿直接到走跑规划器就会拒绝。4.2 谁有权动输入源仲裁状态对了只说明“这个动作合法”。谁有权发这个动作是另一套机制。机器人可能同时被手机 App、语音 Agent、实体遥控器、开发者程序控制。启元的做法是给每个控制源注册一个名字、一个优先级、一个超时时间由 MC 仲裁出当前唯一的主控。优先级分五档来源《接口说明》2.1.1.4档位优先级信源系统级100–80急停、安全保护、rc、pnc、interaction高级79–60实体遥控器、App 手动遥控、vr、app_proxy中级59–40语音指令、手势交互低级39–20SDK 二次开发、PNC 仿真备用19–0研发调试、低压测试、离线仿真规则有三条高优先级直接抢占同优先级先入为主当前主控不停后来者进不来每个源有 1000 ms 看门狗主控断了按优先级降序找下一个还活着的候补。要发速度开发者得先调SetMcInputSource用1001ADD注册一个源填name、priority、timeout。注册成功后源默认就是 Enable直接参与仲裁。之后每条速度消息的source字段必须和注册名完全一致否则帧会被静默丢弃。官方速度示例里这个注册写成了priority 80和rc、pnc、interaction同级而文档建议 SDK 二次开发用 39–20。这不是小差别同优先级是先入为主如果 SDK 先占锁遥控器后发反而抢不进来要等 SDK 停发 1000 ms 超时后才能接管。我在自己的会话里把优先级改成 30行为就回到文档描述的样子。示例代码大概率是为了让新手脚本“一跑就动”但抄进产品之前这一行值得改。这张时序图是我按文档规则写的离线仲裁器跑出来的Appp60先占锁SDK 节点p30在 300 ms 开始发一直被挡App 在 650 ms 停发看门狗到 1660 ms 才把锁释放给 SDK遥控器p802000 ms 介入立刻抢占2400 ms 遥控器停发3360 ms 超时锁又回到 SDK5160 ms SDK 也停了没有候补运动停止。两个细节值得记住。第一控制权是内存态。SetMcInputSource的增删改只写 RAM不回刷 YAML机器人重启动态注册的源就没了。所以程序启动时先 DELETE 再 ADD清掉上次异常退出留下的同名源。第二GetCurrentInputSource返回的是锁的归属不代表指令流还活着。主控超时后、还没有新抢占者之前接口依然返回旧主控的名字要自己记最后一帧的时间。4.3 动多快速度话题状态放行、控制权到手最后才是发速度。/aima/mc/locomotion/velocity的字段不多forward_velocity、lateral_velocity、angular_velocity、pitch_velocity、level外加header和source。约束有三条频率 50–100 Hz。官方示例用 50 Hz 定时器发低于这个频率1000 ms 看门狗会把控制权摘走高于这个频率没有额外收益。速度有死区。线速度绝对值要么是 0要么不低于 0.2 m/s角速度同理不低于 0.2 rad/s。文档的解释是低于硬件最低速度运行时关节容易抖动、异响整机为了维持平衡还会触发代偿反而更危险。source必须和注册名一致。名字写错、大小写不一致、用了内置名rc、pnc、interaction、vr、app_proxy帧会被静默丢弃或者和内置源互相冲刷。三个问题都答完MC 才会把速度指令翻译成关节目标。到这里“走过来”这件事在运动控制层就算完成了。五、智能层看人、听话、决定下一步运动控制层回答“怎么动”但“人去哪了”“该跟谁走”“用户刚才说了什么”不归它管。这一层的输入是传感器。Q1 配的是单目摄像头、环形麦克风、触摸传感器和 8 核处理器T1 Pro 多了 Orin Nano、5 组 ToF、双目摄像头和两颗鱼眼来源Q1 参数页、T1 参数页。输出则是几类接口语音识别结果走/aima/agent/asr_result话题播报走PlayTts服务表情走PlayEmotion触摸走/aima/hal/touch/state相机可以抓单帧CaptureJpegImage全链路 100–500 ms建议 1 fps或者拉 RTSP 流端口 2554。启元在发布会上公布了这一层的模型命名PrimeMotion 负责柔顺安全的小脑运控PrimeGo 负责多模态感知与跟随PrimeVista 负责多模态交互PrimeMind 是面向家庭场景的家务基座模型此外还有一个基于 Harness 架构的机器人 Agent来源新华网。需要区分的是这些是模型和产品的命名不是 SDK 里的接口名。SDK 给开发者的是“原始数据 服务”不是“模型内部”。比如你可以订阅 ASR 结果、调用 TTS、抓一帧图但 SDK 没有开放“目标检测”或“导航”的现成接口。官方carry-clothes技能在selfProvided里写得很直白目标检测和视觉伺服要开发者自己补默认的HeuristicDetector只是占位不产生结果。这是理解启元架构的一个关键智能层是产品能力运动层是开放能力。产品页上“看得见、听得懂、会跟随”是前者SDK 文档里“话题、服务、关节”是后者。两者之间有交集但不能画等号。六、技能层把动作串成任务用户不会直接调用 Agent他们装的是技能。启元的技能包格式叫 RPK入口是manifest.json。官方carry-clothes把衣服拿到洗衣机旁是一个很好的样本因为它的清单把“技能”这件事拆得很清楚runtimePython ≥ 3.10入口main:run启动前 source ROS2 和 SDK 环境capabilities逐条声明要用的接口比如SetMcInputSource的参数写死namecarry_clothes_skill, priority30, timeout1000速度话题写死minRateHz50, maxForward0.35, maxYaw0.5selfProvided明确写出 SDK 不提供、要开发者自建的能力这里是目标检测和视觉伺服safety最大前进速度 0.35 m/s、电量底线 20%搬运中 25%、关节限位钳制、动作间隔 500 ms、异常中止时平滑回正、必须设备端确认stages把任务拆成 10 个带超时的阶段从响应指令、切直立、走到用户跟前到抬臂、等待接衣、合臂、找洗衣机、前往、放下、完成。这份清单最值得借鉴的地方是它把“不能做什么”写在了安装之前。selfProvided里说得很清楚SDK 不提供目标检测不提供 SLAM/导航safety.notes里还有三句SDK 无夹爪接口接物是双臂合拢托住SDK 无 ASR 接口用户确认改用头部触摸事件上肢位姿是推算值上机前必须示教标定。这里的“无 ASR 接口”指的是技能运行时没有可调用的识别服务/aima/agent/asr_result话题仍然存在只是技能拿不到一次同步的识别结果。技能层不直接控制电机。它做的是任务编排什么时候切状态、什么时候发速度、什么时候播报、什么条件下中止。真正的控制仍然落在第 3 层。把这两层分开技能才能在没有真机的时候用 Mock 跑通也才能被审查、被打包、被分发。七、工具链与开发模式从读到跑五层讲完回到开发者这一侧。启元给的入口是 PrimeConsole一个跨 macOS、Windows、Linux 的桌面工作台能连机器人看视频和日志、控运动、跑仿真、验证技能。它本质上是一组标准 DDS 节点加图形界面不装它用ros2 topic list、rqt、rosbag也能做同样的事只是要自己配环境。仿真侧有官方 URDF、MuJoCo XML、Gazebo launch还有三套 Docker 工具链ARM 原生编译Orin / RK、x86 交叉编译 ARM、x86 原生编译。SDK 里直接带了 OpenCV 4.13.0 和 Ruckig 轨迹库的源码版本钉死减少“本地能跑、板上编译不过”的环境漂移。开发者模式分五层运行模式Standard / Develop、开发方式API / ROS2、开发层级Basic / Advanced、领域设置、能力配置。当前版本 API 方式没开放默认只支持 ROS2领域设置和能力配置暂时合并只生效“运动控制—低层运控开发”。Basic 和 Advanced 的差别不是权限多一点少一点而是接管方式不同。Basic 保持原厂业务和安全策略外部指令并发注入Advanced 允许关闭特定官方模块拿传感器裸流和底层运控的独占权。代价也写在文档里开启开发者功能后不再享受维保服务切模式要重新上下电。如果只想跑通一次“走过来”最短路径是五步ros2 node list确认节点GetMcAction确认当前状态SetMcInputSource注册一个 p30 的源50 Hz 发 0.2 m/s 走两秒零速度加DELETE收尾。真机先架空或平躺手边留急停。八、三处对不上的地方读到这儿你已经能把一条指令从头走到尾。但真上手时还有三处文档、枚举和示例代码对不上的地方值得提前知道。第一处官方速度示例把 SDK 源注册成了 p80。mc_locomotion_velocity.py第 149–151 行是name node、priority 80、timeout 1000第 16 行注释也写 “priority 80”而《接口说明》把“SDK 二次开发信号”放在 39–20。按示例抄SDK 和遥控器同级按文档写SDK 应该低一档。我倾向前者只是为了让新手脚本“一跑就动”产品里应该改成 30。第二处文档的状态图画了LYING_DEFAULT → STAND_UP代码的表里没有。《接口说明》2.1.1.1 的 mermaid 图里躺姿有一条指向站起的虚线但 Python 和 C 两份mc_action_switcher的_ACTION_RULES里LYING_DEFAULT只有STORE_DEFAULT一条出边而STORE_DEFAULT又不能当中间态。结果就是官方规划器认为“躺姿 → 走跑”不可达。这不等于底层状态机拒绝这条切换但意味着你按示例的规划器办事会在这一步停住。第三处状态图里有三个状态枚举表里没有。BIPED_WALK_RUN_DEFAULT、BIPED_GROUND_POSE、BIPED_RECORD_UPPER出现在_ACTION_RULES里McAction.msg的 Q1 枚举段却没有给它们数值。它们只能通过action_desc字符串下发不能靠action.value。反过来MIMIC、MIMIC_LINKCRAFT、MIMIC_OPENSOURCE等 7 个枚举又不在图里。三处差异指向同一件事这套 SDK 的权威顺序是“代码 枚举 文档图”。文档适合建立框架真正下发之前用ros2 service call和GetMcAction各验一次比抄示例稳。九、边界与取舍最后说说这套架构的边界。开放的层次是扎实的ROS2 Humble、FastDDS、标准 Topic/Service、URDF、MuJoCo、Docker没有私有格式接口给到了关节力矩、刚度、电池状态字这一级状态机、输入源、速度话题都有明确的错误码和超时。对做研究和做技能的人来说这是一套能落地的开放平台。没开放的部分也要说清楚没有导航、SLAM、语义地图没有夹爪接口没有现成的目标检测语音只给识别结果不给唤醒词和对话模型API 方式还没上线Advanced 模式会失去维保。社区里已经有人问 T1 Pro 的声纹、人脸识别结果从哪读问 Orin Nano 是 4GB 还是 8GB问音频通道为什么和文档对不上——这些问题恰好说明参数表之外开发者还需要一份“哪些有接口、哪些是黑盒、哪些要自己补”的边界文档。这套架构适合谁适合愿意按 ROS2 的方式做事、需要关节级控制、或者想把技能做成可分发包的人。它不适合想“装个 App 就能让机器人干活”的人——那部分工作在技能层和智能层SDK 只给到原料。十、再回到那条指令现在再看“走过来”这句话。技能层把它拆成阶段智能层判断人在哪运动控制层确认“现在允许走、我有权走、走多快”通信层把速度送到运控板本体层把电流变成力矩。走的过程中关节状态、电池、触摸事件又沿着相反的方向回到上层变成下一次判断。五层各管一段缺一层这句话就落不了地。如果你想自己走一遍SDK、URDF、桌面端 PrimeConsole、技能仓库都在启元机器人开发者社区dev.primebot.comAtomGit 组织是 atomgit.com/primebot。本文用到的状态图数据、仲裁模型、Mock 会话和 URDF 提取脚本整理在primebot-control-path仓库按 README 的顺序跑就能复现文中的输出。社区里已经有 Q1 仿真挥手、T1 搬运、语音叫车这些例子遇到问题先去论坛搜比从头啃文档快。参考资料启元 Q1 产品页https://www.primebot.com/q1.html启元 Q1 参数页https://www.primebot.com/product_spec4.html启元 T1 参数页https://www.primebot.com/product_spec1.html启元机器人开发者社区下载页https://dev.primebot.com/download启元 Q1 SDK v1.0.0.0《接口说明》《PrimeBot SDK 快速入门与集成指南》2026-10-10启元 Q1 URDF v1.0.0q1_v32026-09-24官方技能carry-clothes的manifest.jsonhttps://atomgit.com/primebot/carry-clothes新华网《启元个人机器人正式发售AI模型、生态布局同步公布》2026-09-22https://www.news.cn/tech/20260922/770e10d4acdb48ed865eee514b26e06d/c.htmlAtomGitx启元机器人具身智能原创内容征文活动#
把 Q1 从折叠收储的状态叫起来让它走到你面前。对用户来说这是一句话。对机器人来说这句话要穿过五层技能层决定“做什么”智能层理解“在哪、是谁”运动控制层决定“怎么动”通信层把指令送到板子上本体层把电流变成力矩。这篇文章不按模块清单罗列。指令本身是从上往下走的但我们要理解它为什么能走通得反过来从最底下的身体开始一层层往上先看身体能做什么再看两块板怎么把指令送到关节然后是小脑、大脑最后回到技能。每到一个新层先问它解决了下面哪一层解决不了的问题再看它对外暴露什么最后指出开发者最容易卡住的地方。一、先看全景五层各管一段图是从上往下画的因为指令确实从上往下走正文从 1 往上讲因为每一层都踩在下一层上。这张图里有两组关系值得先记住。从上往下是指令的翻译过程。技能层把“走过来”拆成若干阶段智能层判断人在哪、要不要跟进运动控制层把“向前 0.3 米每秒”翻译成关节目标通信层把目标送到运控板本体层把目标变成电流。每往下一层语义少一分实时性高一分。从下往上是状态的反馈过程。关节状态、电池电量、触摸事件、相机画面沿着相反的方向往上走最后变成智能层的一次判断、技能层的一次状态迁移。上层之所以能“知道”机器人现在怎么样靠的是下面四层把状态一层层交上来。还有一条边界第 3 层是分水岭。第 1、2 层主要由固件和系统守住开发者一般只动配置第 3 层能一直管到关节第 4、5 层负责任务是二次开发主要发生的地方。启元的开发者模式本质上就是在控制这条边界开放到什么程度。接下来按 1 到 5 走。走到第 3 层会停得久一点因为“谁能让电机转”这件事主要在这一层决定。二、身体层参数会变成上层的常量先看本体。Q1 身高 88 厘米整机约 16 公斤22 个自由度电池 215 Wh标称续航 3 小时日常最大移动速度 1 m/s。自由度拆开是腿 6×2、臂 4×2、腰 2来源Q1 参数页。关节是 QDD 准直驱。官方给的数字是齿圈电机与外壳一体化粉末冶金减重到 260 克2.5 mm 中空走线峰值扭矩密度 85 N·m/kg。翻译成开发者能用的信息是三个词体积小、能反驱、力控响应快。前两个决定它能不能塞进 88 厘米的身体第三个决定它能不能做柔顺交互。这些本体参数不是产品页上的装饰。它们会变成上层代码里的常量。我把官方 URDFq1_v3拉下来算了一遍26 个 link、25 个 joint其中 22 个是可动关节所有mass加起来是 16.917 kg髋、膝关节的effort上限是 36 N·m踝关节是 22 N·m。后来在速度控制那一层看到“线速度绝对值要么是 0要么不低于 0.2 m/s”就不难理解低于硬件的低速下限关节会抖整机会为了平衡触发代偿。所以身体层虽然改不动却必须读懂。它决定了上层哪些参数是“物理上做不到”哪些只是“软件上没开放”。三、通信与计算层两块板一条总线指令离开本体层往上先碰到的是计算与通信。启元用的是双板运控板10.1.1.100大脑板10.1.1.101开发机建议设成10.1.1.99三者在10.1.1.0/24网段来源SDK《快速入门与集成指南》第 2.1.2 节。接上网线、打开开发者模式之后ros2 node list能同时看到两块板上的节点比如hal_camera、hal_audio、mc_ros2_node。为什么要分两块板因为实时性和算力是两种资源。运控板要在一个固定的控制周期里算完关节目标晚一毫秒都不行大脑板要跑视觉、语音、Agent算得久一点没关系但不能抖到控制环里。分成两块板中间用网线隔开实时控制就不会被推理任务拖累。两块板之间跑的是 ROS2 HumbleRMW 固定为rmw_fastrtps_cppFastDDS。你可以把 DDS 理解成一条总线节点往总线上发消息谁关心谁订阅不需要知道对方在哪块板、哪个进程。这套机制的好处是解耦代价是调优。调优的参数写在 SDK 自带的fastdds_profiles.xml里UDP 收发缓冲 20 MB20971520开发机内核参数要跟着抬到 24 MB25165824否则ros2 topic echo会时通时不通。配置文件里还有一个 200 MB 的共享内存段但默认 participant 只启用 UDP同机多进程部署时才去开 SHM。QoS 也不是一套参数打天下数据频率QoS速度话题/aima/mc/locomotion/velocity50–100 HzReliable / Volatile / Depth10上肢关节/aima/mc/custom/joint/command100 HzBest Effort / Volatile / Depth10关节指令/aima/hal/joint/command1000 HzBest Effort / Volatile / Depth10关节状态/aima/hal/joint/state500 HzBest Effort / Volatile / Depth10电池/aima/hal/bms/state1 HzBest Effort / Volatile / Depth10速度用 Reliable因为它是“持续意图”丢一帧可能意味着机器人突然收不到“继续走”关节指令 1 kHz 用 Best Effort因为下一帧马上补上重传反而制造延迟。这个取舍在别的机器人栈里也能看到但启元把它写进了默认配置开发者不用自己猜。通信层不产生动作但它决定动作能不能及时、完整地到达。调不好上层逻辑再对表现出来也是“时好时坏”。四、运动控制层三个问题三道关指令到了运控板MC 要连续回答三个问题现在允许动吗谁有权动动多快4.1 现在允许动吗状态机Q1 的运动状态不是一组可以随便跳的枚举而是一张有向图。官方McAction.msg给 Q1 列了 22 个动作常量示例代码mc_action_switcher.py里的_ACTION_RULES把其中 18 个状态写成了 55 条有向边。为什么要有这张图因为人形机器人的动作有物理先后。趴着不能直接走必须先撑起来躺着不能直接跑必须先经过收储或站立。状态机把这些物理约束写成规则不合法的跳转直接拒绝返回-1001到-1006这样的错误码。回到我们的指令。Q1 现在在STORE_DEFAULT折叠收储目标是BIPED_WALK_RUN走跑。官方规划器给的是两步STORE_DEFAULT - BIPED_WALK_RUN: 2 次 SetMcAction 1. BIPED_GROUND_POSE 2. STAND_UP - BIPED_WALK_RUN(auto)第一步BIPED_GROUND_POSE把身体撑起来第二步STAND_UP执行站起。站起完成后MC 会自动把状态更新到走跑不需要再发第三次。这个“自动落到走跑”的规则写在官方代码的_AUTOMATIC_NEXT_ACTIONS里注释的原话是 “STAND_UP is the Q1 recovery action: its runner updates MC to BIPED_WALK_RUN”。这里有两个新手最容易踩的点。第一两次SetMcAction的间隔不能小于 500 ms否则返回-10001。第二GetMcAction的status在切换期间是200TRANSITION切完才是100RUNNING必须轮询到100再发下一条否则两条轨迹会叠在一起。我把这张图抽成 JSON穷举了所有有序状态对306 对里 209 对可达97 对不可达可达的里面89 对一步105 对两步15 对三步最长的一条最短路是 8 步。不可达不代表机器人坏了只代表“这两个状态之间没有合法的物理路径”比如从躺姿直接到走跑规划器就会拒绝。4.2 谁有权动输入源仲裁状态对了只说明“这个动作合法”。谁有权发这个动作是另一套机制。机器人可能同时被手机 App、语音 Agent、实体遥控器、开发者程序控制。启元的做法是给每个控制源注册一个名字、一个优先级、一个超时时间由 MC 仲裁出当前唯一的主控。优先级分五档来源《接口说明》2.1.1.4档位优先级信源系统级100–80急停、安全保护、rc、pnc、interaction高级79–60实体遥控器、App 手动遥控、vr、app_proxy中级59–40语音指令、手势交互低级39–20SDK 二次开发、PNC 仿真备用19–0研发调试、低压测试、离线仿真规则有三条高优先级直接抢占同优先级先入为主当前主控不停后来者进不来每个源有 1000 ms 看门狗主控断了按优先级降序找下一个还活着的候补。要发速度开发者得先调SetMcInputSource用1001ADD注册一个源填name、priority、timeout。注册成功后源默认就是 Enable直接参与仲裁。之后每条速度消息的source字段必须和注册名完全一致否则帧会被静默丢弃。官方速度示例里这个注册写成了priority 80和rc、pnc、interaction同级而文档建议 SDK 二次开发用 39–20。这不是小差别同优先级是先入为主如果 SDK 先占锁遥控器后发反而抢不进来要等 SDK 停发 1000 ms 超时后才能接管。我在自己的会话里把优先级改成 30行为就回到文档描述的样子。示例代码大概率是为了让新手脚本“一跑就动”但抄进产品之前这一行值得改。这张时序图是我按文档规则写的离线仲裁器跑出来的Appp60先占锁SDK 节点p30在 300 ms 开始发一直被挡App 在 650 ms 停发看门狗到 1660 ms 才把锁释放给 SDK遥控器p802000 ms 介入立刻抢占2400 ms 遥控器停发3360 ms 超时锁又回到 SDK5160 ms SDK 也停了没有候补运动停止。两个细节值得记住。第一控制权是内存态。SetMcInputSource的增删改只写 RAM不回刷 YAML机器人重启动态注册的源就没了。所以程序启动时先 DELETE 再 ADD清掉上次异常退出留下的同名源。第二GetCurrentInputSource返回的是锁的归属不代表指令流还活着。主控超时后、还没有新抢占者之前接口依然返回旧主控的名字要自己记最后一帧的时间。4.3 动多快速度话题状态放行、控制权到手最后才是发速度。/aima/mc/locomotion/velocity的字段不多forward_velocity、lateral_velocity、angular_velocity、pitch_velocity、level外加header和source。约束有三条频率 50–100 Hz。官方示例用 50 Hz 定时器发低于这个频率1000 ms 看门狗会把控制权摘走高于这个频率没有额外收益。速度有死区。线速度绝对值要么是 0要么不低于 0.2 m/s角速度同理不低于 0.2 rad/s。文档的解释是低于硬件最低速度运行时关节容易抖动、异响整机为了维持平衡还会触发代偿反而更危险。source必须和注册名一致。名字写错、大小写不一致、用了内置名rc、pnc、interaction、vr、app_proxy帧会被静默丢弃或者和内置源互相冲刷。三个问题都答完MC 才会把速度指令翻译成关节目标。到这里“走过来”这件事在运动控制层就算完成了。五、智能层看人、听话、决定下一步运动控制层回答“怎么动”但“人去哪了”“该跟谁走”“用户刚才说了什么”不归它管。这一层的输入是传感器。Q1 配的是单目摄像头、环形麦克风、触摸传感器和 8 核处理器T1 Pro 多了 Orin Nano、5 组 ToF、双目摄像头和两颗鱼眼来源Q1 参数页、T1 参数页。输出则是几类接口语音识别结果走/aima/agent/asr_result话题播报走PlayTts服务表情走PlayEmotion触摸走/aima/hal/touch/state相机可以抓单帧CaptureJpegImage全链路 100–500 ms建议 1 fps或者拉 RTSP 流端口 2554。启元在发布会上公布了这一层的模型命名PrimeMotion 负责柔顺安全的小脑运控PrimeGo 负责多模态感知与跟随PrimeVista 负责多模态交互PrimeMind 是面向家庭场景的家务基座模型此外还有一个基于 Harness 架构的机器人 Agent来源新华网。需要区分的是这些是模型和产品的命名不是 SDK 里的接口名。SDK 给开发者的是“原始数据 服务”不是“模型内部”。比如你可以订阅 ASR 结果、调用 TTS、抓一帧图但 SDK 没有开放“目标检测”或“导航”的现成接口。官方carry-clothes技能在selfProvided里写得很直白目标检测和视觉伺服要开发者自己补默认的HeuristicDetector只是占位不产生结果。这是理解启元架构的一个关键智能层是产品能力运动层是开放能力。产品页上“看得见、听得懂、会跟随”是前者SDK 文档里“话题、服务、关节”是后者。两者之间有交集但不能画等号。六、技能层把动作串成任务用户不会直接调用 Agent他们装的是技能。启元的技能包格式叫 RPK入口是manifest.json。官方carry-clothes把衣服拿到洗衣机旁是一个很好的样本因为它的清单把“技能”这件事拆得很清楚runtimePython ≥ 3.10入口main:run启动前 source ROS2 和 SDK 环境capabilities逐条声明要用的接口比如SetMcInputSource的参数写死namecarry_clothes_skill, priority30, timeout1000速度话题写死minRateHz50, maxForward0.35, maxYaw0.5selfProvided明确写出 SDK 不提供、要开发者自建的能力这里是目标检测和视觉伺服safety最大前进速度 0.35 m/s、电量底线 20%搬运中 25%、关节限位钳制、动作间隔 500 ms、异常中止时平滑回正、必须设备端确认stages把任务拆成 10 个带超时的阶段从响应指令、切直立、走到用户跟前到抬臂、等待接衣、合臂、找洗衣机、前往、放下、完成。这份清单最值得借鉴的地方是它把“不能做什么”写在了安装之前。selfProvided里说得很清楚SDK 不提供目标检测不提供 SLAM/导航safety.notes里还有三句SDK 无夹爪接口接物是双臂合拢托住SDK 无 ASR 接口用户确认改用头部触摸事件上肢位姿是推算值上机前必须示教标定。这里的“无 ASR 接口”指的是技能运行时没有可调用的识别服务/aima/agent/asr_result话题仍然存在只是技能拿不到一次同步的识别结果。技能层不直接控制电机。它做的是任务编排什么时候切状态、什么时候发速度、什么时候播报、什么条件下中止。真正的控制仍然落在第 3 层。把这两层分开技能才能在没有真机的时候用 Mock 跑通也才能被审查、被打包、被分发。七、工具链与开发模式从读到跑五层讲完回到开发者这一侧。启元给的入口是 PrimeConsole一个跨 macOS、Windows、Linux 的桌面工作台能连机器人看视频和日志、控运动、跑仿真、验证技能。它本质上是一组标准 DDS 节点加图形界面不装它用ros2 topic list、rqt、rosbag也能做同样的事只是要自己配环境。仿真侧有官方 URDF、MuJoCo XML、Gazebo launch还有三套 Docker 工具链ARM 原生编译Orin / RK、x86 交叉编译 ARM、x86 原生编译。SDK 里直接带了 OpenCV 4.13.0 和 Ruckig 轨迹库的源码版本钉死减少“本地能跑、板上编译不过”的环境漂移。开发者模式分五层运行模式Standard / Develop、开发方式API / ROS2、开发层级Basic / Advanced、领域设置、能力配置。当前版本 API 方式没开放默认只支持 ROS2领域设置和能力配置暂时合并只生效“运动控制—低层运控开发”。Basic 和 Advanced 的差别不是权限多一点少一点而是接管方式不同。Basic 保持原厂业务和安全策略外部指令并发注入Advanced 允许关闭特定官方模块拿传感器裸流和底层运控的独占权。代价也写在文档里开启开发者功能后不再享受维保服务切模式要重新上下电。如果只想跑通一次“走过来”最短路径是五步ros2 node list确认节点GetMcAction确认当前状态SetMcInputSource注册一个 p30 的源50 Hz 发 0.2 m/s 走两秒零速度加DELETE收尾。真机先架空或平躺手边留急停。八、三处对不上的地方读到这儿你已经能把一条指令从头走到尾。但真上手时还有三处文档、枚举和示例代码对不上的地方值得提前知道。第一处官方速度示例把 SDK 源注册成了 p80。mc_locomotion_velocity.py第 149–151 行是name node、priority 80、timeout 1000第 16 行注释也写 “priority 80”而《接口说明》把“SDK 二次开发信号”放在 39–20。按示例抄SDK 和遥控器同级按文档写SDK 应该低一档。我倾向前者只是为了让新手脚本“一跑就动”产品里应该改成 30。第二处文档的状态图画了LYING_DEFAULT → STAND_UP代码的表里没有。《接口说明》2.1.1.1 的 mermaid 图里躺姿有一条指向站起的虚线但 Python 和 C 两份mc_action_switcher的_ACTION_RULES里LYING_DEFAULT只有STORE_DEFAULT一条出边而STORE_DEFAULT又不能当中间态。结果就是官方规划器认为“躺姿 → 走跑”不可达。这不等于底层状态机拒绝这条切换但意味着你按示例的规划器办事会在这一步停住。第三处状态图里有三个状态枚举表里没有。BIPED_WALK_RUN_DEFAULT、BIPED_GROUND_POSE、BIPED_RECORD_UPPER出现在_ACTION_RULES里McAction.msg的 Q1 枚举段却没有给它们数值。它们只能通过action_desc字符串下发不能靠action.value。反过来MIMIC、MIMIC_LINKCRAFT、MIMIC_OPENSOURCE等 7 个枚举又不在图里。三处差异指向同一件事这套 SDK 的权威顺序是“代码 枚举 文档图”。文档适合建立框架真正下发之前用ros2 service call和GetMcAction各验一次比抄示例稳。九、边界与取舍最后说说这套架构的边界。开放的层次是扎实的ROS2 Humble、FastDDS、标准 Topic/Service、URDF、MuJoCo、Docker没有私有格式接口给到了关节力矩、刚度、电池状态字这一级状态机、输入源、速度话题都有明确的错误码和超时。对做研究和做技能的人来说这是一套能落地的开放平台。没开放的部分也要说清楚没有导航、SLAM、语义地图没有夹爪接口没有现成的目标检测语音只给识别结果不给唤醒词和对话模型API 方式还没上线Advanced 模式会失去维保。社区里已经有人问 T1 Pro 的声纹、人脸识别结果从哪读问 Orin Nano 是 4GB 还是 8GB问音频通道为什么和文档对不上——这些问题恰好说明参数表之外开发者还需要一份“哪些有接口、哪些是黑盒、哪些要自己补”的边界文档。这套架构适合谁适合愿意按 ROS2 的方式做事、需要关节级控制、或者想把技能做成可分发包的人。它不适合想“装个 App 就能让机器人干活”的人——那部分工作在技能层和智能层SDK 只给到原料。十、再回到那条指令现在再看“走过来”这句话。技能层把它拆成阶段智能层判断人在哪运动控制层确认“现在允许走、我有权走、走多快”通信层把速度送到运控板本体层把电流变成力矩。走的过程中关节状态、电池、触摸事件又沿着相反的方向回到上层变成下一次判断。五层各管一段缺一层这句话就落不了地。如果你想自己走一遍SDK、URDF、桌面端 PrimeConsole、技能仓库都在启元机器人开发者社区dev.primebot.comAtomGit 组织是 atomgit.com/primebot。本文用到的状态图数据、仲裁模型、Mock 会话和 URDF 提取脚本整理在primebot-control-path仓库按 README 的顺序跑就能复现文中的输出。社区里已经有 Q1 仿真挥手、T1 搬运、语音叫车这些例子遇到问题先去论坛搜比从头啃文档快。参考资料启元 Q1 产品页https://www.primebot.com/q1.html启元 Q1 参数页https://www.primebot.com/product_spec4.html启元 T1 参数页https://www.primebot.com/product_spec1.html启元机器人开发者社区下载页https://dev.primebot.com/download启元 Q1 SDK v1.0.0.0《接口说明》《PrimeBot SDK 快速入门与集成指南》2026-10-10启元 Q1 URDF v1.0.0q1_v32026-09-24官方技能carry-clothes的manifest.jsonhttps://atomgit.com/primebot/carry-clothes新华网《启元个人机器人正式发售AI模型、生态布局同步公布》2026-09-22https://www.news.cn/tech/20260922/770e10d4acdb48ed865eee514b26e06d/c.htmlAtomGitx启元机器人具身智能原创内容征文活动#
