Install platform dependencies at runtime

Author: makermelissa

README.rst

@@ -49,6 +49,12 @@ running CircuitPython and would likely conflict in unhappy ways.
 The test suites in the test/src folder under **testing.universal** are by design
 intended to run on *either* CircuitPython *or* CPython/Micropython+compatibility layer to prove conformance.
 
+Platform-specific dependencies are detected when Blinka starts. When Blinka is
+running in an interactive terminal and a dependency is missing, it offers to
+install the packages needed by the detected board into the current Python
+environment. In non-interactive environments, the existing import error includes
+the command needed to install the missing platform package.
+
 Installing from PyPI
 =====================
 

requirements.txt

@@ -5,10 +5,3 @@ pyftdi>=0.40.0
 adafruit-circuitpython-typing
 sysv_ipc>=1.1.0;sys_platform=='linux' and platform_machine!='mips'
 toml>=0.10.2;python_version<'3.11'
-Jetson.GPIO;sys_platform=='linux' and platform_machine=='aarch64'
-rpi_ws281x>=4.0.0;sys_platform=='linux' and (platform_machine=='armv6l' or platform_machine=='armv7l' or platform_machine=='aarch64')
-lgpio>=0.2.2.0; sys_platform=='linux' and python_version<'3.13' and (platform_machine=='aarch64' or platform_machine=='armv7l')
-adafruit-lgpio>=0.2.2.0; sys_platform=='linux' and python_version>='3.13' and (platform_machine=='aarch64' or platform_machine=='armv7l')
-RPi.GPIO;sys_platform=='linux' and (platform_machine=='armv6l' or platform_machine=='armv7l' or platform_machine=='aarch64')
-Adafruit-Blinka-Raspberry-Pi5-Neopixel;sys_platform=='linux' and platform_machine=='aarch64' and python_version>='3.11'
-Adafruit_BBIO>=1.2.4;sys_platform=='linux' and platform_machine=='armv7l'

setup.py

@@ -10,7 +10,6 @@
 
 import io
 import os
-import sys
 
 from setuptools import setup, find_packages
 
@@ -22,48 +21,6 @@
 with io.open(os.path.join(here, "README.rst"), encoding="utf-8") as f:
     long_description = "\n" + f.read()
 
