1. 项目缘起：为什么要在Windows上模拟蓝牙HID设备？

几年前，我在做一个智能家居中控的演示项目，需要让一台Windows迷你主机同时扮演“大脑”和“遥控器”的角色。具体来说，就是让这台主机通过蓝牙，直接控制客厅的智能电视和投影仪，实现PPT翻页、视频播放暂停等操作。最直接的思路，就是让这台Windows电脑模拟成一个蓝牙键盘或鼠标。

听起来很简单，市面上不是有各种“蓝牙适配器”吗？但当我真正开始动手，才发现从软件层面让Windows原生模拟蓝牙HID（Human Interface Device，人机接口设备），是一个相当“硬核”的领域。你很难找到一个开箱即用的软件，告诉你点一下就能让电脑变成蓝牙键盘。核心的障碍在于，Windows的蓝牙协议栈对HID设备的角色有明确的划分：它通常只作为“主机”（Host）或“中心设备”（Central），去连接和支配像键盘、鼠标这样的“外围设备”（Peripheral）。而我们要做的，是让Windows去扮演那个“外围设备”的角色，这触及了系统蓝牙驱动和协议栈的底层。

这不仅仅是发几个按键信号那么简单，它涉及到：

1. 蓝牙协议层面的角色转换：让Windows的蓝牙控制器进入“外围设备”广播模式。
2. 系统驱动的交互：需要编写或改造驱动，让系统识别并管理这个“虚拟”的HID设备。
3. HID报告描述符的构建：精确地定义这个虚拟设备的功能（是键盘？鼠标？还是游戏手柄？），让对端设备（如电视、平板）能正确解析其发送的数据包。

网上关于这个主题的中文资料非常零散，大多停留在理论或某个孤立工具的使用上，缺乏从原理到实战、从环境搭建到驱动调试的完整链路。因此，我决定结合自己的踩坑经历，写一个系列，目标是手把手带你从零开始，在Windows上实现蓝牙HID设备的模拟。本篇作为开篇，将重点放在核心概念、方案选型与底层原理的梳理上，这是后续所有实操的基石。理解了“为什么”，后面的“怎么做”才会顺畅。

2. 核心概念拆解：蓝牙、HID与Windows驱动模型

在动手写一行代码之前，我们必须把几个关键概念及其在Windows环境下的交互关系搞清楚。这能避免你未来在调试时对着晦涩的错误代码茫然无措。

2.1 蓝牙HID协议概要

蓝牙HID协议是基于蓝牙无线通信技术，实现键盘、鼠标、游戏手柄等设备与主机交互的标准。它本身是USB HID协议在蓝牙领域的适配和扩展。其通信模型通常包含两个角色：

• HID主机：接收并处理输入数据的设备，如电脑、手机、平板。
• HID设备：产生输入数据的设备，如键盘、鼠标。

在我们的项目中，目标设备（如智能电视）是HID主机，而我们的Windows电脑需要扮演HID设备。

一个蓝牙HID设备的工作流程可以简化为：

1. 广播：设备以低功耗模式向外广播自己的存在，包含设备名称、支持的HID服务等信息。
2. 连接：主机扫描并发现设备后，发起连接请求，建立一条安全的通信链路。
3. 配对/绑定：为了安全，主机和设备会交换密钥，完成配对，后续连接可以快速重连。
4. 服务发现：连接后，主机会查询设备提供的服务（Services）和特征（Characteristics）。HID服务有标准的UUID（0x1812）。
5. 报告传输：HID输入数据（如按下了A键）被封装成“报告”，通过特定的特征值（Characteristic）发送给主机。报告的结构由一份叫做“报告描述符”的二进制文档预先定义好。

2.2 Windows蓝牙驱动栈剖析

Windows的蓝牙驱动是一个分层结构，理解它有助于我们知道在哪里“动手术”。

