完全自定义报文采集

完全自定义报文采集用于接入没有现成采集插件、但通讯规则可以用固定请求、分帧、响应匹配、校验和数据偏移描述的设备。设备插件名称为 CustomPacketMaster，支持 TCP 客户端、TCP 服务端、UDP 会话和串口通道。

通过协议配置可以定义完整读取请求、带变量值占位符的写入请求、四种响应分帧规则、响应归属和成功条件、校验算法及有效载荷范围。设备调试可以按 Hex 或文本发送完整报文，并显示实际发送字节、完整响应、耗时和错误信息。

适用场景

场景	说明
厂商私有二进制协议	请求和响应结构固定，数据位于明确的字节或位偏移。
文本指令协议	报文可以按指定字符编码生成，并以结束符或固定长度分帧。
固定包头协议	包头中包含一、二或四字节长度字段，可以据此计算完整帧长度。
起止码协议	每帧包含明确的起始码和结束码。
简单读写协议	读取使用固定请求，写入报文只需要替换一个变量值。

不适用的协议

需要登录握手、多阶段会话、动态密钥、加密解密、压缩、文件传输或跨报文状态机的协议，应开发独立采集插件。自定义报文配置不会执行任意脚本。

配置前准备

配置前应从设备协议手册、抓包结果或厂商联调资料中确认以下信息。

信息	需要确认的内容
通讯链路	设备使用 TCP 客户端、TCP 服务端、UDP 会话，还是通过本机串口通讯。
完整请求	每个读取命令实际发送的完整 Hex 报文。
分帧规则	固定包头、起止码区间、结束符或固定长度中的一种。
响应归属	响应中可用于判断其属于当前请求的命令字、站号或事务标识。
成功条件	响应中表示成功或失败的状态字节。
有效载荷	变量数据在完整响应帧中的起点和长度。
校验规则	算法、计算区间、校验值位置、字节序以及请求校验值的写入方式。
点表	变量名称、数据类型、字节序、字节偏移、可选位偏移和读写权限。

首次联调建议只配置一个读取命令和一到三个变量。确认报文收发、有效载荷和数值解析均正确后，再扩展完整点表和写入命令。

新建通道

登录 GatewayRuntime Web，进入“开发配置 → 采集配置”，点击“通道管理 → 新增”。

1. 填写唯一且便于识别的通道名称。
2. 根据设备连接方向选择 TcpClient、TcpService、UdpSession 或串口通道。
3. 填写远程地址、绑定地址或串口参数，并开启通道。普通 UDP 主动采集必须配置设备远程地址。
4. 结合现场网络时延设置连接超时、缓存超时和最大并发数。
5. 保存通道。

通道类型	使用条件	关键参数
TcpClient	GatewayRuntime 主动连接设备或协议模拟器。	远程 IP、端口、连接超时。
TcpService	设备或 DTU 主动连接 GatewayRuntime。	绑定地址、监听端口、客户端上限和 DTU 标识规则。
UdpSession	设备通过 UDP 收发完整数据报；适合无连接的请求响应协议。	本地绑定地址、设备远程 IP 和端口；DDP 场景还需确认终端标识。
串口	设备通过本机或映射串口通讯。	串口号、波特率、数据位、停止位和校验位。

UDP 数据报边界

UDP 通道下，一个数据报必须且只能包含一个完整协议帧，GatewayRuntime 不会把多个 UDP 数据报拼成一帧，也不会接受在同一数据报中夹带第二帧。数据报内部仍按协议配置检查固定包头、起止码区间、结束符或固定长度。UDP 本身不保证报文到达、顺序和去重，设备和网络侧应允许请求超时及按采集策略重试。

新建设备

点击“设备管理 → 新增”，先完成设备基本信息，再配置插件属性。

1. “设备名称”填写现场设备的唯一名称。
2. “设备插件”选择 CustomPacketMaster。
3. “关联通道”选择前一步创建的通道。
4. 按现场轮询周期设置执行间隔和读写超时。
5. TCP 服务端或 DDP UDP 场景按终端实际注册标识填写 DTU ID；普通 UDP 使用通道配置的远程地址。
6. 打开“插件属性”，在“协议配置”中点击“配置协议”。

配置分帧