-board_reqs = []
-if os.path.exists("/proc/device-tree/compatible"):
-    with open("/proc/device-tree/compatible", "rb") as f:
-        compat = f.read()
-    # Jetson Nano, TX2, Xavier, etc
-    if b"nvidia,tegra" in compat:
-        board_reqs = ["Jetson.GPIO"]
-    # Pi 5 and Earlier
-    elif (
-        b"brcm,bcm2835" in compat
-        or b"brcm,bcm2836" in compat
-        or b"brcm,bcm2837" in compat
-        or b"brcm,bcm2838" in compat
-        or b"brcm,bcm2711" in compat
-        or b"brcm,bcm2712" in compat
-    ):
-        _pyver = (sys.version_info.major, sys.version_info.minor)
-        # adafruit-lgpio provides pre-built wheels for Python 3.13+ (aarch64 + armv7l)
-        if _pyver >= (3, 13):
-            lgpio_req = "adafruit-lgpio>=0.2.2.0"
-        else:
-            lgpio_req = "lgpio>=0.2.2.0"
-        try:
-            import lgpio
-        except ImportError:
-            print(
-                "\n*** lgpio is not installed. On Raspberry Pi OS, install it with:\n"
-                "    sudo apt-get install -y python3-lgpio\n"
-                "  Then recreate your virtual environment with --system-site-packages\n"
-                "  or install adafruit-lgpio from PyPI:\n"
-                "    pip install adafruit-lgpio\n"
-            )
-        board_reqs = [
-            "rpi_ws281x>=4.0.0",
-            lgpio_req,
-            "RPi.GPIO",
-            "Adafruit-Blinka-Raspberry-Pi5-Neopixel",
-        ]
-    # BeagleBone Black, Green, PocketBeagle, BeagleBone AI, etc.
-    elif b"ti,am335x" in compat:
-        board_reqs = ["Adafruit_BBIO"]
-
 setup(
     name="Adafruit-Blinka",
     use_scm_version={
@@ -120,8 +77,7 @@
         "adafruit-circuitpython-typing",
         "sysv_ipc>=1.1.0;sys_platform=='linux' and platform_machine!='mips'",
         "toml>=0.10.2;python_version<'3.11'",
-    ]
-    + board_reqs,
+    ],
     license="MIT",
     classifiers=[
         # Trove classifiers

src/adafruit_blinka/importing.py

@@ -9,6 +9,7 @@
 * Author(s): Melissa LeBlanc-Williams
 """
 
+import sys
 
 try:
     from importlib import import_module
@@ -24,7 +25,6 @@ def import_module(module_name: str, package: str = None):
 
 from adafruit_blinka.agnostic import detector
 
-
 PLATFORM_DEPENDENCY_INSTALLS = {
     "Adafruit_BBIO": "pip install Adafruit_BBIO",
     "Jetson": "pip install Jetson.GPIO",
@@ -39,7 +39,17 @@ def import_module(module_name: str, package: str = None):
 
 def raise_for_missing_platform_dependency(error: ModuleNotFoundError):
     """Raise a helpful message for known optional platform dependencies."""
-    install_command = PLATFORM_DEPENDENCY_INSTALLS.get(error.name)
+    install_command = None
+    if sys.implementation.name == "cpython":
+        from adafruit_blinka.platform_dependencies import (
+            get_platform_requirement_for_import,
+        )
+
+        requirement = get_platform_requirement_for_import(detector, error.name)
+        if requirement is not None:
+            install_command = f"pip install {requirement}"
+    if install_command is None:
+        install_command = PLATFORM_DEPENDENCY_INSTALLS.get(error.name)
     if install_command is None:
         raise error
 

src/adafruit_blinka/platform_dependencies.py

@@ -0,0 +1,112 @@
+# SPDX-FileCopyrightText: 2026 Melissa LeBlanc-Williams for Adafruit Industries
+#
+# SPDX-License-Identifier: MIT
+
+"""Runtime installation helpers for platform-specific dependencies."""
+
+import importlib
+import importlib.util
+import subprocess
+import sys
+
+
+def get_platform_dependencies(detector, python_version=None):
+    """Return ``(import name, pip requirement)`` pairs for detected hardware."""
+    if python_version is None:
+        python_version = sys.version_info[:2]
+
+    if detector.board.any_raspberry_pi_5_board:
+        lgpio_requirement = (
+            "adafruit-lgpio>=0.2.2.0" if python_version >= (3, 13) else "lgpio>=0.2.2.0"
+        )
+        dependencies = [("lgpio", lgpio_requirement)]
+        if python_version >= (3, 11):
+            dependencies.append(
+                (
+                    "adafruit_raspberry_pi5_neopixel_write",
+                    "Adafruit-Blinka-Raspberry-Pi5-Neopixel",
+                )
+            )
+        return dependencies
+
+    if detector.board.any_raspberry_pi:
+        return [
+            ("RPi.GPIO", "RPi.GPIO"),
+            ("_rpi_ws281x", "rpi_ws281x>=4.0.0"),
+        ]
+
+    if detector.board.any_jetson_board:
+        return [("Jetson.GPIO", "Jetson.GPIO")]
+
+    if detector.chip.id == "AM33XX":
+        return [("Adafruit_BBIO", "Adafruit_BBIO>=1.2.4")]
+
+    return []
+
+
+def _module_available(module_name):
+    """Return whether an import can be resolved without importing the module."""
+    try:
+        return importlib.util.find_spec(module_name) is not None
+    except (ImportError, ModuleNotFoundError):
+        return False
+
+
+def get_missing_platform_dependencies(detector, python_version=None):
+    """Return platform requirements whose import modules are unavailable."""
+    return [
+        requirement
+        for module_name, requirement in get_platform_dependencies(
+            detector, python_version
+        )
+        if not _module_available(module_name)
+    ]
+
+
+def get_platform_requirement_for_import(detector, import_name, python_version=None):
+    """Return the detected platform's pip requirement for an import name."""
+    for module_name, requirement in get_platform_dependencies(detector, python_version):
+        if import_name in (module_name, module_name.split(".", maxsplit=1)[0]):
+            return requirement
+    return None
+
+
+def install_missing_platform_dependencies(
+    detector, python_version=None, input_func=input
+):
+    """Offer to install missing dependencies into the running Python environment."""
+    missing = get_missing_platform_dependencies(detector, python_version)
+    if not missing:
+        return False
+
+    if (
+        sys.stdin is None
+        or sys.stdout is None
+        or not (sys.stdin.isatty() and sys.stdout.isatty())
+    ):
+        return False
+
+    print("\nBlinka detected missing platform dependencies:")
+    for requirement in missing:
+        print(f"  - {requirement}")
+
+    try:
+        response = input_func(
+            "Install them into the current Python environment? [Y/n] "
+        )
+    except EOFError:
+        return False
+    if response.strip().lower() not in ("", "y", "yes"):
+        return False
+
+    command = [sys.executable, "-m", "pip", "install", *missing]
+    try:
+        subprocess.run(command, check=True)
+    except (OSError, subprocess.CalledProcessError) as error:
+        install_command = " ".join(command)
+        raise RuntimeError(
+            f"Unable to install the platform dependencies. Try: {install_command}"
+        ) from error
+
+    importlib.invalidate_caches()
+    return True

src/board.py

@@ -26,6 +26,13 @@
 
 SCL = SDA = SCLK = MOSI = MISO = None
 
+if sys.implementation.name == "cpython":
+    from adafruit_blinka.platform_dependencies import (
+        install_missing_platform_dependencies,
+    )
+
+    install_missing_platform_dependencies(detector)
+
 # Start with micropython boards as importlib isn't available on those chips:
 
 # Go through the board_list and import the first one that matches

tests/test_platform_dependencies.py

@@ -0,0 +1,134 @@
+# SPDX-FileCopyrightText: 2026 Melissa LeBlanc-Williams for Adafruit Industries
+#
+# SPDX-License-Identifier: MIT
+
+"""Tests for runtime platform dependency handling."""
+
+from types import SimpleNamespace
+
+from adafruit_blinka import platform_dependencies
+
+
+def _detector(chip_id=None, **board_values):
+    values = {
+        "any_raspberry_pi_5_board": False,
+        "any_raspberry_pi": False,
+        "any_jetson_board": False,
+        "any_beaglebone": False,
+    }
+    values.update(board_values)
+    return SimpleNamespace(
+        board=SimpleNamespace(**values), chip=SimpleNamespace(id=chip_id)
+    )
+
+
+def test_raspberry_pi_5_uses_adafruit_lgpio_on_python_313():
+    dependencies = platform_dependencies.get_platform_dependencies(
+        _detector(any_raspberry_pi_5_board=True, any_raspberry_pi=True),
+        python_version=(3, 13),
+    )
+
+    assert dependencies == [
+        ("lgpio", "adafruit-lgpio>=0.2.2.0"),
+        (
+            "adafruit_raspberry_pi5_neopixel_write",
+            "Adafruit-Blinka-Raspberry-Pi5-Neopixel",
+        ),
+    ]
+
+
+def test_raspberry_pi_5_uses_upstream_lgpio_before_python_313():
+    dependencies = platform_dependencies.get_platform_dependencies(
+        _detector(any_raspberry_pi_5_board=True, any_raspberry_pi=True),
+        python_version=(3, 12),
+    )
+
+    assert ("lgpio", "lgpio>=0.2.2.0") in dependencies
+
+
+def test_raspberry_pi_5_neopixel_requires_python_311():
+    dependencies = platform_dependencies.get_platform_dependencies(
+        _detector(any_raspberry_pi_5_board=True, any_raspberry_pi=True),
+        python_version=(3, 10),
+    )
+
+    assert all(
+        module_name != "adafruit_raspberry_pi5_neopixel_write"
+        for module_name, _ in dependencies
+    )
+
+
+def test_earlier_raspberry_pi_does_not_install_lgpio():
+    dependencies = platform_dependencies.get_platform_dependencies(
+        _detector(any_raspberry_pi=True), python_version=(3, 13)
+    )
+
+    assert dependencies == [
+        ("RPi.GPIO", "RPi.GPIO"),
+        ("_rpi_ws281x", "rpi_ws281x>=4.0.0"),
+    ]
+
+
+def test_import_requirement_uses_detected_python_version():
+    detector = _detector(any_raspberry_pi_5_board=True, any_raspberry_pi=True)
+
+    requirement = platform_dependencies.get_platform_requirement_for_import(
+        detector, "lgpio", python_version=(3, 12)
+    )
+
+    assert requirement == "lgpio>=0.2.2.0"
+
+
+def test_installer_uses_running_python(monkeypatch):
+    detector = _detector(chip_id="AM33XX", any_beaglebone=True)
+    commands = []
+
+    monkeypatch.setattr(
+        platform_dependencies,
+        "get_missing_platform_dependencies",
+        lambda *_args, **_kwargs: ["Adafruit_BBIO>=1.2.4"],
+    )
+    monkeypatch.setattr(platform_dependencies.sys.stdin, "isatty", lambda: True)
+    monkeypatch.setattr(platform_dependencies.sys.stdout, "isatty", lambda: True)
+    monkeypatch.setattr(
+        platform_dependencies.subprocess,
+        "run",
+        lambda command, check: commands.append((command, check)),
+    )
+
+    installed = platform_dependencies.install_missing_platform_dependencies(
+        detector, input_func=lambda _prompt: "y"
+    )
+
+    assert installed is True
+    assert commands == [
+        (
+            [
+                platform_dependencies.sys.executable,
+                "-m",
+                "pip",
+                "install",
+                "Adafruit_BBIO>=1.2.4",
+            ],
+            True,
+        )
+    ]
+
+
+def test_installer_skips_prompt_without_terminal(monkeypatch):
+    detector = _detector(chip_id="AM33XX", any_beaglebone=True)
+    prompted = []
+
+    monkeypatch.setattr(
+        platform_dependencies,
+        "get_missing_platform_dependencies",
+        lambda *_args, **_kwargs: ["Adafruit_BBIO>=1.2.4"],
+    )
+    monkeypatch.setattr(platform_dependencies.sys.stdin, "isatty", lambda: False)
+
+    installed = platform_dependencies.install_missing_platform_dependencies(
+        detector, input_func=prompted.append
+    )
+
+    assert installed is False
+    assert not prompted