• 蓝牙无线电硬件：最底层，比如你的笔记本内置的蓝牙模块，或一个USB蓝牙适配器（如常见的CSR8510 A10）。
• 蓝牙端口驱动程序：由硬件厂商提供，负责与特定蓝牙芯片的底层通信。例如，bthusb.sys处理USB蓝牙适配器，bthpan.sys处理个人局域网。
• 蓝牙协议栈：微软提供的Bthport.sys是核心，它实现了蓝牙的核心协议（如L2CAP, RFCOMM, SDP, GATT等）。它向上提供统一的接口。
• Windows蓝牙API层：包括经典的Windows Sockets蓝牙扩展（ws2_32.dll）和较新的低功耗蓝牙API（在Windows.Devices.Bluetooth命名空间下）。我们编写的应用程序通常通过这一层与蓝牙交互。
• HID类驱动程序：当Windows作为主机时，hidclass.sys和hidparse.sys负责解析HID报告描述符，并将HID报告转换为标准的输入事件，传递给上层系统。

关键障碍：在标准Windows配置中，Bthport.sys和整个驱动栈被设计为只支持主机角色。它没有提供直接的、用户态（User-Mode）的API来让一个应用程序以标准HID设备身份进行广播和连接。这就是我们需要驱动级开发的根本原因。

2.3 方案选型：三条路径的深度对比

基于以上原理，我们有三条主要路径可以实现目标，每条路径的复杂度、灵活性和适用场景截然不同。

路径一：使用虚拟HID设备驱动 + 用户态控制（推荐起点）这是平衡了难度和灵活性的最佳起点。其核心思想是：在驱动层创建一个“虚拟”的HID设备，这个设备对Windows系统内部表现为一个普通的USB HID设备；然后，我们再通过一个用户态程序，将蓝牙通信模块获取到的数据，“注入”到这个虚拟设备中。

• 如何工作：
  1. 安装一个虚拟HID设备驱动（如ViGEmBus，或基于HidGuardian的方案）。这个驱动会在“设备管理器”的“人体学输入设备”下创建一个虚拟设备。
  2. 我们的用户态程序包含两部分逻辑：一部分通过Windows蓝牙API（如Windows.Devices.Bluetooth.Advertisement）以低功耗蓝牙外围模式广播，并与目标主机连接；另一部分通过驱动提供的接口（如HidCerberus.SDK或直接IOCTL）将生成的HID报告发送给虚拟设备。
  3. 虚拟设备驱动将这些报告“转发”给Windows输入系统，就好像是一个真实硬件在输入。
• 优点：用户态开发为主，相对安全，调试方便。可以利用成熟的虚拟驱动，避免编写复杂的内核驱动。功能强大，可以模拟多种HID设备。
• 缺点：架构稍显复杂，涉及进程间通信。需要处理用户态与内核态的数据交换。
• 适用场景：大多数软件模拟场景，如自动化测试工具、远程控制、自定义输入设备原型开发。

路径二：修改或编写蓝牙协议栈过滤驱动（高阶玩法）这是更底层、更彻底的方案。通过编写一个内核态的过滤驱动程序，附着在系统蓝牙协议栈（如Bthport.sys）之上或之下，拦截并修改其发出的蓝牙指令和数据包，强制其以外围设备模式工作。

• 如何工作：使用Windows Driver Kit开发一个KMDF或WDM过滤驱动。这个驱动可以拦截蓝牙控制命令，将其从“主机模式”改为“外围模式”，并处理来自对端主机的HID服务查询请求和报告数据写入请求。
• 优点：更接近硬件，效率可能更高，理论上可以实现最完整的功能。
• 缺点：开发难度极大，需要深厚的驱动开发知识和蓝牙协议知识。极易导致系统蓝屏，稳定性风险高。对系统版本依赖性强。
• 适用场景：对性能有极致要求，或需要实现非常规蓝牙功能的研究型项目。

路径三：使用特定硬件的专属模式（取巧方案）某些蓝牙芯片（如部分Nordic nRF系列）支持“串口透传”或“HID-over-GATT”的固件。你可以在这类开发板上编写固件，使其模拟HID设备，然后通过USB连接到Windows电脑，电脑再通过串口工具向开发板发送指令来控制它。此时，Windows本身并未模拟HID，它只是通过串口控制了一个外部的硬件模拟器。

• 如何工作：购买一个支持蓝牙HID设备角色的开发板，烧写相应固件。Windows上运行一个串口通信程序，将按键指令通过USB虚拟串口发送给开发板，由开发板通过蓝牙发送给目标主机。
• 优点：完全避开了Windows驱动开发的难题，稳定性好。
• 缺点：需要额外硬件，成本增加，便携性差。本质上不是“Windows模拟”，而是“硬件桥接”。
• 适用场景：快速功能验证，或作为最终产品的硬件方案原型。

