public class BluetoothPeripheral
extends java.lang.Object
A BluetoothPeripheral
lets you create a connection with the peripheral or query information about it.
This class is a wrapper around the BluetoothDevice
and takes care of operation queueing, some Android bugs, and provides several convenience functions.
Modifier and Type | Field and Description |
---|---|
static int |
MAX_MTU
Max MTU that Android can handle
|
Modifier and Type | Method and Description |
---|---|
void |
cancelConnection()
Cancel an active or pending connection.
|
boolean |
clearServicesCache()
Asynchronous method to clear the services cache.
|
boolean |
createBond()
Create a bond with the peripheral.
|
@NotNull java.lang.String |
getAddress()
Get the mac address of the bluetooth peripheral.
|
@NotNull BondState |
getBondState()
Get the bond state of the bluetooth peripheral.
|
@Nullable android.bluetooth.BluetoothGattCharacteristic |
getCharacteristic(@NotNull java.util.UUID serviceUUID,
@NotNull java.util.UUID characteristicUUID)
Get the BluetoothGattCharacteristic object for a characteristic UUID.
|
int |
getCurrentMtu()
Returns the currently set MTU
|
int |
getMaximumWriteValueLength(@NotNull WriteType writeType)
Get maximum length of byte array that can be written depending on WriteType
|
@NotNull java.lang.String |
getName()
Get the name of the bluetooth peripheral.
|
@NotNull java.util.Set<android.bluetooth.BluetoothGattCharacteristic> |
getNotifyingCharacteristics()
Get all notifying/indicating characteristics
|
@Nullable android.bluetooth.BluetoothGattService |
getService(@NotNull java.util.UUID serviceUUID)
Get the BluetoothGattService object for a service UUID.
|
@NotNull java.util.List<android.bluetooth.BluetoothGattService> |
getServices()
Get the services supported by the connected bluetooth peripheral.
|
@NotNull ConnectionState |
getState()
Returns the connection state of the peripheral.
|
@NotNull PeripheralType |
getType()
Get the type of the peripheral.
|
boolean |
isNotifying(@NotNull android.bluetooth.BluetoothGattCharacteristic characteristic)
Boolean to indicate if the specified characteristic is currently notifying or indicating.
|
boolean |
readCharacteristic(@NotNull android.bluetooth.BluetoothGattCharacteristic characteristic)
Read the value of a characteristic.
|
boolean |
readCharacteristic(@NotNull java.util.UUID serviceUUID,
@NotNull java.util.UUID characteristicUUID)
Read the value of a characteristic.
|
boolean |
readDescriptor(@NotNull android.bluetooth.BluetoothGattDescriptor descriptor)
Read the value of a descriptor.
|
boolean |
readPhy()
Read the current transmitter PHY and receiver PHY of the connection.
|
boolean |
readRemoteRssi()
Read the RSSI for a connected remote peripheral.
|
boolean |
requestConnectionPriority(@NotNull ConnectionPriority priority)
Request a different connection priority.
|
boolean |
requestMtu(int mtu)
Request an MTU size used for a given connection.
|
boolean |
setNotify(@NotNull android.bluetooth.BluetoothGattCharacteristic characteristic,
boolean enable)
Set the notification state of a characteristic to 'on' or 'off'.
|
boolean |
setNotify(@NotNull java.util.UUID serviceUUID,
@NotNull java.util.UUID characteristicUUID,
boolean enable)
Set the notification state of a characteristic to 'on' or 'off'.
|
boolean |
setPreferredPhy(@NotNull PhyType txPhy,
@NotNull PhyType rxPhy,
@NotNull PhyOptions phyOptions)
Set the preferred connection PHY for this app.
|
boolean |
writeCharacteristic(@NotNull android.bluetooth.BluetoothGattCharacteristic characteristic,
@NotNull byte[] value,
@NotNull WriteType writeType)
Write a value to a characteristic using the specified write type.
|
boolean |
writeCharacteristic(@NotNull java.util.UUID serviceUUID,
@NotNull java.util.UUID characteristicUUID,
@NotNull byte[] value,
@NotNull WriteType writeType)
Write a value to a characteristic using the specified write type.
|
boolean |
writeDescriptor(@NotNull android.bluetooth.BluetoothGattDescriptor descriptor,
@NotNull byte[] value)
Write a value to a descriptor.
|
public static final int MAX_MTU
public boolean createBond()
If a (auto)connect has been issued, the bonding command will be enqueued and you will
receive updates via the BluetoothPeripheralCallback
. Otherwise the bonding will
be done immediately and no updates via the callback will happen.
public void cancelConnection()
This operation is asynchronous and you will receive a callback on onDisconnectedPeripheral.
@NotNull public @NotNull java.lang.String getAddress()
@NotNull public @NotNull PeripheralType getType()
@NotNull public @NotNull java.lang.String getName()
@NotNull public @NotNull BondState getBondState()
@NotNull public @NotNull java.util.List<android.bluetooth.BluetoothGattService> getServices()
BluetoothCentralManager
are included.@Nullable public @Nullable android.bluetooth.BluetoothGattService getService(@NotNull @NotNull java.util.UUID serviceUUID)
serviceUUID
- the UUID of the service@Nullable public @Nullable android.bluetooth.BluetoothGattCharacteristic getCharacteristic(@NotNull @NotNull java.util.UUID serviceUUID, @NotNull @NotNull java.util.UUID characteristicUUID)
serviceUUID
- the service UUID the characteristic is part ofcharacteristicUUID
- the UUID of the chararacteristic@NotNull public @NotNull ConnectionState getState()
public int getCurrentMtu()
public int getMaximumWriteValueLength(@NotNull @NotNull WriteType writeType)
This value is derived from the current negotiated MTU or the maximum characteristic length (512)
public boolean isNotifying(@NotNull @NotNull android.bluetooth.BluetoothGattCharacteristic characteristic)
characteristic
- the characteristic to check@NotNull public @NotNull java.util.Set<android.bluetooth.BluetoothGattCharacteristic> getNotifyingCharacteristics()
public boolean readCharacteristic(@NotNull @NotNull java.util.UUID serviceUUID, @NotNull @NotNull java.util.UUID characteristicUUID)
The characteristic must support reading it, otherwise the operation will not be enqueued.
serviceUUID
- the service UUID the characteristic belongs tocharacteristicUUID
- the characteristic's UUIDpublic boolean readCharacteristic(@NotNull @NotNull android.bluetooth.BluetoothGattCharacteristic characteristic)
The characteristic must support reading it, otherwise the operation will not be enqueued.
BluetoothPeripheralCallback.onCharacteristicUpdate(BluetoothPeripheral, byte[], BluetoothGattCharacteristic, GattStatus)
will be triggered as a result of this call.
characteristic
- Specifies the characteristic to read.public boolean writeCharacteristic(@NotNull @NotNull java.util.UUID serviceUUID, @NotNull @NotNull java.util.UUID characteristicUUID, @NotNull @NotNull byte[] value, @NotNull @NotNull WriteType writeType)
All parameters must have a valid value in order for the operation to be enqueued. If the characteristic does not support writing with the specified writeType, the operation will not be enqueued.
serviceUUID
- the service UUID the characteristic belongs tocharacteristicUUID
- the characteristic's UUIDvalue
- the byte array to writewriteType
- the write type to use when writing. Must be WRITE_TYPE_DEFAULT, WRITE_TYPE_NO_RESPONSE or WRITE_TYPE_SIGNEDpublic boolean writeCharacteristic(@NotNull @NotNull android.bluetooth.BluetoothGattCharacteristic characteristic, @NotNull @NotNull byte[] value, @NotNull @NotNull WriteType writeType)
All parameters must have a valid value in order for the operation to be enqueued. If the characteristic does not support writing with the specified writeType, the operation will not be enqueued. The length of the byte array to write must be between 1 and getMaximumWriteValueLength(writeType).
BluetoothPeripheralCallback.onCharacteristicWrite(BluetoothPeripheral, byte[], BluetoothGattCharacteristic, GattStatus)
will be triggered as a result of this call.
characteristic
- the characteristic to write tovalue
- the byte array to writewriteType
- the write type to use when writing.public boolean readDescriptor(@NotNull @NotNull android.bluetooth.BluetoothGattDescriptor descriptor)
descriptor
- the descriptor to readpublic boolean writeDescriptor(@NotNull @NotNull android.bluetooth.BluetoothGattDescriptor descriptor, @NotNull @NotNull byte[] value)
For turning on/off notifications use setNotify(BluetoothGattCharacteristic, boolean)
instead.
descriptor
- the descriptor to write tovalue
- the value to writepublic boolean setNotify(@NotNull @NotNull java.util.UUID serviceUUID, @NotNull @NotNull java.util.UUID characteristicUUID, boolean enable)
serviceUUID
- the service UUID the characteristic belongs tocharacteristicUUID
- the characteristic's UUIDenable
- true for setting notification on, false for turning it offpublic boolean setNotify(@NotNull @NotNull android.bluetooth.BluetoothGattCharacteristic characteristic, boolean enable)
BluetoothPeripheralCallback.onNotificationStateUpdate(BluetoothPeripheral, BluetoothGattCharacteristic, GattStatus)
will be triggered as a result of this call.
characteristic
- the characteristic to turn notification on/off forenable
- true for setting notification on, false for turning it offpublic boolean readRemoteRssi()
BluetoothPeripheralCallback.onReadRemoteRssi(BluetoothPeripheral, int, GattStatus)
will be triggered as a result of this call.
public boolean requestMtu(int mtu)
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.
BluetoothPeripheralCallback.onMtuChanged(BluetoothPeripheral, int, GattStatus)
will be triggered as a result of this call.
mtu
- the desired MTU sizepublic boolean requestConnectionPriority(@NotNull @NotNull ConnectionPriority priority)
priority
- the requested connection prioritypublic boolean setPreferredPhy(@NotNull @NotNull PhyType txPhy, @NotNull @NotNull PhyType rxPhy, @NotNull @NotNull PhyOptions phyOptions)
BluetoothPeripheralCallback.onPhyUpdate(com.welie.blessed.BluetoothPeripheral, com.welie.blessed.PhyType, com.welie.blessed.PhyType, com.welie.blessed.GattStatus)
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.
txPhy
- the desired TX PHYrxPhy
- the desired RX PHYphyOptions
- the desired optional sub-type for PHY_LE_CODEDpublic boolean readPhy()
BluetoothPeripheralCallback.onPhyUpdate(com.welie.blessed.BluetoothPeripheral, com.welie.blessed.PhyType, com.welie.blessed.PhyType, com.welie.blessed.GattStatus)
public boolean clearServicesCache()