LHR.USBLIN 2.1.0

LHR.USBLIN — USB-LIN Box 上位机 SDK

USB-LIN Box 的 C# 客户端库。通过 USB Vendor Bulk 端点与 ESP32-S3 固件 通信，把两路 LIN master 能力封装成强类型 API。

• 目标框架：.NET 10
• 依赖：LibUsbDotNet 2.x（跨平台，Windows / Linux / macOS）
• 协议版本：proto = 3，配套固件 1.3.0 及以上

快速开始

dotnet add package LHR.USBLIN

using LHR.USBLIN;

using var conn = UsbBulkConnection.Open();   // 默认 VID/PID，找不到抛 UsbDeviceNotFoundException
var lin = new LINClient(conn);
lin.CheckProtocol();                          // 校验固件协议版本，强烈建议

lin.Begin(LINChannel.Ch0, 19200, LINNodeVersion.V2_1);

// 下发一帧
lin.MasterRequest(LINChannel.Ch0, 0x3B, LINChecksum.Enhanced, [0x01, 0x02]);

// 读从机回帧
var r = lin.SlaveResponse(LINChannel.Ch0, 0x1B, LINChecksum.Enhanced, count: 8);
if (r.IsSuccess)
    Console.WriteLine(BitConverter.ToString(r.Data!));
else if (r.Error.Has(LINBusError.Timeout))
    Console.WriteLine("从机无响应");

lin.End(LINChannel.Ch0);

Windows 需先装 WinUSB 驱动（Zadig 或 installer/ 里的一键安装器）， 否则 Open() 会找不到设备 —— 见 docs/driver-setup.md。

能做什么

两路通道可用 LINChannel.All 一次操作，固件侧真正并行执行， 墙钟 ≈ 单通道（~10 ms）而非串行两倍。

所有 *All 方法返回长度恒为 LINChannel.Count 的数组，下标即通道号。

两个容易混淆的概念

诊断帧 0x3C / 0x3D 必须用 LINChecksum.Classic（LIN 规范硬约束）。

错误处理要点

LINError 是一个字节的门面，内部分两个互斥码段：LIN 总线错误（00–80，位掩码可组合） 与协议层错误（E0–FF，离散取值）。

if (r.Error.Has(LINBusError.Timeout)) { /* 总线超时 */ }
if (r.Error.Protocol == LINProtocolError.NotInitialized) { /* 通道未 Begin */ }

位判断一律用 Has()，不要对 Error.Raw 直接做位运算 —— 两段共用一个字节，0xE1 & 0x01 非零会产生"状态机错误"的假阳性。

读类命令（SlaveResponse*）不抛 LIN 错误异常，结果放在 LINChannelResult.Error； 写类命令抛 LINCommandException。断线抛 UsbDisconnectedException，可精准捕获触发重连。

仓库结构

src/LHR.USBLIN/          SDK 本体
  UsbBulkConnection.cs     传输层：USB Bulk + 行协议 + 设备发现
  ILINTransport.cs         行传输抽象（便于离线测试）
  LIN/LINClient.cs         命令层：拼命令、解析响应
  LIN/LINTypes.cs          LINChannel / LINError / LINState 等
samples/                 6 个可运行示例，从 Ping 到真实总线验收（LinCheck）
tests/
  LHR.USBLIN.UnitTests/    94 个离线单测（无需设备）
  LHR.USBLIN.Tests/        硬件压测（需真实设备）
drivers/                 WinUSB inf + Linux udev 规则
installer/               Windows 驱动一键安装器
canoe/                   CANoe LIN 从机联调用 LDF
docs/                    详细文档

文档

版本兼容

SDK 与固件的 proto 号必须一致。两者在独立仓库、无法原子发布， 所以连接后应调 CheckProtocol() —— 否则版本错配表现为难以归因的解析错误。

构建

dotnet build LHR.USBLIN.slnx
dotnet test tests/LHR.USBLIN.UnitTests    # 离线单测，无需设备