对于绝大多数开发者，我强烈建议从路径一开始。它让我们能够将复杂问题分解：先集中精力搞定蓝牙通信逻辑（用户态），再通过一个稳定的虚拟驱动接口处理HID报告注入。本系列后续的实战也将围绕此路径展开。

3. 环境准备：工具链与SDK的抉择

工欲善其事，必先利其器。选择正确的工具能事半功倍，尤其是避免在环境问题上浪费数天时间。

3.1 开发环境搭建

1. Visual Studio：这是Windows开发的核心。建议使用最新稳定版的Visual Studio Community（免费），安装时务必勾选“使用C++的桌面开发”工作负载，这会包含基本的Windows SDK和编译工具链。
2. Windows Driver Kit：即使我们主要走用户态路径，WDK也是必需的，因为它包含了编译驱动所需的头文件、库和工具（如inf2cat,signtool）。更重要的是，它提供了hidpi.h等HID相关的头文件，以及驱动开发的调试符号。从微软官网下载与您Windows SDK版本匹配的WDK。
3. Windows SDK：通常随Visual Studio安装或更新。确保安装了较新版本（如Windows 11 SDK），它包含了最新的蓝牙LE API头文件（windows.devices.bluetooth.h等）。

实操心得：安装WDK后，建议创建一个纯净的“驱动开发”虚拟机环境。因为驱动安装、测试经常需要禁用驱动程序强制签名，甚至进入测试模式，在虚拟机里操作不会影响宿主机的工作环境，也更安全。

3.2 关键库与框架选择

• 虚拟HID设备驱动：ViGEmBus是目前最活跃、文档相对完善的开源选择。它最初为虚拟游戏手柄设计，但其架构也支持创建虚拟键盘和鼠标。它的用户态接口清晰，通过Feeder库可以方便地注入输入。另一个历史选择是HidGuardian，但它更侧重于输入重定向和屏蔽，对于从零创建新设备不如ViGEmBus直观。
• 蓝牙LE通信库：我们将使用Windows Runtime API，即Windows.Devices.Bluetooth命名空间下的类。这是微软官方推荐的现代蓝牙LE开发接口，支持异步操作，比古老的32feet.NET（基于Windows Sockets）对BLE外围模式的支持更好、更现代。在C++项目中，需要通过C++/WinRT语言投影来调用这些API。
• 项目类型选择：对于控制台应用程序，我推荐使用C++/WinRT控制台应用项目模板。它天然集成了Windows Runtime支持。如果你更熟悉C#，也可以使用.NET Core/ .NET 6+的控制台应用，通过Windows.Devices.Bluetooth.Advertisement等NuGet包进行开发，语法更简洁。

3.3 硬件要求与兼容性排查

不是所有蓝牙适配器都支持低功耗蓝牙和外围模式！

• 内置适配器：2015年后生产的多数笔记本电脑内置蓝牙（如Intel AX200/AX210）都支持蓝牙4.2/5.0，通常也支持外围模式。
• USB蓝牙适配器：需要特别注意。市面上很多便宜的USB蓝牙4.0适配器（尤其是那些使用CSR8510旧版固件的）可能仅支持经典蓝牙，而不支持低功耗蓝牙，或者固件锁死了外围模式功能。
• 如何验证：一个简单的方法是打开“设备管理器”，找到你的蓝牙无线电设备，查看属性详情中的“硬件ID”。或者，运行一个简单的BLE扫描程序（网上有很多示例），看能否扫描到其他BLE设备（如智能手环）。如果扫不到，很可能不支持BLE。

踩坑记录：我曾在一个项目中被一个CSR8510 A10适配器卡了两天。它在Windows 10下能被识别，也能连接经典蓝牙设备，但调用BluetoothLEAdvertisementPublisher相关API时总是返回权限错误或不支持。后来换了一个明确标注支持蓝牙4.2 BLE的适配器（如基于Realtek RTL8761B芯片的），问题立刻解决。所以，硬件是第一步，务必确认。

4. 核心原理实战推演：从广播到报告发送

