README_CN.md

CanKit

CanKit 是一个统一的、跨平台的、支持多厂商的高性能 c# CAN 通信库。

支持通过 Endpoint 字符串或强类型入口打开总线，并在不同适配器上提供尽可能一致的收发、过滤、周期发送、错误帧与诊断体验。

• 适配厂商：vxlApi(Vector), PCAN-Basic (Peak CAN), CANlib(Kvaser), SocketCAN (Linux), ZLG(周立功), ControlCAN(广成，创芯，周立功)

---

下面是一个使用CanKit开发的CAN通信Demo，支持多厂商发送接收，查询连接设备，设置滤波等功能。CAN通信Demo

安装

先添加核心包，再按需选择适配器包：

# Core
dotnet add package CanKit.Core

# Adapters（按需选择）
dotnet add package CanKit.Adapter.Vector
dotnet add package CanKit.Adapter.PCAN
dotnet add package CanKit.Adapter.Kvaser
dotnet add package CanKit.Adapter.SocketCAN
dotnet add package CanKit.Adapter.ZLG
dotnet add package CanKit.Adapter.ControlCAN
dotnet add package CanKit.Adapter.Virtual

注：驱动/运行库需按各厂商要求单独安装（见下方“适配器说明”）。

特性（Features）

• 高性能与背压
  • 高吞吐流水线，背压友好的异步接口
  • 可配置缓冲容量，避免过载与丢帧
• 统一 API
  • Endpoint 打开或强类型打开；支持枚举 Endpoint
  • 支持经典 CAN 2.0 与 CAN FD 帧类型
  • 同步/异步：Transmit/Receive、TransmitAsync/ReceiveAsync、GetFramesAsync（.NET 8+）
  • 事件：FrameObserved、ErrorFrameReceived、BackgroundExceptionOccurred
• 定时与模式
  • 经典/FD 位时序配置；支持段参数（Tseg1/Tseg2/Brp 等）
  • 工作模式：正常/只听/回环（取决于设备能力）
• 过滤器
  • 统一的掩码/范围过滤配置接口
  • 当硬件能力有限时，可启用软件回退
• 周期发送
  • 支持设备上的硬件周期发送（若可用）；否则自动使用软件周期发送
• 诊断与监控
  • 错误帧、总线状态、错误计数、总线利用率（是否可用取决于适配器）
• 运行时选项
  • 异步缓冲容量、接收循环延迟停止、发送重试策略（单次/重试）、启用错误信息等

快速开始

通过 Endpoint 打开，然后发送/接收（示例Endpoint）：

• PCAN: pcan://PCAN_USBBUS1
• Kvaser: kvaser://0 or kvaser://?ch=0
• SocketCAN (Linux): socketcan://can0
• ZLG: zlg://USBCANFD-200U?index=0#ch1
• Virtual: virtual://alpha/0
• Vector: vector://YourAppName/0
• ControlCAN: controlcan://USBCAN2index=0#ch0

发送 & 接收

// 快速上手：打开总线，发送一帧，带超时接收
using CanKit.Core;
using CanKit.Core.Definitions;

// 通过端点打开；在配置器中设置比特率等参数
using var bus = CanBus.Open(
    "socketcan://can0#netlink",
    cfg => cfg.Baud(500_000)); // 经典 CAN 500 kbps

// 同步发送一帧经典 CAN
var frame = CanFrame.Classic(0x123, new byte[] { 0x11, 0x22, 0x33 });
var sentCount = bus.Transmit(frame);

// 异步发送同一帧
sentCount = await bus.TransmitAsync(frame);

// 同步接收（最多 2 帧），单位为毫秒
var items = bus.Receive(2, timeOut: 100);

// 异步批量接收（最多 10 帧），带超时
var list = await bus.ReceiveAsync(10, timeOut: 500);

事件驱动接收 + 批量发送

