Add Android backend using Chaquopy/Briefcase

.github/workflows/build_and_test.yml

@@ -89,7 +89,7 @@ jobs:
             export FORCE_COLOR=1
             export CI=true
             export GITHUB_ACTIONS=true
-            uv run --python ${{ matrix.python-version }} pytest -v tests --bleak-bluez-vhci -v --cov-report=xml --cov-report=html:../.htmlcov --junitxml=junit.xml -o junit_family=legacy -o cache_dir=../.pytest_cache
+            uv run --python ${{ matrix.python-version }} --no-dev --group test pytest -v tests --bleak-bluez-vhci -v --cov-report=xml --cov-report=html:../.htmlcov --junitxml=junit.xml -o junit_family=legacy -o cache_dir=../.pytest_cache
           '
 
       - name: Upload coverage reports to Codecov
@@ -106,3 +106,80 @@ jobs:
           report_type: test_results
           flags: bluez-integration-py${{ matrix.python-version }}
           token: ${{ secrets.CODECOV_TOKEN }}
+
+  integration_tests_android:
+    name: "Android integration tests"
+    runs-on: ubuntu-24.04
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: [
+          "3.13",
+          # some binary dependencies of bumble are not yet available for 3.14, like cryptography or aiohttp
+          # "3.14"
+        ]
+    env:
+      FORCE_COLOR: "1"
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install the latest version of uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          version: "latest"
+          python-version: ${{ matrix.python-version }}
+          activate-environment: true
+
+      - name: Setup Environment
+        run: |
+          # Use GitHub's preinstalled JDK 17 for Android builds
+          echo JAVA_HOME="${JAVA_HOME_17_X64:-$JAVA_HOME_17_arm64}" | tee -a ${GITHUB_ENV}
+          # Enable KVM permissions for the emulator
+          echo 'KERNEL=="kvm", GROUP="kvm", MODE="0666", OPTIONS+="static_node=kvm"' \
+            | sudo tee /etc/udev/rules.d/99-kvm4all.rules
+          sudo udevadm control --reload-rules
+          sudo udevadm trigger --name-match=kvm
+
+      - name: Cache build dependencies
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.cache/briefcase
+            ~/.gradle/wrapper/dists
+            ~/.gradle/caches
+            /usr/local/lib/android/sdk/cmdline-tools/19.0
+            /usr/local/lib/android/sdk/emulator
+            /usr/local/lib/android/sdk/system-images/android-31
+          key: build-deps-${{ runner.os }}-${{ hashFiles('testbed/pyproject.toml') }}
+          restore-keys: |
+            build-deps-${{ runner.os }}-
+
+      - name: Run App
+        run: uv run testbed/run_android_tests_emulator.py --ci
+
+      - name: Upload coverage reports to Codecov
+        uses: codecov/codecov-action@v5
+        with:
+          report_type: coverage
+          flags: android-integration-py${{ matrix.python-version }}
+          token: ${{ secrets.CODECOV_TOKEN }}
+
+      - name: Upload test results to Codecov
+        if: ${{ !cancelled() }}
+        uses: codecov/codecov-action@v5
+        with:
+          report_type: test_results
+          flags: android-integration-py${{ matrix.python-version }}
+          token: ${{ secrets.CODECOV_TOKEN }}
+
+      - name: Type checking
+        # We don't do this in the lint job because we have conditionals
+        # on both the platform and the Python version in the code, so we
+        # need to check each matrix combination.
+        run: |
+          # For pyright a new release is missing that includes https://github.com/microsoft/pyright/pull/11221
+          # When building pyright from main locally, it works.
+          # uv tool install pyright
+          # uv run pyright --project pyrightconfig-android.json
+          uv tool install mypy
+          uv run mypy --config-file=mypy-android.ini

.gitignore

@@ -51,6 +51,7 @@ nosetests.xml
 coverage.xml
 *,cover
 .hypothesis/
+junit.xml
 
 # Integration test VM
 .alpine-vm-build/

CHANGELOG.rst

