A thread safe singleton handler of the HCI control channel to one controller (BT adapter) More...

#include <HCIHandler.hpp>

Collaboration diagram for direct_bt::HCIHandler:

Public Types
enum	DefaultsSizeT : jau::nsize_t { HCI_MAX_MTU = static_cast<jau::nsize_t>(HCIConstSizeT::PACKET_MAX_SIZE) }

typedef std::shared_ptr< HCIConnection >	HCIConnectionRef

typedef jau::darray< HCIConnectionRef, size_type >	HCIConnectionRefList_t

typedef jau::function< HCIStatusCode() >	PostShutdownFunc
	Use post shutdown function, considered to be `noexcept`. More...

typedef jau::nsize_t	size_type

Public Member Functions
	HCIHandler (const HCIHandler &)=delete

	HCIHandler (const uint16_t dev_id, const BTMode btMode=BTMode::NONE) noexcept

	~HCIHandler () noexcept
	Releases this instance after issuing `close()`. More...

bool	addMgmtEventCallback (const MgmtEvent::Opcode opc, const MgmtEventCallback &cb) noexcept
	MgmtEventCallback handling More...

void	addSMPMsgCallback (const HCISMPMsgCallback &l)

void	clearAllCallbacks () noexcept
	Removes all MgmtEventCallbacks from all MgmtEvent::Opcode lists and all SMPSecurityReqCallbacks. More...

void	clearMgmtEventCallbacks (const MgmtEvent::Opcode opc) noexcept
	Removes all MgmtEventCallbacks from the to the named MgmtEvent::Opcode list. More...

void	close () noexcept

HCIStatusCode	create_conn (const EUI48 &bdaddr, const uint16_t pkt_type=HCI_DM1\|HCI_DM3\|HCI_DM5\|HCI_DH1\|HCI_DH3\|HCI_DH5, const uint16_t clock_offset=0x0000, const uint8_t role_switch=0x01) noexcept
	Establish a connection to the given BREDR (non LE). More...

HCIStatusCode	disconnect (const uint16_t conn_handle, const BDAddressAndType &peerAddressAndType, const HCIStatusCode reason=HCIStatusCode::REMOTE_USER_TERMINATED_CONNECTION) noexcept
	Disconnect an established connection. More...

BTMode	getBTMode () const noexcept

ScanType	getCurrentScanType () const noexcept

HCIStatusCode	getLocalVersion (HCILocalVersion &version) noexcept

bool	isAdvertising () const noexcept
	Advertising is enabled via le_start_adv() or le_enable_adv(). More...

bool	isOpen () const noexcept
	Returns true if this mgmt instance is open, connected and hence valid, otherwise false. More...

HCIStatusCode	le_add_to_resolv_list (const BDAddressAndType &peerIdentityAddressAndType, jau::uint128dp_t &peer_irk, jau::uint128dp_t &local_irk) noexcept
	BT Core Spec v5.2: Vol 4, Part E HCI: 7.8.38 LE Add Device To Resolving List command. More...

HCIStatusCode	le_clear_resolv_list () noexcept
	BT Core Spec v5.2: Vol 4, Part E HCI: 7.8.40 LE Clear Resolving List command. More...

HCIStatusCode	le_create_conn (const EUI48 &peer_bdaddr, const HCILEPeerAddressType peer_mac_type=HCILEPeerAddressType::PUBLIC, const HCILEOwnAddressType own_mac_type=HCILEOwnAddressType::PUBLIC, const uint16_t le_scan_interval=24, const uint16_t le_scan_window=24, const uint16_t conn_interval_min=8, const uint16_t conn_interval_max=12, const uint16_t conn_latency=0, const uint16_t supervision_timeout=getHCIConnSupervisorTimeout(0, 15)) noexcept
	Establish a connection to the given LE peer. More...

HCIStatusCode	le_del_from_resolv_list (const BDAddressAndType &peerIdentityAddressAndType) noexcept
	BT Core Spec v5.2: Vol 4, Part E HCI: 7.8.39 LE Remove Device From Resolving List command. More...

HCIStatusCode	le_enable_adv (const bool enable) noexcept
	Enables or disabled advertising. More...

HCIStatusCode	le_enable_scan (const bool enable, const bool filter_dup=true) noexcept
	Starts or stops LE scanning. More...

LE_Features	le_get_local_features () noexcept
	Return previously fetched LE_Features for the controller via initSupCommands() via resetAllStates() More...

HCIStatusCode	le_read_local_resolv_addr (const BDAddressAndType &peerIdentityAddressAndType, jau::EUI48 &localResolvableAddress) noexcept
	BT Core Spec v5.2: Vol 4, Part E HCI: 7.8.43 LE Read Local Resolvable Address command. More...

