ZL.IotOss 2.2.18

ZL.IotOss

Oss = Open Source Software。本包只做“薄适配”：协议栈全部来自成熟开源库， 不自研 TCP/帧解析，不引入商业/收费库。

ZL.IotOss 是 ZL.IotEngine 的开源驱动插件包，当前提供四类协议：

范围说明（2026-11-05 证据评审，docs/573）：本包不含三菱 MC。 libplctag 不支持 MC 协议（随包原生库 mitsubishi 0 命中；官方仓库仅 AB/Omron/Modbus TCP）， 其余开源候选均不满足生产标准——按“宁缺毋滥”原则移出本包范围。

Omron 边界：omron-njnx-oss 只覆盖 NJ/NX 的 CIP/EtherNet/IP（libplctag PlcType.Omron）， 不是 FINS；CJ/CP/CS 等 FINS/HostLink 机型仍用自研 omron-fins-tcp / omron-host-link。

详细评审：依赖精简、协议键/型号组织、58 个自研描述符的对比分析，见 docs/585_ZL.IotOss依赖精简与协议描述符组织评审_20261105.md。

1. 先搞清楚三个包的关系

ZL.IotEngine   核心运行时：契约、编排、地址合并、批量采集、OPC UA（可选）
     ▲
     │ ProjectReference / PackageReference
     ├── ZL.IotDriver   58 个自研协议描述符（不依赖任何第三方通讯库）
     └── ZL.IotOss      7 个开源协议描述符（S7.Net Plus / NModbus / LibPlcTag）

ZL.IotOss 不引用 ZL.IotDriver；反过来 ZL.IotDriver 也不引用 ZL.IotOss。 两个插件包都只依赖 ZL.IotEngine，宿主把对应 dll 放到输出目录即可被自动发现。

2. 安装与插件发现

2.1 引用

<ItemGroup>
  <PackageReference Include="ZL.IotEngine" Version="3.1.0" />
  <PackageReference Include="ZL.IotOss" Version="3.1.0" />
</ItemGroup>

仓库内开发用 <ProjectReference> 指向 ZL.IotEngine/ZL.IotEngine.csproj 与 ZL.IotOss/ZL.IotOss.csproj；不要为了用开源协议去引用 ZL.IotDriver。

2.2 插件发现

引擎启动时 ProtocolPluginLoader.TryLoadAuto() 会：

1. 扫描宿主目录下的 ZL.Iot*.dll（排除 ZL.IotEngine.dll、ZL.License.dll）；
2. 反射创建 IProtocolPlugin 实例；
3. 调用 GetDescriptors() 注册到 NativeProtocolRegistry；
4. 校验 ApiVersion == 1。

因此只要 ZL.IotOss.dll 在应用输出目录，NativeProtocolRegistry.All 里就会出现 7 个 -oss 协议键。也可以放 protocol-plugins.json 清单显式指定，但常规部署不需要。

2.3 初始化（AB / Omron NJ/NX 必需）

using ZL.IotOss;

// AB / Omron NJ/NX（libplctag）首次读写前必须调用；S7 / Modbus 不需要。
// 幂等；返回 false = 原生库没有部署成功（AB/Omron 会报 DllNotFoundException，S7/Modbus 不受影响）。
bool ready = OssBootstrap.EnsureReady();

libplctag.NativeImport 把各平台原生库作为内嵌资源分发，但不会在 P/Invoke 时自动解包。 EnsureReady() 按进程架构把当前平台的原生库写到 AppContext.BaseDirectory。

⚠️ macOS x64 已知问题：libplctag.NativeImport 1.0.41 的 osx_x64 内嵌资源实测也是 arm64（上游包错标）。在 Apple Silicon 上用 x64 .NET（Rosetta）跑 AB 时，EnsureReady() 会检测到架构不匹配并返回 false；请改用 arm64 .NET，或把正确架构的 libplctag.dylib 预置到应用目录（EnsureReady() 会保留架构正确的已有文件）。Linux x64 / Windows x64 不受此影响。

3. 两种用法：裸设备 vs 引擎托管

