Skip to content

Most visited

Recently visited

navigation
Added in API level 18

BluetoothGatt

public final class BluetoothGatt
extends Object implements BluetoothProfile

java.lang.Object
   ↳ android.bluetooth.BluetoothGatt


Public API for the Bluetooth GATT Profile.

This class provides Bluetooth GATT functionality to enable communication with Bluetooth Smart or Smart Ready devices.

To connect to a remote peripheral device, create a BluetoothGattCallback and call connectGatt(Context, boolean, BluetoothGattCallback) to get a instance of this class. GATT capable devices can be discovered using the Bluetooth device discovery or BLE scan process.

Summary

Constants

int CONNECTION_PRIORITY_BALANCED

Connection paramter update - Use the connection paramters recommended by the Bluetooth SIG.

int CONNECTION_PRIORITY_HIGH

Connection paramter update - Request a high priority, low latency connection.

int CONNECTION_PRIORITY_LOW_POWER

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

int GATT_CONNECTION_CONGESTED

A remote device connection is congested.

int GATT_FAILURE

A GATT operation failed, errors other than the above

int GATT_INSUFFICIENT_AUTHENTICATION

Insufficient authentication for a given operation

int GATT_INSUFFICIENT_ENCRYPTION

Insufficient encryption for a given operation

int GATT_INVALID_ATTRIBUTE_LENGTH

A write operation exceeds the maximum length of the attribute

int GATT_INVALID_OFFSET

A read or write operation was requested with an invalid offset

int GATT_READ_NOT_PERMITTED

GATT read operation is not permitted

int GATT_REQUEST_NOT_SUPPORTED

The given request is not supported

int GATT_SUCCESS

A GATT operation completed successfully

int GATT_WRITE_NOT_PERMITTED

GATT write operation is not permitted

Inherited constants

From interface android.bluetooth.BluetoothProfile

Public methods

void abortReliableWrite()

Cancels a reliable write transaction for a given device.

void abortReliableWrite(BluetoothDevice mDevice)

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

boolean beginReliableWrite()

Initiates a reliable write transaction for a given remote device.

void close()

Close this Bluetooth GATT client.

boolean connect()

Connect back to remote device.

void disconnect()

Disconnects an established connection, or cancels a connection attempt currently in progress.

boolean discoverServices()

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

boolean executeReliableWrite()

Executes a reliable write transaction for a given remote device.

List<BluetoothDevice> getConnectedDevices()

Not supported - please use getConnectedDevices(int) with GATT as argument

int getConnectionState(BluetoothDevice device)

Not supported - please use getConnectedDevices(int) with GATT as argument

BluetoothDevice getDevice()

Return the remote bluetooth device this GATT client targets to

List<BluetoothDevice> getDevicesMatchingConnectionStates(int[] states)

Not supported - please use getDevicesMatchingConnectionStates(int, int[]) with GATT as first argument

BluetoothGattService getService(UUID uuid)

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

List<BluetoothGattService> getServices()

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

boolean readCharacteristic(BluetoothGattCharacteristic characteristic)

Reads the requested characteristic from the associated remote device.

boolean readDescriptor(BluetoothGattDescriptor descriptor)

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

boolean readRemoteRssi()

Read the RSSI for a connected remote device.

boolean requestConnectionPriority(int connectionPriority)

Request a connection parameter update.

boolean requestMtu(int mtu)

Request an MTU size used for a given connection.

boolean setCharacteristicNotification(BluetoothGattCharacteristic characteristic, boolean enable)

Enable or disable notifications/indications for a given characteristic.

boolean writeCharacteristic(BluetoothGattCharacteristic characteristic)

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

boolean writeDescriptor(BluetoothGattDescriptor descriptor)

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

Inherited methods

From class java.lang.Object
From interface android.bluetooth.BluetoothProfile

Constants

CONNECTION_PRIORITY_BALANCED

Added in API level 21
int CONNECTION_PRIORITY_BALANCED

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

Constant Value: 0 (0x00000000)

CONNECTION_PRIORITY_HIGH

Added in API level 21
int CONNECTION_PRIORITY_HIGH

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

Constant Value: 1 (0x00000001)

CONNECTION_PRIORITY_LOW_POWER

Added in API level 21
int CONNECTION_PRIORITY_LOW_POWER

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

Constant Value: 2 (0x00000002)

GATT_CONNECTION_CONGESTED

Added in API level 21
int GATT_CONNECTION_CONGESTED