HCIStatusCode	le_read_peer_resolv_addr (const BDAddressAndType &peerIdentityAddressAndType, jau::EUI48 &peerResolvableAddress) noexcept
	BT Core Spec v5.2: Vol 4, Part E HCI: 7.8.42 LE Read Peer Resolvable Address command. More...

HCIStatusCode	le_read_phy (const uint16_t conn_handle, const BDAddressAndType &peerAddressAndType, LE_PHYs &resTx, LE_PHYs &resRx) noexcept
	Request and return LE_PHYs bit for the given connection. More...

HCIStatusCode	le_read_remote_features (const uint16_t conn_handle, const BDAddressAndType &peerAddressAndType) noexcept
	Request supported LE_Features from remote device. More...

HCIStatusCode	le_read_resolv_list_size (uint32_t &size_res) noexcept
	BT Core Spec v5.2: Vol 4, Part E HCI: 7.8.41 LE Read Resolving List Size command. More...

HCIStatusCode	le_set_addr_resolv_enable (const bool enable) noexcept
	BT Core Spec v5.2: Vol 4, Part E HCI: 7.8.44 LE Set Address Resolution Enable command. More...

HCIStatusCode	le_set_default_phy (const LE_PHYs Tx, const LE_PHYs Rx) noexcept
	Sets default preference of used LE_PHYs for all subsequent LE connections. More...

HCIStatusCode	le_set_phy (const uint16_t conn_handle, const BDAddressAndType &peerAddressAndType, const LE_PHYs Tx, const LE_PHYs Rx) noexcept
	Sets preference of used LE_PHYs for the given connection. More...

HCIStatusCode	le_start_adv (const EInfoReport &eir, const EIRDataType adv_mask=EIRDataType::FLAGS\|EIRDataType::SERVICE_UUID, const EIRDataType scanrsp_mask=EIRDataType::NAME\|EIRDataType::CONN_IVAL, const EUI48 &peer_bdaddr=EUI48::ANY_DEVICE, const HCILEOwnAddressType own_mac_type=HCILEOwnAddressType::PUBLIC, const HCILEOwnAddressType peer_mac_type=HCILEOwnAddressType::PUBLIC, const uint16_t adv_interval_min=160, const uint16_t adv_interval_max=480, const AD_PDU_Type adv_type=AD_PDU_Type::ADV_IND, const uint8_t adv_chan_map=0x07, const uint8_t filter_policy=0x00) noexcept
	Starts advertising. More...

HCIStatusCode	le_start_scan (const bool filter_dup=true, const bool le_scan_active=true, const HCILEOwnAddressType own_mac_type=HCILEOwnAddressType::PUBLIC, const uint16_t le_scan_interval=24, const uint16_t le_scan_window=24, const uint8_t filter_policy=0x00) noexcept
	Start LE scanning, i.e. More...

void	operator= (const HCIHandler &)=delete

size_type	removeMgmtEventCallback (const MgmtEvent::Opcode opc, const MgmtEventCallback &cb) noexcept
	Returns count of removed given MgmtEventCallback from the named MgmtEvent::Opcode list. More...

size_type	removeSMPMsgCallback (const HCISMPMsgCallback &l)

HCIStatusCode	resetAdapter (const PostShutdownFunc &user_post_shutdown)
	Complete adapter reset. More...

bool	resetAllStates (const bool powered_on) noexcept
	Reset all internal states, i.e. More...

void	sendMgmtEvent (const MgmtEvent &event) noexcept
	Manually send a MgmtEvent to all of its listeners. More...

void	setBTMode (const BTMode mode) noexcept

void	setCurrentScanType (const ScanType v) noexcept

void	setResolvHCIConnectionAddr (const BDAddressAndType &visibleAddressAndType, const BDAddressAndType &addressAndType) noexcept

std::string	toString () const noexcept

bool	use_ext_adv () const noexcept
	Use extended advertising if LE_Features::LE_Ext_Adv is set (Bluetooth 5.0). More...

bool	use_ext_conn () const noexcept
	Use extended connection if HCI_LE_Extended_Create_Connection is supported (Bluetooth 5.0). More...

bool	use_ext_scan () const noexcept
	Use extended scanning if HCI_LE_Set_Extended_Scan_Parameters and HCI_LE_Set_Extended_Scan_Enable is supported (Bluetooth 5.0). More...

bool	use_resolv_add () const noexcept

bool	use_resolv_clear () const noexcept

bool	use_resolv_del () const noexcept

bool	use_resolv_enable () const noexcept

bool	use_resolv_readLocalRA () const noexcept

bool	use_resolv_readPeerRA () const noexcept

bool	use_resolv_size () const noexcept

