Add the ability to specify bluetooth permission

changes/2522.bugfix.md

@@ -0,0 +1 @@
+Permission disabling is now handled correctly

changes/2522.feature.md

@@ -0,0 +1 @@
+Add the ability to specify bluetooth permission.

docs/en/reference/configuration.md

@@ -379,6 +379,10 @@ Applications may also need to declare the permissions they require. Permissions
 
 Briefcase maintains a set of cross-platform permissions:
 
+#### `permission.bluetooth`
+
+Permission to connect to an external device via Bluetooth.
+
 #### `permission.camera`
 
 Permission to access the camera to take photos or video.

docs/en/reference/platforms/android/gradle.md

@@ -239,8 +239,8 @@ A property whose sub-properties define the platform-specific permissions that wi
 
 For example, specifying:
 
-```python
-permission."android.permission.HIGH_SAMPLING_RATE_SENSORS" = true
+```toml
+permission."android.permission.HIGH_SAMPLING_RATE_SENSORS" = {}
 ```
 
 will result in an `AndroidManifest.xml` declaration of:
@@ -249,6 +249,22 @@ will result in an `AndroidManifest.xml` declaration of:
 <uses-permission android:name="android.permission.HIGH_SAMPLING_RATE_SENSORS">
 ```
 
+Using a dictionary as a value allows you to specify additional attributes that detail, for example, the API version or combined constraints.
+
+For example, specifying:
+
+```toml
+permission."android.permission.BLUETOOTH_ADMIN" = {"android:maxSdkVersion"= "30"}
+permission."android.permission.BLUETOOTH_SCAN" = {"android:usesPermissionFlags"= "neverForLocation"}
+```
+
+will result in an `AndroidManifest.xml` declaration of:
+
+```xml
+<uses-permission android:name="android.permission.BLUETOOTH_ADMIN" android:maxSdkVersion="30"/>
+<uses-permission android:name="android.permission.BLUETOOTH_SCAN" android:usesPermissionFlags="neverForLocation"/>
+```
+
 ### `target_os_version`
 
 The API level that the app will target. This controls the version of the Android SDK that is used to build your app (by setting the `compileSdkVersion` for your app), and the forwards compatibility behavioral changes your app will enable (by setting the `targetSdkVersion` setting). This is *not* the Android version; it is the underlying API level. For example, Android 15 uses an API level of 35; if you wanted to specify Android 15 as your target API level, you would define `target_os_version = "35"`.
@@ -270,6 +286,7 @@ If you want to manually specify a version code by defining `version_code` in you
 
 Briefcase cross platform permissions map to `<uses-permission>` declarations in the app's `AppManifest.xml`:
 
+* [`permission.bluetooth`][permissionbluetooth]: `android.permission.BLUETOOTH` and other (see below for details)
 * [`permission.camera`][permissioncamera]: `android.permission.CAMERA`
 * [`permission.microphone`][permissioncamera]: `android.permission.RECORD_AUDIO`
 * [`permission.coarse_location`][permissioncoarse_location]: `android.permission.ACCESS_COARSE_LOCATION`
@@ -279,6 +296,15 @@ Briefcase cross platform permissions map to `<uses-permission>` declarations in
 
 Every application will be automatically granted the `android.permission.INTERNET` and `android.permission.NETWORK_STATE` permissions.
 
+Specifying a [`permission.bluetooth`][permissionbluetooth] permission will result in the following `<uses-permission>` declarations in the app's `AppManifest.xml`:
+
+* `android.permission.ACCESS_COARSE_LOCATION`, with an attribute declaration of `android:maxSdkVersion="30"`. If `permission.coarse_location` is defined, the attribute declaration will be omitted
+* `android.permission.ACCESS_FINE_LOCATION`, with an attribute declaration of `android:maxSdkVersion="30"`. If `permission.coarse_location` is defined, the attribute declaration will be omitted
+* `android.permission.BLUETOOTH`, with an attribute declaration of `android:maxSdkVersion="30"`
+* `android.permission.BLUETOOTH_ADMIN"`, with an attribute declaration of `android:maxSdkVersion="30"`
+* `android.permission.BLUETOOTH_CONNECT`
+* `android.permission.BLUETOOTH_SCAN`, with an attribute declaration of `android:usesPermissionFlags="neverForLocation"`. If `permission.fine_location` or `permission.coarse_location` is defined, the attribute declaration will be omitted.
+
 Specifying a [`permission.camera`][permissioncamera] permission will result in the following non-required [`feature`][] definitions being implicitly added to your app:
 
 * `android.hardware.camera`,

