Please note that the contents of this offline web site may be out of date. To access the most recent documentation visit the online version .
Note that links that point to online resources are green in color and will open in a new window.
We would love it if you could give us feedback about this material by filling this form (You have to be online to fill it)
Android APIs
public final class

BluetoothDevice

extends Object
implements Parcelable
java.lang.Object
   ↳ android.bluetooth.BluetoothDevice

Class Overview

Represents a remote Bluetooth device. A BluetoothDevice lets you create a connection with the respective device or query information about it, such as the name, address, class, and bonding state.

This class is really just a thin wrapper for a Bluetooth hardware address. Objects of this class are immutable. Operations on this class are performed on the remote Bluetooth hardware address, using the BluetoothAdapter that was used to create this BluetoothDevice .

To get a BluetoothDevice , use BluetoothAdapter.getRemoteDevice(String) to create one representing a device of a known MAC address (which you can get through device discovery with BluetoothAdapter ) or get one from the set of bonded devices returned by BluetoothAdapter.getBondedDevices() . You can then open a BluetoothSocket for communication with the remote device, using createRfcommSocketToServiceRecord(UUID) .

Note: Requires the BLUETOOTH permission.

Developer Guides

For more information about using Bluetooth, read the Bluetooth developer guide.

Summary

Constants
String ACTION_ACL_CONNECTED Broadcast Action: Indicates a low level (ACL) connection has been established with a remote device.
String ACTION_ACL_DISCONNECTED Broadcast Action: Indicates a low level (ACL) disconnection from a remote device.
String ACTION_ACL_DISCONNECT_REQUESTED Broadcast Action: Indicates that a low level (ACL) disconnection has been requested for a remote device, and it will soon be disconnected.
String ACTION_BOND_STATE_CHANGED Broadcast Action: Indicates a change in the bond state of a remote device.
String ACTION_CLASS_CHANGED Broadcast Action: Bluetooth class of a remote device has changed.
String ACTION_FOUND Broadcast Action: Remote device discovered.
String ACTION_NAME_CHANGED Broadcast Action: Indicates the friendly name of a remote device has been retrieved for the first time, or changed since the last retrieval.
String ACTION_PAIRING_REQUEST Broadcast Action: This intent is used to broadcast PAIRING REQUEST

Requires BLUETOOTH_ADMIN to receive.

String ACTION_UUID Broadcast Action: This intent is used to broadcast the UUID wrapped as a ParcelUuid of the remote device after it has been fetched.
int BOND_BONDED Indicates the remote device is bonded (paired).
int BOND_BONDING Indicates bonding (pairing) is in progress with the remote device.
int BOND_NONE Indicates the remote device is not bonded (paired).
int DEVICE_TYPE_CLASSIC Bluetooth device type, Classic - BR/EDR devices
int DEVICE_TYPE_DUAL Bluetooth device type, Dual Mode - BR/EDR/LE
int DEVICE_TYPE_LE Bluetooth device type, Low Energy - LE-only
int DEVICE_TYPE_UNKNOWN Bluetooth device type, Unknown
int ERROR Sentinel error value for this class.
String EXTRA_BOND_STATE Used as an int extra field in ACTION_BOND_STATE_CHANGED intents.
String EXTRA_CLASS Used as a Parcelable BluetoothClass extra field in ACTION_FOUND and ACTION_CLASS_CHANGED intents.
String EXTRA_DEVICE Used as a Parcelable BluetoothDevice extra field in every intent broadcast by this class.
String EXTRA_NAME Used as a String extra field in ACTION_NAME_CHANGED and ACTION_FOUND intents.
String EXTRA_PAIRING_KEY Used as an int extra field in ACTION_PAIRING_REQUEST intents as the value of passkey.
String EXTRA_PAIRING_VARIANT Used as an int extra field in ACTION_PAIRING_REQUEST intents to indicate pairing method used.
String EXTRA_PREVIOUS_BOND_STATE Used as an int extra field in ACTION_BOND_STATE_CHANGED intents.
String EXTRA_RSSI Used as an optional short extra field in ACTION_FOUND intents.
String EXTRA_UUID Used as an extra field in ACTION_UUID intents, Contains the ParcelUuid s of the remote device which is a parcelable version of UUID .
int PAIRING_VARIANT_PASSKEY_CONFIRMATION The user will be prompted to confirm the passkey displayed on the screen or an app will confirm the passkey for the user.
int PAIRING_VARIANT_PIN The user will be prompted to enter a pin or an app will enter a pin for user.
[Expand]
Inherited Constants
From interface android.os.Parcelable
Fields
public static final Creator < BluetoothDevice > CREATOR
Public Methods
BluetoothGatt connectGatt ( Context context, boolean autoConnect, BluetoothGattCallback callback)
Connect to GATT Server hosted by this device.
boolean createBond ()
Start the bonding (pairing) process with the remote device.
BluetoothSocket createInsecureRfcommSocketToServiceRecord ( UUID uuid)
Create an RFCOMM BluetoothSocket socket ready to start an insecure outgoing connection to this remote device using SDP lookup of uuid.
BluetoothSocket createRfcommSocketToServiceRecord ( UUID uuid)
Create an RFCOMM BluetoothSocket ready to start a secure outgoing connection to this remote device using SDP lookup of uuid.
int describeContents ()
Describe the kinds of special objects contained in this Parcelable's marshalled representation.
boolean equals ( Object o)
Compares this instance with the specified object and indicates if they are equal.
boolean fetchUuidsWithSdp ()
Perform a service discovery on the remote device to get the UUIDs supported.
String getAddress ()
Returns the hardware address of this BluetoothDevice.
BluetoothClass getBluetoothClass ()
Get the Bluetooth class of the remote device.
int getBondState ()
Get the bond state of the remote device.
String getName ()
Get the friendly Bluetooth name of the remote device.
int getType ()
Get the Bluetooth device type of the remote device.
ParcelUuid[] getUuids ()
Returns the supported features (UUIDs) of the remote device.
int hashCode ()
Returns an integer hash code for this object.
boolean setPairingConfirmation (boolean confirm)
Confirm passkey for PAIRING_VARIANT_PASSKEY_CONFIRMATION pairing.
boolean setPin (byte[] pin)
Set the pin during pairing when the pairing method is PAIRING_VARIANT_PIN

