Team.LightControl

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

当前版本为 1.0.6，新增实机验证型号 KDC-24V120W-4T（4 通道、小写回读/仅应答双模式探测）与 KDCC-24V300W-2T-4X（2 通道、无回读、连接探测写 0），并保留 KDC4-24V120W-8T 支持、实机修正的 KCS 写应答校验（通道字母与 ! 序列均接受）、仅亮度直接输出写（连接后即可“打开全部/关闭全部”）及 COM 口扫描示例。

包结构

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

使用

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 型号：

新型号使用同一个驱动入口（串口参数以型号实际为准）：

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

GlobalChannelUpdate 的亮度/开关可以单独提供，未指定字段保持原状态。亮度为设备原始值，范围按型号见上表（多数 0..255，KDCC-24V300W-2T-4X 为 0..1000），越界批次被拒绝且不发送命令。连接后输出状态可能未知；KCS 首次设置请同时明确提供亮度和开关。开启尚无已知目标亮度的通道会返回 UnknownState，不会默认点亮为 100。

UI 可按全局通道号获取该型号的亮度上下限，直接绑定到滑动条等控件的 Min/Max——不同量程的控制器注册在同一服务时各自返回自己的量程，互不影响：

GlobalChannelInfo info = service.GetChannelInfo(10);
brightnessSlider.Minimum = info.MinimumBrightness;   // 0
brightnessSlider.Maximum = info.MaximumBrightness;   // 多数型号 255；KDCC-24V300W-2T-4X 为 1000
// info.ControllerId / info.ChannelIndex / info.Model 也可用于界面标注与诊断。

GetChannelInfo 只依赖注册信息，无需连接即可调用；未注册的全局通道号抛出 KeyNotFoundException，与 GetSnapshot 一致。

关闭 KCS 通道会关闭输出并保留本会话的目标亮度，再次开启恢复该目标。原型号发送记忆亮度加 F 后缀，KDC4-24V120W-8T 写入亮度 0000。仅亮度的变更视为直接输出写：大于 0 立即点亮、0 熄灭，连接后无需先建立开关状态即可“打开全部（设亮度）/关闭全部（写 0 或 enabled=false）”，SetBrightnessAsync 连接后直接可用。关闭状态下只更新目标亮度而不点亮，需同时传入 enabled=false 与新亮度。断开、重连或不确定写入会使缓存失效，重新应用完整目标状态。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 已实机验证（COM3，串口 19200 8N1）：单通道亮度指令为 SA0200#，不附加 T/F（实测附加 T/F 被设备忽略、输出不变），成功应答为通道字母（如 A）；批量应答为逐子命令的通道字母序列，例如 SA0050#SB0100# 期望 AB。写应答校验与型号无关：逐子命令的通道字母序列与逐命令 ! 序列（如 !!）整批一致即通过，兼容手册固件与实测固件，型号枚举仅区分命令格式与通道数。连接探测使用 SRA#，亮度 100 的应答为 A0100。该实机回通道字母——若按手册仅匹配 !，设备实际已执行成功但驱动会判定 InvalidResponse 并断开会话，导致后续全部读写以 NotConnected 失败。零亮度熄灭、关闭期间保留目标亮度和开启恢复均已实机验证。当前未提供 SM0001#、SM0000#、SRM# 触发电平设置/查询接口。

KDC-24V120W-4T 已实机验证（COM2，串口 9600 8N1）：仅亮度协议，写命令 S<字母><DDDD>#（如 SA0255#），批量应答为通道字母序列（SA0255#SB0180#SC0120#SD0060# 期望 ABCD），单命令期望 A。回读命令为逐通道 S<字母>#（如 SA#），应答 5 字节小写字母 + 4 位十进制亮度（a0100 即通道 A 亮度 100），逐通道独立、幂等、不改输出；不支持多通道合并读（SAB# 无应答）。实测注意两点：其一，该固件存在“完整回读”与“仅应答”两种模式，会随命令交互切换（触发规律未完全确定，且重开串口后保持）；仅应答模式下 SA# 只回单字节大写 A——驱动探测两种应答均接受，仅应答按“设备在线、亮度未知”处理（启用通道需显式提供亮度），写路径不受模式影响。其二，设备对流式解析器外的杂帧会回伪应答（如对 TSD 帧 #4100016 回 #4107B63），勿向该设备发送未实测的帧格式；多协议扫描工具应让 KCS 档案先于 TSD 档案命中。其三，该固件对超出额定量程（0..255）的写命令同样应答，但 SDK 按型号上限拦截、不外发——各型号量程相互独立，勿以其他型号（如 KDCC 的 0..1000）的上限测试或配置本型号。

KDCC-24V300W-2T-4X 已实机验证（COM1，串口 19200 8N1）：2 通道（仅 A/B），仅亮度协议，写命令同上，应答为逐命令 !（SA0123#SB0045# 期望 !!）；T/F 后缀与一切读取/查询命令（含小写变体）均无应答，无效命令也不回应答。因此该型号无法只读探测：连接探测采用全通道写 0（SA0000#SB0000#，应答 !!），确认设备在线并建立确定的全灭初始状态——这是该固件下唯一不点亮光源的设备确认方式，连接即熄灭该控制器全部通道。亮度量程实测 0..1000：SA1000# 应答 !、SA1001# 起静默拒绝（面板满量程显示 10000，与串口值疑似 1:10 换算）。手册的 S100T150FC# 逐通道 <值><T|F> 全帧格式（含字面 C、去校验码及 XOR/求和校验码变体）实测均无应答，该固件不支持；开关语义由 SDK 软件记忆亮度实现（关闭写 0、开启恢复目标）。

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

ConnectAsync 会进行协议探测（KCS 回读型号为只读探测；KDCC-24V300W-2T-4X 无回读，探测为全通道写 0），探测成功后才就绪。配置保存、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、9600、38400、57600、115200（8N1、无流控）探测 KCS 和 TSD，最多并行扫描 4 个端口。KCS/TSD 回读型号仅发送通道 1 亮度读取指令；KDCC-24V300W-2T-4X 无回读，其探测档案会向该控制器全通道写 0（熄灭）以确认在线，且排在各只读档案之后。

# 默认扫描，单次打开/查询超时 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,2400,4800 --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.6/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。