BTAdapter represents one local Bluetooth Controller. More...

Inheritance diagram for org.direct_bt.BTAdapter:

Collaboration diagram for org.direct_bt.BTAdapter:

Public Member Functions
boolean	addDeviceToWhitelist (final BDAddressAndType addressAndType, final HCIWhitelistConnectType ctype)
	Add the given device to the adapter's autoconnect whitelist. More...

boolean	addDeviceToWhitelist (final BDAddressAndType addressAndType, final HCIWhitelistConnectType ctype, final short conn_interval_min, final short conn_interval_max, final short conn_latency, final short timeout)
	Add the given device to the adapter's autoconnect whitelist. More...

boolean	addStatusListener (final AdapterStatusListener listener)
	Add the given `AdapterStatusListener` to the list if not already present. More...

BTDevice	connectDevice (BDAddressAndType addressAndType)
	This method connects to device without need of performing General Discovery. More...

boolean	equals (final Object obj)
	If both types are of `BTAdapter`, it compares their `BDAddressAndType`, see `getAddressAndType()`. More...

BTDevice	find (String name, BDAddressAndType addressAndType)
	Find a BluetoothDevice. More...

BTDevice	find (String name, BDAddressAndType addressAndType, long timeoutMS)
	Find a BluetoothDevice. More...

BDAddressAndType	getAddressAndType ()
	Returns the adapter's public BDAddressAndType. More...

int	getBTMajorVersion ()
	Returns the Bluetooth major version of this adapter. More...

BTMode	getBTMode ()
	Returns the current `BTMode` of this adapter. More...

DiscoveryPolicy	getCurrentDiscoveryPolicy ()
	Return the current `DiscoveryPolicy`, set via `startDiscovery(DiscoveryPolicy, boolean, short, short, byte, boolean)`. More...

ScanType	getCurrentScanType ()
	Returns the current meta discovering `ScanType`. More...

int	getDevID ()
	Returns the BluetoothAdapter's internal temporary device id. More...

List< BTDevice >	getDiscoveredDevices ()
	Returns a list of discovered BluetoothDevices from this adapter. More...

DBGattServer	getGATTServerData ()
	Return the user's DBGattServer shared reference if in `BTRole#Slave` mode as set via `and valid until subsequent disconnect.` More...

LE_Features	getLEFeatures ()
	Return `LE_Features` for this controller. More...

BTManager	getManager ()
	Returns the used singleton `BTManager` instance, used to create this adapter. More...

String	getName ()
	Returns the name. More...

boolean	getPoweredState ()
	Returns the power state the adapter. More...

BTRole	getRole ()
	Return the current `BTRole` of this adapter. More...

boolean	getSecureConnectionsEnabled ()
	Returns whether Secure Connections (SC) is enabled. More...

String	getShortName ()
	Returns the short name. More...

BDAddressAndType	getVisibleAddressAndType ()
	Returns the adapter's currently visible BDAddressAndType. More...

HCIStatusCode	initialize (final BTMode btMode, boolean powerOn)
	Initialize the adapter with default values, including power-on. More...

boolean	isAdvertising ()
	Returns the adapter's current advertising state. More...

boolean	isDeviceWhitelisted (final BDAddressAndType addressAndType)
	Returns true, if the adapter's device is already whitelisted. More...

boolean	isDiscovering ()
	Returns true if the meta discovering state is not `ScanType#NONE`. More...

boolean	isInitialized ()
	Returns true, if `initialize(BTMode)` has already been called for this adapter, otherwise false. More...

boolean	isPowered ()
	Returns whether the adapter is valid, plugged in and powered. More...

boolean	isSuspended ()
	Returns whether the adapter is suspended, i.e. More...

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

void	printDeviceLists ()
	Print the internally maintained BTDevice lists to stderr: More...

int	removeAllStatusListener ()
	Remove all `AdapterStatusListener` from the list. More...

boolean	removeDeviceFromWhitelist (final BDAddressAndType addressAndType)
	Remove the given device from the adapter's autoconnect whitelist. More...

boolean	removeDevicePausingDiscovery (final BTDevice device)
	Manual `DiscoveryPolicy` intervention point, allowing user to remove the ready device from the queue of pausing-discovery devices. More...

boolean	removeDiscoveredDevice (final BDAddressAndType addressAndType)
	Discards matching discovered devices. More...

int	removeDiscoveredDevices () throws BTException
	Remove all the discovered devices found on this adapter. More...

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

HCIStatusCode	reset ()
	Reset the adapter. More...

HCIStatusCode	setDefaultConnParam (final short conn_interval_min, final short conn_interval_max, final short conn_latency, final short supervision_timeout)
	Set default connection parameter of incoming connections for this adapter when in server mode, i.e. More...

HCIStatusCode	setDefaultLE_PHY (final LE_PHYs Tx, final LE_PHYs Rx)
	Sets default preference of LE_PHYs. More...

HCIStatusCode	setName (String name, String short_name)
	Sets the name and short-name. More...

boolean	setPowered (final boolean power_on)
	Sets the power state the adapter. More...

HCIStatusCode	setPrivacy (boolean enable)
	Toggle adapter privacy address mode, i.e. More...

HCIStatusCode	setSecureConnections (final boolean enable)
	Enable or disable Secure Connections (SC) of the adapter. More...

void	setServerConnSecurity (final BTSecurityLevel sec_level, final SMPIOCapability io_cap)
	Sets the given ::BTSecurityLevel and ::SMPIOCapability for connecting device when in server (peripheral) mode, see adapter's role. More...

void	setSMPKeyPath (final String path)
	Set the adapter's persistent storage directory for `SMPKeyBin` files. More...

HCIStatusCode	startAdvertising (final DBGattServer gattServerData)
	Starts advertising using all default arguments, see `startAdvertising(short, short, byte, byte, byte)` for details. More...