Requires BLUETOOTH_ADMIN .

String toString ()
Returns a string representation of this BluetoothDevice.
void writeToParcel ( Parcel out, int flags)
Flatten this object in to a Parcel.
[Expand]
Inherited Methods
From class java.lang.Object
From interface android.os.Parcelable

Constants

public static final String ACTION_ACL_CONNECTED

Added in API level 5

Broadcast Action: Indicates a low level (ACL) connection has been established with a remote device.

Always contains the extra field EXTRA_DEVICE .

ACL connections are managed automatically by the Android Bluetooth stack.

Requires BLUETOOTH to receive.

Constant Value: "android.bluetooth.device.action.ACL_CONNECTED"

public static final String ACTION_ACL_DISCONNECTED

Added in API level 5

Broadcast Action: Indicates a low level (ACL) disconnection from a remote device.

Always contains the extra field EXTRA_DEVICE .

ACL connections are managed automatically by the Android Bluetooth stack.

Requires BLUETOOTH to receive.

Constant Value: "android.bluetooth.device.action.ACL_DISCONNECTED"

public static final String ACTION_ACL_DISCONNECT_REQUESTED

Added in API level 5

Broadcast Action: Indicates that a low level (ACL) disconnection has been requested for a remote device, and it will soon be disconnected.

This is useful for graceful disconnection. Applications should use this intent as a hint to immediately terminate higher level connections (RFCOMM, L2CAP, or profile connections) to the remote device.

Always contains the extra field EXTRA_DEVICE .

Requires BLUETOOTH to receive.

Constant Value: "android.bluetooth.device.action.ACL_DISCONNECT_REQUESTED"

public static final String ACTION_BOND_STATE_CHANGED

Added in API level 5

Broadcast Action: Indicates a change in the bond state of a remote device. For example, if a device is bonded (paired).

Always contains the extra fields EXTRA_DEVICE , EXTRA_BOND_STATE and EXTRA_PREVIOUS_BOND_STATE .

Requires BLUETOOTH to receive.

Constant Value: "android.bluetooth.device.action.BOND_STATE_CHANGED"

public static final String ACTION_CLASS_CHANGED

Added in API level 5

Broadcast Action: Bluetooth class of a remote device has changed.

Always contains the extra fields EXTRA_DEVICE and EXTRA_CLASS .

Requires BLUETOOTH to receive.

Constant Value: "android.bluetooth.device.action.CLASS_CHANGED"

public static final String ACTION_FOUND

Added in API level 5

Broadcast Action: Remote device discovered.

Sent when a remote device is found during discovery.

Always contains the extra fields EXTRA_DEVICE and EXTRA_CLASS . Can contain the extra fields EXTRA_NAME and/or EXTRA_RSSI if they are available.

Requires BLUETOOTH to receive.

Constant Value: "android.bluetooth.device.action.FOUND"

public static final String ACTION_NAME_CHANGED

Added in API level 5