3.1 裸 IPlcDevice（按地址直读，适合脚本/诊断/小工具）

using ZL.IotEngine.Abstractions;
using ZL.IotEngine.Native;
using ZL.Tag;

var cfg = new DeviceConfig();
cfg.Add("Protocol", "s7-1200-plus-oss");
cfg.Add("DeviceIp", "192.168.1.100");
cfg.Add("Port", 102);
cfg.Add("DeviceType", "S7-1200");   // 可选；不写默认 S7-1200
cfg.Add("TimeoutMs", 3000);         // 可选；默认 3000

var descriptor = NativeProtocolRegistry.ResolveByKey("s7-1200-plus-oss")
    ?? throw new InvalidOperationException("协议未注册：ZL.IotOss.dll 是否在输出目录？");

var device = (IPlcDevice)descriptor.ClientFactory(cfg);
try
{
    var conn = device.ConnectServer();
    if (!conn.IsSuccess) throw new InvalidOperationException(conn.Message);

    var write = await device.WriteAsync("DB1.DBW2", (short)123);
    if (!write.IsSuccess) throw new InvalidOperationException(write.Message);

    var read = await device.ReadInt16Async("DB1.DBW2");
    Console.WriteLine(read.IsSuccess ? read.Content : read.Message);
}
finally
{
    device.ConnectClose();
    if (device is IDisposable d) d.Dispose();   // AB 适配器实现了 IDisposable
}

这条路径不经过引擎的标签表/批量合并，地址原样交给适配器；适合验证点位、排查现场问题。 tests/ZL.IotOss.Tests/SimulatorE2ETests.cs 走的就是同一条路径。

3.2 DriverFactory + 标签表（生产采集推荐）

using ZL.IotEngine.Orchestration;
using ZL.Tag;

var cfg = new DeviceConfig();
cfg.Add("Protocol", "s7-1200-plus-oss");
cfg.Add("DeviceIp", "192.168.1.100");
cfg.Add("Port", 102);
cfg.Add("DeviceId", "PLC1");

using var driver = DriverFactory.Create(cfg);

// 🔴 先登记点位，再按【标签 Id】读写；Read<T>("DB1.DBW2") 是错误用法。
driver.Tags["Temperature"] = new TagItem
{
    Id = "Temperature",
    Address = "DB1.DBW2",
    DataTypeCode = "int16",
    Enable = true,
};

driver.Connect();
var value = driver.Read<int>("Temperature");   // 走引擎批量/实时路径

DeviceBase.Read<T>(string id) 的参数是标签 Id，不是 PLC 地址。查不到时它返回 default(T)（例如 0），不会抛异常——这是现场“永远读到 0”的最常见原因。

类型码必须按位宽选（PlcDataTypeMap.Normalize 的别名表）：

🔴 uint 是 32 位无符号，不是 16 位；要 16 位无符号必须写 ushort / uint16。 把 uint 当 uint16 用会读 4 字节，轻则值不对，重则覆盖相邻点位。

4. 协议配置与地址写法

4.1 通用键

4.2 西门子 S7

协议键与型号（键是“协议族”，不是“型号清单”）：

适配器还识别 S7-200、S7-200Smart 两个 CpuType（默认 Slot=1），但：

• 当前没有为它们注册独立协议键，也没有仿真器 E2E；
• 经典 S7-200 本体只有 PPI/MPI，没有以太网；要走上层 S7comm 必须加 CP243-1 或经网关； 纯 PPI 现场请用 ZL.IotDriver 的 siemens-ppi（本包不处理 PPI）；
• S7-200Smart 有以太网，适配器支持 CpuType.S7200Smart，但属“可用但未验证”组合， 发布文档不把它写成已承诺支持。

配置示例：

cfg.Add("Protocol", "s7-1200-plus-oss");
cfg.Add("DeviceType", "S7-1500");   // 或 S7-1200 / S7-300 / S7-400
// cfg.Add("CpuType", "S71500");    // 可选；显式 CpuType 优先于 DeviceType
// cfg.Add("Rack", 0);              // 可选；不写用型号默认值
// cfg.Add("Slot", 2);              // 可选；S7-1500 部分 CPU 需要 3