HCIStatusCode	startAdvertising (final DBGattServer gattServerData, final EInfoReport eir, final EIRDataTypeSet adv_mask, final EIRDataTypeSet scanrsp_mask, final short adv_interval_min, final short adv_interval_max, final byte adv_type, final byte adv_chan_map, final byte filter_policy)
	Starts advertising. More...

HCIStatusCode	startAdvertising (final DBGattServer gattServerData, final short adv_interval_min, final short adv_interval_max, final byte adv_type, final byte adv_chan_map, final byte filter_policy)
	Starts advertising. More...

HCIStatusCode	startDiscovery () throws BTException
	Starts discovery using all default arguments, see `startDiscovery(DiscoveryPolicy, boolean, short, short, byte, boolean)` for details. More...

HCIStatusCode	startDiscovery (final DBGattServer gattServerData, final DiscoveryPolicy policy, final boolean le_scan_active, final short le_scan_interval, final short le_scan_window, final byte filter_policy, final boolean filter_dup) throws BTException
	Starts discovery. More...

HCIStatusCode	startDiscovery (final DiscoveryPolicy policy, final boolean le_scan_active) throws BTException
	Starts discovery using default arguments, see `startDiscovery(DiscoveryPolicy, boolean, short, short, byte, boolean)` for details. More...

HCIStatusCode	stopAdvertising ()
	Ends advertising. More...

HCIStatusCode	stopDiscovery () throws BTException
	Turns off device discovery if it is enabled. More...

String	toString ()

Public Member Functions inherited from org.direct_bt.BTObject
void	close ()
	Release the native memory associated with this object The object should not be used following a call to close. More...

boolean	equals (Object obj)

int	hashCode ()

Detailed Description

BTAdapter represents one local Bluetooth Controller.

Local BTAdapter roles (see getRole()):

BTRole::Master: The local adapter is discovering remote BTRole::Slave BTDevices and may initiate connections. Enabled via startDiscovery(..), but also per default at construction.
BTRole::Slave: The local adapter is advertising to remote BTRole::Master BTDevices and may accept connections. Enabled explicitly via startAdvertising(..) until startDiscovery(..).

Note the remote BTDevice's opposite role.

See also: BTDevice; BTDevice roles.; Bluetooth Specification; Direct-BT Overview

Definition at line 47 of file BTAdapter.java.

Member Function Documentation

◆ getManager()

BTManager org.direct_bt.BTAdapter.getManager ( )

Returns the used singleton BTManager instance, used to create this adapter.

Implemented in jau.direct_bt.DBTAdapter.

◆ getRole()

BTRole org.direct_bt.BTAdapter.getRole ( )

Return the current BTRole of this adapter.

See also: BTAdapterRoles

Since: 2.4.0

Implemented in jau.direct_bt.DBTAdapter.

Here is the caller graph for this function:

◆ getBTMode()

BTMode org.direct_bt.BTAdapter.getBTMode ( )

Returns the current BTMode of this adapter.

Since: 2.4.0

Implemented in jau.direct_bt.DBTAdapter.

◆ find() [1/2]

BTDevice org.direct_bt.BTAdapter.find	(	String	name,
		BDAddressAndType	addressAndType,
		long	timeoutMS
	)

Find a BluetoothDevice.

If parameters name and address are not null, the returned object will have to match them. It will first check for existing objects. It will not turn on discovery or connect to devices. @parameter name optionally specify the name of the object you are waiting for @parameter address optionally specify the MAC address of the device 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 name and address or null if not found before timeout expires.

Implemented in jau.direct_bt.DBTAdapter.

◆ find() [2/2]

BTDevice org.direct_bt.BTAdapter.find	(	String	name,
		BDAddressAndType	addressAndType
	)

Find a BluetoothDevice.

If parameters name and address are not null, the returned object will have to match them. It will first check for existing objects. It will not turn on discovery or connect to devices. @parameter name optionally specify the name of the object you are waiting for @parameter address optionally specify the MAC address of the device you are waiting for

Returns: An object matching the name and address.

Implemented in jau.direct_bt.DBTAdapter.

◆ isDeviceWhitelisted()

boolean org.direct_bt.BTAdapter.isDeviceWhitelisted ( final BDAddressAndType addressAndType )

Returns true, if the adapter's device is already whitelisted.

Since: 2.0.0

Implemented in jau.direct_bt.DBTAdapter.

◆ addDeviceToWhitelist() [1/2]

boolean org.direct_bt.BTAdapter.addDeviceToWhitelist	(	final BDAddressAndType	addressAndType,
		final HCIWhitelistConnectType	ctype,
		final short	conn_interval_min,
		final short	conn_interval_max,
		final short	conn_latency,
		final short	timeout
	)

Add the given device to the adapter's autoconnect whitelist.

The given LE connection parameter will be uploaded to the kernel for the given device first, if the device is of type BDAddressType#BDADDR_LE_PUBLIC or BDAddressType#BDADDR_LE_RANDOM.

Method will reject duplicate devices, in which case it should be removed first.

Parameters

address
address_type
ctype
conn_interval_min	default value 0x000F
conn_interval_max	default value 0x000F
conn_latency	default value 0x0000
timeout	in units of 10ms, default value 1000 for 10000ms or 10s.

Returns: true if successful, otherwise false.

See also: #addDeviceToWhitelist(String, BDAddressType, HCIWhitelistConnectType)

Since: 2.0.0

Implemented in jau.direct_bt.DBTAdapter.

◆ addDeviceToWhitelist() [2/2]

boolean org.direct_bt.BTAdapter.addDeviceToWhitelist	(	final BDAddressAndType	addressAndType,
		final HCIWhitelistConnectType	ctype
	)

Add the given device to the adapter's autoconnect whitelist.

This variant of addDeviceToWhitelist(String, BDAddressType, HCIWhitelistConnectType, short, short, short, short) uses default connection parameter, which will be uploaded to the kernel for the given device first.

