知识库

CyUSB.NET编程参考-Cypress .NET USB类库接口

6分钟阅读

CyUSB.NET 编程参考-Cypress .NET USB 类库接口

来源：Cypress CyUSB .NET Programmer’s Reference（2012，294 页 CHM 导出 PDF） 适用：C#/.NET 上位机与 Cypress FX2/FX3 芯片的 USB 通信；液相芯片数据采集卡 CY7C68013A 上位机开发的依赖库；同目录另有 CyUSB.NET.chm。 关联：Cypress-CyUSB3驱动编程参考手册（Win32/C++ 侧度量）、USB固件配置-数据采集卡FX2LP固件烧录流程、数据采集卡USB驱动安装说明-CYUSB签名绕过

一、库定位与编程模型

CyUSB.dll 是托管 .NET 类库（managed .NET），让上位机应用不用直接调用 Win32 API（SetupDiXxxx / DeviceIoControl），而是通过 XferData 方法、AltIntfc 属性等高级接口访问 USB 设备。可被任意 .NET 托管语言使用（C#、VB.NET、managed C++、J#）。

用法：项目引用 CyUSB.dll → 源文件 using CyUSB;。

三层对象模型：DeviceList → Devices → EndPoints

USBDeviceList usbDevices = new USBDeviceList(CyConst.DEVICES_CYUSB);
usbDevices.DeviceAttached += new EventHandler(usbDevices_DeviceAttached);
usbDevices.DeviceRemoved  += new EventHandler(usbDevices_DeviceRemoved);
// 按 VID/PID 直接索引定位设备
CyUSBDevice myDevice = usbDevices[0x04B4, 0x8613] as CyUSBDevice;
  • USBDeviceList：设备列表，支持即插即用（PnP）事件回调。
  • CyUSBDevice：由 cyusb3.sys 驱动服务的厂商自定义设备；也支持 HID/MSC 等 USB Class 设备。
  • 列表索引器（indexers）支持多种定位：usbDevices[int]、usbDevices[string fname]、usbDevices[VID, PID]、usbDevices[sMfg, sProd]。

二、CyConst 设备过滤常量

传给 USBDeviceList 构造器选设备类别，可按位或组合：

常量值含义
DEVICES_CYUSB0x01cyusb3.sys 或其自定义 GUID 衍生驱动服务的设备
DEVICES_MSC0x02usbstor.sys 驱动的大容量存储类设备
DEVICES_HID0x04人机接口设备

控制端点方向常量：DIR_FROM_DEVICE = 0x80（设备→主机），对应另有 DIR_TO_DEVICE。

三、USB3.0（BOS）支持

2012 版新增特性，不支持 USB3.0 bulk streams。

  • API（均在 CyUSBDevice）：GetBosDescriptor()、GetBosContainerIDDescriptor()、GetBosSSCapabilityDescriptor()、GetBosUSB20DeviceExtensionDesc()
  • 数据结构：USB_BOS_DESCRIPTOR、USB_BOS_CONTAINER_ID、USB_BOS_SS_DEVICE_CAPABILITY、USB_BOS_USB20_DEVICE_EXTENSION
  • 类：CyBOS_CONTAINER_ID、CyBOS_SS_DEVICE_CAPABILITY、CyBOS_USB20_DEVICE_EXT
  • 设备速度：CyUSBDevice.bSuperSpeed 布尔量
  • 超高速端点伴随描述符变量（在 CyUSBEndPoint 内，USB2.0 设备为 0）：SSDscLen、SSDscType、SSBytePerInterval、SSBmAttribute、SSMaxBurst

四、芯片子类扩展

CyFX2Device（FX2/FX2LP，本采集卡相关）

继承 CyUSBDevice，新增三个 FX2 专用方法（对非 FX2 设备调用行为未定义）：

  • LoadEEPROM(string fwFile)：把 .iic 固件镜像写入外接 EEPROM 并回读校验。
  • LoadRAM(string fwFile)：把 .iic 或 .hex 固件写入 FX2 内部 RAM 并重启运行新固件。
  • Reset(int hold)：hold=1 挂起芯片，hold=0 恢复执行。

典型 UI 集成模式：TreeView.Tag 存设备引用 → “Program EEPROM”/“Program RAM” 分支走 LoadEEPROM/LoadRAM。