地址写法（Siemens 画像）：

德语助记符 E0.0 / A4.0：直调适配器时会映射到 I/Q；但点表建块阶段按 Siemens 画像解析，E/A 会被响亮排除（有告警，不会静默错读）。新点表请直接写 I/Q。

4.3 Modbus TCP / RTU / ASCII

地址写法：

纯数字地址按标准 Modbus 5 位约定解析；50000+、越界地址会被拒绝。 ReadBytes 的 length 恒为字节，适配器内部按 (length+1)/2 换算寄存器数。

4.4 Allen-Bradley EtherNet/IP

地址写法：地址就是 Logix Tag 名，原样交给 libplctag：

AB 走 UCMM（UseConnectedMessaging=false），不自研 Class-3 / 0x0070 / Forward Close。 仿真器回环只能证明“与仿真器一致”，不等于真机验证；生产前必须用真实 PLC 复验。

4.5 Omron NJ/NX CIP/EtherNet/IP

协议边界：本适配器走 CIP/EtherNet/IP，与 AB 共用 libplctag 的 protocol=ab-eip， 仅 PlcType/默认路径不同；不是 FINS。只适用于 NJ/NX（含 NX1P2）等支持 CIP 变量访问的机型； CJ/CP/CS 等 FINS/HostLink 机型请用自研 omron-fins-tcp / omron-host-link。

地址写法：地址 = Sysmac Studio 中的变量名，原样交给 libplctag：

已验证边界：离线契约测试覆盖构造/别名/描述符；真实读写用 libplctag 官方 ab_server --plc=Omron 模拟器验证（Path=18,127.0.0.1，QuickStart 10/10）。 模拟器通过 ≠ NJ/NX 真机通过：真机还需确认变量访问权限、CIP 路由、防火墙和固件差异。

5. 协议键、别名与共存

别名避让规则：本包不占用自研驱动已注册的裸名（modbus-tcp、modbus、modbus-rtu、 ab、allen-bradley、s7 等）。NativeProtocolRegistry 对重复别名是“后到者静默覆盖”， 共存时请使用带 -oss 的键；不要新增裸名别名。

与 ZL.IotHub.X（HSL）共存：两者都依赖 ZL.IotEngine，但 HSL 走自己的 HslProtocolRegistry，协议键体系不同；同一宿主可以同时引用。不要同时引用冻结的 ZL.IotHub 与 ZL.IotEngine（CS0433）。

6. 新增协议 / 新增型号

6.1 同协议族新增型号（只改配置）

S7 的 1200/1500、300/400 已经证明：同一协议族的不同型号不应新增协议键。 做法是把型号元数据集中到 *ProtocolDescriptor 静态类（CPU 类型、默认 Rack/Slot、地址方言）， 适配器按 DeviceType / CpuType 选择；插件只为“协议族/传输方式”注册描述符。

6.2 全新协议（新增 Plugin + Adapter）

public sealed class MyProtocolDeviceAdapter : IPlcDevice { /* 薄适配 */ }

public sealed class MyProtocolPlugin : IProtocolPlugin
{
    public int ApiVersion => 1;
    public string Id => "my-protocol-oss";
    public IEnumerable<NativeProtocolDescriptor> GetDescriptors()
    {
        yield return new NativeProtocolDescriptor(
            "my-protocol-oss",
            "My Protocol (LibXxx)",
            new[] { "my-protocol-oss" },       // 别名必须避开自研驱动的裸名
            cfg => new MyProtocolDeviceAdapter(cfg),
            addressProfile: PlcAddressProfile.Any);
    }
}

编译成 ZL.Iot*.dll 放到宿主目录即可自动发现；不需要改引擎。不要为每个设备型号 复制一个 Plugin/Descriptor。

7. 故障排查

8. 测试与验证边界

# 单元/契约测试（离线；不需要 PLC/仿真器）
dotnet test tests/ZL.IotOss.Tests/ZL.IotOss.Tests.csproj

# 仿真器回环（Manual；需要本机 plcsim）
plcsim --protocols siemens-s7,modbus-tcp,ab \
       --ports siemens-s7=31002,modbus-tcp=31502,ab=32004 \
       --headless --stay-alive --auto-start