Method will reject duplicate devices, in which case it should be removed first.

Parameters

address
address_type
ctype

Returns: true if successful, otherwise false.

See also: #addDeviceToWhitelist(String, BDAddressType, HCIWhitelistConnectType, short, short, short, short)

Since: 2.0.0

Implemented in jau.direct_bt.DBTAdapter.

◆ removeDeviceFromWhitelist()

boolean org.direct_bt.BTAdapter.removeDeviceFromWhitelist ( final BDAddressAndType addressAndType )

Remove the given device from the adapter's autoconnect whitelist.

Since: 2.0.0

Implemented in jau.direct_bt.DBTAdapter.

◆ startDiscovery() [1/3]

HCIStatusCode org.direct_bt.BTAdapter.startDiscovery ( ) throws BTException

Starts discovery using all default arguments, see startDiscovery(DiscoveryPolicy, boolean, short, short, byte, boolean) for details.

Returns: HCIStatusCode#SUCCESS if successful, otherwise the HCIStatusCode error state

Exceptions

BTException

See also: #startDiscovery(DiscoveryPolicy, boolean, short, short, byte, boolean); #getDiscovering(); DiscoveryPolicy

Since: 2.5.0

Implemented in jau.direct_bt.DBTAdapter.

Here is the caller graph for this function:

◆ startDiscovery() [2/3]

HCIStatusCode org.direct_bt.BTAdapter.startDiscovery	(	final DiscoveryPolicy	policy,
		final boolean	le_scan_active
	)		throws BTException

Starts discovery using default arguments, see startDiscovery(DiscoveryPolicy, boolean, short, short, byte, boolean) for details.

Parameters

policy	defaults to `DiscoveryPolicy#PAUSE_CONNECTED_UNTIL_READY`, see `DiscoveryPolicy`
le_scan_active	true enables delivery of active scanning PDUs like EIR w/ device name (default), otherwise no scanning PDUs shall be sent.

Returns: HCIStatusCode#SUCCESS if successful, otherwise the HCIStatusCode error state

Exceptions

BTException

See also: #startDiscovery(DiscoveryPolicy, boolean, short, short, byte, boolean); #getDiscovering(); DiscoveryPolicy

Since: 2.5.0

Implemented in jau.direct_bt.DBTAdapter.

◆ startDiscovery() [3/3]

HCIStatusCode org.direct_bt.BTAdapter.startDiscovery	(	final DBGattServer	gattServerData,
		final DiscoveryPolicy	policy,
		final boolean	le_scan_active,
		final short	le_scan_interval,
		final short	le_scan_window,
		final byte	filter_policy,
		final boolean	filter_dup
	)		throws BTException

Starts discovery.

Returns HCIStatusCode#SUCCESS if successful, otherwise the HCIStatusCode error state;

Depending on given DiscoveryPolicy policy, the discovery mode may be turned-off, paused until a certain readiness stage has been reached or preserved at all times. Default is DiscoveryPolicy#PAUSE_CONNECTED_UNTIL_READY.

+ --+-------+--------+-----------+----------------------------------------------------+
| # | meta  | native | keepAlive | Note
+---+-------+--------+-----------+----------------------------------------------------+
| 1 | true  | true   | false     | -
| 2 | false | false  | false     | -
+---+-------+--------+-----------+----------------------------------------------------+
| 3 | true  | true   | true      | -
| 4 | true  | false  | true      | temporarily disabled -> startDiscoveryBackground()
| 5 | false | false  | true      | [4] -> [5] requires manual DISCOVERING event
+---+-------+--------+-----------+----------------------------------------------------+

Default parameter values are chosen for using public address resolution and usual discovery intervals etc.

Method will always clear previous discovered devices via removeDiscoveredDevices().

Method fails if isAdvertising().

If successful, method also changes this adapter's role to BTRole#Master.

Parameters

gattServerData_	the `DBGattServer` data to be offered via GattHandler as ::GATTRole::Client. Its handles will be setup via DBGattServer::setServicesHandles(). Reference is held until next startDiscovery.
policy	defaults to `DiscoveryPolicy#PAUSE_CONNECTED_UNTIL_READY`, see `DiscoveryPolicy`
le_scan_active	true enables delivery of active scanning PDUs like EIR w/ device name (default), otherwise no scanning PDUs shall be sent
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
filter_policy	0x00 accepts all PDUs (default), 0x01 only of whitelisted, ...
filter_dup	true to filter out duplicate AD PDUs (default), otherwise all will be reported.

Returns: HCIStatusCode#SUCCESS if successful, otherwise the HCIStatusCode error state

Exceptions

BTException

Since: 3.2.0

See also: startDiscovery(DiscoveryPolicy, boolean); isDiscovering(); isAdvertising(); DiscoveryPolicy; BTAdapterRoles

Implemented in jau.direct_bt.DBTAdapter.

◆ stopDiscovery()

HCIStatusCode org.direct_bt.BTAdapter.stopDiscovery ( ) throws BTException

Turns off device discovery if it is enabled.

Returns: HCIStatusCode#SUCCESS if successful, otherwise the HCIStatusCode error state @apiNote return HCIStatusCode since 2.0.0

Since: 2.0.0

Implemented in jau.direct_bt.DBTAdapter.

Here is the caller graph for this function:

◆ getCurrentDiscoveryPolicy()

DiscoveryPolicy org.direct_bt.BTAdapter.getCurrentDiscoveryPolicy ( )

Return the current DiscoveryPolicy, set via startDiscovery(DiscoveryPolicy, boolean, short, short, byte, boolean).

Since: 2.5.1

Implemented in jau.direct_bt.DBTAdapter.

◆ removeDevicePausingDiscovery()

boolean org.direct_bt.BTAdapter.removeDevicePausingDiscovery ( final BTDevice device )

Manual DiscoveryPolicy intervention point, allowing user to remove the ready device from the queue of pausing-discovery devices.

