munim-bluetooth 0.3.24 → 0.3.26

package/android/src/main/AndroidManifest.xml

@@ -13,8 +13,18 @@
   <!-- Location permissions required for BLE scanning on Android 6.0+ -->
   <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
   <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
+  <uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
+  <uses-permission android:name="android.permission.FOREGROUND_SERVICE_LOCATION" />
   
   <!-- Feature declarations -->
   <uses-feature android:name="android.hardware.bluetooth" android:required="false" />
   <uses-feature android:name="android.hardware.bluetooth_le" android:required="true" />
+
+  <application>
+    <service
+      android:name=".MunimBluetoothBackgroundService"
+      android:enabled="true"
+      android:exported="false"
+      android:foregroundServiceType="location" />
+  </application>
 </manifest>

package/android/src/main/java/com/munimbluetooth/HybridMunimBluetooth.kt

@@ -22,6 +22,7 @@ import android.bluetooth.le.ScanRecord
 import android.bluetooth.le.ScanResult
 import android.bluetooth.le.ScanSettings
 import android.content.Context
+import android.content.Intent
 import android.os.Build
 import android.os.ParcelUuid
 import android.util.Log
@@ -33,6 +34,7 @@ import com.margelo.nitro.NitroModules
 import com.margelo.nitro.core.Promise
 import com.margelo.nitro.munimbluetooth.AdvertisingDataTypes
 import com.margelo.nitro.munimbluetooth.AdvertisingOptions
+import com.margelo.nitro.munimbluetooth.BackgroundSessionOptions
 import com.margelo.nitro.munimbluetooth.CharacteristicValue
 import com.margelo.nitro.munimbluetooth.GATTCharacteristic
 import com.margelo.nitro.munimbluetooth.GATTService
