SECS-II/HSMS调试工具实战：模拟器搭建与高频踩坑指南

简介：面向半导体及制造业MES系统开发与调试人员，提供SECS-II/HSMS通信链路的模拟验证工具。该模拟器可灵活切换为服务端或客户端模式，用于确认上位机与设备间交互数据是否符合SECS-II标准及客户规范，避免因协议偏差导致联调返工。整套资源共4个文件、约90KB，包含可直接运行的exe程序、两个XML配置文件及一份使用说明文本，其中XML分别对应测试场景与默认配置，便于快速搭建模拟环境，文本说明则覆盖启动方式、常见指令与报文收发要点。资源已有2838人学习，适合自动化设备通讯工程师、MES集成人员及协议测试人员学习参考。通过对照内置样板文件，读者能直观理解标准报文的组织方式，也可以基于默认配置直接进行服务端/客户端模拟联调，从而高效验证自研程序在会话建立、消息头解析、数据项编码等环节是否符合SECS-II规范。

1. SECS-II/HSMS 调试工具：设备还没到场，联机代码也得先跑起来

干过半导体设备联机的人都有过这种经历：EAP 开发排期被压到设备进场前两周，设备还在海运路上，客户却要求进场三天内把 S1F13/S1F14 跑通。没有设备，你怎么验证自己写的通信层？对着 SEMI E37 标准文档手搓字节流，搓到凌晨也未必能跟真机一次握上手。SECS-II/HSMS 调试工具和模拟器解决的就是这个痛点：在一台普通 PC 上把“假设备”跑起来，让它能说 SECS-II 的话、能响应 HSMS 会话控制、能按样板文件回你定义好的数据。这篇文章的目标是让你看完就能搭一套这样的工具，并知道联调时哪些参数是必调的、哪些坑是必踩的。

2. 先把协议底子弄清：10 字节报文头、5 个超时参数与 SML 样板文件

写模拟器之前，先逼着自己把 SECS-II 的消息格式和 HSMS 的会话流程理一遍。这个环节省不得，因为后面你看到的每一个“玄学问题”，几乎都能回溯到协议理解偏差上。尤其是 HSMS 报文头那 10 个字节，EAP 端和模拟器端对它的理解不一致，直接表现就是连接建立了但消息互相不理——这种问题最难查，因为 TCP 层是通的，抓包也能看到包，就是业务跑不动。

2.1 10 字节报文头：一眼认出 S1F13 的基本功

HSMS 在 TCP 上传输 SECS-II 消息时，每个数据包由“4 字节消息长度 + 10 字节报文头 + 消息体”组成。报文头是整个协议的骨架，我把常用字段拆成下面这张表，你调试时对着 hexdump 能认出每一个字节。

排查问题最常用的就是最后这个 System Bytes。EAP 发一条 Primary 消息（比如 S1F13），系统字节是 0x00000012，那么模拟器回 S1F14 时，系统字节必须是同一个 0x00000012，否则 EAP 会把这条回复当成“来路不明”的消息直接丢弃。我在项目里见过不少新手模拟器，能收能回，但 EAP 日志永远提示 timeout，查到最后就是系统字节没回原值。

SType 不为 0 时，第六、七字节的含义会变成控制消息的状态字而不是 Stream/Function。例如 Select.Req 的 SType=0x01、字节6和字节7皆为 0；Select.Rsp 的 SType=0x02、字节6是状态码（0x00 成功）。如果你拿解析数据消息的逻辑去解析控制消息，会把 0x00 误当成 Stream=0、Function=0，然后一脸茫然。这一点是新手最容易在抓包工具里看懵的地方。

2.2 T3/T5/T6/T7/T8：模拟器里那五个“看不见的敌人”

HSMS 的状态机不复杂：TCP 连接建立后，主动端发送 Select.Req，被动端回 Select.Rsp，双方进入 Selected 状态，这时候才能传数据消息。但支撑这个状态机的五组超时参数，才是联调时真正的坑。设备厂家的默认值五花八门，日本设备爱把 T3 设成 20 秒，欧美设备常见 45 秒，你的模拟器和 EAP 如果各用一个默认值，就会出现“客户现场总是偶发超时”这种需要靠运气复现的故障。

