Direct-BT
2.3.1
Direct-BT - Direct Bluetooth Programming.
|
A thread safe singleton handler of the HCI control channel to one controller (BT adapter) More...
#include <HCIHandler.hpp>
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 HCIEnv & | env |
Static Public Attributes | |
static const pid_t | pidSelf = getpid() |
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.
Enumerator | |
---|---|
HCI_MAX_MTU |
Definition at line 173 of file HCIHandler.hpp.
|
noexcept |
|
delete |
|
inlinenoexcept |
Releases this instance after issuing close().
Definition at line 365 of file HCIHandler.hpp.
|
noexcept |
MgmtEventCallback handling
Appends the given MgmtEventCallback to the named MgmtEvent::Opcode list, if it is not present already (opcode + callback).
opc | opcode index for callback list, the callback shall be added to |
cb | the to be added callback |
Definition at line 1558 of file HCIHandler.cpp.
void HCIHandler::addSMPMsgCallback | ( | const HCISMPMsgCallback & | l | ) |
|
noexcept |
Removes all MgmtEventCallbacks from all MgmtEvent::Opcode lists and all SMPSecurityReqCallbacks.
Definition at line 1582 of file HCIHandler.cpp.
|
noexcept |
Removes all MgmtEventCallbacks from the to the named MgmtEvent::Opcode list.
Definition at line 1575 of file HCIHandler.cpp.
|
noexcept |
Definition at line 766 of file HCIHandler.cpp.
|
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.
|
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.
|
inlinenoexcept |
Definition at line 369 of file HCIHandler.hpp.
|
inlinenoexcept |
|
noexcept |
|
inlinenoexcept |
Returns true if this mgmt instance is open, connected and hence valid, otherwise false.
Definition at line 374 of file HCIHandler.hpp.
|
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.
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 12 for 15ms; Value range [6 .. 3200] for [7.5ms .. 4000ms] |
conn_interval_max | in units of 1.25ms, default value 12 for 15ms; Value range [6 .. 3200] for [7.5ms .. 4000ms] |
conn_latency | slave latency in units of connection events, default value 0; Value range [0 .. 0x01F3]. |
supervision_timeout | in units of 10ms, default value >= 10 x conn_interval_max, we use HCIConstInt::LE_CONN_MIN_TIMEOUT_MS minimum; Value range [0xA-0x0C80] for [100ms - 32s]. |
Definition at line 1074 of file HCIHandler.cpp.
|
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
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 1001 of file HCIHandler.cpp.
|
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
res | reference for the resulting LE_Features |
Definition at line 927 of file HCIHandler.cpp.
|
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)
conn_handle | |
addressAndType | |
resRx | reference for the resulting receiver LE_PHYs bit |
resTx | reference for the resulting transmitter LE_PHYs bit |
Definition at line 1327 of file HCIHandler.cpp.
|
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.
le_scan_active | true enables delivery of active scanning PDUs, otherwise no scanning PDUs shall be sent (default) |
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, ... |
Definition at line 946 of file HCIHandler.cpp.
|
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.
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, otherwise no scanning PDUs shall be sent (default) |
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, ... |
Definition at line 1045 of file HCIHandler.cpp.
|
delete |
|
noexcept |
Returns count of removed given MgmtEventCallback from the named MgmtEvent::Opcode list.
Definition at line 1567 of file HCIHandler.cpp.
int HCIHandler::removeSMPMsgCallback | ( | const HCISMPMsgCallback & | l | ) |
|
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.
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.
|
noexcept |
Reset all internal states, i.e.
connection and disconnect lists.
powered_on | indicates whether the adapter is powered on or not |
Definition at line 168 of file HCIHandler.cpp.
|
noexcept |
Manually send a MgmtEvent to all of its listeners.
Definition at line 496 of file HCIHandler.cpp.
|
inlinenoexcept |
Definition at line 371 of file HCIHandler.hpp.
|
inlinenoexcept |
HCIStatusCode HCIHandler::startAdapter | ( | ) |
Bring up this adapter into a POWERED functional state.
Definition at line 821 of file HCIHandler.cpp.
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.
|
noexcept |
Definition at line 814 of file HCIHandler.cpp.
|
inlinenoexcept |
Use extended connection if HCI_LE_Extended_Create_Connection is supported (Bluetooth 5.0).
Definition at line 385 of file HCIHandler.hpp.
|
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.
const HCIEnv& direct_bt::HCIHandler::env |
Definition at line 179 of file HCIHandler.hpp.
|
static |
Definition at line 177 of file HCIHandler.hpp.