Provides access to Bluetooth adapters. More...

Inheritance diagram for org.direct_bt.BTDevice:

Collaboration diagram for org.direct_bt.BTDevice:

Public Member Functions
BTGattService	find (String UUID, long timeoutMS)
	Find a BluetoothGattService. More...

BTGattService	find (String UUID)
	Find a BluetoothGattService. More...

boolean	addStatusListener (final AdapterStatusListener listener)
	Add the given AdapterStatusListener to the list if not already present, listening only for events matching this device. More...

boolean	removeStatusListener (final AdapterStatusListener l)
	Remove the given AdapterStatusListener from the list. More...

HCIStatusCode	disconnect () throws BTException

HCIStatusCode	connect () throws BTException

HCIStatusCode	connectLE (final short le_scan_interval, final short le_scan_window, final short conn_interval_min, final short conn_interval_max, final short conn_latency, final short supervision_timeout)
	Establish a HCI BDADDR_LE_PUBLIC or BDADDR_LE_RANDOM connection to this device. More...

SMPKeyMask	getAvailableSMPKeys (final boolean responder)
	Returns the available SMPKeyMask.KeyType SMPKeyMask for the responder (LL slave) or initiator (LL master). More...

SMPLongTermKeyInfo	getLongTermKeyInfo (final boolean responder)
	Returns a copy of the long term key (LTK) info, valid after connection and SMP pairing has been completed. More...

HCIStatusCode	setLongTermKeyInfo (final SMPLongTermKeyInfo ltk)
	Sets the long term ket (LTK) info of this device to reuse pre-paired encryption. More...

SMPSignatureResolvingKeyInfo	getSignatureResolvingKeyInfo (final boolean responder)
	Returns a copy of the Signature Resolving Key (LTK) info, valid after connection and SMP pairing has been completed. More...

HCIStatusCode	unpair ()
	Unpairs this device from the adapter while staying connected. More...

boolean	setConnSecurityLevel (final BTSecurityLevel sec_level)
	Set the BTSecurityLevel used to connect to this device on the upcoming connection. More...

BTSecurityLevel	getConnSecurityLevel ()
	Return the BTSecurityLevel, determined when the connection is established. More...

boolean	setConnIOCapability (final SMPIOCapability io_cap)
	Sets the given SMPIOCapability used to connect to this device on the upcoming connection. More...

SMPIOCapability	getConnIOCapability ()
	Return the SMPIOCapability value, determined when the connection is established. More...

boolean	setConnSecurity (final BTSecurityLevel sec_level, final SMPIOCapability io_cap)
	Sets the given BTSecurityLevel and SMPIOCapability used to connect to this device on the upcoming connection. More...

boolean	setConnSecurityBest (final BTSecurityLevel sec_level, final SMPIOCapability io_cap)
	Convenience method to determine the best practice BTSecurityLevel and SMPIOCapability based on the given arguments, used to connect to this device on the upcoming connection. More...

boolean	setConnSecurityAuto (final SMPIOCapability iocap_auto)
	Set automatic security negotiation of BTSecurityLevel and SMPIOCapability pairing mode. More...

boolean	isConnSecurityAutoEnabled ()
	Returns true if automatic security negotiation has been enabled via setConnSecurityAuto(SMPIOCapability), otherwise false. More...

HCIStatusCode	setPairingPasskey (final int passkey)
	Method sets the given passkey entry, see PairingMode#PASSKEY_ENTRY_ini. More...

HCIStatusCode	setPairingPasskeyNegative ()
	Method replies with a negative passkey response, i.e. More...

HCIStatusCode	setPairingNumericComparison (final boolean equal)
	Method sets the numeric comparison result, see PairingMode#NUMERIC_COMPARE_ini. More...

PairingMode	getPairingMode ()
	Returns the current PairingMode used by the device. More...

SMPPairingState	getPairingState ()
	Returns the current SMPPairingState. More...

boolean	remove () throws BTException
	Remove this device from the system (like an unpair). More...

boolean	isValid ()
	Returns whether the device is valid, i.e. More...

List< BTGattService >	getServices ()
	Returns a list of BluetoothGattServices available on this device. More...

boolean	pingGATT ()
	Issues a GATT ping to the device, validating whether it is still reachable. More...

long	getCreationTimestamp ()
	Returns the timestamp in monotonic milliseconds when this device instance has been created, either via its initial discovery or its initial direct connection. More...

long	getLastDiscoveryTimestamp ()
	Returns the timestamp in monotonic milliseconds when this device instance has discovered or connected directly the last time. More...

long	getLastUpdateTimestamp ()
	Returns the timestamp in monotonic milliseconds when this device instance underlying data has been updated the last time. More...

BDAddressAndType	getAddressAndType ()
	Returns the unique device EUI48 address and BDAddressType type. More...

