Team.LightControl

面向 .NET Framework 4.8 和现代 .NET 的光源控制 SDK。使用端只提交全局通道编号；SDK 按控制器实例分组，独立连接并行，同一控制器内按批次互斥执行。

当前版本为 1.0.3，包含 KDC4-24V120W-8T 支持及 COM 口扫描示例，保留 KCS 实测探测应答格式、批量写入及通信超时、取消提示的修复。

包结构

按需安装 1.0.3 品牌包即可，NuGet 会引入同版本的公共依赖。本库没有 WPF、Prism、海康 VM、数据库或配置文件路径依赖。现代 .NET 使用 netstandard2.0 资产；自动验证覆盖 Windows 的 .NET Framework 4.8 和 .NET 10。KDC3-24V300W-8T 已记录实测串口探测应答；其他型号、固件和运行环境仍按现场配置确认。

使用

using Team.LightControl;
using Team.LightControl.Communication;
using Team.LightControl.Drivers.Kcs;

using var service = new LightService();
service.RegisterController(
    controllerId: 1,
    driver: KcsLightController.CreateSerial(
        KcsModel.Kdc12V60W4T,
        new SerialConnectionOptions("COM3", baudRate: 19200)),
    mappings: new[]
    {
        new ChannelMapping(10, 0), new ChannelMapping(20, 1),
        new ChannelMapping(30, 2), new ChannelMapping(40, 3)
    });

var connections = await service.ConnectAllAsync(cancellationToken);
// 必须检查每个连接的 IsSuccess / Error。
var result = await service.ApplyAsync(new[]
{
    new GlobalChannelUpdate(10, brightness: 120, enabled: true),
    new GlobalChannelUpdate(20, brightness: 130, enabled: true),
    new GlobalChannelUpdate(30, brightness: 140, enabled: true),
    new GlobalChannelUpdate(40, brightness: 150, enabled: true)
}, cancellationToken);

// result.IsSuccess、Channels 和 Controllers 提供逐通道结果与命令数、耗时。
await service.SetEnabledAsync(10, false, cancellationToken);
await service.DisconnectAllAsync(cancellationToken);

同一个 LightService 继续注册其他品牌、其他连接上的设备即可。业务代码仍然只使用全局通道编号。实际通道索引统一从 0 开始；驱动负责转换协议地址。

当前源码支持的 KCS 型号：

新型号使用同一个驱动入口，串口参数为 19200、8N1、无流控：

using var driver = KcsLightController.CreateSerial(
    KcsModel.Kdc4_24V120W8T,
    new SerialConnectionOptions("COM3", baudRate: 19200));
// 注册到 LightService 时按需映射实际通道索引 0..7。

GlobalChannelUpdate 的亮度/开关可以单独提供，未指定字段保持原状态。亮度为设备原始值，当前型号范围 0..255。连接后输出状态可能未知；KCS 首次设置请同时明确提供亮度和开关。开启尚无已知目标亮度的通道会返回 UnknownState，不会默认点亮为 100。

关闭 KCS 通道会关闭输出并保留本会话的目标亮度，再次开启恢复该目标。原型号发送记忆亮度加 F 后缀，KDC4-24V120W-8T 写入亮度 0000；新型号关闭期间单独修改亮度仅更新软件目标，发送的输出亮度仍为零，开启时恢复最新目标。断开、重连或不确定写入会使缓存失效，重新应用完整目标状态。TSD 保留原工程的开关命令和“开启后设置亮度”顺序。

批次语义

1. 一次 ApplyAsync 表达一个明确的业务批次。重复编号、未知通道、越界亮度或空变更会拒绝整批，且不发送命令。
2. 按控制器实例分组，独立端点异步并行；同一控制器的整个批次互斥，命令不会被其他批次穿插。异步锁不承诺严格 FIFO。
3. KCS 默认将请求涉及的通道按索引排序，把各个以 # 结尾的子命令拼接后一次写入。支持全部通道、任意子集及混合开关，不修改未参与请求的通道；批量写入并不保证设备内部同时更新各通道。
4. KCS 可以设置 enableNativeFullFrame: false 改为逐通道顺序执行；TSD 使用逐通道顺序执行。
5. 单个控制器出现错误后停止该组剩余操作；其他控制器继续完成。业务收到全部组的结果后再决定是否拍照。
6. 取消以逐通道结果返回：保留已确认项，未开始项为 NotExecuted，在途写入不确定时为 Unknown。取消和跨设备失败不会自动回滚已完成操作。
7. 成功注册后服务拥有驱动。成功注册前校验失败的驱动仍由调用方释放。所有注册、映射修改和注销仅允许在服务无在途操作时执行；服务释放会取消在途驱动操作并关闭资源。
8. 全局编号不自动重新分配。当前每个物理端点只允许注册一个控制器，拒绝重复 COM 口/端点；多地址共享总线调度留待后续型号接入时实现。

逐通道结果包括 Confirmed、Failed、PartiallyApplied、Unknown、NotExecuted。CommandAcknowledged 仅表示命令确认；不代表逐通道回读或光学测量。TSD 输出开关状态不会通过亮度是否大于零来推断。

多个控制器的并行不保证硬件同步点亮。拍照流程共享通道时，业务需从应用光源到采图完成持有相应的资源占用，并在全部必要通道成功及稳定时间满足后拍照。

通信和设备验证边界

传输由 ICommandTransport 隔离。串口使用标准 System.IO.Ports，有界读取在后台执行；完整帧到达立即返回，无 100ms 空闲分包等待。TCP 使用异步流收发。超时、在途取消、截断/异常响应会关闭会话，防止迟到回复被下一条请求使用；不会自动重试写命令。

