OpenIntelWireless

Appearance

FAQ ​

What does this Kext do ​

Non of the Kexts from this project implement any part of the Bluetooth Stack, hence they are not considered as drivers. They do not handle HCI commands, device pairing, and any feature other than uploading the firmware and preparing the device. The core part of Bluetooth is handled by Apple's drivers which only provides limited compatibility.

IntelBluetoothFirmware ​

  • Uploads Firmware to the device

  • Sets the device's USB Host Controller name to Bluetooth USB Host Controller on Monterey and newer to bypass board-id check in bluetoothd and bluetool

    INFO

    BluetoolFixup.kext also includes a workaround but this is cleaner approach.

IntelBTPatcher ​

This Kext serves two different purposes on different versions of macOS.

  • Monterey and newer
    • Workaround for a bug in bluetoothd by initializing the bluetooth module properly before attempting a LE Scan.
  • Prior to Monterey
    • Workaround for a bug in IOBluetoothHostController that prevents certain Bluetooth 4.X devices from connecting.
Technical Details

  • Monterey and newer

    • Apple forgot to set a random address before starting a LE scan with address type Random which results in the firmware returning Invalid HCI Command Parameters (0x12) (equivalent to OI_STATUS 718 shown in bluetoothd log output). Then bluetoothd crashes immediately.
    • Around the time when Intel Bluetooth 5.2 modules released, a check in the firmware was implemented accroding to Bluetooth Core Specs 5.0 and newer to return this error. This check has been backported to newer versions of Bluetooth 5.1 firmware. Before that, firmware for Bluetooth 5.1 and earlier will return success even if the conditions are not satisfied.

      If the scanning parameters' Own_Address_Type parameter is set to 0x01 or 0x03 and the random address for the device has not been initialized, the Controller shall return the error code Invalid HCI Command Parameters (0x12).

      BLUETOOTH SPECIFICATION Version 5.0 | Vol 2, Part E | 7.8.11 LE Set Scan Enable Command

    • Since all scans and advertisements in macOS Big Sur and earlier use public address instead of private, new versions of firmware with the check implemented work as intended.
    • All conclusions have been confirmed by using a modified version of BlueKitchen's Bluetooth stack running on macOS.

  • Prior to Monterey

    • A bug in IOBluetoothHostController mishandles LE Start Encryption which prevents Bluetooth 4.X devices that require encryption from connecting.
    • When a device requires encryption, the connection handle does not get stored in the async callback queue properly; the default handle 0xffff gets stored instead. When the event returns, the completion handle could not be found and the request fails because of timeout.
    • Bluetooth modules produced by neither Broadcom nor CSR all use IOBluetoothHostController.
    • BroadcomBluetoothHostController inherits IOBluetoothHostController and sends the HCI commands with IOBluetoothHostController::SendRawHCICommand instead of IOBluetoothHostController::SendHCICommand.
    • Inside the SendRawHCICommand method, there is a separate branch used to handle the LE Encryption event.
    • IntelBTPatcher's workaround forces the FindQueueRequest method to find the 0xffff handle when appropriate.
    • This is the only bug that prevents Bluetooth 5.X modules from connecting to Bluetooth 4.X devices that require encryption.
    • There are possibly more bugs in the stack that prevents Bluetooth 4.X modules from connecting to Bluetooth 4.X devices, requires further investigation.

Note

Fixes for Continuity features and other issues are not planned.

IntelBluetoothInjector ​

Do NOT use this Kext on macOS Monterey and newer

Codeless Kext that enables the on-off switch on older versions of macOS.

What additional steps should I do to make Bluetooth work on macOS Monterey and newer ​

  1. Install IntelBTPatcher.kext (Depends on Lilu v1.6.2 or newer)
  2. Make sure IntelBluetoothFirmware.kext v2.2.0 or newer is used.
  3. Remove/Exclude IntelBluetoothInjector.kext for macOS Monterey and newer from the Bootloader's config
  4. Install BlueToolFixup.kext from acidanthera/BrcmPatchRAM

Will there be any fixes for Bluetooth 4.X compatibility ​

Monterey and Newer ​

Apple rewrote the entire Bluetooth Driver for macOS Monterey which now delivers better compatibility with Bluetooth 4.X devices for all Intel Bluetooth modules.

Prior to Monterey ​

With IntelBTPatcher.kext installed, Bluetooth modules that support Bluetooth 5.X should now be able to connect to Bluetooth 4.X devices.

Bluetooth modules that only support up to Bluetooth 4.X are still unable to connect to other Bluetooth 4.X devices.

Why can't macOS Bluetooth connect to iPhone or iPad ​

Ask Apple, the same behavior occurs on real Macs as well.

Try something else if you are testing your device.

Is the solution meant to replace native supported USB Bluetooth Dongles ​

Not at all, Intel Bluetooth is only partly compatible with Apple's Drivers and has limited functionality.

Please consider an alternative solution like USB Dongles with BCM or CSR chips if Bluetooth is crucial for you.

I can't connect to device XXX but it's successfully discovered ​

Unfortunately, this is currently out of our control.

Can Intel Bluetooth co-exist with other Bluetooth Devices ​

No.

Will there be any fixes for XXX audio format ​

No, it's out of our control.