2. 开发环境搭建与工程创建

XPlanar 的路径规划并不是在独立软件里完成的，它最终要落到 TwinCAT 3 的实时控制工程中。因此，在真正开始写运动代码之前，必须先把“开发环境”这条链路搭通：TwinCAT 3 作为实时运行与工程开发平台，XPlanar 软件包作为扩展功能，硬件扫描负责把实际控制器、EtherCAT 耦合器和 XPlanar 模块识别进工程，基本通信则保证工程能下载、能激活、能在线观察。这一节的重点不是“装完就行”，而是理解每一层在工程里对应什么对象，以及如何判断环境是否真正可用。

一、安装顺序与版本匹配

推荐顺序是：先安装 TwinCAT 3 完整开发环境，再安装 XPlanar 软件包，最后安装或更新 TwinCAT 3 的实时网卡驱动与 EtherCAT 从站描述文件。原因在于 XPlanar 软件包会向 TwinCAT 3 注册库、设备描述和功能模块，如果顺序颠倒，可能出现库找不到、设备树里没有 XPlanar 节点、或者编译时报“未解析引用”等问题。

版本匹配是这一节最容易踩坑的地方。TwinCAT 3 有多个 Build 版本，XPlanar 软件包也有对应的兼容范围。工程实践中应遵循：TwinCAT 3 Build 版本 ≥ XPlanar 软件包要求的最低版本，并且 XPlanar 固件版本与软件包版本保持同一主版本。例如，若 XPlanar 软件包要求 TwinCAT 3.1 Build 4024.10 以上，而现场控制器只装了 4024.00，那么即使安装成功，激活配置时也可能报“Target 不支持该功能”。因此安装前先确认三件事：控制器 TwinCAT 版本、开发机 TwinCAT 版本、XPlanar 模块固件版本。

二、创建 XPlanar 工程

安装完成后，在 TwinCAT 3 中新建工程。选择 TwinCAT XAE Project，而不是空工程或 PLC 单独工程，因为 XPlanar 需要 System 管理器来管理 EtherCAT 拓扑、运动轴和 PLC 之间的映射关系。工程创建后，先在 Solution 中确认出现 SYSTEM、MOTION、PLC 三个主要节点，这是后续配置的基础。

接着添加 PLC 项目。XPlanar 的运动控制通常由 PLC 库调用，因此需要在 PLC 项目中引用 Tc2_MC2、Tc3_XPlanar 等库。引用方式是在 PLC 项目的 References 中右键 Add Library，搜索对应库名。若搜索不到，说明 XPlanar 软件包没有正确安装或没有勾选“Install TwinCAT 3 XAE integration”。

三、硬件扫描与 EtherCAT 拓扑

硬件扫描是本节最关键的实操环节。操作路径是：在 SYSTEM 下右键 I/O → Devices，选择 Scan Devices，然后选择目标网卡。TwinCAT 会通过 EtherCAT 广播扫描从站，扫描结果会以树形结构显示。一个典型的 XPlanar 拓扑如下：

• EtherCAT Master：控制器上的实时网卡，例如 Device 1 (EtherCAT)；
• 第一个从站：EtherCAT 耦合器或 XPlanar 电源模块，例如 EK1100 或 XPlanar 专用供电单元；
• 后续从站：XPlanar 定子模块，每个模块有独立的 EtherCAT 地址和固件信息；
• 末端从站：XPlanar 动子或末端扩展模块，视具体配置而定。

扫描完成后不要急着激活，先逐项核对：从站数量是否与现场一致、每个从站的 Revision 号是否与 XML 描述匹配、是否有黄色问号或红色叉号。黄色问号通常表示缺少对应版本的 ESI/XML 文件，红色叉号通常表示拓扑顺序或通信参数不匹配。只有全部从站显示为正常状态，才进入下一步。

四、基本通信配置与验证

扫描完成后，需要把 EtherCAT 从站与 PLC 变量建立映射。XPlanar 的典型做法是：在 MOTION 下创建 NC Axis 或 XPlanar Axis，再把每个定子模块对应的轴与 PLC 中的轴变量关联。对于多定子系统，每个定子通常对应一个独立的轴对象，动子则通过 XPlanar 库中的 MC_XPlanarMove 等功能块进行控制。

通信验证分三步。第一步，在 SYSTEM → I/O 中确认所有从站处于 OP 状态，而不是 INIT 或 PREOP。第二步，激活配置并下载到控制器，观察 TwinCAT 右下角是否出现 Config Mode 切换为 Run Mode。第三步，在 PLC 中写一段最小测试代码，读取 XPlanar 模块的状态字和位置反馈，例如：

// 示例：读取 XPlanar 轴状态与位置
axisStatus : WORD;
axisPosition : LREAL;

axisStatus := Axis1.Status;
axisPosition := Axis1.ActPosition;

// 判断轴是否使能且无错误
IF (axisStatus AND 16#0001) <> 0 THEN
    bAxisReady := TRUE;
END_IF

这段代码中的 Axis1 是示例轴变量名，实际工程中应根据扫描结果替换为真实轴实例。运行后观察 axisStatus 是否进入使能状态、axisPosition 是否随动子移动而变化。如果位置始终为 0 或状态字不变，优先检查 EtherCAT 从站是否处于 OP 状态、轴是否已使能、以及 XPlanar 库版本是否与固件匹配。

五、常见问题与判断依据

完成以上步骤后，工程应达到一个可继续开发的状态：TwinCAT 3 能正常编译、下载和激活；EtherCAT 拓扑完整且所有从站处于 OP；PLC 能读取 XPlanar 轴状态和位置；XPlanar 库引用无报错。此时环境搭建才算真正完成，后续的路径规划、动子调度和轨迹优化才有可靠的运行基础。