汇川 EVO 系列 PLC EtherNet/IP(CIP)协议通信驱动的 C# 实现
本文档描述 InovanceEvoEipDriver 的当前实现形态:一个面向汇川 iFA Evolution(EVO)系列 PLC、直接踩在 EtherNet/IP(CIP)协议之上的 .NET Framework 4.0 类库。驱动不依赖任何厂商运行时,全部报文构造、分帧、符号路径编码、类型编解码都在本库内完成;符号表来自 iFA Evolution 导出的 XML。
协议栈自下而上分为五层:Socket 分帧(TcpClient)→ EtherNet/IP 封装(Encapsulation)→ CIP 服务与符号路径(EipStructures)→ 数据类型编解码(StructCodec / PValue)→ 门面与读写引擎(InovanceEvoEipDriver)。门面之上另有一层 DriverContracts 契约适配器,供统一契约的宿主使用。
驱动当前共 15 个源文件、约 6800 行,全部经汇川 EVO 仿真器与现场设备联调,并与汇川官方 EIP 标签通信库做过逐项对拍。
一、背景与总体架构
1.1 依赖关系
驱动本体是一个自包含的旧式 csproj 类库,目标框架 v4.0,唯一的 NuGet 依赖是 Net4x.Extensions.Logging.Abstractions(ILogger 抽象的 .NET 4.x 端口)。对共享契约 DriverContracts 的工程引用只出现在契约适配器源文件里,主类不感知契约类型------这一分层是所有兄弟驱动(西门子、罗克韦尔、欧姆龙、CODESYS)共同的"依赖反转"形态,使品牌层可以在脱离契约的情况下单独编译。
javascript
宿主应用(GUI / console / 上位机)
└─ InovanceEvoEipDriver 门面(Connect / Read / Write / WriteByText / Browse / 重连 / 日志)
├─ InovanceEvoSymbolXmlFile + VarTreeStructures(iFA 导出符号 XML → 运行时变量树)
├─ PValue + StructCodec(IEC 类型值层次与线编解码)
├─ EipStructures + Encapsulation(封装层报文、CIP 路径与服务)
└─ TcpClient(自研 Socket 封装:EtherNet/IP 分帧 + 串行化收发)
1.2 设计要点
- 没有符号注册这一步 。欧姆龙 NJ/NX 驱动走"符号句柄注册表 + 句柄批量读写",EVO 不吃这一套:它的符号访问就是把点分名字现编成 CIP 符号段(
0x91)打进请求里。这省掉了一整张注册表及其生命周期管理,代价是每请求都做一次路径编码。 - 批量读不借符号元服务 。罗克韦尔的打包读会在 N 条子请求之前多塞一条对 class
0xAC(Symbol 对象)instance 1 的Get_Attribute_List(它的打包写不塞);EVO 读写两条都直接嵌 N 条0x4C/0x4D,符号名字段就在每条子请求自己的路径里,段内不含任何0xAC包装(Encapsulation.cs注明"EVO 抓包验证:不携带罗克韦尔 0xAC 元服务")。欧姆龙有同款打包构造器但门面没接,批量读仍是逐点发。 - 类型码按 EVO 实测确定 。
BYTE/WORD/DWORD/LWORD用0xD1--0xD4,而不是USINT/UINT/UDINT/ULINT的0xC6--0xC9------见第四节。 - 字节序不做成参数 。整条链路一律小端(
BitConverter),没有暴露字节序开关:EtherNet/IP/CIP 本身就是小端协议,这一层没有可配置项。 - 状态逐实例 。会话句柄、连接 ID、序列号、包大小上限、重连相位、符号树、日志闸全是实例字段。全类的
static只剩常量与纯函数。进程级静态状态冒充逐连接状态是本仓库反复出现过的缺陷类,本家在结构上就断掉这条路。
1.3 连接建立
EtherNet/IP 是"会话 + 连接"两级模型。EVO 不建模背板槽位,Connect 因此只有地址与端口两个入参:
csharp
public bool Connect(string ipAddress, int port = 44818)
顺序是:装配 TCP → RegisterSession(命令 0x0065,28 字节 = 24 字节头 + 4 字节协议版本 1)→ 尽力读一次设备标识 → ForwardOpen → 启动心跳与重连监听。
ForwardOpen 这一段是本家比较"手工"的地方:先试 LargeForwardOpen(0x5B),失败回退普通 ForwardOpen(0x54),两条路径只差连接尺寸字段(1996 / 490 字节)。请求里 OriginatorVendorID = 0x067C(1660,汇川自己的厂商号)、ActualTimeout = 0x9C05、RPI 2000000(2 s)、连接参数 0x4200、传输类型 0xA3、连接路径固定 14 字节 34 04 00 00 ... 20 02 24 01。响应回来的 O_T_ConnectionID 之后一直当 SendUnitData 的地址项用。
OpenConnection 开头有一句值得抄进检查清单的注释------ConnectionStatusDescriptor 必须为 0,否则仿真器会直接断开连接。这不是猜的:
csharp
// ConnectionStatusDescriptor 必须为 0:仿真器实测(2026-11-10)非 0 时
// EVO 在 ForwardOpen 响应之后直接断开 TCP 连接。
半途失败必须收尾:RegisterSession 已经成功、ForwardOpen 抛或被拒时,如果只断 TCP,控制器侧会留下一份孤儿会话,攒到会话数上限就连不上了。因此失败路径按 Disconnect 同口径先尽力 UnRegisterSession 再释放 socket,且清理失败不得跳过后面的步骤。
二、EtherNet/IP 封装层与请求---响应串行化
2.1 报文头与命令
24 字节封装头:命令(2)、长度(2)、会话句柄(4)、状态码(4)、请求上下文(8)、可选协议版本(4)。会话句柄存在实例字段 _sessionHandle 上,从响应头取回,为 0 立即抛。
驱动实际只发四类命令,其余(ListServices 0x0004、ListIdentity 0x0063、ListInterfaces 0x0064)只在枚举里声明、没有调用点------留着是因为协议文档上有,不代表我们推荐用:
| 命令 | 码 | 用途 |
|---|---|---|
| RegisterSession | 0x0065 | 建立会话 |
| UnRegisterSession | 0x0066 | 注销会话 |
| SendRRData | 0x006F | 未连接报文(Identity、ForwardOpen) |
| SendUnitData | 0x0070 | 已连接报文(日常读写、心跳) |
所有请求的 Options 恒为 0、SenderContext 8 字节全 0、InterfaceHandle 与 CIP 层 Timeout 未使用。
2.2 分帧与串行化
TcpClient 是仓库自研的 Socket 封装(不是 BCL 的 TcpClient),按封装头偏移 2 的长度字段 + 24 计算一帧边界,用 while 连续提取缓冲区里所有完整帧------粘包和半包同一条代码路径覆盖。这里修过一个真实缺陷:早期版本只检查一次边界,一次 Receive 收到两帧时第二帧会滞留。
接收侧是 BeginReceive(1460 字节)+ 后台线程 + PDU 队列,但对上层的 API 语义是同步阻塞 :SendAndReceive 在截止时间内等一条响应,驱动侧显式传 2000 ms。整个请求路径由一把 _sendLock 串行化,一条连接同时只有一个在途请求。
两个细节值得单独说:
- 发送前先清掉队列里滞留的 PDU;带期望序列号时,在剩余截止时间内丢弃序号不匹配的迟到响应。否则上一轮超时留下的旧包会被这一轮捡走,错配得极其隐蔽。
- 序列号有两个,别混:
_sequenceCount是逐请求 递增的 CIP 连接地址项序号(回绕时0 → 1,锁保护,重连不复位);ConnectionSerialNumber是 ForwardOpen 连接标识,另走一张 0..65535 的 Fisher-Yates 洗牌唯一发放表,用尽直接抛------它的用途之一正是判断控制器侧是否还残留旧连接。
TCP 层另有一次性探测:CheckForTcp 在正式连接之前用一个短命 socket 单独走一遍 RegisterSession,拿到非 0 会话句柄就立刻补一发 UnRegisterSession 再关闭------探测本身也不给控制器留孤儿会话。远端关闭或异常时 ConnectionLost 只发一遍,避免上层被同一个故障打断多次。
三、CIP 层:符号路径直接寻址与打包读写
3.1 服务与路径
| 服务 | 码 | 用法 |
|---|---|---|
| Read_Tag | 0x4C | 单点读,打包进多服务 |
| Write_Tag | 0x4D | 单点写,打包进多服务 |
| Multiple_Service_Packet | 0x0A | 外层容器,路径 class 0x02 / instance 0x01 |
| ForwardOpen / LargeForwardOpen | 0x54 / 0x5B | 建立连接(先大后小回退) |
| ForwardClose | 0x4E | 释放连接 |
| Get_Attribute_Single | 0x0E | 心跳 |
| Unconnected_Send | 0x52 | 未连接转发(Identity) |
注意 Read_Modify_Write_Tag 与 ForwardClose 同为 0x4E,枚举里是别名;本驱动只在释放连接时发这一位,不做读改写。
符号路径按 . 拆段后逐段编码:名字段是 0x91 + 1 字节 UTF-8 字节数 + 内容 + 补零(中文名合法 ,EVO 变量名支持中文,实测过中文叶的读写往返);数组下标是成员段 0x28(≤255)或 0x29 + 2 字节,多维就是每个下标一个段;纯 1--2 位数字段当作位地址跳过(Tag.5 这种写法)。路径长度字段以"字"为单位(段字节数 / 2),B1 项数据带 2 字节连接序号,编解码两侧互为镜像。
响应解析取偏移 2 的单字节 general status,值区从偏移 4 起,附加状态按长度 0 约定跳过。扩展状态码目前没有解析------设备回 0x13/0x15/0x1E 时能报出主状态码与标签名,但拿不到厂商给出的附加说明。这是明确的待办,不是遗漏。
3.2 一处设备能力差异:Identity
连接建立后驱动会尽力读一次设备标识(0x52 未连接转发 + Get_Attribute_Single,class 1 / instance 1)。EVO 实测回 Path segment error。处理方式是在外层再套一层捕获,只记一行告警,不让一次"读不到名牌"毁掉已经建好的连接。设备信息因此主要靠离线符号 XML 的 ProjectInfo 回填(工程名 / 设备名 / 应用名 / 版本)。
这条经验值得推广:"可选的装饰性调用"必须显式降级,否则同一份代码在不同厂商设备上会因一家不支持的可选服务而整体判故障。
3.3 心跳与自动重连
门面里有一套五家同形的重连骨架,本家是这一轮"同形(含实现代码)"的取材来源------判据不是"看起来一样",而是脚本把五家门面的生命周期区逐字符比对,只允许品牌类型名与各家握手调用不同,其余差异必须显式登记才放行。骨架内联在门面类里(不额外给每家加一个类型),开关与事件留在原生面(契约不扩成员)。参数在这一轮换过一次名,宿主可见:AutomaticReconnect(缺省 true)→ Reconnect.Enabled(缺省 false)、RetryCount(-1 = 无限)→ MaxRetries(0 = 无限)、RetryInterval(固定 5000 ms)→ InitialDelayMs / MaxDelayMs / Multiplier。
- 心跳:2000 ms 定时器,距上次交互超过 5 s 时发一条
Get_Attribute_Single,连续 2 次失败判链路死。 - 相位机:
LifecyclePhase { Closed, Connected, Reconnecting, Lost }+ 世代计数。所有写全局字段的重连线程动作前都核对代次,宿主另起Connect时先DisarmLifecycle,避免"宿主已重连、上一轮重连线程又把会话建起来"的竞态。 - 退避:
DelayBeforeAttempt是纯函数,1000 ms 起步、×2、封顶 30000 ms;MaxRetries = 0表示不限;Reconnect.Enabled缺省 false。 RebuildSession每一轮自清残骸(旧 socket、旧会话、旧连接 ID),不再用Thread.Abort,改用Join(3000)+ 事件把手打断。- 重连成功后事件
Reconnected上屏,读恢复;不重新加载符号表(EVO 的树本来就在本地文件里)。
真机验证方式是掐透明中转(本机端口 → 仿真器 44818),实测按 1/2/4 s 退避、第 4 次握手成功(累计 13828 ms),期间轮询读 265 次、恢复后 0 失败。
四、数据类型与线格式
4.1 类型码是实测出来的
VarType 的成员取值直接就是实机响应里的 CIP 类型码,不是照抄规范表:
sql
BOOL C1 SINT C2 INT C3 DINT C4 LINT C5
USINT C6 UINT C7 UDINT C8 ULINT C9 REAL CA LREAL CB
DATE CD TIME_OF_DAY CE DATE_AND_TIME CF STRING D0
BYTE D1 WORD D2 DWORD D3 LWORD D4
WSTRING D5 LTIME D7 TIME DB
BYTE/WORD/DWORD/LWORD 走 0xD1--0xD4 这组 EVO 方言码,与 USINT 家族的 0xC6--0xC9 是两条线------DATE/TOD/DT 落在这两组之间。这些值全部由 2026-11-11 那轮"逐类型实读、取响应 data type 字段"的联调确定。枚举里另有一层树节点语义类型(STRUCT A2、ARRAY A3、Program 0x68、VARINSTANCE -2、ROOT -3),只服务于树展示与容器判定,不上线。
4.2 字符串、BOOL 与结构体
- STRING:
[len 2B][UTF-8],读与写同形。它不是 IEC 那种 81 字节定长布局,也不是句柄风格。声明容量 STRING = 81 B、WSTRING = 162 B,与符号表 XML 一致。 - WSTRING:
[len 2B][UTF-16LE]。曾经按"capacity 前缀"写法发过,EVO 直接回0x13,实机写实验之后统一成无 capacity 形态。 - BOOL:独立标签线上占 2 字节(值 + 填充),结构体成员里只占 1 字节,数组里按 1 字节/元素紧密排列。三处形态各不相同,是最容易写错的一处。
- 写请求值区:
[dtype 2B][count 2B][raw];读响应值区:[dtype 2B][值...]。未知类型码有兜底猜测(GuessTypeFromCode),猜不出就判不可转换而不是返回半个值。 - 结构体:成员偏移直接取符号 XML 的
byteoffset,因此不需要任何在线模板/类型服务。实际路径是逐成员读写 ------整块功能体(FB)读写在 EVO 上实测无响应,所以门面把"读一个结构体"扇出成按成员路径的若干次访问。StructCodec.DecodeStruct只作为整块回包时的后备解包存在。
4.3 PValue
值层次由 39 个值类组成:20 个标量与复合类(ValueBool、8 个整数类 ValueSInt/ValueInt/ValueDInt/ValueLInt/ValueUSInt/ValueUInt/ValueUDInt/ValueULInt、ValueReal/ValueLReal、ValueString/ValueWString、ValueTime/ValueLTime、ValueDate/ValueTimeOfDay/ValueDateAndTime、ValueStruct、以及表示"无值"的 ValueNull)+ 19 个对应的数组类(含 ValueStructArray)。三个入口分工明确:
csharp
public static PValue Create(VarType type, object value) // 公开工厂:按线级类型建值
public abstract string ToStringWithType() // 纯文本形态(WriteByText 要的就是它)
internal static PValue FromString(string raw, VarType t) // 文本解析:失败/空白回 null,不抛
Create 对 null 入参落的是该类型的零值 (WORD → (ushort)0、LTIME → 0L...),不是 ValueNull;容器等不可写类型直接抛 ArgumentException。BOOL 走一个专门的宽容转换:
csharp
// GUI 文本写常传 "1"/"0", Convert.ToBoolean 只认 "True"/"False" 字符串会抛 FormatException
FromString 反过来------空白输入或解析失败一律回 null 且不抛 ,由调用方决定怎么说失败。两条文本通道方向不同,别记反:ToStringWithType 是值 → 文本 (demo 与 GUI 用它显示读回来的值、比对两次读是否一致),FromString 是文本 → 值 ,全仓只有一个调用点,就是门面的 WriteByText。于是"值缺失"由 ValueNull 表达(读失败时门面返回它,原因进错误账),"文本转不过去"由 null + 一行账本原因表达,两者不混。
五、批量读写:按字节分包
分组引擎与罗克韦尔同形(贪心装箱 + 0x0A 多服务报文),源码里多处注明"与 Rockwell 口径一致";欧姆龙虽有同款的打包报文构造器,门面批量读却没接上去。本家真正的差异在寻址形态、尺寸估算与失败回退三处。
上限只有尺寸,没有条数。 _maxPacketSize 由连接类型决定:普通 490 - 100 = 390,Large 1996 - 100 = 1896。单只标签的开销估算:
csharp
// 路径 + 服务头 + 响应类型码与状态开销的保守估计
return dataSize + node.FullPath.Length * 2 + 50;
dataSize 按解析出的类型取:数组取元素大小 × 元素总数,结构体取 StructureSize。GroupTagsWithPackets(读)与 GroupWrites(写)共用这套估算,按顺序装箱成多个 0x0A 请求。
响应切分。 每条子响应的首偏移是 N × 2 + 2,之后按相邻偏移之差顺序切片------没有元服务,所以切分完全依赖"回包按请求顺序原样排列"这一实测约定。
权限不预判,靠回包定位坏点。 组里混进一只只写标签,整组回 0x1E;写组里混进只读标签,同样整组 0x1E。此时回退成逐标签单发,把坏点定位出来(详见 6.6)。真机日志里就有这一格:16 点批量先整批被拒,剔掉 1 只只写点后其余 15 点读通、账本干净。
数组访问的四条硬边界(全部实测得出,写进注释与文档):
- 数组整体读写用在线类型码
0x4E2D,逐维带 count,BOOL 数组 1 字节/元素; - STRING/WSTRING 数组不支持整体访问,EVO 回
0x15(官方文档亦明确一次只能访问一个元素)→ 驱动按多维下标逐元素展开读写再组装; - 带下标的路径只允许
count = 1,count > 1与下标越界同样回0x15; - 功能块数组按
FB[i].成员逐元素组装成ValueStructArray。
曾经有一个静默缺陷藏在这里:路径编码缺三维及以上的下标分支,[i,j,k] 被降级成"无下标路径"------不报错,只是读到另一个对象。修完之后本家补了逐维下标的正反用例,并且把 ≥3 维的覆盖固定进冒烟测试。
回填按原始下标对齐。 分组会打乱顺序,SendReadGroup 回的是"原列表下标 → 值"的键值对,上层按这个索引写回值表;整批失败时把 values 直接置空列表,绝不留旧值冒充新值。
六、符号表:只吃离线导出
6.1 没有在线符号表通道
LoadSymbolsFromPLC() 无条件抛 NotSupportedException,理由写在注释里:EVO 的抓包里从未观察到符号表上传/下载服务。契约侧 LoadSymbolsOnline() 因此恒返回 false,GUI 上保留一个"在线取树"按钮,用途就是演示这一抛(保留而不删)。驱动不因缺少在线符号表而假装支持,也不静默回退到陈旧缓存------这是本仓库对"能力边界"的统一口径。
6.2 载入的三类坏输入
LoadSymbolsFromFile 对坏输入统一"return false + 一行 Warning 原因",异常不越出 API:
- 路径级校验(空 / 指向目录 / 文件不存在 / 长度为 0 / 存在但打不开);
- XML 解析异常(非 XML、编码错、被占用)收口成一行原因,不把
XmlException堆栈甩给调用方; - 解析出 0 个符号节点判"非汇川 EVO 符号表 XML"。
不设扩展名门:后缀对但内容异构的文件由第 3 道判掉,比按后缀拦更早暴露真实原因。解析只发生在局部对象上,失败即返回,驱动里上一棵可用树不会被碰过(旧实现会把 _rootNode 留在半切换状态)。
6.3 方言闸门:一次真实的误判
EVO 导出与 CODESYS 符号导出的根元素同名 (都是 Symbolconfiguration),元素名也大面积重叠(TypeSimple / TypeUserDef / NodeList / Node),而解析器按元素名匹配、完全不看命名空间。后果不是"解析失败",而是更坏的情况:
交叉试跑旧版解析器,一份 1 MB 的 CODESYS 工程物化出 1978 个节点并被判定成功。两份 schema 字段口径不同(CODESYS 的
UserDefElement只有iecname没有name,顶层Node用nodeflags而 EVO 用offset),得到的是一份结构体成员名全空、看着能用实则地址不可用的符号表,且没有任何一行日志说明。
修法是把判定推到"看到的第一个元素",即读即拒:
csharp
string rootNamespace = r.NamespaceURI;
if (!string.IsNullOrEmpty(rootNamespace) &&
rootNamespace.IndexOf("3s-software.com", StringComparison.OrdinalIgnoreCase) >= 0)
throw new CIPException("非汇川 EVO 符号表 XML: 文档为 CODESYS 符号导出 (命名空间 " + rootNamespace + ")");
兜底再认 Header 的直接子元素 SymbolConfigObject(两家真样本都挂在同一位置)。真 EVO 导出没有命名空间,这条路径一字未改。驱动 catch 的 Warning 一并写出异常类型名,让"方言拒绝"与"真 bug"在日志里天生可分。
6.4 流式解析与建树
百万级符号表是这一节的驱动力。类型表按 简单 → 结构体 → 数组 的顺序解析(结构体成员可引用其他结构体,数组必须最后),NodeList 用显式栈建树、不递归:
csharp
if (r.NodeType == XmlNodeType.EndElement && r.Name == "Node")
{
stack.Pop(); // 容器节点出栈(只有非空 Node 曾入栈,XML 良构保证配对)
continue;
}
这段代码上注释提到的"入栈条件与出栈条件必须配对",是重写时抓出来的缺陷:早先漏了出栈,兄弟组会挂到错误的父节点上。类型对象按名字共享(原子与纯数组类型不可变、读写路径只读),每个变量零拷贝。
数组语义有一处必须写死的约定:ArrayDimension 存的是元素总数 (各维 maxrange − minrange + 1 的乘积),Lx/Ly/Lz 才是前三维长度;结构体数组的 DataType 保持 STRUCT、ArrayDataType 有意留 UNDEFINED,"是不是数组"这件事只体现在节点级 Datatype = ARRAY 上。BuildArrayDims 的守卫曾经写反两次:拿 DataType == ARRAY 提前 return,而类型对象里存的从来只是元素 类型,于是各维长度恒为 null;把守卫改成 ArrayDimension != 0 之后,又拿这个总数当维数去 switch。现在的写法是"按实际填了哪几维定维数"(Lz>0 取三维、否则 Ly>0 取二维、否则 {Lx 或总数}),注释里把这段历史原样留着。
6.5 树语义与懒合成
Browse(parentPath) 返回指定路径节点的子节点列表;空串表示根,路径不存在返回空列表(不抛)。符号表里结构体与数组节点没有真实子节点 ,全部由 GetChildren 按需合成:
- 结构体 → 成员子节点,
FullPath = 父路径.成员名; - 数组 → 全部元素平铺 成直接子节点,一维用序号、多维用逗号下标(
gvl11[0,1,2],末维变化最快),没有中间维度节点; - 结构体数组的元素再展开成成员;
- 合成节点继承父节点访问权限。
合成结果挂在节点对象上(CachedSynthChildren),首次访问构建、后续直接命中;重载符号表时整棵旧树连同缓存一起被丢弃(载入只在新解析出的树上做)。容器判定不触发合成:真实子节点存在即可展开,否则按类型枚举兜底。这里也踩过坑------Application、GVL 表这类"没有类型但有真子节点"的分组节点曾被纯按类型判成非容器,GUI 展不开、采样收 0 叶子,修复就是引入"真实子节点优先、类型枚举兜底"这条顺序。注意 IsContainer == true 并不保证真展得出成员(结构体声明零成员这类极端情况会展开为空),这一点在文档里明写,不做过度承诺。
可寻址 key 就是 FullPath 去掉 ROOT. 前缀,全路径索引用 StringComparer.Ordinal 建,成员路径(gvl23.PV)查询 O(1)。
6.6 权限
AccessRight 有五个取值:ReadWrite = 0 / WriteOnly = 1 / Read = 2 / None = 3 / Unknown = 255(WriteOnly = 1 只有本家有------罗克韦尔与欧姆龙的同名枚举是 None/Read/Write/ReadWrite 四项,本家反倒没有 Write;按裁定不"顺手统一")。解析器认 XML 里的 readwrite / readonly / writeonly / public(视为可读写)/ none 五种写法,其余一律落 Unknown------"没读到权限属性"与"权限确实是无"是两件事,不合并。
驱动发请求之前不做权限预判------只读标签被写不拦、写只读标签被读也不拦,裁判是设备返回值,不是我们手抄一遍的厂商权限矩阵。事实上驱动里没有任何一处按 AccessRight 过滤请求:权限只随 SymbolNode.Access 交给宿主展示。坏点靠回包定位:读组内含只写标签、写组内混只读标签,EVO 都让整组 回 0x1E(Embedded service error),驱动随即回退成逐标签单发,让好的成功、坏的抛出带标签名的明确错误。GUI 的交互也只是"提示":读/写/文本写三个入口各调一次 WarnAccessMismatch,三条文案(无权限、写只读、读只写),弹窗之后照常按请求发出;Unknown 不提示。这条口径来自全部六份 GUI 的统一裁定:"节点文本只有名字,权限不匹配只在执行读写时弹窗且照常执行。"
七、门面 API 与错误账
工作面是品牌原生 API(契约程序集已停止演进,适配器只保证编译与行为不回退)。门面公开面如下,符号一律用点分路径字符串------早期版本里"把节点包成 ItemAddress 句柄再传回来"的形态已经整体移除:
csharp
bool Connect(string ipAddress, int port = 44818)
bool Disconnect()
bool Read(List<string> symbols, out List<PValue> values)
bool Write(List<string> symbols, List<PValue> values)
bool Write(string symbol, PValue value)
bool WriteByText(string symbol, string value)
PValue Read(string symbol) // 单点读:五家里本家独有的形态,按裁定保留
PValue Read(string symbol, int count)
List<SymbolNode> Browse(string parentPath)
bool + 逐实例错误账。 门面核动作返回 bool,失败细节走 LastErrorCode / LastErrorText:0 = 成功、设备码原值(CIPException.StatusCode,如 0x15、0x1E)、-1 = 本侧判定(符号未解析、路径非法、设备返回 Null 等)。本侧 -1 与设备码之间不做任何映射表,现场对表时一眼分得清是谁拒的。预期内的现场失败不抛异常;Read(string) 失败时返回 ValueNull,原因同样只进账本。
单点读返回 PValue 而不是 bool 三件套,是这一轮统一里刻意登记的差异之一(连同"保留 WriteOnly 枚举成员"):口径是"失败返回 ValueNull + 填 LastErrorCode/LastErrorText,一样不抛",在源级形状审计里以 INO:KeptShape 一条明确登记。符号清单不齐(含 count <= 0)这类调用错误仍照旧抛 ArgumentException------那是编程错误,不是现场失败。
W3 形参序 :全五家的 Connect 都是"地址 → 端口 → 品牌特有条目"。本家天然只有前两个(无槽号、无凭据),所以那一轮只把形参名改成 ipAddress 对齐词汇表,形参序与默认端口 44818 一字未动。
契约适配层 (InovanceEvoEipDriverAdapter,显式实现 IPlcDriver + ISettingsAware)只做转调与类型映射:原生 SymbolNode ↔ 契约 CTagInfo、本家 39 个 PValue 值类 ↔ 契约值类、AccessRight ↔ 契约枚举;"EVO 无在线符号表服务"这条设备事实由契约的 LoadSymbolsOnline() 恒返回 false 表达。契约程序集已停止演进,适配器只保证编译与行为不回退,不再往里加新能力。
八、性能
- 离线解析 :400 万级符号表是现场真实遇到过的量级。合成 4,004,400 叶 / 321 MB XML 实测:Release 加载 17.2 s,托管内存增量约 1.5 GB,峰值工作集 1.8 GB;
LoadAllSymbolicInfo3.8 s;随机符号查询 2 万次 130 ms。原 DOM 方案在该量级下内存预估达数 GB。结论是瓶颈只剩一次性 XML 解析,树视图建议按组展开而不是整树铺开。小工程侧另有一个基线数字:214 叶符号解析 7 ms。 - 零分配方向 :
WrapNode纯值包装(句柄时代遗留的IntPtr分配链已整体移除);GetChildCount直接计数,不再为每个子节点分配句柄;原子/数组类型对象按名共享;合成子节点缓存。 - 明确不做的两件事 。对象池在评估后未采用------那是弱句柄时代(v0.4.6)的决策:当时的
ItemAddress是被调用方无限期持有的公共可变对象(GUI 存在TreeNode.Tag上),池化的"租用/归还"生命周期与公共对象身份冲突,复用会带来身份混淆与串扰,而槽位有界已由空闲栈保证;后来句柄整体被纯值形态取代,这个选项就更没有位置了。另一件是热路径(每包/每标签)不打日志:结构化日志调用在调用点就分配 args 数组,内插串更是先拼串后判级。 - 没有做的:端到端吞吐压测、并发多连接实测(当前序列化模型下多线程共用一条连接会在组之间交错,属于已声明的使用边界)。
九、日志
日志闸 DriverLogGate 是各家各持一份的同形原生副本,不在共享程序集里------本仓库定的规则是"日志属原生驱动层,与契约无关"。要点:
- 逐实例:闸跟着门面实例创建,绝不做进程级静态(
DriverLogGate.cs里是明写的注释)。 - 生效级别 = 驱动侧
MinimumLogLevel与宿主ILogger.IsEnabled的交集,缺省Debug;宿主 logger 抛异常一律吞掉;BeginScope永不返回 null。 - 换 logger 不丢已设级别(
Loggersetter 走Use)。 - 实调分布很克制:门面类里
LogError2 处、LogWarning16 处、LogInformation6 处,没有 Debug/Trace 调用点;失败原因统一由Fail()记成 Warning。传输与编解码层(TcpClient、Encapsulation、EipStructures、StructCodec、PValue)以及符号表解析器(InovanceEvoSymbolXmlFile)全部零日志调用------日志只在门面一处出,符号表载入的成功/失败摘要也是门面打的。这与仓库定的"日志只在驱动对外的门面类里出"是同一条规则。 - 符号表载入的成功摘要带上类型表统计:类型总数、
DuplicateTypeNameCount(同名类型重复定义,行为仍是后定义覆盖)、UnresolvedTypeRefCount(引用未声明类型名,行为仍是按 UNDEFINED 解析)。这两项原本是完全静默的口径,现在只观测、不改行为;任一非 0 另记一行诊断 Warning,且放在成功路径末尾,不会伪装成失败原因。已知边界也写清楚:没有type属性的节点不计数(基线工程恰有 3 处,计入会把健康工程报成有病)。
十、测试与验证
分层:
- 离线断言电池 (
TestInovanceEvoEipDriver.Console的check模式,57 项,0 依赖 0 网络;撰写本文时以 Release 产物复跑一次:57 通过 / 0 失败 ):基线建树 1、坏输入拒收 9、"失败不碰旧树" 1、"失败不污染重载" 1、类型表诊断 2、未连接态Disconnect1、重连同形 13、命名面 6、错误账 15、容器形态 2、数组三级形态 6。 - 在线品牌原生流程 (同工程不带
check参数即跑):离线建树 →Connect→ 明确跳过在线取树 → 抽样 32 点批量读 ×2 一致性 → 整批被拒时逐点剔坏点重试 → 固定种子(20261113)的 BOOL 写往返 3/3 且写完复原原值。 - 官方库对拍 (历史轮次,2026-11-11 与 11-12,结论留档在更新履历):当时 console 另有
abtest模式,P/Invoke 汇川官方EipTagSimple.dllV2.0.2.9(DLL 不入库、运行时SetDllDirectory加载)。写对拍 74 项双向一致(本驱动写→官方读、官方写→本驱动读,含全部数组与功能块数组、三维逐元素),读对拍从 159 项扩到 209 项,最后一轮合计 283 通过 / 0 失败 / 5 跳过(跳过的 5 项是只写符号)。对拍顺带发现官方库两处缺陷------读 WSTRING 丢首字符、写 WSTRING 数组元素会把多元素写成同一值(会污染数据,因此对拍的值恢复一律改用本驱动写)。这一模式在 console 改写为品牌原生形态时已移除,需要复做要按履历重建。 - 链路故障 :用可杀的透明 TCP 回环中转替代拔线,验判死、退避、
Reconnected、读恢复、不重新 browse。 - Release 全解决方案重建 0 错误,是每一轮的收口前置。
几条已经写成硬规则的实践:
- 每条探针各用一只新实例 。早期一轮错误账断言"搭便车"跑绿过:前一条探针留下的状态让后一条误判通过。加固之后跑变异才见牙------把
Fail()改成"记 0 码"能红 6 条,把Connect改回抛异常能红 2 条;只红 1 条时会把人带偏到"断点设错了",红得够多才说明覆盖是真的。 - 样例缺失判 FAIL 不判 SKIP。"工程里没有这一类符号"和"逻辑没跑"必须区分,否则电池会悄悄缩水。
- 基线建树不可用 ⇒ 整条电池 FAIL。后面所有断言都以这棵树为前提。
- 断言里不写提前 return。提前返回就是假绿的藏身处。
- 连续两次失败即重写该条断言;收口数字必须在最终那次全量重建之后重跑。
还有一条与"断言有没有实体样本撑着"相关的实践:容器形态那组断言要求正反两条------有成员的容器要判 true,合法的空容器也要判 true 且能展不出成员而不报错。本家基线工程里恰有一例现成的:Application.默认变量表.gvl27 的类型 T_SYS_FILETIME 在导出的符号 XML 里没有成员表,声明是结构体、工程里展不出成员。有界扫样例得 243 节点 / 容器 30 / 合法空容器 1,这一格不是合成出来的,是真实工程给的。这也正是"IsContainer == true 只表明按声明是容器"这条口径的来由。
十一、与兄弟驱动的差异
同为 EtherNet/IP + CIP 语言,本家与欧姆龙/罗克韦尔是"同族不同味"(下表只列已逐项核过代码的事实):
| 维度 | 汇川 EVO | 欧姆龙 NJ/NX | 罗克韦尔 |
|---|---|---|---|
| 连接建立 | RegisterSession → ForwardOpen(先 0x5B 后回退 0x54) |
会话 + 符号注册 | RegisterSession → ForwardOpen |
| 符号访问 | 每请求现编 ANSI 扩展符号段 0x91(UTF-8,中文名合法) |
注册句柄(5/6/7 字节编码维度) | 现编 0x91 符号段 |
| 批量读打包 | 0x0A 打包 N 条 0x4C,段内无 0xAC(实测可用) |
打包报文构造器已备(BuildCIPMultipleServicePacket)但门面批量读仍逐点发 |
0x0A 打包:读路径含 0xAC 属性清单,打包写不含 |
| 分包依据 | 只按字节(390 / 1896),无条数上限 | 无驱动侧分包(是否补分包仍是待裁项) | 按连接尺寸(普通 490,Large 协商后 4002 - 100) |
| 数组树形态 | 元素平铺为数组节点的直接子节点,多维逗号下标,无中间维度节点(源码注明"与 Rockwell 口径一致") | 各自形态见其设计文档 | 同左 |
| 单点读 | 返回 PValue(Read(string),独有) |
bool 三件套 | bool 三件套 |
| 在线符号表 | 无该服务(LoadSymbolsFromPLC 直接抛) |
有 | 有 |
| 背板槽号 | 无此概念 | 无 | 有 |
AccessRight |
五值,独有 WriteOnly = 1 |
四项(None/Read/Write/ReadWrite) |
四项(无 WriteOnly) |
五家之间真正的统一发生在命名与形态 层(类名/枚举名/属性名以西门子为基准收敛、SymbolNode/DeviceInformation 统一、门面核四件返回 bool + 错误账三件套同形、Connect 形参序、重连骨架同形),而不是把各家协议强行抹平成一套字节。差异用"登记"的方式留着------Read(string) 返回 PValue、AccessRight.WriteOnly、西门子 int 地址面的 Record(int)、CODESYS 的批量写三件套,都在审计脚本里以"已知差异"通过,避免被"顺手统一"掉。源级形状审计 + 各家 CheckNamingSurface 断言把这条边界钉住:本家离线电池 57 项,全仓 native_shape_audit 同形审计 66 项(实测 61 通过 / 5 登记差异 / 0 失败)。
十二、结语
三点可复用的经验:
其一,异构文件最危险的表现不是"解析失败",而是"解析成功"。 EVO 与 CODESYS 符号导出根元素同名、元素名重叠,按元素名匹配的解析器会把一份外家工程物化成 1978 个节点并判成功,得到一张成员名全空、地址全废的表。判定必须落在真指纹(命名空间 / 特有子元素)上,而且要即读即拒------不要等解析完再验,百万级文件会白读一遍。
其二,设备能力要靠实测,不能靠规范表格。 类型码 0xD1--0xD4、ConnectionStatusDescriptor 非 0 会被直接断连、整块 FB 读写无响应、STRING 数组与带下标路径的 count > 1 回 0x15、WSTRING 不接受 capacity 前缀、Identity 回 Path segment error------这几条没有一条能从手册里读出来,全部是实机一轮一轮试出来的。相应地,能力边界要在代码里明写(LoadSymbolsFromPLC 直接抛并说明"无抓包证据"),而不是靠运行时静默降级。
其三,失败路径的状态清理与成功路径同等重要。 ForwardOpen 半途失败要尽力 UnRegisterSession,否则攒够孤儿会话就连不上;符号表载入失败不能碰旧树;整批读被拒要回退逐点定位坏点;重连每一轮自清残骸;迟到响应要按序号丢弃。现场最难查的问题,通常不是"功能不工作",而是"上一次失败的残留让这一次看起来时好时坏"。
当前状态:门面与批量读写、符号树、数组语义、错误账、重连、日志、契约适配均已实现,离线电池 57 项与在线品牌原生流程按上述矩阵维护。开放项两个:CIP 扩展状态码仍未解析(主状态码 + 标签名可用,厂商附加说明拿不到);与官方库的对拍通道在 console 改写为品牌原生形态时已撤下,需要复做得按履历重建。
附:关键文件索引
| 文件 | 行数量级 | 职责 |
|---|---|---|
InovanceEvoEipDriver.cs |
1962 | 门面:TCP/会话、ForwardOpen 与回退、心跳、重连、读写引擎、符号索引与懒合成、权限门、错误账 |
InovanceEvoSymbolXmlFile.cs |
381 | iFA 导出符号 XML 的流式解析、类型表、建树、方言闸门、类型表诊断计数 |
VarTreeStructures.cs |
97 | 运行时变量树节点与类型对象(ArrayDimension = 元素总数) |
EipStructures.cs |
621 | CIP 服务/路径/类型码、ForwardOpen 与连接系列、多服务打包 |
Encapsulation.cs |
516 | RegisterSession / UnRegisterSession / SendUnitData / SendRRData 报文构造与符号段编码 |
TcpClient.cs |
332 | 自研 Socket 封装:EtherNet/IP 分帧、请求串行化、超时与迟到响应丢弃、ConnectionLost |
PValue.cs |
1875 | 39 个 IEC 值类、公开工厂 Create、文本形态 ToStringWithType 与内部 FromString |
StructCodec.cs |
512 | 原子类型线上编解码、STRING/WSTRING 线格式、结构体后备解包 |
DeviceInfo.cs |
171 | DeviceInformation 与离线工程信息(ProjectInfo 回填) |
SymbolNode.cs |
45 | 统一门面节点类型(五家同名同形,IsContainer 在门面侧) |
DriverLogGate.cs |
137 | 逐实例日志闸:级别门与宿主 IsEnabled 取交集、ParseLevel |
SymbolFileCheck.cs |
45 | 路径级坏输入校验(各家各持一份同形原生副本) |
SerialNumberGenerator.cs |
49 | ForwardOpen 连接序号的洗牌唯一发放 |
CIPException.cs |
39 | 携带 CIP 状态码的异常,LastErrorCode 的直接来源 |
更新履历.txt |
873 | 中文变更史:逐条含问题、根因、实测数字与验证矩阵 |
DriverContracts/Adapters/InovanceEvoEipDriverAdapter.cs |
--- | 契约显式实现,只做转调与类型映射 |
测试 demo 获取:TestInovanceEvoEipDriver.Console(check = 57 项离线电池;不带参数 = 连设备的品牌原生流程)与 TestInovanceEvoEipDriver.GUI(WinForm 树形浏览 + 读写 + 冒烟),均随本仓库一同维护。