Public Attributes
const HCIEnv &	env

Detailed Description

A thread safe singleton handler of the HCI control channel to one controller (BT adapter)

Implementation utilizes a lock free ringbuffer receiving data within its separate thread.

Controlling Environment variables, see HCIEnv.

Definition at line 179 of file HCIHandler.hpp.

Member Typedef Documentation

◆ size_type

typedef jau::nsize_t direct_bt::HCIHandler::size_type

Definition at line 187 of file HCIHandler.hpp.

◆ HCIConnectionRef

typedef std::shared_ptr<HCIConnection> direct_bt::HCIHandler::HCIConnectionRef

Definition at line 237 of file HCIHandler.hpp.

◆ HCIConnectionRefList_t

typedef jau::darray<HCIConnectionRef, size_type> direct_bt::HCIHandler::HCIConnectionRefList_t

Definition at line 238 of file HCIHandler.hpp.

◆ PostShutdownFunc

typedef jau::function<HCIStatusCode() > direct_bt::HCIHandler::PostShutdownFunc

Use post shutdown function, considered to be noexcept.

HCIStatusCode post_shutdown() noexcept

Returns: HCIStatusCode::SUCCESS to continue the process, otherwise to abort process.

Definition at line 481 of file HCIHandler.hpp.

Member Enumeration Documentation

◆ DefaultsSizeT

enum direct_bt::HCIHandler::DefaultsSizeT : jau::nsize_t

Enumerator
HCI_MAX_MTU

Definition at line 181 of file HCIHandler.hpp.

Constructor & Destructor Documentation

◆ HCIHandler() [1/2]

HCIHandler::HCIHandler	(	const uint16_t	dev_id,
		const BTMode	btMode = `BTMode::NONE`
	)

noexcept

Definition at line 686 of file HCIHandler.cpp.

◆ HCIHandler() [2/2]

direct_bt::HCIHandler::HCIHandler ( const HCIHandler & )

delete

◆ ~HCIHandler()

direct_bt::HCIHandler::~HCIHandler ( )

inlinenoexcept

Releases this instance after issuing close().

Definition at line 396 of file HCIHandler.hpp.

Member Function Documentation

◆ setResolvHCIConnectionAddr()

void direct_bt::HCIHandler::setResolvHCIConnectionAddr	(	const BDAddressAndType &	visibleAddressAndType,
		const BDAddressAndType &	addressAndType
	)

inlinenoexcept

Definition at line 298 of file HCIHandler.hpp.

◆ operator=()

void direct_bt::HCIHandler::operator= ( const HCIHandler & )

delete

◆ close()

void HCIHandler::close ( )

noexcept

Definition at line 949 of file HCIHandler.cpp.

Here is the caller graph for this function:

◆ getBTMode()

BTMode direct_bt::HCIHandler::getBTMode ( ) const

inlinenoexcept

Definition at line 400 of file HCIHandler.hpp.

◆ setBTMode()

void direct_bt::HCIHandler::setBTMode ( const BTMode mode )

inlinenoexcept

Definition at line 402 of file HCIHandler.hpp.

◆ isOpen()

bool direct_bt::HCIHandler::isOpen ( ) const

inlinenoexcept

Returns true if this mgmt instance is open, connected and hence valid, otherwise false.

Definition at line 405 of file HCIHandler.hpp.

Here is the caller graph for this function:

◆ use_ext_scan()

bool direct_bt::HCIHandler::use_ext_scan ( ) const

inlinenoexcept

Use extended scanning if HCI_LE_Set_Extended_Scan_Parameters and HCI_LE_Set_Extended_Scan_Enable is supported (Bluetooth 5.0).

Definition at line 410 of file HCIHandler.hpp.

Here is the caller graph for this function:

◆ use_ext_conn()

bool direct_bt::HCIHandler::use_ext_conn ( ) const

inlinenoexcept

Use extended connection if HCI_LE_Extended_Create_Connection is supported (Bluetooth 5.0).

Definition at line 416 of file HCIHandler.hpp.

Here is the caller graph for this function:

◆ use_resolv_add()

bool direct_bt::HCIHandler::use_resolv_add ( ) const

inlinenoexcept

Definition at line 420 of file HCIHandler.hpp.

◆ use_resolv_del()

bool direct_bt::HCIHandler::use_resolv_del ( ) const

inlinenoexcept

Definition at line 421 of file HCIHandler.hpp.

◆ use_resolv_clear()

bool direct_bt::HCIHandler::use_resolv_clear ( ) const

inlinenoexcept

Definition at line 422 of file HCIHandler.hpp.

Here is the caller graph for this function:

◆ use_resolv_size()

bool direct_bt::HCIHandler::use_resolv_size ( ) const

