Modbus 写缓存队列
写任务排队 · 失败不堵车

一、它解决什么问题

往从站写数据，最朴素的做法是直接调 MB_CLIENT。设备不在线的时候，这一调就等于把整个程序吊死：指令一直等不到 DONE，后面的写请求全堵在后面，一个都发不出去，而 HMI 上看起来一切正常。

写缓存队列的做法是把"提交"和"发送"拆开：

• 你只管调 FC_ModbusWrite_PutTask 把写请求扔进队列，函数立刻返回；
• FC_ModbusWrite_CacheRun 每周期调一次，从队列里取一条发给 MB_CLIENT；
• 发成功就出队继续下一条，发失败就按规则重试 / 重连 / 丢弃，状态机永远不会停在某一步上不动。

本包只发写缓存队列这一个功能块（三件套）。同批的另外几个块 （多从站轮询主站、自由口主站、RTU 从站等）各有各的测试状态，没测完的我不往站上放。

二、三个文件各干什么

在 OB1 里怎么调

// ① 提交写请求：每周期可以调多次
"FC_ModbusWrite_PutTask"(
    SlaveID   := 1,            // 从站号 1..247，0 是广播（拒收）
    RegAddr   := 40101,        // 保持寄存器地址（带区号）
    RegValue  := 16#1234,      // 要写的值
    AddTrigger:= "写启动脉冲");  // 必须单周期脉冲！

// ② 调度：每周期调一次，全工程只调一次
"FC_ModbusWrite_CacheRun"(
    InterfaceId := 64,         // PLC 的 PROFINET 口硬件标识符
    ID          := 21,         // 连接号，必须唯一
    ADDR1       := 192, ADDR2 := 168,
    ADDR3       := 0,   ADDR4 := 51,
    RemotePort  := 502);

三、状态机

        队列非空且总闸开
   0 空闲 ──────────────► 10 等受理 ──BUSY──► 20 等结果 ──DONE──► 出队(成功) ──┐
       ▲                    │                  │                              │
       │                    │T_ACCEPT 超时     │T_REQ 超时 / ERROR            │
       │                    ▼                  ▼                              │
       │                  ┌──────────────────────┐                            │
       │                  │ 30 判定               │                           │
       │                  │  · 818x/838x → 丢弃   │                           │
       │                  │  · 80Cx/超时 → 60 断线│                           │
       │                  │  · 其余 → 原地重试    │                           │
       │                  └────────┬─────────────┘                            │
       │                           ▼                                          │
       └───────────────────── 60 断开 ──► 65 冷却 ──► 回到 10（重试）          │
       └──────────────────────────── 丢弃(失败) ◄─────────────────────────────┘

成功和丢弃都不单占状态，就地出队 —— 每个任务固定 4 拍。

四、三个版本文件怎么选

三个块都是这三份编码，同一个块要导同一编码版本，别混着导。

_GB2312 是派生文件，由脚本自动生成。改了逻辑要改主文件后重新派生 —— 永远不要手工改 _GB2312，下次派生会全部覆盖。

五、导入步骤

1. 项目树 → 外部源文件 → 添加新的外部源文件 → 选中 .scl → 从源生成块。
2. 先导 ModbusWriteCache_Types → 生成 UDT + 全局 DB 两项。
3. 再导 FC_ModbusWrite_PutTask，最后导 FC_ModbusWrite_CacheRun。
4. 不要先手动新建同名块，否则会冲突。
5. 不要重导 MB_CLIENT_DB / MB_CLIENT_PARA —— 本包故意不含，那两个 DB 里是现场 IP 与连接号，重导会冲掉。
6. OB1 里：CacheRun 每周期调一次、全工程只调一次；PutTask 每周期可调多次。
7. 在线看 DB_ModbusWriteCache.VER，是 16#21 就说明新代码生效了。

导入 ModbusWriteCache_Types 会覆盖现有的 DB_ModbusWriteCache： 队列清空、统计清零、组态值回到默认。队列本来就是非保持的，但请在停机试车的窗口里做， 别在线路上正跑着东西的时候导。

从零建工程还缺两个 DB

MB_CLIENT_DB（在 OB 里拖一次 MB_CLIENT 指令，让 TIA 自动生成）+ MB_CLIENT_PARA（一个 T_CON_IP_v4 结构： InterfaceId=64 / ID=21 / ActiveEstablished=1 / RemotePort=502 / LocalPort=0）。

