Home

Awesome

BrcmPatchRAM

Build Status Scan Status

Translate Language

Most Broadcom USB Bluetooth devices make use of a system called RAMUSB. RAMUSB allows the firmware for the device to be updated on-the-fly, however any updates previously applied are lost when shutting down the machine.

The Broadcom Windows driver will upload firmware into the Broadcom Bluetooth device on every startup, however for macOS this functionality is not supported out of the box. BrcmPatchRAM kext is a macOS driver which applies PatchRAM updates for Broadcom RAMUSB based devices. It will apply the firmware update to your Broadcom Bluetooth device on every startup / wakeup, identical to the Windows drivers. The firmware applied is extracted from the Windows drivers and the functionality should be equal to Windows.

Note that the original Apple Broadcom bluetooth devices are not RAMUSB devices, and thus do not have the same firmware mechanism.

Installation

Note if you have an Apple MacBook/iMac/Mac Pro etc, follow the Mac instructions

Install one of BrcmPatchRAM.kext or BrcmPatchRAM2.kext or BrcmPatchRAM3.kext depending on macOS version, never both.

Also, install one firmware kext BrcmFirmwareData.kext or BrcmFirmwareRepo.kext, depending on installation location, never both.

Keep in mind that BrcmPatchRAM3.kext also requires BrcmBluetoothInjector.kext to be installed. Starting with macOS 10.15, this is the only supported configuration because due to framework changes BrcmPatchRAM.kext and BrcmPatchRAM2.kext are incompatible with macOS 10.15. In case you forget to install BrcmBluetoothInjector.kext, Bluetooth will appear to be available but it won't work at all.