String	getName ()
	Returns the remote friendly name of this device. More...

short	getRSSI ()
	Returns the Received Signal Strength Indicator of the device. More...

boolean	getConnected ()
	Returns the connected state of the device. More...

short	getConnectionHandle ()
	Return the HCI connection handle to the LE or BREDR peer, zero if not connected. More...

BTAdapter	getAdapter ()
	Returns the adapter on which this device was discovered or connected. More...

Map< Short, byte[]>	getManufacturerData ()
	Returns a map containing manufacturer specific advertisement data. More...

short	getTxPower ()
	Returns the transmission power level (0 means unknown). More...

boolean	addCharListener (final BTGattCharListener listener) throws IllegalStateException
	Add the given BTGattCharListener to the listener list if not already present. More...

boolean	removeCharListener (final BTGattCharListener l)
	Remove the given BTGattCharListener from the listener list. More...

int	removeAllAssociatedCharListener (final BTGattChar associatedCharacteristic)
	Remove all BTGattCharListener from the list, which are associated to the given BTGattChar. More...

int	removeAllCharListener ()
	Remove all BTGattCharListener from the list. More...

Public Member Functions inherited from org.direct_bt.BTObject
BTType	getBluetoothType ()
	Returns the BluetoothType of this object. More...

boolean	equals (Object obj)

int	hashCode ()

void	close ()
	Release the native memory associated with this object The object should not be used following a call to close. More...

Detailed Description

Provides access to Bluetooth adapters.

See also: Bluetooth Specification; BlueZ device API

Definition at line 41 of file BTDevice.java.

Member Function Documentation

◆ addCharListener()

boolean org.direct_bt.BTDevice.addCharListener ( final BTGattCharListener listener ) throws IllegalStateException

Add the given BTGattCharListener to the listener list if not already present.

To enable the actual BLE notification and/or indication, one needs to call BTGattChar#configNotificationIndication(boolean, boolean, boolean[]) or BTGattChar#enableNotificationOrIndication(boolean[]).

Parameters

listener A BTGattCharListener instance, listening to all BTGattChar events of this device

Returns: true if the given listener is not element of the list and has been newly added, otherwise false.

Exceptions

IllegalStateException	if the BTDevice's BTGattHandler is null, i.e. not connected
IllegalStateException	if the given BTGattCharListener is already in use, i.e. added.

See also: BTGattChar::configNotificationIndication(boolean, boolean, boolean[]); BTGattChar::enableNotificationOrIndication(boolean[])

Since: 2.0.0

Implemented in jau.direct_bt.DBTDevice.

Here is the caller graph for this function:

◆ addStatusListener()

boolean org.direct_bt.BTDevice.addStatusListener ( final AdapterStatusListener listener )

Add the given AdapterStatusListener to the list if not already present, listening only for events matching this device.

The AdapterStatusListener is released at remove() or this device's destruction.

The newly added AdapterStatusListener will receive an initial adapterSettingsChanged event, passing an empty oldMask and changedMask, as well as current newMask.
This allows the receiver to be aware of this adapter's current settings.

Parameters

listener	A AdapterStatusListener instance
deviceMatch	Optional BTDevice to be matched before calling any AdapterStatusListener device* methods. Pass null for no filtering.

Returns: true if the given listener is not element of the list and has been newly added, otherwise false.

Since: 2.3.0

See also: BTDevice#addStatusListener(AdapterStatusListener, BTDevice); removeStatusListener(AdapterStatusListener); removeAllStatusListener()

Implemented in jau.direct_bt.DBTDevice.

◆ connect()

HCIStatusCode org.direct_bt.BTDevice.connect ( ) throws BTException

jau.direct_bt

: Establish a default HCI connection to this device, using certain default parameter.

BT Core Spec v5.2: Vol 4, Part E HCI: 7.8.12 LE Create Connection command
BT Core Spec v5.2: Vol 4, Part E HCI: 7.1.5 Create Connection command

Depending on this device's addressType, either a BREDR (BDADDR_BREDR) or LE (BDADDR_LE_PUBLIC, BDADDR_LE_RANDOM) connection is attempted.
If unacceptable, HCIStatusCode#UNACCEPTABLE_CONNECTION_PARAM is being returned.

The actual new connection handle will be delivered asynchronous and the connection event can be caught via AdapterStatusListener#deviceConnected(BTDevice, long), or if failed via AdapterStatusListener#deviceDisconnected(BTDevice, HCIStatusCode, long).

The device is tracked by the managing adapter.

flagged as auto-connectable.

Returns: HCIStatusCode#SUCCESS if the command has been accepted, otherwise HCIStatusCode may disclose reason for rejection.

See also: connectLE(short, short, short, short, short, short)

Since: 2.1.0 change API, i.e. return value from boolean to HCIStatusCode in favor of
jau.direct_bt