与采集卡烧录流程对应：USB固件配置-数据采集卡FX2LP固件烧录流程 里 Control Center 的 Program FX2 按钮底层即这两个 API。

CyFX3Device（FX3 boot 设备）

仅对 FX3 boot 设备有效，非 boot 设备用 CyUSBDevice：

  • DownloadFw(filename, FX3_FWDWNLOAD_MEDIA_TYPE)：固件下载到 RAM / I2C EEPROM / SPI FLASH，文件必须 .img；返回 FX3_FWDWNLOAD_ERROR_CODE，用 GetFwErrorString() 转错误字符串。
  • IsBootLoaderRunning()：发厂商命令探测 bootloader 状态。

五、端点类体系

CyUSBEndPoint 为抽象基类，子类：

  • CyControlEndPoint：每个设备必有 ControlEndPt 成员；Direction/ReqType/Target 等属性可设置后发起控制传输。
  • CyBulkEndPoint：设备 BulkInEndPt / BulkOutEndPt 成员；属性 Attributes == 2。
  • CyInterruptEndPoint：InterruptInEndPt / InterruptOutEndPt；Attributes == 3；无额外方法。
  • CyIsocEndPoint：IsocInEndPt / IsocOutEndPt；Attributes == 1；为等时传输提供特殊的 ISO 包信息处理。

遍历端点找特定类型：

foreach (CyUSBEndPoint ept in dev.EndPoints)
    if (ept.bIn && (ept.Attributes == 3))
        InterruptIn = ept as CyInterruptEndPoint;

六、数据传输入门与进阶

同步：XferData

通常优先用同步 XferData(buf, len)，库内部自动完成分包、ISO 包信息计算等。

异步三件套：BeginDataXfer / WaitForXfer / FinishDataXfer

官方明确警告：这是”困难模式”，只有在必须榨干每一滴 USB 带宽时才用。

要点（CyIsocEndPoint 异步队列范例，QueueSz=8 保持带宽满载）：

  1. 每个队列项需四个 buffer：cmdBuf（长 SINGLE_XFER_LEN + GetPktBlockSize(BufSz)，BUFFERED 模式再加 BufSz）、xferBuf（数据）、ovLap（OVERLAPPED，OverlapSignalAllocSize 字节，hEvent 用 PInvoke.CreateEvent 创建）、pktInfos（ISO_PKT_INFO[GetPktCount(BufSz)]）。
  2. 先设 ept.XferSize = BufSz 预分配。
  3. 全部 BeginDataXfer 预填充队列。
  4. 循环：WaitForXfer(ovLap.hEvent, 500) 超时则 Abort() + PInvoke.WaitForSingleObject；FinishDataXfer 成功后立即 BeginDataXfer 重新挂回队列。
  5. SINGLE_XFER_LEN 的需求是 BUFFERED 模式（XMODE）特有的。

GetPktBlockSize(len)：返回 len 字节等时传输需要的所有 ISO_PKT_INFO 结构的总尺寸；只有用异步三件套时才需要自己算，XferData 会代劳。

七、参考结构与工具类

手册后半部分为逐属性 API 参考（约 30 个条目族）：USB_*_DESCRIPTOR 描述符结构、USBDevice（BcdUSB/DevClass/DriverName/FriendlyName/VendorID/ProductID/SerialNumber/USBAddress 等枚举属性）、USBDeviceList（Count、四种索引器、DeviceAttached/DeviceRemoved 事件）、Util（ParseHexFile/ParseHexData/ParseIICFile/ParseIICData/ReverseBytes、Assemblies/MaxFwSize）、OVERLAPPED/ISO_PKT_INFO/PInvoke/XMODE 等互操作结构。

Util.ParseHexData/ParseIICData 可直接把固件 .hex/.iic 解析成数组，供自写 FX2 烧录工具使用。

可行动点

  1. 液相芯片采集卡（CY7C68013A = FX2LP）上位机若要换用 C#，直接用 CyUSB.dll + CyFX2Device.LoadRAM 即可完成固件下载，不必自写控制传输。
  2. 大数据量采集回放用 BulkInEndPt.XferData；要跑满带宽再上 BeginDataXfer 三件套和 8 深队列。
  3. PnP 事件必须订阅，否则热插拔后设备句柄失效。
  4. 注意该库不支持 USB3.0 bulk streams，纯 FX2/68013A 项目无碍，FX3 走 bulk stream 需换 CyAPI（C++）。

关系图谱

反向链接