Android BluetoothGatt

一、BluetoothGatt介绍

蓝牙分为经典蓝牙和低功耗蓝牙（BLE），我们常用的蓝牙遥控器就是低功耗蓝牙。

低功耗蓝牙（BLE）连接都是建立在 GATT (Generic Attribute Profile) 协议之上。

GATT全称Generic Attribute Profile（直译即：通用属性协议），是一个在蓝牙连接之上的发送和接收较短的数据段的通用规范，这些很短的数据段被称为属性（Attribute）。

BLE架构

如下为BLE的架构图：

物理层：定义与无线电（RF）有关的所有蓝牙技术方面，包括调制方案、频段、信道使用、发射器和接收器特性等。定义了几种不同的物理层参数组合，并称为PHY。

链接层：定义空中接口数据包格式、比特流处理过程（如检错）、状态机和用于无线通信和链路控制的协议等。定义使用底层无线电进行无连接、连接导向和等时通信的几种不同方式，称为逻辑传输。

等时自适应层（ISOAL）：允许使用等时通信的设备使用不同的帧持续时间。执行成帧PDU的分段和重组，或未成帧PDU的分割和重新组合。

主机控制接口（HCI）：为主机组件和控制器之间的命令和数据双向通信提供明确定义的功能接口。由数种物理传输实现之一提供支持。

逻辑链路控制和适应协议（L2CAP）：在主机内充当协议复用器，确保协议由适当的主机组件服务。在下层和上层L2CAP之间执行PDU/SDU的分割和重组。

安全管理协议（SMP）：用于执行诸如配对等安全过程期间的协议。

属性协议（ATT）：由ATT客户端和ATT服务器使用的协议，允许在服务器的属性表中发现和使用数据。

通用属性配置文件（GATT）：根据属性表中的底层属性定义高级数据类型，称为服务、特征和描述符。定义了使用ATT与属性表进行交互的更高级别程序。

通用接入配置文件（GAP）：定义了非连接状态下可使用的操作模式和过程，例如如何使用广告进行无连接通信以及如何执行设备发现。定义了安全级别和模式。定义了一些用户界面标准。

二、BluetoothGatt相关接口

IBluetoothGatt

API for interacting with BLE / GATT

用于与 BLE/GATT 交互的 API

IBluetoothGatt代码位于：

packages/modules/Bluetooth/system/binder/android/bluetooth/IBluetoothGatt.aidl

IBluetoothGatt的定义：

oneway interface IBluetoothGatt {}