协议配置中的“分帧”页决定 GatewayRuntime 如何从 TCP/串口连续字节流或单个 UDP 数据报中识别一帧完整响应。一个设备只能选择一种分帧模式。

固定包头

固定包头模式适用于包头内包含长度字段的协议。完整帧长度按“长度字段解码值 + 长度调整”计算。

配置项	说明
包头长度	首次判断帧长所需的固定包头字节数。长度字段必须完整位于此范围内。
包头特征 Hex	用于识别帧起点的固定字节。存在链路噪声或粘包时建议填写。
包头掩码 Hex	与包头特征等长。掩码为 FF 的位参与比较，为 00 的位忽略。
长度字段偏移	长度字段相对于完整帧第一个字节的偏移，从 0 开始。
长度字段字节数	只允许 1、2 或 4。
长度字段字节序	按协议选择大端或小端。
长度调整	把长度字段值换算为完整帧长度时需要增加的字节数。长度字段已经表示完整帧长度时填写 0。

例如，长度字段表示消息体长度，固定包头为 6 字节，则长度调整填写 6；长度字段表示整帧长度时填写 0。

区间

区间模式从起始码开始收集字节，直到遇到结束码，将起始码和结束码都计入完整帧。

配置项	说明
起始码 Hex	标识一帧开始的一个或多个字节。
结束码 Hex	标识一帧结束的一个或多个字节。
最小帧长	小于该长度的候选帧不会作为有效响应。

结束符

结束符模式从当前帧起点收集字节，遇到指定结束符后完成一帧。适用于换行结束的文本协议或固定尾码协议。

配置项	说明
结束符 Hex	一个或多个结束字节，例如 CRLF 为 0D 0A。
最小帧长	用于排除只有结束符或长度不足的异常帧。

固定长度

固定长度模式按恒定字节数切分响应。只有设备每次响应长度完全一致时才使用此模式。

配置项	说明
固定长度	每个完整响应帧的总字节数。

通用分帧参数

配置项	说明
最大包长	单帧允许的最大字节数。应覆盖现场最大响应，但不要无依据地调大。
文本编码	仅用于文本调试输入和响应文本显示，不改变 Hex 请求。
调试报文上限	单次设备调试允许发送的最大字节数，不能超过最大包长。

UDP 还受单个 IPv4 数据报大小限制。普通 UDP 的自定义报文最多为 65507 字节；DDP UDP 需要预留 16 字节封装，自定义报文最多为 65491 字节。实际允许值取“最大包长”“调试报文上限”和 UDP 传输上限中的最小值。

配置读取命令

切换到“命令”页，点击“添加命令”，为协议中的每种读取请求建立一个唯一命令。

1. “命令名称”填写以英文字母开头的名称，可包含字母、数字、下划线和连字符，例如 ReadStatus。
2. 开启“读取命令”。
3. “读取请求 Hex”填写设备实际需要收到的完整请求报文。
4. 配置读取响应的归属匹配段、成功匹配段和有效载荷范围。
5. 响应带校验值时开启响应校验，并填写算法和字段位置。

Hex 可以包含空格以便阅读，但必须由完整字节组成。例如 01 03 00 00 00 02 有效，奇数个十六进制字符或非 Hex 字符无效。

配置写入命令

需要变量写入时，可在同一命令或独立命令中开启“写入命令”。

1. “写入请求模板”填写完整 Hex 模板，并在变量值应出现的位置放置一个 ${value}。
2. 模板必须且只能包含一个 ${value}，占位符以外的内容必须是有效 Hex。
3. 设备写入后不返回响应时开启“写入仅发送”。
4. 需要确认写入结果时关闭“写入仅发送”，并配置写入响应规则。
5. 请求需要校验时配置“请求校验”，选择覆盖预留字段或追加到报文末尾。

例如 01 06 00 10 ${value} 表示前五个字节固定，变量编码后的字节放在报文末尾。${value} 的实际字节数和字节序由变量的数据类型与解析配置决定。

写入安全

写入会直接作用于现场设备。首次测试应选择无联锁风险的点位，并确认设备允许远程控制。对启停、复位、阀门、电机和工艺设定值执行写入前，必须取得现场授权。

配置响应规则

