SECP 驱动功能设计
SECP 二进制帧 TCP 协议接入 · 位号表自动重建 · 运行期自动建点
SECP 驱动用于接入支持 SECP 协议的设备——主要是 PCS-200 / PCS-600 / LCS-300 PLC 及 OptiEdge 边缘产品。SECP 是一种基于原始 TCP Socket 的二进制帧协议，平台作为客户端主动连接设备，通过自定义二进制报文读写数据。
不同于基于文本（如 HTTP/MQTT）的协议，SECP 直接操作字节流，帧由固定头部（版本+密码+命令类型+索引）+ 变长数据组成，解析必须精确到字节。
| 属性 | 值 | 说明 |
|---|---|---|
| 驱动名称 | secp | SPI 注册名 |
| 版本 | V 1.0 | getDriverVersion() |
| 接入模式 | EMBEDDED | 内嵌于平台主应用 |
| 传输方式 | 原始 TCP Socket（NIO 阻塞模式） | java.nio.channels.SocketChannel |
| 通信模型 | 轮询（虚拟线程读循环） | 带 label 变更检测 |
| Web 接口 | 1 个 | 点位比对检测 |
| 定时任务 | 1 个 | 每 4 秒心跳+读触发 |
| 适用设备 | PCS-200/600、LCS-300、OptiEdge | 两类协议版本 |
每帧由固定头部和变长数据组成。头部各字段含义：
2 字节"] PWD["密码
32 字节"] CMD["命令类型
4 字节"] IDX["索引
2 字节"] DATA["数据
变长"] end V --- PWD --- CMD --- IDX --- DATA style V fill:#e8f0fe,stroke:#007aff,color:#1c1c1e style PWD fill:#f0f0f5,stroke:#5856d6,color:#1c1c1e style CMD fill:#fff4e8,stroke:#ff9500,color:#1c1c1e style DATA fill:#e8f8f0,stroke:#34c759,color:#1c1c1e
| 字段 | 长度 | 说明 |
|---|---|---|
| Version | 2 字节 | 协议版本（V1.0=0x0a 0x00，V2.0=0x14 0x00） |
| Password | 32 字节 | 固定全零密码 |
| CmdType | 4 字节 | 命令类型（1/2/3） |
| Index | 2 字节 | 序号 |
| Data | 变长 | 负载 |
| CmdType | 用途 | 方向 |
|---|---|---|
| 1 读位号表 | 读取设备所有位号（tag）的元信息（id/数据类型/长度/名称） | 平台 → 设备 |
| 2 读数据 | 读取位号当前值 | 平台 → 设备 |
| 3 写下载 | 向位号写入控制值 | 平台 → 设备 |
对应头部常量：HEAD_10_1/2/3（V1.0）与 HEAD_20_1/2/3（V2.0）。
| 维度 | V1.0（0x0a 0x00） | V2.0（0x14 0x00） |
|---|---|---|
| 适用设备 | PCS-200 / PCS-600 / LCS-300（传统） | OptiEdge（新一代） |
| 写方式 | 仅单点写 | 批量写 |
| 头部常量 | HEAD_10_* | HEAD_20_* |
驱动根据设备类型/连接情况使用对应版本的头部，V2.0 设备支持批量写，效率更高。
实例管理 · 校验 · 写 · 建点"] CH["SecpChannel
每实例 · SocketChannel · 帧收发"] AR["AssembleRequestBody
帧编码/解码"] end subgraph 接口/任务 API["PointDetectionApi
点位比对"] T["CheckInstanceAliveTask
cron 0/4"] end A --> M M --> CH CH --> AR AR <-->|"二进制帧"| DEV["PCS/OptiEdge 设备"] API --> M T -->|"心跳+读触发"| M style A fill:#e8f0fe,stroke:#007aff,stroke-width:2px,color:#1c1c1e style M fill:#f0f0f5,stroke:#5856d6,stroke-width:2px,color:#1c1c1e style CH fill:#fff4e8,stroke:#ff9500,color:#1c1c1e
SECP 设备的位号表（tag table）可能因工程变更而变化。驱动通过 8 字节 label 检测位号表是否变化——每次读取前先比对 label，若变化则重建位号表（逐个 tag 表读取），再读值。
每个实例运行期间首次读取到位号表时（instancePointHasCreate），驱动会自动把设备的位号创建为平台点位。这意味着无需手工配置点位——设备有什么位号，平台就自动建什么点。
运行期间位号不可修改——一旦建点，本次运行周期内点位固定。位号表变化需触发 label 检测重建。
设备返回的数据按 dataType 码解析：
| 类型码 | 平台类型 |
|---|---|
1 | bool |
2-10 | int |
11 | float |
20 | string |
| 其他 | double |
下行控制（issuePointValueBatch → dataDownload）按点逐个发送写下载命令（CmdType 3），带 writeRetry 重试。返回码 1 表示成功。写值前会做值域校验（checkValueLength）。
SECP 提供 pointDetection API，对比设备实际位号与平台已有点位，返回三类差异：
| 差异类型 | 含义 |
|---|---|
| 平台缺失 | 设备有但平台没建的点位 |
| 设备缺失 | 平台有但设备已删除的点位 |
| 类型不一致 | 两端都存在但数据类型不匹配 |
这是排查「点位对不上」问题的利器，尤其适合设备工程变更后的对账场景。
| 属性名 | 类型 | 默认 | 说明 |
|---|---|---|---|
host | string | 必填 | 设备 IP；与 port 联合唯一 |
port | int | 必填 | 设备 TCP 端口 |
commandInterval | int | 必填 | 位号表读取间隔（毫秒） |
instanceLoopSilenceTime | int | 必填 | 读循环休眠（毫秒） |
readTimeout | int | 500 | 连接超时（毫秒） |
readValueTimeout | int | 必填 | 响应等待超时（毫秒） |
writeRetry | int | 3 | 写下载重试次数 |
host + port 必须项目内唯一。
| 属性名 | 含义 | 说明 |
|---|---|---|
tagName | 位号名 | SECP「位号」；实例内唯一 |
点位唯一码：secp&&{channelId}&&{pointName}。
| 映射路径 | 用途 | 参数 |
|---|---|---|
pointDetection | 比对设备位号与平台点位，返回缺失/多余/类型不一致 | instanceId |
调用路径前缀：POST /driver/api/secp/{mapping}。
| 任务名 | Cron | 频率 | 职责 |
|---|---|---|---|
checkInstanceAliveTask | 0/4 * * * * ? | 每 4 秒 | 建立 TCP 通道、设置状态、读线程死亡时重启 |
host/port 网络可达、防火墙放行。SECP 用原始 TCP，无 Broker。可用 telnet 测试端口连通性。注意 readTimeout（默认 500ms）若设备响应慢可能误判超时，可适当调大。pointDetection API 检查设备实际位号，确认通信正常。dataType 码决定（1=bool、2-10=int、11=float、20=string）。若设备上报的类型码与实际不符，解析会出错。这种情况通常是设备工程配置问题，需核对位号在设备侧的数据类型定义。pointDetection 比对差异，清理平台多余点位、补建缺失点位；③ 注意运行期间位号不可改，可能需重启实例使新位号生效。