inlinenoexcept

Definition at line 423 of file HCIHandler.hpp.

◆ use_resolv_readPeerRA()

bool direct_bt::HCIHandler::use_resolv_readPeerRA ( ) const

inlinenoexcept

Definition at line 424 of file HCIHandler.hpp.

◆ use_resolv_readLocalRA()

bool direct_bt::HCIHandler::use_resolv_readLocalRA ( ) const

inlinenoexcept

Definition at line 425 of file HCIHandler.hpp.

◆ use_resolv_enable()

bool direct_bt::HCIHandler::use_resolv_enable ( ) const

inlinenoexcept

Definition at line 426 of file HCIHandler.hpp.

◆ use_ext_adv()

bool direct_bt::HCIHandler::use_ext_adv ( ) const

inlinenoexcept

Use extended advertising if LE_Features::LE_Ext_Adv is set (Bluetooth 5.0).

Definition at line 429 of file HCIHandler.hpp.

Here is the caller graph for this function:

◆ getCurrentScanType()

ScanType direct_bt::HCIHandler::getCurrentScanType ( ) const

inlinenoexcept

Definition at line 433 of file HCIHandler.hpp.

Here is the caller graph for this function:

◆ setCurrentScanType()

void direct_bt::HCIHandler::setCurrentScanType ( const ScanType v )

inlinenoexcept

Definition at line 434 of file HCIHandler.hpp.

◆ isAdvertising()

bool direct_bt::HCIHandler::isAdvertising ( ) const

inlinenoexcept

Advertising is enabled via le_start_adv() or le_enable_adv().

Advertising is active until either disabled via le_enable_adv(false) or a connection has been made.

Returns: true if advertising is active, otherwise false.

Definition at line 443 of file HCIHandler.hpp.

Here is the caller graph for this function:

◆ toString()

std::string HCIHandler::toString ( ) const

noexcept

Definition at line 976 of file HCIHandler.cpp.

Here is the caller graph for this function:

◆ resetAdapter()

HCIStatusCode HCIHandler::resetAdapter ( const PostShutdownFunc & user_post_shutdown )

Complete adapter reset.

The semantics are specific to the HCI host implementation, however, it shall comply at least with the HCI Reset command.

The adapter shall be shutdown into standby first, i.e. POWERED off, then the adapter should be brought up into a POWERED functional state afterwards.

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

Parameters

user_post_shutdown optional custom user function to be executed after successful adapter shutdown. If function is not null and returns false, the adapter will not be brought up again.

Returns: HCIStatusCode

Definition at line 1049 of file HCIHandler.cpp.

Here is the caller graph for this function:

◆ resetAllStates()

bool HCIHandler::resetAllStates ( const bool powered_on )

noexcept

Reset all internal states, i.e.

connection and disconnect lists.

Must be explicitly called with powered_on=true when adapter is powered on!

Parameters

powered_on indicates whether the adapter is powered on or not

See also: initSupCommands(); resetAdapter()

Definition at line 1086 of file HCIHandler.cpp.

Here is the caller graph for this function:

◆ getLocalVersion()

HCIStatusCode HCIHandler::getLocalVersion ( HCILocalVersion & version )

noexcept

Definition at line 1117 of file HCIHandler.cpp.

◆ le_get_local_features()

LE_Features direct_bt::HCIHandler::le_get_local_features ( )

inlinenoexcept

Return previously fetched LE_Features for the controller via initSupCommands() via resetAllStates()

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

BT Core Spec v5.2: Vol 4, Part E, 7.8.3 LE Read Local Supported Features command

Parameters

res	reference for the resulting LE_Features

Returns: HCIStatusCode

See also: initSupCommands(); resetAllStates()

Definition at line 532 of file HCIHandler.hpp.

◆ le_read_remote_features()

HCIStatusCode HCIHandler::le_read_remote_features	(	const uint16_t	conn_handle,
		const BDAddressAndType &	peerAddressAndType
	)

noexcept

Request supported LE_Features from remote device.

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

BT Core Spec v5.2: Vol 4, Part E, 7.8.21 LE Read Remote Features command

Method returns immediate without result.

Result is being delivered off-thread via HCIMetaEventType::LE_REMOTE_FEAT_COMPLETE, see

BT Core Spec v5.2: Vol 4, Part E, 7.7.65.4 LE Read Remote Features Complete event

Returns: HCIStatusCode

Definition at line 932 of file HCIHandler.cpp.

◆ le_enable_scan()

HCIStatusCode HCIHandler::le_enable_scan	(	const bool	enable,
		const bool	filter_dup = `true`
	)

noexcept

Starts or stops LE scanning.

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

if available, otherwise using