我在配置模拟器时，永远把这五个参数全部暴露到配置文件里，而不是写死在代码中。理由很直接：你现在是给自己调试，参数可以随便；但将来这套模拟器要交给客户或产线工程师用，对方设备的超时配置未必跟你的开发环境一致，写死一个默认值就等于埋雷。把参数暴露出来，万一联调出问题，可以先排查是不是超时配置不匹配，而不是回头改代码重新部署。

2.3 样板文件长什么样：SML 格式的 S1F14 回复体

标题里特别提到“带样板文件”，说明作者也明白：模拟器再灵活，不给几个现成的 .sml 文件让用户改，大多数人还是不知从哪下手。SML（SECS Message Language）是 SECS-II 消息的文本表示法，模拟器读取 SML 后将其编码成二进制消息体发送。一个 S1F14 的回复样板长这样：

S1F14 W <L <U4 0> <L <L <A "MDLN"> <A "SIM-PROBER"> > <L <A "SOFTREV"> <A "1.2.0"> > > >.

这段 SML 的含义是：回复一条 S1F14，W 表示这是一条带 Wait Bit 的消息（虽然 F14 本身是 Secondary，这个 W 会被忽略，但保留它不影响解析）。最外层 L 是列表，第一个元素 U4 是 COMMACK 的返回值，0 表示 OK；第二个元素是设备信息列表，MDLN 和 SOFTREV 是标准键。模拟器加载这个文件后，收到 S1F13 就会把这段内容编码成字节流回给 EAP。

写 SML 有两条纪律。第一条，缩进必须用空格或 Tab 之一，别混用，很多解析器对混用缩进的报错信息非常弱，直接给一个“parse error”让你猜半天。第二条，字符串 A 类型里的内容不要带不可见字符，回车换行都要转义，否则编码出来的消息长度跟你预期对不上。样板文件的价值就是让你不用从零写这些框子，但改内容时千万别破坏它原有的格式骨架。

3. 用模拟器把被动端跑起来：库选型、代码骨架与配置文件

协议底子清楚了，接下来就是把模拟器真正跑起来。这一步我的建议是：不要自己从 socket 开始实现 HSMS，直接站在成熟库的肩膀上。半导体行业不缺实现，缺的是能说明白“为什么这样选”的人。我惯用的方案是 Python 生态里的 secom 库，它把 HSMS 被动端/主动端的会话管理、超时控制都封装好了，业务上只需要处理“收到什么消息，回什么消息”这件事本身。

3.1 为什么是 secom 而不是自己拼 socket

自己实现 HSMS 不是不行，但成本和收益不成比例。你写模拟器的目的是验证业务逻辑，不是复习 TCP 编程。HSMS 的选包、分帧、会话控制消息（Select/Linktest/Separate）这些底层逻辑，如果自己写，至少要几百行代码，而且每一个坑都要自己趟一遍。我在早期项目里吃过这个亏：自己实现的被动端在正常连接下没问题，一旦 EAP 端重启，TCP 半关闭状态下触发 T5 超时，就出现“连接在，会话没了”的诡异状态，排查了大半天才发现是自己没处理连接断开后的会话清理。

secom 这类库把状态机封装好了，被动端连接断开后会自动清理会话状态，T6 超时后会自动断开异常连接，这些边界逻辑都已经过大量使用者的验证。另一个好处是日志质量。自己写 socket 程序，打印出的日志往往只有字节长度，而 secom 会把 SType、Session ID、Stream/Function 都打出来，联调时看日志定位问题比逐字节看 hexdump 高效太多。

3.2 HSMS 被动端：一版能跑通的最小代码

下面这个骨架是我在自己的调试工具里一直用的组织方式。注意库 API 以你安装的版本为准，结构上按照“配置、连接、消息处理、启动”四层来写，不会跑偏。

