BluetoothGatt

CONNECTION_PRIORITY_BALANCED

public static final int CONNECTION_PRIORITY_BALANCED

Connection parameter update - Use the connection parameters recommended by the Bluetooth SIG. This is the default value if no connection parameter update is requested.

Constant Value: 0 (0x00000000)

CONNECTION_PRIORITY_DCK

public static final int CONNECTION_PRIORITY_DCK

Connection parameter update - Request the priority preferred for Digital Car Key for a lower latency connection. This connection parameter will consume more power than CONNECTION_PRIORITY_BALANCED, so it is recommended that apps do not use this unless it specifically fits their use case.

Constant Value: 3 (0x00000003)

CONNECTION_PRIORITY_HIGH

public static final int CONNECTION_PRIORITY_HIGH

Connection parameter update - Request a high priority, low latency connection. An application should only request high priority connection parameters to transfer large amounts of data over LE quickly. Once the transfer is complete, the application should request CONNECTION_PRIORITY_BALANCED connection parameters to reduce energy use.

Constant Value: 1 (0x00000001)

CONNECTION_PRIORITY_LOW_POWER

public static final int CONNECTION_PRIORITY_LOW_POWER

Connection parameter update - Request low power, reduced data rate connection parameters.

Constant Value: 2 (0x00000002)

GATT_CONNECTION_CONGESTED

public static final int GATT_CONNECTION_CONGESTED

A remote device connection is congested.

Constant Value: 143 (0x0000008f)

GATT_CONNECTION_TIMEOUT

public static final int GATT_CONNECTION_TIMEOUT

GATT connection timed out, likely due to the remote device being out of range or not advertising as connectable.

Constant Value: 147 (0x00000093)

GATT_FAILURE

public static final int GATT_FAILURE

A GATT operation failed, errors other than the above

Constant Value: 257 (0x00000101)

GATT_INSUFFICIENT_AUTHENTICATION

public static final int GATT_INSUFFICIENT_AUTHENTICATION

Insufficient authentication for a given operation

Constant Value: 5 (0x00000005)

GATT_INSUFFICIENT_AUTHORIZATION

public static final int GATT_INSUFFICIENT_AUTHORIZATION

Insufficient authorization for a given operation

Constant Value: 8 (0x00000008)

GATT_INSUFFICIENT_ENCRYPTION

public static final int GATT_INSUFFICIENT_ENCRYPTION

Insufficient encryption for a given operation

Constant Value: 15 (0x0000000f)

GATT_INVALID_ATTRIBUTE_LENGTH

public static final int GATT_INVALID_ATTRIBUTE_LENGTH

A write operation exceeds the maximum length of the attribute

Constant Value: 13 (0x0000000d)

GATT_INVALID_OFFSET

public static final int GATT_INVALID_OFFSET

A read or write operation was requested with an invalid offset

Constant Value: 7 (0x00000007)

GATT_READ_NOT_PERMITTED

public static final int GATT_READ_NOT_PERMITTED

GATT read operation is not permitted

Constant Value: 2 (0x00000002)

GATT_REQUEST_NOT_SUPPORTED

public static final int GATT_REQUEST_NOT_SUPPORTED

The given request is not supported

Constant Value: 6 (0x00000006)

GATT_SUCCESS

public static final int GATT_SUCCESS

A GATT operation completed successfully

Constant Value: 0 (0x00000000)

GATT_WRITE_NOT_PERMITTED

public static final int GATT_WRITE_NOT_PERMITTED

GATT write operation is not permitted

Constant Value: 3 (0x00000003)

SUBRATE_MODE_BALANCED

public static final int SUBRATE_MODE_BALANCED

Connection subrate mode - Balanced.

Constant Value: 2 (0x00000002)

SUBRATE_MODE_HIGH

public static final int SUBRATE_MODE_HIGH

Connection subrate mode - High.

Constant Value: 3 (0x00000003)

SUBRATE_MODE_LOW

public static final int SUBRATE_MODE_LOW

Connection Subrate mode - Low

Constant Value: 1 (0x00000001)

SUBRATE_MODE_NOT_UPDATED

public static final int SUBRATE_MODE_NOT_UPDATED