KCS 所有型号默认按 5 字节探测应答解析，兼容实测的 A0073（通道字母在首位，末 3 位表示亮度 73）和旧格式 ?ADDD（通道字母在次位）。KDC3-24V300W-8T 的实测串口配置为 19200 8N1，对 SRA# 返回 A0073。使用旧 7 字节格式的固件可通过构造函数显式指定 readResponseLength: 7。TSD 使用 8 字节 ASCII 帧和动态 XOR 校验，写应答要求匹配命令回显。不同型号与固件的具体格式以现场手册和真实报文为准。

KDC4-24V120W-8T 按手册第 7–8 页接入：单通道亮度指令为 SA0200#，不附加 T/F，成功应答严格为 !；批量应答按子命令数匹配，例如 SA0050#SB0100# 期望 !!。连接探测使用 SRA#，亮度 100 的应答为 A0100。其他 KCS 型号继续匹配通道字母应答（如 AB）。本型号尚未实机验证；手册存在型号名称及示例应答数量不一致，现场需核对 ! 应答、零亮度熄灭和恢复目标亮度的行为。当前未提供 SM0001#、SM0000#、SRM# 触发电平设置/查询接口。

内部通信超时会报告包含时限的明确错误信息，外部取消保留独立错误码，原始异常保存在 InnerException。回归测试分别验证内部超时和主动取消，避免把超时误读为用户取消。

ConnectAsync 会进行只读协议探测，探测成功后才就绪，不主动设置设备输出。配置保存、UI 数据绑定、产品配方和参数审计由应用层负责。

构建、测试和打包

Windows、.NET SDK 10.0.402（同补丁系列可滚动）。测试和示例包含 net48 与 net10.0 两个目标。

dotnet build Team.LightControl.sln -c Release
dotnet test tests/Team.LightControl.Tests -c Release
dotnet run --project samples/Team.LightControl.ConsoleDemo -c Release -f net10.0
./scripts/Pack.ps1

模拟示例使用真实驱动和虚拟传输，不连接硬件。Pack.ps1 默认从 Directory.Build.props 读取统一版本，依次构建、执行双框架测试、生成四个 NuGet 包，检查嵌入图标，并在隔离缓存中通过纯 PackageReference 消费验证，最终生成 SHA256 清单和 ZIP。不会上传包或使用发布凭据。

输出目录：artifacts/packages/。可以直接将此目录添加为本地 NuGet 源。需要使用的品牌包及其公共依赖都要上传到私有源。

查找光源控制器的 COM 口

samples/Team.LightControl.PortScanner 是独立的轻量控制台示例，支持 .NET Framework 4.8 和 .NET 10。它枚举本机所有 COM 口，默认在 19200、8N1、无流控下探测 KCS 和 TSD，最多并行扫描 4 个端口。仅发送 SDK 的通道 1 亮度读取指令，不设置亮度、开关或触发电平。

# 默认扫描，单次打开/查询超时 500 ms
dotnet run --project samples/Team.LightControl.PortScanner -c Release -f net10.0

# 指定多个波特率，并增大慢设备的等待时间
dotnet run --project samples/Team.LightControl.PortScanner -c Release -f net10.0 -- --baud-rates 19200,9600,38400,57600,115200 --timeout-ms 1000

扫描结果输出匹配端口、波特率、协议及通道 1 当前亮度；占用/无法打开与未识别的端口会分别提示。扫描前先退出占用串口的控制软件，扫描结束或按 Ctrl+C 取消后自动释放端口。双击 EXE 运行时会等待按键关闭结果窗口，在已有终端中运行则自动退出；自动化调用可加 --no-pause 明确禁止等待。KCS 的多个 8/16 通道型号共用读取协议，读取成功无法确定具体型号、通道数或写入应答格式，请结合铭牌选择 KcsModel。TSD 与其他固件也应结合实机确认；该工具只识别当前 SDK 支持的查询协议。

使用 --help 查看参数。退出码：0 找到设备，1 无串口或未找到设备，2 参数/运行错误，130 用户取消。

发布独立单文件 EXE

./scripts/Publish-PortScanner.ps1
# 也可按目标电脑架构指定 -Runtime win-x86 或 -Runtime win-arm64。

默认输出 artifacts/port-scanner/1.0.3/win-x64/Team.LightControl.PortScanner.exe，同级版本目录还包含分发 ZIP 和 SHA256 清单。只需复制这个 EXE 到目标 Windows x64 电脑，无需携带 DLL 或单独安装 .NET 运行时。单文件使用 .NET 10 自包含发布，包含串口依赖和原生运行时；原生库在启动时自动释放到系统临时目录，详见 Microsoft 单文件部署说明。

普通 dotnet build 仍保留 net48/net10.0 的开发输出；用于分发的单文件 EXE 请使用上述发布脚本生成。

包图标

四个包共享根目录的 icon.png，通过 PackageIcon 指向包内图标，无需外部图片服务。图标为 128x128 像素、透明背景 PNG，小于 1MB，符合 NuGet 官方图标规范。打包验证会检查四个包的图标声明、PNG 格式、尺寸、文件大小和内容一致性。

原图由内置 imagegen 生成，保存在 assets/branding/icon-source.png；完整提示词见 assets/branding/icon-prompt.txt。Windows 下可运行 ./scripts/Export-PackageIcon.ps1 重新导出 128x128 图标。只将小尺寸图标嵌入 NuGet 包。

实施计划见 docs/IMPLEMENTATION_PLAN.md，原项目接入说明见 docs/MIGRATION.md。