# gem_equipment_sim.py # 模拟器被动端：等待 EAP 主动连接，收到 S1F13 回 S1F14 import asyncio import logging from secom.hsms import HsmsSettings, HsmsConnection logging.basicConfig(level=logging.DEBUG) async def handle_message(msg): # msg 携带 stream/function 与消息体，内部已解析成 SECS-II 结构 stream, func = msg.stream, msg.function # 收到 S1F13：设备通信建立请求，回复 S1F14 if (stream, func) == (1, 13): # 构造回复体，模拟器向 EAP 宣告自身型号与软件版本 body = { "COMMACK": 0, "MDLN": "SIM-PROBER", "SOFTREV": "1.2.0", } return msg.reply(body) # 其他消息暂不处理，返回 None 表示不回复 return None async def main(): settings = HsmsSettings( device_id=0, # 设备 ID，需与 EAP 侧配置保持一致 is_server=True, # True=被动端，等待 EAP 连接 ip="0.0.0.0", # 监听所有网卡，避免本机防火墙拦连接 port=5000, # 默认端口建议 5000，可改 t3=30, t5=10, t6=5, t7=10, t8=60, ) conn = HsmsConnection(settings) conn.on_message = handle_message await conn.start() await asyncio.Event().wait() # 保持进程常驻 if __name__ == "__main__": asyncio.run(main())

这段代码的逻辑很简单：启动一个 HSMS 被动端，监听 5000 端口，任何 EAP 连上来之后，只要发 S1F13，模拟器就回 S1F14。msg.reply(body)这个方法会替你完成三件事：把 body 编码成 SECS-II 二进制、把 System Bytes 置成请求里的原值、把 R 位清掉——这三件事正好对应前文强调的“系统字节必须回原值”这条协议规则。

参数里最需要注意的是device_id。它在报文头里占据了 Session ID 字段的高 7 位，EAP 侧配置的 Device ID 跟模拟器不一致时，消息能收发但会被对方判定为非法会话。我在客户现场见过很多次“两台设备明明都配了 0，还是不通”的情况，最后发现是一个配了 0 一个配了 127——0 的时候高 7 位全 0，127 的时候高 7 位全 1，抓包看 4-5 字节是 0x0000 和 0x8000 的差别，肉眼很容易漏看。

3.3 配置 JSON：把五个超时和设备参数全部抽出来

代码里的参数写死不是好习惯，我一般会把配置抽成独立的 JSON 文件。这样换设备、换产线环境时，只改配置不碰代码，客户现场的工程师也能自己动手调，不用每次都回来找你改脚本。

{ "device_id": 0, "mode": "passive", "ip": "0.0.0.0", "port": 5000, "timeouts": { "t3": 30, "t5": 10, "t6": 5, "t7": 10, "t8": 60 }, "log_level": "DEBUG", "sml_dir": "./sml" }

sml_dir字段值得多说一句。把样板文件单独放一个目录，而不是塞在代码里，模拟器启动时遍历目录加载所有 .sml 文件，按文件名自动注册消息处理函数。比如s1f13.sml文件里写的是回复体，那么收到 S1F13 就自动加载它并返回。这样你在不修改任何代码的前提下，往目录里丢一个新的 S7F5.sml，模拟器就自动具备响应 S7F5 的能力——样板文件从“参考示例”变成了“可插拔的消息库”，这套设计在交付给产线时特别实用，对方只要会复制粘贴 .sml 文件就能扩展模拟器行为。

3.4 用网络调试工具先验证链路：nc 不是摆设

代码写完先别急着跑完整业务联调，先用最朴素的手段验证链路通没通。我习惯在网络调试工具里用 nc 做一次 TCP 连通性探测，这一招在区分“网络层问题”和“协议层问题”时极其高效：

nc -vz 127.0.0.1 5000

这条命令的-v显示详细连接信息，-z表示只扫描端口不发送数据。看到Connected to 127.0.0.1 port 5000 succeeded就说明 TCP 层是通的，再往下才是 HSMS 会话层的问题。如果这条命令都失败，就先排查防火墙和监听地址，别急着折腾协议。很多新手一上来就抓包看字节，结果发现机器上两个模拟器实例都在，一个占了 5000 端口，另一个眼巴巴等你连接——先用 nc 探一下就能少走这个弯路。

4. 从 S1F13 到 S7F5：把业务消息在模拟器上完整联调一遍

被动端跑起来只是第一步，这个标题里的工具真正值钱的地方在于“能联调业务消息”。半导体设备联机不只是 S1F13/S1F14 握个手就完事，后面接踵而来的是一大堆业务交互：主机下传配方（S7 系列）、设备上报事件（S6 系列）、参数读取（S2 系列）。这一章我们从最常用的三条链路走一遍，顺便把“如何确认消息正确”的方法讲清楚。