. @implNote
jau.direct_bt

does not throw a BTException on error, only a 'general' exception in case of fatality like NPE etc (FIXME: Remove throws)

Implemented in jau.direct_bt.DBTDevice.

◆ connectLE()

HCIStatusCode org.direct_bt.BTDevice.connectLE	(	final short	le_scan_interval,
		final short	le_scan_window,
		final short	conn_interval_min,
		final short	conn_interval_max,
		final short	conn_latency,
		final short	supervision_timeout
	)

Establish a HCI BDADDR_LE_PUBLIC or BDADDR_LE_RANDOM connection to this device.

BT Core Spec v5.2: Vol 4, Part E HCI: 7.8.12 LE Create Connection command

If this device's getAddressType() is not BDADDR_LE_PUBLIC or BDADDR_LE_RANDOM, HCIStatusCode#UNACCEPTABLE_CONNECTION_PARAM is being returned.

The actual new connection handle will be delivered asynchronous and the connection event can be caught via AdapterStatusListener#deviceConnected(BTDevice, long), or if failed via AdapterStatusListener#deviceDisconnected(BTDevice, HCIStatusCode, long).

The device is tracked by the managing adapter.

Default parameter are used if

-1

has been passed for any of the arguments.

Default parameter values are chosen for using public address resolution and usual connection latency, interval etc.

Set window to the same value as the interval, enables continuous scanning.

Parameters

le_scan_interval	in units of 0.625ms, default value 24 for 15ms; Value range [4 .. 0x4000] for [2.5ms .. 10.24s]
le_scan_window	in units of 0.625ms, default value 24 for 15ms; Value range [4 .. 0x4000] for [2.5ms .. 10.24s]. Shall be <= le_scan_interval
conn_interval_min	in units of 1.25ms, default value 12 for 15ms; Value range [6 .. 3200] for [7.5ms .. 4000ms]
conn_interval_max	in units of 1.25ms, default value 12 for 15ms; Value range [6 .. 3200] for [7.5ms .. 4000ms]
conn_latency	slave latency in units of connection events, default value 0; Value range [0 .. 0x01F3].
supervision_timeout	in units of 10ms, default value >= 10 x conn_interval_max, we use 500 ms minimum; Value range [0xA-0x0C80] for [100ms - 32s].

Returns: HCIStatusCode#SUCCESS if the command has been accepted, otherwise HCIStatusCode may disclose reason for rejection.

See also: BTUtils::getHCIConnSupervisorTimeout(int, int, int, int); connect()

Implemented in jau.direct_bt.DBTDevice.

◆ disconnect()

HCIStatusCode org.direct_bt.BTDevice.disconnect ( ) throws BTException

jau.direct_bt

: Disconnect the LE or BREDR peer's GATT and HCI connection.

BT Core Spec v5.2: Vol 4, Part E HCI: 7.1.6 Disconnect command

The actual disconnect event will be delivered asynchronous and the connection event can be caught via AdapterStatusListener::deviceDisconnected(..). If unacceptable, HCIStatusCode#UNACCEPTABLE_CONNECTION_PARAM is being returned.

The device will be removed from the managing adapter's connected devices when AdapterStatusListener#deviceDisconnected(BTDevice, HCIStatusCode, long) has been received.

An open GATT connection will also be closed.
The connection to this device is removed, removing all connected profiles.

An application using one thread per device and rapid connect, should either use disconnect() or remove(), but never issue remove() after disconnect(). Doing so would eventually delete the device being already in use by another thread due to discovery post disconnect!

Returns: HCIStatusCode#SUCCESS if the command has been accepted, otherwise HCIStatusCode may disclose reason for rejection.

Since: 2.1.0 change API, i.e. return value from boolean to HCIStatusCode in favor of direct_bt @implNote
jau.direct_bt

does not throw a BTException on error, only a 'general' exception in case of fatality like NPE etc (FIXME: Remove throws)

Implemented in jau.direct_bt.DBTDevice.

◆ find() [1/2]

BTGattService org.direct_bt.BTDevice.find ( String UUID )

Find a BluetoothGattService.

If parameter UUID is not null, the returned object will have to match it. It will first check for existing objects. It will not turn on discovery or connect to devices. @parameter UUID optionally specify the UUID of the BluetoothGattService you are waiting for

Returns: An object matching the UUID or null if not found before timeout expires or event is canceled.

Implemented in jau.direct_bt.DBTDevice.

◆ find() [2/2]

BTGattService org.direct_bt.BTDevice.find	(	String	UUID,
		long	timeoutMS
	)

Find a BluetoothGattService.

If parameter UUID is not null, the returned object will have to match it. It will first check for existing objects. It will not turn on discovery or connect to devices. @parameter UUID optionally specify the UUID of the BluetoothGattService you are waiting for @parameter timeoutMS the function will return after timeout time in milliseconds, a value of zero means wait forever. If object is not found during this time null will be returned.

