启元 Q1 到 T1 的 SDK 迁移：同一个编号，为什么含义变了？

对照Q1和T1的SDK时有一处差异特别容易漏掉两份TouchState.msg逐字节相同sensor_id1的意思却变了。Q1上是头部T1上是背部。两种解释就写在同一份文件的注释里。如果功能是“摸头后显示一个开心表情”代码从Q1搬到T1可能照常编译、照常进入回调甚至还能显示表情。只是触发它的部位已经换了。程序没有报错原来的产品要求却没保住。下面就沿着这个小功能核对输入、表情调用和动作定义三处差异。使用的都是Q1/T1 SDK v1.0.0.0文末给出可离线运行的核心判断。1. 文件相同为什么编号含义不同两包aimdk_msgs/hal/msg/TouchState.msg的内容逐字节一致。它们都有消息头、传感器编号sensor_id、事件类型event_type以及单击、双击和滑动等常量。但相同文件里恰好写着不同机型的解释Tid为1表示背部传感器id为2表示胸部传感器 Qid为1表示头部传感器字段类型没变取值也合法编译器当然查不出问题。它只认识这个字段能放一个编号至于编号指向哪块传感器要结合机型解释。回到我们的功能。第一版如果写成“编号1单击时播放开心表情”迁移后仍可能命中同一个分支。但产品想保留的究竟是什么如果意图是“摸头才回应”T1的编号1就不能直接替代Q1的编号1。如果意图是“用户主动触摸时友好回应”则可以针对T1重新选择背部、胸部中的哪些触摸算有效互动。前一个需求强调部位后一个强调交互意图代码看起来相似迁移决策却不同。后面的例子选择第二种需求主动触摸时友好回应。输入先按机型解释成身体部位再配置哪些部位触发欢迎。这样从Q1的摸头改成T1的背部触摸就是一项看得见的产品选择不会藏在同一个数字1后面。2. 传入两个表情最后只发出了一个触摸输入解释清楚后下一步是显示开心表情。两个SDK都有examples/python/play_emotion.py但默认值和回退时机不同。Q1示例把emotion_ids默认设为[10]。在表情模式下发送前会检查列表只要其中包含10就把整个待发送列表改成[3003]。T1示例默认设为[90]先尝试原始请求调用返回失败并且原列表中含90时再尝试[3003]。项目Q1 示例T1 示例默认表情列表[10][90]首次发送前表情模式且含10时整体改为[3003]尝试原始列表首次失败后该分支没有T1式的第二次尝试表情模式且原列表含90时再尝试[3003]例如在Q1示例中传入[10, 3004]最终发送的是[3003]不是[3003, 3004]。如果业务把这个列表当作一段连续表情编排后一个元素也随整体替换消失了。移植时只检查“接口是否存在”很难发现这样的行为。T1的先尝试、再回退则意味着一次业务请求可能对应两次服务调用。若只在业务入口打一条日志后面出了问题很难看出失败发生在哪次调用。更合适的记录方式是保留原始意图、首次实际发送值、返回结果以及是否进入回退。文件里还有一个值得注意的小矛盾T1回退分支的注释写“ID 10失败”代码实际检查90 in self.emotion_ids。阅读者如果只扫注释会得到另一套规则实际执行条件应以代码为准。所以业务层最好只提出“显示开心表情”具体编号由目标环境的配置提供。示例里的默认值和回退值可以拿来理解调用过程直接把它们搬成全项目的资源规则容易连同整体替换和失败重试一起搬过去。资源依据Q1文档列出3001—3013T1示例中的90只是尝试值。示例源码不能确认目标设备实际安装了哪些资源。3. 常量204在一份包里有效在另一份里被注释如果欢迎功能以后还想加一个转身或模仿动作就会接触McAction.msg。这份文件把急停、形态切换、四足、双足和Q系列动作放在不同区段里。结构很像常量却并不完全相同。T1包有效定义了int32 BIPED_LOCOMOTION_ROTATE_LOCAL 204Q1包的对应位置是# 双足原地旋转(删除) # int32 BIPED_LOCOMOTION_ROTATE_LOCAL 204反过来Q1包末尾有有效的MIMIC_V21018与MIMIC_OPENSOURCE_V21019T1包中没有这两个定义。只使用一份SDK开发再把“有这个常量”的假设带到另一份包就可能在很早的构建阶段碰到问题。但更隐蔽的风险来自两边都有的定义。两份文件都包含四足动作区段Q1是人形机器人文件里存在四足枚举不能据此推断它具备对应的四足执行能力。协议可能表达多个产品共用的命令集合具体设备只实现其中一部分。要接这类动作检查就得往下多走两步目标包有定义之后还要确认设备支持再确认当前状态允许执行。否则找到一个常量名距离真正做出那个动作仍然很远。图 1两份SDK的静态证据。上层共享命名和协议框架下面分别列出字段语义、示例路径及枚举定义差异图中的常量不作为真机能力清单。4. 三处核对得到了什么读者可以从官方页面下载两包v1.0.0.0按前文的文件路径逐项核对。我用离线脚本比较了触摸文件的哈希通过Python语法树读取表情默认参数再扫描三个动作常量是否为有效定义。得到的主要结果如下核对项Q1T1TouchState.msg文件内容两者一致两者一致表情默认列表[10][90]BIPED_LOCOMOTION_ROTATE_LOCAL无有效定义204MIMIC_V21018无有效定义MIMIC_OPENSOURCE_V21019无有效定义以后升级SDK这几项也值得再查一次。默认值变了就重看首次发送和失败回退动作常量变了就找出依赖它的业务。比起拿所有功能从头试一遍这张差异表能先缩小范围。脚本检查文件哈希、默认参数和有效枚举表情回退路径由源码阅读核对设备资源与动作能力仍须运行验证。5. 用同一个函数处理两台机器前面的问题落到代码里其实不用做一个很大的框架。把输入部位和输出资源各翻译一次中间保留同一段欢迎逻辑就够这个例子使用。输入端结合明确的机型配置把原始触摸编号解释成部位与事件。共享业务层只判断“这是不是当前欢迎流程允许的有效触摸”再产生“表达开心”的意图。输出端根据目标机型和版本查找已确认的资源然后通过该设备对应的SDK调用服务。图 2本文提出的应用结构不是官方SDK内置组件。机型配置负责解释输入和选择资源公共业务逻辑处理互动意图。未知资源不在图中被自动视为可用。欢迎流程只用“有效触摸”和“开心表情”这两个概念。编号、SDK版本及资源确认记录放进设备配置服务调用结果再交回来。后面即使换了资源也不必沿着所有业务分支找数字。把这条路径缩成Python代码核心判断只需要输入映射、业务条件和资源查询defplan_reply(sensor_parts,accepted_parts,resources,sensor_id,event):partsensor_parts.get(sensor_id)ifpartisNone:returnunknown_sensor,Noneifevent!single_taporpartnotinaccepted_parts:returnignored,Noneresourceresources.get(happy)ifresourceisNone:returnresource_unmapped,Nonereturnready,resourceQ1的部位映射填{1: head}T1填{1: back, 2: chest}。两种配置交给同一个函数输入先得到部位含义再经过业务判断最后查找资源。返回ready后调用层才继续处理输出。本例选择Q1头部单击、T1背部单击触发欢迎。这个选择属于我们的产品规则T1胸部传感器仍可被识别但暂不触发这段互动。三个主要用例的结果如下输入与配置业务判断输出Q1编号1单击已有演示资源映射头部触摸有效记录Q1开心资源T1编号1单击未配开心资源背部触摸有效资源缺失resource_unmapped不记录播放T1编号1单击补上演示资源映射背部触摸有效记录T1开心资源演示使用的demo:q1:happy和demo:t1:happy是虚构测试资源名不是设备IDsingle_tap是应用解码后的统一事件标签。程序不导入SDK、不连接设备。中间一行是这段实现最有用的地方。背部触摸已识别欢迎规则也允许最后卡在资源缺失。此时应当补映射输入和业务逻辑都不用动。“没有回应”终于有了一个具体原因。把调用写出来缺少映射和补齐映射的差别就更直观t1_parts{1:back,2:chest}print(plan_reply(t1_parts,{back},{},1,single_tap))# (resource_unmapped, None)print(plan_reply(t1_parts,{back},{happy:demo:t1:happy},1,single_tap))# (ready, demo:t1:happy)离线演示还检查了胸部触摸未获业务允许、未知传感器和双击三种情况。它们分别停在自己的判断位置因此“没有回应”可以沿路径查清原因。真正接设备时资源配置换成目标环境确认过的ID收到ready后由调用层通过对应SDK服务发起请求并检查服务回执。这个替换把设备差异留在两端欢迎逻辑仍然使用“有效触摸”和“表达开心”这样的业务概念。6. 最后到设备上确认什么离线用例已经能检查部位映射、欢迎规则和资源缺失分支。接上目标设备之后再确认触摸实际来自哪个部位、所选表情是否存在、服务失败时返回什么。几种结果要和前面的分层对应起来别最后又统统记成“播放失败”。这次对比里最值得提前处理的是sensor_id1这样的语义差异。少了一个常量程序可能直接报错编号含义变了程序却能一路跑下去直到人觉得“怎么碰这里也有反应”才暴露出来。把身体部位和资源映射写清楚改动并不大。它让“摸一下笑一下”先在两台机器人上各自成立共享代码才有实际意义。验证范围本文完成SDK静态比较及离线分支演示未连接真机。各设备应使用匹配的SDK构建环境同名包不构成两份消息包混装或整体二进制兼容的证据。依据启元官方SDK下载中Q1/T1 v1.0.0.0的TouchState.msg、play_emotion.py、McAction.msg与接口说明机型参考Q1官方产品页。欢迎在启元开发者社区交流跨机型开发经验。