Spectrum Socket 业务指令与完成边界
Plugins/Spectrum/Socket/ 是 ColorVision.SocketProtocol 上的五个 ISocketJsonHandler 实现,不是另一套 Socket 服务器。宿主装载 Spectrum 后使用公共分发器;独立程序的 App.Application_Startup 也调用公共 SocketInitializer。监听是否启用、JSON 模式、端口、handler 发现时机、报文分帧、发送记录和重发见公共 Socket 契约,不能仅凭 handler 存在判断客户端可达。
本主题只定义 Spectrum 业务调用。设备、许可证、标定和原生驱动前提见 Spectrum 测量与标定。连接、断开、校零、自动积分和测量都会进入真实设备路径,必须另获现场授权;下面的合成报文只说明数据结构,不是设备联调授权。
开始接入
在已获授权的设备环境中,先确认通信入口,再连接和测量:
- 启动装载了 Spectrum 的 ColorVision,或启动完整依赖齐备的 Spectrum 独立程序。五个 handler 必须在公共分发器创建时已经加载;运行中加入程序集不会自动刷新分发器。
- 在 ColorVision 的 帮助 → Socket 连接管理器 → 服务设置 中配置地址、端口,将 消息解析格式 设为
Json,再启动服务。若服务已经运行,更改配置后须停止并重新启动;具体监听与停止规则见公共 Socket 契约。 - 连接实际监听端点,发送下面的状态请求。收到对应
MsgID和Code = 200表示状态 handler 可达;设备尚未连接时也可以成功查询。 - 准备好设备、许可证和标定后发送
SpectrumConnect,同时查看Code、IsConnected、IsCalibrationReady和CalibrationStatus。需要测量时再调用SpectrumMeasure;校零与自动积分按实际流程选择,不是每次请求都必须执行。
状态查询读取 Manager 属性,不调用设备连接或测量:
{"EventName":"SpectrumStatus","MsgID":"status-1"}若返回 404 和 Handler not found for event: SpectrumStatus,先核对大小写、插件装载与分发器创建时机;若没有响应,先查监听端点、JSON 模式和公共传输层的消息边界。收到业务响应后,再按本页的设备门禁与错误码定位。
请求与五个入口
Params 是字符串。连接请求示例:
{"EventName":"SpectrumConnect","MsgID":"example-1","Params":"connect"}实际路由名是 SpectrumConnect 等连续字符串,不是 Spectrum.Connect。操作参数在 Params,没有 Action 字段。五个 handler 自己构造的响应会设置对应 EventName 并回传请求的 MsgID;它们不验证 Version,也不按请求的 SerialNumber 选择设备。当前 handler 不设置响应的 Version / SerialNumber;不要把它们当作版本协商或设备选择结果。分发前失败的响应另遵守公共 Socket 契约,不能假定它们也具有这些关联字段。
| EventName | 参数、门禁与成功含义 | Data |
|---|---|---|
SpectrumStatus | 读取 Manager 当前属性;200 只表示状态读取成功 | 连接、采集配置及 WindowOpen,不含标定 readiness |
SpectrumConnect | Params 去空白并转小写后,只有 disconnect 进入断开;其他值(包括空值、空串和拼错的值)都进入连接 | IsConnected、IsCalibrationReady、CalibrationStatus |
SpectrumDarkCalibration | 已连接;PerformDarkCalibrationAsync(requireAutomaticControl: true) 要求自动校零参数中所选的 Shutter 或滤色轮可用并执行暗场;成功返回 200 | 未设置 |
SpectrumAutoIntTime | 已连接;TryGetAutoIntegrationTimeAsync 成功得到时间并写回 Manager 后返回 200 | 数值 IntTime |
SpectrumMeasure | 已连接,Manager 再检查标定和采集条件;直接等待本次 MeasureAsync 的结果,不从窗口列表找最新记录 | 本次结果的色度等字段,以及响应构造时 Manager 的 IntTime |
除 SpectrumConnect 外,当前四个 handler 不使用 Params。SpectrumConnect 不是严格的参数校验 API,不能用未知参数探测能力而假定不会连接设备。
SpectrumStatus.Data 完整字段为 IsConnected、IntTime、Average、SerialNumber、EnableAutodark、EnableAutoIntegration、EnableAdaptiveAutoDark、MeasurementInterval、MeasurementNum、WindowOpen。这些属性顺序读取,不持有设备操作锁,不是一次测量的冻结快照;WindowOpen 仅检查 MainWindow.Instance != null,不表示窗口可见、设备就绪或测量成功。
连接、标定与遮光控制
连接响应 Code = 200 需要 Connect() 返回 1 且 Manager 为已连接,但不要求 IsCalibrationReady。因此必须把“通信已建立”和“可以测量”分开;连接时读到 readiness 也不能替代后续测量入口的再次校验。SpectrumStatus 没有 readiness 字段,标定门禁及修复依据见 Spectrum 标定契约。
断开响应按 Disconnect() 返回值决定 200 或 -2。Manager 的断开路径即使原生关闭/释放失败也会清空本地连接状态;释放失败还可能隔离原生会话。Data.IsConnected = false 不能单独证明驱动释放成功,必须结合 Code / Msg 和设备检查。
Socket 校零不回退到人工遮光,复用 Spectrum 的 Shutter/滤色轮控制约定。Shutter 模式按 OpenForDark 及两条指令配置完成遮光、采暗数据、恢复通光;默认 a → 采暗数据 → b,可反向配置。turn on / turn off 按实际发送的 a/b 校验,不能代替实际光路验收。选择滤色轮时,Manager 读取当前测量孔位、切到已配置的遮光孔位,暗场结束后在 finally 中恢复原孔位;临时切换不会改变当前标定组。所选控制器缺失、遮光切换失败、原光路恢复失败或 native 返回失败都会使指令失败;收到失败响应不能据此认定光路已经恢复。
设备锁与合作式取消
Connect / Disconnect 使用 RunExclusive 等待设备门禁;当前连接 handler 没有传入取消令牌或设置操作超时。它不是“设备忙就立即拒绝”的路径,连接返回 -4 对应的是 OperationBusy 原生会话占用/隔离结果。
校零、自动积分和测量使用 TryRunExclusiveAsync 的 WaitAsync(0, token),拿不到设备门禁就拒绝,不排队另一项原生操作。测量在服务停止接收请求时也可返回 IsBusy,handler 将其转成 -4。UI、Job 和 Socket 应复用这些 Manager 入口,不自行创建、释放或缓存光谱仪句柄。测量的设备锁覆盖采集阶段,捕获完成后才在锁外检查取消并保存结果;这不是覆盖数据库保存与响应发送的整请求锁。
三个耗时 handler 同步等待异步 Manager API,并分别建立校零/自动积分 30 秒、测量 60 秒的 CancellationTokenSource。这是合作式取消触发时间,不是响应或设备停止的硬截止。 native 同步调用不接收该令牌,快门或滤色轮的恢复也不会被它强制中断:
- 校零在 native 暗场调用前检查取消,调用后还等待所选遮光控制器恢复,但没有最终再次检查令牌。自动积分只在进入设备工作时检查取消,之后的 native 自动积分、可选同步频率调整和
IntTime写回没有最终取消检查。两者都可能超过30秒后仍返回200。 - 测量有多个取消检查点,成功捕获后、保存结果前还会检查一次。只有检测到取消并抛出
OperationCanceledException才走取消响应;失败捕获也可能直接走业务失败。同步保存阶段不接收令牌,因此在该阶段触发60秒取消仍可能提交结果并返回成功。 - 请求超时、客户端断开或
-4响应都不是设备安全停止证明。已经执行的暗场、快门、滤色轮或其他设备动作不会因令牌取消而自动回滚;设备锁等工作返回后才释放。
自动积分成功表示得到并写回一个时间,不表示可选同步频率调整也成功:TryGetAutoIntegrationTimeAsync 对后者失败只记录警告,仍可使用原自动积分值返回 200。
测量返回字段与持久化
SpectrumMeasureSocketHandler 使用 SpectrumMeasurementResult.Result,不会监听 UI 集合来推断完成。成功路径由 ViewResultManager.SaveMeasurement 在同一 SQLite 事务内插入光谱结果和 SpectrumMeasurementProfile,提交后发布 UI 投影,再返回结果;响应成功不保证界面已经刷新。WPF 跨线程投影通过 Dispatcher 排队,数据库代次变化也可能让该次投影被跳过。
| Data 字段 | 当前来源与 JSON 类型 |
|---|---|
Lv | ViewResultSpectrum.Lv,字符串;由安全亮度值 ToString() 生成,不是 JSON 数值 |
x / y / u / v | fx / fy / fu / fv,数值 |
CCT / Duv | 共用 Robertson 1968 从 CIE 1931 xy 计算,数值或 null;Duv 使用 CIE 1960 UCS |
DominantWavelength / ComplementaryWavelength | 主波长与补色波长分别输出正数 nm,白点/无效色度为 null;紫红色只有补色波长 |
WavelengthStatus / TemperatureStatus | 共享色度计算的枚举状态名称字符串,含有效、白点、补色及不可用原因 |
PeakWavelength / HalfBandwidth | fLp / fHW,数值 |
ColorPurity / Ra | D65 参考白点的兴奋纯度(0~1)、CIE 13.3 Ra,数值或 null |
IP | 字符串,带 % 后缀 |
Blue | 字符串,比例乘 100 后取两位小数的文本,不带 %;分母为零时为 "0" |
IntTime | 响应构造时的 SpectrometerManager.IntTime,数值;不是从本次结果的不可变快照读取 |
以下是字段类型示例,数值为合成数据;字符串由当前实现的 ToString() 产生,不能把示例的小数格式当成跨区域设置的格式保证:
{
"EventName": "SpectrumMeasure",
"MsgID": "example-2",
"Code": 200,
"Msg": "测量完成",
"Data": {
"Lv": "123.45",
"x": 0.312, "y": 0.329, "u": 0.198, "v": 0.468,
"CCT": 6504, "Duv": 0.003,
"DominantWavelength": 530.2, "PeakWavelength": 531.5,
"HalfBandwidth": 2.1, "ColorPurity": 0.85, "Ra": 95,
"IP": "85%", "Blue": "12.5", "IntTime": 150.5
}
}测量失败或取消不等于数据库完全未写入:采集已开始但成功路径未完成时,Manager 的 finally 会尽力单独保存失败/取消的测量画像,保存失败仅记录日志。事务回滚的范围是那次数据库事务,不会撤销此前的设备动作;结果有效点数、显示集合上限和 CSV 见 Spectrum 结果契约。
业务错误与窗口边界
| Code | 当前 handler 的判据 |
|---|---|
200 | 本指令成功路径;状态查询和连接的成功都不代表可测量 |
-2 | 校零/自动积分/测量入口观察到未连接,或连接/断开返回失败 |
-3 | 校零非成功/非 Busy 结果、自动积分没有返回值,或测量 IsSuccess 为假/结果为空;具体失败原因看 Msg |
-4 | 三个耗时操作未进入设备门禁或捕获到取消异常;测量服务暂停也映射为忙;连接另用于原生会话占用/隔离 |
-99 | handler 的 try/catch 捕获到的其他异常;不能据此保证所有上游异常都转成此码 |
MeasureAsync 会把部分内部异常转成失败结果,因此数据库或采集异常可能表现为 -3,不能只检查 -99。公共分发/解析错误不属于上述业务码表,按公共 Socket 契约处理。
业务 handler 不要求 MainWindow 已打开,不等于“关闭独立程序后仍提供后台服务”。Spectrum 窗口关闭会暂停接收新测量、等待在途路径并尝试断开设备;独立 WPF 程序也没有在 App.xaml 配置关闭窗口后常驻的模式。宿主仍存活且入口已启用时,可以在没有 Spectrum 窗口的情况下重新连接并操作,但仍须满足设备、标定和所选自动遮光控制器门禁。
实现与验证范围
五个 handler 的 Handle 定义参数和返回码;设备互斥、标定检查和取消观察点在 SpectrometerManager,快门确认在 Configs/ShutterController.cs,滤色轮位置确认在 Configs/FilterWheelController.cs,结果事务在 Data/ViewResultManager.cs,字段格式在 Models/ViewResultSpectrum.cs。扩展指令时保留这些责任边界,传输注册只依公共 Socket 的当前发现规则。
验收分别核对 handler 字段及异常、忙与取消时序,以及经授权的快门恢复、原生长调用和进程生命周期。