Connection Subrate mode - No Update applied due to error.

Constant Value: 255 (0x000000ff)

SUBRATE_MODE_OFF

public static final int SUBRATE_MODE_OFF

Connection Subrate mode - Off

Constant Value: 0 (0x00000000)

SUBRATE_MODE_SYSTEM_UPDATE

public static final int SUBRATE_MODE_SYSTEM_UPDATE

Connection Subrate mode - System Update.

Constant Value: 99 (0x00000063)

abortReliableWrite

public void abortReliableWrite (BluetoothDevice mDevice)

This method was deprecated in API level 19.
Use abortReliableWrite()

For apps targeting Build.VERSION_CODES.S or or higher, this requires the Manifest.permission.BLUETOOTH_CONNECT permission which can be gained with Activity.requestPermissions(String[], int).
Requires Manifest.permission.BLUETOOTH_CONNECT

abortReliableWrite

public void abortReliableWrite ()

Cancels a reliable write transaction for a given device.

Calling this function will discard all queued characteristic write operations for a given remote device.
For apps targeting Build.VERSION_CODES.R or lower, this requires the Manifest.permission.BLUETOOTH permission which can be gained with a simple <uses-permission> manifest tag.
For apps targeting Build.VERSION_CODES.S or or higher, this requires the Manifest.permission.BLUETOOTH_CONNECT permission which can be gained with Activity.requestPermissions(String[], int).
Requires Manifest.permission.BLUETOOTH_CONNECT

beginReliableWrite

public boolean beginReliableWrite ()

Initiates a reliable write transaction for a given remote device.

Once a reliable write transaction has been initiated, all calls to writeCharacteristic(BluetoothGattCharacteristic) are sent to the remote device for verification and queued up for atomic execution. The application will receive a BluetoothGattCallback.onCharacteristicWrite callback in response to every writeCharacteristic(android.bluetooth.BluetoothGattCharacteristic, byte[], int) call and is responsible for verifying if the value has been transmitted accurately.

After all characteristics have been queued up and verified, executeReliableWrite() will execute all writes. If a characteristic was not written correctly, calling abortReliableWrite() will cancel the current transaction without committing any values on the remote device.
For apps targeting Build.VERSION_CODES.R or lower, this requires the Manifest.permission.BLUETOOTH permission which can be gained with a simple <uses-permission> manifest tag.
For apps targeting Build.VERSION_CODES.S or or higher, this requires the Manifest.permission.BLUETOOTH_CONNECT permission which can be gained with Activity.requestPermissions(String[], int).
Requires Manifest.permission.BLUETOOTH_CONNECT

close

public void close ()

Close this Bluetooth GATT client.

Application should call this method as early as possible after it is done with this GATT client.
For apps targeting Build.VERSION_CODES.S or or higher, this requires the Manifest.permission.BLUETOOTH_CONNECT permission which can be gained with Activity.requestPermissions(String[], int).
Requires Manifest.permission.BLUETOOTH_CONNECT

connect

public boolean connect ()

Connect back to remote device.

This method is used to re-connect to a remote device after the connection has been dropped. If the device is not in range, the re-connection will be triggered once the device is back in range.
For apps targeting Build.VERSION_CODES.S or or higher, this requires the Manifest.permission.BLUETOOTH_CONNECT permission which can be gained with Activity.requestPermissions(String[], int).
Requires Manifest.permission.BLUETOOTH_CONNECT

disconnect

public void disconnect ()

Disconnects an established connection, or cancels a connection attempt currently in progress.
For apps targeting Build.VERSION_CODES.R or lower, this requires the Manifest.permission.BLUETOOTH permission which can be gained with a simple <uses-permission> manifest tag.
For apps targeting Build.VERSION_CODES.S or or higher, this requires the Manifest.permission.BLUETOOTH_CONNECT permission which can be gained with Activity.requestPermissions(String[], int).
Requires Manifest.permission.BLUETOOTH_CONNECT

discoverServices

public boolean discoverServices ()

Discovers services offered by a remote device as well as their characteristics and descriptors.

