ControlLogix EtherNet/IP 主站

插件用途

ControlLogixMaster 通过 EtherNet/IP 连接 Allen-Bradley ControlLogix，按控制器标签名读取和写入变量。公共通道、设备、变量和数据格式配置见采集配置；本页说明 ControlLogix 专用参数、地址规则、数据边界和调试工作流。

配置入口

登录 WEB 配置页后，进入“开发配置 → 采集配置”：

1. 创建 TCP 客户端通道，在远端地址中填写控制器主机和端口，例如 192.168.1.10:44818。
2. 创建设备，驱动选择“ControlLogixMaster”，并选择刚创建的 TCP 客户端通道。
3. 配置设备协议参数，保存后新增变量。变量的“寄存器地址”始终填写控制器标签名，不填写易失的 Physical 地址或 Symbol Instance。

当前驱动只开放单跳 TCP：默认路径为 TCP 端口 44818、背板端口 1 和 CPU 槽位。多跳背板、网桥或其他路由路径需要目标型号和固件的专项验证，未验证前不要在地址中拼接路由字符串。

支持范围

项目	当前范围
通道	TCP 客户端；同一物理连接串行处理请求。
路由	单跳 Backplane + Slot。
标签	全局标签、已浏览的 Program Scope 标签、数组下标和结构成员路径。
运行时类型	Boolean、Byte、Int16、UInt16、Int32、UInt32、Int64、UInt64、Float、Double、String。
暂不作为通用承诺	完整 UDT 读写、STRING 数组、TIME、Decimal、多跳路由及未验证的控制器型号/固件组合。

AB 真机、UDT 以及 STRING 的完整控制器语义仍需在目标型号、固件和网络拓扑上验证。未完成现场验证时，生产配置应优先使用已确认的 Symbolic 标签和只读变量。

通道参数

以下参数由 TCP 客户端通道负责，设备页面不会重复创建同名字段：

参数	默认值	说明
RemoteUrl	示例值	完整的 主机:端口，ControlLogix 通常使用 44818。支持主备远端时，切换后会清除旧 Session 和连接标识。
ConnectTimeout	3000 ms	只限制 TCP 建连阶段；不包含 CIP 请求等待。
CacheTimeout	500 ms	TCP 粘包/半包的收帧缓存时间，不等于设备请求超时或 Watchdog。
RetryCount	3	采集层失败重试次数。驱动内部的连接重建最多再恢复当前请求一次，写入时不要把两层重试配置得过高。
Timeout（方案语义名 RequestTimeout）	3000 ms	从发出设备请求到收到并匹配完整 CIP 响应的等待上限。
SendDelayTime	0 ms	每个物理请求发出前的延时，不改变采集周期。
DutyCycle、WritePriority	公共默认值	由 Runtime 读写锁控制读写交错和写优先级。
LogLevel	公共默认值	调试阶段可提高日志级别查看会话、连接标识、序号和 CIP 状态。

UseSSL 是通用 TCP/TLS 包装，不等于 ControlLogix CIP Security；Heartbeat/HeartbeatTime 不是合法的 Connected CIP 保活事务；CheckClearTime 只用于 TCP 服务端客户端清理。不要用它们替代本驱动的协议级空闲 Watchdog。

设备参数

参数	默认值	范围或单位	说明
Slot	0	0-255	CPU 在机架中的槽位。CompactLogix 仍需按实际端口和模块布局确认。
Backplane	1	路径段	访问 CPU 使用的背板端口。当前只支持单跳背板。
ProtocolMode	Symbolic	Symbolic、LogicalNonBlocking、LogicalBlocking	选择标签名或当前项目元数据生成请求路径。首次接入或未完成项目浏览时使用 Symbolic。
ConnectionSize	500	500-4000 字节	Forward Open 请求的 O→T/T→O 连接容量。设备不接受请求值时，驱动按 3840、2048、1024、500 等候选值回退。
InactivityWatchdog	32	秒；0 表示禁用	无业务通信达到该时间后主动关闭并重新注册 Session/Forward Open，避免继续使用控制器已释放的连接。
MaxPack	500	1-1980 字节	单次连接式 CIP 业务请求预算，包含编码后的标签路径、服务头、偏移表、CPF 和数据。它不是标签数量，也不是数组元素数。

调试页刷新摘要中的 ActualConnectionSize 是只读运行态值，表示最后一次成功 Forward Open 实际采用的连接容量；它不是可保存配置。业务请求和自动分片始终取 MaxPack、ActualConnectionSize 与协议硬上限的最小值。