两个 FC 的输入接口完全没变，原有的调用语句不用改；新增的都是输出引脚，可以全部不接（状态在 DB 里都有）。

六、参数速查

全部在 DB_ModbusWriteCache 里，HMI 或监视表直接改（DB 是非保持的，掉电回默认值）。

七、四个必须知道的坑

1. DB 的「优化的块访问」必须关

DB_ModbusWriteCache 的 S7_Optimized_Access 必须是 'FALSE'。 MB_CLIENT 的 MB_DATA_PTR 只能指向非优化 DB 或 M 区；一旦被「顺手优化」成 TRUE， MB_CLIENT 会稳定报 16#818C 并且一条都写不出去。

2. AddTrigger 必须是单周期脉冲

用 R_TRIG 把电平取成单周期脉冲再喂给每个调用点。接成电平会每周期重复写同一个值， TrigHoldWarn 输出会亮一拍提示。同一个脉冲可以喂给多个调用点， v2.1 起同一扫描周期里多处提交互不干扰。

3. 写出去的是线圈不是寄存器

RegAddr 直接对应 MB_CLIENT 的 MB_DATA_ADDR： 写保持寄存器要填 40101 这种带区号的地址；填 100 会被当成线圈区，发出去的是 FC05 而不是 FC16。 地址习惯是 0 基寄存器号，就在 ADDR_OFFSET 里填 40001。

4. 升级 v2.1 只要导一个文件

v2.1 只改了 FC_ModbusWrite_PutTask 的入队触发语义，ModbusWriteCache_Types 本次只改了注释、DB 结构一个字节没变。 不要重导 Types —— 重导会把在线整定过的 T_ACCEPT / T_REQ / RETRY_MAX 一起重置。

八、常见问题

一条都写不出去，MB_StatusLatched = 16#818C

MB_DATA_PTR 指向了优化访问的 DB。把 DB_ModbusWriteCache 的「优化的块访问」关掉 —— 别把它改成优化。

队列只入不发，WriteLocked = TRUE

ENABLE_WRITE 是 FALSE。打开写总闸。

PutTask 的 MultiCall 亮了

同一周期不是第一次调用。v2.1 起这只是诊断位，不是故障，不用管。v2.0 时期接了报警的，这次要拆掉。

StatusLive 一直 16#7004

这是正常的（连接已建立、无作业在跑）。不是故障，别当错误码查。真卡住时 STATUS 是 16#7005 或 16#8200。

16#8200 端口正在处理另一个请求

同一连接号被两处用了，或者上一作业没收尾。检查全工程是不是有第二个 MB_CLIENT 用了同一个 ID。

时间戳 / 计数掉电就归零

DB 是 NON_RETAIN。有意的：写任务绝不能在重启后被重放 —— 那等于把设备写回历史状态，比重发一条新写请求危险得多。

九、验证记录

实机验证

已在 S7-1510SP-1 PN 上导入 TIA 工程实跑，验证了两项：

• 正常写入通路 —— 写请求经队列发出，从站应答，寄存器里的值对得上。
• 同一扫描周期多次提交 —— 一个扫描周期里调 PutTask 多次、多处各喂同一个脉冲，每一条都进了队列，没有静默丢弃（这正是 v2.1 修的那个缺陷）。

其余边界场景（兜底超时、断线重连、失败丢弃、协议异常码分类）目前是仿真结论，没有在真机上逐条复现 —— 页面上不把它们说成实测过。

仿真验证

配套仿真脚本用 Python 1:1 复刻了两套状态机的离散递推，并对 MB_CLIENT 建模了四种搭档行为（正常 / 报错 / 受理后永不返回 / 根本不受理）—— 只跑成功路径是测不出问题的。

• 57 项断言 · 0 项失败 · 含 6 组「新版 vs 原稿」对照实验
• 直接跑，无需第三方库：python test_ModbusWriteCache_simulation.py

关键对照数据

诚实声明：写缓存队列本身已在真机上跑通（S7-1510SP-1 PN，验证了正常写入通路与同周期多次提交）。 但上面那张对照表里的「原稿」那一列，以及超时兜底、断线重连、失败丢弃这些边界分支，是仿真 + 手册核对的结论， 没在真机上逐条复现 —— 这里不把它们说成实测过。
换到自己的工程时，仍建议在停机窗口做，先置 ENABLE_WRITE=FALSE 观察状态机跑通，再开闸。

站上的规矩没变 —— 没跑通的不放上来。同批的其余几个块还在整理，没测完的我不往站上放。