Broadcast Action: Indicates the friendly name of a remote device has been retrieved for the first time, or changed since the last retrieval.

Always contains the extra fields EXTRA_DEVICE and EXTRA_NAME .

Requires BLUETOOTH to receive.

Constant Value: "android.bluetooth.device.action.NAME_CHANGED"

public static final String ACTION_PAIRING_REQUEST

Broadcast Action: This intent is used to broadcast PAIRING REQUEST

Requires BLUETOOTH_ADMIN to receive.

Constant Value: "android.bluetooth.device.action.PAIRING_REQUEST"

public static final String ACTION_UUID

Broadcast Action: This intent is used to broadcast the UUID wrapped as a ParcelUuid of the remote device after it has been fetched. This intent is sent only when the UUIDs of the remote device are requested to be fetched using Service Discovery Protocol

Always contains the extra field EXTRA_DEVICE

Always contains the extra field EXTRA_UUID

Requires BLUETOOTH to receive.

Constant Value: "android.bluetooth.device.action.UUID"

public static final int BOND_BONDED

Added in API level 5

Indicates the remote device is bonded (paired).

A shared link keys exists locally for the remote device, so communication can be authenticated and encrypted.

Being bonded (paired) with a remote device does not necessarily mean the device is currently connected. It just means that the pending procedure was completed at some earlier time, and the link key is still stored locally, ready to use on the next connection.

Constant Value: 12 (0x0000000c)

public static final int BOND_BONDING

Added in API level 5

Indicates bonding (pairing) is in progress with the remote device.

Constant Value: 11 (0x0000000b)

public static final int BOND_NONE

Added in API level 5

Indicates the remote device is not bonded (paired).

There is no shared link key with the remote device, so communication (if it is allowed at all) will be unauthenticated and unencrypted.

Constant Value: 10 (0x0000000a)

public static final int DEVICE_TYPE_CLASSIC

Bluetooth device type, Classic - BR/EDR devices

Constant Value: 1 (0x00000001)

public static final int DEVICE_TYPE_DUAL

Bluetooth device type, Dual Mode - BR/EDR/LE

Constant Value: 3 (0x00000003)

public static final int DEVICE_TYPE_LE

Bluetooth device type, Low Energy - LE-only

Constant Value: 2 (0x00000002)

public static final int DEVICE_TYPE_UNKNOWN

Bluetooth device type, Unknown

Constant Value: 0 (0x00000000)

public static final int ERROR

Added in API level 5

Sentinel error value for this class. Guaranteed to not equal any other integer constant in this class. Provided as a convenience for functions that require a sentinel error value, for example:

Intent.getIntExtra(BluetoothDevice.EXTRA_BOND_STATE, BluetoothDevice.ERROR)

Constant Value: -2147483648 (0x80000000)

public static final String EXTRA_BOND_STATE

Added in API level 5

Used as an int extra field in ACTION_BOND_STATE_CHANGED intents. Contains the bond state of the remote device.

Possible values are: BOND_NONE , BOND_BONDING , BOND_BONDED .

Constant Value: "android.bluetooth.device.extra.BOND_STATE"

public static final String EXTRA_CLASS

Added in API level 5

Used as a Parcelable BluetoothClass extra field in ACTION_FOUND and ACTION_CLASS_CHANGED intents.

Constant Value: "android.bluetooth.device.extra.CLASS"

public static final String EXTRA_DEVICE

Added in API level 5

Used as a Parcelable BluetoothDevice extra field in every intent broadcast by this class. It contains the BluetoothDevice that the intent applies to.

Constant Value: "android.bluetooth.device.extra.DEVICE"

public static final String EXTRA_NAME

Added in API level 5

Used as a String extra field in ACTION_NAME_CHANGED and ACTION_FOUND intents. It contains the friendly Bluetooth name.

Constant Value: "android.bluetooth.device.extra.NAME"

public static final String EXTRA_PAIRING_KEY

Used as an int extra field in ACTION_PAIRING_REQUEST intents as the value of passkey.

Constant Value: "android.bluetooth.device.extra.PAIRING_KEY"

public static final String EXTRA_PAIRING_VARIANT

Used as an int extra field in ACTION_PAIRING_REQUEST intents to indicate pairing method used. Possible values are: PAIRING_VARIANT_PIN , PAIRING_VARIANT_PASSKEY_CONFIRMATION ,

Constant Value: "android.bluetooth.device.extra.PAIRING_VARIANT"

public static final String EXTRA_PREVIOUS_BOND_STATE

Added in API level 5

Used as an int extra field in ACTION_BOND_STATE_CHANGED intents. Contains the previous bond state of the remote device.

