連線至 BLE GATT 伺服器後，您可以使用此連線找出裝置上可用的服務、查詢裝置資料，並在特定 GATT 特性變更時要求通知。
探索服務
當您在 BLE 裝置上連線至 GATT 伺服器後，首先要進行服務探索。這項資訊會提供遠端裝置可用服務的相關資訊，以及服務特性和描述元。在以下範例中，服務成功連線至裝置後 (以對 BluetoothGattCallback 的 onConnectionStateChange() 函式的適當呼叫表示)，discoverServices() 函式會從 BLE 裝置查詢資訊。
服務需要覆寫 BluetoothGattCallback 中的 onServicesDiscovered() 函式。當裝置回報可用的服務時，系統會呼叫此函式。
Kotlin
class BluetoothLeService : Service() {
...
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
broadcastUpdate(ACTION_GATT_CONNECTED)
connectionState = STATE_CONNECTED
// Attempts to discover services after successful connection.
bluetoothGatt?.discoverServices()
} else if (newState == BluetoothProfile.STATE_DISCONNECTED) {
// disconnected from the GATT Server
broadcastUpdate(ACTION_GATT_DISCONNECTED)
connectionState = STATE_DISCONNECTED
}
}
override fun onServicesDiscovered(gatt: BluetoothGatt?, status: Int) {
if (status == BluetoothGatt.GATT_SUCCESS) {
broadcastUpdate(ACTION_GATT_SERVICES_DISCOVERED)
} else {
Log.w(BluetoothService.TAG, "onServicesDiscovered received: $status")
}
}
}
...
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"
const val ACTION_GATT_SERVICES_DISCOVERED =
"com.example.bluetooth.le.ACTION_GATT_SERVICES_DISCOVERED"
private const val STATE_DISCONNECTED = 0
private const val STATE_CONNECTED = 2
}
Java
class BluetoothService extends Service {
public final static String ACTION_GATT_SERVICES_DISCOVERED =
"com.example.bluetooth.le.ACTION_GATT_SERVICES_DISCOVERED";
...
private final BluetoothGattCallback bluetoothGattCallback = new BluetoothGattCallback() {
@Override
public void onConnectionStateChange(BluetoothGatt gatt, int status, int newState) {
if (newState == BluetoothProfile.STATE_CONNECTED) {
// successfully connected to the GATT Server
connectionState = STATE_CONNECTED;
broadcastUpdate(ACTION_GATT_CONNECTED);
// Attempts to discover services after successful connection.
bluetoothGatt.discoverServices();
} else if (newState == BluetoothProfile.STATE_DISCONNECTED) {
// disconnected from the GATT Server
connectionState = STATE_DISCONNECTED;
broadcastUpdate(ACTION_GATT_DISCONNECTED);
}
}
@Override
public void onServicesDiscovered(BluetoothGatt gatt, int status) {
if (status == BluetoothGatt.GATT_SUCCESS) {
broadcastUpdate(ACTION_GATT_SERVICES_DISCOVERED);
} else {
Log.w(TAG, "onServicesDiscovered received: " + status);
}
}
};
}
服務會使用廣播來通知活動。發現服務後，服務可以呼叫 getServices() 來取得回報的資料。
Kotlin
class BluetoothLeService : Service() {
...
fun getSupportedGattServices(): List<BluetoothGattService?>? {
return bluetoothGatt?.services
}
}
Java
class BluetoothService extends Service {
...
public List<BluetoothGattService> getSupportedGattServices() {
if (bluetoothGatt == null) return null;
return bluetoothGatt.getServices();
}
}
活動隨後可以在收到廣播意圖時呼叫此函式，表示服務探索已完成。
Kotlin
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)
}
BluetoothLeService.ACTION_GATT_SERVICES_DISCOVERED -> {
// Show all the supported services and characteristics on the user interface.
displayGattServices(bluetoothService?.getSupportedGattServices())
}
}
}
}
}
Java
class DeviceControlsActivity extends AppCompatActivity {
...
private final BroadcastReceiver gattUpdateReceiver = new BroadcastReceiver() {
@Override
public void onReceive(Context context, Intent intent) {
final String action = intent.getAction();
if (BluetoothLeService.ACTION_GATT_CONNECTED.equals(action)) {
connected = true;
updateConnectionState(R.string.connected);
} else if (BluetoothLeService.ACTION_GATT_DISCONNECTED.equals(action)) {
connected = false;
updateConnectionState(R.string.disconnected);
} else if (BluetoothLeService.ACTION_GATT_SERVICES_DISCOVERED.equals(action)) {
// Show all the supported services and characteristics on the user interface.
displayGattServices(bluetoothService.getSupportedGattServices());
}
}
};
}
讀取 BLE 特性
應用程式連線至 GATT 伺服器並找到服務後，就能在支援的情況下讀取及寫入屬性。舉例來說，下列程式碼片段會在伺服器的服務和特性中反覆顯示，並在使用者介面中顯示：
Kotlin
class DeviceControlActivity : Activity() {
// Demonstrates how to iterate through the supported GATT
// Services/Characteristics.
// In this sample, we populate the data structure that is bound to the
// ExpandableListView on the UI.
private fun displayGattServices(gattServices: List<BluetoothGattService>?) {
if (gattServices == null) return
var uuid: String?
val unknownServiceString: String = resources.getString(R.string.unknown_service)
val unknownCharaString: String = resources.getString(R.string.unknown_characteristic)
val gattServiceData: MutableList<HashMap<String, String>> = mutableListOf()
val gattCharacteristicData: MutableList<ArrayList<HashMap<String, String>>> =
mutableListOf()
mGattCharacteristics = mutableListOf()
// Loops through available GATT Services.
gattServices.forEach { gattService ->
val currentServiceData = HashMap<String, String>()
uuid = gattService.uuid.toString()
currentServiceData[LIST_NAME] = SampleGattAttributes.lookup(uuid, unknownServiceString)
currentServiceData[LIST_UUID] = uuid
gattServiceData += currentServiceData
val gattCharacteristicGroupData: ArrayList<HashMap<String, String>> = arrayListOf()
val gattCharacteristics = gattService.characteristics
val charas: MutableList<BluetoothGattCharacteristic> = mutableListOf()
// Loops through available Characteristics.
gattCharacteristics.forEach { gattCharacteristic ->
charas += gattCharacteristic
val currentCharaData: HashMap<String, String> = hashMapOf()
uuid = gattCharacteristic.uuid.toString()
currentCharaData[LIST_NAME] = SampleGattAttributes.lookup(uuid, unknownCharaString)
currentCharaData[LIST_UUID] = uuid
gattCharacteristicGroupData += currentCharaData
}
mGattCharacteristics += charas
gattCharacteristicData += gattCharacteristicGroupData
}
}
}
Java
public class DeviceControlActivity extends Activity {
...
// Demonstrates how to iterate through the supported GATT
// Services/Characteristics.
// In this sample, we populate the data structure that is bound to the
// ExpandableListView on the UI.
private void displayGattServices(List<BluetoothGattService> gattServices) {
if (gattServices == null) return;
String uuid = null;
String unknownServiceString = getResources().
getString(R.string.unknown_service);
String unknownCharaString = getResources().
getString(R.string.unknown_characteristic);
ArrayList<HashMap<String, String>> gattServiceData =
new ArrayList<HashMap<String, String>>();
ArrayList<ArrayList<HashMap<String, String>>> gattCharacteristicData
= new ArrayList<ArrayList<HashMap<String, String>>>();
mGattCharacteristics =
new ArrayList<ArrayList<BluetoothGattCharacteristic>>();
// Loops through available GATT Services.
for (BluetoothGattService gattService : gattServices) {
HashMap<String, String> currentServiceData =
new HashMap<String, String>();
uuid = gattService.getUuid().toString();
currentServiceData.put(
LIST_NAME, SampleGattAttributes.
lookup(uuid, unknownServiceString));
currentServiceData.put(LIST_UUID, uuid);
gattServiceData.add(currentServiceData);
ArrayList<HashMap<String, String>> gattCharacteristicGroupData =
new ArrayList<HashMap<String, String>>();
List<BluetoothGattCharacteristic> gattCharacteristics =
gattService.getCharacteristics();
ArrayList<BluetoothGattCharacteristic> charas =
new ArrayList<BluetoothGattCharacteristic>();
// Loops through available Characteristics.
for (BluetoothGattCharacteristic gattCharacteristic :
gattCharacteristics) {
charas.add(gattCharacteristic);
HashMap<String, String> currentCharaData =
new HashMap<String, String>();
uuid = gattCharacteristic.getUuid().toString();
currentCharaData.put(
LIST_NAME, SampleGattAttributes.lookup(uuid,
unknownCharaString));
currentCharaData.put(LIST_UUID, uuid);
gattCharacteristicGroupData.add(currentCharaData);
}
mGattCharacteristics.add(charas);
gattCharacteristicData.add(gattCharacteristicGroupData);
}
...
}
...
}
GATT 服務提供可從裝置讀取的特性清單。如要查詢資料，請在 BluetoothGatt 上呼叫 readCharacteristic() 函式，並傳入要讀取的 BluetoothGattCharacteristic。
Kotlin
class BluetoothLeService : Service() {
...
fun readCharacteristic(characteristic: BluetoothGattCharacteristic) {
bluetoothGatt?.let { gatt ->
gatt.readCharacteristic(characteristic)
} ?: run {
Log.w(TAG, "BluetoothGatt not initialized")
Return
}
}
}
Java
class BluetoothService extends Service {
...
public void readCharacteristic(BluetoothGattCharacteristic characteristic) {
if (bluetoothGatt == null) {
Log.w(TAG, "BluetoothGatt not initialized");
return;
}
bluetoothGatt.readCharacteristic(characteristic);
}
}
在這個範例中，服務會實作呼叫 readCharacteristic() 的函式。這是非同步呼叫。結果會傳送到 BluetoothGattCallback 函式 onCharacteristicRead()。
Kotlin
class BluetoothLeService : Service() {
...
private val bluetoothGattCallback = object : BluetoothGattCallback() {
...
override fun onCharacteristicRead(
gatt: BluetoothGatt,
characteristic: BluetoothGattCharacteristic,
status: Int
) {
if (status == BluetoothGatt.GATT_SUCCESS) {
broadcastUpdate(BluetoothService.ACTION_DATA_AVAILABLE, characteristic)
}
}
}
}
Java
class BluetoothService extends Service {
...
private final BluetoothGattCallback bluetoothGattCallback = new BluetoothGattCallback() {
...
@Override
public void onCharacteristicRead(
BluetoothGatt gatt,
BluetoothGattCharacteristic characteristic,
int status
) {
if (status == BluetoothGatt.GATT_SUCCESS) {
broadcastUpdate(ACTION_DATA_AVAILABLE, characteristic);
}
}
};
}
特定回呼觸發時，會呼叫適當的 broadcastUpdate() 輔助方法並傳遞動作。請注意，本節中的資料是根據藍牙心率測量設定檔規格執行。
Kotlin
private fun broadcastUpdate(action: String, characteristic: BluetoothGattCharacteristic) {
val intent = Intent(action)
// This is special handling for the Heart Rate Measurement profile. Data
// parsing is carried out as per profile specifications.
when (characteristic.uuid) {
UUID_HEART_RATE_MEASUREMENT -> {
val flag = characteristic.properties
val format = when (flag and 0x01) {
0x01 -> {
Log.d(TAG, "Heart rate format UINT16.")
BluetoothGattCharacteristic.FORMAT_UINT16
}
else -> {
Log.d(TAG, "Heart rate format UINT8.")
BluetoothGattCharacteristic.FORMAT_UINT8
}
}
val heartRate = characteristic.getIntValue(format, 1)
Log.d(TAG, String.format("Received heart rate: %d", heartRate))
intent.putExtra(EXTRA_DATA, (heartRate).toString())
}
else -> {
// For all other profiles, writes the data formatted in HEX.
val data: ByteArray? = characteristic.value
if (data?.isNotEmpty() == true) {
val hexString: String = data.joinToString(separator = " ") {
String.format("%02X", it)
}
intent.putExtra(EXTRA_DATA, "$data\n$hexString")
}
}
}
sendBroadcast(intent)
}
Java
private void broadcastUpdate(final String action,
final BluetoothGattCharacteristic characteristic) {
final Intent intent = new Intent(action);
// This is special handling for the Heart Rate Measurement profile. Data
// parsing is carried out as per profile specifications.
if (UUID_HEART_RATE_MEASUREMENT.equals(characteristic.getUuid())) {
int flag = characteristic.getProperties();
int format = -1;
if ((flag & 0x01) != 0) {
format = BluetoothGattCharacteristic.FORMAT_UINT16;
Log.d(TAG, "Heart rate format UINT16.");
} else {
format = BluetoothGattCharacteristic.FORMAT_UINT8;
Log.d(TAG, "Heart rate format UINT8.");
}
final int heartRate = characteristic.getIntValue(format, 1);
Log.d(TAG, String.format("Received heart rate: %d", heartRate));
intent.putExtra(EXTRA_DATA, String.valueOf(heartRate));
} else {
// For all other profiles, writes the data formatted in HEX.
final byte[] data = characteristic.getValue();
if (data != null && data.length > 0) {
final StringBuilder stringBuilder = new StringBuilder(data.length);
for(byte byteChar : data)
stringBuilder.append(String.format("%02X ", byteChar));
intent.putExtra(EXTRA_DATA, new String(data) + "\n" +
stringBuilder.toString());
}
}
sendBroadcast(intent);
}
接收 GATT 通知
BLE 應用程式常會在裝置上要求取得特定特性變更時收到通知。在以下範例中，服務會實作函式來呼叫 setCharacteristicNotification() 方法：
Kotlin
class BluetoothLeService : Service() {
...
fun setCharacteristicNotification(
characteristic: BluetoothGattCharacteristic,
enabled: Boolean
) {
bluetoothGatt?.let { gatt ->
gatt.setCharacteristicNotification(characteristic, enabled)
// This is specific to Heart Rate Measurement.
if (BluetoothService.UUID_HEART_RATE_MEASUREMENT == characteristic.uuid) {
val descriptor = characteristic.getDescriptor(UUID.fromString(SampleGattAttributes.CLIENT_CHARACTERISTIC_CONFIG))
descriptor.value = BluetoothGattDescriptor.ENABLE_NOTIFICATION_VALUE
gatt.writeDescriptor(descriptor)
}
} ?: run {
Log.w(BluetoothService.TAG, "BluetoothGatt not initialized")
}
}
}
Java
class BluetoothService extends Service {
...
public void setCharacteristicNotification(BluetoothGattCharacteristic characteristic,boolean enabled) {
if (bluetoothGatt == null) {
Log.w(TAG, "BluetoothGatt not initialized");
Return;
}
bluetoothGatt.setCharacteristicNotification(characteristic, enabled);
// This is specific to Heart Rate Measurement.
if (UUID_HEART_RATE_MEASUREMENT.equals(characteristic.getUuid())) {
BluetoothGattDescriptor descriptor = characteristic.getDescriptor(UUID.fromString(SampleGattAttributes.CLIENT_CHARACTERISTIC_CONFIG));
descriptor.setValue(BluetoothGattDescriptor.ENABLE_NOTIFICATION_VALUE);
bluetoothGatt.writeDescriptor(descriptor);
}
}
}
針對特性啟用通知後，如果遠端裝置的特性改變，就會觸發 onCharacteristicChanged() 回呼：
Kotlin
class BluetoothLeService : Service() {
...
private val bluetoothGattCallback = object : BluetoothGattCallback() {
...
override fun onCharacteristicChanged(
gatt: BluetoothGatt,
characteristic: BluetoothGattCharacteristic
) {
broadcastUpdate(ACTION_DATA_AVAILABLE, characteristic)
}
}
}
Java
class BluetoothService extends Service {
...
private final BluetoothGattCallback bluetoothGattCallback = new BluetoothGattCallback() {
...
@Override
public void onCharacteristicChanged(
BluetoothGatt gatt,
BluetoothGattCharacteristic characteristic
) {
broadcastUpdate(ACTION_DATA_AVAILABLE, characteristic);
}
};
}