Bluetooth Permissions

Bluetooth is a sensitive capability that requires explicit permissions from the operating system and, in many cases, the user. SimpleBLE attempts to simplify this, but you still need to configure your application correctly.

Desktop Platforms

Windows

Generally, Windows doesn't require special manifest entries for Bluetooth if you're building a standard Win32 application. However, users must have Bluetooth enabled in the system settings.

Note that if you attempt to pair with a device, Windows will typically show a system notification or pop-up asking the user to confirm the pairing request.

macOS

Starting with macOS 10.15 (Catalina), applications must include the NSBluetoothAlwaysUsageDescription key in their Info.plist file. This key should contain a string explaining why the app needs Bluetooth access.

<key>NSBluetoothAlwaysUsageDescription</key>
<string>This app needs Bluetooth access to connect to your smart device.</string>

The first time your application attempts to use Bluetooth, the operating system will automatically prompt the user to grant access using the description provided above.

If your app targets older versions of macOS, you might also need NSBluetoothPeripheralUsageDescription.

Similar to Windows, any pairing requests will trigger a macOS system UI that the user must interact with to complete the process.

Linux

On Linux, permissions are usually handled by the bluetooth group or via D-Bus policies. Users might need to be part of the lp or bluetooth group depending on the distribution.

Mobile Platforms

Android

Android has the most complex permission model for Bluetooth. Depending on the API level, you need different permissions in your AndroidManifest.xml:

For all versions:

<uses-permission android:name="android.permission.BLUETOOTH" />
<uses-permission android:name="android.permission.BLUETOOTH_ADMIN" />

For Android 12 (API 31) and above:

<uses-permission android:name="android.permission.BLUETOOTH_SCAN" />
<uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />
<uses-permission android:name="android.permission.BLUETOOTH_ADVERTISE" />

Additionally, you must request these permissions at runtime. SimpleDroidBLE provides helpers for this.

Note on Location: On many Android versions, ACCESS_FINE_LOCATION or ACCESS_COARSE_LOCATION is required to perform Bluetooth scans because beacons can be used to infer the user's location.

iOS

Similar to macOS, iOS requires the NSBluetoothAlwaysUsageDescription in the Info.plist. You must also request permission at runtime, which typically happens automatically the first time you try to use the Bluetooth adapter.

Checking Permission State

In SimpleBLE, you can check if Bluetooth is available and permissions are granted using:

if (!SimpleBLE::Adapter::bluetooth_enabled()) {
    // Bluetooth is off or permissions are missing
}

On Android, you should use the platform-specific helpers to request permissions before calling any SimpleBLE functions.