本地通用传感器与模板
“模板 → 传感器模板”、通用传感器设备面板和流程节点的模板入口均使用数据库中已启用的 50 / Sensor.Default。打开界面只读取现有字典。历史设备保留原有类别配置,使用默认组模板前应将传感器类型设为 Sensor.Default。通过数据库迁移保留历史模板与指令数据。
新建 Sensor.Default 时可按业务选择内置基础模板,首批包含 PG 上下电、设备已有图片切换和 SA 灯控共 13 项。预览说明用途、应选择的“本地设备 → 本地通用传感器”流程模块、适用协议,并显示可读的发送和预期返回;[LF] / [CR] 明示结束符。展开“编辑指令与通信参数”可修改内容或增加指令。PG 文本协议、GECS 帧协议与 SA 灯控必须按实际设备匹配;切图预设要求设备已存在同名图片,SA 开灯值需按控制器协议调整。预设源于已有指令格式,不代表所有型号的真机验收;设备专用的寄存器写入不作为通用预设。
基础示例保存在随软件交付的 Assets/Templates/BasicTemplates.db,以只读模式打开,按模板代码查询。它只提供创建来源;选择、预览和取消不向用户库写入模板或指令。用户点击创建后,按原结构将独立副本保存到 MySQL,之后编辑该副本;软件升级可替换基础库,不覆盖已经创建的用户模板。新建默认来源仍读取该类型已有的字典默认值,缺失时在草稿中使用默认指令;复制与文件导入保留全部指令及 ValueB,清除源记录 ID 并在保存时映射目标字典。模板、指令和必要的字典修复在同一事务中写入,成功提交后更新字典缓存。基础库缺失、损坏或版本不兼容时显示提示,默认、已有副本和文件来源仍可使用。
维护基础库时修改 Engine/ColorVision.Engine/Assets/Templates/BasicTemplates.json,运行 python Scripts/build_basic_templates.py 并同时提交生成的 .db。通用表保存模板代码、业务说明、模块/设备指引及带版本的 JSON 参数,各模板实现负责解释参数;普通参数与 JSON 模板已由共享基类接入 ITemplateCreatePresetProvider,传感器保留专用指令载荷。项目复制 .db 到构建及 publish 输出,安装项目需包含相同路径;主发布入口在构建后核对 SQLite 完整性及安装目标,更新包沿既有输出文件收集规则包含它。现场核对 MySQL 保存及设备通信。
传感器面板左侧并排提供紧凑的“打开/关闭”按钮和齿轮配置图标,齿轮与属性页“修改配置”打开同一个单页窗口,无需管理员权限。窗口同时管理 ConfigSensor 的名称、SN、传感器类型、自动连接、IsNet、Addr、Port 和 DisplaySensorConfig 的“使用本地传感器”、连接超时及本地串口参数。网口显示 IP/主机名及端口,串口显示串口选择及波特率;本地连接参数仅在本地模式显示,数据位、校验位、停止位、DTR/RTS 仅在串口模式显示。IP 输入复用共享四段编辑器,同时保留主机名/IPv6 文本模式。
窗口编辑两个对象的副本,取消不修改当前配置;本地参数校验通过后,确定才写回,保留原对象及订阅者。本地开关和本机连接参数通过 DisplayConfigManager 保存,设备参数沿原链路写入资源数据库。只改本机选项时,仅保存本机配置,服务继续运行。两类参数都有改动时先保存本机配置,再保存设备资源。“使用本地传感器”默认开启;新配置及缺少 UseLocalSensor 字段的旧配置使用本地,已明确保存的开启或关闭值继续保留,用户可手动关闭以使用服务通信。DeviceSensor.Local.cs 负责入口和状态,LocalSensorSession 持有单一连接并串行执行整组模板。切换开关只影响下一次打开,当前连接要先关闭。设备面板仍显式管理连接;流程中的 LocalSensorNode 及启用本地模式的旧传感器结点在执行指令前检查连接,未连接时尝试打开。连接超时取本机显示设置的 ConnectTimeout(默认 3000 ms),属于建立连接阶段;发送及回包共用模板 Timeout,结点不再另设本地操作超时。模板 Delay 是每条指令成功后的等待,排队与延时仍可被关闭或流程停止取消。地址、端口或波特率仍取原设备配置,本地打开时将它们与本机的数据位、校验位、停止位、DTR/RTS 设置合成连接快照。
传感器类型下拉显示标准类型的 Code 和名称,也显示该设备当前保存的旧类型值。选择标准类型后可调用默认组模板,空白类型不能提交。
本地连接打开后,更改端点、串口参数或传感器类型须关闭并重新连接,设备面板和流程才会按新配置发送指令。
LocalSensorNode 只配置设备代码和参数模板,固定执行模板;结点摘要显示模板名称。自动连接失败会让当前结点失败,不发送指令;通信失败不会在当前执行中自动重连或重发,后续再次执行时可尝试连接。旧 CommonSensorNode、TempCommonSensorNode、RealCommonSensorNode 在设备启用本地模式时转到同一会话;模板结点沿用模板,旧指令结点沿用其指令参数。旧结点转发时跳过原结点的等待超时,远程模式保留原 MQTT 路径。FlowLocalExecution 按后端注册,传感器与光谱仪可以同时使用;流程结束时共享的 FlowRuntimeResources.StopToken 取消正在进行的传感器操作,包括自动连接。
“通用传感器-指令”(RealCommonSensorNode)保留用于加载、编辑和运行已有流程,不提供新建入口;其序列化类型和指令字段保持原样。流程新建菜单中的 PG 控制组位于“传感器 → PG”,完整保留原 PG 子菜单和命令节点。PG 资源开启“使用本地 PG”后,这些旧 PG 节点由独立的本地 PG 适配器接管,见设备链中的 PG 契约;无需改成传感器模板节点。两类设备共享 TCP/串口端点互斥,不能同时占用同一连接。
本地回包按实际收到的字节累积,按原模板预期回包的字节长度收齐后完全匹配,避免将第一段数据当成完整回包。未配置预期回包时接收到模板超时结束,有数据才算成功;超时小于等于零的指令作为仅发送使用。文本支持 ASCII、UTF8、GBK 和旧 UTF7,Hex 使用十六进制字节;单次回包最多 1 MiB。超时、最终回包不符或断线会关闭连接,防止残留回包进入下一条指令;错误保留指令名和已接收数据。完整回包不匹配时按原模板 RetryCount 最大尝试次数重发,小于 1 时执行一次;所有尝试共用一次模板超时。
本地执行直接读取现有 MySQL 传感器模板;数据库结构、导入导出及 ValueA / ValueB 格式保持兼容,内置示例库不参与执行时的模板查询。编辑器使用单指令表单,打开模板默认显示第一条;多条指令全部保留,通过下拉框切换,新增后定位到新指令。括号格式编辑框及“转发送 / 转返回 / 发送回显 / 返回回显”位于发送、返回指令前方,始终显示;可先回显已有指令,编辑可读文本后转入对应字段。发送、返回指令框均为两行高度,长内容在框内滚动。预览位于表单下方,可折叠并记住开关,新配置默认折叠,原字段含义不变。“转换内容”按目标编码同时转换发送和返回,支持 ASCII、UTF8、GBK、旧 UTF7 与 Hex,保持字节及超时、延时、重试次数不变;无法无损转换时保留原内容。旧服务的五段模板按逗号分隔,因此会引入逗号或被重新解释的转义文本的文本转换须保留 Hex。None 是请求调用模板的标记,不可作为新指令的编码选择。转换不使用 ValueB,也不自动把所有模板改存 Hex。
“删除指令”作用于当前指令,左侧模板列表的删除作用于当前模板。标准类型由服务数据库提供,编辑器仅维护其模板和指令。
SensorTemplateRepository 按设备类别和模板 ID 或名称读取原指令,LocalSensorCommand 解析既有的发送、返回、编码、超时/延时、重试次数字段;旧的一至四字段格式使用原服务默认值。执行模板需要连接 MySQL,旧指令结点的直接指令参数不依赖模板库。会话阻止重复本地地址占用,设备入口也检查已知服务占用;服务离线不代表服务已释放连接,已知占用须先由服务关闭。此约束基于本进程会话及服务上报,不能检测其他程序占用的 TCP 连接。
真实设备及串口驱动验收应使用现场连接和模板。
传感器面板的“通信调试”按钮或设备右键菜单“本地通信调试”打开独立窗口,同一设备复用一个窗口。“收发消息”逐条显示发送尝试,默认按指令和尝试次数汇总保留的接收分片。勾选“显示分片”可查看每次读取的时间和字节,未关联指令的接收仍逐条显示。“运行日志”显示连接、执行完成、回包不匹配重试、关闭及错误。每条收发记录包含当时的连接地址、指令名、指令序号、尝试次数、模板编码、字节数、原文和 Hex。列表内容及详情默认显示“可读回显”,沿用模板编辑器的括号字节转换:Hex 中可打印的 ASCII 字节显示为字符,控制字节用名称标识(例如 0D/0A 显示为 [CR][LF],02/03 显示为 [STX][ETX]),其他字节显示为 [FF] 等十六进制标记。文本编码保留解码后的文字,并以同样的标识显示控制字符;未等待指令的数据保留 Hex 原文,回显只按字节转换,不猜测多字节编码。详情可切换“原文”和“十六进制”。汇总行先拼接字节再解码,详情显示分片数量。累计接收显示已收到的数据,完整匹配、回包不符或超时以运行日志为准。发送记录表示已开始发送尝试,写入失败由后续错误日志说明。
窗口支持搜索(包括可读回显及控制字符标识)、发送/接收筛选、自动滚动、JSON 格式化查看、原文与 Hex 复制;回显及格式化只影响查看,复制原文保留原始文本。记录从设备会话创建时开始采集,打开窗口可查看此前记录;关闭窗口只停止刷新,不关闭传感器。每设备最多保留最近 500 条原始记录,每条收发记录及每个汇总行最多保留前 16 KiB,超出时显示原字节数与截断提示,复制也只包含保留部分。“清空”只清除此设备的窗口历史。记录同步写入既有应用日志,随正常诊断反馈收集;窗口历史不另外建库,进程退出后从应用日志排查。服务模式通信仍沿原 MQTT 路径,此窗口仅记录本地 TCP/串口会话。