读取响应和非仅发送写入响应都会先执行归属、校验和成功判断。只有读取响应需要截取变量数据，因此“有效载荷偏移”和“有效载荷长度”只显示在读取响应中；写入响应只确认设备是否正确执行，不返回变量数据。

配置项	作用
归属匹配段	判断分帧后的完整响应是否属于当前请求。每段由“偏移、期望 Hex、可选掩码 Hex”组成；配置多段时必须全部匹配。留空会接受分帧后的第一帧，设备存在异步上报时容易误接收。
偏移	从完整响应帧的第一个字节开始，以 0 计数的字节位置。归属段和成功段都使用这一规则。
期望 Hex	从指定偏移开始应出现的一个或多个字节，例如 AA 55。
掩码 Hex	可选，必须与期望 Hex 等长。逐位按 (实际值 & 掩码) == (期望值 & 掩码) 比较；FF 表示全部位参与比较，00 表示全部位忽略，留空表示精确匹配。
响应校验	验证响应中的校验值，防止损坏报文进入变量解析。
成功匹配段	在响应已归属且校验通过后，判断设备是否执行成功。配置多段时必须全部匹配；留空表示不检查状态码。
有效载荷偏移	仅用于读取响应。从完整响应帧第一个字节开始，以 0 计数的数据区起点。
有效载荷长度	仅用于读取响应。要返回给变量解析的数据区字节数；留空表示从有效载荷偏移截取到帧尾。

归属匹配段通常配置站号、命令字或事务标识。成功匹配段通常配置状态码或异常码。变量地址中的字节偏移从截取后的有效载荷起点计算，不是从完整响应帧起点计算。

例如设备返回完整读取响应：

AA 55 10 00 02 01

可以按下表配置：

位置	配置	说明
归属匹配段 1	偏移 0，期望 AA 55	确认固定响应头。
归属匹配段 2	偏移 2，期望 10	确认命令字属于本次读取。
成功匹配段	偏移 3，期望 00	设备状态码为成功。
有效载荷	偏移 4，长度 2	最终交给变量解析的字节为 02 01。

如果某个状态字节只要求高四位相同，可填写单字节掩码 F0；低四位会被忽略。不要用 00 掩码代替“无需配置”，因为它会使对应期望字节的全部位都不参与比较。

配置校验

开启校验后可选择 Sum8、Xor8、Lrc8、Crc16Modbus、Crc16Ibm 和 Crc16Ccitt。关闭校验开关表示不配置校验规则，不需要再选择 None。

读取请求始终保存调试时实际发送的完整固定 Hex，包括请求末尾已有的 CRC 或累加和，不单独配置请求校验。请求校验只用于写入模板：${value} 被实际变量字节替换后，运行时需要按当前完整请求重新覆盖或追加校验值。读取和非仅发送写入的响应都可以配置响应校验。

配置项	说明
算法	必须与设备协议手册一致。不了解算法时不要根据报文尾部字节猜测。
计算起点	参与校验计算的首字节偏移。
计算长度	参与计算的字节数。留空时，从“计算起点”一直计算到校验字段之前；请求使用“追加”时，一直计算到追加前原请求的末尾。
校验值偏移	覆盖模式下，校验值在完整报文中的起始位置。
字节序	CRC 等多字节校验值在报文中的排列顺序。
写入方式	请求校验可选择覆盖预留字段或追加；响应校验使用报文中的既有校验字段。

配置变量地址

变量地址使用以下唯一格式：

ReadCommand@ByteOffset[.BitOffset][;write=WriteCommand]

部分	说明
ReadCommand	已配置完整读取请求和读取响应规则的命令名称。
ByteOffset	变量值相对于响应有效载荷起点的字节偏移，必须为非负整数。
BitOffset	可选位偏移，范围为 0 到 7，常用于布尔量。
write=WriteCommand	可选写命令。未填写时，写入默认使用读取命令中的写入配置。

示例：

变量地址	含义
ReadStatus@0	使用 ReadStatus 读取，从有效载荷第 0 字节解析变量。
ReadStatus@2.3	从有效载荷第 2 字节的第 3 位解析布尔变量。
ReadValue@4;write=WriteValue	使用 ReadValue 读取第 4 字节起的数据，写入时使用 WriteValue。

