简介：面向UR（优遨）机器人开发者与自动化集成工程师的RTDE接口技术手册，聚焦如何通过标准TCP/IP连接将外部程序与UR控制器同步，同时不破坏控制器实时属性，适用于现场总线驱动交互、机器人I/O操作与轨迹状态绘制等场景。压缩包内为1份PDF文档，约226KB，篇幅精炼，便于随查随用。内容系统梳理RTDE的关键特性、输入输出字段名称与数据类型，并逐项讲解协议报文，包括Header、协议版本请求、控制器版本获取、文本消息（协议v1/v2）、数据包以及输出/输入控制包的设置、启动与暂停等返回流程，还说明了设置阶段与同步循环两阶段机制及recipe配方概念。已有929人学习，适合需要精确控制与实时反馈的工业应用开发者作为协议对照与联调参考。

1. RTDE 的真相：125Hz 不是承诺，而是一个上限

很多人第一次接触 UR 机器人的实时数据交换接口，都会默认一件事：既然叫“实时”，那它应该像心跳一样稳定地每 8 毫秒推一帧数据过来。实际跑起来才发现，帧间隔会抖，偶尔还会丢几帧，于是开始怀疑是不是网络有问题、是不是 TCP 缓冲没调好。这个直觉恰恰是理解 RTDE 的第一道坎——RTDE 的 125Hz 输出频率从来不是一个硬承诺，而是一个“尽力而为”的上限。控制器内部的实时控制环优先级高于 RTDE 接口本身，当计算资源紧张时，控制器会直接跳过若干输出包，而且跳过的包不会补发，你收到的永远是“最新鲜”的那一份数据。搞懂这个设计动机，比调任何参数都重要，因为它决定了你后面所有关于时序、丢帧、输入生效时机的判断逻辑。

2. 两阶段设计：为什么 RTDE 要先“配菜”再“上菜”

RTDE 把整个通信生命周期切成两个截然不同的阶段：setup（设置）和 synchronization loop（同步循环）。这个切分不是随手为之，而是整个协议能在标准 TCP/IP 上跑出实时感的关键。设置阶段是“慢”的、带返回值的、可以反复协商的；同步循环阶段是“快”的、单向的、不带任何确认的。理解了这条分界线，你才能明白为什么有些操作只能在连接初期做，为什么运行中改不了配方。

2.1 配方（recipe）：把字段名列表变成二进制布局

设置阶段的核心动作，是客户端向控制器提交一份“配方”——一份它想读或想写的字段名列表。控制器收到后，会按你给的顺序把这些字段的类型解析出来，回给你一份类型清单，同时给每个成功配置的输入配方分配一个唯一的 recipe id。这里有个容易被忽略的硬约束：字段名列表的序列化表示上限是 2048 字节。也就是说，你订阅的字段不是无限的，字段名越长、数量越多，越容易撞到这个天花板。

为什么是“按请求顺序”返回数据？因为同步循环阶段控制器不再发送任何字段名，只发裸的二进制值。客户端必须自己记住“第 1 个字段是 actual_q，占 6 个 DOUBLE，第 2 个字段是 actual_TCP_pose……”这种布局。配方本质上就是一份双方共同持有的“数据契约”，把冗长的字段名在设置阶段一次性交换掉，同步阶段只传值。这是典型的用一次性协商换持续带宽的做法，也是很多工业协议共通的思路。

常见的实现思路是：客户端在 setup 时把字段名列表序列化成一个字符串数组发过去，控制器逐项查表校验，找不到的字段会在返回里明确标出“未找到”，而不是静默丢弃。这一点很关键——它让你在连接建立的第一秒就能发现拼写错误，而不是等到同步循环跑起来发现数据对不上。

2.2 同步循环：单向数据流与“最后值保持”

进入同步循环后，协议的性格完全变了。控制器按配方顺序、以序列化二进制形式持续推送输出数据；客户端则在输入值发生变化时，把更新后的输入发回去。注意这里的关键词是“变化时”，不是“每个周期”。输入没有固定更新速率的要求，控制器会一直保持你最后一次发来的值。这带来一个很实用的自由度：你可以一条消息更新全部输入，也可以每个变量一条消息，甚至只在真正需要改的时候才发。

但自由度背后有一条铁律：同一个变量，任意时刻只允许一个 RTDE 客户端控制。如果你有两个客户端都想写 standard_analog_output_0，后写的会覆盖先写的，而且没有任何冲突提示。这个限制在多进程协作的场景里是血泪经验级别的坑，后面避坑章节会展开。