This is an asynchronous operation. Once service discovery is completed, the BluetoothGattCallback.onServicesDiscovered(BluetoothGatt, int) callback is triggered. If the discovery was successful, the remote services can be retrieved using the getServices() function.
For apps targeting Build.VERSION_CODES.R or lower, this requires the Manifest.permission.BLUETOOTH permission which can be gained with a simple <uses-permission> manifest tag.
For apps targeting Build.VERSION_CODES.S or or higher, this requires the Manifest.permission.BLUETOOTH_CONNECT permission which can be gained with Activity.requestPermissions(String[], int).
Requires Manifest.permission.BLUETOOTH_CONNECT

executeReliableWrite

public boolean executeReliableWrite ()

Executes a reliable write transaction for a given remote device.

This function will commit all queued up characteristic write operations for a given remote device.

A BluetoothGattCallback.onReliableWriteCompleted callback is invoked to indicate whether the transaction has been executed correctly.
For apps targeting Build.VERSION_CODES.R or lower, this requires the Manifest.permission.BLUETOOTH permission which can be gained with a simple <uses-permission> manifest tag.
For apps targeting Build.VERSION_CODES.S or or higher, this requires the Manifest.permission.BLUETOOTH_CONNECT permission which can be gained with Activity.requestPermissions(String[], int).
Requires Manifest.permission.BLUETOOTH_CONNECT

getConnectedDevices

public List<BluetoothDevice> getConnectedDevices ()

This method is deprecated.
Not supported - please use BluetoothManager.getConnectedDevices(int) with BluetoothProfile.GATT as argument

Get connected devices for this specific profile.

Return the set of devices which are in state STATE_CONNECTED

getConnectionState

public int getConnectionState (BluetoothDevice device)

This method is deprecated.
Not supported - please use BluetoothManager.getConnectedDevices(int) with BluetoothProfile.GATT as argument

Get the current connection state of the profile

getDevice

public BluetoothDevice getDevice ()

Return the remote bluetooth device this GATT client targets to

getDevicesMatchingConnectionStates

public List<BluetoothDevice> getDevicesMatchingConnectionStates (int[] states)

This method is deprecated.
Not supported - please use BluetoothManager.getDevicesMatchingConnectionStates(int, int[]) with BluetoothProfile.GATT as first argument

Get a list of devices that match any of the given connection states.

If none of the devices match any of the given states, an empty list will be returned.

getService

public BluetoothGattService getService (UUID uuid)

Returns a BluetoothGattService, if the requested UUID is supported by the remote device.

This function requires that service discovery has been completed for the given device.

If multiple instances of the same service (as identified by UUID) exist, the first instance of the service is returned.
For apps targeting Build.VERSION_CODES.R or lower, this requires the Manifest.permission.BLUETOOTH permission which can be gained with a simple <uses-permission> manifest tag.

getServices

public List<BluetoothGattService> getServices ()

Returns a list of GATT services offered by the remote device.

This function requires that service discovery has been completed for the given device.
For apps targeting Build.VERSION_CODES.R or lower, this requires the Manifest.permission.BLUETOOTH permission which can be gained with a simple <uses-permission> manifest tag.

readCharacteristic

public boolean readCharacteristic (BluetoothGattCharacteristic characteristic)

Reads the requested characteristic from the associated remote device.

This is an asynchronous operation. The result of the read operation is reported by the BluetoothGattCallback.onCharacteristicRead(BluetoothGatt, BluetoothGattCharacteristic, byte[], int) callback.
For apps targeting Build.VERSION_CODES.R or lower, this requires the Manifest.permission.BLUETOOTH permission which can be gained with a simple <uses-permission> manifest tag.
For apps targeting Build.VERSION_CODES.S or or higher, this requires the Manifest.permission.BLUETOOTH_CONNECT permission which can be gained with Activity.requestPermissions(String[], int).
Requires Manifest.permission.BLUETOOTH_CONNECT

readDescriptor

public boolean readDescriptor (BluetoothGattDescriptor descriptor)

Reads the value for a given descriptor from the associated remote device.

