简介本资源是一套面向嵌入式与Windows内核开发初学者的实践型源码项目聚焦I2C设备在Windows平台下的全栈通信实现适用于高校电子/计算机专业学生、驱动开发入门者及对KMDF和SPB总线机制感兴趣的工程师。项目完整覆盖用户态WinRT API调用、KMDF内核驱动开发支持多I2C设备接入与传感器数据读取、以及配套用户模式应用程序通过DeviceIoControl与驱动交互具备清晰的学习路径与工程可复现性。压缩包共38个文件含12个头文件定义常量与接口、9个C源文件分属winrtapi/kmdf/exe三层架构、3个Visual Studio工程文件sln/vcxproj/filters及ASL固件描述、驱动INF配置等关键构建要素整体体积仅1.83MB轻量易导入。目前已有51人学习下载读者可直接获取从硬件抽象、驱动建模到应用层控制的完整代码结构、模块化目录设计及README说明文档是理解Windows嵌入式外设通信机制的优质教学范例。1. 这不是“Windows 上跑 I2C”那么简单Sensy 是一套可调试、可验证、能进蓝屏现场的 KMDF I2C 驱动教学闭环你有没有试过在 Windows 上直接读一个温湿度传感器不是用 Arduino 或树莓派而是真正在 Win10/Win11 的 x64 系统里从内核态发起 I2C transaction把数据拿回来再通过 DeviceIoControl 推给用户程序最后在 WinRT UI 上显示——全程不依赖第三方 USB 转接器、不走 HID 模拟、不绕开 ACPI SPB 总线规范。Sensy 就是干这个的。它不是 demo不是玩具而是一套完整覆盖「用户态 WinRT 通信 → 内核态 KMDF 驱动开发 → SPB 总线抽象 → ACPI DSDT 适配 → 用户模式控制台交互」的嵌入式驱动教学链路。项目里带的rpi2_dsdt.ASL不是摆设asl.exe和winrtapi/下的I2CDisplay.cpp是真实联动的sensy.sys编译出来能加载、能枚举、能响应IOCTL_SENSY_READ_TEMP而main.cpp里那几行CreateFile(L\\\\.\\Sensy, ...)也不是示意代码——它真能打开设备、发控制码、收回 4 字节浮点温度值。适合谁正在啃《Windows Driver Development》第 7 章却卡在 SPB 初始化的某开发者想把 STM32 传感器板子直连 Surface Pro 做边缘采集但被 INF 签名拦住的某实验室成员或者刚学完 WDK 构建流程、急需一个“改三行就能看到蓝屏/成功日志”的最小可运行 KMDF 实体。这不是教你怎么装驱动是教你怎么让驱动自己开口说话。2. 从 WinRT API 入手为什么 Sensy 选择先做用户态 I2C 通信而不是一上来就写 .sysSensy 的设计逻辑很务实先确认硬件通路存在再封装成内核服务。很多初学者一上来就猛扎 KMDF结果驱动加载成功、设备管理器里也出现黄色感叹号但WdfIoQueueCreate后死活等不到EvtIoDefault回调——根本原因是I2C 总线压根没被系统识别SPB 控制器驱动没加载或者 ACPI 表里缺_HID或_CID。Sensy 把 WinRT API 作为第一道探针就是因为它足够轻、足够快、足够“无感”只要你的主板支持 UEFI ACPI SPBIntel 平台常见于 2015 年后AMD 平台需确认芯片组是否含 SPB Host Controller且 BIOS 开启了相关接口如 “I2C Controller Enable”WinRT 的I2cDevice.FromIdAsync()就能直接列出可用总线并完成一次读写。这步成功了说明① 硬件物理连接 OK② ACPI DSDT 描述正确③ Windows 已加载spb.sys和i2cminidriver.sys④ 用户权限足够无需管理员。这才是启动 KMDF 开发的黄金前提。2.1 WinRT I2C 通信实操用I2CDisplay.cpp验证 SPB 总线可达性项目中src/winrtapi/I2CDisplay.cpp是完整的 WinRT 用户态 I2C 测试入口。它不依赖任何第三方库只引用windows.devices.i2c.h和ppltasks.h编译目标为Windows Application (Universal Windows)。关键逻辑如下// I2CDisplay.cpp 核心片段已精简注释 #include windows.devices.i2c.h #include ppltasks.h using namespace Windows::Devices::I2c; using namespace concurrency; void TestI2cRead() { auto selector I2cDevice::GetDeviceSelector(); // 获取系统所有 I2C 总线 ID 列表 create_task(DeviceInformation::FindAllAsync(selector)).then([](DeviceInformationCollection^ devices) { if (devices-Size 0) { OutputDebugString(L[ERR] No I2C bus found. Check ACPI DSDT or BIOS setting.\n); return; } // 取第一个总线通常为 SPB0 auto busId devices-GetAt(0)-Id; auto settings ref new I2cConnectionSettings(0x40); // 假设传感器地址为 0x40 settings-BusSpeed I2cBusSpeed::StandardMode; // 必须匹配硬件规格 create_task(I2cDevice::FromIdAsync(busId, settings)).then([](I2cDevice^ device) { if (device nullptr) { OutputDebugString(L[ERR] Failed to open I2C device at 0x40.\n); return; } Platform::Arrayuint8_t^ writeBuf ref new Platform::Arrayuint8_t({0x00}); // 寄存器地址 Platform::Arrayuint8_t^ readBuf ref new Platform::Arrayuint8_t(2); try { device-Write(writeBuf); // 发起寄存器地址 device-Read(readBuf); // 读取 2 字节数据 float temp (readBuf[0] 8 | readBuf[1]) / 100.0f; wchar_t buf[64]; swprintf_s(buf, L[OK] Temp: %.2f°C\n, temp); OutputDebugString(buf); } catch (Platform::Exception^ e) { OutputDebugString(L[ERR] I2C transaction failed.\n); } }); }); }参数说明与逻辑拆解I2cDevice::GetDeviceSelector()返回的是系统级总线枚举器不是设备地址。它查的是ACPI\SPB*类型的总线实例对应spb.sys加载的控制器。若返回空90% 是 DSDT 缺失或 BIOS 关闭 I2C 控制器。I2cConnectionSettings(0x40)中的0x40是目标传感器的 7-bit 地址如 HTU21D必须与硬件 DIP 开关或上拉电阻配置一致若用 8-bit 地址如0x80会直接失败。BusSpeed必须严格匹配传感器手册要求StandardMode100kHz、FastMode400kHz或 FastPlus1MHz。Windows 默认只支持前两者FastPlusMode在部分平台会静默降级导致读数错位。Write()Read()是原子操作但 WinRT 不暴露 START/STOP 控制权。若传感器要求“重复启动”Repeated Start此方式会失败需切到 KMDF 手动构造 transaction。2.2 为什么不用libusb或i2c-toolsWinRT 的边界在哪有人会问既然 WinRT 能读为啥还要费劲写 KMDF 驱动答案藏在三个硬限制里①地址空间隔离WinRT I2C API 只允许访问ACPI\SPB*总线下挂载的设备且设备必须在 DSDT 中明确定义_HID如MSFT0001和_CID如PNP0C50。你无法用它去碰 SMBus、GPIO 模拟 I2C 或自定义 PCIe I2C IP 核。②事务粒度锁定WinRT 强制单次Write() 单次Read()不支持多寄存器连续读如0x00→0x01→0x02、不支持写后立即读Write-Read combined、不支持 clock stretching 处理。而工业传感器如 BME280常需此类操作。③无中断支持WinRT 是轮询模型无法注册OnDataReceived事件。你想做“温度超阈值立刻通知”只能靠用户程序每 100ms 主动Read()功耗和延迟都不可控。Sensy 的价值正是用 WinRT 快速验明“这条路能走”再用 KMDF 把路修宽、修深、修出红绿灯和应急通道。3. KMDF 驱动核心SPB 总线抽象与多设备复用的Sensy.sys架构设计Sensy 的.sys文件不是传统意义上的“独占 I2C 控制器驱动”而是一个SPB Function Driver—— 它不直接操作硬件寄存器而是通过 Windows 提供的SpbCxSPB Class Extension与底层spb.sys交互。这种分层设计是微软推荐的现代做法也是它能同时管理多个 I2C 设备如温度传感器 OLED 显示屏的关键。驱动主体位于src/kmdf/核心文件是Sensy.cpp主框架、SensySpbTarget.cppSPB 通信封装和SensyIoctl.h控制码定义。整个架构规避了直接操作 MMIO、处理中断向量、编写 HAL 层代码等高危操作把复杂度锁死在 KMDF 框架内。3.1 SPB Target 封装如何用SpbCx统一管理不同 I2C 设备KMDF 驱动中每个物理 I2C 设备如地址0x40的温感、0x3C的 OLED在驱动内表现为一个WDFDEVICE对象其背后绑定一个SPB_TARGET句柄。Sensy 通过SensySpbTarget.cpp封装了创建、读写、清理全流程// SensySpbTarget.cpp 片段创建 SPB target 并缓存句柄 NTSTATUS SensySpbTargetCreate( _In_ WDFDEVICE Device, _In_ PCUNICODE_STRING DeviceId, _Out_ PSPB_TARGET* SpbTarget ) { SPB_TARGET_CONFIG config; SPB_TARGET_CONFIG_INIT(config); config.DeviceId DeviceId; // 来自 ACPI _ADR 或 INF 中指定的设备 ID config.RequestType SpbRequestTypeI2c; config.I2cAddress 0x40; // 此处应从设备资源中读取非硬编码 NTSTATUS status SpbTargetCreate( Device, config, WDF_NO_OBJECT_ATTRIBUTES, SpbTarget ); if (!NT_SUCCESS(status)) { KdPrint((Sensy: SpbTargetCreate failed for %wZ, status0x%08X\n, DeviceId, status)); return status; } // 关键将 SPB target 句柄挂到 WDFDEVICE 的 Context 中供后续 IOCTL 使用 PSensyDeviceContext pCtx GetSensyDeviceContext(Device); pCtx-SpbTarget *SpbTarget; return STATUS_SUCCESS; }为什么I2cAddress不能硬编码Sensy 支持多设备地址必须从 ACPI DSDT 的_CRSCurrent Resource Settings中解析。例如 DSDT 片段Device (TMP0) { Name (_HID, MSFT0001) Name (_CID, PNP0C50) Name (_ADR, 0x0000000040000000) // 低 8 位即 I2C 地址 0x40 Name (_CRS, ResourceTemplate () { I2cSerialBus (0x40, ControllerInitiated, 0x00061A80, AddressingMode7Bit, \\_SB.PCI0.SPB0) }) }驱动在EvtDeviceAdd中调用WdfFdoQueryForInterface()获取SPB_BUS_INTERFACE_STANDARD再用SpbTargetCreate()传入_ADR或_CRS解析出的地址。硬编码0x40只适用于单设备调试量产必须动态获取。3.2 IOCTL 控制码设计IOCTL_SENSY_READ_TEMP如何穿透三层进入 SPB用户程序通过DeviceIoControl()发送控制码驱动在EvtIoDeviceControl中分发。Sensy 定义了 4 个核心 IOCTL见SensyIoctl.hIOCTL 名称功能数据流向IOCTL_SENSY_READ_TEMP读取温度传感器原始值驱动 → 用户缓冲区4 字节 floatIOCTL_SENSY_WRITE_DISPLAY向 OLED 写入 128×64 像素缓冲区用户缓冲区1024 字节 → 驱动 → SPBIOCTL_SENSY_GET_DEVICE_INFO返回当前 SPB 总线 ID 和设备地址驱动 → 用户缓冲区结构体IOCTL_SENSY_SET_SAMPLE_RATE设置采样间隔毫秒用户缓冲区uint32 → 驱动更新定时器以IOCTL_SENSY_READ_TEMP为例其内核执行链为main.cpp→CreateFile(\\\\.\\Sensy)→DeviceIoControl(hDev, IOCTL_SENSY_READ_TEMP, NULL, 0, temp, sizeof(float), bytes, NULL)↓Sensy.cpp:EvtIoDeviceControl()匹配到IOCTL_SENSY_READ_TEMP↓调用SensySpbTargetReadTemp(pCtx-SpbTarget, rawData)↓SensySpbTargetReadTemp()构造SPB_REQUEST-RequestType SpbRequestTypeI2c-I2cAddress pCtx-DeviceAddress-WriteBuffer {0x00}读取温度寄存器 0x00-ReadBuffer rawBytes[2]读 2 字节原始值↓SpbRequestSubmitSynchronously()提交至spb.sys↓spb.sys调用i2cminidriver.sys操作硬件寄存器返回数据↓驱动将rawBytes转为 float拷贝至Irp-AssociatedIrp.SystemBuffer关键细节SPB_REQUEST 的生命周期SpbRequestSubmitSynchronously()是阻塞调用会占用 IRQL DISPATCH_LEVEL 的线程。Sensy 未使用异步SpbRequestSubmit()因为温度读取是低频操作默认 1s 一次同步更易调试。若需高吞吐如音频 I2S必须改用异步 EvtSpbRequestComplete回调并确保WDFQUEUE配置为Parallel模式。4. 避坑 / 常见问题 / 排查Sensy 编译、加载、通信失败的五类血泪现场Sensy 是教学项目但它的坑比商用驱动还密集——因为每一步都暴露在开发者眼前。以下是我在三台不同主板Intel NUC、AMD B550 Mini-ITX、Surface Pro 7上反复踩出的 5 个高频问题按现象→原因→解决结构整理拒绝模糊描述。4.1 现象Build succeeded但sc create sensy type kernel binPath C:\sensy.sys后sc start sensy报Error 2: The system cannot find the file specified.原因.sys文件路径含中文、空格或长路径sc工具无法解析或sensy.sys依赖的WdfLdr.sys未预加载Windows 10 1809 默认启用 Driver Signature Enforcement未签名驱动无法加载。解决① 将sensy.sys放入纯英文短路径如C:\drv\sensy.sys② 以管理员身份运行bcdedit /set testsigning on→ 重启 → 进入测试签名模式③ 用Inf2Cat和signtool对sensy.inf签名项目中sensy.inf已提供模板需替换PublisherName④sc create后务必sc qc sensy确认TYPE为kernel、START_TYPE为demand非auto避免开机自启失败蓝屏。4.2 现象驱动加载成功sc query sensy显示RUNNING但main.cpp中CreateFile(\\\\.\\Sensy)返回INVALID_HANDLE_VALUEGetLastError()为2ERROR_FILE_NOT_FOUND原因符号链接未创建。KMDF 驱动必须在EvtDeviceAdd中调用WdfDeviceCreateSymbolicLink()否则用户程序找不到设备对象。Sensy 的Sensy.cpp第 127 行有该调用但若WdfDeviceCreateSymbolicLink()返回失败如链接名已被占用驱动不会报错退出而是静默跳过。解决① 在EvtDeviceAdd中添加日志KdPrint((Sensy: Creating symbolic link %wZ\n, linkName));② 检查linkName是否为L\\??\\Sensy注意双反斜杠③ 运行winobj.exeSysinternals 工具导航到\??\目录确认Sensy链接是否存在且指向\Device\Sensy0④ 若存在冲突卸载旧驱动sc delete sensy→devcon remove ROOT#SENSY#0→ 清理注册表HKLM\SYSTEM\CurrentControlSet\Services\sensy。4.3 现象WinRTI2cDevice::FromIdAsync()成功但 KMDF 中SpbTargetCreate()失败状态码0xC0000001STATUS_UNSUCCESSFUL原因ACPI DSDT 中设备节点的_HID或_CID不被 Windows SPB 驱动识别。Sensy 依赖MSFT0001或PNP0C50若你修改 DSDT 时误写为MSFT0002或ACPI0001spb.sys就不会将该设备暴露给SpbTargetCreate()。解决① 用acpidump.exe导出当前 DSDT搜索设备节点的_HID值② 确认spb.sys支持的 HID 列表可通过strings spb.sys | findstr MSFT\|PNP查看③ 修改 DSDT确保_HID为MSFT0001_CID为PNP0C50④ 重新编译 DSDTasl.exe rpi2_dsdt.ASL用iasl工具注入需关闭 Secure Boot。4.4 现象IOCTL_SENSY_READ_TEMP返回成功但读出的float值恒为0.00或乱码如1.4013e-45原因SPB transaction 中WriteBuffer和ReadBuffer长度/顺序错误。I2C 传感器读取通常需两步先Write寄存器地址1 字节再Read数据N 字节。若WriteBuffer为空或ReadBuffer大小不足SpbRequestSubmitSynchronously()会静默返回成功但ReadBuffer未被填充。解决① 在SensySpbTargetReadTemp()中打印WriteBuffer.Length和ReadBuffer.Length② 确保WriteBuffer至少 1 字节存放寄存器地址ReadBuffer大小匹配传感器手册如 HTU21D 为 2 字节BME280 为 3 字节③ 检查SPB_REQUEST结构体初始化Request-WriteBuffer.Length必须等于WriteBuffer实际长度不能为 0。4.5 现象驱动加载后设备管理器中显示“Sensy”带黄色感叹号属性页提示“Windows 无法验证此设备的数字签名”原因驱动未签名且系统未启用测试签名模式或签名证书链不完整如仅用自签名证书未包含中间 CA。解决① 最简方案bcdedit /set testsigning on→ 重启仅限开发机② 生产方案申请 EV 代码签名证书用signtool sign /v /fd SHA256 /td SHA256 /tr http://timestamp.digicert.com /a sensy.sys签名③ 验证签名signtool verify /pa sensy.sys输出必须含Successfully verified④ 若用Inf2Cat生成.cat文件需确保sensy.inf中[Version]段的CatalogFilesensy.cat与生成文件名一致且.cat文件与.sys同目录。5. 从 DSDT 注入到实时调试用TraceView抓取 SPB 通信波形与驱动状态流转Sensy 的最大教学价值不是让你写出一个能跑的驱动而是让你看清“数据从传感器引脚进来到用户程序变量赋值”之间每一帧发生了什么。这需要两套工具协同ACPI DSDT 注入用于硬件描述落地WPP 跟踪 TraceView用于内核行为可视化。我一般会强制走一遍这套组合技哪怕只是验证一行KdPrint是否生效。5.1 DSDT 注入实战把rpi2_dsdt.ASL改造成你的主板可用版本rpi2_dsdt.ASL是 Raspberry Pi 2 的参考实现不能直接用于 x86 主板。改造核心是三步①提取原厂 DSDT用acpidump.exe -t导出当前 BIOS 的DSDT.dat再用iasl -d DSDT.dat反编译为DSDT.dsl②定位 SPB 控制器节点在DSDT.dsl中搜索SPB0、I2C0或PCI0.SPB0找到类似结构Device (SPB0) { Name (_HID, INT33C2) // Intel SPB Host Controller Name (_CID, PNP0C50) Method (_STA, 0, NotSerialized) { Return (0x0F) } ... }③嫁接 Sensy 设备节点将rpi2_dsdt.ASL中的Device (TMP0)节点复制到DSDT.dsl的SPB0下并修改_ADR为你的传感器地址如0x0000000040000000_HID改为MSFT0001。保存后iasl -tc DSDT.dsl编译为DSDT.aml。注入注意事项必须关闭 Secure Boot否则 UEFI 拒绝加载自定义 DSDTDSDT.aml需放入 EFI 分区/EFI/Microsoft/Boot/目录重命名为DSDT.aml部分主板要求OEM1.aml注入后用acpidump -t验证新 DSDT 是否生效搜索TMP0确认节点存在。5.2 WPP 跟踪配置让KdPrint变成可过滤、可时间戳、可导出的结构化日志Sensy 的Sensy.cpp已启用 WPPWindows Software Trace Preprocessor但默认配置不输出到TraceView。需手动配置① 在sensy.vcxproj中确认EnableWppTracingtrue/EnableWppTracing已开启② 在驱动源码顶部添加 WPP 宏定义#include wpp.h #define WPP_CONTROL_GUIDS \ WPP_DEFINE_CONTROL_GUID(SensyTraceGuid, (b0e5c9a1, 1f2b, 4c8e, 0x9a, 0x1b, 0x2c, 0x3d, 0x4e, 0x5f, 0x6a, 0x7b), \ WPP_DEFINE_BIT(TRACE_DRIVER) \ WPP_DEFINE_BIT(TRACE_SPB) \ WPP_DEFINE_BIT(TRACE_IOCTL) \ )③ 在EvtDeviceAdd等函数中用DoTraceMessage(TRACE_DRIVER, Device added, context%p, pCtx);替代KdPrint④ 编译后生成sensy.tmh和sensy.wpp用tracepdb.exe sensy.sys提取 PDB 信息。5.3 TraceView 实时抓包亲眼看见 SPB transaction 的 START/STOP 时刻配置好 WPP 后启动TraceViewWDK 自带①File → New Log Session→ 勾选Kernel Logger和Real-time②Provider → Add Provider→ 输入SensyTraceGuid即上面定义的 GUID③Start开始捕获④ 运行main.exe触发IOCTL_SENSY_READ_TEMP⑤TraceView中将看到结构化日志[14:22:31.123] Sensy: TRACE_SPB - SpbTargetCreate for TMP0, addr0x40 [14:22:31.125] Sensy: TRACE_SPB - SpbRequestSubmit: Write1byte, Read2bytes [14:22:31.127] Sensy: TRACE_IOCTL - IOCTL_SENSY_READ_TEMP completed, temp23.45°C关键技巧关联硬件波形若你有逻辑分析仪可将SPB0_SCL和SPB0_SDA引出用Saleae Logic抓取实际 I2C 波形。对比TraceView中SpbRequestSubmit时间戳与波形 START 时刻误差应 1ms。若偏差 10ms说明SpbCx层有调度延迟需检查WDFQUEUE是否配置为Sequential强制串行导致阻塞。从那以后我每次调试 KMDF I2C 驱动都强制走一遍 DSDT 注入 WPP 跟踪 TraceView 抓包三件套。不是为了炫技是因为只有看到SpbRequestSubmit日志和示波器波形严丝合缝对齐的那一刻你才真正相信——数据真的从传感器流进了你的驱动没有丢包、没有错位、没有玄学。希望帮到你。本文还有配套的精品资源点击获取