Manual intervention might be desired, if using DiscoveryPolicy#PAUSE_CONNECTED_UNTIL_DISCONNECTED, but allowing discovery at an earlier processing step from AdapterStatusListener#deviceReady(BTDevice, long).

Re-enabling discovery is performed on the current thread.

Parameters

device the BTDevice to remove from the pausing-discovery queue

Returns: true if this was the last BTDevice, re-enabling discovery. Otherwise false.

Since: 2.5.1

Implemented in jau.direct_bt.DBTAdapter.

◆ getDiscoveredDevices()

List< BTDevice > org.direct_bt.BTAdapter.getDiscoveredDevices ( )

Returns a list of discovered BluetoothDevices from this adapter.

Returns: A list of discovered BluetoothDevices on this adapter, NULL if an error occurred

Implemented in jau.direct_bt.DBTAdapter.

◆ removeDiscoveredDevices()

int org.direct_bt.BTAdapter.removeDiscoveredDevices ( ) throws BTException

Remove all the discovered devices found on this adapter.

Returns: The number of removed discovered devices on this adapter

Exceptions

BTException

Since: 2.2.0 @implNote Changed from 'removeDiscoveredDevices()' for clarity since version 2.2.0

Implemented in jau.direct_bt.DBTAdapter.

◆ removeDiscoveredDevice()

boolean org.direct_bt.BTAdapter.removeDiscoveredDevice ( final BDAddressAndType addressAndType )

Discards matching discovered devices.

Returns: true if found and removed, otherwise false.

Since: 2.2.0

Implemented in jau.direct_bt.DBTAdapter.

◆ startAdvertising() [1/3]

HCIStatusCode org.direct_bt.BTAdapter.startAdvertising	(	final DBGattServer	gattServerData,
		final EInfoReport	eir,
		final EIRDataTypeSet	adv_mask,
		final EIRDataTypeSet	scanrsp_mask,
		final short	adv_interval_min,
		final short	adv_interval_max,
		final byte	adv_type,
		final byte	adv_chan_map,
		final byte	filter_policy
	)

Starts advertising.

BT Core Spec v5.2: Vol 4 HCI, Part E HCI Functional: 7.8.53 LE Set Extended Advertising Parameters command (Bluetooth 5.0)
BT Core Spec v5.2: Vol 4 HCI, Part E HCI Functional: 7.8.54 LE Set Extended Advertising Data command (Bluetooth 5.0)
BT Core Spec v5.2: Vol 4 HCI, Part E HCI Functional: 7.8.55 LE Set Extended Scan Response Data command (Bluetooth 5.0)
BT Core Spec v5.2: Vol 4 HCI, Part E HCI Functional: 7.8.56 LE Set Extended Advertising Enable command (Bluetooth 5.0)

if available, otherwise using

BT Core Spec v5.2: Vol 4 HCI, Part E HCI Functional: 7.8.5 LE Set Advertising Parameters command
BT Core Spec v5.2: Vol 4 HCI, Part E HCI Functional: 7.8.7 LE Set Advertising Data command
BT Core Spec v5.2: Vol 4 HCI, Part E HCI Functional: 7.8.8 LE Set Scan Response Data command
BT Core Spec v5.2: Vol 4 HCI, Part E HCI Functional: 7.8.9 LE Set Advertising Enable command

Method fails if isDiscovering() or has any open or pending connected remote BTDevices.

If successful, method also changes this adapter's role to ::BTRole::Slave.

Advertising is active until either disabled via stopAdvertising() or a connection has been made, see isAdvertising().

The given ADV EIR EInfoReport will be updated with getName() and at least GAPFlags.Bit#LE_Gen_Disc set.

The given adv_mask and scanrsp_mask will be updated to have at least EIRDataTypeSet.DataType#FLAGS and EIRDataTypeSet.DataType#NAME set in total.

Parameters

gattServerData_	the `DBGattServer` data to be advertised and offered via GattHandler as ::GATTRole::Server. Its handles will be setup via DBGattServer::setServicesHandles(). Reference is held until next disconnect.
eir	Full ADV EIR `EInfoReport`, will be updated with `getName()` and at least `GAPFlags.Bit#LE_Gen_Disc` set.
adv_mask	`EIRDataTypeSet` mask for `EInfoReport` to select advertisement EIR PDU data, defaults to `EIRDataTypeSet.DataType#FLAGS` \| `EIRDataTypeSet.DataType#SERVICE_UUID`
scanrsp_mask	`EIRDataTypeSet` mask for `EInfoReport` to select scan-response (active scanning) EIR PDU data, defaults to `EIRDataTypeSet.DataType#NAME` \| `EIRDataTypeSet.DataType#CONN_IVAL`
adv_interval_min	in units of 0.625ms, default value 160 for 100ms; Value range [0x0020 .. 0x4000] for [20ms .. 10.24s]
adv_interval_max	in units of 0.625ms, default value 480 for 300ms; Value range [0x0020 .. 0x4000] for [20ms .. 10.24s]
adv_type	see AD_PDU_Type, default 0x00, i.e. ::AD_PDU_Type::ADV_IND
adv_chan_map	bit 0: chan 37, bit 1: chan 38, bit 2: chan 39, default is 0x07 (all 3 channels enabled)
filter_policy	0x00 accepts all PDUs (default), 0x01 only of whitelisted, ...

Returns: HCIStatusCode::SUCCESS if successful, otherwise the HCIStatusCode error state

See also: startAdvertising(DBGattServer, short, short, byte, byte, byte); stopAdvertising(); isAdvertising(); isDiscovering(); BTAdapterRoles

Since: 2.5.3

Implemented in jau.direct_bt.DBTAdapter.

Here is the caller graph for this function:

◆ startAdvertising() [2/3]

