Der erste Schritt bei der Interaktion mit einem BLE-Gerät ist die Verbindung mit dem Gerät. Genauer gesagt, wird eine Verbindung zum GATT-Server auf dem Gerät hergestellt. Verwenden Sie die Methode connectGatt(), um eine Verbindung zu einem GATT-Server auf einem BLE-Gerät herzustellen. Diese Methode verwendet drei Parameter: ein Context-Objekt, autoConnect (ein boolescher Wert, der angibt, ob automatisch eine Verbindung zum BLE-Gerät hergestellt werden soll, sobald es verfügbar ist) und einen Verweis auf ein BluetoothGattCallback:
var bluetoothGatt: BluetoothGatt? = null // ... bluetoothGatt = device.connectGatt(this, false, bluetoothGattCallback)
Dadurch wird eine Verbindung zum GATT-Server hergestellt, der vom BLE-Gerät gehostet wird, und eine BluetoothGatt-Instanz zurückgegeben, die du dann für GATT-Clientvorgänge verwenden kannst. Der Aufrufer (die Android-App) ist der GATT-Client. Der BluetoothGattCallback wird verwendet, um Ergebnisse an den Client zu senden, z. B. den Verbindungsstatus, sowie alle weiteren GATT-Clientvorgänge.
Gebundenen Dienst einrichten
Im folgenden Beispiel stellt die BLE-App eine Aktivität (DeviceControlActivity) bereit, um eine Verbindung zu Bluetooth-Geräten herzustellen, Gerätedaten anzuzeigen und die vom Gerät unterstützten GATT-Dienste und ‑Eigenschaften anzuzeigen. Basierend auf der Nutzereingabe kommuniziert diese Aktivität mit einem Service namens BluetoothLeService, der über die BLE API mit dem BLE-Gerät interagiert. Diese Kommunikation wird von einem gebundenen Dienst verarbeitet, der es der Aktivität ermöglicht, eine Verbindung zum BluetoothLeService herzustellen und Funktionen aufzurufen, um eine Verbindung zu den Geräten herzustellen. Die BluetoothLeService benötigt eine Binder-Implementierung, die Zugriff auf den Dienst für die Aktivität bietet.
class BluetoothLeService : Service() { private val binder = LocalBinder() override fun onBind(intent: Intent): IBinder? { return binder } inner class LocalBinder : Binder() { fun getService(): BluetoothLeService { return this@BluetoothLeService } } }
Die Aktivität kann den Dienst mit bindService() starten. Dabei wird ein Intent zum Starten des Dienstes, eine ServiceConnection-Implementierung zum Überwachen der Verbindungs- und Trennungsereignisse und ein Flag zum Angeben zusätzlicher Verbindungsoptionen übergeben.
class DeviceControlActivity : AppCompatActivity() { private var bluetoothService: BluetoothLeService? = null // Code to manage Service lifecycle. private val serviceConnection: ServiceConnection = object : ServiceConnection { override fun onServiceConnected( componentName: ComponentName, service: IBinder ) { bluetoothService = (service as LocalBinder).getService() bluetoothService?.let { bluetooth -> // call functions on service to check connection and connect to devices } } override fun onServiceDisconnected(componentName: ComponentName) { bluetoothService = null } } override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) setContentView(R.layout.gatt_services_characteristics) val gattServiceIntent = Intent(this, BluetoothLeService::class.java) bindService(gattServiceIntent, serviceConnection, Context.BIND_AUTO_CREATE) } }
BluetoothAdapter einrichten
Nachdem die Aktivität an den Dienst gebunden wurde, muss der Dienst auf den BluetoothAdapter zugreifen. Es sollte prüfen, ob der Adapter auf dem Gerät verfügbar ist. Weitere Informationen zum BluetoothAdapter findest du unter Bluetooth einrichten. Im folgenden Beispiel wird dieser Einrichtungscode in eine initialize()-Funktion eingebunden, die einen Boolean-Wert zurückgibt, der den Erfolg angibt.
private const val TAG = "BluetoothLeService" class BluetoothLeService : Service() { private var bluetoothAdapter: BluetoothAdapter? = null fun initialize(): Boolean { bluetoothAdapter = BluetoothAdapter.getDefaultAdapter() if (bluetoothAdapter == null) { Log.e(TAG, "Unable to obtain a BluetoothAdapter.") return false } return true } // ... }
Die Aktivität ruft diese Funktion in ihrer ServiceConnection-Implementierung auf.
Wie ein falscher Rückgabewert der Funktion initialize() behandelt wird, hängt von Ihrer Anwendung ab. Du kannst dem Nutzer eine Fehlermeldung anzeigen, die darauf hinweist, dass das aktuelle Gerät den Bluetooth-Vorgang nicht unterstützt, oder alle Funktionen deaktivieren, für die Bluetooth erforderlich ist. Im folgenden Beispiel ruft die Aktivität finish() auf, um den Nutzer zum vorherigen Bildschirm zurückzuleiten.
class DeviceControlActivity : AppCompatActivity() { // Code to manage Service lifecycle. private val serviceConnection: ServiceConnection = object : ServiceConnection { override fun onServiceConnected( componentName: ComponentName, service: IBinder ) { bluetoothService = (service as LocalBinder).getService() bluetoothService?.let { bluetooth -> if (!bluetooth.initialize()) { Log.e(TAG, "Unable to initialize Bluetooth") finish() } // perform device connection } } override fun onServiceDisconnected(componentName: ComponentName) { bluetoothService = null } } // ... }
Mit einem Gerät verbinden
Nachdem die BluetoothLeService-Instanz initialisiert wurde, kann sie eine Verbindung zum BLE-Gerät herstellen. Die Aktivität muss die Geräteadresse an den Dienst senden, damit dieser die Verbindung herstellen kann. Der Dienst ruft zuerst getRemoteDevice() auf dem BluetoothAdapter auf, um auf das Gerät zuzugreifen. Wenn der Adapter kein Gerät mit dieser Adresse finden kann, löst getRemoteDevice() eine IllegalArgumentException aus.
fun connect(address: String): Boolean { bluetoothAdapter?.let { adapter -> try { val device = adapter.getRemoteDevice(address) } catch (exception: IllegalArgumentException) { Log.w(TAG, "Device not found with provided address.") return false } // connect to the GATT server on the device return true } ?: run { Log.w(TAG, "BluetoothAdapter not initialized") return false } }
Der DeviceControlActivity ruft diese connect()-Funktion auf, nachdem der Dienst initialisiert wurde. Die Aktivität muss die Adresse des BLE-Geräts übergeben. Im folgenden Beispiel wird die Geräteadresse als Intent-Extra an die Aktivität übergeben.
// Code to manage Service lifecycle. private val serviceConnection: ServiceConnection = object : ServiceConnection { override fun onServiceConnected( componentName: ComponentName, service: IBinder ) { bluetoothService = (service as LocalBinder).getService() bluetoothService?.let { bluetooth -> if (!bluetooth.initialize()) { Log.e(TAG, "Unable to initialize Bluetooth") finish() } // perform device connection deviceAddress?.let { bluetooth.connect(it) } } } override fun onServiceDisconnected(componentName: ComponentName) { bluetoothService = null } }
GATT-Callback deklarieren
Nachdem die Aktivität dem Dienst mitgeteilt hat, mit welchem Gerät eine Verbindung hergestellt werden soll, und der Dienst eine Verbindung zum Gerät hergestellt hat, muss der Dienst eine Verbindung zum GATT-Server auf dem BLE-Gerät herstellen. Für diese Verbindung ist ein BluetoothGattCallback erforderlich, um Benachrichtigungen zum Verbindungsstatus, zur Service Discovery, zu gelesenen Merkmalen und zu Merkmalsbenachrichtigungen zu erhalten.
In diesem Dokument geht es um Benachrichtigungen zum Verbindungsstatus. Informationen zum Erkennen von Diensten, zum Lesen von Merkmalen und zum Anfordern von Benachrichtigungen zu Merkmalen findest du unter BLE-Daten übertragen.
Die Funktion onConnectionStateChange() wird ausgelöst, wenn sich die Verbindung zum GATT-Server des Geräts ändert. Im folgenden Beispiel wird der Callback in der Klasse Service definiert, damit er mit dem BluetoothDevice verwendet werden kann, nachdem der Dienst eine Verbindung zu ihm hergestellt hat.
private val bluetoothGattCallback = object : BluetoothGattCallback() { override fun onConnectionStateChange(gatt: BluetoothGatt?, status: Int, newState: Int) { if (newState == BluetoothProfile.STATE_CONNECTED) { // successfully connected to the GATT Server } else if (newState == BluetoothProfile.STATE_DISCONNECTED) { // disconnected from the GATT Server } } }
Verbindung zum GATT-Dienst herstellen
Nachdem der BluetoothGattCallback deklariert wurde, kann der Dienst das BluetoothDevice-Objekt aus der connect()-Funktion verwenden, um eine Verbindung zum GATT-Dienst auf dem Gerät herzustellen.
Der Dienst ruft die Funktion connectGatt() auf. Dazu sind ein Context-Objekt, ein boolesches autoConnect-Flag und die BluetoothGattCallback erforderlich. In diesem Beispiel stellt die App eine direkte Verbindung zum BLE-Gerät her, sodass false für autoConnect übergeben wird.
Der Dienst fügt außerdem ein BluetoothGatt-Attribut hinzu, damit er die Verbindung schließen kann, wenn sie nicht mehr benötigt wird.
class BluetoothLeService : Service() { // ... private var bluetoothGatt: BluetoothGatt? = null // ... fun connect(address: String): Boolean { bluetoothAdapter?.let { adapter -> try { val device = adapter.getRemoteDevice(address) // connect to the GATT server on the device bluetoothGatt = device.connectGatt(this, false, bluetoothGattCallback) return true } catch (exception: IllegalArgumentException) { Log.w(TAG, "Device not found with provided address. Unable to connect.") return false } } ?: run { Log.w(TAG, "BluetoothAdapter not initialized") return false } } }
Updates übertragen
Wenn der Dienst eine Verbindung zum GATT-Server herstellt oder trennt, muss er die Aktivität über den neuen Status benachrichtigen. Dafür gibt es mehrere Möglichkeiten. Im folgenden Beispiel werden Broadcasts verwendet, um die Informationen vom Dienst an die Aktivität zu senden.
Der Dienst deklariert eine Funktion, um den neuen Status zu übertragen. Diese Funktion nimmt einen Aktionsstring auf, der an ein Intent-Objekt übergeben wird, bevor er an das System gesendet wird.
private fun broadcastUpdate(action: String) { val intent = Intent(action) sendBroadcast(intent) }
Nachdem die Broadcast-Funktion eingerichtet wurde, wird sie vom Dienst innerhalb von BluetoothGattCallback verwendet, um Informationen zum Verbindungsstatus mit dem GATT-Server zu senden. Der Dienst deklariert Konstanten, die die Intent-Aktionen und den aktuellen Verbindungsstatus des Dienstes darstellen.
class BluetoothLeService : Service() { private var connectionState = STATE_DISCONNECTED private val bluetoothGattCallback = object : BluetoothGattCallback() { override fun onConnectionStateChange(gatt: BluetoothGatt?, status: Int, newState: Int) { if (newState == BluetoothProfile.STATE_CONNECTED) { // successfully connected to the GATT Server connectionState = STATE_CONNECTED broadcastUpdate(ACTION_GATT_CONNECTED) } else if (newState == BluetoothProfile.STATE_DISCONNECTED) { // disconnected from the GATT Server connectionState = STATE_DISCONNECTED broadcastUpdate(ACTION_GATT_DISCONNECTED) } } } // ... companion object { const val ACTION_GATT_CONNECTED = "com.example.bluetooth.le.ACTION_GATT_CONNECTED" const val ACTION_GATT_DISCONNECTED = "com.example.bluetooth.le.ACTION_GATT_DISCONNECTED" private const val STATE_DISCONNECTED = 0 private const val STATE_CONNECTED = 2 } }
Auf Updates zu Aktivitäten warten
Nachdem der Dienst die Verbindungsaktualisierungen übertragen hat, muss die Aktivität einen BroadcastReceiver implementieren. Registriere diesen Empfänger, wenn du die Aktivität einrichtest, und hebe die Registrierung auf, wenn die Aktivität den Bildschirm verlässt. Durch das Abhören der Ereignisse vom Dienst kann die Aktivität die Benutzeroberfläche basierend auf dem aktuellen Verbindungsstatus mit dem BLE-Gerät aktualisieren.
class DeviceControlActivity : AppCompatActivity() { private val gattUpdateReceiver: BroadcastReceiver = object : BroadcastReceiver() { override fun onReceive(context: Context, intent: Intent) { when (intent.action) { BluetoothLeService.ACTION_GATT_CONNECTED -> { connected = true updateConnectionState(R.string.connected) } BluetoothLeService.ACTION_GATT_DISCONNECTED -> { connected = false updateConnectionState(R.string.disconnected) } } } } override fun onResume() { super.onResume() registerReceiver(gattUpdateReceiver, makeGattUpdateIntentFilter()) bluetoothService?.let { service -> deviceAddress?.let { address -> val result = service.connect(address) Log.d(TAG, "Connect request result=$result") } } } override fun onPause() { super.onPause() unregisterReceiver(gattUpdateReceiver) } private fun makeGattUpdateIntentFilter(): IntentFilter { return IntentFilter().apply { addAction(BluetoothLeService.ACTION_GATT_CONNECTED) addAction(BluetoothLeService.ACTION_GATT_DISCONNECTED) } } }
In BLE-Daten übertragen wird die BroadcastReceiver auch verwendet, um die Service Discovery sowie die charakteristischen Daten vom Gerät zu übertragen.
GATT-Verbindung schließen
Ein wichtiger Schritt beim Umgang mit Bluetooth-Verbindungen ist das Schließen der Verbindung, wenn sie nicht mehr benötigt wird. Rufen Sie dazu die Funktion close() für das Objekt BluetoothGatt auf. Im folgenden Beispiel enthält der Dienst den Verweis auf BluetoothGatt. Wenn die Aktivität vom Dienst getrennt wird, wird die Verbindung geschlossen, um den Akku des Geräts zu schonen.
class BluetoothLeService : Service() { // ... override fun onUnbind(intent: Intent?): Boolean { close() return super.onUnbind(intent) } private fun close() { bluetoothGatt?.let { gatt -> gatt.close() bluetoothGatt = null } } }