BT Core Spec v5.2: Vol 4, Part E HCI: 7.8.11 LE Set Scan Enable command

Parameters

enable	true to enable discovery, otherwise false
filter_dup	true to filter out duplicate AD PDUs (default), otherwise all will be reported.

Definition at line 1195 of file HCIHandler.cpp.

◆ le_start_scan()

HCIStatusCode HCIHandler::le_start_scan	(	const bool	filter_dup = `true`,
		const bool	le_scan_active = `true`,
		const HCILEOwnAddressType	own_mac_type = `HCILEOwnAddressType::PUBLIC`,
		const uint16_t	le_scan_interval = `24`,
		const uint16_t	le_scan_window = `24`,
		const uint8_t	filter_policy = `0x00`
	)

noexcept

Start LE scanning, i.e.

performs le_set_scan_param() and le_enable_scan() in one atomic operation.

BT Core Spec v5.2: Vol 4 HCI, Part E HCI Functional: 7.8.64 LE Set Extended Scan Parameters command (Bluetooth 5.0)
BT Core Spec v5.2: Vol 4 HCI, Part E HCI Functional: 7.8.10 LE Set Scan Parameters command
BT Core Spec v5.2: Vol 4 HCI, Part E HCI Functional: 7.8.65 LE Set Extended Scan Enable command (Bluetooth 5.0)
BT Core Spec v5.2: Vol 4, Part E HCI: 7.8.11 LE Set Scan Enable command

<p<blockquote>‍

Scan parameters control advertising (AD) Protocol Data Unit (PDU) delivery behavior.

Should not be called while LE scanning is active, otherwise HCIStatusCode::COMMAND_DISALLOWED will be returned.

Method will report errors.

Parameters

filter_dup	true to filter out duplicate AD PDUs (default), otherwise all will be reported.
le_scan_active	true enables delivery of active scanning PDUs like EIR w/ device name (default), otherwise no scanning PDUs shall be sent.
own_mac_type	HCILEOwnAddressType::PUBLIC (default) or random/private.
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, ...

See also: le_read_local_features()

Definition at line 1243 of file HCIHandler.cpp.

◆ le_create_conn()

HCIStatusCode HCIHandler::le_create_conn	(	const EUI48 &	peer_bdaddr,
		const HCILEPeerAddressType	peer_mac_type = `HCILEPeerAddressType::PUBLIC`,
		const HCILEOwnAddressType	own_mac_type = `HCILEOwnAddressType::PUBLIC`,
		const uint16_t	le_scan_interval = `24`,
		const uint16_t	le_scan_window = `24`,
		const uint16_t	conn_interval_min = `8`,
		const uint16_t	conn_interval_max = `12`,
		const uint16_t	conn_latency = `0`,
		const uint16_t	supervision_timeout = `getHCIConnSupervisorTimeout(0, 15)`
	)

noexcept

Establish a connection to the given LE peer.

BT Core Spec v5.2: Vol 4, Part E HCI: 7.8.66 LE Extended Create Connection command (Bluetooth 5.0)

if available, otherwise using

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

<p<blockquote>‍

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

The supervising timeout period is the time it takes before a devices gives up on the link if no packets are received. Hence this parameter influences the responsiveness on a link loss. A too small number may render the link too unstable, it should be at least 6 times of the connection interval.
To detect a link loss one can also send a regular ping to check whether the peripheral is still responding, see BTGattHandler::ping().

Implementation tries to mitigate HCIStatusCode::COMMAND_DISALLOWED failure due to any pending connection commands, waiting actively up to HCIEnv::HCI_COMMAND_COMPLETE_REPLY_TIMEOUT, testing every HCIEnv::HCI_COMMAND_POLL_PERIOD if resolved.

In case of no resolution, i.e. another HCI_LE_Create_Connection command is pending, HCIStatusCode::COMMAND_DISALLOWED will be returned by the underlying HCI host implementation.

Implementation tries to mitigate HCIStatusCode::CONNECTION_ALREADY_EXISTS failure due to a specific pending disconnect command, waiting actively up to HCIEnv::HCI_COMMAND_COMPLETE_REPLY_TIMEOUT, testing every HCIEnv::HCI_COMMAND_POLL_PERIOD if resolved.

In case of no resolution, i.e. the connection persists, HCIStatusCode::CONNECTION_ALREADY_EXISTS will be returned by the underlying HCI host implementation.

Parameters

peer_bdaddr
peer_mac_type
own_mac_type
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 8 for 10ms; 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]. See Range of [0 - getHCIMaxConnLatency()].
supervision_timeout	in units of 10ms, default value >= 10 x conn_interval_max; Value range [0xA-0x0C80] for [100ms - 32s]. We use 500ms minimum, i.e. getHCIConnSupervisorTimeout(0, 15, ::HCIConstInt::LE_CONN_MIN_TIMEOUT_MS).