输入包的处理时机也值得说清楚：输入包总是在它被收到的那个控制周期内处理，所以控制器负载会随你发送的包数量波动。你发得越碎、越频繁，控制器在解析输入上花的力气就越多。这和输出侧的“跳过不补发”形成了一组不对称的设计——输出可以丢，输入不能等。

2.3 协议版本协商：给未来留的后悔药

RTDE 协议本身会随控制器固件演进而增补字段和消息类型。为了让老客户端不至于在新控制器上直接翻车，协议允许客户端在连接初期请求一个特定的协议版本。所有协议增补和变更都会被显式标注，没有标注的地方默认按版本 1 理解。这个机制的价值在于：你的客户端可以锁定在自己验证过的版本上，控制器侧则负责向下兼容地响应。对于要长期部署在产线上的程序，这相当于一颗后悔药——固件升级后，只要版本协商还认你的请求，行为就不会莫名其妙地变。

3. 报文结构：一个 Header 撑起所有消息类型

RTDE 所有报文共享同一个通用结构：一个固定长度的 header，加上可选的 payload。设置阶段的消息会带回包，同步循环阶段的消息不带。这种“统一信封 + 差异化内容”的设计，让解析器可以先读固定字节数的头，再根据头里的信息决定后面怎么读，避免了流式解析里最常见的粘包判断难题。

3.1 Header 的字段布局与大小端陷阱

Header 里承载的是消息类型、payload 长度这类元信息。这里必须强调一个几乎每个新手都会踩的点：RTDE 的数据一律使用网络字节序，也就是大端序。如果你直接从 socket 读原始字节然后按本机小端去解，得到的会是完全错乱的数值——一个正常的关节角度可能变成一个天文数字。Python 的 struct 模块里，格式串前缀用>表示大端，用<表示小端，这个字符写错，后面全盘皆输。

import struct # RTDE 报文头：3 字节消息类型 + 1 字节填充 + 8 字节 payload 长度 # 全部按网络字节序（大端）解析 HEADER_FMT = ">HBQ" # H=uint16 类型, B=uint8 填充, Q=uint64 长度 HEADER_SIZE = struct.calcsize(HEADER_FMT) # 11 字节 def parse_header(raw: bytes): if len(raw) < HEADER_SIZE: raise ValueError("header 不完整，继续收") msg_type, _, payload_len = struct.unpack(HEADER_FMT, raw[:HEADER_SIZE]) return msg_type, payload_len

上面这段代码里，>HBQ三个字符分别对应消息类型、一个填充字节、payload 长度。填充字节的存在是为了让后续字段对齐，解析时不能跳过不读，否则偏移全错。calcsize算出来的 11 字节就是你必须先攒够的最小长度——不够就继续从 socket 收，够了再决定 payload 要读多少。这个“先读头、再读体”的两段式读取，是所有基于长度前缀的协议解析的通用骨架。

3.2 数据类型的位宽与 VECTOR 的展开规则

RTDE 定义了一套精简的数据类型：BOOL 占 8 位（0 为假，非 0 为真）、UINT8/UINT32/UINT64、INT32（二进制补码）、DOUBLE（IEEE 754 双精度）、VECTOR3D（3 个 DOUBLE）、VECTOR6D（6 个 DOUBLE）、VECTOR6INT32（6 个 INT32）、VECTOR6UINT32，以及变长的 STRING（ASCII 字符数组）。这套类型系统直接决定了配方解析时每个字段占多少字节。

以actual_q为例，它是 VECTOR6D，展开就是 6 个 64 位 DOUBLE，共 48 字节。robot_mode是 INT32，4 字节。actual_digital_input_bits是 UINT64，8 字节。你在客户端里维护的偏移量表，就是把这些位宽按配方顺序累加出来的。一旦某个字段的类型记错——比如把safety_status当成 UINT32 而它实际是 INT32——虽然位宽一样不会错位，但符号位解释会出错，负值场景下就会翻车。

提示：STRING 类型是唯一变长的，长度由字符数组实际长度决定。配方里如果混入 STRING，偏移量计算就不能用固定累加，必须逐项按实际长度推进。

3.3 控制包与数据包的分工

协议里的消息类型可以分成两组。控制类包括请求协议版本、获取控制器版本、设置输出配方、设置输入配方、启动、暂停，这些都在设置阶段使用，且都期待一个返回。数据类是 RTDE_DATA_PACKAGE，只在同步循环里出现，不带返回。文本消息 RTDE_TEXT_MESSAGE 则比较特殊，客户端和控制器双方都可以在任何时刻发送，用警告级别字段标明问题严重程度。