Returns: An object matching the UUID or null if not found before timeout expires or event is canceled.

Implemented in jau.direct_bt.DBTDevice.

◆ getAdapter()

BTAdapter org.direct_bt.BTDevice.getAdapter ( )

Returns the adapter on which this device was discovered or connected.

Returns: The adapter.

Implemented in jau.direct_bt.DBTDevice.

◆ getAddressAndType()

BDAddressAndType org.direct_bt.BTDevice.getAddressAndType ( )

Returns the unique device EUI48 address and BDAddressType type.

Since: 2.2.0

Implemented in jau.direct_bt.DBTDevice.

Here is the caller graph for this function:

◆ getAvailableSMPKeys()

SMPKeyMask org.direct_bt.BTDevice.getAvailableSMPKeys ( final boolean responder )

Returns the available SMPKeyMask.KeyType SMPKeyMask for the responder (LL slave) or initiator (LL master).

Parameters

responder if true, queries the responder (LL slave) key, otherwise the initiator (LL master) key.

Returns: SMPKeyMask.KeyType SMPKeyMask result

Since: 2.2.0

Implemented in jau.direct_bt.DBTDevice.

Here is the caller graph for this function:

◆ getConnected()

boolean org.direct_bt.BTDevice.getConnected ( )

Returns the connected state of the device.

Returns: The connected state of the device.

Implemented in jau.direct_bt.DBTDevice.

◆ getConnectionHandle()

short org.direct_bt.BTDevice.getConnectionHandle ( )

Return the HCI connection handle to the LE or BREDR peer, zero if not connected.

Since: 2.1.0

Implemented in jau.direct_bt.DBTDevice.

◆ getConnIOCapability()

SMPIOCapability org.direct_bt.BTDevice.getConnIOCapability ( )

Return the SMPIOCapability value, determined when the connection is established.

Since: 2.1.0

See also: BTSecurityLevel; SMPIOCapability; setConnSecurityLevel(BTSecurityLevel); getConnSecurityLevel(); setConnIOCapability(SMPIOCapability); setConnSecurity(BTSecurityLevel, SMPIOCapability); setConnSecurityBest(BTSecurityLevel, SMPIOCapability)

Implemented in jau.direct_bt.DBTDevice.

Here is the caller graph for this function:

◆ getConnSecurityLevel()

BTSecurityLevel org.direct_bt.BTDevice.getConnSecurityLevel ( )

Return the BTSecurityLevel, determined when the connection is established.

Since: 2.1.0

See also: BTSecurityLevel; SMPIOCapability; setConnSecurityLevel(BTSecurityLevel); #setConnIOCapability(SMPIOCapability, boolean); getConnIOCapability(); #setConnSecurity(BTSecurityLevel, SMPIOCapability, boolean); setConnSecurityBest(BTSecurityLevel, SMPIOCapability)

Implemented in jau.direct_bt.DBTDevice.

Here is the caller graph for this function:

◆ getCreationTimestamp()

long org.direct_bt.BTDevice.getCreationTimestamp ( )

Returns the timestamp in monotonic milliseconds when this device instance has been created, either via its initial discovery or its initial direct connection.

See also: BTUtils::currentTimeMillis()

Since: 2.0.0

Implemented in jau.direct_bt.DBTDevice.

◆ getLastDiscoveryTimestamp()

long org.direct_bt.BTDevice.getLastDiscoveryTimestamp ( )

Returns the timestamp in monotonic milliseconds when this device instance has discovered or connected directly the last time.

See also: BTUtils::currentTimeMillis()

Since: 2.0.0

Implemented in jau.direct_bt.DBTDevice.

◆ getLastUpdateTimestamp()

long org.direct_bt.BTDevice.getLastUpdateTimestamp ( )

Returns the timestamp in monotonic milliseconds when this device instance underlying data has been updated the last time.

See also: BTUtils::currentTimeMillis()

Since: 2.0.0

Implemented in jau.direct_bt.DBTDevice.

◆ getLongTermKeyInfo()

SMPLongTermKeyInfo org.direct_bt.BTDevice.getLongTermKeyInfo ( final boolean responder )

Returns a copy of the long term key (LTK) info, valid after connection and SMP pairing has been completed.

Parameters

responder true will return the responder's LTK info (remote device, LL slave), otherwise the initiator's (the LL master).

Returns: the resulting key. SMPLongTermKeyInfo#enc_size will be zero if invalid.

See also: SMPPairingState#COMPLETED; AdapterStatusListener#deviceReady(BTDevice, long)

Since: 2.2.0

Implemented in jau.direct_bt.DBTDevice.

Here is the caller graph for this function:

◆ getManufacturerData()

Map<Short, byte[]> org.direct_bt.BTDevice.getManufacturerData ( )