Returns

Definition at line 1276 of file HCIHandler.cpp.

Here is the caller graph for this function:

◆ create_conn()

HCIStatusCode HCIHandler::create_conn	(	const EUI48 &	bdaddr,
		const uint16_t	pkt_type = `HCI_DM1 \| HCI_DM3 \| HCI_DM5 \| HCI_DH1 \| HCI_DH3 \| HCI_DH5`,
		const uint16_t	clock_offset = `0x0000`,
		const uint8_t	role_switch = `0x01`
	)

noexcept

Establish a connection to the given BREDR (non LE).

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

<p<blockquote>‍

Implementation tries to mitigate HCIStatusCode::COMMAND_DISALLOWED failure due to any pending connection commands, waiting actively up to HCIEnv::HCI_COMMAND_COMPLETE_REPLY_TIMEOUT, testing every HCIEnv::HCI_COMMAND_POLL_PERIOD if resolved.

In case of no resolution, i.e. another HCI_Create_Connection command is pending, HCIStatusCode::COMMAND_DISALLOWED will be returned by the underlying HCI host implementation.

Implementation tries to mitigate HCIStatusCode::CONNECTION_ALREADY_EXISTS failure due to a specific pending disconnect command, waiting actively up to HCIEnv::HCI_COMMAND_COMPLETE_REPLY_TIMEOUT, testing every HCIEnv::HCI_COMMAND_POLL_PERIOD if resolved.

In case of no resolution, i.e. the connection persists, HCIStatusCode::CONNECTION_ALREADY_EXISTS will be returned by the underlying HCI host implementation.

Definition at line 1409 of file HCIHandler.cpp.

Here is the caller graph for this function:

◆ disconnect()

HCIStatusCode HCIHandler::disconnect	(	const uint16_t	conn_handle,
		const BDAddressAndType &	peerAddressAndType,
		const HCIStatusCode	reason = `HCIStatusCode::REMOTE_USER_TERMINATED_CONNECTION`
	)

noexcept

Disconnect an established connection.

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

Definition at line 1485 of file HCIHandler.cpp.

Here is the caller graph for this function:

◆ le_add_to_resolv_list()

HCIStatusCode HCIHandler::le_add_to_resolv_list	(	const BDAddressAndType &	peerIdentityAddressAndType,
		jau::uint128dp_t &	peer_irk,
		jau::uint128dp_t &	local_irk
	)

noexcept

BT Core Spec v5.2: Vol 4, Part E HCI: 7.8.38 LE Add Device To Resolving List command.

Definition at line 1510 of file HCIHandler.cpp.

◆ le_del_from_resolv_list()

HCIStatusCode HCIHandler::le_del_from_resolv_list ( const BDAddressAndType & peerIdentityAddressAndType )

noexcept

BT Core Spec v5.2: Vol 4, Part E HCI: 7.8.39 LE Remove Device From Resolving List command.

Definition at line 1528 of file HCIHandler.cpp.

Here is the caller graph for this function:

◆ le_clear_resolv_list()

HCIStatusCode HCIHandler::le_clear_resolv_list ( )

noexcept

BT Core Spec v5.2: Vol 4, Part E HCI: 7.8.40 LE Clear Resolving List command.

Definition at line 1543 of file HCIHandler.cpp.

◆ le_read_resolv_list_size()

HCIStatusCode HCIHandler::le_read_resolv_list_size ( uint32_t & size_res )

noexcept

BT Core Spec v5.2: Vol 4, Part E HCI: 7.8.41 LE Read Resolving List Size command.

Definition at line 1555 of file HCIHandler.cpp.

◆ le_read_peer_resolv_addr()

HCIStatusCode HCIHandler::le_read_peer_resolv_addr	(	const BDAddressAndType &	peerIdentityAddressAndType,
		jau::EUI48 &	peerResolvableAddress
	)

noexcept

BT Core Spec v5.2: Vol 4, Part E HCI: 7.8.42 LE Read Peer Resolvable Address command.

FIXME: May not be supported by Linux/BlueZ

Definition at line 1570 of file HCIHandler.cpp.

◆ le_read_local_resolv_addr()

HCIStatusCode HCIHandler::le_read_local_resolv_addr	(	const BDAddressAndType &	peerIdentityAddressAndType,
		jau::EUI48 &	localResolvableAddress
	)

noexcept

BT Core Spec v5.2: Vol 4, Part E HCI: 7.8.43 LE Read Local Resolvable Address command.

FIXME: May not be supported by Linux/BlueZ