4.1 一条完整链路：S1F13 握手之后的业务交互

EAP 跟设备建立通信后，最常见的第一件业务事是查配方列表。主机发 S7F5（Process Program List Request），设备回 S7F6，里面带一个字符串数组，列出设备上存有的所有配方名。这个交互虽然简单，却是检验模拟器是否真正“可用”的分水岭：只会握手不会回业务消息的工具，在真实联调里帮不上忙。

我把 S7F5 的样板文件写成这样：

S7F5 W <L <A "PP001"> <A "PP002"> <A "PP003"> >.

SML 解析后的内容是：一个列表，包含三个 A 类型字符串，对应三个配方名。模拟器收到 S7F5 后，把这个列表编码进 S7F6 的回复消息体。EAP 侧收到后能正确解析出三个配方名，说明从“消息编码”到“消息解析”的整条链路上，Stream/Function、消息长度、SECS-II 类型标记全都对得上。

这里有个细节我需要提醒：SML 文件里 W 的作用在不同消息里不一样。S7F5 在协议里就是带 W 的 Primary 消息（主机期待设备回复），你写 W 没错；但如果你把 W 理解成“我回复时也带 W”，那就错了。回复消息（Secondary）的 R 位在报文头里应该清零，如果模拟器库没有自动处理这个位，你就得手动确保回复时不携带 R 位，否则 EAP 会把你的回复当成又一条 Primary 来期待处理，日志会疯掉。

4.2 在模拟器里注册 S7F5 处理逻辑

回到代码上。前面 3.2 的骨架只处理了 S1F13，现在我们需要扩展它，让模拟器具备多个消息处理分支。我采用的方式是注册表模式：把消息处理函数做成一个路由表，每个 (stream, function) 元组对应一个函数。

async def handle_s7f5_query(msg): # 返回配方列表，内容可由 sml 文件读取，也可硬编码 return [b"PP001", b"PP002", b"PP003"] async def handle_message(msg): handlers = { (1, 13): handle_s1f13, (7, 5): handle_s7f5_query, # (7, 17): handle_s7f17, # 配方下载请求，可继续扩展 } handler = handlers.get((msg.stream, msg.function)) if handler: return await handler(msg) return None

路由表的好处是清晰，来一条消息直接查表，没有命中就保持沉默。沉默本身也是一种调试信息：如果 EAP 发的消息你不想处理，不要乱回文不对题的内容，宁可让它超时，也比回错数据把对方的状态机搞乱强。b"PP001"这种 bytes 类型对应 SECS-II 的 A 类型，如果你传 Python 字符串，有些库会自动编码，有些库会直接报错，注意保持一致。

配方列表这种静态数据放在代码里没问题，但真实设备上的配方名经常有规律，比如按设备腔室编号CH1_PP001、CH2_PP001。这时候我建议把配方列表也抽到配置文件里，模拟器启动时读入，生成对应的消息体。你要模拟“设备里有 100 个配方”的场景时，直接改配置就行，不用重新写代码。

4.3 验证业务消息：抓包与日志双通道确认

消息发出去了，怎么确认对错？我的标准做法是双通道验证：一边看模拟器日志里的解析结果，一边用抓包工具看原始字节。日志告诉你“业务逻辑执行了没有”，抓包告诉你“字节长得到底对不对”，两个都能对上，这条消息才算真正跑通。

先用抓包确认 S7F6 回复的报文头：

# 在 EAP 侧抓包，过滤设备的 IP 和端口 tcpdump -i eth0 host 192.168.1.100 and port 5000 -X

抓到 S7F6 的回复后，重点看三处：第一，第 4-5 字节的 Session ID，高 7 位必须跟 EAP 配置的 Device ID 一致，R 位应为 0；第二，第 6 字节是 0x07、第 7 字节是 0x06，合起来就是 S7F6；第三，第 10-13 字节的 System Bytes 必须跟请求 S7F5 里的完全一样。这三处全对，EAP 才可能正确识别这条回复，任何一处不对，迎接你的就是 T3 超时。