Returns a map containing manufacturer specific advertisement data.

An entry has a uint16_t key and an array of bytes.

Returns: manufacturer specific advertisement data.

Implemented in jau.direct_bt.DBTDevice.

◆ getName()

String org.direct_bt.BTDevice.getName ( )

Returns the remote friendly name of this device.

Returns: The remote friendly name of this device, or NULL if not set.

Implemented in jau.direct_bt.DBTDevice.

Here is the caller graph for this function:

◆ getPairingMode()

PairingMode org.direct_bt.BTDevice.getPairingMode ( )

Returns the current PairingMode used by the device.

If the device is not paired, the current mode is PairingMode#NONE.

If the Pairing Feature Exchange is completed, i.e. SMPPairingState#FEATURE_EXCHANGE_COMPLETED as notified by devicePairingState the current mode reflects the currently used PairingMode.

In case the Pairing Feature Exchange is in progress, the current mode is PairingMode#NEGOTIATING.

Returns: current PairingMode.

See also: PairingMode; SMPPairingState; AdapterStatusListener::devicePairingState(BTDevice, SMPPairingState, PairingMode, long); setPairingPasskey(int); setPairingNumericComparison(boolean); getPairingMode(); getPairingState()

Since: 2.1.0

Implemented in jau.direct_bt.DBTDevice.

Here is the caller graph for this function:

◆ getPairingState()

SMPPairingState org.direct_bt.BTDevice.getPairingState ( )

Returns the current SMPPairingState.

If the device is not paired, the current state is SMPPairingState#NONE.

See also: PairingMode; SMPPairingState; AdapterStatusListener::devicePairingState(BTDevice, SMPPairingState, PairingMode, long); setPairingPasskey(int); setPairingNumericComparison(boolean); getPairingMode(); getPairingState()

Since: 2.1.0

Implemented in jau.direct_bt.DBTDevice.

Here is the caller graph for this function:

◆ getRSSI()

short org.direct_bt.BTDevice.getRSSI ( )

Returns the Received Signal Strength Indicator of the device.

Returns: The Received Signal Strength Indicator of the device.

Implemented in jau.direct_bt.DBTDevice.

◆ getServices()

List<BTGattService> org.direct_bt.BTDevice.getServices ( )

Returns a list of BluetoothGattServices available on this device.

Returns: A list of BluetoothGattServices available on this device, NULL if an error occurred

Implemented in jau.direct_bt.DBTDevice.

Here is the caller graph for this function:

◆ getSignatureResolvingKeyInfo()

SMPSignatureResolvingKeyInfo org.direct_bt.BTDevice.getSignatureResolvingKeyInfo ( final boolean responder )

Returns a copy of the Signature Resolving Key (LTK) info, valid after connection and SMP pairing has been completed.

Parameters

responder true will return the responder's LTK info (remote device, LL slave), otherwise the initiator's (the LL master).

Returns: the resulting key

See also: SMPPairingState#COMPLETED; AdapterStatusListener#deviceReady(BTDevice, long)

Since: 2.2.0

Implemented in jau.direct_bt.DBTDevice.

Here is the caller graph for this function:

◆ getTxPower()

short org.direct_bt.BTDevice.getTxPower ( )

Returns the transmission power level (0 means unknown).

Returns: the transmission power level (0 means unknown).

Implemented in jau.direct_bt.DBTDevice.

◆ isConnSecurityAutoEnabled()

boolean org.direct_bt.BTDevice.isConnSecurityAutoEnabled ( )

Returns true if automatic security negotiation has been enabled via setConnSecurityAuto(SMPIOCapability), otherwise false.

Since: 2.2.0

See also: setConnSecurityAuto(SMPIOCapability)

Implemented in jau.direct_bt.DBTDevice.

◆ isValid()

boolean org.direct_bt.BTDevice.isValid ( )

Returns whether the device is valid, i.e.

reference is valid but not necessarily connected.

Returns: true if this device's references are valid and hasn't been remove()'ed

See also: remove()

Since: 2.2.0

Implemented in jau.direct_bt.DBTDevice.

Here is the caller graph for this function:

◆ pingGATT()

boolean org.direct_bt.BTDevice.pingGATT ( )

Issues a GATT ping to the device, validating whether it is still reachable.

This method could be periodically utilized to shorten the underlying OS disconnect period after turning the device off, which lies within 7-13s.

In case the device is no more reachable, disconnect will be initiated due to the occurring IO error.

GATT services must have been initialized via getServices(), otherwise

false

is being returned.

Returns: true

if successful or not implemented, otherwise false in case no GATT services exists or is not connected..

Since: 2.0.0

Implemented in jau.direct_bt.DBTDevice.

◆ remove()

boolean org.direct_bt.BTDevice.remove ( ) throws BTException

Remove this device from the system (like an unpair).

