Skip to content
NanamiKitePublic

About

DirectHCI 是 Windows 蓝牙控制器的用户态访问基础设施:通过临时 WinUSB 接管提供 Raw HCI 与 BLE/GATT 能力,并在会话结束后恢复 Windows 蓝牙驱动。

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Latest commit

 

History

18 Commits

Folders and files

Repository files navigation

DirectHCI

中文

DirectHCI lets Windows applications use a USB Bluetooth controller directly. Its local service temporarily switches a selected controller to Microsoft's WinUSB driver, carries raw HCI commands, events and ACL data, then restores the Windows Bluetooth driver and saved access permissions when the session ends.

Use it to build a BLE client with the Rust SDK, connect your own HCI host stack, or inspect a controller with the command-line tools. The BLE library uses TrouBLE for scanning, connections and GATT.

DirectHCI does not maintain a static VID/PID allowlist. Prepare Controller reads the selected controller's actual Hardware ID and creates a matching WinUSB package. A new eligible controller does not require an updated device list or a new DirectHCI installation.

Try it on Windows

You need Windows x64, administrator access and a suitable USB Bluetooth controller. Windows cannot use that controller while DirectHCI owns it. Keep a wired keyboard or mouse available if your input devices use Bluetooth.

  1. Install the DirectHCI setup executable. For a source build, follow the build instructions.
  2. Open DirectHCI Control Panel and approve elevation.
  3. Click Start Service, select a controller, then Prepare Controller if it is not ready. Read and approve the package-signing certificate prompt.
  4. Run a DirectHCI consumer with administrator rights. Its session request starts takeover; starting the service or preparing a controller does not.
Windows Bluetooth
  → Prepare: stage a matching package, keep Windows in control
  → Acquire: give one client exclusive HCI access
  → Release: close HCI and restore Windows ownership and permissions

With the service running, these PowerShell commands only query its state:

& "$env:ProgramFiles\DirectHCI\directhci.exe" status --json
& "$env:ProgramFiles\DirectHCI\directhci.exe" controllers --json

Minimizing the panel keeps it in the tray. Closing it stops the service. For installation, upgrades and removal, see the user guide. If Bluetooth does not return, use safe recovery; a stopped service alone does not confirm recovery.

Use it from another application

Rust applications link the unpublished SDK crates from a local checkout:

  • directhci-ble provides async BLE scanning, connections, GATT reads/writes and notifications.
  • directhci-client connects to the service and owns a raw HCI session.
  • directhci-bt-hci adapts that session to the bt-hci controller traits.

The SDK talks to directhcid over a local named pipe. BLE runs in the consumer process; the service owns WinUSB handles and driver changes. There is no HTTP server or ready-made C, C# or Python binding. See SDK integration for dependencies, startup and cleanup.

Status and limits

This is development software. Users have reported successful operation with Intel AX201, AX200 and BE200 Bluetooth controllers. Those reports are hardware records, not a support list, and do not certify every later build.

Windows can reject a locally signed package or require a system restart during driver restoration. DirectHCI does not change Secure Boot, TESTSIGNING or BCD. Power loss, a blue screen, forced termination or replacing running binaries can leave recovery incomplete. BLE GATT/disconnect regressions and the newer package-ranking changes still need recorded hardware retesting.

The installer label and Rust runtime version are separate; see build versions before producing a release.

Further reading

Start with the documentation index. It separates user recovery, SDK/CLI usage, implementation details and historical experiments. The architecture explains which process owns each resource.

First-party code is GPL-3.0-only. See dependencies and distribution files before distributing binaries.

About

DirectHCI 是 Windows 蓝牙控制器的用户态访问基础设施:通过临时 WinUSB 接管提供 Raw HCI 与 BLE/GATT 能力,并在会话结束后恢复 Windows 蓝牙驱动。

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages