BluetoothAdapter — mi ez, metódusok és Bluetooth-kezelés Androidban

Mi az a BluetoothAdapter: lényeg és példány lekérése

BluetoothAdapter az Android-eszköz fizikai Bluetooth-adapterét képviseli. Minden eszköznek pontosan egy adaptere van (kivétel — az Android Automotive több Bluetooth-chipsel, ahol a BluetoothManager.getAdapterList() használatos). A BluetoothAdapter beágyazza a rádió állapotát: STATE_OFF (0), STATE_TURNING_ON (1), STATE_ON (2), STATE_TURNING_OFF (3). Az állapot az ACTION_STATE_CHANGED BroadcastReceiver-en keresztül követhető.

A BluetoothAdapter-példány lekérése az első lépés minden BLE-alkalmazásban Androidban. Az ajánlott metódus — a BluetoothManager.getAdapter() segítségével API 18+-tól. Alternatíva — a BluetoothAdapter.getDefaultAdapter() statikus metódus, amely API 5-től működik, de kevésbé rugalmas. Mindkét metódus null értéket ad vissza, ha az eszköz nem rendelkezik Bluetooth-modullal (Wi-Fi-only táblagépek, emulátor). A null ellenőrzése kötelező: az alkalmazásnak megfelelően be kell fejeznie a működést vagy ki kell kapcsolnia a BLE-funkciókat.

// BluetoothAdapter lekérése (ajánlott)
import android.bluetooth.BluetoothAdapter
import android.bluetooth.BluetoothManager
import android.content.Context

class BluetoothHelper(context: Context) {

    private val bluetoothAdapter: BluetoothAdapter?

    init {
        // 1. módszer: BluetoothManager segítségével (API 18+)
        val manager = context.getSystemService(Context.BLUETOOTH_SERVICE)
                as BluetoothManager?
        bluetoothAdapter = manager?.adapter

        // 2. módszer: statikus metódussal (API 5+)
        // val adapter = BluetoothAdapter.getDefaultAdapter()

        // Null ellenőrzés
        if (bluetoothAdapter == null) {
            // Az eszköz nem támogatja a Bluetooth-t
        }
    }

    // Bluetooth állapotának ellenőrzése
    fun isBluetoothEnabled(): Boolean {
        return bluetoothAdapter?.isEnabled == true
    }

    // Adapter információ lekérése
    fun getAdapterInfo(): Map<String, String> {
        return mapOf(
            "name" to (bluetoothAdapter?.name ?: "N/A"),
            "address" to (bluetoothAdapter?.address ?: "N/A"),
            "state" to (bluetoothAdapter?.state?.toString() ?: "N/A"),
            "scanMode" to (bluetoothAdapter?.scanMode?.toString() ?: "N/A")
        )
    }
}

A BluetoothHelper osztály bemutatja a BluetoothAdapter lekérését a BluetoothManager-en keresztül a későbbi null ellenőrzéssel. Az isBluetoothEnabled ellenőrzi az isEnabled-et — kötelező feltétel bármilyen BLE-művelet előtt. A getAdapterInfo visszaadja az eszköz nevét, MAC-címét, állapotát és láthatósági módját. Fontos: Android 10+-ban (API 29+) a rendszerszolgáltatás hamis MAC-címet (02:00:00:00:00:00) ad vissza, ha az alkalmazás nem rendelkezik BLUETOOTH_ADMIN és ACCESS_FINE_LOCATION engedéllyel.

A BluetoothAdapter fő metódusai: enable, disable, getState, getAddress

BluetoothAdapter metódusokat biztosít a Bluetooth-rádió kezeléséhez. Az enable() és disable() be- és kikapcsolja a Bluetooth-t. Mindkét metódus BLUETOOTH_ADMIN engedélyt igényel, és aszinkron módon hajtódik végre: az enable() meghívása után a rendszer elindítja a rádió bekapcsolásának folyamatát, az állapot a BluetoothAdapter.ACTION_STATE_CHANGED akcióval rendelkező BroadcastReceiver-en keresztül követhető. Android 10+-tól az enable() és disable() további rendszerengedélyt igényel — a hétköznapi alkalmazások nem tudják programozottan kezelni a Bluetooth-t a felhasználói párbeszédablak nélkül.

getState() visszaadja az adapter aktuális állapotát: STATE_OFF (10), STATE_TURNING_ON (11), STATE_ON (12), STATE_TURNING_OFF (13). getAddress() visszaadja a Bluetooth-adapter MAC-címét. Android 6+-ban a MAC-cím lekéréséhez ACCESS_FINE_LOCATION (vagy API 31+ esetén ACCESS_COARSE_LOCATION) szükséges. Android 10+-ban a getAddress() a konstans 02:00:00:00:00:00 címet adja vissza — a valódi cím nem érhető el a nyilvános API-n keresztül.

getScanMode() meghatározza az adapter láthatósági módját: SCAN_MODE_NONE (nem látható), SCAN_MODE_CONNECTABLE (látható a csatlakoztatottak számára), SCAN_MODE_CONNECTABLE_DISCOVERABLE (mindenki számára látható). A láthatósági mód időben korlátozott (általában 60–300 másodperc) a biztonság érdekében. A mód beállítása a setScanMode() segítségével BLUETOOTH_ADMIN-t és rendszerengedélyt igényel Android 10+-ban.

Eszközök szkennelése: startDiscovery és BluetoothLeScanner

BluetoothAdapter kétféle szkennelést támogat. A klasszikus Bluetooth-szkennelés (BR/EDR) a startDiscovery() segítségével indul — minden típusú Bluetooth-eszközt észlel, beleértve a telefonokat és headseteket. Az eredmények a BluetoothDevice.ACTION_FOUND akcióval rendelkező BroadcastReceiver-en keresztül érkeznek. A startDiscovery() 12 másodpercig működik, és a cancelDiscovery() meghívásával megszakítható. Ez a metódus elavult a BLE számára — használja a BluetoothLeScanner-t.

A BLE-szkennelés a BluetoothAdapter-en keresztül az elavult startLeScan(LeScanCallback) metódussal történik. API 21-től kezdve a Google a BluetoothLeScanner használatát ajánlja, amely a BluetoothAdapter.getBluetoothLeScanner() segítségével érhető el. A BluetoothLeScanner rugalmasabb API-t biztosít: a szkennelés konfigurálása a ScanSettings segítségével (mód, callback type, match mode), szűrés a ScanFilter segítségével (szolgáltatás UUID-je, eszköznév, MAC-cím alapján) és a PendingIntent támogatása a háttérben történő szkenneléshez.

// Régi (elavult) vs új BLE szkennelési API
import android.bluetooth.BluetoothAdapter
import android.bluetooth.le.*

class BLEScanner(private val bluetoothAdapter: BluetoothAdapter?) {

    // ELAVULT: startLeScan (API 18+, API 21)
    @Suppress("DEPRECATION")
    fun legacyScan() {
        bluetoothAdapter?.startLeScan { device, rssi, scanRecord ->
            print("Found (LE Scan): $device.name, RSSI: $rssi")
        }
    }

    // ÚJ: BluetoothLeScanner (API 21+)
    fun modernScan() {
        val scanner = bluetoothAdapter?.bluetoothLeScanner
            ?: return

        // Szkennelési beállítások
        val settings = ScanSettings.Builder()
            .setScanMode(ScanSettings.SCAN_MODE_LOW_LATENCY)
            .setCallbackType(ScanSettings.CALLBACK_TYPE_ALL_MATCHES)
            .setMatchMode(ScanSettings.MATCH_MODE_AGGRESSIVE)
            .build()

        // Szűrés szolgáltatás szerint (Pulzus UUID)
        val filters = listOf(
            ScanFilter.Builder()
                .setServiceUuid(ParcelUuid.fromString("0000180D-0000-1000-8000-00805F9B34FB"))
                .build()
        )

        // Szkennelés indítása
        scanner.startScan(filters, settings, object : ScanCallback() {
            override fun onScanResult(callbackType: Int, result: ScanResult) {
                val device = result.device
                val rssi = result.rssi
                print("Found (BLE Scanner): ${device.name}, RSSI: $rssi, address: ${device.address}")
            }

            override fun onScanFailed(errorCode: Int) {
                print("Scan error: $errorCode")
            }
        })
    }
}

A BLEScanner osztály összehasonlítja az elavult startLeScan-t és a modern BluetoothLeScanner-t. A legacyScan-ban a LeScanCallback callback BluetoothDevice-t, RSSI-t és nyers scanRecord-ot kap. A modernScan-ban a ScanSettings LOW_LATENCY móddal (maximális észlelési sebesség) és ScanFilter használatos a pulzusszolgáltatás UUID-je (Heart Rate Service 0x180D) alapján történő szűréshez. A ScanCallback onScanResult-t biztosít egy ScanResult objektummal, amely kiterjesztett információkat tartalmaz: név, RSSI, reklámadatok, kapcsolat típusa.

BluetoothManager: modern API a BluetoothAdapter eléréséhez

BluetoothManager — az Android rendszerszolgáltatása, amely API 18-ban (Android 4.3) került bevezetésre a Bluetooth-műveletek kezelésére. API 18 előtt a BluetoothAdapter megszerzésének egyetlen módja a getDefaultAdapter() statikus metódus volt. A BluetoothManager a következőket biztosítja: adapter — a BluetoothAdapter példánya, getConnectedDevices() — a csatlakoztatott eszközök listája, getDevicesMatchingConnectionStates() — szűrés állapot alapján. A BluetoothManager a BluetoothLeScanner megszerzésére is használatos régebbi API-ken.