Direct-BT: Disconnects this device via disconnect(..) if getConnected()==true and explicitly removes its shared references from the Adapter: connected-devices, discovered-devices and shared-devices.

This method shall be issued to ensure no device reference will be leaked in a long lived adapter, as only its reference within connected-devices and discovered-devices are removed at disconnect.

After calling this method, this instance is destroyed and shall not be used anymore!

This method is automatically called @ destructor.

This method is an atomic operation.

An application using one thread per device and rapid connect, should either use disconnect() or remove(), but never issue remove() after disconnect() if the device is in use.

Returns: TRUE if the device has been removed

Exceptions

BTException

Implemented in jau.direct_bt.DBTDevice.

Here is the caller graph for this function:

◆ removeAllAssociatedCharListener()

int org.direct_bt.BTDevice.removeAllAssociatedCharListener ( final BTGattChar associatedCharacteristic )

Remove all BTGattCharListener from the list, which are associated to the given BTGattChar.

Implementation tests all listener's BTGattCharListener#getAssociatedChar() to match with the given associated characteristic.

Parameters

associatedCharacteristic the match criteria to remove any BTGattCharListener from the list

Returns: number of removed listener.

Since: 2.0.0

Implemented in jau.direct_bt.DBTDevice.

Here is the caller graph for this function:

◆ removeAllCharListener()

int org.direct_bt.BTDevice.removeAllCharListener ( )

Remove all BTGattCharListener from the list.

Returns: number of removed listener.

Since: 2.0.0

Implemented in jau.direct_bt.DBTDevice.

Here is the caller graph for this function:

◆ removeCharListener()

boolean org.direct_bt.BTDevice.removeCharListener ( final BTGattCharListener l )

Remove the given BTGattCharListener from the listener list.

If the BTDevice's BTGattHandler is null, i.e. not connected,

false

is being returned.

Parameters

listener A BTGattCharListener instance

Returns: true if the given listener is an element of the list and has been removed, otherwise false.

Since: 2.0.0

Implemented in jau.direct_bt.DBTDevice.

Here is the caller graph for this function:

◆ removeStatusListener()

boolean org.direct_bt.BTDevice.removeStatusListener ( final AdapterStatusListener l )

Remove the given AdapterStatusListener from the list.

Parameters

listener A AdapterStatusListener instance

Returns: true if the given listener is an element of the list and has been removed, otherwise false.

Since: 2.3.0

Implemented in jau.direct_bt.DBTDevice.

◆ setConnIOCapability()

boolean org.direct_bt.BTDevice.setConnIOCapability ( final SMPIOCapability io_cap )

Sets the given SMPIOCapability used to connect to this device on the upcoming connection.

Method returns false if SMPIOCapability#UNSET has been given, operation fails, this device has already being connected, or connectLE or connect() has been issued already.

Parameters

io_cap SMPIOCapability to be applied, SMPIOCapability#UNSET will be ignored and method fails.

Since: 2.1.0

See also: BTSecurityLevel; SMPIOCapability; setConnSecurityLevel(BTSecurityLevel); getConnSecurityLevel(); getConnIOCapability(); setConnSecurity(BTSecurityLevel, SMPIOCapability); setConnSecurityBest(BTSecurityLevel, SMPIOCapability)

Implemented in jau.direct_bt.DBTDevice.

◆ setConnSecurity()

boolean org.direct_bt.BTDevice.setConnSecurity	(	final BTSecurityLevel	sec_level,
		final SMPIOCapability	io_cap
	)

Sets the given BTSecurityLevel and SMPIOCapability used to connect to this device on the upcoming connection.

Method returns false if this device has already being connected, or connectLE or connect() has been issued already.

Method either changes both parameter for the upcoming connection or none at all.

Parameters

sec_level	BTSecurityLevel to be applied.
io_cap	SMPIOCapability to be applied.

Since: 2.1.0

See also: BTSecurityLevel; SMPIOCapability; setConnSecurityLevel(BTSecurityLevel); getConnSecurityLevel(); setConnIOCapability(SMPIOCapability); getConnIOCapability(); setConnSecurityBest(BTSecurityLevel, SMPIOCapability)

Implemented in jau.direct_bt.DBTDevice.

Here is the caller graph for this function:

◆ setConnSecurityAuto()

boolean org.direct_bt.BTDevice.setConnSecurityAuto ( final SMPIOCapability iocap_auto )

Set automatic security negotiation of BTSecurityLevel and SMPIOCapability pairing mode.

Disabled by default and if set to SMPIOCapability#UNSET

Implementation iterates through below setup from highest security to lowest, while performing a full connection attempt for each.

BTSecurityLevel::ENC_AUTH_FIPS, iocap_auto*
BTSecurityLevel::ENC_AUTH,      iocap_auto*
BTSecurityLevel::ENC_ONLY,      SMPIOCapability::NO_INPUT_NO_OUTPUT
BTSecurityLevel::NONE,          SMPIOCapability::NO_INPUT_NO_OUTPUT