Once the read operation has been completed, the BluetoothGattCallback.onDescriptorRead(BluetoothGatt, BluetoothGattDescriptor, int) callback is triggered, signaling the result of the operation.
For apps targeting Build.VERSION_CODES.R or lower, this requires the Manifest.permission.BLUETOOTH permission which can be gained with a simple <uses-permission> manifest tag.
For apps targeting Build.VERSION_CODES.S or or higher, this requires the Manifest.permission.BLUETOOTH_CONNECT permission which can be gained with Activity.requestPermissions(String[], int).
Requires Manifest.permission.BLUETOOTH_CONNECT

readPhy

public void readPhy ()

Read the current transmitter PHY and receiver PHY of the connection. The values are returned in BluetoothGattCallback.onPhyRead
For apps targeting Build.VERSION_CODES.S or or higher, this requires the Manifest.permission.BLUETOOTH_CONNECT permission which can be gained with Activity.requestPermissions(String[], int).
Requires Manifest.permission.BLUETOOTH_CONNECT

readRemoteRssi

public boolean readRemoteRssi ()

Read the RSSI for a connected remote device.

The BluetoothGattCallback.onReadRemoteRssi callback will be invoked when the RSSI value has been read.
For apps targeting Build.VERSION_CODES.R or lower, this requires the Manifest.permission.BLUETOOTH permission which can be gained with a simple <uses-permission> manifest tag.
For apps targeting Build.VERSION_CODES.S or or higher, this requires the Manifest.permission.BLUETOOTH_CONNECT permission which can be gained with Activity.requestPermissions(String[], int).
Requires Manifest.permission.BLUETOOTH_CONNECT

requestConnectionPriority

public boolean requestConnectionPriority (int connectionPriority)

Request a connection parameter update.

This function will send a connection parameter update request to the remote device.
For apps targeting Build.VERSION_CODES.S or or higher, this requires the Manifest.permission.BLUETOOTH_CONNECT permission which can be gained with Activity.requestPermissions(String[], int).
Requires Manifest.permission.BLUETOOTH_CONNECT

requestMtu

public boolean requestMtu (int mtu)

Request an MTU size used for a given connection. Please note that starting from Android 14, the Android Bluetooth stack requests the BLE ATT MTU to 517 bytes when the first GATT client requests an MTU, and disregards all subsequent MTU requests. Check out MTU is set to 517 for the first GATT client requesting an MTU for more information.

When performing a write request operation (write without response), the data sent is truncated to the MTU size. This function may be used to request a larger MTU size to be able to send more data at once.

A BluetoothGattCallback.onMtuChanged callback will indicate whether this operation was successful.
For apps targeting Build.VERSION_CODES.R or lower, this requires the Manifest.permission.BLUETOOTH permission which can be gained with a simple <uses-permission> manifest tag.
For apps targeting Build.VERSION_CODES.S or or higher, this requires the Manifest.permission.BLUETOOTH_CONNECT permission which can be gained with Activity.requestPermissions(String[], int).
Requires Manifest.permission.BLUETOOTH_CONNECT

requestSubrateMode

public int requestSubrateMode (int subrateMode)

Request LE subrate mode.

This function will send a LE subrate request to the remote device.

This method requires the calling app to have the Manifest.permission.BLUETOOTH_CONNECT permission. Additionally, an app must either have the Manifest.permission.BLUETOOTH_PRIVILEGED or be associated with the Companion Device manager (see CompanionDeviceManager.associate(AssociationRequest, android.companion.CompanionDeviceManager.Callback, Handler))
For apps targeting Build.VERSION_CODES.S or or higher, this requires the Manifest.permission.BLUETOOTH_CONNECT permission which can be gained with Activity.requestPermissions(String[], int).

setCharacteristicNotification

public boolean setCharacteristicNotification (BluetoothGattCharacteristic characteristic, 
                boolean enable)

Enable or disable notifications/indications for a given characteristic.

Once notifications are enabled for a characteristic, a BluetoothGattCallback.onCharacteristicChanged(android.bluetooth.BluetoothGatt, android.bluetooth.BluetoothGattCharacteristic, byte[]) callback will be triggered if the remote device indicates that the given characteristic has changed.
For apps targeting Build.VERSION_CODES.R or lower, this requires the Manifest.permission.BLUETOOTH permission which can be gained with a simple <uses-permission> manifest tag.
For apps targeting Build.VERSION_CODES.S or or higher, this requires the Manifest.permission.BLUETOOTH_CONNECT permission which can be gained with Activity.requestPermissions(String[], int).
Requires Manifest.permission.BLUETOOTH_CONNECT