HCIStatusCode org.direct_bt.BTAdapter.startAdvertising	(	final DBGattServer	gattServerData,
		final short	adv_interval_min,
		final short	adv_interval_max,
		final byte	adv_type,
		final byte	adv_chan_map,
		final byte	filter_policy
	)

Starts advertising.

BT Core Spec v5.2: Vol 4 HCI, Part E HCI Functional: 7.8.53 LE Set Extended Advertising Parameters command (Bluetooth 5.0)
BT Core Spec v5.2: Vol 4 HCI, Part E HCI Functional: 7.8.54 LE Set Extended Advertising Data command (Bluetooth 5.0)
BT Core Spec v5.2: Vol 4 HCI, Part E HCI Functional: 7.8.55 LE Set Extended Scan Response Data command (Bluetooth 5.0)
BT Core Spec v5.2: Vol 4 HCI, Part E HCI Functional: 7.8.56 LE Set Extended Advertising Enable command (Bluetooth 5.0)

if available, otherwise using

BT Core Spec v5.2: Vol 4 HCI, Part E HCI Functional: 7.8.5 LE Set Advertising Parameters command
BT Core Spec v5.2: Vol 4 HCI, Part E HCI Functional: 7.8.7 LE Set Advertising Data command
BT Core Spec v5.2: Vol 4 HCI, Part E HCI Functional: 7.8.8 LE Set Scan Response Data command
BT Core Spec v5.2: Vol 4 HCI, Part E HCI Functional: 7.8.9 LE Set Advertising Enable command

Method fails if isDiscovering() or has any open or pending connected remote BTDevices.

If successful, method also changes this adapter's role to ::BTRole::Slave.

Advertising is active until either disabled via stopAdvertising() or a connection has been made, see isAdvertising().

The ADV EIR EInfoReport will be generated on the default EIRDataTypeSet adv_mask using EIRDataTypeSet.DataType#FLAGS | EIRDataTypeSet.DataType#SERVICE_UUID and EIRDataTypeSet scanrsp_mask using scan-response (active scanning) EIRDataTypeSet.DataType#NAME | EIRDataTypeSet.DataType#CONN_IVAL.

Parameters

gattServerData_	the `DBGattServer` data to be advertised and offered via GattHandler as ::GATTRole::Server. Its handles will be setup via DBGattServer::setServicesHandles(). Reference is held until next disconnect.
adv_interval_min	in units of 0.625ms, default value 160 for 100ms; Value range [0x0020 .. 0x4000] for [20ms .. 10.24s]
adv_interval_max	in units of 0.625ms, default value 480 for 300ms; Value range [0x0020 .. 0x4000] for [20ms .. 10.24s]
adv_type	see AD_PDU_Type, default 0x00, i.e. ::AD_PDU_Type::ADV_IND
adv_chan_map	bit 0: chan 37, bit 1: chan 38, bit 2: chan 39, default is 0x07 (all 3 channels enabled)
filter_policy	0x00 accepts all PDUs (default), 0x01 only of whitelisted, ...

Returns: HCIStatusCode::SUCCESS if successful, otherwise the HCIStatusCode error state

See also: startAdvertising(DBGattServer, EInfoReport, EIRDataTypeSet, EIRDataTypeSet, short, short, byte, byte, byte); startAdvertising(DBGattServer); stopAdvertising(); isAdvertising(); isDiscovering(); BTAdapterRoles

Since: 2.4.0

Implemented in jau.direct_bt.DBTAdapter.

◆ startAdvertising() [3/3]

HCIStatusCode org.direct_bt.BTAdapter.startAdvertising ( final DBGattServer gattServerData )

Starts advertising using all default arguments, see startAdvertising(short, short, byte, byte, byte) for details.

Advertising is active until either disabled via stopAdvertising() or a connection has been made, see isAdvertising().

Parameters

gattServerData_ the DBGattServer data to be advertised and offered via GattHandler as ::GATTRole::Server. Its handles will be setup via DBGattServer::setServicesHandles(). Reference is held until next disconnect.

Returns: HCIStatusCode::SUCCESS if successful, otherwise the HCIStatusCode error state

See also: startAdvertising(DBGattServer, EInfoReport, EIRDataTypeSet, EIRDataTypeSet, short, short, byte, byte, byte); stopAdvertising(); isAdvertising(); isDiscovering(); BTAdapterRoles

Since: 2.4.0

Implemented in jau.direct_bt.DBTAdapter.

◆ stopAdvertising()

HCIStatusCode org.direct_bt.BTAdapter.stopAdvertising ( )

Ends advertising.

BT Core Spec v5.2: Vol 4 HCI, Part E HCI Functional: 7.8.56 LE Set Extended Advertising Enable command (Bluetooth 5.0)

if available, otherwise using

BT Core Spec v5.2: Vol 4 HCI, Part E HCI Functional: 7.8.9 LE Set Advertising Enable command

Advertising is active until either disabled via stopAdvertising() or a connection has been made, see isAdvertising().

Returns: HCIStatusCode::SUCCESS if successful, otherwise the HCIStatusCode error state

See also: #startAdvertising(short, short, byte, byte, byte); isAdvertising()

Since: 2.4.0

Implemented in jau.direct_bt.DBTAdapter.

◆ isAdvertising()

boolean org.direct_bt.BTAdapter.isAdvertising ( )

Returns the adapter's current advertising state.

It can be modified through startAdvertising(..) and stopAdvertising().

Advertising is active until either disabled via stopAdvertising() or a connection has been made, see isAdvertising().

See also: #startAdvertising(short, short, byte, byte, byte); stopAdvertising()

Since: 2.4.0

Implemented in jau.direct_bt.DBTAdapter.

Here is the caller graph for this function:

◆ equals()

boolean org.direct_bt.BTAdapter.equals ( final Object obj )

If both types are of BTAdapter, it compares their BDAddressAndType, see getAddressAndType().

Implements org.direct_bt.BTObject.

Implemented in jau.direct_bt.DBTAdapter.