Definition at line 1589 of file HCIHandler.cpp.

◆ le_set_addr_resolv_enable()

HCIStatusCode HCIHandler::le_set_addr_resolv_enable ( const bool enable )

noexcept

BT Core Spec v5.2: Vol 4, Part E HCI: 7.8.44 LE Set Address Resolution Enable command.

Definition at line 1608 of file HCIHandler.cpp.

◆ le_read_phy()

HCIStatusCode HCIHandler::le_read_phy	(	const uint16_t	conn_handle,
		const BDAddressAndType &	peerAddressAndType,
		LE_PHYs &	resTx,
		LE_PHYs &	resRx
	)

noexcept

Request and return LE_PHYs bit for the given connection.

BT Core Spec v5.2: Vol 4, Part E, 7.8.47 LE Read PHY command

Controller shall send a pending HCIMetaEventType::LE_PHY_UPDATE_COMPLETE event with SUCCESS after issuing this command in all cases (change or unchanged PHYs).

Parameters

conn_handle
addressAndType
resTx	reference for the resulting transmitter LE_PHYs bit
resRx	reference for the resulting receiver LE_PHYs bit

Returns: HCIStatusCode

Since: 2.4.0

Definition at line 1622 of file HCIHandler.cpp.

Here is the caller graph for this function:

◆ le_set_default_phy()

HCIStatusCode HCIHandler::le_set_default_phy	(	const LE_PHYs	Tx,
		const LE_PHYs	Rx
	)

noexcept

Sets default preference of used LE_PHYs for all subsequent LE connections.

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

Parameters

Tx	transmitter LE_PHYs bit mask of preference if not set to LE_PHYs::NONE (ignored).
Rx	receiver LE_PHYs bit mask of preference if not set to LE_PHYs::NONE (ignored).

Returns

Since: 2.4.0

Definition at line 1678 of file HCIHandler.cpp.

◆ le_set_phy()

HCIStatusCode HCIHandler::le_set_phy	(	const uint16_t	conn_handle,
		const BDAddressAndType &	peerAddressAndType,
		const LE_PHYs	Tx,
		const LE_PHYs	Rx
	)

noexcept

Sets preference of used LE_PHYs for the given connection.

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

Parameters

conn_handle
peerAddressAndType
Tx	transmitter LE_PHYs bit mask of preference if not set to LE_PHYs::NONE (ignored).
Rx	receiver LE_PHYs bit mask of preference if not set to LE_PHYs::NONE (ignored).

Returns

Since: 2.4.0

Definition at line 1712 of file HCIHandler.cpp.

Here is the caller graph for this function:

◆ le_enable_adv()

HCIStatusCode HCIHandler::le_enable_adv ( const bool enable )

noexcept

Enables or disabled 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 le_enable_adv(false) or a connection has been made, see isAdvertising().

Parameters

enable

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

Since: 2.4.0

Definition at line 1900 of file HCIHandler.cpp.

Here is the caller graph for this function:

◆ le_start_adv()

HCIStatusCode HCIHandler::le_start_adv	(	const EInfoReport &	eir,
		const EIRDataType	adv_mask = `EIRDataType::FLAGS \| EIRDataType::SERVICE_UUID`,
		const EIRDataType	scanrsp_mask = `EIRDataType::NAME \| EIRDataType::CONN_IVAL`,
		const EUI48 &	peer_bdaddr = `EUI48::ANY_DEVICE`,
		const HCILEOwnAddressType	own_mac_type = `HCILEOwnAddressType::PUBLIC`,
		const HCILEOwnAddressType	peer_mac_type = `HCILEOwnAddressType::PUBLIC`,
		const uint16_t	adv_interval_min = `160`,
		const uint16_t	adv_interval_max = `480`,
		const AD_PDU_Type	adv_type = `AD_PDU_Type::ADV_IND`,
		const uint8_t	adv_chan_map = `0x07`,
		const uint8_t	filter_policy = `0x00`
	)

noexcept

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

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

TODO:

Random address for privacy if desired!
Consider SMP (security)

Parameters

eir	Full ADV EIR EInfoReport
adv_mask	EIRDataType mask for EInfoReport to select advertisement EIR PDU data, defaults to EIRDataType::FLAGS \| EIRDataType::SERVICE_UUID
scanrsp_mask	EIRDataType mask for EInfoReport to select scan-response (active scanning) EIR PDU data, defaults to EIRDataType::NAME \| EIRDataType::CONN_IVAL
peer_bdaddr	EUI48 of directed peer, defaults to EUI48::ANY_DEVICE (zero address)
own_mac_type	HCILEOwnAddressType::PUBLIC (default) or random/private.
peer_mac_type	HCILEOwnAddressType::PUBLIC (default) or random/private.
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 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

