feedc0de/esp-nimble-cpp
1
0
Fork 0
forked from h2zero/esp-nimble-cpp
Code Pull Requests Activity

Fix comments for doxygen (#16)

Browse Source 
* Fix comments for doxygen

* Add documentation and update readme.
This commit is contained in:
h2zero
2020-07-08 19:27:26 -06:00
committed by GitHub
parent 64caf3553e
commit aae2a8f1e3
39 changed files with 1384 additions and 686 deletions
Download Patch File Download Diff File Expand all files Collapse all files
src/NimBLEDevice.cpp
+112 -65
View File
@@ -90,6 +90,10 @@ NimBLESecurityCallbacks* NimBLEDevice::m_securityCallbacks = nullptr;
#if defined(CONFIG_BT_NIMBLE_ROLE_BROADCASTER)
/**
* @brief Get the instance of the advertising object.
* @return A pointer to the advertising object.
*/
NimBLEAdvertising* NimBLEDevice::getAdvertising() {
if(m_bleAdvertising == nullptr) {
m_bleAdvertising = new NimBLEAdvertising();
@@ -98,11 +102,17 @@ NimBLEAdvertising* NimBLEDevice::getAdvertising() {
}
/**
* @brief Convenience function to begin advertising.
*/
void NimBLEDevice::startAdvertising() {
getAdvertising()->start();
} // startAdvertising
/**
* @brief Convenience function to stop advertising.
*/
void NimBLEDevice::stopAdvertising() {
getAdvertising()->stop();
} // stopAdvertising
@@ -123,6 +133,7 @@ void NimBLEDevice::stopAdvertising() {
} // getScan
#endif // #if defined(CONFIG_BT_NIMBLE_ROLE_OBSERVER)
/**
* @brief Creates a new client object and maintains a list of all client objects
* each client can connect to 1 peripheral device.
@@ -143,9 +154,9 @@ void NimBLEDevice::stopAdvertising() {
/**
* @brief Delete the client object and remove it from the list.
* Check if it is connected or trying to connect and close/stop it first.
* @param [in] Pointer to the client object.
* @brief Delete the client object and remove it from the list.\n
* Checks if it is connected or trying to connect and disconnects/stops it first.
* @param [in] pClient A pointer to the client object.
*/
/* STATIC */ bool NimBLEDevice::deleteClient(NimBLEClient* pClient) {
if(pClient == nullptr) {
@@ -183,8 +194,8 @@ void NimBLEDevice::stopAdvertising() {
/**
* @brief get the list of clients.
* @return a pointer to the list of clients.
* @brief Get the list of created client objects.
* @return A pointer to the list of clients.
*/
/* STATIC */std::list<NimBLEClient*>* NimBLEDevice::getClientList() {
return &m_cList;
@@ -192,8 +203,8 @@ void NimBLEDevice::stopAdvertising() {
/**
* @brief get the size of the list of clients.
* @return a pointer to the list of clients.
* @brief Get the number of created client objects.
* @return Number of client objects created.
*/
/* STATIC */size_t NimBLEDevice::getClientListSize() {
return m_cList.size();
@@ -202,8 +213,8 @@ void NimBLEDevice::stopAdvertising() {
/**
* @brief Get a reference to a client by connection ID.
* @param [in] The client connection ID to search for.
* @return A reference pointer to the client with the spcified connection ID.
* @param [in] conn_id The client connection ID to search for.
* @return A pointer to the client object with the spcified connection ID.
*/
/* STATIC */NimBLEClient* NimBLEDevice::getClientByID(uint16_t conn_id) {
for(auto it = m_cList.cbegin(); it != m_cList.cend(); ++it) {
@@ -218,8 +229,8 @@ void NimBLEDevice::stopAdvertising() {
/**
* @brief Get a reference to a client by peer address.
* @param [in] a NimBLEAddress of the peer to search for.
* @return A reference pointer to the client with the peer address.
* @param [in] peer_addr The address of the peer to search for.
* @return A pointer to the client object with the peer address.
*/
/* STATIC */NimBLEClient* NimBLEDevice::getClientByPeerAddress(const NimBLEAddress &peer_addr) {
for(auto it = m_cList.cbegin(); it != m_cList.cend(); ++it) {
@@ -233,7 +244,7 @@ void NimBLEDevice::stopAdvertising() {
/**
* @brief Finds the first disconnected client in the list.
* @return A reference pointer to the first client that is not connected to a peer.
* @return A pointer to the first client object that is not connected to a peer.
*/
/* STATIC */NimBLEClient* NimBLEDevice::getDisconnectedClient() {
for(auto it = m_cList.cbegin(); it != m_cList.cend(); ++it) {
@@ -249,16 +260,28 @@ void NimBLEDevice::stopAdvertising() {
/**
* @brief Set the transmission power.
* The power level can be one of:
* * ESP_PWR_LVL_N12 = 0, !< Corresponding to -12dbm
* * ESP_PWR_LVL_N9 = 1, !< Corresponding to -9dbm
* * ESP_PWR_LVL_N6 = 2, !< Corresponding to -6dbm
* * ESP_PWR_LVL_N3 = 3, !< Corresponding to -3dbm
* * ESP_PWR_LVL_N0 = 4, !< Corresponding to 0dbm
* * ESP_PWR_LVL_P3 = 5, !< Corresponding to +3dbm
* * ESP_PWR_LVL_P6 = 6, !< Corresponding to +6dbm
* * ESP_PWR_LVL_P9 = 7, !< Corresponding to +9dbm
* @param [in] powerLevel.
* @param [in] powerLevel The power level to set, can be one of:
* * ESP_PWR_LVL_N12 = 0, Corresponding to -12dbm
* * ESP_PWR_LVL_N9 = 1, Corresponding to -9dbm
* * ESP_PWR_LVL_N6 = 2, Corresponding to -6dbm
* * ESP_PWR_LVL_N3 = 3, Corresponding to -3dbm
* * ESP_PWR_LVL_N0 = 4, Corresponding to 0dbm
* * ESP_PWR_LVL_P3 = 5, Corresponding to +3dbm
* * ESP_PWR_LVL_P6 = 6, Corresponding to +6dbm
* * ESP_PWR_LVL_P9 = 7, Corresponding to +9dbm
* @param [in] powerType The BLE function to set the power level for, can be one of:
* * ESP_BLE_PWR_TYPE_CONN_HDL0 = 0, For connection handle 0
* * ESP_BLE_PWR_TYPE_CONN_HDL1 = 1, For connection handle 1
* * ESP_BLE_PWR_TYPE_CONN_HDL2 = 2, For connection handle 2
* * ESP_BLE_PWR_TYPE_CONN_HDL3 = 3, For connection handle 3
* * ESP_BLE_PWR_TYPE_CONN_HDL4 = 4, For connection handle 4
* * ESP_BLE_PWR_TYPE_CONN_HDL5 = 5, For connection handle 5
* * ESP_BLE_PWR_TYPE_CONN_HDL6 = 6, For connection handle 6
* * ESP_BLE_PWR_TYPE_CONN_HDL7 = 7, For connection handle 7
* * ESP_BLE_PWR_TYPE_CONN_HDL8 = 8, For connection handle 8
* * ESP_BLE_PWR_TYPE_ADV = 9, For advertising
* * ESP_BLE_PWR_TYPE_SCAN = 10, For scan
* * ESP_BLE_PWR_TYPE_DEFAULT = 11, For default, if not set other, it will use default value
*/
/* STATIC */ void NimBLEDevice::setPower(esp_power_level_t powerLevel, esp_ble_power_type_t powerType) {
NIMBLE_LOGD(LOG_TAG, ">> setPower: %d (type: %d)", powerLevel, powerType);
@@ -270,6 +293,24 @@ void NimBLEDevice::stopAdvertising() {
} // setPower
/**
* @brief Set the transmission power.
* @param [in] powerType The power level to set, can be one of:
* * ESP_BLE_PWR_TYPE_CONN_HDL0 = 0, For connection handle 0
* * ESP_BLE_PWR_TYPE_CONN_HDL1 = 1, For connection handle 1
* * ESP_BLE_PWR_TYPE_CONN_HDL2 = 2, For connection handle 2
* * ESP_BLE_PWR_TYPE_CONN_HDL3 = 3, For connection handle 3
* * ESP_BLE_PWR_TYPE_CONN_HDL4 = 4, For connection handle 4
* * ESP_BLE_PWR_TYPE_CONN_HDL5 = 5, For connection handle 5
* * ESP_BLE_PWR_TYPE_CONN_HDL6 = 6, For connection handle 6
* * ESP_BLE_PWR_TYPE_CONN_HDL7 = 7, For connection handle 7
* * ESP_BLE_PWR_TYPE_CONN_HDL8 = 8, For connection handle 8
* * ESP_BLE_PWR_TYPE_ADV = 9, For advertising
* * ESP_BLE_PWR_TYPE_SCAN = 10, For scan
* * ESP_BLE_PWR_TYPE_DEFAULT = 11, For default, if not set other, it will use default value
* @return the power level currently used by the type specified.
*/
/* STATIC */ int NimBLEDevice::getPower(esp_ble_power_type_t powerType) {
switch(esp_ble_tx_power_get(powerType)) {
@@ -302,7 +343,6 @@ void NimBLEDevice::stopAdvertising() {
*/
/* STATIC*/ NimBLEAddress NimBLEDevice::getAddress() {
ble_addr_t addr = {BLE_ADDR_PUBLIC, 0};
//ble_hs_id_copy_addr(BLE_ADDR_PUBLIC, addr.val, NULL)
if(BLE_HS_ENOADDR == ble_hs_id_copy_addr(BLE_ADDR_PUBLIC, addr.val, NULL)) {
NIMBLE_LOGD(LOG_TAG, "Public address not found, checking random");
@@ -324,9 +364,9 @@ void NimBLEDevice::stopAdvertising() {
/**
* @brief Setup local mtu that will be used to negotiate mtu during request from client peer
* @param [in] mtu Value to set local mtu, should be larger than 23 and lower or equal to
* BLE_ATT_MTU_MAX = 527
* @brief Setup local mtu that will be used to negotiate mtu during request from client peer.
* @param [in] mtu Value to set local mtu:
* * This should be larger than 23 and lower or equal to BLE_ATT_MTU_MAX = 527.
*/
/* STATIC */int NimBLEDevice::setMTU(uint16_t mtu) {
NIMBLE_LOGD(LOG_TAG, ">> setLocalMTU: %d", mtu);
@@ -344,6 +384,7 @@ void NimBLEDevice::stopAdvertising() {
/**
* @brief Get local MTU value set.
* @return The current preferred MTU setting.
*/
/* STATIC */uint16_t NimBLEDevice::getMTU() {
return ble_att_preferred_mtu();
@@ -352,6 +393,7 @@ void NimBLEDevice::stopAdvertising() {
/**
* @brief Host reset, we pass the message so we don't make calls until resynced.
* @param [in] reason The reason code for the reset.
*/
/* STATIC */ void NimBLEDevice::onReset(int reason)
{
@@ -389,7 +431,7 @@ void NimBLEDevice::stopAdvertising() {
/**
* @brief Host resynced with controller, all clear to make calls.
* @brief Host resynced with controller, all clear to make calls to the stack.
*/
/* STATIC */ void NimBLEDevice::onSync(void)
{
@@ -439,7 +481,7 @@ void NimBLEDevice::stopAdvertising() {
/**
* @brief Initialize the %BLE environment.
* @param deviceName The device name of the device.
* @param [in] deviceName The device name of the device.
*/
/* STATIC */ void NimBLEDevice::init(const std::string &deviceName) {
if(!initialized){
@@ -516,6 +558,7 @@ void NimBLEDevice::stopAdvertising() {
/**
* @brief Check if the initialization is complete.
* @return true if initialized.
*/
bool NimBLEDevice::getInitialized() {
return initialized;
@@ -524,9 +567,9 @@ bool NimBLEDevice::getInitialized() {
/**
* @brief Set the authorization mode for this device.
* @param bonding, if true we allow bonding, false no bonding will be performed.
* @param mitm, if true we are capable of man in the middle protection, false if not.
* @param sc, if true we will perform secure connection pairing, false we will use legacy pairing.
* @param bonding If true we allow bonding, false no bonding will be performed.
* @param mitm If true we are capable of man in the middle protection, false if not.
* @param sc If true we will perform secure connection pairing, false we will use legacy pairing.
*/
/*STATIC*/ void NimBLEDevice::setSecurityAuth(bool bonding, bool mitm, bool sc) {
NIMBLE_LOGD(LOG_TAG, "Setting bonding: %d, mitm: %d, sc: %d",bonding,mitm,sc);
@@ -538,13 +581,12 @@ bool NimBLEDevice::getInitialized() {
/**
* @brief Set the authorization mode for this device.
* @param A bitmap indicating what modes are supported.
* The bits are defined as follows:
** 0x01 BLE_SM_PAIR_AUTHREQ_BOND
** 0x04 BLE_SM_PAIR_AUTHREQ_MITM
** 0x08 BLE_SM_PAIR_AUTHREQ_SC
** 0x10 BLE_SM_PAIR_AUTHREQ_KEYPRESS - not yet supported.
** 0xe2 BLE_SM_PAIR_AUTHREQ_RESERVED - for reference only.
* @param auth_req A bitmap indicating what modes are supported.\n
* The available bits are defined as:
* * 0x01 BLE_SM_PAIR_AUTHREQ_BOND
* * 0x04 BLE_SM_PAIR_AUTHREQ_MITM
* * 0x08 BLE_SM_PAIR_AUTHREQ_SC
* * 0x10 BLE_SM_PAIR_AUTHREQ_KEYPRESS - not yet supported.
*/
/*STATIC*/void NimBLEDevice::setSecurityAuth(uint8_t auth_req) {
NimBLEDevice::setSecurityAuth((auth_req & BLE_SM_PAIR_AUTHREQ_BOND)>0,
@@ -555,12 +597,12 @@ bool NimBLEDevice::getInitialized() {
/**
* @brief Set the Input/Output capabilities of this device.
* @param One of the following:
** 0x00 BLE_HS_IO_DISPLAY_ONLY DisplayOnly IO capability
** 0x01 BLE_HS_IO_DISPLAY_YESNO DisplayYesNo IO capability
** 0x02 BLE_HS_IO_KEYBOARD_ONLY KeyboardOnly IO capability
** 0x03 BLE_HS_IO_NO_INPUT_OUTPUT NoInputNoOutput IO capability
** 0x04 BLE_HS_IO_KEYBOARD_DISPLAY KeyboardDisplay Only IO capability
* @param iocap One of the following values:
* * 0x00 BLE_HS_IO_DISPLAY_ONLY DisplayOnly IO capability
* * 0x01 BLE_HS_IO_DISPLAY_YESNO DisplayYesNo IO capability
* * 0x02 BLE_HS_IO_KEYBOARD_ONLY KeyboardOnly IO capability
* * 0x03 BLE_HS_IO_NO_INPUT_OUTPUT NoInputNoOutput IO capability
* * 0x04 BLE_HS_IO_KEYBOARD_DISPLAY KeyboardDisplay Only IO capability
*/
/*STATIC*/ void NimBLEDevice::setSecurityIOCap(uint8_t iocap) {
ble_hs_cfg.sm_io_cap = iocap;
@@ -569,12 +611,12 @@ bool NimBLEDevice::getInitialized() {
/**
* @brief If we are the initiator of the security procedure this sets the keys we will distribute.
* @param A bitmap indicating which keys to distribute during pairing.
* The bits are defined as follows:
** 0x01: BLE_SM_PAIR_KEY_DIST_ENC - Distribute the encryption key.
** 0x02: BLE_SM_PAIR_KEY_DIST_ID - Distribute the ID key (IRK).
** 0x04: BLE_SM_PAIR_KEY_DIST_SIGN
** 0x08: BLE_SM_PAIR_KEY_DIST_LINK
* @param init_key A bitmap indicating which keys to distribute during pairing.\n
* The available bits are defined as:
* * 0x01: BLE_SM_PAIR_KEY_DIST_ENC - Distribute the encryption key.
* * 0x02: BLE_SM_PAIR_KEY_DIST_ID - Distribute the ID key (IRK).
* * 0x04: BLE_SM_PAIR_KEY_DIST_SIGN
* * 0x08: BLE_SM_PAIR_KEY_DIST_LINK
*/
/*STATIC*/void NimBLEDevice::setSecurityInitKey(uint8_t init_key) {
ble_hs_cfg.sm_our_key_dist = init_key;
@@ -583,20 +625,21 @@ bool NimBLEDevice::getInitialized() {
/**
* @brief Set the keys we are willing to accept during pairing.
* @param A bitmap indicating which keys to accept during pairing.
* The bits are defined as follows:
** 0x01: BLE_SM_PAIR_KEY_DIST_ENC - Accept the encryption key.
** 0x02: BLE_SM_PAIR_KEY_DIST_ID - Accept the ID key (IRK).
** 0x04: BLE_SM_PAIR_KEY_DIST_SIGN
** 0x08: BLE_SM_PAIR_KEY_DIST_LINK
* @param resp_key A bitmap indicating which keys to accept during pairing.
* The available bits are defined as:
* * 0x01: BLE_SM_PAIR_KEY_DIST_ENC - Accept the encryption key.
* * 0x02: BLE_SM_PAIR_KEY_DIST_ID - Accept the ID key (IRK).
* * 0x04: BLE_SM_PAIR_KEY_DIST_SIGN
* * 0x08: BLE_SM_PAIR_KEY_DIST_LINK
*/
/*STATIC*/void NimBLEDevice::setSecurityRespKey(uint8_t init_key) {
ble_hs_cfg.sm_their_key_dist = init_key;
/*STATIC*/void NimBLEDevice::setSecurityRespKey(uint8_t resp_key) {
ble_hs_cfg.sm_their_key_dist = resp_key;
} // setsSecurityRespKey
/**
* @brief Set the passkey for pairing.
* @brief Set the passkey the server will ask for when pairing.
* @param [in] pin The passkey to use.
*/
/*STATIC*/void NimBLEDevice::setSecurityPasskey(uint32_t pin) {
m_passkey = pin;
@@ -604,7 +647,8 @@ bool NimBLEDevice::getInitialized() {
/**
* @brief Get the passkey for pairing.
* @brief Get the current passkey used for pairing.
* @return The current passkey.
*/
/*STATIC*/uint32_t NimBLEDevice::getSecurityPasskey() {
return m_passkey;
@@ -613,7 +657,8 @@ bool NimBLEDevice::getInitialized() {
/**
* @brief Set callbacks that will be used to handle encryption negotiation events and authentication events
* @param [in] cllbacks Pointer to NimBLESecurityCallbacks class
* @param [in] callbacks Pointer to NimBLESecurityCallbacks class
* @deprecated For backward compatibility, New code should use client/server callback methods.
*/
void NimBLEDevice::setSecurityCallbacks(NimBLESecurityCallbacks* callbacks) {
NimBLEDevice::m_securityCallbacks = callbacks;
@@ -622,8 +667,8 @@ void NimBLEDevice::setSecurityCallbacks(NimBLESecurityCallbacks* callbacks) {
/**
* @brief Start the connection securing and authorization for this connection.
* @param Connection id of the client.
* @returns host return code 0 if success.
* @param conn_id The connection id of the peer device.
* @returns NimBLE stack return code, 0 = success.
*/
/* STATIC */int NimBLEDevice::startSecurity(uint16_t conn_id) {
/* if(m_securityCallbacks != nullptr) {
@@ -641,6 +686,7 @@ void NimBLEDevice::setSecurityCallbacks(NimBLESecurityCallbacks* callbacks) {
/**
* @brief Check if the device address is on our ignore list.
* @param [in] address The address to look for.
* @return True if ignoring.
*/
/*STATIC*/ bool NimBLEDevice::isIgnored(const NimBLEAddress &address) {
@@ -656,7 +702,7 @@ void NimBLEDevice::setSecurityCallbacks(NimBLESecurityCallbacks* callbacks) {
/**
* @brief Add a device to the ignore list.
* @param Address of the device we want to ignore.
* @param [in] address The address of the device we want to ignore.
*/
/*STATIC*/ void NimBLEDevice::addIgnored(const NimBLEAddress &address) {
m_ignoreList.push_back(address);
@@ -665,7 +711,7 @@ void NimBLEDevice::setSecurityCallbacks(NimBLESecurityCallbacks* callbacks) {
/**
* @brief Remove a device from the ignore list.
* @param Address of the device we want to remove from the list.
* @param [in] address The address of the device we want to remove from the list.
*/
/*STATIC*/void NimBLEDevice::removeIgnored(const NimBLEAddress &address) {
for(auto it = m_ignoreList.begin(); it != m_ignoreList.end(); ++it) {
@@ -679,6 +725,7 @@ void NimBLEDevice::setSecurityCallbacks(NimBLESecurityCallbacks* callbacks) {
/**
* @brief Set a custom callback for gap events.
* @param [in] handler The function to call when gap events occur.
*/
void NimBLEDevice::setCustomGapHandler(gap_event_handler handler) {
m_customGapHandler = handler;