📚 课程目录第1章 URScript开发环境搭建

1. URScript开发环境搭建

URScript 是 Universal Robots 控制器内部运行的脚本语言，它既可以通过 PolyScope 图形界面中的“程序”节点间接生成，也可以由外部程序通过 TCP 端口直接下发。要真正进入 URScript 开发，第一步不是写脚本，而是把“能运行脚本的控制器”和“能编辑、下发、观察脚本的通道”同时准备好。本章围绕这条链路展开：用 URSim 在本地获得一个可运行的虚拟控制器，用 PolyScope 连接并操作它，再打通脚本编辑与远程调试通道，使脚本从编辑到执行形成闭环。

1.1 为什么先用 URSim 而不是真机

URSim 是 Universal Robots 官方提供的离线仿真软件，它内部运行的是与真实控制器一致的 URControl 和 PolyScope 版本。对 URScript 开发而言，URSim 的价值在于三点：第一，脚本语法错误、端口占用、变量作用域等问题可以在不占用真机、不承担碰撞风险的前提下暴露；第二，URSim 支持与真机相同的 30001/30002/30003/30004 等 TCP 端口，远程下发脚本的代码几乎不用修改就能迁移到真机；第三，仿真环境可以反复重启、快照和回滚，适合做参数试验。

需要明确的是，URSim 的“仿真”指的是控制器逻辑与运动学仿真，它并不模拟真实工件的接触力、线缆拖拽和夹具气路。因此涉及力控、碰撞检测阈值、实际节拍的内容，最终仍需在真机上验证。本节的目标是搭建一个“脚本能跑、能看、能改”的开发底座。

1.2 URSim 安装与首次启动

URSim 官方以虚拟机镜像和 Linux 安装包两种形式发布。工程上更常用的是虚拟机方式：在 VMware Workstation 或 VirtualBox 中导入 URSim 的 .vmdk 镜像，网络模式选择“桥接”或“NAT”。选择桥接时，虚拟机会从局域网获得独立 IP，便于其他电脑访问；选择 NAT 时，需要配置端口转发才能让宿主机访问 30001 等端口。若只在宿主机上开发，NAT 加端口转发即可；若要与同事共享一台仿真控制器，桥接更直接。

启动虚拟机后，系统会自动进入 PolyScope 界面。此时应先在“设置 → 系统 → 网络”中确认控制器 IP。常见默认值为 192.168.56.101（VirtualBox Host-Only）或由 DHCP 分配的地址。记下这个 IP，后续所有连接都围绕它进行。首次启动还应检查“设置 → 关于”中的软件版本，例如 URSim 5.14 对应 PolyScope 5.x，其 URScript 语法与 3.x 存在差异，版本必须与目标真机一致，否则脚本可能在真机上无法解析。

1.3 PolyScope 连接与脚本编辑器

PolyScope 是控制器的图形操作界面。在 URSim 中它直接显示在虚拟机屏幕上；在真机上则通过示教器或浏览器访问。若要从宿主机浏览器访问 URSim 的 PolyScope，可在地址栏输入 http://<控制器IP>:8080（部分版本为 80 端口）。连接成功后，应能看到“程序”“安装”“设置”等选项卡。

PolyScope 自带的脚本编辑能力有限：它主要通过“程序”树中的“脚本”节点插入代码行，适合少量逻辑，但不适合大段 URScript 的编写与版本管理。因此实际开发中通常采用“外部编辑器 + 远程下发”的方式。外部编辑器可选 VS Code、Notepad++ 或任何纯文本编辑器，关键是保存为 UTF-8 编码的 .script 或 .urp 中的脚本片段，避免中文注释乱码。

在 PolyScope 中验证脚本是否被正确解析，最直接的方法是：新建程序 → 添加“脚本”节点 → 粘贴一段最小脚本 → 点击“播放”。若脚本有语法错误，PolyScope 会在日志区给出类似 Parse error at line ... 的提示。这个反馈是后续远程调试的基础。

1.4 远程调试通道配置

URScript 的远程通道本质是 TCP 端口。最常用的两个是：30001 主控制端口，用于下发脚本并接收控制器返回的文本消息；30002 次要控制端口，行为类似但优先级不同。此外，30003 以 125Hz 持续推送机器人状态数据包，30004 是 RTDE 实时数据交换端口，适合高频读取关节角、TCP 位姿和 IO 状态。

配置远程通道时，先在宿主机上确认网络可达：

ping 192.168.56.101
telnet 192.168.56.101 30001

若 telnet 能建立连接，说明端口开放。随后可用 Python 建立最小下发通道：

import socket

HOST = "192.168.56.101"
PORT = 30001

script = 'def hello():\n  textmsg("URScript channel OK")\nend\n'

with socket.create_connection((HOST, PORT), timeout=5) as s:
    s.sendall(script.encode("utf-8"))
    print(s.recv(1024).decode("utf-8", errors="ignore"))

这段代码做了三件事：连接 30001 端口、把脚本以 UTF-8 字节流发送、读取控制器返回。若返回内容中出现 URScript channel OK 或 PolyScope 日志区出现同名消息，说明通道已打通。若连接被拒绝，优先检查 URSim 网络模式、防火墙和端口是否被其他进程占用；若连接成功但无返回，检查脚本是否以 end 正确结尾，以及函数是否被调用。

1.5 一个可复用的最小验证脚本

为了同时验证“脚本能解析、能执行、能回传”，建议使用下面这段最小脚本作为环境自检：

def env_check():
  textmsg("ENV_CHECK_START")
  local p = get_actual_tcp_pose()
  textmsg("TCP_POSE=" + str(p))
  local q = get_actual_joint_positions()
  textmsg("JOINT=" + str(q))
  textmsg("ENV_CHECK_END")
end

env_check()

执行后，PolyScope 日志区或 30001 端口返回中应依次出现 ENV_CHECK_START、TCP_POSE=...、JOINT=...、ENV_CHECK_END。四行齐全，说明脚本解析、变量读取、字符串拼接和消息回传都正常。若只出现 START 而没有 END，通常是脚本在中途抛出了异常，应检查 get_actual_tcp_pose() 是否在控制器已上电且未报错的状态下调用。

建议把 URSim 的 IP、PolyScope 版本、30001/30002/30003/30004 端口连通性、最小脚本执行结果记录成一张环境自检表。每次更换电脑或升级 URSim 后重新执行一次，可以避免把环境问题误判为脚本问题。

1.6 环境搭建完成后的判断标准

当以下条件同时满足时，可以认为 URScript 开发环境已经可用：URSim 能正常启动并显示 PolyScope；宿主机能 ping 通控制器 IP；30001 端口能建立 TCP 连接并收到脚本执行回传；PolyScope 日志区能看到脚本输出的文本消息；外部编辑器保存的脚本能通过远程通道下发并执行。此时再进入后续章节的变量、运动指令、IO 控制和异常处理，才不会在环境问题上反复消耗时间。

需要提醒的是，URSim 与真机在端口行为上基本一致，但真机通常启用了更严格的网络与安全设置，例如需要先使能机器人、释放急停，部分端口才允许写入。因此把 URSim 上验证通过的脚本迁移到真机时，应先在真机 PolyScope 中手动执行一次，确认无语法错误后，再切换到远程通道。这样可以把“环境差异”和“脚本逻辑错误”分开定位。