Direct-BT  2.3.1
Direct-BT - Direct Bluetooth Programming.
Classes | Public Types | Public Member Functions | Public Attributes | Static Public Attributes | List of all members
direct_bt::HCIHandler Class Reference

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) }
 

Public Member Functions

 HCIHandler (const uint16_t dev_id, const BTMode btMode=BTMode::NONE) noexcept
 
 HCIHandler (const HCIHandler &)=delete
 
void operator= (const HCIHandler &)=delete
 
 ~HCIHandler () noexcept
 Releases this instance after issuing close(). More...
 
void close () noexcept
 
BTMode getBTMode () const noexcept
 
void setBTMode (const BTMode mode) noexcept
 
bool isOpen () const noexcept
 Returns true if this mgmt instance is open, connected and hence valid, otherwise false. 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_ext_conn () const noexcept
 Use extended connection if HCI_LE_Extended_Create_Connection is supported (Bluetooth 5.0). More...
 
ScanType getCurrentScanType () const noexcept
 
void setCurrentScanType (const ScanType v) noexcept
 
std::string toString () const noexcept
 
HCIStatusCode startAdapter ()
 Bring up this adapter into a POWERED functional state. More...
 
HCIStatusCode stopAdapter ()
 Bring down this adapter into a non-POWERED non-functional state. More...
 
HCIStatusCode resetAdapter ()
 Reset the adapter. More...
 
HCIStatusCode reset () noexcept
 HCI Reset Command. More...
 
HCIStatusCode getLocalVersion (HCILocalVersion &version) noexcept
 
HCIStatusCode le_read_local_features (LE_Features &res) noexcept
 Request and return LE_Features for the controller. More...
 