ProtocolMode 与地址路径

变量地址只填写稳定标签名，驱动根据模式和当前项目快照生成实际 CIP 路径：

模式	读取路径	写入路径
Symbolic	直接按标签名编码 Symbolic EPATH。	直接按标签名编码 Symbolic EPATH。
LogicalNonBlocking	使用浏览得到的项目映射；固件版本 V20 及以下使用 Physical 地址，V21 及以上使用 Symbol Instance。	使用浏览得到的 Symbol Instance。
LogicalBlocking	使用同一项目映射和固件规则生成 Logical 路径；当前实现与 NonBlocking 共享地址转换契约。	使用浏览得到的 Symbol Instance。

项目映射带有快照标识。在线编辑、下载或重新浏览导致快照变化后，旧 Symbol Instance/Physical 地址会失效，Logical 请求会明确失败；请刷新标签目录后再继续。未知固件或没有可靠项目元数据时，不要手工填写实例号，改用 Symbolic 并先做只读验证。

地址规则

场景	示例	说明
标量标签	TankLevel	标签名大小写和作用域必须与 PLC 工程一致。
一维数组元素	Counts[0]、Counts[255]	下标从 0 开始，公开范围为 0-65535。
连续数组	Counts	变量的“数组长度”填写逻辑元素数，驱动自动按元素宽度分片。
多维数组	Matrix[1,2]、Cube[1,2,3]	支持 1-3 维，按行主序折算；空维度、负数、未闭合括号和超过范围的下标会被拒绝。
Program Scope	Program:MainProgram.Speed	Program:<程序名>.<标签名>，程序必须能从在线浏览结果中取得。
结构成员	Motor.Status	只在当前类型和模板元数据可解析时使用；完整 UDT 变量不自动导入。

不支持把 Physical 数字地址直接写进变量地址，也不支持用字符串包含关系猜测结构成员。数组、结构或索引超出当前工程公开范围时，先在调试页浏览确认，再创建变量。

数据语义

BOOL

BOOL 标量按一个逻辑值读写。BOOL 数组在线协议使用小端 DWORD 线布局：每个协议元素承载 32 个逻辑 bit，[0] 位于第一个 DWORD 的最低位，返回到变量时再展开为每个逻辑元素一个布尔值。数组长度为 31、32、33 或 255 时，驱动会分别计算所需 DWORD 数并在边界处分片；不要把逻辑 bit 数直接当成字节数。

Byte

Byte 是一字节运行时类型。控制器中的 SINT、USINT 或 BYTE/D1 可能返回不同的 CIP 类型码，驱动会保留并校验实际类型码；创建变量时应以 PLC 工程类型和调试响应为准，不要用 Byte 掩盖类型不匹配。

STRING

ControlLogix STRING 由 LEN（DINT）和 DATA（SINT 数组）组成，变量地址填写字符串标签名，例如 RecipeName，不要把 .LEN 或 .DATA 作为普通变量长期配置。

• 读取时驱动先取得长度，再按 DATA 字节数读取并按 UTF-8 交付；长度是未填充的实际字节数。
• 写入非空字符串时按 LEN、DATA 顺序提交；DATA 为奇数字节时在线协议补一个尾部填充字节，但 LEN 仍保持原始字节数。
• 写入空字符串时将长度写为 0，不发送无意义的 DATA 数据；LEN 或 DATA 任一子服务失败都会报告整体写入失败。
• STRING 数组、超过控制器定义最大长度的内容和完整 UDT 字符串成员需要目标控制器专项验证，不能按普通 String[] 导入。

自动分片与读写

采集变量的“数组长度”表示逻辑元素数量。驱动按标签路径编码长度、元素宽度、BOOL DWORD 规则、MaxPack 和最后一次成功握手的 ActualConnectionSize 自动计算每片大小，并使用连续偏移完成大数组读取和写入。用户不需要手工把同一数组拆成多个变量。

当单个标签的路径和最小服务开销已经超过预算时，驱动返回带标签地址的超限错误；它不会发送一个明知超出连接容量的请求。分片响应的 More 状态、偏移、服务码、类型码、General Status 和 Additional Status 都会校验，取消操作不会重放已经确认的写入片段。

调试工作台

进入“开发配置 → 采集配置”，选中 ControlLogix 设备，点击“更多功能 → 调试”。页面首次打开会刷新当前在线标签目录，并以项目快照保存结果。

浏览、筛选和分页

