📚 课程目录第2章 RSI 对象模型与 XML 通信

2. RSI 对象模型与 XML 通信

RSI（Robot Sensor Interface）并不是一组可以直接调用的函数库，而是一套以 XML 描述、按固定周期交换数据的实时通信框架。理解它的关键，是先建立“对象树”这一心智模型：控制器与外部系统各自持有一棵由 <ROOT> 派生的对象树，树上的每个节点都是一个具有类型、名称和参数的对象，节点之间通过父子关系组织，数据则沿着这棵树按周期流动。只有先看清对象树的结构，才能理解 SEN/CMD 为什么这样命名、XML 为什么这样组织、周期报文为什么这样打包。

一、RSI 对象树：一切通信的骨架

RSI 对象树由三类角色构成：容器对象、信号对象和功能对象。容器对象如 ROOT、CONTAINER，只负责组织层级，不产生数据；信号对象如 SEN、CMD，是数据进出的端点；功能对象如 AXISCORR、RKorr、PID、MAP、GENERATOR，负责对信号做运算、映射或生成。对象树是“静态结构”，它决定了每个周期里哪些数据被读取、哪些被写入、哪些被计算。

一个典型的 RSI 对象树根节点是 <ROOT>，其下通常挂一个 <CONTAINER> 作为逻辑分组，再在容器内并列放置 <SEN> 与 <CMD>。SEN 是 Sensor 的缩写，表示“从机器人控制器流向外部系统”的数据；CMD 是 Command 的缩写，表示“从外部系统流向机器人控制器”的数据。方向约定必须牢记：SEN 是控制器输出、外部接收；CMD 是外部输出、控制器接收。这一约定在整门课程中保持一致，后续所有图示与代码都遵循它。

二、SEN 与 CMD：数据流的方向与语义

SEN 对象负责把控制器内部状态“暴露”给外部。常见类型包括 AXIS（关节角或笛卡尔位姿）、RKorr（当前修正量）、FRAME（坐标系）、DIGITAL（数字 IO）。每个 SEN 对象在 XML 中通过 type 和 name 声明，外部系统按名称读取对应数值。CMD 对象则相反，它把外部计算出的修正量、使能位或控制字写回控制器，典型类型有 AXISCORR（关节修正）、RKorr（笛卡尔修正）、DIGITAL（数字输出）。

需要特别注意的是，SEN 与 CMD 并不是“同一变量的两个方向”，而是两组独立声明的端点。例如控制器可以同时声明一个 SEN type="AXIS" name="A1" 和一个 CMD type="AXISCORR" name="K1"，前者报告当前关节角，后者接收外部叠加的关节修正量。二者在对象树中并列，互不覆盖。理解这一点，才能正确设计“读状态—算修正—写回”的闭环。

三、XML 结构解析：从文本到对象树

RSI 的 XML 文件通常以 <ROBOT> 或 <ROOT> 为根，内部用 <CONTAINER> 分组，再逐层放置 SEN、CMD 和功能对象。一个最小可用的结构如下：

<ROOT>
  <CONTAINER name="RSI_Demo">
    <SEN type="AXIS" name="AxisPos" />
    <CMD type="AXISCORR" name="Corr" />
    <GENERATOR name="Gen" type="SINE" amplitude="2.0" frequency="0.5" />
  </CONTAINER>
</ROOT>

解析时，控制器按深度优先遍历对象树：先建立容器，再实例化每个子对象，最后把 SEN 与 CMD 注册到周期通信表中。外部系统收到 XML 后，同样解析出对象名称与类型，建立“名称—数值”映射。解析结果必须与控制器侧一致，否则会出现“名称对不上、数据读不到”的典型故障。因此，XML 文件应作为双方共享的接口契约，而不是只放在控制器里。

四、周期报文组织方式

RSI 以固定周期（常见 4 ms、8 ms、12 ms）交换报文。每个周期内，控制器先采集所有 SEN 对象的值，按对象树顺序打包成一帧发送给外部；外部解析后计算 CMD 值，再按同样顺序打包回传。报文本身不携带 XML 文本，而是二进制或紧凑格式的“值序列”，顺序由对象树决定。这意味着：对象树中 SEN/CMD 的排列顺序，就是报文中数值的排列顺序。如果中途增删对象，双方必须同步更新 XML，否则整帧错位。

周期时间的选择需要权衡：周期越短，实时性越好，但对 CPU 和网络负担越大；周期越长，控制越平滑但响应变慢。工程上常从 12 ms 起步，稳定后再逐步缩短。判断周期是否合适，可以观察 CMD 修正量是否出现明显阶梯或滞后，以及控制器是否报通信超时。

五、最小通信闭环搭建

搭建最小闭环的目标是：让控制器把一个 SEN 值发出去，外部原样或简单处理后写回 CMD，控制器能收到并确认。建议按以下顺序操作：

在控制器侧创建 RSI 对象树 XML，只保留一个 SEN type="AXIS" name="AxisPos" 和一个 CMD type="AXISCORR" name="Corr"，先不加功能对象。
把 XML 复制到外部系统，用同一份文件解析，确保名称与顺序完全一致。
外部程序每个周期读取 SEN 的 6 个关节角，写入日志；同时把 CMD 的 6 个修正量先全部置 0，回传。
启动 RSI，观察控制器是否进入 RSI 模式、外部是否持续收到报文、周期计数是否递增。
确认稳定后，再把 CMD 的某个分量改为一个小幅正弦值（例如幅度 0.5°、频率 0.2 Hz），观察机器人是否产生对应微动。

判断闭环是否真正建立，不看“程序是否运行”，而看三个证据：外部每周期都能收到 SEN 且数值随机器人姿态变化；控制器能收到 CMD 且不报超时；修改 CMD 后机器人产生可观察的、方向正确的微动。三者同时成立，才说明 SEN/CMD 方向、名称映射和周期顺序都正确。

常见错误是把 SEN 和 CMD 的方向写反，或在外部解析时按字母顺序而非对象树顺序读取。前者会导致控制器收不到修正量，后者会导致关节数据错位。排查时优先核对 XML 中对象的出现顺序，再核对外部读取索引。

完成最小闭环后，对象树就可以逐步扩展：加入 GENERATOR 产生测试信号，加入 PID 做闭环调节，加入 MAP 做坐标映射。但无论扩展多少对象，SEN/CMD 的方向约定、XML 的共享契约、周期报文的顺序一致性这三条始终不变。它们是 RSI 通信的底层规则，也是后续所有实时控制逻辑的起点。