@@ -28,6 +28,7 @@ Added
 * Added ``bleak.exc.BleakGATTProtocolError`` and ``bleak.exc.BleakGATTProtocolErrorCode`` classes.
 * Added type hints and documentation for ``use_cached`` kwarg for ``read_gatt_char()`` and ``read_gatt_descriptor()`` methods in ``BleakClient``.
 * Added support for ``"use_cached"`` kwarg to ``read_gatt_char()`` and ``read_gatt_descriptor()`` methods in BlueZ backend.
+* Added new Android backend using Chaquopy/briefcase.
 
 Changed
 -------

bleak/backends/__init__.py

@@ -27,6 +27,11 @@ class BleakBackend(str, enum.Enum):
     Python for Android backend.
     """
 
+    ANDROID = "android"
+    """
+    Android backend using chaquopy.
+    """
+
     BLUEZ_DBUS = "bluez_dbus"
     """
     BlueZ D-Bus backend for Linux.
@@ -57,6 +62,9 @@ def get_default_backend() -> BleakBackend:
     if os.environ.get("P4A_BOOTSTRAP") is not None:
         return BleakBackend.P4ANDROID
 
+    if sys.platform == "android":
+        return BleakBackend.ANDROID
+
     if platform.system() == "Linux":
         return BleakBackend.BLUEZ_DBUS
 

bleak/backends/android/broadcast.py

@@ -0,0 +1,81 @@
+from __future__ import annotations
+
+import sys
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    if sys.platform != "android":
+        assert False, "This backend is only available on Android"
+
+import logging
+from typing import Callable
+
+from android.content import BroadcastReceiver as _BroadcastReceiver
+from android.content import Context, Intent, IntentFilter
+from android.os import Handler, HandlerThread
+from java import Override, jvoid, static_proxy
+
+from bleak.backends._utils import external_thread_callback
+from bleak.backends.android.utils import context
+
+logger = logging.getLogger(__name__)
+
+
+# Copied BroadcastReceiver logic from python-for-android and adapted it to chaquopy.
+# See https://github.com/kivy/python-for-android/blob/6f3ab805972e0d9531e3a207a6bc51c0effd8eb9/pythonforandroid/recipes/android/src/android/broadcast.py
+class BroadcastReceiver(static_proxy(_BroadcastReceiver)):  # type: ignore[misc]
+    def __init__(
+        self,
+        callback: Callable[[Context, Intent], None],
+        actions: list[str] | None = None,
+        categories: list[str] | None = None,
+    ):
+        super(BroadcastReceiver, self).__init__()
+        self.context = context
+        self.callback = callback
+
+        if not actions and not categories:
+            raise Exception("You need to define at least actions or categories")
+
+        def _expand_partial_name(partial_name: str):
+            if "." in partial_name:
+                return partial_name  # Its actually a full dotted name
+            else:
+                name = "ACTION_{}".format(partial_name.upper())
+                if not hasattr(Intent, name):
+                    raise Exception("The intent {} does not exist".format(name))
+                return getattr(Intent, name)
+
+        # resolve actions/categories first
+        resolved_actions = [_expand_partial_name(x) for x in actions or []]
+        resolved_categories = [_expand_partial_name(x) for x in categories or []]
+
+        # create a thread for handling events from the receiver
+        self.handlerthread = HandlerThread("handlerthread")
+
+        # create a listener
+        self.receiver_filter = IntentFilter()
+        for x in resolved_actions:
+            self.receiver_filter.addAction(x)
+        for x in resolved_categories:
+            self.receiver_filter.addCategory(x)
+
+    def start(self):
+        self.handlerthread.start()
+        self.handler = Handler(self.handlerthread.getLooper())
+        self.context.registerReceiver(
+            self,
+            self.receiver_filter,
+            None,  # type: ignore
+            self.handler,
+        )
+
+    def stop(self):
+        self.context.unregisterReceiver(self)
+        self.handlerthread.quit()
+
+    @Override(jvoid, [Context, Intent])
+    @external_thread_callback
+    def onReceive(self, context: Context, intent: Intent):
+        logger.debug(f"BroadcastReceiver received intent: {intent}")
+        self.callback(context, intent)