IBluetoothGatt API：

       void getDevicesMatchingConnectionStates(in int[] states, in AttributionSource attributionSource, in SynchronousResultReceiver receiver);
        void registerScanner(in IScannerCallback callback, in WorkSource workSource, in AttributionSource attributionSource, in SynchronousResultReceiver receiver);
        void unregisterScanner(in int scannerId, in AttributionSource attributionSource, in SynchronousResultReceiver receiver);
        void startScan(in int scannerId, in ScanSettings settings, in List<ScanFilter> filters, in AttributionSource attributionSource, in SynchronousResultReceiver receiver);
        void startScanForIntent(in PendingIntent intent, in ScanSettings settings, in List<ScanFilter> filters, in AttributionSource attributionSource, in SynchronousResultReceiver receiver);
        void stopScanForIntent(in PendingIntent intent, in AttributionSource attributionSource, in SynchronousResultReceiver receiver);
        void stopScan(in int scannerId, in AttributionSource attributionSource, in SynchronousResultReceiver receiver);
        void flushPendingBatchResults(in int scannerId, in AttributionSource attributionSource, in SynchronousResultReceiver receiver);
        void startAdvertisingSet(in AdvertisingSetParameters parameters, in AdvertiseData advertiseData,in AdvertiseData scanResponse, in PeriodicAdvertisingParameters periodicParameters, in AdvertiseData periodicData, in int duration, in int maxExtAdvEvents, in IAdvertisingSetCallback callback, in AttributionSource attributionSource, in SynchronousResultReceiver receiver);
        void stopAdvertisingSet(in IAdvertisingSetCallback callback, in AttributionSource attributionSource, in SynchronousResultReceiver receiver);
        void getOwnAddress(in int advertiserId, in AttributionSource attributionSource, in SynchronousResultReceiver receiver);
        void enableAdvertisingSet(in int advertiserId, in boolean enable, in int duration, in int maxExtAdvEvents, in AttributionSource attributionSource, in SynchronousResultReceiver receiver);
        void setAdvertisingData(in int advertiserId, in AdvertiseData data, in AttributionSource attributionSource, in SynchronousResultReceiver receiver);
        void setScanResponseData(in int advertiserId, in AdvertiseData data, in AttributionSource attributionSource, in SynchronousResultReceiver receiver);
        void setAdvertisingParameters(in int advertiserId, in AdvertisingSetParameters parameters, in AttributionSource attributionSource, in SynchronousResultReceiver receiver);
        void setPeriodicAdvertisingParameters(in int advertiserId, in PeriodicAdvertisingParameters parameters, in AttributionSource attributionSource, in SynchronousResultReceiver receiver);
        void setPeriodicAdvertisingData(in int advertiserId, in AdvertiseData data, in AttributionSource attributionSource, in SynchronousResultReceiver receiver);
        void setPeriodicAdvertisingEnable(in int advertiserId, in boolean enable, in AttributionSource attributionSource, in SynchronousResultReceiver receiver);
        void registerSync(in ScanResult scanResult, in int skip, in int timeout, in IPeriodicAdvertisingCallback callback, in AttributionSource attributionSource, in SynchronousResultReceiver receiver);
        void unregisterSync(in IPeriodicAdvertisingCallback callback, in AttributionSource attributionSource, in SynchronousResultReceiver receiver);
        void transferSync(in BluetoothDevice bda, in int serviceData, in int syncHandle, in AttributionSource attributionSource, in SynchronousResultReceiver receiver);
        void transferSetInfo(in BluetoothDevice bda, in int serviceData, in int advertisingHandle, in IPeriodicAdvertisingCallback callback,  in AttributionSource attributionSource, in SynchronousResultReceiver receiver);
        void registerClient(in ParcelUuid appId, in IBluetoothGattCallback callback, boolean eatt_support, in AttributionSource attributionSource, in SynchronousResultReceiver receiver);
        void unregisterClient(in int clientIf, in AttributionSource attributionSource, in SynchronousResultReceiver receiver);
        void clientConnect(in int clientIf, in String address, in boolean isDirect, in int transport, in boolean opportunistic, in int phy, in AttributionSource attributionSource, in SynchronousResultReceiver receiver);
        void clientDisconnect(in int clientIf, in String address, in AttributionSource attributionSource, in SynchronousResultReceiver receiver);
        void clientSetPreferredPhy(in int clientIf, in String address, in int txPhy, in int rxPhy, in int phyOptions, in AttributionSource attributionSource, in SynchronousResultReceiver receiver);
        void clientReadPhy(in int clientIf, in String addres, in AttributionSource attributionSources, in SynchronousResultReceiver receiver);
        void refreshDevice(in int clientIf, in String address, in AttributionSource attributionSource, in SynchronousResultReceiver receiver);
        void discoverServices(in int clientIf, in String address, in AttributionSource attributionSource, in SynchronousResultReceiver receiver);
        void discoverServiceByUuid(in int clientIf, in String address, in ParcelUuid uuid, in AttributionSource attributionSource, in SynchronousResultReceiver receiver);
        void readCharacteristic(in int clientIf, in String address, in int handle, in int authReq, in AttributionSource attributionSource, in SynchronousResultReceiver receiver);
        void readUsingCharacteristicUuid(in int clientIf, in String address, in ParcelUuid uuid, in int startHandle, in int endHandle, in int authReq, in AttributionSource attributionSource, in SynchronousResultReceiver receiver);
        void writeCharacteristic(in int clientIf, in String address, in int handle, in int writeType, in int authReq, in byte[] value, in AttributionSource attributionSource, in SynchronousResultReceiver receiver)
        void readDescriptor(in int clientIf, in String address, in int handle, in int authReq, in AttributionSource attributionSource, in SynchronousResultReceiver receiver);
        void writeDescriptor(in int clientIf, in String address, in int handle, in int authReq, in byte[] value, in AttributionSource attributionSource, in SynchronousResultReceiver receiver);
        void registerForNotification(in int clientIf, in String address, in int handle, in boolean enable, in AttributionSource attributionSource, in SynchronousResultReceiver receiver);
        void beginReliableWrite(in int clientIf, in String address, in AttributionSource attributionSource, in SynchronousResultReceiver receiver);
        void endReliableWrite(in int clientIf, in String address, in boolean execute, in AttributionSource attributionSource, in SynchronousResultReceiver receiver);
        void readRemoteRssi(in int clientIf, in String address, in AttributionSource attributionSource, in SynchronousResultReceiver receiver);
        void configureMTU(in int clientIf, in String address, in int mtu, in AttributionSource attributionSource, in SynchronousResultReceiver receiver)
        void connectionParameterUpdate(in int clientIf, in String address, in int connectionPriority, in AttributionSource attributionSource, in SynchronousResultReceiver receiver);
        void leConnectionUpdate(int clientIf, String address, int minInterval, int maxInterval, int peripheralLatency, int supervisionTimeout, int minConnectionEventLen, int maxConnectionEventLen, in AttributionSource attributionSource, in SynchronousResultReceiver receiver);
        void registerServer(in ParcelUuid appId, in IBluetoothGattServerCallback callback, boolean eatt_support, in AttributionSource attributionSource, in SynchronousResultReceiver receiver);
        void unregisterServer(in int serverIf, in AttributionSource attributionSource, in SynchronousResultReceiver receiver)
        void serverConnect(in int serverIf, in String address, in boolean isDirect, in int transport, in AttributionSource attributionSource, in SynchronousResultReceiver receiver)
        void serverDisconnect(in int serverIf, in String address, in AttributionSource attributionSource, in SynchronousResultReceiver receiver);
        void serverSetPreferredPhy(in int clientIf, in String address, in int txPhy, in int rxPhy, in int phyOptions, in AttributionSource attributionSource, in SynchronousResultReceiver receiver);
        void serverReadPhy(in int clientIf, in String address, in AttributionSource attributionSource, in SynchronousResultReceiver receiver);
        void addService(in int serverIf, in BluetoothGattService service, in AttributionSource attributionSource, in SynchronousResultReceiver receiver);
        void removeService(in int serverIf, in int handle, in AttributionSource attributionSource, in SynchronousResultReceiver receiver);
        void clearServices(in int serverIf, in AttributionSource attributionSource, in SynchronousResultReceiver receiver);
        void sendResponse(in int serverIf, in String address, in int requestId, in int status, in int offset, in byte[] value, in AttributionSource attributionSource, in SynchronousResultReceiver receiver);
        void sendNotification(in int serverIf, in String address, in int handle, in boolean confirm, in byte[] value, in AttributionSource attributionSource, in SynchronousResultReceiver receiver);
        void disconnectAll(in AttributionSource attributionSource, in SynchronousResultReceiver receiver);
        void unregAll(in AttributionSource attributionSource, in SynchronousResultReceiver receiver)
        void numHwTrackFiltersAvailable(in AttributionSource attributionSource, in SynchronousResultReceiver receiver);