(*): user SMPIOCapability choice of for authentication IO, skipped if ::SMPIOCapability::NO_INPUT_NO_OUTPUT

<p<blockquote>

Implementation may perform multiple connection and disconnect actions until successful pairing or failure.

Intermediate deviceConnected(..) and deviceDisconnected(..) callbacks are not delivered while negotiating. This avoids any interference by the user application.

Parameters

auth_io_cap user SMPIOCapability choice for negotiation

Since: 2.2.0

See also: isConnSecurityAutoEnabled(); BTSecurityLevel; SMPIOCapability

Implemented in jau.direct_bt.DBTDevice.

◆ setConnSecurityBest()

boolean org.direct_bt.BTDevice.setConnSecurityBest	(	final BTSecurityLevel	sec_level,
		final SMPIOCapability	io_cap
	)

Convenience method to determine the best practice BTSecurityLevel and SMPIOCapability based on the given arguments, used to connect to this device on the upcoming connection.

  if( BTSecurityLevel::UNSET < sec_level && SMPIOCapability::UNSET != io_cap ) {
     return setConnSecurity(sec_level, io_cap);
  } else if( BTSecurityLevel::UNSET < sec_level ) {
      if( BTSecurityLevel::ENC_ONLY >= sec_level ) {
          return setConnSecurity(sec_level, SMPIOCapability::NO_INPUT_NO_OUTPUT);
      } else {
          return setConnSecurityLevel(sec_level);
      }
  } else if( SMPIOCapability::UNSET != io_cap ) {
      return setConnIOCapability(io_cap);
  } else {
      return false;
  }

<p<blockquote>

Method returns false if BTSecurityLevel#UNSET and SMPIOCapability#UNSET has been given, operation fails, this device has already being connected, or connectLE or connect() has been issued already.

Parameters

sec_level	BTSecurityLevel to be applied.
io_cap	SMPIOCapability to be applied.

Since: 2.1.0

See also: BTSecurityLevel; SMPIOCapability; setConnSecurityLevel(BTSecurityLevel); getConnSecurityLevel(); setConnIOCapability(SMPIOCapability); getConnIOCapability(); setConnSecurity(BTSecurityLevel, SMPIOCapability); setConnSecurityAuto(SMPIOCapability)

Implemented in jau.direct_bt.DBTDevice.

◆ setConnSecurityLevel()

boolean org.direct_bt.BTDevice.setConnSecurityLevel ( final BTSecurityLevel sec_level )

Set the BTSecurityLevel used to connect to this device on the upcoming connection.

Method returns false if BTSecurityLevel#UNSET has been given, operation fails, this device has already being connected, or connectLE or connect() has been issued already.

To ensure a consistent authentication setup, it is advised to set SMPIOCapability#NO_INPUT_NO_OUTPUT for sec_level <= BTSecurityLevel#ENC_ONLY using setConnSecurity(..) as well as an IO capable SMPIOCapability value for BTSecurityLevel#ENC_AUTH or BTSecurityLevel#ENC_AUTH_FIPS.
You may like to consider using setConnSecurityBest(BTSecurityLevel, SMPIOCapability).

Parameters

sec_level BTSecurityLevel to be applied, BTSecurityLevel#UNSET will be ignored and method fails.

Returns

Since: 2.1.0

See also: BTSecurityLevel; SMPIOCapability; getConnSecurityLevel(); setConnIOCapability(SMPIOCapability); getConnIOCapability(); setConnSecurity(BTSecurityLevel, SMPIOCapability); setConnSecurityBest(BTSecurityLevel, SMPIOCapability)

Implemented in jau.direct_bt.DBTDevice.

◆ setLongTermKeyInfo()

HCIStatusCode org.direct_bt.BTDevice.setLongTermKeyInfo ( final SMPLongTermKeyInfo ltk )

Sets the long term ket (LTK) info of this device to reuse pre-paired encryption.

Must be called before connecting to this device, otherwise HCIStatusCode#CONNECTION_ALREADY_EXISTS will be returned.

Parameters

ltk	the pre-paired encryption LTK

Returns: HCIStatusCode#SUCCESS if successful, otherwise the appropriate error code.

Since: 2.2.0

Implemented in jau.direct_bt.DBTDevice.

Here is the caller graph for this function:

◆ setPairingNumericComparison()

HCIStatusCode org.direct_bt.BTDevice.setPairingNumericComparison ( final boolean equal )

Method sets the numeric comparison result, see PairingMode#NUMERIC_COMPARE_ini.

Call this method if the device shall be securely paired with PairingMode#NUMERIC_COMPARE_ini, i.e. when notified via devicePairingState in state SMPPairingState#NUMERIC_COMPARE_EXPECTED.