变量的数据类型、数组长度、字节序、字符串编码和表达式仍在变量配置中设置。它们必须与有效载荷中的真实数据布局一致。

使用自定义报文调试

进入“开发配置 → 采集配置”，切换到“设备显示”，选择 CustomPacketMaster 设备，在详情区打开“调试”标签。

1. 选择 Hex 或“文本”输入模式。
2. 选择“仅发送”或“发送并等待”。
3. 文本模式下选择与设备一致的字符编码。
4. TCP 服务端通道必须从在线列表中选择一个目标客户端。普通 UDP 使用通道中预先配置的远程地址，DDP UDP 使用已识别的终端端点。
5. 输入完整报文并点击发送。
6. 核对“实际发送 Hex”。该值应与输入内容逐字节一致。
7. “发送并等待”时继续核对响应 Hex、响应文本、耗时和错误信息。

调试发送的是用户输入的完整报文，不会自动添加包头、结束符、长度字段或校验码。需要这些字节时必须在调试输入中完整填写。调试收发使用独立的原始捕获通道，不依赖当前错误的分帧配置；TCP/串口按接收静默间隔聚合响应，UDP 以一个非空数据报作为响应边界，零长度数据报不会被当作有效响应。调试仍使用当前设备绑定的通道，不能临时修改 UDP 远程地址、串口参数或 TLS 参数。

模式	行为
仅发送	报文写入通道后立即返回，不等待设备响应。
发送并等待	报文写入通道后，通过原始捕获等待响应；TCP/串口在静默间隔后结束，UDP 收到一个非空数据报即结束。

“发送并等待”从注册原始捕获开始，到收到响应、超时或取消为止，会独占目标物理通道。通道上已有周期采集、变量写入或其他调试请求时，本次调试会先等待前一个请求结束；等待期间被取消的调试不会发送报文，也不会阻塞后续请求。捕获会话会在下一个请求进入前关闭，避免迟到响应被下一条命令误用。

从调试结果生成协议配置

协议配置错误时也可以进入原始调试。设备会暂停变量采集并使用调试引导协议保持通道连接；调试页面先通过真实请求和响应采集样本，再按用户选择生成分帧、读取命令或写入模板，最后由完整编辑器和后端实发样本验证确认。

建议对同一请求至少执行两次“发送并等待”。在安全且允许的前提下，让设备返回的数据值发生变化，例如温度、计数值或状态发生变化，系统才能更准确地识别可能的有效载荷范围和稳定响应字段。

1. 在调试页面输入完整请求。读取或需要确认结果的写入命令选择“发送并等待”并执行多次成功交换；设备没有写入响应时选择“仅发送”。TCP/串口按需要调整接收静默间隔。
2. 让响应长度出现变化，以便固定包头长度字段具有可验证证据；如果协议使用起止码或结束符，也要收集至少两个完整响应。页面最多保留最近 8 个成功响应样本。
3. 点击工具栏中的魔棒按钮，打开“协议草稿”。成功的“发送并等待”必须同时包含实际请求和完整响应；成功的“仅发送”可以直接生成写入仅发送命令。
4. 选择“读取命令”或“写入命令”，填写符合命名规则的命令名称。
5. 在“分帧生成方式”中选择“自动识别”“保留当前配置”或一种明确分帧模式。已知设备使用固定包头、区间、结束符或固定长度时，应直接选择对应模式。
6. 根据实际协议确认有效载荷、成功状态和写入值范围。只有确实需要时才开启“自动生成归属匹配段”，并设置最多生成几段；默认不生成，开启后默认最多生成 1 段。
7. 协议包含校验时，写入命令可以开启“请求校验”，读取或等待响应命令可以开启“响应校验”。按设备协议手册选择算法、计算范围、校验值偏移和字节序；写请求校验还需选择覆盖或追加。
8. 点击“重新生成”，等待“实发样本验证通过”状态出现。未通过时按错误提示调整字段并重新生成。
9. 点击“完整复核”，检查当前分帧配置、命令请求、响应规则和校验配置。可以重命名本次生成的命令，系统会继续跟踪该命令并使用新名称验证；如果删除本次样本对应的命令，草稿会立即失效。关闭完整编辑器后系统会再次使用同一实发样本验证。
10. 点击“应用并重启设备”，确认后系统会把草稿写入该设备的最新协议配置，并按正常设备更新流程重启设备。