HCIStatusCode le_set_scan_param (const bool le_scan_active=false, 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
 Sets LE scanning parameters. More...
 
HCIStatusCode le_enable_scan (const bool enable, const bool filter_dup=true) noexcept
 Starts or stops LE scanning. More...
 
HCIStatusCode le_start_scan (const bool filter_dup=true, const bool le_scan_active=false, 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...
 
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=12, 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 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 &addressAndType, const HCIStatusCode reason=HCIStatusCode::REMOTE_USER_TERMINATED_CONNECTION) noexcept
 Disconnect an established connection. More...
 
HCIStatusCode le_read_phy (const uint16_t conn_handle, const BDAddressAndType &addressAndType, LE_PHYs &resRx, LE_PHYs &resTx) noexcept
 Request and return LE_PHYs bit for the given connection. More...
 
void resetAllStates (const bool powered_on) noexcept
 Reset all internal states, i.e. More...
 
bool addMgmtEventCallback (const MgmtEvent::Opcode opc, const MgmtEventCallback &cb) noexcept
 MgmtEventCallback handling
More...
 
int removeMgmtEventCallback (const MgmtEvent::Opcode opc, const MgmtEventCallback &cb) noexcept
 Returns count of removed given MgmtEventCallback from the named MgmtEvent::Opcode list. More...
 
void clearMgmtEventCallbacks (const MgmtEvent::Opcode opc) noexcept
 Removes all MgmtEventCallbacks from the to the named MgmtEvent::Opcode list. More...
 
void addSMPMsgCallback (const HCISMPMsgCallback &l)
 
int removeSMPMsgCallback (const HCISMPMsgCallback &l)
 
void clearAllCallbacks () noexcept
 Removes all MgmtEventCallbacks from all MgmtEvent::Opcode lists and all SMPSecurityReqCallbacks. More...
 
void sendMgmtEvent (const MgmtEvent &event) noexcept
 Manually send a MgmtEvent to all of its listeners. More...
 

Public Attributes

const HCIEnvenv
 

Static Public Attributes

static const pid_t pidSelf = getpid()
 

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 171 of file HCIHandler.hpp.

Member Enumeration Documentation

◆ DefaultsSizeT

Enumerator
HCI_MAX_MTU 

Definition at line 173 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 592 of file HCIHandler.cpp.

Here is the call graph for this function:

◆ 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 365 of file HCIHandler.hpp.

Here is the call graph for this function:

Member Function Documentation

◆ 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
opcopcode index for callback list, the callback shall be added to
cbthe 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 1558 of file HCIHandler.cpp.

Here is the call graph for this function:

◆ addSMPMsgCallback()

void HCIHandler::addSMPMsgCallback ( const HCISMPMsgCallback l)

Definition at line 1597 of file HCIHandler.cpp.

Here is the call graph for this function:

◆ clearAllCallbacks()

void HCIHandler::clearAllCallbacks ( )
noexcept

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

Definition at line 1582 of file HCIHandler.cpp.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ clearMgmtEventCallbacks()

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

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

Definition at line 1575 of file HCIHandler.cpp.

Here is the call graph for this function:

◆ close()

void HCIHandler::close ( )
noexcept

Definition at line 766 of file HCIHandler.cpp.

Here is the call graph for this function:
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 1203 of file HCIHandler.cpp.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ disconnect()

HCIStatusCode HCIHandler::disconnect ( const uint16_t  conn_handle,
const BDAddressAndType addressAndType,
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 1275 of file HCIHandler.cpp.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ getBTMode()

BTMode direct_bt::HCIHandler::getBTMode ( ) const
inlinenoexcept

Definition at line 369 of file HCIHandler.hpp.

◆ getCurrentScanType()

ScanType direct_bt::HCIHandler::getCurrentScanType ( ) const
inlinenoexcept

Definition at line 389 of file HCIHandler.hpp.

Here is the caller graph for this function:

◆ getLocalVersion()

HCIStatusCode HCIHandler::getLocalVersion ( HCILocalVersion version)
noexcept

Definition at line 904 of file HCIHandler.cpp.

Here is the call graph for this function:

◆ 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 374 of file HCIHandler.hpp.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ 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 = 12,
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_intervalin units of 0.625ms, default value 24 for 15ms; Value range [4 .. 0x4000] for [2.5ms .. 10.24s]
le_scan_windowin 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_minin units of 1.25ms, default value 12 for 15ms; Value range [6 .. 3200] for [7.5ms .. 4000ms]
conn_interval_maxin units of 1.25ms, default value 12 for 15ms; Value range [6 .. 3200] for [7.5ms .. 4000ms]
conn_latencyslave latency in units of connection events, default value 0; Value range [0 .. 0x01F3].
supervision_timeoutin units of 10ms, default value >= 10 x conn_interval_max, we use HCIConstInt::LE_CONN_MIN_TIMEOUT_MS minimum; Value range [0xA-0x0C80] for [100ms - 32s].
Returns

Definition at line 1074 of file HCIHandler.cpp.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ 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
enabletrue to enable discovery, otherwise false
filter_duptrue to filter out duplicate AD PDUs (default), otherwise all will be reported.

Definition at line 1001 of file HCIHandler.cpp.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ le_read_local_features()

HCIStatusCode HCIHandler::le_read_local_features ( LE_Features res)
noexcept

Request and return LE_Features for the controller.

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
resreference for the resulting LE_Features
Returns
HCIStatusCode

Definition at line 927 of file HCIHandler.cpp.

Here is the call graph for this function:

◆ le_read_phy()

HCIStatusCode HCIHandler::le_read_phy ( const uint16_t  conn_handle,
const BDAddressAndType addressAndType,
LE_PHYs resRx,
LE_PHYs resTx 
)
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 (we transfer the sequential value to this bitmask for unification)
Parameters
conn_handle
addressAndType
resRxreference for the resulting receiver LE_PHYs bit
resTxreference for the resulting transmitter LE_PHYs bit
Returns
HCIStatusCode

Definition at line 1327 of file HCIHandler.cpp.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ le_set_scan_param()

HCIStatusCode HCIHandler::le_set_scan_param ( const bool  le_scan_active = false,
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

Sets LE scanning parameters.

BT Core Spec v5.2: Vol 4 HCI, Part E HCI Functional: 7.8.64 LE Set Extended Scan Parameters command (Bluetooth 5.0)
if available, otherwise using
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 6 LE, Part B Link Layer: 4.4.3 Scanning State

<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.

Parameters
le_scan_activetrue enables delivery of active scanning PDUs, otherwise no scanning PDUs shall be sent (default)
own_mac_typeHCILEOwnAddressType::PUBLIC (default) or random/private.
le_scan_intervalin units of 0.625ms, default value 24 for 15ms; Value range [4 .. 0x4000] for [2.5ms .. 10.24s]
le_scan_windowin units of 0.625ms, default value 24 for 15ms; Value range [4 .. 0x4000] for [2.5ms .. 10.24s]. Shall be <= le_scan_interval
filter_policy0x00 accepts all PDUs (default), 0x01 only of whitelisted, ...

Definition at line 946 of file HCIHandler.cpp.

Here is the call graph for this function:

◆ le_start_scan()

HCIStatusCode HCIHandler::le_start_scan ( const bool  filter_dup = true,
const bool  le_scan_active = false,
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_duptrue to filter out duplicate AD PDUs (default), otherwise all will be reported.
le_scan_activetrue enables delivery of active scanning PDUs, otherwise no scanning PDUs shall be sent (default)
own_mac_typeHCILEOwnAddressType::PUBLIC (default) or random/private.
le_scan_intervalin units of 0.625ms, default value 24 for 15ms; Value range [4 .. 0x4000] for [2.5ms .. 10.24s]
le_scan_windowin units of 0.625ms, default value 24 for 15ms; Value range [4 .. 0x4000] for [2.5ms .. 10.24s]. Shall be <= le_scan_interval
filter_policy0x00 accepts all PDUs (default), 0x01 only of whitelisted, ...
See also
le_read_local_features()

Definition at line 1045 of file HCIHandler.cpp.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ operator=()

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

◆ removeMgmtEventCallback()

int 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 1567 of file HCIHandler.cpp.

Here is the call graph for this function:

◆ removeSMPMsgCallback()

int HCIHandler::removeSMPMsgCallback ( const HCISMPMsgCallback l)

Definition at line 1600 of file HCIHandler.cpp.

Here is the call graph for this function:

◆ reset()

HCIStatusCode HCIHandler::reset ( )
noexcept

HCI Reset Command.

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

Definition at line 884 of file HCIHandler.cpp.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ resetAdapter()

HCIStatusCode HCIHandler::resetAdapter ( )

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

Definition at line 868 of file HCIHandler.cpp.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ resetAllStates()

void HCIHandler::resetAllStates ( const bool  powered_on)
noexcept

Reset all internal states, i.e.

connection and disconnect lists.

Parameters
powered_onindicates whether the adapter is powered on or not

Definition at line 168 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 496 of file HCIHandler.cpp.

Here is the call graph for this function:

◆ setBTMode()

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

Definition at line 371 of file HCIHandler.hpp.

◆ setCurrentScanType()

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

Definition at line 390 of file HCIHandler.hpp.

Here is the caller graph for this function:

◆ startAdapter()

HCIStatusCode HCIHandler::startAdapter ( )

Bring up this adapter into a POWERED functional state.

Definition at line 821 of file HCIHandler.cpp.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ stopAdapter()

HCIStatusCode HCIHandler::stopAdapter ( )

Bring down this adapter into a non-POWERED non-functional state.

All allocated resources should be freed and the internal state being reset in compliance to

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

Definition at line 843 of file HCIHandler.cpp.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ toString()

std::string HCIHandler::toString ( ) const
noexcept

Definition at line 814 of file HCIHandler.cpp.

Here is the call graph for this function:
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 385 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 379 of file HCIHandler.hpp.

Here is the caller graph for this function:

Member Data Documentation

◆ env

const HCIEnv& direct_bt::HCIHandler::env

Definition at line 179 of file HCIHandler.hpp.

◆ pidSelf

const pid_t HCIHandler::pidSelf = getpid()
static

Definition at line 177 of file HCIHandler.hpp.


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