# macintelk/intelbtunified architecture

> Architecture diagram of the GitHub repository macintelk/intelbtunified, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/macintelk/intelbtunified
- Repository: https://github.com/macintelk/intelbtunified

## Overview

IntelBTUnified is a macOS kernel extension combining an Intel Bluetooth firmware driver with a Lilu plugin that patches HCI requests and macOS Bluetooth components. The principal path is USB-device matching, controller setup, generation-specific firmware loading, then Bluetooth operation; the plugin provides separate compatibility patches. The README documents plugin behavior and packaging capabilities, while sampled driver excerpts show USB transport and generation-specific firmware logic. Several driver dispatch and lifecycle details were not sampled, so those links are left unverified.

Main entry points: [`src/driver/IntelBluetoothFirmware.cpp`](https://github.com/macintelk/intelbtunified/blob/main/src/driver/IntelBluetoothFirmware.cpp) (Device driver), [`src/driver/BtIntel.cpp`](https://github.com/macintelk/intelbtunified/blob/main/src/driver/BtIntel.cpp) (Intel HCI core), [`src/IntelBTUnified.cpp`](https://github.com/macintelk/intelbtunified/blob/main/src/IntelBTUnified.cpp) (Lilu plugin), [`src/driver/IntelBluetoothOpsGen2.cpp`](https://github.com/macintelk/intelbtunified/blob/main/src/driver/IntelBluetoothOpsGen2.cpp) (Gen2 operations)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_plugin["Lilu compatibility plugin"]
  node_plugin_entry["Lilu plugin<br/>[IntelBTUnified.cpp]"]
  node_hci_patch["HCI patch<br/>[IntelBTUnified.cpp]"]
  node_bluetooth_patches["BlueTool patches<br/>[IntelBTUnified.cpp]"]
end

subgraph group_driver["Firmware driver"]
  node_device_driver["Device driver"]
  node_usb_controller["USB transport"]
end

subgraph group_protocol["Intel protocol operations"]
  node_btintel["Intel HCI core<br/>[BtIntel.cpp]"]
  node_gen1["Gen1 operations"]
  node_gen2["Gen2 operations"]
  node_gen3["Gen3 operations"]
  node_vsc["Vendor commands<br/>[BtIntelVSC.cpp]"]
  node_fw_core["Firmware requests<br/>[BtIntelFw.cpp]"]
end

subgraph group_firmware["Firmware resources"]
  node_device_table["Supported devices<br/>[devices.txt]"]
  node_fw_files["Firmware files"]
end

node_macos(("macOS Bluetooth"))
node_lilu(("Lilu"))
node_usb(("Intel USB controller"))

node_macos -.->|"loads plugin"| node_plugin_entry
node_lilu -.->|"hosts plugin"| node_plugin_entry
node_plugin_entry -.->|"applies"| node_hci_patch
node_plugin_entry -.->|"applies"| node_bluetooth_patches
node_usb -.->|"matches device"| node_device_driver
node_device_driver -.->|"initializes"| node_usb_controller
node_btintel -->|"sends HCI"| node_usb_controller
node_device_driver -.->|"selects operations"| node_btintel
node_device_driver -.->|"dispatches"| node_gen1
node_device_driver -.->|"dispatches"| node_gen2
node_device_driver -.->|"dispatches"| node_gen3
node_gen1 -->|"requests firmware"| node_fw_core
node_gen2 -.->|"requests firmware"| node_fw_core
node_gen3 -.->|"requests firmware"| node_fw_core
node_fw_core -.->|"loads resources"| node_fw_files
node_device_table -.->|"defines support"| node_device_driver
node_gen1 -.->|"uses HCI core"| node_btintel
node_gen2 -.->|"uses HCI core"| node_btintel
node_gen3 -->|"extends operations"| node_gen2
node_vsc -.->|"uses controller core"| node_btintel

click node_plugin_entry "https://github.com/macintelk/intelbtunified/blob/main/src/IntelBTUnified.cpp"
click node_hci_patch "https://github.com/macintelk/intelbtunified/blob/main/src/IntelBTUnified.cpp"
click node_bluetooth_patches "https://github.com/macintelk/intelbtunified/blob/main/src/IntelBTUnified.cpp"
click node_device_driver "https://github.com/macintelk/intelbtunified/blob/main/src/driver/IntelBluetoothFirmware.cpp"
click node_usb_controller "https://github.com/macintelk/intelbtunified/blob/main/src/driver/USBDeviceController.cpp"
click node_btintel "https://github.com/macintelk/intelbtunified/blob/main/src/driver/BtIntel.cpp"
click node_gen1 "https://github.com/macintelk/intelbtunified/blob/main/src/driver/IntelBluetoothOpsGen1.cpp"
click node_gen2 "https://github.com/macintelk/intelbtunified/blob/main/src/driver/IntelBluetoothOpsGen2.cpp"
click node_gen3 "https://github.com/macintelk/intelbtunified/blob/main/src/driver/IntelBluetoothOpsGen3.cpp"
click node_vsc "https://github.com/macintelk/intelbtunified/blob/main/src/driver/BtIntelVSC.cpp"
click node_fw_core "https://github.com/macintelk/intelbtunified/blob/main/src/driver/BtIntelFw.cpp"
click node_device_table "https://github.com/macintelk/intelbtunified/blob/main/devices.txt"
click node_fw_files "https://github.com/macintelk/intelbtunified/tree/main/fw"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_plugin_entry,node_hci_patch,node_bluetooth_patches toneBlue
class node_device_driver,node_usb_controller toneAmber
class node_btintel,node_gen1,node_gen2,node_gen3,node_vsc,node_fw_core toneMint
class node_device_table,node_fw_files toneRose
class node_macos,node_lilu,node_usb toneIndigo
```

## Components

### Lilu compatibility plugin

- [Lilu plugin](https://github.com/macintelk/intelbtunified/blob/main/src/IntelBTUnified.cpp): `src/IntelBTUnified.cpp`
- [HCI patch](https://github.com/macintelk/intelbtunified/blob/main/src/IntelBTUnified.cpp): `src/IntelBTUnified.cpp`
- [BlueTool patches](https://github.com/macintelk/intelbtunified/blob/main/src/IntelBTUnified.cpp): `src/IntelBTUnified.cpp`

### Firmware driver

- [Device driver](https://github.com/macintelk/intelbtunified/blob/main/src/driver/IntelBluetoothFirmware.cpp): `src/driver/IntelBluetoothFirmware.cpp`
- [USB transport](https://github.com/macintelk/intelbtunified/blob/main/src/driver/USBDeviceController.cpp): `src/driver/USBDeviceController.cpp`

### Intel protocol operations

- [Intel HCI core](https://github.com/macintelk/intelbtunified/blob/main/src/driver/BtIntel.cpp): `src/driver/BtIntel.cpp`
- [Gen1 operations](https://github.com/macintelk/intelbtunified/blob/main/src/driver/IntelBluetoothOpsGen1.cpp): `src/driver/IntelBluetoothOpsGen1.cpp`
- [Gen2 operations](https://github.com/macintelk/intelbtunified/blob/main/src/driver/IntelBluetoothOpsGen2.cpp): `src/driver/IntelBluetoothOpsGen2.cpp`
- [Gen3 operations](https://github.com/macintelk/intelbtunified/blob/main/src/driver/IntelBluetoothOpsGen3.cpp): `src/driver/IntelBluetoothOpsGen3.cpp`
- [Vendor commands](https://github.com/macintelk/intelbtunified/blob/main/src/driver/BtIntelVSC.cpp): `src/driver/BtIntelVSC.cpp`
- [Firmware requests](https://github.com/macintelk/intelbtunified/blob/main/src/driver/BtIntelFw.cpp): `src/driver/BtIntelFw.cpp`

### Firmware resources

- [Supported devices](https://github.com/macintelk/intelbtunified/blob/main/devices.txt): `devices.txt`
- [Firmware files](https://github.com/macintelk/intelbtunified/tree/main/fw): `fw`

### Other components

- **macOS Bluetooth**
- **Lilu**
- **Intel USB controller**

## Connections

- macOS Bluetooth → Lilu plugin: loads plugin (evidence: `README.md`)
- Lilu → Lilu plugin: hosts plugin (evidence: `README.md`)
- Lilu plugin → HCI patch: applies (evidence: `README.md`)
- Lilu plugin → BlueTool patches: applies (evidence: `README.md`)
- Intel USB controller → Device driver: matches device (evidence: `README.md`)
- Device driver → USB transport: initializes
- Intel HCI core → USB transport: sends HCI (evidence: `src/driver/BtIntel.cpp`)
- Device driver → Intel HCI core: selects operations
- Device driver → Gen1 operations: dispatches (evidence: `README.md`)
- Device driver → Gen2 operations: dispatches (evidence: `README.md`)
- Device driver → Gen3 operations: dispatches (evidence: `README.md`)
- Gen1 operations → Firmware requests: requests firmware (evidence: `src/driver/BtIntelFw.cpp`)
- Gen2 operations → Firmware requests: requests firmware
- Gen3 operations → Firmware requests: requests firmware
- Firmware requests → Firmware files: loads resources (evidence: `README.md`)
- Supported devices → Device driver: defines support (evidence: `README.md`)
- Gen1 operations → Intel HCI core: uses HCI core
- Gen2 operations → Intel HCI core: uses HCI core
- Gen3 operations → Gen2 operations: extends operations
- Vendor commands → Intel HCI core: uses controller core