日志侧的验证更直接。secom 的 DEBUG 日志会打印“收到 S7F5, 回复 S7F6, device_id=0, system_bytes=0x0000001A”这类信息，你一眼就能看到回复方向与事务号。我把这个习惯总结成一句话：抓到包先看报文头三要素，再谈消息体。报文头不对，消息体里的数据再正确也是白瞎；报文头对了，消息体解析不出来，再去查 SML 文件的编码问题，两条线分开排查，效率会高很多。

4.4 测试反向消息：模拟器主动上抛 S6F11 事件

设备联机里还有一半场景是设备主动发消息给主机，典型代表是 S6F11（事件报告），比如“加工完成”“异常报警”这类状态变化。模拟器不能只会等着被问，还得会主动“说话”，否则你没法验证 EAP 的事件处理逻辑。

# 定时或触发式发送 S6F11：模拟一个 "Process Complete" 事件 event_message = { "EVENTID": 501, # 事件 ID，需与 EAP 配置的事件表对照 "DATA": [ {"DATAID": "LOT001", "PPID": "PP001", "RESULT": "OK"}, ], } await conn.send_primary(6, 11, event_message)

send_primary的方向要理解清楚：模拟器作为设备，发出 S6F11 是一条带 W 的 Primary 消息，期待 EAP 回 S6F12 应答。EAP 回 S6F12 里的 ACK 值要跟事件 ID 对得上，如果对不上，说明 EAP 侧的事件订阅配置有问题。这个方向如果搞反了，模拟器用send_primary发了消息然后又去回一个 Secondary，状态机立刻乱套，这也是刚接触 HSMS 的人最常犯的方向性错误。

事件上报的时机也值得在模拟器里做成可配置。我习惯在配置文件里加一个event_interval_seconds字段，模拟器每隔 N 秒自动上抛一条 S6F11，用于压力测试 EAP 的接收能力。有的客户 EAP 处理事件较慢，消息一密集就丢，这种场景你在模拟器上几秒钟就能模拟出来，不用等真设备出问题才发现。

5. 避坑手册：HSMS 模拟器联调最常见的 5 个翻车现场

这个章节写的是我这些年调试 SECS/GEM 设备攒下的血泪经验。每一条都曾经真实发生过，且复现率极高。你照着前面章节操作大概率会撞上其中一两条，提前看完能省下半天到一天的排查时间。

5.1 现象：EAP 连不上模拟器，报 connect_refused

原因：八成不是程序逻辑错，而是监听地址没对。模拟器配置里 ip 写成 127.0.0.1，EAP 在另一台机器上用真实 IP 去连，连接必然被拒。另一类原因是本机防火墙把端口挡了，特别是 Windows 上 Python 第一次监听端口时会弹出防火墙授权框，没点允许就永远被拦在外面。

解决：模拟器监听地址直接写 0.0.0.0，端口选一个产线不会冲突的（5000 是 HSMS 常用默认值之一）。然后用前面说的 nc 命令在本机验证一遍，再换到 EAP 所在机器验证一遍，两步都通才算链路没问题。如果换了机器之后 nc 还是不通，优先查防火墙规则而不是改代码。

5.2 现象：S1F13 发出去了，模拟器显示收到了，但 EAP 一直报 T3 超时

原因：模拟器回了消息，但回复的系统字节跟请求不一致。这是新手实现 HSMS 时最高发的错误——自己构造回复消息时把 System Bytes 填成了新的随机值，或者干脆填了 0。EAP 靠 System Bytes 匹配请求和回复，匹配不上就丢弃，表现为“对方好像没回”。

解决：检查模拟器日志里收到的请求和发出的回复，System Bytes 必须逐字节一致。如果用的库没有自动回填功能，你在代码里拿到请求 msg 后，构造回复时要显式把msg.system_bytes写进回复头。这个坑我在项目里踩过，当时抓包对比了十几分钟才猛然发现两个包的 System Bytes 差了 1。

5.3 现象：模拟器收到的消息是乱码，SML 解析频繁报错

原因：八成不是解析器问题，而是文件编码。Windows 上编辑的 SML 文件默认可能是 GBK 或带 BOM 的 UTF-8，解析器按无 BOM 的 UTF-8 读取，字符串里就会出现不可见字符，导致长度计算错位。另一个常见原因是缩进混用 Tab 和空格，解析器对层级结构敏感，混用会直接解析失败。