草稿配置项	说明
可比样本数	与首次响应长度相同、可以参与逐字节比较的响应数量。响应长度不同的样本不会参与本次范围推导。
分帧生成方式	“自动识别”按区间、固定包头、结束符、固定长度的证据顺序选择一个候选；“保留当前配置”不修改设备已有分帧；选择明确模式时只生成该模式，不会再用其他边界候选覆盖。固定包头仍需要至少两种响应长度证明长度字段关系。
自动归属匹配	默认关闭。至少有 2 个同请求同长度样本时，开启后从载荷和成功状态范围之外选择稳定字节，并严格按“归属匹配段上限”生成；默认上限为 1，最大为 4，每段最多 16 字节。
有效载荷偏移和长度	读取命令中交给变量解析的数据区。多样本存在变化字节时，初始值覆盖首个到最后一个变化字节；生成后仍应按协议手册确认。
成功状态检查	开启后，从指定偏移和长度提取最近一次响应字节，生成成功匹配段。应确保该范围确实表示设备执行成功。
写入值偏移和长度	写入命令中变量编码字节所在范围。系统用 ${value} 替换该范围，必须按协议手册和实际写请求确认。
写入仅发送	设备不返回写入响应时开启。成功的“仅发送”调试默认生成该方向并保留当前分帧；不要求响应样本，也不会生成写入响应规则。
请求校验	只用于写入模板，由用户明确开启。覆盖方式保留模板内的预留校验字段，并在指定偏移重写；追加方式会先移除完整调试请求末尾与算法等长的现有校验值，再由运行时重新追加。读取请求保存完整实发 Hex，不生成请求校验规则。算法不会从样本猜测。
响应校验	用户明确开启后生成到读取响应或非仅发送的写入响应，只能校验完整响应中已有的覆盖字段。算法不会从样本猜测。
完整复核	打开完整协议编辑器，检查分帧、命令、响应规则和校验规则后再返回草稿。重命名生成命令会同步到后续验证和应用；删除生成命令会阻止应用。

草稿验证不是只检查 JSON 结构。读取命令会将配置中的完整固定请求与实际发送字节逐字节比较；写入命令会从实际请求提取值区间，再通过运行期模板和请求校验引擎重建完整请求并逐字节比较。存在响应时，完整响应还会进入正式采集使用的 CustomPacketMessage 分帧路径，并继续验证归属匹配、响应校验和成功状态。错误的校验算法、范围、字节序、偏移、帧长或边界会在应用前被拒绝。

自动生成边界

• 只有一个可比样本时不会生成归属匹配段，分帧也只会生成低置信度候选，避免把可能变化的数据误写成固定条件。
• 响应始终等长时不会把稳定常量字节猜成固定包头长度字段；此时只生成固定长度或明确边界候选。要推导长度字段，必须采集至少两种完整响应长度。
• 自动生成不会猜测请求或响应校验算法。协议存在校验时，必须在草稿页由用户选择；完整复核仍应再次核对计算范围和校验值位置。
• 写入值区间无法从单次写请求可靠识别，必须人工确认；错误范围可能生成无效请求，甚至写入错误点位。
• 自动推导只处理请求和响应均不超过 64 KiB 的样本，预览只显示有限字节；超限报文仍可按设备配置调试，但不能自动生成。
• 应用协议需要设备更新权限，并会重启当前设备。应用前应确认现场允许短暂中断采集。

导入和导出

采集配置可以沿用页面现有的 Excel 导入和导出流程。导入前建议先在页面创建一台 CustomPacketMaster 测试设备并导出，以当前导出文件作为模板。

1. 导出时确认设备插件、关联通道、协议配置和变量地址都在交付文件中。
2. 导入时先使用“验证”或预览功能检查错误，再正式写入。
3. 导入后打开协议配置，检查命令名称、Hex、分帧和校验规则是否完整。
4. 先启动少量测试变量并执行设备调试，再启用完整采集任务。

当前版本只接受当前导出模板和当前协议配置结构。不要手工增加旧字段、别名或第二套配置对象。

共享通道