现在，我们结合路径一的方案，推演一下一个最简单的“蓝牙键盘模拟器”从启动到发送一个按键“A”的完整软件流程。这会将前面所有的理论串联起来。

4.1 第一步：启动虚拟HID设备驱动

在用户程序启动前，虚拟HID设备驱动（如ViGEmBus）需要已安装并运行。安装后，你会在设备管理器看到类似“HID-compliant game controller”或“Virtual HID Device”的设备。我们的程序需要与这个驱动的用户态接口建立连接。

对于ViGEmBus，我们需要初始化其客户端库，并请求创建一个特定类型的虚拟设备。例如，创建一个虚拟键盘设备。这个过程会返回一个设备句柄或对象，后续我们通过它来“喂”数据。

// 伪代码，示意流程 #include <ViGEmClient.h> #include <ViGEmTarget.h> PVIGEM_CLIENT client = vigem_alloc(); // 分配客户端 VIGEM_ERROR err = vigem_connect(client); // 连接到驱动 PVIGEM_TARGET keyboard = vigem_target_x360_alloc(); // 分配一个目标设备（此处以手柄为例，键盘类似） err = vigem_target_add(client, keyboard); // 将虚拟设备添加到驱动 // 此时，系统会多出一个“Xbox 360 Controller”设备。对于键盘，需要使用对应的创建函数。

4.2 第二步：以BLE外围设备身份广播

我们的用户程序需要扮演一个BLE外围设备。这需要做以下几件事：

1. 定义HID服务：创建一个蓝牙GATT服务，其UUID为标准的HID服务UUID (0x1812)。在这个服务下，需要创建几个必需的特征：
   • 报告特征：用于发送输入报告。例如，键盘的报告特征UUID通常是0x2A4D（HID Report）。
   • 报告映射特征：用于存放HID报告描述符 (0x2A4B)。
   • HID信息特征：包含HID设备的版本、国家代码等信息 (0x2A4A)。
   • 协议模式特征：指示使用引导协议还是报告协议 (0x2A4E)。
2. 构建HID报告描述符：这是一段二进制数据，精确描述了你的虚拟设备。例如，一个最简单的键盘描述符会定义：有一个8字节的输入报告，第一个字节是修饰键（Ctrl, Shift等），第二个字节保留，第三到第八字节是6个按键的键码。你需要按照HID规范来编写这段描述符，这是与主机正确通信的“合同”。
3. 创建广播数据：将包含HID服务UUID的数据加入到广播数据包中。同时，可以设置设备名称、外观类别等。
4. 启动广播：使用BluetoothLEAdvertisementPublisher类开始广播。

// C++/WinRT 伪代码示意 #include <winrt/Windows.Devices.Bluetooth.Advertisement.h> #include <winrt/Windows.Devices.Bluetooth.GenericAttributeProfile.h> using namespace winrt; using namespace Windows::Devices::Bluetooth; using namespace Windows::Devices::Bluetooth::Advertisement; using namespace Windows::Devices::Bluetooth::GenericAttributeProfile; // 1. 创建GATT服务提供者（需要系统权限，通常需要声明capability或在清单中请求） GattServiceProvider hidServiceProvider = co_await GattServiceProvider::CreateAsync(GattServiceUuids::HumanInterfaceDevice()); // 2. 创建并配置报告特征等... GattLocalCharacteristicParameters reportParams; reportParams.CharacteristicProperties(GattCharacteristicProperties::Read | GattCharacteristicProperties::Write | GattCharacteristicProperties::Notify); // ... 设置UUID、权限等 GattLocalCharacteristic inputReportCharacteristic = co_await hidServiceProvider.Service().CreateCharacteristicAsync(reportCharacteristicUuid, reportParams); // 3. 设置广播数据 BluetoothLEAdvertisementPublisher publisher; BluetoothLEAdvertisement advertisement = publisher.Advertisement(); advertisement.ServiceUuids().Append(GattServiceUuids::HumanInterfaceDevice()); // ... 设置其他广播数据 publisher.Start();

4.3 第三步：处理连接与报告发送

当目标主机（如手机）扫描并连接上我们的设备后：