@@ -61,6 +63,7 @@ class HybridMunimBluetooth : HybridMunimBluetoothSpec() {
     private var currentServiceUUIDs: Array<String> = emptyArray()
     private var currentLocalName: String? = null
     private var currentManufacturerData: String? = null
+    private var previousAdapterName: String? = null
     private var bluetoothManager: BluetoothManager? = null
     private var bluetoothAdapter: BluetoothAdapter? = null
 
@@ -111,6 +114,17 @@ class HybridMunimBluetooth : HybridMunimBluetoothSpec() {
             options.manufacturerData
         )
 
+        if (!currentLocalName.isNullOrBlank() && previousAdapterName == null) {
+            previousAdapterName = adapter.name
+        }
+        if (!currentLocalName.isNullOrBlank()) {
+            try {
+                adapter.name = currentLocalName
+            } catch (error: SecurityException) {
+                Log.w(TAG, "Unable to apply custom localName to Bluetooth adapter", error)
+            }
+        }
+
         if (!gattServerReady) {
             setServicesFromOptions(options.serviceUUIDs)
         }
@@ -143,6 +157,7 @@ class HybridMunimBluetooth : HybridMunimBluetoothSpec() {
         currentServiceUUIDs = emptyArray()
         currentLocalName = null
         currentManufacturerData = null
+        restoreAdapterName()
     }
 
     override fun setServices(services: Array<GATTService>) {
@@ -432,6 +447,67 @@ class HybridMunimBluetooth : HybridMunimBluetoothSpec() {
         return promise
     }
 
+    override fun startBackgroundSession(options: BackgroundSessionOptions) {
+        val context = NitroModules.applicationContext ?: run {
+            Log.w(TAG, "Unable to start background BLE session: application context unavailable")
+            return
+        }
+
+        val intent = Intent(context, MunimBluetoothBackgroundService::class.java).apply {
+            action = MunimBluetoothBackgroundService.ACTION_START
+            putExtra(
+                MunimBluetoothBackgroundService.EXTRA_SERVICE_UUIDS,
+                options.serviceUUIDs
+            )
+            putExtra(
+                MunimBluetoothBackgroundService.EXTRA_LOCAL_NAME,
+                options.localName
+            )
+            putExtra(
+                MunimBluetoothBackgroundService.EXTRA_ALLOW_DUPLICATES,
+                options.allowDuplicates ?: false
+            )
+            putExtra(
+                MunimBluetoothBackgroundService.EXTRA_SCAN_MODE,
+                options.scanMode?.name ?: ScanMode.LOWPOWER.name
+            )
+            putExtra(
+                MunimBluetoothBackgroundService.EXTRA_NOTIFICATION_CHANNEL_ID,
+                options.androidNotificationChannelId
+                    ?: MunimBluetoothBackgroundService.DEFAULT_CHANNEL_ID
+            )
+            putExtra(
+                MunimBluetoothBackgroundService.EXTRA_NOTIFICATION_CHANNEL_NAME,
+                options.androidNotificationChannelName
+                    ?: MunimBluetoothBackgroundService.DEFAULT_CHANNEL_NAME
+            )
+            putExtra(
+                MunimBluetoothBackgroundService.EXTRA_NOTIFICATION_TITLE,
+                options.androidNotificationTitle
+                    ?: MunimBluetoothBackgroundService.DEFAULT_NOTIFICATION_TITLE
+            )
+            putExtra(
+                MunimBluetoothBackgroundService.EXTRA_NOTIFICATION_TEXT,
+                options.androidNotificationText
+                    ?: MunimBluetoothBackgroundService.DEFAULT_NOTIFICATION_TEXT
+            )
+        }
+
+        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
+            context.startForegroundService(intent)
+        } else {
+            context.startService(intent)
+        }
+    }
+
+    override fun stopBackgroundSession() {
+        val context = NitroModules.applicationContext ?: return
+        val intent = Intent(context, MunimBluetoothBackgroundService::class.java).apply {
+            action = MunimBluetoothBackgroundService.ACTION_STOP
+        }
+        context.startService(intent)
+    }
+
     override fun addListener(eventName: String) {
         // Nitro uses JS-side listener registration. No native bookkeeping required here.
     }
@@ -938,6 +1014,17 @@ class HybridMunimBluetooth : HybridMunimBluetoothSpec() {
         gattServerReady = true
     }
 
+    private fun restoreAdapterName() {
+        val adapter = bluetoothAdapter ?: return
+        val originalName = previousAdapterName ?: return
+        try {
+            adapter.name = originalName
+        } catch (error: SecurityException) {
+            Log.w(TAG, "Unable to restore Bluetooth adapter name", error)
+        }
+        previousAdapterName = null
+    }
+
     companion object {
         private const val TAG = "HybridMunimBluetooth"
         private val CLIENT_CHARACTERISTIC_CONFIG_UUID =

package/android/src/main/java/com/munimbluetooth/MunimBluetoothBackgroundService.kt

@@ -0,0 +1,344 @@
+package com.munimbluetooth
+
+import android.app.Notification
+import android.app.NotificationChannel
+import android.app.NotificationManager
+import android.app.Service
+import android.bluetooth.BluetoothAdapter
+import android.bluetooth.BluetoothManager
+import android.bluetooth.le.AdvertiseCallback
+import android.bluetooth.le.AdvertiseData
+import android.bluetooth.le.AdvertiseSettings
+import android.bluetooth.le.BluetoothLeAdvertiser
+import android.bluetooth.le.BluetoothLeScanner
+import android.bluetooth.le.ScanCallback
+import android.bluetooth.le.ScanFilter
+import android.bluetooth.le.ScanResult
+import android.bluetooth.le.ScanSettings
+import android.content.Context
+import android.content.Intent
+import android.os.Build
+import android.os.IBinder
+import android.os.ParcelUuid
+import android.util.Log
+import com.margelo.nitro.munimbluetooth.ScanMode
+import java.util.Locale
+
+class MunimBluetoothBackgroundService : Service() {
+    private var bluetoothManager: BluetoothManager? = null
+    private var bluetoothAdapter: BluetoothAdapter? = null
+    private var advertiser: BluetoothLeAdvertiser? = null
+    private var advertiseCallback: AdvertiseCallback? = null
+    private var scanner: BluetoothLeScanner? = null
+    private var scanCallback: ScanCallback? = null
+    private var previousAdapterName: String? = null
+
+    private val discoveredDeviceIds = linkedSetOf<String>()
+    private var notificationChannelId = DEFAULT_CHANNEL_ID
+    private var notificationChannelName = DEFAULT_CHANNEL_NAME
+    private var notificationTitle = DEFAULT_NOTIFICATION_TITLE
+    private var notificationText = DEFAULT_NOTIFICATION_TEXT
+
+    override fun onBind(intent: Intent?): IBinder? = null
+
+    override fun onStartCommand(intent: Intent?, flags: Int, startId: Int): Int {
+        when (intent?.action) {
+            ACTION_STOP -> {
+                stopSelf()
+                return START_NOT_STICKY
+            }
+
+            ACTION_START -> {
+                notificationChannelId =
+                    intent.getStringExtra(EXTRA_NOTIFICATION_CHANNEL_ID)
+                        ?: DEFAULT_CHANNEL_ID
+                notificationChannelName =
+                    intent.getStringExtra(EXTRA_NOTIFICATION_CHANNEL_NAME)
+                        ?: DEFAULT_CHANNEL_NAME
+                notificationTitle =
+                    intent.getStringExtra(EXTRA_NOTIFICATION_TITLE)
+                        ?: DEFAULT_NOTIFICATION_TITLE
+                notificationText =
+                    intent.getStringExtra(EXTRA_NOTIFICATION_TEXT)
+                        ?: DEFAULT_NOTIFICATION_TEXT
+
+                startForeground(
+                    NOTIFICATION_ID,
+                    buildNotification(neighborCount = discoveredDeviceIds.size)
+                )
+
+                val serviceUUIDs =
+                    intent.getStringArrayExtra(EXTRA_SERVICE_UUIDS) ?: emptyArray()
+                val localName = intent.getStringExtra(EXTRA_LOCAL_NAME)
+                val allowDuplicates =
+                    intent.getBooleanExtra(EXTRA_ALLOW_DUPLICATES, false)
+                val scanMode = parseScanMode(
+                    intent.getStringExtra(EXTRA_SCAN_MODE) ?: ScanMode.LOWPOWER.name
+                )
+
+                startBleSession(
+                    serviceUUIDs = serviceUUIDs,
+                    localName = localName,
+                    allowDuplicates = allowDuplicates,
+                    scanMode = scanMode
+                )
+                return START_STICKY
+            }
+        }
+
+        return START_NOT_STICKY
+    }
+
+    override fun onDestroy() {
+        stopBleSession()
+        super.onDestroy()
+    }
+
+    private fun startBleSession(
+        serviceUUIDs: Array<String>,
+        localName: String?,
+        allowDuplicates: Boolean,
+        scanMode: ScanMode
+    ) {
+        bluetoothManager =
+            applicationContext.getSystemService(Context.BLUETOOTH_SERVICE) as? BluetoothManager
+        bluetoothAdapter = bluetoothManager?.adapter
+
+        val adapter = bluetoothAdapter
+        if (adapter == null || !adapter.isEnabled) {
+            Log.w(TAG, "Unable to start background BLE session: Bluetooth unavailable")
+            stopSelf()
+            return
+        }
+
+        if (!localName.isNullOrBlank() && previousAdapterName == null) {
+            previousAdapterName = adapter.name
+            try {
+                adapter.name = localName
+            } catch (error: SecurityException) {
+                Log.w(TAG, "Unable to set adapter name for background advertising", error)
+            }
+        }
+
+        startAdvertising(adapter, serviceUUIDs, !localName.isNullOrBlank())
+        startScan(adapter, serviceUUIDs, allowDuplicates, scanMode)
+    }
+
+    private fun stopBleSession() {
+        scanCallback?.let { callback ->
+            try {
+                scanner?.stopScan(callback)
+            } catch (error: SecurityException) {
+                Log.w(TAG, "Unable to stop background scan cleanly", error)
+            }
+        }
+        scanCallback = null
+        scanner = null
+
+        advertiseCallback?.let { callback ->
+            try {
+                advertiser?.stopAdvertising(callback)
+            } catch (error: SecurityException) {
+                Log.w(TAG, "Unable to stop background advertising cleanly", error)
+            }
+        }
+        advertiseCallback = null
+        advertiser = null
+
+        val adapter = bluetoothAdapter
+        val previousName = previousAdapterName
+        if (adapter != null && previousName != null) {
+            try {
+                adapter.name = previousName
+            } catch (error: SecurityException) {
+                Log.w(TAG, "Unable to restore adapter name", error)
+            }
+        }
+        previousAdapterName = null
+        discoveredDeviceIds.clear()
+    }
+
+    private fun startAdvertising(
+        adapter: BluetoothAdapter,
+        serviceUUIDs: Array<String>,
+        includeDeviceName: Boolean
+    ) {
+        val activeAdvertiser = adapter.bluetoothLeAdvertiser ?: run {
+            Log.w(TAG, "Bluetooth advertiser unavailable for background session")
+            return
+        }
+        advertiser = activeAdvertiser
+
+        val data = AdvertiseData.Builder()
+            .setIncludeDeviceName(includeDeviceName)
+
+        serviceUUIDs.forEach { uuid ->
+            runCatching { ParcelUuid.fromString(uuid) }.getOrNull()?.let(data::addServiceUuid)
+        }
+
+        val settings = AdvertiseSettings.Builder()
+            .setAdvertiseMode(AdvertiseSettings.ADVERTISE_MODE_LOW_POWER)
+            .setConnectable(true)
+            .setTimeout(0)
+            .setTxPowerLevel(AdvertiseSettings.ADVERTISE_TX_POWER_MEDIUM)
+            .build()
+
+        advertiseCallback = object : AdvertiseCallback() {
+            override fun onStartSuccess(settingsInEffect: AdvertiseSettings) {
+                Log.i(TAG, "Background advertising started")
+            }
+
+            override fun onStartFailure(errorCode: Int) {
+                Log.e(TAG, "Background advertising failed: $errorCode")
+            }
+        }
+
+        activeAdvertiser.startAdvertising(settings, data.build(), advertiseCallback)
+    }
+
+    private fun startScan(
+        adapter: BluetoothAdapter,
+        serviceUUIDs: Array<String>,
+        allowDuplicates: Boolean,
+        scanMode: ScanMode
+    ) {
+        val activeScanner = adapter.bluetoothLeScanner ?: run {
+            Log.w(TAG, "Bluetooth scanner unavailable for background session")
+            return
+        }
+        scanner = activeScanner
+
+        val filters = serviceUUIDs.mapNotNull { uuid ->
+            runCatching {
+                ScanFilter.Builder()
+                    .setServiceUuid(ParcelUuid.fromString(uuid))
+                    .build()
+            }.getOrNull()
+        }
+
+        val androidScanMode = when (scanMode) {
+            ScanMode.LOWLATENCY -> ScanSettings.SCAN_MODE_LOW_LATENCY
+            ScanMode.BALANCED -> ScanSettings.SCAN_MODE_BALANCED
+            ScanMode.LOWPOWER -> ScanSettings.SCAN_MODE_LOW_POWER
+        }
+
+        val settingsBuilder = ScanSettings.Builder().setScanMode(androidScanMode)
+        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.M) {
+            settingsBuilder.setCallbackType(ScanSettings.CALLBACK_TYPE_ALL_MATCHES)
+            settingsBuilder.setMatchMode(ScanSettings.MATCH_MODE_STICKY)
+        }
+
+        scanCallback = object : ScanCallback() {
+            override fun onScanResult(callbackType: Int, result: ScanResult) {
+                handleScanResult(result, allowDuplicates)
+            }
+
+            override fun onBatchScanResults(results: MutableList<ScanResult>) {
+                results.forEach { handleScanResult(it, allowDuplicates) }
+            }
+
+            override fun onScanFailed(errorCode: Int) {
+                Log.e(TAG, "Background scan failed: $errorCode")
+            }
+        }
+
+        activeScanner.startScan(filters, settingsBuilder.build(), scanCallback)
+    }
+
+    private fun handleScanResult(result: ScanResult, allowDuplicates: Boolean) {
+        val deviceId = result.device.address ?: return
+        if (!allowDuplicates && !discoveredDeviceIds.add(deviceId)) {
+            return
+        }
+        if (allowDuplicates) {
+            discoveredDeviceIds.add(deviceId)
+        }
+
+        updateForegroundNotification()
+    }
+
+    private fun updateForegroundNotification() {
+        val manager = getSystemService(Context.NOTIFICATION_SERVICE) as? NotificationManager
+        manager?.notify(
+            NOTIFICATION_ID,
+            buildNotification(neighborCount = discoveredDeviceIds.size)
+        )
+    }
+
+    private fun buildNotification(neighborCount: Int): Notification {
+        ensureNotificationChannel()
+
+        val text = if (neighborCount <= 0) {
+            notificationText
+        } else {
+            String.format(
+                Locale.US,
+                "%s (%d nearby)",
+                notificationText,
+                neighborCount
+            )
+        }
+
+        val builder = if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
+            Notification.Builder(this, notificationChannelId)
+        } else {
+            Notification.Builder(this)
+        }
+
+        return builder
+            .setContentTitle(notificationTitle)
+            .setContentText(text)
+            .setSmallIcon(android.R.drawable.stat_sys_data_bluetooth)
+            .setOngoing(true)
+            .setOnlyAlertOnce(true)
+            .setForegroundServiceBehaviorCompat()
+            .build()
+    }
+
+    private fun Notification.Builder.setForegroundServiceBehaviorCompat(): Notification.Builder {
+        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.S) {
+            setForegroundServiceBehavior(Notification.FOREGROUND_SERVICE_IMMEDIATE)
+        }
+        return this
+    }
+
+    private fun ensureNotificationChannel() {
+        if (Build.VERSION.SDK_INT < Build.VERSION_CODES.O) {
+            return
+        }
+
+        val manager = getSystemService(Context.NOTIFICATION_SERVICE) as? NotificationManager
+        val channel = NotificationChannel(
+            notificationChannelId,
+            notificationChannelName,
+            NotificationManager.IMPORTANCE_LOW
+        )
+        manager?.createNotificationChannel(channel)
+    }
+
+    private fun parseScanMode(rawValue: String): ScanMode {
+        return runCatching { ScanMode.valueOf(rawValue) }.getOrElse { ScanMode.LOWPOWER }
+    }
+
+    companion object {
+        const val ACTION_START = "com.munimbluetooth.action.START_BACKGROUND_SESSION"
+        const val ACTION_STOP = "com.munimbluetooth.action.STOP_BACKGROUND_SESSION"
+
+        const val EXTRA_SERVICE_UUIDS = "serviceUUIDs"
+        const val EXTRA_LOCAL_NAME = "localName"
+        const val EXTRA_ALLOW_DUPLICATES = "allowDuplicates"
+        const val EXTRA_SCAN_MODE = "scanMode"
+        const val EXTRA_NOTIFICATION_CHANNEL_ID = "notificationChannelId"
+        const val EXTRA_NOTIFICATION_CHANNEL_NAME = "notificationChannelName"
+        const val EXTRA_NOTIFICATION_TITLE = "notificationTitle"
+        const val EXTRA_NOTIFICATION_TEXT = "notificationText"
+
+        const val DEFAULT_CHANNEL_ID = "munim-bluetooth-background"
+        const val DEFAULT_CHANNEL_NAME = "Bluetooth background session"
+        const val DEFAULT_NOTIFICATION_TITLE = "Bluetooth nearby mode"
+        const val DEFAULT_NOTIFICATION_TEXT = "Scanning for nearby Bluetooth devices"
+
+        private const val NOTIFICATION_ID = 48231
+        private const val TAG = "MunimBluetoothBgSvc"
+    }
+}