Parameters

equal used for PairingMode#NUMERIC_COMPARE_ini method. Will be encrypted before sending to counter-party.

Returns: HCIStatusCode#SUCCESS if the command has been accepted, otherwise HCIStatusCode may disclose reason for rejection.

See also: PairingMode; SMPPairingState; AdapterStatusListener::devicePairingState(BTDevice, SMPPairingState, PairingMode, long); setPairingPasskey(int); setPairingNumericComparison(boolean); getPairingMode(); getPairingState()

Since: 2.1.0

Implemented in jau.direct_bt.DBTDevice.

◆ setPairingPasskey()

HCIStatusCode org.direct_bt.BTDevice.setPairingPasskey ( final int passkey )

Method sets the given passkey entry, see PairingMode#PASSKEY_ENTRY_ini.

Call this method if the device shall be securely paired with PairingMode#PASSKEY_ENTRY_ini, i.e. when notified via devicePairingState in state SMPPairingState#PASSKEY_EXPECTED.

Parameters

passkey used for PairingMode#PASSKEY_ENTRY_ini method. Will be encrypted before sending to counter-party.

Returns: HCIStatusCode#SUCCESS if the command has been accepted, otherwise HCIStatusCode may disclose reason for rejection.

See also: PairingMode; SMPPairingState; AdapterStatusListener::devicePairingState(BTDevice, SMPPairingState, PairingMode, long); setPairingPasskey(int); setPairingNumericComparison(boolean); getPairingMode(); getPairingState()

Since: 2.1.0

Implemented in jau.direct_bt.DBTDevice.

◆ setPairingPasskeyNegative()

HCIStatusCode org.direct_bt.BTDevice.setPairingPasskeyNegative ( )

Method replies with a negative passkey response, i.e.

rejection, see PairingMode#PASSKEY_ENTRY_ini.

You may call this method if the device shall be securely paired with PairingMode#PASSKEY_ENTRY_ini, i.e. when notified via devicePairingState in state SMPPairingState#PASSKEY_EXPECTED.

Current experience exposed a roughly 3s immediate disconnect handshake with certain devices and/or Kernel BlueZ code.

Hence using setPairingPasskey(int) with

passkey = 0

is recommended, especially when utilizing automatic security negotiation via setConnSecurityAuto()!

Returns: HCIStatusCode#SUCCESS if the command has been accepted, otherwise HCIStatusCode may disclose reason for rejection.

See also: PairingMode; SMPPairingState; AdapterStatusListener::devicePairingState(BTDevice, SMPPairingState, PairingMode, long); setPairingPasskey(int); setPairingNumericComparison(boolean); getPairingMode(); getPairingState()

Since: 2.1.0

Implemented in jau.direct_bt.DBTDevice.

◆ unpair()

HCIStatusCode org.direct_bt.BTDevice.unpair ( )

Unpairs this device from the adapter while staying connected.

All keys will be cleared within the adapter and host implementation.
Should rarely being used by user.
Internally being used to re-start pairing if GATT connection fails in PairingMode#PRE_PAIRED mode.

Returns: HCIStatusCode#SUCCESS or an appropriate error status.

Since: 2.1.0

Implemented in jau.direct_bt.DBTDevice.

The documentation for this interface was generated from the following file:

/usr/local/projects/direct_bt/java/org/direct_bt/BTDevice.java

Public Member Functions

Detailed Description

Member Function Documentation

◆ addCharListener()

◆ addStatusListener()

◆ connect()

◆ connectLE()

◆ disconnect()

◆ find() [1/2]

◆ find() [2/2]

◆ getAdapter()

◆ getAddressAndType()

◆ getAvailableSMPKeys()

◆ getConnected()

◆ getConnectionHandle()

◆ getConnIOCapability()

◆ getConnSecurityLevel()

◆ getCreationTimestamp()

◆ getLastDiscoveryTimestamp()

◆ getLastUpdateTimestamp()

◆ getLongTermKeyInfo()

◆ getManufacturerData()

◆ getName()

◆ getPairingMode()

◆ getPairingState()

◆ getRSSI()

◆ getServices()

◆ getSignatureResolvingKeyInfo()

◆ getTxPower()

◆ isConnSecurityAutoEnabled()

◆ isValid()

◆ pingGATT()

◆ remove()

◆ removeAllAssociatedCharListener()

◆ removeAllCharListener()

◆ removeCharListener()

◆ removeStatusListener()

◆ setConnIOCapability()

◆ setConnSecurity()

◆ setConnSecurityAuto()

◆ setConnSecurityBest()

◆ setConnSecurityLevel()

◆ setLongTermKeyInfo()

◆ setPairingNumericComparison()

◆ setPairingPasskey()

◆ setPairingPasskeyNegative()

◆ unpair()