1. 处理连接事件：GattServiceProvider会触发连接状态改变事件，我们可以在此事件中获知主机已连接。
2. 主机发现服务：主机会自动进行服务发现，读取我们预先设置好的HID服务、特征和报告描述符。
3. 构建并发送HID报告：当需要模拟按键时，我们的程序需要按照HID报告描述符定义的格式，组装一个报告数据包。例如，发送一个“按下A键”的报告：
   • 报告内容可能是：[0x00, 0x00, 0x04, 0x00, 0x00, 0x00, 0x00, 0x00]（假设第三个字节的0x04对应A键的HID使用码）。
   • 然后，通过调用虚拟HID设备驱动提供的接口（如ViGEm的vigem_target_x360_update函数，对于键盘则是相应的更新函数），将这个报告“注入”到虚拟设备。
   • 同时，如果我们需要通过BLE通道也发送（例如直接控制电视），则需要将同样的报告数据，通过之前创建的inputReportCharacteristic的Notify方法（或Write方法，取决于协议模式）发送给已连接的BLE主机。

// 伪代码：发送按键报告 void SendKeyPress(VIGEM_TARGET keyboard, uint8_t hidKeyCode) { // 1. 构建报告数据结构（根据你的虚拟设备类型） XUSB_REPORT report; report.wButtons = 0; // 假设我们模拟的是手柄按钮，这里仅为示意 // ... 填充报告数据 // 2. 更新虚拟设备状态 VIGEM_ERROR err = vigem_target_x360_update(client, keyboard, report); // 3. 同时，通过BLE特征值通知主机（如果BLE已连接） if (bleConnected) { winrt::array_view<const uint8_t> reportData = ... ; // 构建同样的HID报告字节流 inputReportCharacteristic.NotifyValueAsync(reportData); } }

4. 释放按键：发送一个所有键都为0的报告，表示按键释放。

4.4 一个关键的技术细节：HID报告描述符

这是模拟HID设备中最容易出错的部分。报告描述符是一种非常紧凑的二进制语言，用于向主机描述数据格式。一个描述键盘的报告描述符片段看起来像这样（用C数组表示）：

0x05, 0x01, // Usage Page (Generic Desktop) 0x09, 0x06, // Usage (Keyboard) 0xA1, 0x01, // Collection (Application) 0x05, 0x07, // Usage Page (Key Codes) 0x19, 0xE0, // Usage Minimum (224) 0x29, 0xE7, // Usage Maximum (231) 0x15, 0x00, // Logical Minimum (0) 0x25, 0x01, // Logical Maximum (1) 0x75, 0x01, // Report Size (1) 0x95, 0x08, // Report Count (8) 0x81, 0x02, // Input (Data,Var,Abs) ; Modifier byte 0x95, 0x01, // Report Count (1) 0x75, 0x08, // Report Size (8) 0x81, 0x01, // Input (Cnst,Arr,Abs) ; Reserved byte 0x95, 0x05, // Report Count (5) 0x75, 0x01, // Report Size (1) 0x05, 0x08, // Usage Page (LEDs) // ... 后续还有LED输出报告、按键数组等定义

编写它需要参考USB HID规范文档。幸运的是，网上有很多现成的键盘、鼠标、游戏手柄的描述符可以直接借鉴或使用工具生成。在调试时，如果主机无法识别你的设备，十有八九是报告描述符有问题。

5. 常见陷阱与调试心法

即使理解了原理，实际开发中依然会踩很多坑。这里分享几个我亲身经历过的典型问题及其排查思路。

5.1 权限问题：应用程序无法启动广播或连接

• 现象：调用BluetoothLEAdvertisementPublisher.Start()失败，返回“访问被拒绝”或类似错误。
• 根因：从Windows 10开始，蓝牙广播和GATT服务器操作需要特定的设备能力声明，并且在首次运行时需要用户授权。
• 解决方案：
  1. 在应用程序清单文件（Package.appxmanifest或桌面应用的app.manifest）中，添加以下能力声明：

     <!-- 对于打包应用（如UWP/MSIX） --> <Capabilities> <DeviceCapability Name="bluetooth"/> <DeviceCapability Name="radios"/> </Capabilities>

     对于非打包的桌面控制台应用，情况更复杂。你可能需要以管理员身份运行，或者使用Windows.Devices.BluetoothAPI的特定重载，这些重载需要应用具有相应的后台权限。一个更简单粗暴的测试方法是：直接以管理员身份运行你的调试程序，有时可以绕过初步的权限检查。
  2. 确保系统蓝牙设置中，“允许设备发现此电脑”的选项是打开的。