解决：所有 SML 样板文件统一用 UTF-8 无 BOM 保存，缩进统一用两个空格。加一条规矩：文件里不要出现中文字符串，设备信息里全部用 ASCII 字符。别笑，很多设备厂家在 MDLN 字符串里写中文型号名，传出去的字节跟 EAP 侧编码不一致，乱码问题从协议层一路传到数据库。编辑 SML 时用能显示隐藏字符的编辑器，比如 VS Code，一眼能看到文件尾有没有多余的回车。

5.4 现象：模拟器连着 EAP，但几分钟后会话自动断开

原因：主动端（EAP）默认每 T8 秒发一条 Linktest.Req 来探测连接是否还活着。模拟器如果没正确回 Linktest.Rsp，EAP 会认为连接已断，主动发起 Separate 并关闭套接字。很多新手模拟器只顾着处理业务消息，忘了控制消息也要响应。

解决：确认你用的库是否默认自动响应 Linktest 和 Select，如果没有，在消息处理函数里加一个分支：收到 SType=0x05 的控制消息（Linktest.Req），直接回 SType=0x06 的 Linktest.Rsp，系统字节同样回原值。我在自己调试工具里把这个响应放在库的底层自动处理，业务层永远看不到控制消息，省心很多。

5.5 现象：抓包能看到 TCP 数据，但 Wireshark 解析不出 HSMS 协议

原因：Wireshark 的 HSMS 解析器默认只对特定端口生效（常见的是 5000 端口和 10000 端口），你用 4000 或 8000 端口跑模拟器，它就不会按 HSMS 协议解析，只能看到一堆 RAW 数据。

解决：在 Wireshark 里右键任意 TCP 包，选择“Decode As”，手动指定为 HSMS 协议；或者干脆在模拟器配置里就用默认端口 5000。还有一个更省事的习惯：抓包时顺便开模拟器的 DEBUG 日志，业务对错看日志，字节对错看抓包，两者配合，大多数问题五到十分钟就能定位。纯靠抓包一个通道排查问题，容易被端口解析这种小事带偏方向。

6. 进阶：把模拟器接进回归流程，再平滑切到真设备

模拟器跑通了，别急着卸载。我后来养成的习惯是把它变成一个常驻的回归测试工具：每完成一次 EAP 代码变更，先跑一遍模拟器回归脚本再上真机。这个习惯帮我拦下了至少三次“低级但致命”的线上事故——比如改了一个共用函数导致 S6F11 的事件 ID 全部错位，这种问题在模拟器上只要跑一次回归就能暴露，而到了真机上产生误报才会被发现，损失完全不是一个量级。

回归脚本的做法很朴素：写一个循环脚本，反复执行“S1F13 握手 → S7F5 查列表 → S6F11 上抛事件 → 验证回复”这条链路五百次，中途随机触发断线重连、超时不回等异常场景，看 EAP 的恢复逻辑是否正常。我把这个脚本放在 CI 里，每晚自动跑一次并输出报告。模拟器的价值不在于“模拟得像”，而在于“稳定可重复”——真设备不会配合你反复重启、反复注入异常，但模拟器可以，而且随便怎么折腾都不会心疼硬件。

最后说一下切真设备时通常要改什么，我列一张检查表供你对照。IP 和端口是必改的，设备 ID 必须跟真机的实际配置一致；五组超时参数改成真机规格书里的值，特别是 T3 和 T8，日本设备经常跟默认值差很多；样板文件里所有业务数据要从“调试假值”换成真实配方和真实事件 ID；最后把模拟器里设的event_interval_seconds调成跟产线实际报警频率相近再观察一轮。切真机前我还习惯先做一次纯监听不回复的被动模式，先确认真机上线后网络链路是否正常，再逐步启用业务响应。

这套方案我一直走到今天，中间也踩过不少坑，但有一条经验是我反复验证过的：模拟器做得越真、可控性越强，现场联调时间就越短。每次看到别人对着真机一边调参一边祈祷的场景，我就庆幸自己提前把模拟器这套东西搭起来了。希望你这次也能把模拟器的价值用满，别让它只在项目初期露个面就吃灰。希望帮到你。

本文还有配套的精品资源，点击获取