📚 课程目录第2章搭建RTDE开发环境

2. 搭建RTDE开发环境

RTDE（Real-Time Data Exchange）是UR控制器对外提供的高频数据交换接口，默认监听TCP 30004端口，采用二进制协议，典型控制周期为2ms（500Hz）或4ms（250Hz）。要让上位机与UR建立RTDE会话，第一步不是写代码，而是把"上位机—网络—控制器"这条链路打通。本节围绕三种典型连接方式、网络参数配置、客户端库安装、最小可运行示例以及常见故障排查展开。

一、三种连接方式与适用场景

RTDE客户端与UR控制器的连接方式取决于你使用的是真实控制器还是仿真器：

真实UR控制器直连：上位机网口与UR控制柜LAN口用网线直连，或经交换机接入同一网段。控制器默认IP通常为192.168.1.10（e系列/UR20等新机型出厂可能为192.168.1.10或通过示教器PolyScope设置为其他值），子网掩码255.255.255.0。上位机需配置同网段静态IP，例如192.168.1.100。
URSim仿真器：UR官方提供基于VirtualBox或Docker的URSim镜像。VirtualBox版本默认使用NAT+Host-Only双网卡，Host-Only网卡IP通常为192.168.56.101，此时上位机应配置192.168.56.x网段；Docker版本可用-p 30004:30004映射端口，上位机直接连127.0.0.1。
远程/跨网段连接：控制器与上位机不在同一网段时，需要路由器或三层交换机做路由，并确保30004端口可达。跨公网场景不建议直接暴露RTDE端口，应通过VPN或SSH隧道转发。

无论哪种方式，RTDE都要求上位机能与控制器30004端口建立稳定的TCP连接，且网络往返延迟尽量低——RTDE本身不做重传补偿，延迟抖动会直接反映在数据时间戳上。

二、网络配置要点

网络配置的核心是让上位机与控制器处于可互通的IP层，并保证30004端口不被防火墙拦截。以Windows上位机连接真实UR控制器为例：

在"网络和共享中心 → 更改适配器设置"中找到连接控制器的网卡，右键属性 → IPv4 → 使用下面的IP地址，填入192.168.1.100，掩码255.255.255.0，网关留空（直连场景）。
打开命令提示符，执行ping 192.168.1.10确认ICMP可达。若ping不通，先检查网线、网口指示灯和IP是否同网段。
用telnet 192.168.1.10 30004或PowerShell的Test-NetConnection 192.168.1.10 -Port 30004测试端口。若ping通但端口不通，通常是控制器RTDE服务未启用或防火墙拦截。

URSim的VirtualBox版本需要特别注意：默认网络模式为NAT时，上位机无法直接访问仿真器；应在VirtualBox设置中为虚拟机添加"仅主机(Host-Only)网络"适配器，并在URSim的PolyScope中把网络配置为Host-Only网段（如192.168.56.101）。Docker版本则通过端口映射解决：

docker run -d --name ursim \
  -p 30004:30004 -p 29999:29999 -p 30001:30001 \
  universalrobots/ursim_e-series

此时上位机连接127.0.0.1:30004即可。注意Docker Desktop在Windows/Mac上通过虚拟网卡转发，延迟略高于直连，做高频控制验证时需留意。

三、RTDE客户端库安装

UR官方提供Python和C++两种RTDE客户端库。Python版本安装最简便，适合快速验证：

# 方式一：pip 安装官方包
pip install ur-rtde

# 方式二：从GitHub克隆源码
git clone https://github.com/UniversalRobots/RTDE_Python_Client_Library.git
cd RTDE_Python_Client_Library
pip install .

C++版本需要CMake编译，依赖Boost。安装完成后，Python中执行import rtde不报错即表示库可用。若使用ur_rtde（第三方封装，接口更友好），可执行pip install ur_rtde，它同时提供RTDEReceiveInterface和RTDEControlInterface两个类。

四、最小可运行连接示例

下面是一个读取机器人实际关节角的最小示例，使用官方rtde库：

import rtde.rtde as rtde
import rtde.rtde_config as rtde_config
import time

ROBOT_IP = "192.168.1.10"   # URSim 可改为 127.0.0.1
PORT = 30004

# 1. 建立连接
con = rtde.RTDE(ROBOT_IP, PORT)
con.connect()

# 2. 获取控制器RTDE版本
print("RTDE version:", con.get_controller_version())

# 3. 配置输出配方：读取实际关节角
conf = rtde_config.ConfigFile("record_configuration.xml")
output_names, output_types = conf.get_recipe("out")

con.send_output_setup(output_names, output_types, frequency=125)
con.send_start()

# 4. 周期读取
try:
    while True:
        data = con.receive()
        if data is not None:
            print("actual_q =", [round(q, 4) for q in data.actual_q])
        time.sleep(0.008)
except KeyboardInterrupt:
    con.send_pause()
    con.disconnect()

配套的record_configuration.xml内容如下，它定义了输出配方中要读取的变量：

<?xml version="1.0"?>
<rtde_config>
  <recipe key="out">
    <variable name="actual_q" type="VECTOR6D"/>
    <variable name="actual_TCP_pose" type="VECTOR6D"/>
    <variable name="timestamp" type="DOUBLE"/>
  </recipe>
</rtde_config>

运行后若终端持续打印关节角，说明RTDE会话已正常工作。若con.connect()返回False，说明TCP层未连通，应回到网络配置排查；若连接成功但receive()一直返回None，通常是配方变量名拼写错误或频率设置超出控制器允许范围。

五、常见连接故障排查

现象	可能原因	排查方法
connect() 返回 False	IP不通或端口未监听	ping + Test-NetConnection 30004
连接被拒绝 (Connection refused)	RTDE服务未启用	示教器 → 设置 → RTDE，确认已开启
连接超时	防火墙拦截或跨网段路由缺失	临时关闭防火墙测试，检查路由表
receive() 持续返回 None	配方变量名错误或频率超限	核对XML变量名，频率降至125Hz测试
数据时间戳抖动大	网络延迟高或上位机负载重	用直连替代WiFi，关闭占用CPU的进程
URSim连不上	VirtualBox网络模式为NAT	改为Host-Only或使用Docker端口映射

RTDE的30004端口是"数据面"，而29999是Dashboard端口、30001是Primary端口。排查时不要混淆：Dashboard用于发送play/stop等文本指令，Primary用于发送URScript程序，RTDE只负责高频数据交换。三者可以同时连接，互不冲突。

在真实机器人上调试RTDE时，务必先确认机器人处于远程控制模式（Remote Control），且安全配置允许上位机发送控制指令。若只做数据读取，使用RTDEReceiveInterface即可，不要误用控制接口发送运动指令，以免造成意外动作。

完成本节环境搭建后，你应当能够：用ping和端口测试确认链路、根据真实/仿真场景选择正确的IP配置、安装RTDE客户端库、运行最小示例并看到关节角数据、以及根据故障现象快速定位问题层级。这套环境是后续所有RTDE数据采集与控制实验的基础。