dotnet test tests/ZL.IotOss.Tests/ZL.IotOss.Tests.csproj \
  --filter "FullyQualifiedName~SimulatorE2ETests"

# Omron NJ/NX：plcsim 当前没有 Omron CIP 端点，用 libplctag 官方 ab_server 模拟器
ab_server --plc=Omron --port=32005 \
  --tag=TestDINT:DINT[10] --tag=TestINT:INT[10] \
  --tag=TestREAL:REAL[10] --tag=TestBOOL:BOOL[10] --tag=TestBYTES:SINT[10]
dotnet run --project demos/ZL.IotOss.Demo.QuickStart -- \
  --protocol omron-njnx-oss --port 32005 --path 18,127.0.0.1

• S7 / Modbus：仿真器回环已通过。
• AB：用例存在，但本机 plcsim 2.2.10 build_commit e3c244f 早于 AB 修复 e5ff34d5， 复跑仍报 0x0A BAD_STATUS；且 macOS x64 需匹配架构的 libplctag。
• Omron NJ/NX：已用 libplctag 官方 ab_server --plc=Omron 模拟器完成 int32/uint16/bool/float/byte[4] × 裸驱动/引擎双路径 10/10 回环；尚无 NJ/NX 真机验证。 必须用 e5ff34d5+ 仿真器 + 匹配原生库复验，仿真器通过也不等于真机通过。
• 没有真实 PLC：所有“已实现”只代表“与仿真器/协议栈一致”，不代表现场时序、 防火墙、PLC 型号差异都已验证。发布说明必须保留这条边界。

9. 依赖与精简建议

当前直接依赖：

ZL.IotEngine
  ├─ NLog
  ├─ Newtonsoft.Json
  ├─ System.Threading.Channels
  ├─ System.Threading.Tasks.Extensions
  ├─ Microsoft.CSharp
  ├─ System.Memory
  ├─ System.Buffers
  ├─ System.Text.Encoding.CodePages（非 net48）
  └─ OPCFoundation.NetStandard.Opc.Ua.Server（仅 net8/net10）

ZL.IotOss
  ├─ ZL.IotEngine
  ├─ S7netplus 0.20.0
  ├─ NModbus 3.0.83
  ├─ System.IO.Ports 9.0.4（仅 net8/net10；RTU/ASCII 直接使用）
  └─ libplctag 1.5.2 → libplctag.NativeImport 1.0.41

已经做的精简：ZL.IotEngine 删除未使用的 System.IO.Ports；ZL.IotOss 改为直接声明 System.IO.Ports（此前靠 Engine 传递，属隐式耦合），且只在 net8/net10 声明—— netstandard2.0 的串口代码被 #if 排除，不需要该包。

建议但未在本版实施（需单独评审/排期）：

1. 把 OPC UA Server 从 ZL.IotEngine 拆成 ZL.IotEngine.OpcUa 包：当前 net8 发布输出约 18 MB，其中 Opc.Ua.* 约 9.4 MB；只用 S7/Modbus 的宿主被迫携带。
2. 把 ZL.IotOss 按底层库拆成 ZL.IotOss.S7Plus / .NModbus / .AllenBradley： 当前一个包同时拖入 S7.Net Plus、NModbus、libplctag（含 3.1 MB 的 NativeImport）， 只用 Modbus 的宿主也会拿到 AB 原生库。
3. 对 System.Memory / System.Buffers / System.Threading.Channels / System.Threading.Tasks.Extensions 做 TFM 条件化：net8/net10 已内置，netstandard2.0/net48 仍需要；需全 TFM 构建验证后再动。

10. 许可证

本包采用 LICENSE 声明，并再分发以下开源库：

• S7.Net Plus：MIT
• NModbus 3.x：MIT
• LibPlcTag（.NET wrapper）：MPL-2.0；C 核心库：MPL-2.0 或 LGPL-2+ 双许可 （2026-11-05 核实官方仓库 LICENSE；按 MPL-2.0 之选声明，无传染性顾虑）