这种分工的意义在于：设置阶段需要可靠性，所以每条控制包都有明确的返回，客户端可以据此判断成功与否；同步阶段需要低开销，所以数据包不带任何确认，靠 TCP 本身的可靠传输兜底，同时用“跳过不补发”来保证数据新鲜度。可靠性交给 TCP，实时性交给“只发最新”，这是 RTDE 在标准 TCP/IP 上做实时同步的核心取舍。

4. 输入输出字段：寄存器分区背后的资源分配逻辑

RTDE 的字段清单看起来很长，但真正需要记住的不是每个字段的名字，而是它背后的分区规则。控制器把通用寄存器切成“下半区”和“上半区”，下半区留给现场总线/PLC 接口使用，上半区才开放给外部 RTDE 客户端（比如 URCAPS 应用）。这个划分直接决定了你该用哪个寄存器编号，用错了要么写不进去，要么和总线驱动打架。

4.1 输入侧：掩码机制与寄存器分区

输入侧最典型的是数字输出和模拟输出的控制。standard_digital_output_mask是一个位掩码，配合standard_digital_output使用：掩码置 1 的位，才会用对应的输出值去更新。这种“掩码 + 值”的双字段设计，让你可以只改某几位而不影响其他位，避免了读-改-写的竞态。模拟输出同理，standard_analog_output_mask的 bit0-1 分别对应两个模拟输出通道，standard_analog_output_type则决定每个通道是电流（mA）还是电压（V）域。

通用寄存器方面，布尔输入寄存器 0-63 中，0-31 和 32-63 这两段被保留给现场总线/PLC 使用，64-127 这 64 个才开放给外部 RTDE 客户端。整数和双精度寄存器各 48 个，0-23 保留给总线，24-47 开放给外部客户端。这个分区不是建议，是硬边界——你往保留区写，行为是不确定的。

# 构造一条输入更新：只改标准数字输出的第 0 位 # mask 置 1 表示“这一位我要管”，value 给出目标电平 mask = 0b00000001 value = 0b00000001 # 按配方顺序序列化，注意大端 payload = struct.pack(">BB", mask, value) # 前面拼上 RTDE_DATA_PACKAGE 的 header 后发送

这段代码展示了掩码的用法：mask 的第 0 位置 1，表示本次只更新第 0 号标准数字输出；value 的第 0 位给 1，表示把它拉高。其余位因为 mask 为 0，控制器不会去动。参数说明上，mask 和 value 的位宽必须和字段类型一致（这里是 UINT8），序列化时同样走大端。

4.2 输出侧：状态快照与位域解读

输出侧的字段本质上是控制器状态的一份快照。关节层面有actual_q、actual_qd、actual_current、joint_temperatures；笛卡尔层面有actual_TCP_pose、actual_TCP_speed、actual_TCP_force；安全层面有safety_mode、safety_status、safety_status_bits；I/O 层面有actual_digital_input_bits、actual_digital_output_bits、analog_io_types等。

位域字段需要特别小心解读。robot_status_bits的 bit0-3 依次表示是否上电、程序是否运行、示教按钮是否按下、电源按钮是否按下。safety_status_bits的 bit0-10 覆盖正常模式、缩减模式、保护性停止、恢复模式、安全防护停止、系统急停、机器人急停、急停、违规、故障、安全停止等状态。这些位是并列的布尔标志，不是互斥的枚举值，解读时要逐位判断而不是当成一个整数去比较。

actual_TCP_pose的旋转部分是旋转向量表示（rx, ry, rz），不是欧拉角也不是四元数。actual_TCP_speed的线速度单位是 m/s，旋转部分的角速度单位是 rad/s。actual_TCP_force是广义力，已经补偿了负载产生的力和力矩——如果你要的是未补偿的原始测量，得用ft_raw_wrench（较新固件才提供）。这些单位差异在绘图或做力控时是必须对齐的，混用会导致数量级错误。

4.3 版本标注：字段可用性的时间线

字段清单里大量字段带有“Introduced in version”标注，比如safety_status是 3.10.0 / 5.4.0 引入，elbow_position是 3.5.0 / 5.0.0，ft_raw_wrench是 5.9.0。这些标注不是装饰，而是你判断兼容性的依据。一个在旧固件上跑得好好的客户端，订阅了新字段后可能在旧控制器上直接 setup 失败。稳妥的做法是：在设置阶段根据控制器版本动态裁剪配方，而不是写死一份字段列表。

5. 避坑与排查：那些让同步循环“看起来正常”的陷阱