Here is the caller graph for this function:

◆ getAddressAndType()

BDAddressAndType org.direct_bt.BTAdapter.getAddressAndType ( )

Returns the adapter's public BDAddressAndType.

The adapter's address as initially reported by the system is always its public address, i.e. BDAddressType#BDADDR_LE_PUBLIC.

Since: 2.2.8

See also: getVisibleAddressAndType()

Implemented in jau.direct_bt.DBTAdapter.

Here is the caller graph for this function:

◆ getVisibleAddressAndType()

BDAddressAndType org.direct_bt.BTAdapter.getVisibleAddressAndType ( )

Returns the adapter's currently visible BDAddressAndType.

The adapter's address as initially reported by the system is always its public address, i.e. BDAddressType#BDADDR_LE_PUBLIC.

The adapter's visible BDAddressAndType might be set to BDAddressType#BDADDR_LE_RANDOM before scanning / discovery mode (TODO).

Since: 2.2.8

See also: getAddressAndType()

Implemented in jau.direct_bt.DBTAdapter.

◆ getDevID()

int org.direct_bt.BTAdapter.getDevID ( )

Returns the BluetoothAdapter's internal temporary device id.

The internal device id is constant across the adapter lifecycle, but may change after its destruction.

Since: 2.0.0

Implemented in jau.direct_bt.DBTAdapter.

Here is the caller graph for this function:

◆ getBTMajorVersion()

int org.direct_bt.BTAdapter.getBTMajorVersion ( )

Returns the Bluetooth major version of this adapter.

Currently either 4 or 5.

Implemented in jau.direct_bt.DBTAdapter.

Here is the caller graph for this function:

◆ getName()

String org.direct_bt.BTAdapter.getName ( )

Returns the name.

Can be changed via setName(String, String) while powered-off.

See also: setName(String, String)

Implemented in jau.direct_bt.DBTAdapter.

Here is the caller graph for this function:

◆ getShortName()

String org.direct_bt.BTAdapter.getShortName ( )

Returns the short name.

Can be changed via setName(String, String) while powered-off.

See also: setName(String, String)

Since: 2.4.0

Implemented in jau.direct_bt.DBTAdapter.

◆ setName()

HCIStatusCode org.direct_bt.BTAdapter.setName	(	String	name,
		String	short_name
	)

Sets the name and short-name.

The corresponding management event will change the name and short-name.

Shall be called while adapter is powered off, see setPowered(boolean). If adapter is powered, method returns HCIStatusCode#COMMAND_DISALLOWED.

Parameters

name
short_name

Returns: HCIStatusCode#SUCCESS if successful, otherwise the HCIStatusCode error state

See also: getName(); getShortName(); setPowered(boolean)

Since: 2.4.0

Implemented in jau.direct_bt.DBTAdapter.

Here is the caller graph for this function:

◆ isPowered()

boolean org.direct_bt.BTAdapter.isPowered ( )

Returns whether the adapter is valid, plugged in and powered.

Returns: true if isValid(), HCI channel open and POWERED state is set.

See also: isSuspended(); isValid()

Since: 2.0.0

Implemented in jau.direct_bt.DBTAdapter.

Here is the caller graph for this function:

◆ isSuspended()

boolean org.direct_bt.BTAdapter.isSuspended ( )

Returns whether the adapter is suspended, i.e.

valid and plugged in, but not powered.

Returns: true if isValid(), HCI channel open and POWERED state is not set.

See also: isPowered(); isValid()

Implemented in jau.direct_bt.DBTAdapter.

◆ isValid()

boolean org.direct_bt.BTAdapter.isValid ( )

Returns whether the adapter is valid, i.e.

reference is valid, plugged in and generally operational, but not necessarily isPowered().

Returns: true if this adapter references are valid and hadn't been close()'ed

See also: isPowered(); isSuspended()

Since: 2.0.0

Implemented in jau.direct_bt.DBTAdapter.

◆ getLEFeatures()

LE_Features org.direct_bt.BTAdapter.getLEFeatures ( )

Return LE_Features for this controller.

BT Core Spec v5.2: Vol 6, Part B, 4.6 (LE LL) Feature Support

Since: 2.4.0

Implemented in jau.direct_bt.DBTAdapter.

Here is the caller graph for this function:

◆ getPoweredState()

boolean org.direct_bt.BTAdapter.getPoweredState ( )

Returns the power state the adapter.

Consider using isPowered()

Returns: The power state of the adapter.

Since: 2.0.0 Renamed from getPowered() to getPoweredState()

See also: isPowered(); isSuspended(); isValid()

Implemented in jau.direct_bt.DBTAdapter.

◆ setPowered()

boolean org.direct_bt.BTAdapter.setPowered ( final boolean power_on )

Sets the power state the adapter.

In case current power state is already as desired, method will not change the power state.

Parameters

power_on true will power on this adapter if it is powered-off and vice versa.

Returns: true if successfully powered-on, -off or unchanged, false on failure

@apiNote return value boolean since 2.0.0

See also: close(); #initialize(BTMode); isInitialized()

Since: 2.0.0

Implemented in jau.direct_bt.DBTAdapter.

Here is the caller graph for this function:

◆ setPrivacy()

HCIStatusCode org.direct_bt.BTAdapter.setPrivacy ( boolean enable )

Toggle adapter privacy address mode, i.e.

resolvable random address including IRK.

Parameters

enable toggle to enable or disable (default)

Returns: HCIStatusCode::SUCCESS or an error state on failure

Since: 3.2.0

Implemented in jau.direct_bt.DBTAdapter.

◆ getSecureConnectionsEnabled()

boolean org.direct_bt.BTAdapter.getSecureConnectionsEnabled ( )

Returns whether Secure Connections (SC) is enabled.

See also: setSecureConnections(boolean)

Since: 2.4.0

Implemented in jau.direct_bt.DBTAdapter.