Possible values are: BOND_NONE , BOND_BONDING , BOND_BONDED .

Constant Value: "android.bluetooth.device.extra.PREVIOUS_BOND_STATE"

public static final String EXTRA_RSSI

Added in API level 5

Used as an optional short extra field in ACTION_FOUND intents. Contains the RSSI value of the remote device as reported by the Bluetooth hardware.

Constant Value: "android.bluetooth.device.extra.RSSI"

public static final String EXTRA_UUID

Used as an extra field in ACTION_UUID intents, Contains the ParcelUuid s of the remote device which is a parcelable version of UUID .

Constant Value: "android.bluetooth.device.extra.UUID"

public static final int PAIRING_VARIANT_PASSKEY_CONFIRMATION

The user will be prompted to confirm the passkey displayed on the screen or an app will confirm the passkey for the user.

Constant Value: 2 (0x00000002)

public static final int PAIRING_VARIANT_PIN

The user will be prompted to enter a pin or an app will enter a pin for user.

Constant Value: 0 (0x00000000)

Fields

public static final Creator < BluetoothDevice > CREATOR

Added in API level 5

Public Methods

public BluetoothGatt connectGatt ( Context context, boolean autoConnect, BluetoothGattCallback callback)

Connect to GATT Server hosted by this device. Caller acts as GATT client. The callback is used to deliver results to Caller, such as connection status as well as any further GATT client operations. The method returns a BluetoothGatt instance. You can use BluetoothGatt to conduct GATT client operations.

Parameters
autoConnect Whether to directly connect to the remote device (false) or to automatically connect as soon as the remote device becomes available (true).
callback GATT callback handler that will receive asynchronous callbacks.
Throws
IllegalArgumentException if callback is null

public boolean createBond ()

Start the bonding (pairing) process with the remote device.

This is an asynchronous call, it will return immediately. Register for ACTION_BOND_STATE_CHANGED intents to be notified when the bonding process completes, and its result.

Android system services will handle the necessary user interactions to confirm and complete the bonding process.

Requires BLUETOOTH_ADMIN .

Returns
  • false on immediate error, true if bonding will begin

public BluetoothSocket createInsecureRfcommSocketToServiceRecord ( UUID uuid)

Create an RFCOMM BluetoothSocket socket ready to start an insecure outgoing connection to this remote device using SDP lookup of uuid.

The communication channel will not have an authenticated link key i.e it will be subject to man-in-the-middle attacks. For Bluetooth 2.1 devices, the link key will be encrypted, as encryption is mandatory. For legacy devices (pre Bluetooth 2.1 devices) the link key will be not be encrypted. Use createRfcommSocketToServiceRecord(UUID) if an encrypted and authenticated communication channel is desired.

This is designed to be used with listenUsingInsecureRfcommWithServiceRecord(String, UUID) for peer-peer Bluetooth applications.

Use connect() to initiate the outgoing connection. This will also perform an SDP lookup of the given uuid to determine which channel to connect to.

The remote device will be authenticated and communication on this socket will be encrypted.

Hint: If you are connecting to a Bluetooth serial board then try using the well-known SPP UUID 00001101-0000-1000-8000-00805F9B34FB. However if you are connecting to an Android peer then please generate your own unique UUID.

Requires BLUETOOTH

Parameters
uuid service record uuid to lookup RFCOMM channel
Returns
  • a RFCOMM BluetoothServerSocket ready for an outgoing connection
Throws
IOException on error, for example Bluetooth not available, or insufficient permissions

public BluetoothSocket createRfcommSocketToServiceRecord ( UUID uuid)

Added in API level 5

Create an RFCOMM BluetoothSocket ready to start a secure outgoing connection to this remote device using SDP lookup of uuid.

This is designed to be used with listenUsingRfcommWithServiceRecord(String, UUID) for peer-peer Bluetooth applications.

Use connect() to initiate the outgoing connection. This will also perform an SDP lookup of the given uuid to determine which channel to connect to.

The remote device will be authenticated and communication on this socket will be encrypted.