setPreferredPhy

public void setPreferredPhy (int txPhy, 
                int rxPhy, 
                int phyOptions)

Set the preferred connection PHY for this app. Please note that this is just a recommendation, whether the PHY change will happen depends on other applications preferences, local and remote controller capabilities. Controller can override these settings.

BluetoothGattCallback.onPhyUpdate will be triggered as a result of this call, even if no PHY change happens. It is also triggered when remote device updates the PHY.
For apps targeting Build.VERSION_CODES.S or or higher, this requires the Manifest.permission.BLUETOOTH_CONNECT permission which can be gained with Activity.requestPermissions(String[], int).
Requires Manifest.permission.BLUETOOTH_CONNECT

writeCharacteristic

public boolean writeCharacteristic (BluetoothGattCharacteristic characteristic)

This method was deprecated in API level 33.
Use BluetoothGatt.writeCharacteristic(BluetoothGattCharacteristic, byte[], int) as this is not memory safe because it relies on a BluetoothGattCharacteristic object whose underlying fields are subject to change outside this method.

Writes a given characteristic and its values to the associated remote device.

Once the write operation has been completed, the BluetoothGattCallback.onCharacteristicWrite(BluetoothGatt, BluetoothGattCharacteristic, int) callback is invoked, reporting the result of the operation.
For apps targeting Build.VERSION_CODES.R or lower, this requires the Manifest.permission.BLUETOOTH permission which can be gained with a simple <uses-permission> manifest tag.
For apps targeting Build.VERSION_CODES.S or or higher, this requires the Manifest.permission.BLUETOOTH_CONNECT permission which can be gained with Activity.requestPermissions(String[], int).
Requires Manifest.permission.BLUETOOTH_CONNECT

writeCharacteristic

public int writeCharacteristic (BluetoothGattCharacteristic characteristic, 
                byte[] value, 
                int writeType)

Writes a given characteristic and its values to the associated remote device.

Once the write operation has been completed, the BluetoothGattCallback.onCharacteristicWrite(BluetoothGatt, BluetoothGattCharacteristic, int) callback is invoked, reporting the result of the operation.
For apps targeting Build.VERSION_CODES.S or or higher, this requires the Manifest.permission.BLUETOOTH_CONNECT permission which can be gained with Activity.requestPermissions(String[], int).
Requires Manifest.permission.BLUETOOTH_CONNECT

writeDescriptor

public boolean writeDescriptor (BluetoothGattDescriptor descriptor)

This method was deprecated in API level 33.
Use BluetoothGatt.writeDescriptor(BluetoothGattDescriptor, byte[]) as this is not memory safe because it relies on a BluetoothGattDescriptor object whose underlying fields are subject to change outside this method.

Write the value of a given descriptor to the associated remote device.

A BluetoothGattCallback.onDescriptorWrite callback is triggered to report the result of the write operation.
For apps targeting Build.VERSION_CODES.R or lower, this requires the Manifest.permission.BLUETOOTH permission which can be gained with a simple <uses-permission> manifest tag.
For apps targeting Build.VERSION_CODES.S or or higher, this requires the Manifest.permission.BLUETOOTH_CONNECT permission which can be gained with Activity.requestPermissions(String[], int).
Requires Manifest.permission.BLUETOOTH_CONNECT

writeDescriptor

public int writeDescriptor (BluetoothGattDescriptor descriptor, 
                byte[] value)

Write the value of a given descriptor to the associated remote device.

A BluetoothGattCallback.onDescriptorWrite callback is triggered to report the result of the write operation.
For apps targeting Build.VERSION_CODES.S or or higher, this requires the Manifest.permission.BLUETOOTH_CONNECT permission which can be gained with Activity.requestPermissions(String[], int).
Requires Manifest.permission.BLUETOOTH_CONNECT