docs/en/reference/platforms/iOS/xcode.md

@@ -121,6 +121,7 @@ The minimum iOS version that the app will support. This controls the value of `I
 
 Briefcase cross-platform permissions map to the following [`info`][] keys:
 
+* [`permission.bluetooth`][permissionbluetooth]: `NSBluetoothAlwaysUsageDescription`
 * [`permission.camera`][permissioncamera]: `NSCameraUsageDescription`
 * [`permission.microphone`][permissionmicrophone]: `NSMicrophoneUsageDescription`
 * [`permission.coarse_location`][permissioncoarse_location]:

docs/en/reference/platforms/macOS/index.md

@@ -218,12 +218,11 @@ For more details on macOS document type declarations, see the following web page
 
 ## Permissions
 
-### `macOS`
-
 Briefcase cross platform permissions map to a combination of [`info`][] and [`entitlement`][] keys:
 
-- [`permission.microphone`][permissionmicrophone]: an [`info`][] entry for `NSMicrophoneUsageDescription`; and an [`entitlement`][] of `com.apple.security.device.audio-input`
+- [`permission.bluetooth`][permissionbluetooth]: an [`info`][] entry for `NSBluetoothAlwaysUsageDescription`; and an [`entitlement`][] of `com.apple.security.device.bluetooth`
 - [`permission.camera`][permissioncamera]: an [`info`][] entry for `NSCameraUsageDescription`; and an [`entitlement`][] of `com.apple.security.device.camera`
+- [`permission.microphone`][permissionmicrophone]: an [`info`][] entry for `NSMicrophoneUsageDescription`; and an [`entitlement`][] of `com.apple.security.device.audio-input`
 - [`permission.coarse_location`][permissioncoarse_location]: an [`info`][] entry for `NSLocationUsageDescription` (ignored if [`permission.background_location`][permissionbackground_location] or [`permission.fine_location`][permissionfine_location] is defined); plus an entitlement of `com.apple.security.personal-information.location`
 - [`permission.fine_location`][permissionfine_location]: an [`info`][] entry for `NSLocationUsageDescription`(ignored if [`permission.background_location`][permissionbackground_location] is defined); plus an [`entitlement`][] of `com.apple.security.personal-information.location`
 - [`permission.background_location`][permissionbackground_location]: an [`info`][] entry for `NSLocationUsageDescription`; plus an [`entitlement`][] of `com.apple.security.personal-information.location`

src/briefcase/commands/create.py

@@ -192,6 +192,7 @@ def _x_permissions(self, app: AppConfig):
         return {
             key: app.permission.pop(key, None)
             for key in [
+                "bluetooth",
                 "camera",
                 "microphone",
                 "coarse_location",

src/briefcase/platforms/android/gradle.py

@@ -239,41 +239,67 @@ def permissions_context(self, app: AppConfig, x_permissions: dict[str, str]):
         """
         # Default permissions for all Android apps
         permissions = {
-            "android.permission.INTERNET": True,
-            "android.permission.ACCESS_NETWORK_STATE": True,
+            "android.permission.INTERNET": {},
+            "android.permission.ACCESS_NETWORK_STATE": {},
         }
 
         # Default feature usage for all Android apps
         features = {}
 
+        if x_permissions["bluetooth"]:
+            permissions["android.permission.ACCESS_COARSE_LOCATION"] = {
+                "android:maxSdkVersion": "30"
+            }
+            permissions["android.permission.ACCESS_FINE_LOCATION"] = {
+                "android:maxSdkVersion": "30"
+            }
+            permissions["android.permission.BLUETOOTH"] = {
+                "android:maxSdkVersion": "30"
+            }
+            permissions["android.permission.BLUETOOTH_ADMIN"] = {
+                "android:maxSdkVersion": "30"
+            }
+            permissions["android.permission.BLUETOOTH_CONNECT"] = {}
+            permissions["android.permission.BLUETOOTH_SCAN"] = {
+                "android:usesPermissionFlags": "neverForLocation"
+            }
+
         if x_permissions["camera"]:
-            permissions["android.permission.CAMERA"] = True
+            permissions["android.permission.CAMERA"] = {}
             features["android.hardware.camera"] = False
             features["android.hardware.camera.any"] = False
             features["android.hardware.camera.front"] = False
             features["android.hardware.camera.external"] = False
             features["android.hardware.camera.autofocus"] = False
 
         if x_permissions["microphone"]:
-            permissions["android.permission.RECORD_AUDIO"] = True
+            permissions["android.permission.RECORD_AUDIO"] = {}
 
         if x_permissions["fine_location"]:
-            permissions["android.permission.ACCESS_FINE_LOCATION"] = True
+            permissions["android.permission.ACCESS_FINE_LOCATION"] = {}
             features["android.hardware.location.network"] = False
             features["android.hardware.location.gps"] = False
+            # We're good with the location. So we can also use BLUETOOTH_SCAN.
+            bt_scan_perm = permissions.get("android.permission.BLUETOOTH_SCAN")
+            if bt_scan_perm:
+                bt_scan_perm.pop("android:usesPermissionFlags", None)
 
         if x_permissions["coarse_location"]:
-            permissions["android.permission.ACCESS_COARSE_LOCATION"] = True
+            permissions["android.permission.ACCESS_COARSE_LOCATION"] = {}
             features["android.hardware.location.network"] = False
             features["android.hardware.location.gps"] = False
+            # We're good with the location. So we can also use BLUETOOTH_SCAN.
+            bt_scan_perm = permissions.get("android.permission.BLUETOOTH_SCAN")
+            if bt_scan_perm:
+                bt_scan_perm.pop("android:usesPermissionFlags", None)
 
         if x_permissions["background_location"]:
-            permissions["android.permission.ACCESS_BACKGROUND_LOCATION"] = True
+            permissions["android.permission.ACCESS_BACKGROUND_LOCATION"] = {}
             features["android.hardware.location.network"] = False
             features["android.hardware.location.gps"] = False
 
         if x_permissions["photo_library"]:
-            permissions["android.permission.READ_MEDIA_VISUAL_USER_SELECTED"] = True
+            permissions["android.permission.READ_MEDIA_VISUAL_USER_SELECTED"] = {}
 
         # Override any permission and entitlement definitions
         # with the platform-specific definitions

src/briefcase/platforms/iOS/xcode.py

@@ -270,6 +270,8 @@ def permissions_context(self, app: AppConfig, x_permissions: dict[str, str]):
         # The collection of info.plist entries
         info = {}
 
+        if x_permissions["bluetooth"]:
+            info["NSBluetoothAlwaysUsageDescription"] = x_permissions["bluetooth"]
         if x_permissions["camera"]:
             info["NSCameraUsageDescription"] = x_permissions["camera"]
         if x_permissions["microphone"]:

src/briefcase/platforms/macOS/__init__.py

@@ -377,6 +377,9 @@ def permissions_context(self, app: AppConfig, cross_platform: dict[str, str]):
             "com.apple.security.cs.disable-library-validation": True,
         }
 
+        if cross_platform["bluetooth"]:
+            entitlements["com.apple.security.device.bluetooth"] = True
+            info["NSBluetoothAlwaysUsageDescription"] = cross_platform["bluetooth"]
         if cross_platform["camera"]:
             entitlements["com.apple.security.device.camera"] = True
             info["NSCameraUsageDescription"] = cross_platform["camera"]