A remote device connection is congested.

Constant Value: 143 (0x0000008f)

GATT_FAILURE

Added in API level 18
int GATT_FAILURE

A GATT operation failed, errors other than the above

Constant Value: 257 (0x00000101)

GATT_INSUFFICIENT_AUTHENTICATION

Added in API level 18
int GATT_INSUFFICIENT_AUTHENTICATION

Insufficient authentication for a given operation

Constant Value: 5 (0x00000005)

GATT_INSUFFICIENT_ENCRYPTION

Added in API level 18
int GATT_INSUFFICIENT_ENCRYPTION

Insufficient encryption for a given operation

Constant Value: 15 (0x0000000f)

GATT_INVALID_ATTRIBUTE_LENGTH

Added in API level 18
int GATT_INVALID_ATTRIBUTE_LENGTH

A write operation exceeds the maximum length of the attribute

Constant Value: 13 (0x0000000d)

GATT_INVALID_OFFSET

Added in API level 18
int GATT_INVALID_OFFSET

A read or write operation was requested with an invalid offset

Constant Value: 7 (0x00000007)

GATT_READ_NOT_PERMITTED

Added in API level 18
int GATT_READ_NOT_PERMITTED

GATT read operation is not permitted

Constant Value: 2 (0x00000002)

GATT_REQUEST_NOT_SUPPORTED

Added in API level 18
int GATT_REQUEST_NOT_SUPPORTED

The given request is not supported

Constant Value: 6 (0x00000006)

GATT_SUCCESS

Added in API level 18
int GATT_SUCCESS

A GATT operation completed successfully

Constant Value: 0 (0x00000000)

GATT_WRITE_NOT_PERMITTED

Added in API level 18
int GATT_WRITE_NOT_PERMITTED

GATT write operation is not permitted

Constant Value: 3 (0x00000003)

Public methods

abortReliableWrite

Added in API level 19
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.

Requires BLUETOOTH permission.

abortReliableWrite

Added in API level 18
void abortReliableWrite (BluetoothDevice mDevice)

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

Parameters
mDevice BluetoothDevice

beginReliableWrite

Added in API level 18
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 an onCharacteristicWrite(BluetoothGatt, BluetoothGattCharacteristic, int) callback in response to every writeCharacteristic(BluetoothGattCharacteristic) 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 commiting any values on the remote device.

Requires BLUETOOTH permission.

Returns
boolean true, if the reliable write transaction has been initiated

close

Added in API level 18
void close ()

Close this Bluetooth GATT client. Application should call this method as early as possible after it is done with this GATT client.

connect

Added in API level 18
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.

Returns
boolean true, if the connection attempt was initiated successfully

disconnect

Added in API level 18
void disconnect ()

Disconnects an established connection, or cancels a connection attempt currently in progress.

Requires BLUETOOTH permission.

discoverServices

Added in API level 18
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 onServicesDiscovered(BluetoothGatt, int) callback is triggered. If the discovery was successful, the remote services can be retrieved using the getServices() function.

Requires BLUETOOTH permission.

Returns
boolean true, if the remote service discovery has been started

executeReliableWrite

Added in API level 18
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 onReliableWriteCompleted(BluetoothGatt, int) callback is invoked to indicate whether the transaction has been executed correctly.

Requires BLUETOOTH permission.

Returns
boolean true, if the request to execute the transaction has been sent

getConnectedDevices

Added in API level 18
List<BluetoothDevice> getConnectedDevices ()

Not supported - please use getConnectedDevices(int) with GATT as argument

Returns
List<BluetoothDevice> List of devices. The list will be empty on error.
Throws
UnsupportedOperationException

getConnectionState

Added in API level 18
int getConnectionState (BluetoothDevice device)

Not supported - please use getConnectedDevices(int) with GATT as argument

Parameters
device BluetoothDevice: Remote bluetooth device.
Returns
int State of the profile connection. One of STATE_CONNECTED, STATE_CONNECTING, STATE_DISCONNECTED, STATE_DISCONNECTING
Throws
UnsupportedOperationException

getDevice

Added in API level 18
BluetoothDevice getDevice ()

Return the remote bluetooth device this GATT client targets to

Returns
BluetoothDevice remote bluetooth device

getDevicesMatchingConnectionStates

Added in API level 18
List<BluetoothDevice> getDevicesMatchingConnectionStates (int[] states)

Not supported - please use getDevicesMatchingConnectionStates(int, int[]) with GATT as first argument