IBluetoothGattCallback

Callback definitions for interacting with BLE / GATT

与 BLE/GATT 交互的回调定义

IBluetoothGattCallback代码位于：

packages/modules/Bluetooth/system/binder/android/bluetooth/IBluetoothGattCallback.aidl

IBluetoothGattCallback的定义：

oneway interface IBluetoothGattCallback {}

IBluetoothGattCallback API：

void onClientRegistered(in int status, in int clientIf);
void onClientConnectionState(in int status, in int clientIf, in boolean connected, in String address);
void onPhyUpdate(in String address, in int txPhy, in int rxPhy, in int status);
void onPhyRead(in String address, in int txPhy, in int rxPhy, in int status);
void onSearchComplete(in String address, in List<BluetoothGattService> services, in int status);
void onCharacteristicRead(in String address, in int status, in int handle, in byte[] value);
void onCharacteristicWrite(in String address, in int status, in int handle, in byte[] value);
void onExecuteWrite(in String address, in int status);
void onDescriptorRead(in String address, in int status, in int handle, in byte[] value);
void onDescriptorWrite(in String address, in int status, in int handle, in byte[] value);
void onNotify(in String address, in int handle, in byte[] value);
void onReadRemoteRssi(in String address, in int rssi, in int status);
void onConfigureMTU(in String address, in int mtu, in int status);
void onConnectionUpdated(in String address, in int interval, in int latency, in int timeout, in int status);
void onServiceChanged(in String address);