A BluetoothManager előnyei a közvetlen BluetoothAdapter.getDefaultAdapter() hívással szemben: az alkalmazás nem függ egy statikus singleton-tól, a menedzser figyelembe veszi a kontextust (Activity/Application), ami fontos az Android Enterprise többfiókos forgatókönyveiben. Az Android Automotive több Bluetooth-chipsel rendelkező változatában a BluetoothManager.getAdapterList() az összes elérhető adaptert visszaadja — a BluetoothAdapter.getDefaultAdapter() csak az elsőt adja vissza.

// BluetoothManager használata BLE-hez
class BLEConnection(context: Context) {

    private val bluetoothManager: BluetoothManager =
        context.getSystemService(Context.BLUETOOTH_SERVICE) as BluetoothManager

    private val adapter: BluetoothAdapter? = bluetoothManager.adapter

    // Csatlakoztatott BLE-eszközök listájának lekérése
    fun getConnectedDevices(): List<BluetoothDevice> {
        return bluetoothManager.getConnectedDevices(
            BluetoothProfile.GATT
        )
    }

    // Eszközök szűrése állapot szerint
    fun getDevicesByState(states: IntArray): List<BluetoothDevice> {
        return bluetoothManager.getDevicesMatchingConnectionStates(
            BluetoothProfile.GATT, states
        )
    }

    // BLE-támogatás ellenőrzése az eszközön
    fun isBLESupported(): Boolean {
        return adapter != null && context.packageManager
            .hasSystemFeature(PackageManager.FEATURE_BLUETOOTH_LE)
    }

    // Bluetooth bekapcsolásának kérése rendszerpárbeszédablakon keresztül
    fun requestEnableBluetooth(activity: MainActivity) {
        if (adapter?.isEnabled == false) {
            val intent = Intent(BluetoothAdapter.ACTION_REQUEST_ENABLE)
            activity.startActivityForResult(intent, REQUEST_ENABLE_BT)
        }
    }

    companion object {
        const val REQUEST_ENABLE_BT = 1001
    }
}

A BLEConnection osztály a BluetoothManager-t használja a BluetoothAdapter eléréséhez és a csatlakoztatott GATT-eszközök listájának lekéréséhez. Az isBLESupported ellenőrzi a BLE-rádió jelenlétét a PackageManager.hasSystemFeature(FEATURE_BLUETOOTH_LE) segítségével — fontos ellenőrzés a Bluetooth Classic-kal rendelkező, BLE nélküli eszközök esetén. A requestEnableBluetooth megjeleníti a Bluetooth bekapcsolásának rendszerpárbeszédablakát (ACTION_REQUEST_ENABLE), anélkül hogy BLUETOOTH_ADMIN engedélyre lenne szükség — ez az egyetlen legális módja a Bluetooth bekapcsolásának Android 10+-ban rendszeralkalmazás nélkül.

Android-engedélyek a BluetoothAdapter-rel való munkához

Az engedélyek a BluetoothAdapter számára az Android minden verziójával fejlődtek. Android 6–11-ben (API 23–30) a BLE-szkenneléshez a BLUETOOTH, BLUETOOTH_ADMIN és ACCESS_FINE_LOCATION kötelező. Android 12+-ban (API 31+) a Google felosztotta az engedélyeket: az ACCESS_FINE_LOCATION-t felváltotta a BLUETOOTH_SCAN (szkennelés), BLUETOOTH_CONNECT (csatlakozás), BLUETOOTH_ADVERTISE (reklámozás). A BLE-eszközök kereséséhez a BLUETOOTH_SCAN elegendő, helymeghatározás nem szükséges.

Engedélyek táblázata Android-verziók szerint:

Android 12+-ban az összes Bluetooth-engedély futásidejű engedély — futásidőben kell kérni az ActivityResultContracts.RequestMultiplePermissions segítségével. A BLUETOOTH_SCAN és BLUETOOTH_ADVERTISE a NEARBY_DEVICES csoportba tartozik, a BLUETOOTH_CONNECT — ugyanabba a csoportba. A BLUETOOTH és BLUETOOTH_ADMIN engedélyek a manifesztben maradnak az API < 31-gyel való kompatibilitás érdekében, de API 31+ esetén figyelmen kívül lesznek hagyva — a Google az új engedélyek kifejezett megadását követeli meg.

// Bluetooth-engedélyek kérése Android 12+-ban
import android.Manifest
import android.content.pm.PackageManager
import android.os.Build
import androidx.core.content.ContextCompat