1. 点击“刷新”从控制器读取全局和 Program Scope 标签；刷新摘要显示标签总数、可导入数量、当前 ProtocolMode 和 ActualConnectionSize。
2. 在搜索框按标签名或结构模板名筛选，按需勾选“包含系统标签”。按回车或清空搜索重新加载第一页。
3. 表格显示 Symbolic 地址、Symbol Instance、Physical 地址、类型、维度、External Access、实际读协议、写协议和项目快照。分页大小可选 20、50 或 100。
4. 勾选会按稳定的 Symbolic 地址跨页保留；切换设备或点击“刷新”后，旧选择会清空。

导出和导入

• 未选择行时，“导出”导出当前筛选条件下的全部可导入标签；有选择时只导出跨页选中的标签。
• 导出内容可直接用于当前设备的变量配置，保留标签名、数据类型、数组长度和读写保护信息。系统标签、结构模板、不可读标签和超出变量数组上限的标签不会导入。
• “导入”使用相同的选中/筛选规则写入当前采集设备，并返回变量名、地址、类型和现有记录的冲突预览。确认对话框通过后才执行，操作受调试写权限保护并记录操作日志。
• 项目重新下载或在线编辑后，先点击“刷新”得到新快照，再重新导出或导入；不要继续使用旧 Excel 中的 Physical/Instance 描述进行手工写入。

消息和读写验证

使用消息面板查看 Register Session、Forward Open、Connected CIP、分片、Forward Close 和 Unregister 的结果。首次上线按以下顺序验证：

1. 读取一个已确认的标量标签，核对值、类型码和路径。
2. 读取一个小数组，核对元素顺序；再使用 31/32/33 等 BOOL 数组边界。
3. 在授权测试标签上写入临时值，立即读回并恢复原值；字符串还要覆盖空值、非 ASCII 和奇数字节长度。
4. 查看消息中的连接容量、General Status、Additional Status、Session/Connection ID 和 sequence 是否连续。

安全和上线注意事项

• 写入前必须确认 PLC 处于允许测试的模式，变量 External Access 和 Runtime 写权限均已开放，并准备好恢复值。禁止对生产联锁、输出线圈或未知标签做破坏性写入。
• 设备级写入使用 Runtime 的写锁、取消令牌和 Check 语义；DeviceStatus、Script、ScriptRead 等运行时变量只在网关本地处理，不会发往 PLC。
• 连接断开、Session 失效、Forward Open 冲突和 Watchdog 释放会清理旧标识并最多重建当前请求一次；协议格式错误、地址错误和权限错误不会无限重试。
• 同一 TCP 连接最终按单线程处理。通道的并发配置不会改变 Connected sequence 的串行约束。
• 现场验收必须记录控制器型号、固件版本、通信模块/桥接路径、请求和有效连接容量、ProtocolMode、读写帧摘要、分片次数、耗时及恢复结果。模拟器或单一外部客户端结果不能替代 AB 真机验收。

常见问题与排查

现象或状态	排查步骤
TCP 无法建立	检查 RemoteUrl 是否包含 :44818、网卡路由、防火墙、控制器 EtherNet/IP 服务和连接容量；ConnectTimeout 只覆盖建连阶段。
Session 或连接反复重建	查看消息中的封装状态、Connection ID、sequence 和 Watchdog 时间；确认控制器没有达到连接上限，并核对 ActualConnectionSize。
路由失败或 Forward Open 拒绝	核对 Backplane=1、CPU Slot 和实际机架拓扑。当前不接受未经验证的多跳路径。
标签不存在或 Logical 请求被拒绝	检查大小写、Program Scope 前缀、数组下标；Logical 模式先刷新在线目录，项目快照变化后不得使用旧映射。
0x06 响应过大或分片失败	降低 MaxPack，确认 ConnectionSize 与 ActualConnectionSize，检查数组长度和元素类型；不要手工重放已完成片段。
BOOL 数组值错位	确认变量数据类型是 Boolean、数组长度正确，并按 32 bit DWORD 语义检查边界，不要按每 bit 一个线字节解读。
STRING 长度或乱码	先读回 LEN，再检查 UTF-8 字节数、控制器最大长度、奇数长度补齐和是否误把 .DATA 当普通字符串标签。
写入被拒绝	检查 PLC 运行模式、External Access、变量保护、调试写权限和现场联锁；确认不是结构模板或只读系统标签。
导入没有生成变量	重新刷新目录，取消“包含系统标签”以外的筛选，确认 External Access 可读、标签不是结构模板且数组长度不超过变量上限。

相关操作

• 采集配置：通道、设备、变量和数据格式的公共配置。
• 插件索引：其他采集与数据转发插件。