5.2 驱动签名问题：测试模式必不可少

• 现象：自己编译的虚拟HID设备驱动（或修改的驱动）无法安装，提示“Windows无法验证此设备所需的驱动程序的数字签名”。
• 根因：64位Windows系统要求所有内核模式驱动都必须具有有效的数字签名。开发测试时，我们通常没有微软的EV代码签名证书。
• 解决方案：将Windows启动到测试模式。以管理员身份打开命令提示符，执行：

  bcdedit /set testsigning on

  然后重启电脑。桌面右下角会出现“测试模式”的水印。这样系统就会允许加载未正确签名的测试驱动。重要提示：测试模式会降低系统安全性，请在开发测试机上操作，生产环境绝对不要使用。

5.3 蓝牙连接不稳定或无法发现

• 现象：手机或电视能偶尔扫描到设备，但连接经常断开，或者根本扫描不到。
• 排查步骤：
  1. 检查硬件：再次确认蓝牙适配器支持BLE外围模式。尝试用手机上的“蓝牙调试助手”等APP扫描，看能否看到你的设备广播的完整名称和服务UUID。
  2. 检查广播间隔：BluetoothLEAdvertisementPublisher可以设置广播间隔。间隔太短（如小于100ms）可能耗电且被某些主机过滤，间隔太长（如大于1秒）则不易被发现。建议设置在100ms到500ms之间。
  3. 检查广播数据长度：广播数据包有大小限制（通常31字节）。确保你的设备名称、服务UUID列表等没有超限。过长的名称会被截断。
  4. 干扰问题：Wi-Fi（特别是2.4GHz）和蓝牙会相互干扰。尝试关闭电脑的Wi-Fi，或者让设备靠近一些。

5.4 HID报告发送后主机无反应

• 现象：程序逻辑一切正常，BLE连接成功，发送报告也没有报错，但目标主机（如电视）没有任何输入响应。
• 排查步骤：
  1. 报告描述符验证：这是最可能的原因。使用USB分析仪（如Wireshark with USBPcap）或者专门的HID描述符解析工具，检查你生成的报告描述符是否完全符合HID规范。一个常见的错误是逻辑最小值/最大值（Logical Min/Max）或报告大小/计数（Report Size/Count）设置错误。
  2. 报告数据验证：确保你发送的报告字节流，其格式与报告描述符定义完全一致。例如，描述符定义了一个8字节的输入报告，你就必须每次都发送8个字节，即使某些字节是0。
  3. 协议模式：确保HID协议模式特征值设置正确。对于大多数现代设备，使用“报告协议”模式（值为0x01）。
  4. 主机兼容性：有些主机（特别是某些电视或嵌入式设备）对HID设备的实现可能不完整或有特殊要求。尝试先用一个真实的蓝牙键盘连接该主机，确认其HID功能正常。然后，尽量让你的虚拟设备模仿这个真实设备的报告描述符。

调试这类底层交互，一个强大的工具是Windows内置的蓝牙日志。可以通过事件查看器（eventvwr.msc）查看Windows日志 -> 应用程序和服务日志 -> Microsoft -> Windows -> Bluetooth-BthLE。同时，在命令提示符（管理员）下运行netsh trace start scenario=Bluetooth globallevel=verbose persistent=yes capture=yes可以启动蓝牙网络跟踪，生成.etl文件，然后用Windows Performance Analyzer打开分析，能看到非常底层的蓝牙协议交互过程，对于定位疑难杂症有奇效。

本篇作为系列的开篇，我们深入探讨了在Windows上模拟蓝牙HID设备的动机、核心原理、三种实现路径的优劣以及环境准备要点。我们选择了“虚拟HID驱动 + 用户态BLE控制”这条最具可行性的路径，并推演了其完整的工作流程。最后，分享了一些必然会遇到的坑和调试方法。这些知识是后续实战的基石。在下一篇中，我们将真正开始动手，从创建一个最简单的虚拟键盘设备驱动开始，一步步搭建起整个项目的骨架。