IBluetoothGattServerCallback

Callback definitions for interacting with BLE / GATT

与 BLE/GATT 交互的回调定义

IBluetoothGattCallback代码位于：

packages/modules/Bluetooth/system/binder/android/bluetooth/IBluetoothGattCallback.aidl

IBluetoothGattCallback的定义：

oneway interface IBluetoothGattServerCallback {}

IBluetoothGattServerCallback API：

void onServerRegistered(in int status, in int serverIf);
        void onServerConnectionState(in int status, in int serverIf, in boolean connected, in String address);
        void onServiceAdded(in int status, in BluetoothGattService service);
        void onCharacteristicReadRequest(in String address, in int transId, in int offset, in boolean isLong, in int handle);
        void onDescriptorReadRequest(in String address, in int transId, in int offset, in boolean isLong, in int handle);
        void onCharacteristicWriteRequest(in String address, in int transId, in int offset, in int length, in boolean isPrep, in boolean needRsp, in int handle, in byte[] value);
        void onDescriptorWriteRequest(in String address, in int transId, in int offset, in int length, in boolean isPrep, in boolean needRsp, in int handle, in byte[] value);
        void onExecuteWrite(in String address, in int transId, in boolean execWrite);
        void onNotificationSent(in String address, in int status);
        void onMtuChanged(in String address, in int mtu);
        void onPhyUpdate(in String address, in int txPhy, in int rxPhy, in int status);
        void onPhyRead(in String address, in int txPhy, in int rxPhy, in int status);
        void onConnectionUpdated(in String address, in int interval, in int latency, in int timeout, in int status);

三、BluetoothGatt相关类

BluetoothGatt

BluetoothGatt是Android中用于与BLE设备通信的类。它提供了连接到BLE设备，发现服务和特征，读取和写入特征值，以及注册通知等功能，用于管理与远程蓝牙设备之间的GATT连接。GATT全称Generic Attribute Profile，是一个在蓝牙连接之上的发送和接收较短的数据段的通用规范，这些很短的数据段被称为属性（Attribute）。BluetoothGatt类提供了多个方法来管理GATT连接，包括连接到远程设备、发现服务和特征、读取和写入特征值等。在使用BluetoothGatt类之前，需要先通过BluetoothDevice的connectGatt()方法建立GATT连接。

BluetoothGatt代码位于：

packages/modules/Bluetooth/framework/java/android/bluetooth/BluetoothGatt.java

BluetoothGatt的定义：

public final class BluetoothGatt implements BluetoothProfile {}