◆ setSecureConnections()

HCIStatusCode org.direct_bt.BTAdapter.setSecureConnections ( final boolean enable )

Enable or disable Secure Connections (SC) of the adapter.

By default, Secure Connections (SC) is enabled if supported.

Shall be called while adapter is powered off, see setPowered(boolean). If adapter is powered, method returns HCIStatusCode#COMMAND_DISALLOWED.

Parameters

enable

Returns: HCIStatusCode#SUCCESS if successful, otherwise the HCIStatusCode error state

See also: getSecureConnectionsEnabled(); setPowered(boolean)

Since: 2.4.0

Implemented in jau.direct_bt.DBTAdapter.

Here is the caller graph for this function:

◆ setDefaultConnParam()

HCIStatusCode org.direct_bt.BTAdapter.setDefaultConnParam	(	final short	conn_interval_min,
		final short	conn_interval_max,
		final short	conn_latency,
		final short	supervision_timeout
	)

Set default connection parameter of incoming connections for this adapter when in server mode, i.e.

BTRole::Slave.

In case the incoming connection's parameter don't lie within the given default values, a reconnect is being requested.

Shall be called while adapter is powered off, see setPowered(). If adapter is powered, method returns HCIStatusCode::COMMAND_DISALLOWED.

BlueZ/Linux LE connection defaults are

conn_interval_min 24 -> 30ms
conn_interval_max 40 -> 50ms
conn_latency 0
supervision_timeout 42 -> 420ms

Supported on GNU/Linux since kernel 5.9.

Parameters

dev_id
conn_interval_min	in units of 1.25ms, default value 8 for 10ms; Value range [6 .. 3200] for [7.5ms .. 4000ms].
conn_interval_max	in units of 1.25ms, default value 40 for 50ms; 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 500ms >= 10 x conn_interval_max, we use HCIConstInt::LE_CONN_MIN_TIMEOUT_MS minimum; Value range [0xA-0x0C80] for [100ms - 32s].

Returns: HCIStatusCode::SUCCESS or an error state on failure

See also: setPowered()

Since: 2.5.3

Implemented in jau.direct_bt.DBTAdapter.

Here is the caller graph for this function:

◆ setServerConnSecurity()

void org.direct_bt.BTAdapter.setServerConnSecurity	(	final BTSecurityLevel	sec_level,
		final SMPIOCapability	io_cap
	)

Sets the given ::BTSecurityLevel and ::SMPIOCapability for connecting device when in server (peripheral) mode, see adapter's role.

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

Parameters

[in]	sec_level	::BTSecurityLevel to be applied.
[in]	io_cap	::SMPIOCapability to be applied.

See also: BTSecurityLevel; SMPIOCapability; BTDevice::setConnSecurity(BTSecurityLevel, SMPIOCapability); startAdvertising(DBGattServer, EInfoReport, EIRDataTypeSet, EIRDataTypeSet, short, short, byte, byte, byte)

Implemented in jau.direct_bt.DBTAdapter.

Here is the caller graph for this function:

◆ setSMPKeyPath()

void org.direct_bt.BTAdapter.setSMPKeyPath ( final String path )

Set the adapter's persistent storage directory for SMPKeyBin files.

if set, all SMPKeyBin instances will be managed and persistent.
if not set, all SMPKeyBin instances will be transient only.

When called, all keys within the path will be loaded, i.e. issuing for all keys belonging to this BTAdapter. Persistent SMPKeyBin management is only functional when BTAdapter is in BTRole#Slave peripheral mode.

For each SMPKeyBin file one shared BTDevice in BTRole#Master will be instantiated when uploadKeys() is called.

Parameters

path	persistent storage path to `SMPKeyBin` files

See also: BTDevice::uploadKeys(SMPKeyBin, BTSecurityLevel)

Implemented in jau.direct_bt.DBTAdapter.

Here is the caller graph for this function:

◆ initialize()

HCIStatusCode org.direct_bt.BTAdapter.initialize	(	final BTMode	btMode,
		boolean	powerOn
	)

Initialize the adapter with default values, including power-on.

Method shall be issued on the desired adapter found via BTManager.ChangedAdapterSetListener.

While initialization, the adapter is first powered-off, setup and then powered-on.

Calling the method will allow close() to power-off the adapter, if not powered on before.

Parameters

btMode	the desired adapter's `BTMode`, default shall be `BTMode#DUAL`
powerOn	true to leave adapter powered-on, otherwise leave it off *

Returns: HCIStatusCode#SUCCESS or an error state on failure (e.g. power-on)

See also: isInitialized(); initialize(); close(); setPowered(boolean)

Since: 3.2.0

Implemented in jau.direct_bt.DBTAdapter.

Here is the caller graph for this function:

◆ isInitialized()

boolean org.direct_bt.BTAdapter.isInitialized ( )

Returns true, if initialize(BTMode) has already been called for this adapter, otherwise false.

See also: #initialize(BTMode)

Since: 2.4.0

Implemented in jau.direct_bt.DBTAdapter.

Here is the caller graph for this function:

◆ reset()

HCIStatusCode org.direct_bt.BTAdapter.reset ( )

Reset the adapter.

The semantics are specific to the HCI host implementation, however, it shall comply at least with the HCI Reset command and bring up the device from standby into a POWERED functional state afterwards.

BT Core Spec v5.2: Vol 4, Part E HCI: 7.3.2 Reset command

Since: 2.0.0

Implemented in jau.direct_bt.DBTAdapter.

◆ setDefaultLE_PHY()

HCIStatusCode org.direct_bt.BTAdapter.setDefaultLE_PHY	(	final LE_PHYs	Tx,
		final LE_PHYs	Rx
	)

Sets default preference of LE_PHYs.

BT Core Spec v5.2: Vol 4, Part E, 7.8.49 LE Set PHY command

Parameters