// 事件驱动接收、友好打印，及批量发送
using CanKit.Core;
using CanKit.Core.Abstractions;
using CanKit.Core.Definitions;
using System;

// 打开总线；在配置器中按需设置比特率/模式
using var bus = CanBus.Open(
    "socketcan://can0#netlink",
    cfg => cfg.TimingClassic(500_000));

// 订阅接收事件（如需错误/状态帧，请在配置中开启）
bus.FrameObserved += (_, rec) =>
{
    var f = rec.CanFrame;
    Console.WriteLine($"RX {f.FrameKind} ID=0x{f.ID:X} DLC={f.Dlc}");
};

var frame = CanFrame.Classic(0x123, new byte[] { 0x11, 0x22, 0x33 });

// 批量发送（同步 + 异步）
var frames = new[] { frame, frame, frame, frame };
sentCount = bus.Transmit(frames);
sentCount = await bus.TransmitAsync(frames);

// 可选：按需拉取（同步/异步）并设置超时
var one = bus.Receive(1, timeOut: 100);
var many = await bus.ReceiveAsync(10, timeOut: 500);

若更偏好强类型入口：

using CanKit.Adapter.Kvaser;
var bus = Kvaser.Open(0, cfg => cfg.Fd(1_000_000, 2_000_000));

Endpoint 与枚举

using CanKit.Core.Endpoints;
foreach (var ep in BusEndpointEntry.Enumerate("pcan", "kvaser", "socketcan", "virtual"))
{
    Console.WriteLine($"{ep.Title ?? ep.Endpoint} -> {ep.Endpoint}");
}

查询设备支持功能

using CanKit.Core;

var capability = CanBus.QueryCapabilities("kvaser://0");
Console.WriteLine($"support: {capability.Features}")

错误处理与监控

CanKit 提供了相应的事件，用于处理严重故障、后台循环异常以及 CAN 总线错误帧。

// 当连接中断或发生致命驱动错误时触发。
bus.FaultOccurred += (sender, exception) => {};

// 当接收/发送循环中发生非致命异常时触发。
bus.BackgroundExceptionOccurred += (sender, exception) => {};

// 当 CAN 控制器检测到物理总线错误（如位错误、填充错误、CRC 错误等）时触发。
bus.ErrorFrameReceived += (sender, errorInfo) => {};

适配器说明

• Vector (Windows/Linux): 安装 XL-Driver-Library, 并在Vector Hardware Manager 设置好app映射。
• PCAN（Windows）：安装 PCAN 驱动与 PCAN-Basic；确保 PCANBasic.dll 可加载（进程位数匹配 x86/x64）。
• Kvaser（Windows/Linux）：安装 Kvaser Driver + CANlib；确保 canlib 可加载并能访问通道。
• SocketCAN（Linux）：启用内核 SocketCAN，创建/配置接口（ip link …）；安装 libsocketcan。
• ZLG（Windows）：确保 zlgcan.dll 在加载路径，且位数与进程匹配。
• ControlCAN(Windows): 确保 ControlCAN.dll 在加载路径且与进程匹配。
• Virtual：无需驱动。

行为差异

• 超时语义：SocketCAN 对 TX/RX 超时均支持； 其余均只支持RX超时。
• 过滤器：各家支持的过滤类型不同（掩码/范围）；不足可启用软件回退。
• 错误帧/计数/总线利用率：可用性视适配器与驱动而定。部分设备需要先请求数据在获取（kvaser的总线利用率, Vector的错误计数）
• 周期发送：部分设备可使用硬件周期发送；否则用软件周期发送回退。

入门

• 中文：快速开始

项目状态

本库仍在积极开发中。由于可用硬件有限，尚未能对所有设备型号与系统组合进行完整验证。如遇问题，欢迎提交 Issue；也非常欢迎 PR、设备适配改进与测试反馈！ 也可以通过QQ联系我, QQ:2470919804

许可

请参见仓库中的 LICENSE 文件。