tools: Tool to collect bt firmware.

collect_bt_patches.py collects bluetooth module firmware
patch files for the most popular Broadcom and Realtek
modules into a directory where they can be used by the
virtualhub for initializing bluetooth modules.

Author: jaguilar

.gitignore

@@ -72,3 +72,7 @@ Pipfile.lock
 # Jupyter Notebook
 ######################
 .ipynb_checkpoints
+
+# BT Patches fetched by tools/collect_bt_patches.py
+##########################################
+.bt_firmware/

tools/collect_bt_patches.py

@@ -0,0 +1,189 @@
+#!/usr/bin/env python3
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 The Pybricks Authors
+
+"""
+Tool to collect bluetooth patch files in the user's cache directory.
+"""
+
+import argparse
+import os
+import re
+import subprocess
+import shutil
+from pathlib import Path
+
+# Destination directory in user's cache directory
+DEST_DIR = Path.cwd() / ".bt_firmware"
+
+
+def _fetch_and_checkout(checkout_dir: Path, ref_to_fetch: str):
+    """Fetch a specific ref (branch/tag/sha) from origin and check it out.
+
+    Uses a shallow fetch (--depth=1) and then forces checkout of FETCH_HEAD so
+    callers don't need to duplicate the subprocess logic.
+    """
+    subprocess.run(
+        ["git", "fetch", "--depth=1", "origin", ref_to_fetch],
+        cwd=checkout_dir,
+        check=True,
+    )
+    subprocess.run(
+        [
+            "git",
+            "checkout",
+            "--force",
+            "FETCH_HEAD",
+        ],
+        cwd=checkout_dir,
+        check=True,
+    )
+
+
+def sparse_checkout(
+    subdir: str,
+    repo_url: str,
+    paths: list[str],
+    branch: str = "master",
+    ref: str | None = None,
+):
+    """
+    Perform sparse checkout of specified paths from a git repository.
+
+    Args:
+        subdir: Subdirectory name under DEST_DIR
+        repo_url: URL of the git repository
+        paths: List of paths to checkout (e.g., ['brcm/', 'rtl_bt/'])
+        branch: Git branch to pull from (default: 'master')
+        ref: Optional git ref (commit sha or tag) to checkout. If provided,
+             this ref will be fetched and checked out instead of pulling the
+             branch. If None, the function will pull the specified branch as
+             before.
+    """
+    checkout_dir = DEST_DIR / subdir
+    git_dir = checkout_dir / ".git"
+
+    # Check if repo already exists
+    if git_dir.exists():
+        # If a specific ref was requested, fetch and checkout that ref.
+        if ref:
+            _fetch_and_checkout(checkout_dir, ref)
+            return
+
+        # No ref requested: just pull the latest changes from the branch
+        subprocess.run(["git", "pull", "origin", branch], cwd=checkout_dir, check=True)
+        return
+
+    # Create the directory
+    checkout_dir.mkdir(parents=True, exist_ok=True)
+
+    # Initialize git repo
+    subprocess.run(["git", "init"], cwd=checkout_dir, check=True)
+
+    # Add remote
+    subprocess.run(
+        ["git", "remote", "add", "origin", repo_url], cwd=checkout_dir, check=True
+    )
+
+    # Enable sparse checkout
+    subprocess.run(
+        ["git", "config", "core.sparseCheckout", "true"], cwd=checkout_dir, check=True
+    )
+
+    # Specify the paths to checkout
+    sparse_checkout_file = checkout_dir / ".git" / "info" / "sparse-checkout"
+    sparse_checkout_file.parent.mkdir(parents=True, exist_ok=True)
+    sparse_checkout_file.write_text("\n".join(paths) + "\n")
+
+    # Fetch and checkout either the requested ref or the branch tip.
+    ref_to_fetch = ref if ref is not None else branch
+    _fetch_and_checkout(checkout_dir, ref_to_fetch)
+
+
+def collect_firmware(subdir: str, pattern: str):
+    """
+    Create symbolic links for firmware files in DEST_DIR.
+
+    Args:
+        subdir: Subdirectory under DEST_DIR containing firmware files
+        pattern: Regex pattern to match and optionally extract parts for renaming.
+                 - If pattern has 2 capture groups, uses them concatenated as the link name
+                 - If pattern has no capture groups, uses original filename for matches
+    """
+    firmware_dir = DEST_DIR / subdir
+
+    if not firmware_dir.exists():
+        return
+
+    # Compile pattern
+    regex = re.compile(pattern)
+
+    for firmware_file in firmware_dir.iterdir():
+        if not firmware_file.is_file():
+            continue
+
+        # Check if filename matches pattern
+        match = regex.match(firmware_file.name)
+        if not match:
+            continue
+
+        # Determine link name based on capture groups
+        groups = match.groups()
+        if len(groups) == 2:
+            # Two groups: concatenate them for the link name
+            link_name = DEST_DIR / "".join(groups)
+        else:
+            # No groups: use original filename
+            link_name = DEST_DIR / firmware_file.name
+
+        # Skip if link already exists
+        if link_name.exists() or link_name.is_symlink():
+            continue
+
+        # Create the symbolic link
+        link_name.symlink_to(firmware_file)
+
+
+def main():
+    """Main entry point for collecting bluetooth patch files."""
+    parser = argparse.ArgumentParser(
+        description="Collect bluetooth patch files in the user's cache directory"
+    )
+    parser.add_argument(
+        "--clean",
+        action="store_true",
+        help="Delete the entire destination directory before collecting",
+    )
+    args = parser.parse_args()
+
+    # Clean destination directory if requested
+    if args.clean and DEST_DIR.exists():
+        shutil.rmtree(DEST_DIR)
+
+    # Checkout brcm directory from broadcom-bt-firmware repo
+    sparse_checkout(
+        subdir="brcm",
+        repo_url="https://github.com/winterheart/broadcom-bt-firmware",
+        paths=["brcm/"],
+        branch="master",
+        ref="v12.0.1.1105_p4",
+    )
+
+    # Checkout rtl_bt and intel directories from linux-firmware repo
+    sparse_checkout(
+        subdir="linux_firmware",
+        repo_url="https://gitlab.com/kernel-firmware/linux-firmware.git",
+        paths=["rtl_bt/", "intel/"],
+        branch="main",
+        ref="20251125",
+    )
+
+    # Collect firmware files into a single directory. Rename the brcm firmware
+    # files to match btstack's filename expectations.
+    collect_firmware("brcm/brcm", r"([^-]+)[^.]*(\..+)")
+    collect_firmware("linux_firmware/intel", r"^ibt.*(?:(ddc|sfi))$")
+    collect_firmware("linux_firmware/rtl_bt", r"^.*\.bin$")
+
+
+if __name__ == "__main__":
+    main()