简介：secs4net-master 是一套基于 .NET 的 SECS/GEM 协议通信源码工程，面向半导体设备自动化领域开发者，可用于设备与上位机之间的报文交互测试与协议联调。包内共 320 个文件，以 191 个 C# 源码文件为核心，辅以项目工程文件、配置文件及界面资源，覆盖从网络传输、报文编解码到业务处理的主要层次；压缩包仅 405KB，结构紧凑，便于快速下载与本地编译调试。已有 566 人学习/下载，适合具备一定 C# 基础、希望深入 SECS/GEM 实现原理的工程师参考。通过阅读源码可掌握消息格式定义、解析与构建逻辑、错误处理机制及常见部署脚本（如 DevDeploy.bat），同时项目包含 Dockerfile 与多环境配置，便于在不同开发环境中验证通信流程，是学习半导体设备自动化通信与二次开发的实用参考资料。
1. secs4net 是什么：一份“好几年没更新”的协议栈，为什么还在生产线上跑
拿到 secs4net-master.zip 的人，第一反应通常是打开仓库看一眼提交记录，然后嘀咕：上次发布已经是好几年前了，这还敢往生产线里放吗？我的看法正好相反——在 SECS/GEM 这个被半导体行业焊死的通信协议上，老不是缺点，稳才是。secs4net 是 .NET 平台下实现 SECS-I/HSMS 消息通信的开源库，它把设备端与上位机之间的二进制报文封装成可调试的 C# API，解决的是产线上最实在的问题：让 MES/EAP 能收到机台事件报告，能把配方下发到机台里，能随时对一台设备发起状态查询。适合正要接设备、掏不起商用协议栈授权费，又不想从零写报文编解码的工程师。
2. 拆开 secs4net-master.zip：目录结构、编译验证与三个选型理由
2.1 zip 里的“master”不是 Git 分支，是仓库快照
很多第一次接触的人会把 secs4net-master 当成某个叫 master 的版本，甚至有人在群里问“master has no tracked branch 是怎么回事”。这里的 master 只是代码托管平台在导出 zip 时自动加的顶层目录名，本质是把整个仓库源码打了一个快照。解压之后你会看到一个典型的 .NET 工程布局：一个 .sln 解决方案文件，src 目录下是核心协议库项目，sample 目录下是示例程序和模拟设备。这个结构决定了一件事：它不是一个开箱即用的 NuGet 包形态，而是一个需要你自己编译、引用源码或打包成 DLL 的工程。
我一般下载之后不会直接双击 .sln 就开干，而是先做一次静态盘点。打开 README 看支持的协议版本，打开核心项目的 csproj 看 TargetFramework 是 .NET Framework 4.x 还是 .NET Core/.NET 5+。不同年头的版本差别很大，老版本默认锁定 .NET Framework 4.6.1，新版本才放开到跨平台。这个信息决定了最终部署到 Windows 服务还是 Linux 容器里。
盘点完之后你还会发现一个隐藏成本：它不是一个“装完 NuGet 包就能跑”的库，而是带了一整套协议栈实现，包括消息编解码、会话状态机、心跳线程。这意味着你引入的不只是一堆 API，而是一个有一定体积的通信内核。这个体积在产线环境里不是坏事，反而意味着协议细节被处理过了。
2.2 编译验证：让 zip 先变成能跑的项目
别急着写业务代码，先把工程编译通过。这是对 zip 包健康状况的第一轮体检，也能提前暴露依赖缺失和框架版本问题。用命令行编译比在 Visual Studio 里点按钮更可控，尤其是后面要放到 CI 或 Linux 环境时。
unzip secs4net-master.zip cd secs4net-master dotnet build src/Secs4Net/Secs4Net.csproj -c Release如果报找不到依赖包，先执行dotnet restore再重新 build；老版本工程如果用了 packages.config 而不是 PackageReference，则需要用nuget restore还原后才继续。编译输出的 DLL 在 bin/Release 目录下，这个 DLL 就是协议栈本体，后续业务项目直接引用它。
这里有一个值得注意的边界：不要因为机器上装了最新 .NET SDK 就把 TargetFramework 顺手改成 net8.0。SECS/GEM 协议栈里大量用到 socket 超时、定时器、二进制缓冲区处理，这些逻辑在不同运行时版本上行为基本一致，但泛型 API 和异步模型如果被“顺手升级”到新写法，很容易引入回归。我的习惯是保持它的原始目标框架，单独建一个 .NET 8 的宿主项目引用这个老 DLL，两边互不干扰。
2.3 为什么不用商用协议栈，偏偏选一个“老”开源库
这个问题的答案在选型表里最直观。我们接触到的方案无非三类：商用协议栈全家桶、secs4net 这类开源实现、完全自研。我基于做过多次设备接入的经验，按六个维度做了对比。
| 维度 | 商用协议栈（如 Cimetrix 系） | secs4net | 完全自研 |
|---|---|---|---|
| 初始成本 | 高（授权费/年费） | 低（源码可改） | 极高（人手月） |
| 协议覆盖完备度 | 高 | 高（SECS-I/HSMS/SECS-II） | 取决于测试量 |
| 可调试性 | 黑匣子，只有日志 | 可跟到字节级编解码 | 自己写的可控 |
| 产线保守程度 | 最稳但最贵 | 稳定，社区多年验证 | 风险最高 |
| 维护风险 | 厂商兜底 | 靠自己和社区 | 靠自己 |
| 对工程师要求 | 低 | 中 | 最高 |
选 secs4net 的核心逻辑是：半导体设备协议二十多年没大改过，新版本库并没有带来革命性功能，真正的风险从来不在协议栈本身，而在接入现场的千奇百怪设备行为。开源库的好处是遇到厂商设备实现不标准时，可以直接在源码里加日志、加兼容分支，这在商用库里做不到，那些库报一个“消息格式错误”就把你打发了，你还不知道错在哪。
3. 跑通第一条 HSMS 通信链路：最小可执行 C# 程序
3.1 连接模型与 SecsGemOption 里的关键参数
HSMS 本质上是一条 TCP 连接上的消息通道，设备是 Server 还是 Client、上位机是主动连接还是被动监听，决定了整个接入方案的第一层拓扑。secs4net 把这个模型收敛成一个SecsGemOption配置类和SecsGem通信对象，先把参数弄懂，后面调试才不至于全程靠玄学。
| 参数 | 默认值 | 作用 | 现场调参要点 |
|---|---|---|---|
| DeviceId | 0 | 设备会话标识 | 设备端配置不一致直接握手失败 |
| IpAddress | 无 | 对端 IP 或监听地址 | 主动模式填设备 IP，被动模式填 0.0.0.0 |
| Port | 5000 | TCP 端口 | 现场常被防火墙拦，需双向放行 |
| IsActiveMode | true | true=主动连接，false=被动监听 | 必须和设备端约定一致 |
| LinkTestInterval | 20s | 心跳间隔 | 网络抖动大时调短到 10s |
| SocketBufferSize | 默认 | 收发缓冲区 | 大批量配方下发时调大 |
| T3 超时 | 45s | 等待回复的超时 | 设备慢时调大到 60s，但不是越大越好 |
这些参数里最容易踩的是 DeviceId。很多设备面板上显示的是十进制，协议报文里传输的却是右移 7 位的编码值，secs4net 在SecsGemOption层直接收 DeviceId 原始值并做编码处理，但前提是你填的值要跟设备端配置完全一致。错一位，设备就会在握手阶段给你回一个 S9F9。
3.2 最小示例：主动连接模式向模拟器发起建链
最常见的调试场景是 Host（上位机）主动连模拟器或真机。下面这个程序是完整的可运行骨架，能验证网络是否通、协议栈是否转得起来、消息处理回调是否正常触发。
using Secs4Net; var option = new SecsGemOption { DeviceId = 0, IpAddress = "192.168.1.100", // 模拟器或真机设备 IP Port = 5000, IsActiveMode = true, // 上位机主动连设备 LinkTestInterval = TimeSpan.FromSeconds(20) }; using var gem = new SecsGem(option); gem.ConnectionChanged += (_, e) => { Console.WriteLine($"[{DateTime.Now:HH:mm:ss}] 连接状态: {e.IsConnected}"); }; gem.MessageReceived += async (_, e) => { var primary = e.PrimaryMessage; Console.WriteLine($"收到消息 S{primary.S}F{primary.F}: {primary}"); if (primary.S == 1 && primary.F == 1) { var reply = new SecsMessage(1, 2); await gem.SendAsync(reply); } }; await gem.OpenAsync(); Console.WriteLine("设备服务已启动，按 Ctrl+C 退出。"); await Task.Delay(-1);逻辑说明：OpenAsync会创建 TCP 连接并启动心跳线程；ConnectionChanged在连接建立和断开时各触发一次，是判断链路状态的第一道关口；MessageReceived拿到的是已经解码完成的PrimaryMessage，S和F是消息流号与功能号，S1F1 是设备的 Echo 请求，回复 S1F2 是握手基本礼貌。
参数说明：IpAddress在主动模式下填设备侧地址，如果设备不在同一网段，先查路由；LinkTestInterval越短越能早发现半开连接，但也会增加设备侧日志量，产线上通常 20s 是一个平衡点。注意SendAsync是有超时的，如果设备一直不回复，它会抛TimeoutException，最小示例里没包 try-catch，实际项目里必须包住。
3.3 被动模式：让设备来找你，适合多设备对一服务器
另一类场景是产线里多台设备反向连到上位机，上位机只开一个端口监听。此时把IsActiveMode设为 false，IpAddress设为0.0.0.0，secs4net 就会成为一个 TCP 监听端。
var option = new SecsGemOption { DeviceId = 0, IpAddress = "0.0.0.0", Port = 5000, IsActiveMode = false, LinkTestInterval = TimeSpan.FromSeconds(20) };被动模式的隐藏问题是：多台设备连上来之后，MessageReceived里拿到的消息如何区分是哪台设备的。secs4net 对 DeviceId 做了区分，但前提是每台设备的 DeviceId 不同，且你的业务代码在处理消息时必须按 DeviceId 做路由。最小示例里只有一个SecsGem实例，如果现场有 8 台设备，正确做法是每台设备一个SecsGemOption、一个SecsGem实例、一个独立日志文件，而不是把所有连接混在一个回调里靠猜来定位。另一个细节是 Windows 防火墙默认会拦截监听端口的入站连接，被动模式部署后十有八九连不上，先把防火墙入站规则放行。
4. 从 Echo 到生产消息：S1F1/F0、S6F11 事件上报与 S7F1 配方下发的完整链路
4.1 SecsMessage 与 SecsItem：读懂设备消息的骨架
SECS-II 消息的正文是一棵SecsItem树，没有扁平字段，没有 JSON，这对第一次接触的人是个坎。secs4net 把这棵树暴露成SecsMessage.Items属性，你拿到的是一个可遍历的 item 集合，每个 item 有自己的类型和数值。常见的类型就那么几个：List（列表）、ASCII（字符串）、U4/U8（无符号整数）、A（定长字符串）、Boolean。设备端传来的 S6F11 事件报告，本质上就是这些类型嵌套组合出来的一个结构。
理解这棵树的价值在于：排错时你打开抓包工具看到的是一段十六进制字节流，而你能在断点里看到的是解析好的 item 树。想快速验证消息内容，直接打印primary.ToString()，secs4net 的格式化输出会把整棵树按缩进排好，这比对着报文看半天舒服太多。我通常在MessageReceived的第一行就打印这个 ToString，作为所有调试的起点。
4.2 建链消息：S1F13/F14 的完整应答逻辑
S1F1/F2 只是最基础的在线心跳，真正让设备进入可通信状态的是 S1F13（Establish Communications Request）和 S1F14（Establish Communications Response）。设备发来 S1F13，上位机必须回 S1F14，并且里面要带上 MDLN（设备型号名）和 SOFTREV（软件版本），否则部分厂商设备会认为握手失败，主动断开连接。
if (primary.S == 1 && primary.F == 13) { var mdln = SecsItem.ASCII("SECS4NET-DEMO"); var softrev = SecsItem.ASCII("1.0"); var reply = new SecsMessage(1, 14, "S1F14 String", SecsItem.List(mdln, softrev)); await gem.SendAsync(reply); }逻辑说明：这里用SecsItem.List把两个 ASCII item 包成一个树根，S1F14 的标准结构就是 L0 下带两个 A 类型 item。第三个参数是给消息起个可读名字，调试日志里会显示成S1F14 String，方便人工识别。SendAsync的第二参数可以传TimeSpan超时，设备如果迟迟不回 S1F2 或 S1F14，就用它控制等待上限。
参数说明：MDLN和SOFTREV内容不能乱填，厂商设备会校验这两个值和约定是否一致，尤其是某些日系设备，对 MDLN 长度都有严格限制，建议不超过 20 个 ASCII 字符。在接入新设备前，先向设备厂商要一份 SECS 通信手册，里面通常列明了它支持的 S1F13 应答格式。
4.3 S6F11 事件报告解析：从 CEID 到数据变量
S6F11 是产线上最常见的消息类型，设备每完成一个动作、每发生一次报警，都会通过它上报事件。它的结构可以理解为：第一层是 DATAID（数据块 ID），第二层是 CEID（事件 ID），第三层是一个或多个 RPTID（报表 ID），每个报表下面再挂真正的数据变量列表。解析时要注意下标不要取错，一旦把报表里第一个变量当成 CEID，后续所有逻辑全部走偏。
if (primary.S == 6 && primary.F == 11) { var items = primary.Items; if (items == null || items.Count < 3) { Console.WriteLine("S6F11 结构异常"); return; } var ceid = items[1].Value; Console.WriteLine($"事件 CEID: {ceid}"); foreach (var report in items[2].Items) { var rptId = report.Items[0].Value; Console.WriteLine($"报表 RPTID: {rptId}"); foreach (var variable in report.Items[1].Items) { Console.WriteLine($" 数据项: {variable}"); } } await gem.SendAsync(new SecsMessage(6, 12)); }逻辑说明：items[0]是 DATAID，通常直接忽略；items[1]是 CEID，它决定了这条事件是什么类型；items[2]是报表集合，每个报表里Items[0]是 RPTID，Items[1]才是变量列表。很多新手把 CEID 当成字符串去匹配，但它实际上是数值类型，务必先看设备手册确认是 U4 还是 U8。
参数说明：最后回复的 S6F12 是空消息，不带 items，它只是告诉设备“我收到了”。这个回复必须在 T3 超时内返回，否则设备会认为事件上报超时，重发或直接报错。现场接入时曾有设备对回复时间极敏感，处理逻辑里如果做了数据库写入或 HTTP 调用，建议先回 S6F12，再异步处理业务数据。
4.4 F0 与 S9F9 异常消息：设备说“我不认识你”时怎么办
F0 是“无法识别消息”的通用流，S9F9 是设备明确告诉你“刚才那发消息我不能解析”。遇到 S9F9，首要动作不是改业务代码，而是把你自己发出去的消息原始字节打出来，和 SEMI E5/E37 标准逐字节对照。常见原因是 item 类型用错，比如设备要求 U2，你发的是 U4；或者 List 层级不对，少包了一层或多包了一层。secs4net 的构造函数本身不拦截这类逻辑错误，它只负责把你拼出来的 item 树编码成字节流，所以 S9F9 本质上是设备端替你做了校验。
if (primary.S == 9) { Console.WriteLine($"设备上报错误: S{primary.S}F{primary.F}"); if (primary.Items != null && primary.Items.Count > 0) { Console.WriteLine($"错误详情: {primary.Items[0]}"); } }处理 S9F9 的正确姿势是先确认是哪条消息被拒，然后回放该消息的编码结果。secs4net 层面能做的只有日志和计数，真正的根因排查要靠报文比对。如果一时查不出原因，把收到的 S9F9 和本地记录的最近一条发送消息发给设备厂商的 AE，问清楚“你们期望的格式是什么”，这比闷头试快得多。
5. 避坑实录：5 个把工程师耗到深夜的 secs4net 问题
5.1 连接反复断开又自动重连，心跳却没报错
现象：日志里ConnectionChanged频繁触发，连接状态在 True 和 False 之间反复横跳，但从来不抛异常。
原因：现场网络中有交换机启用了 TCP 空闲连接回收策略，secs4net 的LinkTestInterval默认 20s，但设备侧或交换机可能在更短时间判定空闲。另一个常见因素是操作系统的 TCP KeepAlive 默认 2 小时，与协议层心跳锅盖不到一块。
解决：把LinkTestInterval从 20s 调到 10s，同时把设备侧的 T6（连接测试超时）也同步调小，确保双方对“什么算掉线”达成一致。如果调完还断，检查上位机和服务器的电源管理，笔记本场景下系统休眠会把 socket 直接掐断。
5.2 设备端持续回 S9F9，但本地模拟器一切正常
现象：本地用模拟器联调完全正常，接到真机上设备开始不停上报 S9F9，通信基本瘫痪。
原因：真机和模拟器对消息格式的容忍度不同。最常见是位宽问题：设备端变量定义为 U2，secs4net 默认按 U4 编码，模拟器不做严格校验所以没暴露。其次是消息回复顺序问题，设备连续发了两条 S6F11，你只回了一条 S6F12，设备就把第二条当成异常消息。
解决：把 secs4net 源码里对应消息的构造代码打上断点，逐条检查每个SecsItem的创建类型和长度；同时用 WireShark 抓包，对照 S9F9 产生的时刻，反查哪条请求没被正确应答。这类问题 90% 靠抓包定位，靠猜的翻车率极高。
5.3 MessageReceived 事件回调里一 await 就进程崩溃
现象：在事件 handler 里调用了await gem.SendAsync()，某次设备突然断开，进程直接挂掉，没有任何 catch 日志。
原因：事件处理器是async void，异常发生时会直接抛到线程池顶层，你包在方法内部的 try-catch 根本拦不住。secs4net 的SendAsync在连接断开时会抛异常，这个异常就顺着 async void 冲出去了。
解决：把整个事件处理逻辑包进 try-catch，绝不让异常逃逸出事件回调；更稳妥的做法见 6.2，所有收到消息先投递到队列，再由一个独立的消费线程统一处理，彻底绕开事件回调的异常陷阱。
5.4 现场设备连不上，模拟器环境却 10 秒建链完成
现象：拿着笔记本到产线，网线插好、IP 改对，模拟器上能连，真机就是连不上。
原因：设备侧设置为被动模式（等待 Host 主动连接），但你的代码也是被动模式，两边都在等对方先说话。另一种可能是设备端配置的 Host IP 和你笔记本的当前 IP 不一致，设备只接受白名单 IP 的主动连接。
解决：先在设备操作界面确认连接模式是 Active 还是 Passive，再确认设备固件里记录的 Host IP 是哪一位。调试阶段可以把两种模式都写成配置项，用命令行参数切换，避免反复改代码重编译。这类问题不是协议栈的锅，是现场信息收集不到位。
5.5 多设备共用一台服务器，消息串台
现象：两个设备同时接入，A 设备的事件上报被当成 B 设备的处理，工艺参数下发到了错误的机台。
原因：被动模式下，多个设备连接的逻辑链路都在同一个SecsGem实例里，如果业务只按消息内容处理、不按 DeviceId 区分，串台是必然的。更隐蔽的原因是两台设备配置了相同的 DeviceId。
解决：按章节 3.3 的处理原则，每台设备一个独立SecsGemOption和独立SecsGem实例，业务层每个实例对应一个设备上下文。接入前先扫描现场所有设备的 DeviceId，确保全局唯一。这个血泪经验直接催生了 6.1 的封装结构。
6. 进阶：把 secs4net 封装成稳定的设备服务层
6.1 连接管理器：让每台设备都有独立生命周期
public class EquipmentConnection : IDisposable { private readonly SecsGem _gem; private readonly string _equipmentId; public EquipmentConnection(string equipmentId, SecsGemOption option) { _equipmentId = equipmentId; _gem = new SecsGem(option); } public Task OpenAsync() => _gem.OpenAsync(); public void Dispose() => _gem.Dispose(); }每个设备一个实例的封装，是产线项目不翻车的基本前提。后续部署时，每个实例可以注册成独立 Windows 服务，用 sc.exe 或 NSSM 把这套封装打包成本地服务，再做上下电自启，缺点是服务数量跟着设备数量走，运维要习惯按设备查日志。
6.2 消息队列化：把事件回调变成可追溯的工作流
private readonly Channel<SecsMessage> _messageQueue = Channel.CreateUnbounded<SecsMessage>(); gem.MessageReceived += (_, e) => { _messageQueue.Writer.TryWrite(e.PrimaryMessage); }; async Task ProcessLoopAsync() { await foreach (var msg in _messageQueue.Reader.ReadAllAsync()) { try { await HandleMessageAsync(msg); } catch (Exception ex) { Console.WriteLine($"处理消息 S{msg.S}F{msg.F} 失败: {ex}"); } } }消费循环里处理的异常被完整捕获，消息处理失败不影响接收线程，同一连接可以继续收下一条消息。这个结构也方便动态调整消费多线程数量，瓶颈可控，不玄学。
6.3 消息回放验证：把联调记录变成回归用例
接入新设备时我会录一段完整报文交互过程，把 secs4net 解码前的原始字节存成文件。现场出问题时直接拿文件在本地重放，不需要等产线窗口。回放工具核心是读文件、拆消息块、逐个喂给解码器，对比解码结果与当时日志是否一致。改了代码后再回放一遍，能确认修复没有破坏已有消息类型。这套习惯救了我很多次，尤其在设备厂商不肯提供复现环境的时候。回放抓到的问题修复后，再回产线联调跑两小时心跳稳定性，基本就能放心交接。希望帮到你。
本文还有配套的精品资源，点击获取