同一个物理通道可以关联多台 CustomPacketMaster 设备，但这些设备必须使用完全一致的分帧配置和最大包长。系统会比较分帧配置；存在差异时会拒绝共享，并指出冲突信息。

共享通道始终保持单个在途请求。调试、周期采集和变量写入不会在同一通道上交叉发送。TCP 服务端和 DDP UDP 场景还必须为每台设备配置正确的 DTU ID；TCP 服务端调试时需要明确选择目标客户端。

验收检查

检查项	通过标准
通道	TCP 已连接、UDP 已绑定且远程地址正确，或串口已打开；通道日志没有持续通讯失败。
分帧	TCP/串口拆包、粘包或连续响应时能稳定得到完整帧；UDP 每个数据报恰好包含一个完整协议帧。
读取命令	实际发送 Hex 与协议手册一致，响应能通过归属和成功条件。
有效载荷	截取范围准确，变量偏移从有效载荷起点计算。
变量值	当前值、原始值、数据类型和字节序与设备实际值一致。
写入	安全点位写入成功，必要时写后复核结果一致。
调试	仅发送和发送并等待均符合预期，实际发送 Hex 与输入一致。
恢复	TCP 断开重连、UDP 超时后重试或串口重开后能够恢复采集。

故障排查

现象	重点检查
通道无法启动	通道类型是否受支持，TCP/UDP 远程地址、绑定端口、串口占用和权限是否正确。
UDP 无法发出请求	普通 UDP 是否配置远程 IP 和端口；DDP UDP 是否已经识别正确的 DTU ID 和终端端点。
UDP 收到数据但无法分帧	一个数据报是否包含一个完整协议帧，数据报是否被设备拆成多次发送，帧长或边界是否与当前分帧规则一致。
调试请求未立即发出	同一共享通道是否已有周期采集、变量写入或其他调试请求正在等待响应；当前通道只允许一个在途请求，前序请求完成或超时后才会继续。
正式采集持续等待超时	设备是否收到请求，分帧模式、帧长、起止码或结束符是否与真实响应一致；UDP 还需检查丢包、远程端点和设备是否回复。
原始调试等待超时	设备是否真实回复，TCP/串口静默间隔是否足够，UDP 回复来源是否为设备远程端点；原始调试不受当前分帧规则影响。
收到报文但不完成请求	归属匹配段的偏移、期望 Hex 和掩码是否正确。
提示协议失败	成功匹配段是否把异常码当作成功码，或设备是否真实返回错误状态。
校验失败	算法、计算起点、计算长度、校验值偏移和字节序是否与协议一致。
变量值错位	有效载荷偏移和长度是否正确，变量地址是否误按完整帧计算。
数值明显异常	变量数据类型、字节序、数组长度、字符串编码和表达式是否正确。
写入模板无效	${value} 是否恰好出现一次，其余字符是否为偶数长度的有效 Hex。
生成协议按钮不可用	最近一次操作是否成功且包含实际发送 Hex；读取或等待响应命令还必须包含完整响应 Hex，仅发送结果只能生成写入仅发送命令。
原协议缺失或结构损坏	调试页会从空白的当前协议对象生成，不要求先修复旧内容；应用前仍必须完成完整复核并通过后端实发样本验证。
协议草稿样本验证失败	根据错误检查命令名称、完整请求、写入值范围、校验算法与范围、分帧长度或边界、归属段和成功状态；修改后点击“重新生成”。
完整复核提示生成命令已删除	本次实发样本对应的生成命令已被删除；保留该命令并重新复核，或者返回草稿页重新生成。系统不会改用相邻命令验证。
自动归属匹配为空	是否至少有 2 个同请求、同响应长度的样本；稳定字节是否全部落在有效载荷或成功状态范围内。必要时按协议手册手工添加归属段。
应用协议失败	当前账号是否有设备更新权限，设备是否仍存在，以及其他页面是否正在修改同一设备；重新获取设备状态后再生成和应用。
TCP 服务端无法调试	是否已有目标客户端在线，设备 DTU ID 与所选客户端是否一致。
共享通道被拒绝	同一通道下各设备的分帧模式、相关字段和最大包长是否完全一致。

通用的通道、设备和变量维护方法参见采集配置，设备调试入口和安全原则参见设备调试。