Since: 2.4.0

Definition at line 1970 of file HCIHandler.cpp.

◆ addMgmtEventCallback()

bool HCIHandler::addMgmtEventCallback	(	const MgmtEvent::Opcode	opc,
		const MgmtEventCallback &	cb
	)

noexcept

MgmtEventCallback handling

Appends the given MgmtEventCallback to the named MgmtEvent::Opcode list, if it is not present already (opcode + callback).

Parameters

opc	opcode index for callback list, the callback shall be added to
cb	the to be added callback

Returns: true if newly added or already existing, false if given MgmtEvent::Opcode is out of supported range.

Definition at line 2197 of file HCIHandler.cpp.

◆ removeMgmtEventCallback()

HCIHandler::size_type HCIHandler::removeMgmtEventCallback	(	const MgmtEvent::Opcode	opc,
		const MgmtEventCallback &	cb
	)

noexcept

Returns count of removed given MgmtEventCallback from the named MgmtEvent::Opcode list.

Definition at line 2206 of file HCIHandler.cpp.

◆ clearMgmtEventCallbacks()

void HCIHandler::clearMgmtEventCallbacks ( const MgmtEvent::Opcode opc )

noexcept

Removes all MgmtEventCallbacks from the to the named MgmtEvent::Opcode list.

Definition at line 2214 of file HCIHandler.cpp.

◆ addSMPMsgCallback()

void HCIHandler::addSMPMsgCallback ( const HCISMPMsgCallback & l )

Definition at line 2236 of file HCIHandler.cpp.

◆ removeSMPMsgCallback()

HCIHandler::size_type HCIHandler::removeSMPMsgCallback ( const HCISMPMsgCallback & l )

Definition at line 2239 of file HCIHandler.cpp.

◆ clearAllCallbacks()

void HCIHandler::clearAllCallbacks ( )

noexcept

Removes all MgmtEventCallbacks from all MgmtEvent::Opcode lists and all SMPSecurityReqCallbacks.

Definition at line 2221 of file HCIHandler.cpp.

Here is the caller graph for this function:

◆ sendMgmtEvent()

void HCIHandler::sendMgmtEvent ( const MgmtEvent & event )

noexcept

Manually send a MgmtEvent to all of its listeners.

Definition at line 588 of file HCIHandler.cpp.

Member Data Documentation

◆ env

const HCIEnv& direct_bt::HCIHandler::env

Definition at line 185 of file HCIHandler.hpp.

The documentation for this class was generated from the following files:

api/direct_bt/HCIHandler.hpp
src/direct_bt/HCIHandler.cpp

Public Types

Public Member Functions

Public Attributes

Detailed Description

Member Typedef Documentation

◆ size_type

◆ HCIConnectionRef

◆ HCIConnectionRefList_t

◆ PostShutdownFunc

Member Enumeration Documentation

◆ DefaultsSizeT

Constructor & Destructor Documentation

◆ HCIHandler() [1/2]

◆ HCIHandler() [2/2]

◆ ~HCIHandler()

Member Function Documentation

◆ setResolvHCIConnectionAddr()

◆ operator=()

◆ close()

◆ getBTMode()

◆ setBTMode()

◆ isOpen()

◆ use_ext_scan()

◆ use_ext_conn()

◆ use_resolv_add()

◆ use_resolv_del()

◆ use_resolv_clear()

◆ use_resolv_size()

◆ use_resolv_readPeerRA()

◆ use_resolv_readLocalRA()

◆ use_resolv_enable()

◆ use_ext_adv()

◆ getCurrentScanType()

◆ setCurrentScanType()

◆ isAdvertising()

◆ toString()

◆ resetAdapter()

◆ resetAllStates()

◆ getLocalVersion()

◆ le_get_local_features()

◆ le_read_remote_features()

◆ le_enable_scan()

◆ le_start_scan()

◆ le_create_conn()

◆ create_conn()

◆ disconnect()

◆ le_add_to_resolv_list()

◆ le_del_from_resolv_list()

◆ le_clear_resolv_list()

◆ le_read_resolv_list_size()

◆ le_read_peer_resolv_addr()

◆ le_read_local_resolv_addr()

◆ le_set_addr_resolv_enable()

◆ le_read_phy()

◆ le_set_default_phy()

◆ le_set_phy()

◆ le_enable_adv()

◆ le_start_adv()

◆ addMgmtEventCallback()

◆ removeMgmtEventCallback()

◆ clearMgmtEventCallbacks()

◆ addSMPMsgCallback()

◆ removeSMPMsgCallback()

◆ clearAllCallbacks()

◆ sendMgmtEvent()

Member Data Documentation

◆ env