Use this socket only if an authenticated socket link is possible. Authentication refers to the authentication of the link key to prevent man-in-the-middle type of attacks. For example, for Bluetooth 2.1 devices, if any of the devices does not have an input and output capability or just has the ability to display a numeric key, a secure socket connection is not possible. In such a case, use {#link createInsecureRfcommSocketToServiceRecord}. For more details, refer to the Security Model section 5.2 (vol 3) of Bluetooth Core Specification version 2.1 + EDR.

Hint: If you are connecting to a Bluetooth serial board then try using the well-known SPP UUID 00001101-0000-1000-8000-00805F9B34FB. However if you are connecting to an Android peer then please generate your own unique UUID.

Requires BLUETOOTH

Parameters
uuid service record uuid to lookup RFCOMM channel
Returns
  • a RFCOMM BluetoothServerSocket ready for an outgoing connection
Throws
IOException on error, for example Bluetooth not available, or insufficient permissions

public int describeContents ()

Added in API level 5

Describe the kinds of special objects contained in this Parcelable's marshalled representation.

Returns
  • a bitmask indicating the set of special object types marshalled by the Parcelable.

public boolean equals ( Object o)

Added in API level 5

Compares this instance with the specified object and indicates if they are equal. In order to be equal, o must represent the same object as this instance using a class-specific comparison. The general contract is that this comparison should be reflexive, symmetric, and transitive. Also, no object reference other than null is equal to null.

The default implementation returns true only if this == o . See Writing a correct equals method if you intend implementing your own equals method.

The general contract for the equals and hashCode() methods is that if equals returns true for any two objects, then hashCode() must return the same value for these objects. This means that subclasses of Object usually override either both methods or neither of them.

Parameters
o the object to compare this instance with.
Returns
  • true if the specified object is equal to this Object ; false otherwise.

public boolean fetchUuidsWithSdp ()

Perform a service discovery on the remote device to get the UUIDs supported.

This API is asynchronous and ACTION_UUID intent is sent, with the UUIDs supported by the remote end. If there is an error in getting the SDP records or if the process takes a long time, ACTION_UUID intent is sent with the UUIDs that is currently present in the cache. Clients should use the getUuids() to get UUIDs if service discovery is not to be performed.

Requires BLUETOOTH .

Returns
  • False if the sanity check fails, True if the process of initiating an ACL connection to the remote device was started.

public String getAddress ()

Added in API level 5

Returns the hardware address of this BluetoothDevice.

For example, "00:11:22:AA:BB:CC".

Returns
  • Bluetooth hardware address as string

public BluetoothClass getBluetoothClass ()

Added in API level 5

Get the Bluetooth class of the remote device.

Requires BLUETOOTH .

Returns
  • Bluetooth class object, or null on error

public int getBondState ()

Added in API level 5

Get the bond state of the remote device.

Possible values for the bond state are: BOND_NONE , BOND_BONDING , BOND_BONDED .

Requires BLUETOOTH .

Returns
  • the bond state

public String getName ()

Added in API level 5

Get the friendly Bluetooth name of the remote device.

The local adapter will automatically retrieve remote names when performing a device scan, and will cache them. This method just returns the name for this device from the cache.

Requires BLUETOOTH

Returns
  • the Bluetooth name, or null if there was a problem.

public int getType ()

Get the Bluetooth device type of the remote device.

Requires BLUETOOTH

public ParcelUuid[] getUuids ()

Returns the supported features (UUIDs) of the remote device.

This method does not start a service discovery procedure to retrieve the UUIDs from the remote device. Instead, the local cached copy of the service UUIDs are returned.

Use fetchUuidsWithSdp() if fresh UUIDs are desired.

Requires BLUETOOTH .

Returns
  • the supported features (UUIDs) of the remote device, or null on error

public int hashCode ()

Added in API level 5

Returns an integer hash code for this object. By contract, any two objects for which equals(Object) returns true must return the same hash code value. This means that subclasses of Object usually override both methods or neither method.

Note that hash values must not change over time unless information used in equals comparisons also changes.

See Writing a correct hashCode method if you intend implementing your own hashCode method.

Returns
  • this object's hash code.

public boolean setPairingConfirmation (boolean confirm)

Confirm passkey for PAIRING_VARIANT_PASSKEY_CONFIRMATION pairing.

Requires BLUETOOTH_ADMIN .

Returns
  • true confirmation has been sent out false for error

public boolean setPin (byte[] pin)

Set the pin during pairing when the pairing method is PAIRING_VARIANT_PIN

Requires BLUETOOTH_ADMIN .

Returns
  • true pin has been set false for error

public String toString ()

Added in API level 5

Returns a string representation of this BluetoothDevice.

Currently this is the Bluetooth hardware address, for example "00:11:22:AA:BB:CC". However, you should always use getAddress() if you explicitly require the Bluetooth hardware address in case the toString() representation changes in the future.

Returns
  • string representation of this BluetoothDevice

public void writeToParcel ( Parcel out, int flags)

Added in API level 5

Flatten this object in to a Parcel.

Parameters
out The Parcel in which the object should be written.
flags Additional flags about how the object should be written. May be 0 or PARCELABLE_WRITE_RETURN_VALUE .