void abortReliableWrite()：取消给定设备的可靠写入事务。
boolean beginReliableWrite()：为给定的远程设备启动可靠的写入事务。
void close()：关闭此蓝牙GATT客户端。
boolean connect()：连接远程设备。
void disconnect()：断开已建立的连接，或取消当前正在进行的连接尝试。
boolean discoverServices()：发现远程设备提供的服务及其特征和描述符。
boolean executeReliableWrite()：为给定的远程设备执行可靠的写入事务。
BluetoothDevice getDevice()：返回此GATT客户端所针对的远程蓝牙设备。
List<BluetoothGattService> getServices()：返回远程设备提供的GATT服务列表。
boolean readCharacteristic(BluetoothGattCharacteristic characteristic)：从关联的远程设备读取请求的特征。
boolean readDescriptor(BluetoothGattDescriptor descriptor)：从关联的远程设备读取给定描述符的值。
boolean readRemoteRssi()：读取连接的远程设备的RSSI。
boolean requestConnectionPriority(int connectionPriority)：请求连接参数更新。
boolean requestMtu(int mtu)：请求用于给定连接的MTU大小。
boolean setCharacteristicNotification(BluetoothGattCharacteristic characteristic, boolean enable)：启用或禁用给定特征的通知/指示。
boolean writeCharacteristic(BluetoothGattCharacteristic characteristic)：将给定的特性及其值写入关联的远程设备。
boolean writeDescriptor(BluetoothGattDescriptor descriptor)：将给定描述符的值写入关联的远程设备。

BluetoothGattServer

BluetoothGattServer用于在Android设备上实现BLE服务

BluetoothGattServer代码位于：

packages/modules/Bluetooth/framework/java/android/bluetooth/BluetoothGattServer.java

BluetoothGattServer的定义：

public final class BluetoothGattServer implements BluetoothProfile {
private final IBluetoothGattServerCallback mBluetoothGattServerCallback =
new IBluetoothGattServerCallback.Stub() {
public void onServerRegistered(int status, int serverIf) 
public void onServerConnectionState(int status, int serverIf, boolean connected, String address) 
public void onServiceAdded(int status, BluetoothGattService service) 
public void onCharacteristicReadRequest(String address, int transId, int offset, boolean isLong, int handle) 
public void onDescriptorReadRequest(String address, int transId, int offset, boolean isLong, int handle)
public void onCharacteristicWriteRequest(String address, int transId, int offset, int length, boolean isPrep, boolean needRsp, int handle, byte[] value) 
public void onDescriptorWriteRequest(String address, int transId, int offset, int length, boolean isPrep, boolean needRsp, int handle, byte[] value)
public void onExecuteWrite(String address, int transId, boolean execWrite)
public void onNotificationSent(String address, int status)
public void onMtuChanged(String address, int mtu)
public void onPhyUpdate(String address, int txPhy, int rxPhy, int status) 
public void onPhyRead(String address, int txPhy, int rxPhy, int status)
public void onConnectionUpdated(String address, int interval, int latency, int timeout, int status)
   }
}

GattService

GattService是一个通用属性配置文件（GATT）服务，它允许设备之间交换数据。GattService包含一个或多个GattCharacteristic，每个GattCharacteristic都包含一个值和一个或多个描述符。GattService和GattCharacteristic都有一个唯一的UUID，用于标识它们。GattService和GattCharacteristic的值可以是任何数据类型，例如整数、字符串或自定义数据类型。GattService通常用于蓝牙低功耗（BLE）应用程序中，例如智能手表、健康监测设备和智能家居设备。

GattService代码位于：

packages/modules/Bluetooth/android/app/src/com/android/bluetooth/gatt/GattService.java

GattService的定义：

public class GattService extends ProfileService {
    class PendingIntentInfo {}
        private static class MatchResult {}
        private static class BluetoothGattBinder extends IBluetoothGatt.Stub implements IProfileServiceBinder {}
}