class PermissionHelper(context: Context) {

    fun getRequiredPermissions(): Array<String> {
        return if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.S) {
            // Android 12+: BLE-szkennelés
            arrayOf(
                Manifest.permission.BLUETOOTH_SCAN,
                Manifest.permission.BLUETOOTH_CONNECT,
                Manifest.permission.BLUETOOTH_ADVERTISE
            )
        } else {
            // Android 6-11: BLE-szkennelés
            arrayOf(
                Manifest.permission.ACCESS_FINE_LOCATION,
                Manifest.permission.BLUETOOTH,
                Manifest.permission.BLUETOOTH_ADMIN
            )
        }
    }

    // Összes engedély ellenőrzése
    fun hasPermissions(context: Context): Boolean {
        return getRequiredPermissions().all { permission ->
            ContextCompat.checkSelfPermission(context, permission)
                    == PackageManager.PERMISSION_GRANTED
        }
    }
}

A PermissionHelper osztály az API-szinttől függően a megfelelő engedélykészletet adja vissza. Android 12+-ban a BLUETOOTH_SCAN, BLUETOOTH_CONNECT, BLUETOOTH_ADVERTISE használatos helymeghatározás nélkül. Android 6–11-ben a BLE-szkenneléshez továbbra is ACCESS_FINE_LOCATION szükséges. A fejlesztőnek mindkét forgatókönyvet figyelembe kell vennie az engedélyek kérésekor az ActivityResultContracts vagy RxPermissions segítségével.

Teljes példa a BluetoothAdapter használatára Kotlinban

Teljes példa egy BLE-alkalmazásra Kotlinban, amely BluetoothAdapter-t használ a BLE-eszköz szkennelésére, csatlakozására és adatainak olvasására. A példa magában foglalja az engedélyek ellenőrzését, az adapter lekérését, a szkennelést a BluetoothLeScanner segítségével és a csatlakozást a BluetoothDevice.connectGatt segítségével.

// Teljes BLE-menedzser Kotlinban
class BLEManager(private val context: Context) {

    private val bluetoothManager: BluetoothManager =
        context.getSystemService(Context.BLUETOOTH_SERVICE) as BluetoothManager
    private val adapter: BluetoothAdapter? = bluetoothManager.adapter
    private var scanner: BluetoothLeScanner? = adapter?.bluetoothLeScanner
    private var gatt: BluetoothGatt? = null

    // 1. Szolgáltatások felfedezése
    fun canScan(): Boolean {
        return adapter?.isEnabled == true
                && scanner != null
                && PermissionHelper(context).hasPermissions(context)
    }

    // 2. Szkennelés szűrővel
    fun startScanning(callback: (BluetoothDevice, Int) -> Unit) {
        if (!canScan()) return

        val settings = ScanSettings.Builder()
            .setScanMode(ScanSettings.SCAN_MODE_LOW_LATENCY)
            .setReportDelay(0)
            .build()

        scanner?.startScan(null, settings, object : ScanCallback() {
            override fun onScanResult(callbackType: Int, result: ScanResult) {
                callback(result.device, result.rssi)
            }
        })
    }

    // 3. Szkennelés leállítása
    fun stopScanning() {
        scanner?.stopScan(object : ScanCallback() {})
    }

    // 4. Csatlakozás BLE-eszközhöz
    fun connectToDevice(device: BluetoothDevice) {
        if (adapter?.isEnabled != true) return

        gatt = device.connectGatt(
            context,
            false,
            object : BluetoothGattCallback() {
                override fun onConnectionStateChange(gatt: BluetoothGatt, status: Int, newState: Int) {
                    if (newState == BluetoothProfile.STATE_CONNECTED) {
                        gatt.discoverServices()
                    }
                }

                override fun onServicesDiscovered(gatt: BluetoothGatt, status: Int) {
                    // Szolgáltatások megtalálva, jellemzők olvashatók
                }
            },
            BluetoothDevice.TRANSPORT_LE
        )
    }

    // 5. Erőforrások felszabadítása
    fun disconnect() {
        gatt?.disconnect()
        gatt?.close()
        gatt = null
    }
}

A BLEManager menedzser egyesíti a teljes BLE-ciklust Androidban: az adapter és engedélyek ellenőrzése (canScan), szkennelés a BluetoothLeScanner segítségével ScanSettings-tel (startScanning), csatlakozás a BluetoothDevice.connectGatt segítségével TRANSPORT_LE-vel (connectToDevice), erőforrások felszabadítása (disconnect). Minden BLE-művelet az UI-szálon hajtódik végre — az Android a BluetoothGattCallback callback-eket a főszálon hívja meg. Hatékony BLE-feladatokhoz ajánlott a GATT-műveleteket háttér-HandlerThread-re áthelyezni.