简介：CoDeSys运动控制资料包面向工业自动化领域的PLC编程、运动控制与机器人调试人员，系统讲解CoDeSys软PLC中的运动控制实现方案。文档以SMC_TRAFO_Gantry3pi模块和SMC_Interpolator功能块为核心，逐一说明目标位置向量、x/y偏移量、移动范围、驱动器映射等参数，并覆盖bExecute、poqDataIn、bSlow_Stop、bEmergency_Stop、bWaitAtNextStop等输入变量的作用，以及bDone、dwIpoTime、piSetPosition、iStatus、dVel等输出状态量的含义，帮助读者理清从SMC_GEOINFO轨迹对象到离散位置点的插补流程。内容还对比了梯形与S形速度轮廓的特点，以及急停、慢停、等待停止等运动控制逻辑，适用于gantry机器人、数控设备、运动平台等场景。压缩包内共1个doc文档，约130KB，资料精炼且无冗余文件，适合现场调试时快速查阅或作为SMC功能块的学习笔记。目前已有973人学习下载，是一份高性价比的CoDeSys运动控制中文参考资料。
1. 一份写满插补器参数的 CoDeSys 运动控制文档，到底能帮你省多少事
做双轴龙门和数控插补的人，迟早会在 CoDeSys 运动控制库里碰到 SMC_TRAFO_Gantry3pi 和 SMC_Interpolator 这两个名字。前者负责把 GEO 坐标系里的目标位置换算到两个驱动轴，后者是整条轨迹从连续路径变离散位置点的核心。大多数时候你会从某个渠道拿到这份文档的 PDF，但里面全是模块引脚说明和参数注释，没有系统讲解，也没有调试顺序，真正上手时还是会被 bExecute 和 bDone 的时序搞懵。这篇笔记的价值不是替你把文档读一遍，而是把这些参数串成一条可复现的调试链路，告诉你每个管脚在实际设备上到底改什么、怎么改、改完看哪里。
2. 坐标变换层：SMC_TRAFO_Gantry3pi 的参数划分与选型理由
2.1 为什么龙门结构需要单独做一次坐标变换
双轴龙门和我们平时用的 XY 平台有一个关键差异：它有两个电机同时托着一根横梁，负载的位置是由 x 轴和 y 轴电机共同决定的。如果直接把 G 代码解析出来的 VI（虚拟轴）位置送给两个驱动轴，设备在运行中会因为两轴跟随误差不一致产生“扭梁”，轻则轨迹变形，重则憋坏机械结构。所以 CoDeSys 运动控制里专门有 TRAFO 模块做运动学变换，把虚拟轴的笛卡尔坐标映射成物理轴的参考位置。
SMC_TRAFO_Gantry3pi 做的是正向变换，也就是从 G 代码的目标点计算两个轴各自应该到的位置。它的名字里的“3”通常对应龙门结构的第三维约束或者三轴联动场景，当你的项目是双轴龙门加一根横梁时，这个模块就是最直接的选择。另一个常见模块 SMC_TRAFO_Gantry3 处理的是不带附加偏移的基础款龙门结构，而带 pi 后缀的版本增加了目标位置向量 SMC_PosInfo 的直接支持，方便你把插补器输出的位置信息完整接进来，不丢附加轴数据。
2.2 输入输出参数表：哪些是运动参数，哪些只是可视化参数
打开文档里关于 Gantry3pi 的章节，你会发现有很多 LREAL 类型的参数，很多人第一次看会以为它们都要参与控制，实际上它们分成了两类。
第一类是真正影响运动计算的参数。dOffsetX 和 dOffsetY 是 x/y 轴的偏移量，这个偏移通常来自机械安装时的原点偏差，需要你在设备调试时实际测量填入。dx 和 dy 是 GEO 坐标系里 x/y 轴的目标值，这两个值通常直接连接 SMC_Interpolator 输出的 piSetPosition 里的笛卡尔坐标分量。DriveX 和 DriveY 是 AXIS_REF 类型的轴引用，分别指向两个物理驱动轴。
第二类是给可视化用的，它们不参与运动学计算，只在 HMI 或者仿真界面上显示当前的位置范围。minX、maxX、minY、maxY 定义了运动范围边界，ratio 是 x 轴间距和 y 轴间距的比率，便于可视化画面保持真实比例。dnx、dny、dnOffsetX、dnOffsetY 是标准化位置，范围 0 到 1，通常用于虚拟场景贴图，把实际位置映射到画面坐标。
这里最容易翻车的点是把 dx、dy 直接接到别的模块再算一遍，结果位置被二次变换。我一般会把 Gantry3pi 的输出到插补器这条链路上做断点监控，确认 SMC_PosInfo 里的 x、y 值和物理轴的设定位置一致，再往下游送。
2.3 按文档参数做一次最小配置
假设你手头有一台双轴龙门设备，机械原点在左下角，x 轴行程 800mm，y 轴行程 500mm，你在 CoDeSys 环境里按下面的顺序配置。
第一步，在轴配置里添加两个物理轴，命名建议直接叫 DriveX 和 DriveY，类型选 AXIS_REF，并完成驱动器通讯与使能设置。
第二步，调用 SMC_TRAFO_Gantry3pi 功能块。在 I/O 映射里把模块的 DriveX 引脚连接到轴变量 X_REF，DriveY 连接到 Y_REF，dx 和 dy 引脚接到上一级插补器输出的 SMC_PosInfo 笛卡尔坐标分量，dOffsetX 和 dOffsetY 先填 0 预留。
第三步，设置可视化范围。minX=0、maxX=800、minY=0、maxY=500、ratio=800/500=1.6，这几个值只影响画面显示，不影响实际运动。
第四步，用一段单轴往复程序验证映射关系是否正确。手动给 dx 一个固定值，比如 dx=100、dy=0，观察 DriveX 是否走到 100mm 处，DriveY 是否停在原点。如果轴走的方向反了，说明轴的方向配置有问题，需要到轴配置里反转计数方向。
注意，这一步不要急着接插补器，先确认坐标变换模块的缩放和方向正确。很多项目在联调阶段出现问题，最后查来查去都是某个轴的编码器方向或者传动比设错了，而 Gantry3pi 只是如实把坐标传给了轴。
3. SMC_Interpolator 插补器核心：输入输出信号规律与速度轮廓设定
3.1 插补器在运动控制链路中的位置
如果你按照 G 代码解析到驱动器这条链路来理解，整条数据流大致是：SMC_NCDecoder 或者 SMC_SmoothPath 负责把文本格式的 G 代码解析成 SMC_GEOINFO 对象，放进 SMC_OUTQUEUE 缓冲区；然后 SMC_Interpolator 从这个缓冲区不断取出 GEOINFO 对象，按照设定的速度轮廓和时间片计算出每一个插补周期内的目标位置点 piSetPosition；最后上位逻辑把 piSetPosition 里的坐标送入坐标变换模块，变换后再送给驱动轴。
SMC_Interpolator 之所以是核心，是因为它决定了设备实际跑出来的轨迹轮廓。如果你在文档里只看到“将连续轨迹转换成离散轨迹位置点”这句话，可能会误以为它只是个采样器，但实际上它内部包含了加减速规划、急停处理、等待停止、速度倍率、附加轴多项式插补等一整套逻辑。这也解释了为什么它输出变量里有 dVel（当前速度）和 iStatus（状态枚举），这些都是供上位逻辑监控设备实时状态的信号。
3.2 输入引脚时序与行为规律
文档里对输入变量的描述比较零散，我把它整理成一张时序控制表，方便你对照调试。
bExecute 是启动开关。功能块内部逻辑会在 bExecute 出现上升沿时复位自身状态机，同时开始从 poqDataIn 指向的 SMC_OUTQUEUE 取数据。如果你保持 bExecute 为 TRUE 不变化，插补完一段轨迹后 bDone 会变为 TRUE，功能块停在 FINISHED 状态，直到你再次给一个上升沿才会启动下一轮。
poqDataIn 是指针类型的输入，连接前一级模块的输出队列。典型接法是 SMC_NCDecoder 的 DataOut 直接连到这个引脚。这里要注意，必须保证前级模块已经填充了完整的 SMC_OUTQUEUE 结构体，如果队列为空，插补器会等待或者直接报错，具体取决于你的调用周期。
bSlow_Stop 和 bEmergency_Stop 的区别是很多新手容易混淆的地方。bSlow_Stop 是减速停止，它按照当前 GEOINFO 对象里定义的减速度把速度降到 0，但不会立即刹停，适合正常工艺里的暂停需求。bEmergency_Stop 是立即停止，速度瞬间置 0，适合安全场景。两条引脚默认都是 FALSE，接到急停回路时要仔细确认外部信号的常开常闭逻辑，避免急停回路断开时反而触发急停。
bWaitAtNextStop 的作用是让设备在下一次要求停止的位置（典型是轨迹转角处）保持暂停，直到你把这个引脚重新置 FALSE。这个功能在做点胶或者焊缝工艺时很实用，可以在转角处停顿让胶水充分填充。需要注意的是它不是每段都停，而是等到下一个速度为零的位置才生效。
dOverride 是速度倍率，默认 1.0，范围要求大于 0.01。它可以在线修改，但只能在当前没有加速或减速的过程中生效，否则要等当前阶段结束才会应用新值。这意味着你程序里随时改 dOverride 是允许的，但别期待它瞬时改变加速度段的斜率。
iVelMode 选择速度轮廓，TRAPEZOID 是梯形速度图，SIGMOID 是 S 形速度图。梯形图在加减速阶段加速度是恒定的，所以设备在启动和停止瞬间加速度跳变，对轻载设备足够；S 形图加速度连续，适合重型设备或者有精密定位需求的场景。
我一般在程序里用 CASE 语句根据工艺选择速度模式，切换前先确认没有正在执行的轨迹段，否则插补器可能会按新模式重新规划，导致中途变速。
3.3 用一张速度轮廓对比表理解本质区别
梯形速度图和 S 形速度图的本质区别在于加速度是否连续。文档里提到一个容易忽略的细节：把 S 形改成梯形不会让整条轨迹运行时间变长，因为起始和结束端受限的加速度增量会在中间段被更高的加速度补偿。
也就是说，两种轮廓下轨迹总时间接近，但设备承受的加减速冲击完全不同。下面这张表可以直观对比：
| 速度轮廓 | 加速度连续性 | 起始/结束冲击 | 适用负载 | 计算开销 |
|---|---|---|---|---|
| 梯形 | 不连续 | 明显 | 轻载、高节拍 | 小 |
| S 形 | 连续 | 极小 | 重载、高精度 | 略大 |
另一个容易漏掉的参数是 GEOINFO 对象里最大加速度对 S 形轮廓的影响。文档明确提示，使用 S 形轮廓时，编程指定的最大加速度或减速度最多会被超过约 1.57 倍（π/2）。这个数值意味着你在工艺里设定最大加速度为 2m/s²，实际执行时加速度峰值可能到 3.14m/s² 左右，选型时电机的扭矩余量要留够。我见过一个项目因为忽略了这个系数，导致加速阶段电机过载报警，后来把加速度降为原来的一半才稳定运行。
3.4 附加轴插补：S 形还是线性，取决于 wSProfile
文档花了一段描述附加轴的插补方式。默认情况下，附加轴的位置是依据 X、Y、Z 空间中的轨迹长度做线性插补的。这在大多数场合够用，但如果你需要附加轴（比如旋转轴或 Z 轴）在轨迹段两端速度为零、内部平滑过渡，就得对当前对象的 piStartPos 里的 wSProfile 变量相应位置位。
置位后，附加轴不再按笛卡尔空间长度线性插补，而是按轨迹完成比例做多项式插补，得到一个 S 形的轴位置轮廓，并且段首段尾速度和加速度都为零。这种模式适合在轨迹段切换时避免附加轴冲击的场景，比如激光切割时的焦点高度轴。
常见做法是在轨迹预处理阶段根据工艺标记 GEOINFO 对象的 wSProfile，而不是在插补器运行过程中改。因为插补器只在取到对象时读取一次该变量，运行中修改不会生效。
4. 避坑排查：Gantry3pi 与 SMC_Interpolator 联调时最容易翻车的六个点
4.1 bDone 与 bExecute 的复位时序不匹配，程序跑完一次就卡住
现象：第一次启动轨迹运行正常，跑完后 bDone 一直为 TRUE，再次给 bExecute 上升沿没有反应，设备停在原点不动。
原因：SMC_Interpolator 的 bDone 只在 bExecute 为 FALSE 时才被复位。很多人的 PLC 程序把 bExecute 写成一直为 TRUE，导致 bDone 永远不复位，功能块状态停留在 FINISHED，不再处理新进入队列的数据。
解决：手动控制 bExecute 引脚，启动时拉高，检测到 bDone 为 TRUE 后主动把 bExecute 拉低一个扫描周期，再拉高触发下一轮。我习惯写一个两行的状态机来处理这个时序，比直接置 TRUE 靠谱得多。
4.2 dOverride 改倍率后速度纹丝不动
现象：在线把 dOverride 从 1.0 改成 2.0，轴速度没有任何变化，要过几秒钟才突然变快。
原因：文档里写得很清楚，dOverride 只有在当前没有加速或减速的情况下才会被应用。如果你在设备匀速段修改，它可能刚好处于匀速区，所以不会立刻生效；如果正处于加速段，它要等加速完成才应用。
解决：设计 HMI 倍率旋钮时，把改动时机放在设备等待启动阶段。如果必须支持运行中改倍率，就要接受这个延迟特性，或者把 dOverride 的变化同时反馈给上位控制逻辑，避免操作者以为按钮坏了。
4.3 SMC_PosInfo 里的附加轴位置没更新，导致 Gantry3pi 输出轴位置不对
现象：插补器输出的 piSetPosition 中笛卡尔坐标 x、y 始终正确，但附加轴值一直保持初始值，导致使用附加轴联动时轨迹错位。
原因：SMC_PosInfo 结构体里除了笛卡尔坐标，还有附加轴位置字段。如果你在 G 代码解析或者轨迹预处理阶段没有正确填充附加轴的目标值，插补器虽然会输出该结构体，但附加轴字段只是透传或者保持默认值，不会自动做插补计算。
解决：检查 G 代码到 GEOINFO 对象的转换链路，确认附加轴指令被正确解析到 SMC_GEOINFO 对象的附加轴字段里。同时确认 SMC_Interpolator 相关参数中附加轴使能位是开启状态，否则它确实不计算附加轴。
4.4 iLastSwitch 开关信号丢事件，设备越过多个开关只报最后一个
现象：设备运行中经过两个行程开关，上位逻辑采集 iLastSwitch 只收到第二个开关的编号，第一个开关的信号被漏掉。
原因：iLastSwitch 输出的是“上一个通过的开关序号”，如果在一个插补周期内通过了多个开关，它只会显示最后一个，这是设计如此，不是 bug。
解决：如果你的工艺需要捕获每个开关的触发，用 dwSwitches 输出。这个双字变量的每一位代表一个开关的当前状态，第 0 位对应开关 1，第 31 位对应开关 32，辅助标记在第 32 位。你可以在程序里对它做上升沿检测，逐位捕获所有开关事件。
4.5 轨迹末端 OUTQUEUE 为空，无法再次执行同一轨迹
现象：一段轨迹执行完后，再次触发 bExecute，插补器没有动作，监控 poqDataIn 指向的队列发现为空。
原因：SMC_Interpolator 每处理完一个 GEOINFO 对象，就会把它从 SMC_OUTQUEUE 中清除。轨迹跑完，队列自然为空。这是正常行为，不是故障。
解决：如果需要循环运行同一轨迹，有两种做法。第一种是把 CNC 程序重新送入解码器，重建 SMC_OUTQUEUE；第二种是使用 SMC_RESTOREQUEUE 功能块，前提是 OUTQUEUE 缓冲区足够大，在第一次执行时就把完整轨迹缓存下来了。我一般建议用第二种，因为省去了解码时间，循环衔接更紧凑。
4.6 急停后重新启动，插补器静止不动且 iStatus 停在 IPO_WAIT
现象：设备急停后，人工复位急停按钮，再次触发启动指令，轴没有任何反应，查看 iStatus 状态枚举发现停在 IPO_WAIT。
原因：IPO_WAIT 表示急停或者慢停信号有效且速度为零时，插补器进入了等待状态。如果你没有把 bEmergency_Stop 重新拉低到 FALSE，或者程序中急停状态锁存逻辑没释放，插补器会一直保持在等待状态，不接收新的运动请求。
解决：急停复位流程里，除了清理急停信号，还要检查 bSlow_Stop 和 bWaitAtNextStop 是否也被意外置位。我在项目里统一用一个“复位插补器”函数块，把所有停止相关的引脚全部复位，再重新给 bExecute 上升沿，一次搞定。
5. 参数调优：速度轮廓、倍率与附加轴插补的实际调整手法
5.1 从梯形切到 S 形时，加速度余量先降一半
文档里那个 π/2 的超出系数是你调机前必须算的一笔账。我一般会按这个步骤来：
- 第一步，先按梯形速度轮廓调通整条轨迹，记录当前最大加速度下设备运行是否平稳。
- 第二步，切换到 S 形轮廓，把 GEOINFO 里设定的最大加速度数值先乘 0.6，留出约 1.67 倍的执行余量，此时实际峰值加速度约为设定值的 0.6 × 1.57 = 0.94 倍，略低于机械承受极限。
- 第三步，运行一条完整轨迹观察电机电流和机械振动，逐步增大设定加速度，每次增量不超过 10%，直到出现轻微抖动或过载趋势，再回退一档。
这样调出来的加速度参数既发挥了 S 形轮廓的优势，又不会让电机扭矩选型显得捉襟见肘。千万不要直接按梯形轮廓的加速度数值套到 S 形上，峰值超出原设定值 57% 的概率很高，大多数过载报警就是这么来的。
5.2 在线倍率：利用 dOverride 实现不重启程序的工艺切换
有一个实用技巧：dOverride 可以同时用于节流而不是只在调试时用。比如你的设备有两种工艺速度，正常工艺 100% 速度运行，而换料或者空跑挪位置时希望 50% 速度运行。你不需要切换 G 代码加工程序，只需要在 PLC 逻辑里把 dOverride 从 1.0 改成 0.5，设备会在下一个匀速阶段自动降速，省去了重新解析程序的等待。
注意文档里强调“只有在当前没有加速或减速的情况下才会应用修改值”。所以如果你的工艺程序是短段频繁加减速的路径，dOverride 的生效时间可能会让你觉得“没反应”。这时候我一般会在 HMI 上做一个倍率显示，把插补器当前状态里的加速/匀速/减速状态显示出来，操作者看到设备处于匀速段再调整倍率，体验会好很多。
5.3 附加轴 S 形插补：用 wSProfile 实现柔性旋转轴动作
如果你的设备带旋转轴或者定位轴，并且它在轨迹段首尾需要停顿或者换向，默认的线性插补会让附加轴在段边界处产生速度跳变。一个典型场景是涂胶轨迹，Z 轴在段首需要下降，段尾需要抬起。
我把附加轴启停逻辑写成这样：
// 假设 geoObj 是当前待处理的 SMC_GEOINFO 对象 // 当附加轴需要在段首和段尾平滑启停时，置位 wSProfile 的附加轴插补位 IF bEnableSProfileForAux THEN geoObj.piStartPos.wSProfile := geoObj.piStartPos.wSProfile OR 16#0008; // 16#0008 是示例位掩码，具体位数以实际库定义为基准 ELSE geoObj.piStartPos.wSProfile := geoObj.piStartPos.wSProfile AND 16#FFF7; END_IF这段代码的逻辑是：通过位或运算把 wSProfile 的某一位拉高，使能附加轴多项式插补；通过位与运算清除该位，恢复默认的线性插补。我把这个逻辑放在轨迹预处理模块里，在 GEOINFO 对象进入 SMC_Interpolator 之前完成标记。如果你在插补器运行期间修改，插补器已经读过的对象不会响应，新对象才会生效。
参数说明：16#0008 这个掩码值是示例性质，不同 CoDeSys 版本的运动控制库对 wSProfile 的位定义可能不同。你在实际项目里需要打开库的常量定义视图，找到附加轴 S 形插补对应的位，改写成你的库版本对应的数值。用显式的方式做位操作，比直接给整个变量赋值要安全，因为 wSProfile 里可能还有其他位控制着插补器的其他行为。
这段逻辑带来的实际收益比较直观：设备在轨迹转角处附加轴运行更平稳，不会出现轴杆顿挫的声音。如果你做的是高加速度短节拍工艺，这个优化对机械寿命有直接好处。
6. 验证方法：把整条插补链路跑通再上真机
验证顺序不能反过来。我的习惯是先建一个虚拟轴项目，完全不接驱动器和电机，把解码器、轨迹预处理、SMC_Interpolator、Gantry3pi 全部搭好，用一段典型 G 代码跑离线仿真，确认每个输出节点的数值变化符合预期。
第一步，检查 SMC_Interpolator 的 iStatus 变化顺序。正常轨迹运行时应该依次看到 IPO_ACCEL、IPO_CONSTANT、IPO_DECEL、IPO_FINISHED。如果你看到 IPO_WAIT 出现在急停信号复位后，说明停止信号没有完全释放。监控这个枚举值判断插补器是否在正常“呼吸”。
第二步，检查 dVel 是否按梯形或 S 形规律变化。在梯形模式下，dVel 在加速段线性上升，匀速段保持不变，减速段线性下降；在 S 形模式下，加速段起始和结束阶段斜率较缓，中段斜率较陡。如果你发现 dVel 在段间出现跳变，说明 GEOINFO 对象里速度或加速度设定有问题。
第三步，对比 piSetPosition 里的坐标轨迹和输入轨迹。在 HMI 或者在线监控里画一个 XY 散点图，观察插补器输出的点是严格按照路径轮廓分布，还是在转角处出现明显偏差。这一步能提前暴露坐标变换模块的偏移量设置错误。
第四步，验证末段减速和停止行为。把程序末尾加上 M30 或者停止指令，确认 bDone 变为 TRUE 前 dVel 已经降到零，iStatus 进入 IPO_FINISHED。如果减速过程中 bDone 提前置位，说明你前级模块的结束标记与插补器不匹配。
第五步，验证循环执行。使用 SMC_RESTOREQUEUE 缓存完整轨迹，连续触发两次启动，确认第二次执行前不需要重新解码，且轨迹起点、终点位置一致。
从那以后，我每次接手新的运动控制项目，都会强制走一遍这套离线验证流程，再上真机。因为这套方法帮我躲过好几次坐标方向配置错误的坑，也节省了大量现场调试时间。希望帮到你。
本文还有配套的精品资源，点击获取