RTDE 最迷惑人的地方在于，很多错误不会让程序崩溃，而是让数据“看起来差不多但就是不对”。下面几条是实际调试中最常撞上的，每条都按现象、原因、解决来拆。

5.1 现象：数值全是天文数字或负数乱跳

原因几乎总是字节序。RTDE 强制大端，而 x86 主机是小端，直接用本机字节序解 DOUBLE 会得到完全错误的浮点值。另一种可能是字段偏移算错——某个 VECTOR6D 被当成 VECTOR3D，后面所有字段整体错位。

解决：统一用>前缀的 struct 格式串，并在客户端里维护一份按配方顺序累加的偏移表，每加一个字段就打印一次累计偏移，和预期总长度对一遍。总长度对不上，说明类型表有错。

5.2 现象：输入写进去没反应，或者过一会儿被改回去

原因通常是两个客户端在抢同一个变量。RTDE 规定同一变量任意时刻只允许一个客户端控制，但没有冲突报错。另一个可能是你写了保留区（比如整数寄存器 0-23），那一段归现场总线管，你的写入不生效。

解决：梳理所有会写输入的进程，确保每个变量只有一个写入方；寄存器编号严格用开放区（布尔 64-127、整数/双精度 24-47）。如果确实需要多方协作，让一方做“写代理”，其他方通过它间接更新。

5.3 现象：输出帧率远低于 125Hz，且间隔不均匀

这不一定是 bug。控制器实时环优先级高于 RTDE，资源紧张时会跳过输出包且不补发。如果你的客户端还在同步循环里做重计算（比如每帧都做图像处理），会进一步加剧抖动。

解决：把重计算移出接收线程，接收线程只做“收包 + 入队”，另起线程消费。计算密集的进程放到外部 PC 上跑，别和控制盒抢 CPU。同时确认客户端以标准操作系统优先级运行，不要盲目提权。

5.4 现象：setup 阶段返回“字段未找到”，但字段名明明在文档里

原因多半是固件版本低于该字段的引入版本，或者字段名拼写和大小写不完全一致。RTDE 的字段名是精确匹配的，actual_q写成actual_Q就会失败。

解决：先调RTDE_GET_URCONTROL_VERSION拿到控制器版本，再对照字段的引入版本裁剪配方。拼写问题用“逐字段单独 setup”的方式二分定位，比一次性提交整份配方更容易找到罪魁祸首。

5.5 现象：文本消息里冒出警告，但程序逻辑没报错

RTDE_TEXT_MESSAGE 是双方都能随时发的旁路通道，警告级别标明严重程度。很多实现只处理数据包，把文本消息直接丢弃，结果控制器已经在提示某个配置有问题，客户端却浑然不觉。

解决：在接收循环里把文本消息单独解析出来并记录日志，至少按警告级别分级输出。这条通道是排查“玄学问题”时最直接的线索来源。

6. 设计取舍：为什么 RTDE 敢在 TCP 上做“实时”

把 RTDE 的设计摊开看，它其实做了一组非常清醒的取舍。TCP 本身不保证低延迟，但保证有序可靠；实时控制环不能被外部通信拖慢，所以 RTDE 选择“跳过不补发”，用数据新鲜度换确定性；设置阶段用带返回的控制包保证配置正确，同步阶段用无返回的数据包压低开销；输入侧允许变速率、保持最后值，输出侧则尽力推送最新快照。这些选择单独看都不稀奇，组合起来才构成了一个在标准 TCP/IP 上“够实时”的接口。

我一般会这么理解它的边界：RTDE 适合做状态同步、I/O 操控、轨迹绘制、与现场总线驱动对接这类“需要及时但不要求硬实时”的场景。它不适合承担安全功能，也不适合替代控制器内部的实时控制环。判断一个需求能不能交给 RTDE，我会问三个问题：数据晚几十毫秒能不能接受？丢一帧用下一帧顶上有没有问题？这个变量是不是只有我一个写入方？三个都过得去，才放心上。

验证方法上，与其盯着“是不是严格 125Hz”，不如盯两件事：一是输出数据的时间戳timestamp是否单调递增且间隔合理，二是输入写入后控制器侧的回读字段（比如input_bit_registers系列）是否在预期周期内反映出来。这两条能覆盖绝大多数“看起来正常实则错位”的情况。

从那以后我每次接一个新的 RTDE 客户端，都会先把配方字段的偏移表打印出来逐项核对，再跑一段空载同步循环看时间戳分布，最后才接业务逻辑。这个习惯帮我省掉了太多“数据不对但不知道错在哪”的黑匣子时刻。希望帮到你。

本文还有配套的精品资源，点击获取