Tx	transmitter LE_PHYs bit mask of preference if not set to zero `LE_PHYs#mask` (ignored).
Rx	receiver LE_PHYs bit mask of preference if not set to zero `LE_PHYs#mask` (ignored).

Returns

See also: BTDevice::getTxPhys(); BTDevice::getRxPhys(); BTDevice::getConnectedLE_PHY(LE_PHYs[], LE_PHYs[]); BTDevice::setConnectedLE_PHY(LE_PHYs, LE_PHYs)

Since: 2.4.0

Implemented in jau.direct_bt.DBTAdapter.

Here is the caller graph for this function:

◆ connectDevice()

BTDevice org.direct_bt.BTAdapter.connectDevice ( BDAddressAndType addressAndType )

This method connects to device without need of performing General Discovery.

Connection mechanism is similar to Connect method from Device1 interface with exception that this method returns success when physical connection is established. After this method returns, services discovery will continue and any supported profile will be connected. There is no need for calling Connect on Device1 after this call. If connection was successful this method returns object path to created device object.

Parameters

address	The Bluetooth device address of the remote device. This parameter is mandatory.
addressType	The Bluetooth device Address Type. This is address type that should be used for initial connection. If this parameter is not present BR/EDR device is created. Possible values: `public` - Public address `random` - Random address

Implemented in jau.direct_bt.DBTAdapter.

◆ getCurrentScanType()

ScanType org.direct_bt.BTAdapter.getCurrentScanType ( )

Returns the current meta discovering ScanType.

It can be modified through startDiscovery(DiscoveryPolicy, boolean) and stopDiscovery().

Note that if startDiscovery(DiscoveryPolicy, boolean) has been issued with keepAlive==true, the meta ScanType will still keep the desired ScanType enabled even if it has been temporarily disabled.

See also: #startDiscovery(boolean); stopDiscovery()

Since: 2.0.0

Implemented in jau.direct_bt.DBTAdapter.

◆ isDiscovering()

boolean org.direct_bt.BTAdapter.isDiscovering ( )

Returns true if the meta discovering state is not ScanType#NONE.

It can be modified through startDiscovery(DiscoveryPolicy, boolean) and stopDiscovery().

See also: startDiscovery(); stopDiscovery()

Since: 2.4.0

Implemented in jau.direct_bt.DBTAdapter.

Here is the caller graph for this function:

◆ addStatusListener()

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

Add the given AdapterStatusListener to the list if not already present.

In case the AdapterStatusListener's lifecycle and event delivery shall be constrained to this device, please use BTDevice#addStatusListener(AdapterStatusListener).

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

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); removeStatusListener(AdapterStatusListener); removeAllStatusListener()

Implemented in jau.direct_bt.DBTAdapter.

Here is the caller graph for this function:

◆ removeStatusListener()

boolean org.direct_bt.BTAdapter.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.0.0

Implemented in jau.direct_bt.DBTAdapter.

Here is the caller graph for this function:

◆ removeAllStatusListener()

int org.direct_bt.BTAdapter.removeAllStatusListener ( )

Remove all AdapterStatusListener from the list.

Returns: number of removed listener.

Since: 2.0.0

Implemented in jau.direct_bt.DBTAdapter.

Here is the caller graph for this function:

◆ getGATTServerData()

DBGattServer org.direct_bt.BTAdapter.getGATTServerData ( )

Return the user's DBGattServer shared reference if in BTRole#Slave mode as set via and valid until subsequent disconnect.

Returns nullptr if in BTRole#Master mode.

Implemented in jau.direct_bt.DBTAdapter.

◆ printDeviceLists()

void org.direct_bt.BTAdapter.printDeviceLists ( )

Print the internally maintained BTDevice lists to stderr:

sharedDevices
connectedDevice
discoveredDevices
StatusListener

This is intended as a debug facility.

Since: 2.3.0

Implemented in jau.direct_bt.DBTAdapter.

◆ toString()

String org.direct_bt.BTAdapter.toString ( )

Implemented in jau.direct_bt.DBTAdapter.

Here is the caller graph for this function:

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

java/org/direct_bt/BTAdapter.java

Public Member Functions

Detailed Description

Member Function Documentation

◆ getManager()

◆ getRole()

◆ getBTMode()

◆ find() [1/2]

◆ find() [2/2]

◆ isDeviceWhitelisted()

◆ addDeviceToWhitelist() [1/2]

◆ addDeviceToWhitelist() [2/2]

◆ removeDeviceFromWhitelist()

◆ startDiscovery() [1/3]

◆ startDiscovery() [2/3]

◆ startDiscovery() [3/3]

◆ stopDiscovery()

◆ getCurrentDiscoveryPolicy()

◆ removeDevicePausingDiscovery()

◆ getDiscoveredDevices()

◆ removeDiscoveredDevices()

◆ removeDiscoveredDevice()

◆ startAdvertising() [1/3]

◆ startAdvertising() [2/3]

◆ startAdvertising() [3/3]

◆ stopAdvertising()

◆ isAdvertising()

◆ equals()

◆ getAddressAndType()

◆ getVisibleAddressAndType()

◆ getDevID()

◆ getBTMajorVersion()

◆ getName()

◆ getShortName()

◆ setName()

◆ isPowered()

◆ isSuspended()

◆ isValid()

◆ getLEFeatures()

◆ getPoweredState()

◆ setPowered()

◆ setPrivacy()

◆ getSecureConnectionsEnabled()

◆ setSecureConnections()

◆ setDefaultConnParam()

◆ setServerConnSecurity()

◆ setSMPKeyPath()

◆ initialize()

◆ isInitialized()

◆ reset()

◆ setDefaultLE_PHY()

◆ connectDevice()

◆ getCurrentScanType()

◆ isDiscovering()

◆ addStatusListener()

◆ removeStatusListener()

◆ removeAllStatusListener()

◆ getGATTServerData()

◆ printDeviceLists()

◆ toString()