Parameters
states int: Array of states. States can be one of STATE_CONNECTED, STATE_CONNECTING, STATE_DISCONNECTED, STATE_DISCONNECTING,
Returns
List<BluetoothDevice> List of devices. The list will be empty on error.
Throws
UnsupportedOperationException

getService

Added in API level 18
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.

Requires BLUETOOTH permission.

Parameters
uuid UUID: UUID of the requested service
Returns
BluetoothGattService BluetoothGattService if supported, or null if the requested service is not offered by the remote device.

getServices

Added in API level 18
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.

Requires BLUETOOTH permission.

Returns
List<BluetoothGattService> List of services on the remote device. Returns an empty list if service discovery has not yet been performed.

readCharacteristic

Added in API level 18
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 onCharacteristicRead(BluetoothGatt, BluetoothGattCharacteristic, int) callback.

Requires BLUETOOTH permission.

Parameters
characteristic BluetoothGattCharacteristic: Characteristic to read from the remote device
Returns
boolean true, if the read operation was initiated successfully

readDescriptor

Added in API level 18
boolean readDescriptor (BluetoothGattDescriptor descriptor)

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

Once the read operation has been completed, the onDescriptorRead(BluetoothGatt, BluetoothGattDescriptor, int) callback is triggered, signaling the result of the operation.

Requires BLUETOOTH permission.

Parameters
descriptor BluetoothGattDescriptor: Descriptor value to read from the remote device
Returns
boolean true, if the read operation was initiated successfully

readRemoteRssi

Added in API level 18
boolean readRemoteRssi ()

Read the RSSI for a connected remote device.

The onReadRemoteRssi(BluetoothGatt, int, int) callback will be invoked when the RSSI value has been read.

Requires BLUETOOTH permission.

Returns
boolean true, if the RSSI value has been requested successfully

requestConnectionPriority

Added in API level 21
boolean requestConnectionPriority (int connectionPriority)

Request a connection parameter update.

This function will send a connection parameter update request to the remote device.

Parameters
connectionPriority int: Request a specific connection priority. Must be one of CONNECTION_PRIORITY_BALANCED, CONNECTION_PRIORITY_HIGH or CONNECTION_PRIORITY_LOW_POWER.
Returns
boolean
Throws
IllegalArgumentException If the parameters are outside of their specified range.

requestMtu

Added in API level 21
boolean requestMtu (int mtu)

Request an MTU size used for a given connection.

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 onMtuChanged(BluetoothGatt, int, int) callback will indicate whether this operation was successful.

Requires BLUETOOTH permission.

Parameters
mtu int
Returns
boolean true, if the new MTU value has been requested successfully

setCharacteristicNotification

Added in API level 18
boolean setCharacteristicNotification (BluetoothGattCharacteristic characteristic, 
                boolean enable)

Enable or disable notifications/indications for a given characteristic.

Once notifications are enabled for a characteristic, a onCharacteristicChanged(BluetoothGatt, BluetoothGattCharacteristic) callback will be triggered if the remote device indicates that the given characteristic has changed.

Requires BLUETOOTH permission.

Parameters
characteristic BluetoothGattCharacteristic: The characteristic for which to enable notifications
enable boolean: Set to true to enable notifications/indications
Returns
boolean true, if the requested notification status was set successfully

writeCharacteristic

Added in API level 18
boolean writeCharacteristic (BluetoothGattCharacteristic characteristic)

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

Once the write operation has been completed, the onCharacteristicWrite(BluetoothGatt, BluetoothGattCharacteristic, int) callback is invoked, reporting the result of the operation.

Requires BLUETOOTH permission.

Parameters
characteristic BluetoothGattCharacteristic: Characteristic to write on the remote device
Returns
boolean true, if the write operation was initiated successfully

writeDescriptor

Added in API level 18
boolean writeDescriptor (BluetoothGattDescriptor descriptor)

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

A onDescriptorWrite(BluetoothGatt, BluetoothGattDescriptor, int) callback is triggered to report the result of the write operation.

Requires BLUETOOTH permission.

Parameters
descriptor BluetoothGattDescriptor: Descriptor to write to the associated remote device
Returns
boolean true, if the write operation was initiated successfully
This site uses cookies to store your preferences for site-specific language and display options.

Hooray!

This class requires API level or higher

This doc is hidden because your selected API level for the documentation is . You can change the documentation API level with the selector above the left navigation.

For more information about specifying the API level your app requires, read Supporting Different Platform Versions.