Also, if you have a non-PatchRAM device (or you're not sure), install one of BrcmNonPatchRAM.kext or BrcmNonPatchRAM2.kext, depending on macOS version, never both. Although these kexts do not install any firmware (these devices have firmware built-in), they still depend on BrcmPatchRAM/BrcmPatchRAM2.kext.

BrcmBluetoothInjector.kext

To be used for macOS 10.11-11. Use BrcmBluetoothInjectorLegacy.kext for older systems. Using BrcmPatchRAM3.kext also requires BrcmBluetoothInjector.kext as changes in macOS Catalina (10.15) requires the use of a separate injector kext. This is due to the removal of the following IOCatalogue methods:

IOCatalogue::addDrivers, IOCatalogue::removeDrivers and IOCatalogue::startMatching

Consequently to have the native BT driver load for the device (BroadcomBluetoothHostControllerUSBTransport) we inject using a plist with a slightly lower IOProbeScore than BrcmPatchRAM3 so it doesn't probe before the firmware upload.

The BrcmBluetoothInjector.kext is a codeless kernel extension which injects the BT hardware data using a plist; it does not contain a firmware uploader. You might also want to try this kext if you wish to see if your device will work without a firmware uploader.

Do not use BrcmPatchRAM or BrcmPatchRAM2 with this kext.

BrcmBluetoothInjector supported devices:

If yours is not present, edit the Info.plist as needed.

BlueToolFixup.kext

Required for macOS 12 or newer, as in macOS 12 Apple has changed parts of the Bluetooth stack from kernel-space to user-space as detailed in here and here. Requires Lilu 1.5.4+

Do not use it with BrcmBluetoothInjector for macOS 12 or newer.

Supported Devices

BrcmPatchRAM supports any Broadcom USB bluetooth device based on the BCM20702 chipset (possibly other chipsets are supported also, but this has not been tested).

The following devices are supported at the moment:

Devices marked with * are tested successfully

Non-PatchRAM devices (BrcmPatchRAM used to speed up recovery after sleep):

Tested PatchRAM devices:

All of the firmwares from the Windows package are present in the kext and automatically associated with their vendor/device-ids. They are expected to work, but have not been confirmed. If you can confirm a working device not listed above, please notify via the "issues" database on github. The firmwares have been updated to version 12.0.1.1105.

More Installation Details

BrcmPatchRAM.kext, BrcmPatchRAM2.kext and BrcmPatchRAM3.kext can be installed either through bootloader kext injection or placed in /System/Library/Extensions (/Library/Extensions on 10.11 and later). Make sure to install only one of them, depending on system version.

BrcmFirmwareRepo.kext does not work with bootloader kext injection, unless using a device specific firmware injector. BrcmFirmwareData.kext can work with bootloader kext injection.

You can also use a device specific firmware injector (in conjunction with BrcmFirmwareRepo.kext). In this scenario, BrcmFirmwareRepo.kext does work from bootloader kexts.

You will find device specfic injectors in the 'firmwares' directory of the git repository. They are not included in the distribution ZIP.

Configuration

There are a number of delays which can be changed with the following kernel boot arguments. You might change these values if you find BrcmPatchRAM is hanging during firmware load. Refer to the source for futher details on these delays.

For example, to change mPostResetDelay to 400 ms, use the kernel boot argument: bpr_postresetdelay=400.

Note: Some with the typical "wake from sleep" problems are reporting success with: bpr_probedelay=100 bpr_initialdelay=300 bpr_postresetdelay=300. Or slightly longer delays: bpr_probedelay=200 bpr_initialdelay=400 bpr_postresetdelay=400.

On macOS 12.4 and newer versions, a new address check has been introduced in bluetoothd, thus an error will be triggered if two Bluetooth devices have the same address. However, this check can be circumvented by adding the boot argument -btlfxallowanyaddr.

Details

BrcmPatchRAM consists of 2 parts:

If a firmware update is required, the matching firmware data will be uploaded to the device and the device will be reset.

After the device firmware is uploaded, the device control is handed over to Apple's BroadcomBluetoothHostControllerUSBTransport. This means that for all intents and purposes your device will be native on macOS and support all functionalities fully.

It is possible to use the Continuity Activation Patch in combination with BrcmPatchRAM through BT4LEContinuityFixup, or through dokterdok's script Continuity-Activation-Tool, or through OpenCore quirk ExtendBTFeatureFlags.

Troubleshooting

After installing BrcmPatchRAM, even though your Bluetooth icon may show up, it could be that the firmware has not been properly updated.

Verify the firmware is updated by going to System Information and check the Bluetooth firmware version number under the Bluetooth information panel.

If the version number is "4096", this means no firmware was updated for your device and it will not work properly.

Verify any errors in the system log by running the following command in the terminal:

    # For 10.12 and newer:
    log show --last boot | grep -i brcm[fp]
    # For older macOS versions:
    cat /var/log/system.log | grep -i brcm[fp]

Ensure you check only the latest boot messages, as the system.log might go back several days.

If the firmware upload failed with an error, try installing the debug version of BrcmPatchRAM in order to get more detailed information in the log.

In order to report an error log an issue on github with the following information:

Firmware Compatibility

Some USB devices are very firmware specific and trying to upload any other firmware for the same chipset into them will fail.

This usually displays in the system log as:

BrcmPatchRAM: Version 0.5 starting. BrcmPatchRAM: USB [0a5c:21e8 5CF3706267E9 v274] "BCM20702A0" by "Broadcom Corp" BrcmPatchRAM: Retrieved firmware for firmware key "BCM20702A1_001.002.014.1443.1612_v5708". BrcmPatchRAM: Decompressed firmware (29714 bytes --> 70016 bytes). BrcmPatchRAM: device request failed (0xe000404f). BrcmPatchRAM: Failed to reset the device (0xe00002d5). BrcmPatchRAM: Unable to get device status (0xe000404f). BrcmPatchRAM: Firmware upgrade completed successfully.

The errors in between mean the firmware was not uploaded successfully, and the device will most likely need a specific firmware configured.

For other devices the newest firmware available (even though not specified specifically in the Windows drivers) works fine.

New devices

In order to support a new device, the firmware for the device needs to be extracted from existing Windows drivers.

A copy of the (current) latest Broadcom USB bluetooth drivers can be found here: http://drivers.softpedia.com/get/BLUETOOTH/Broadcom/ASUS-X99-DELUXE-Broadcom-Bluetooth-Driver-6515800-12009860.shtml#download

For an automatic update you can unpack the Broadcom USB bluetooth files and run firmware_update.tool.

Should you come across newer drivers than 12.0.1.1012, please let me know.

In order to get the device specific firmware for your device take the following steps:

%BRCM20702.DeviceDesc%=BlueRAMUSB0223, USB\VID_0930&PID_0223       ; 20702A1 Toshiba 4352

;;;;;;;;;;;;;RAMUSB0223;;;;;;;;;;;;;;;;;
[RAMUSB0223.CopyList]
bcbtums.sys
btwampfl.sys
BCM20702A1_001.002.014.1443.1457.hex

zlib.pl deflate BCM20702A1_001.002.014.1443.1457.hex > BCM20702A1_001.002.014.1443.1457.zhx

xxd -ps BCM20702A1_001.002.014.1443.1457.zhx|tr '\n' ' ' > BCM20702A1_001.002.014.1443.1457.dmp

Note that the version number displayed in macOS is the last number in the file name (1457 in our sample) + 4096.

So in this case the firmware version in macOS would be: "c14 v5553".

Firmwares can also be loaded directly from BrcmFirmwareRepo.kext/Contents/Resources, either by firmware key name (see above), or by naming the file with just the vendor and device-id. For example, 0930_0223.hex (uncompressed) or 0930_0223.zhx (compressed).

Copying an existing IOKit personality and modifying its properties is the easiest way to do this. Configure the earlier firmware using its unique firmware key.

Support and discussion

InsanelyMac topic in English
AppleLife topic in Russian