ScStw/esp-nimble-cpp
2
0
Fork 0
mirror of https://github.com/h2zero/esp-nimble-cpp.git synced 2024-12-18 17:20:47 +01:00
Code Issues Projects Releases Packages Wiki Activity
esp-nimble-cpp/src/NimBLEClient.h

214 lines
8.5 KiB
C
Raw Normal View History

Initial commit.
2020-03-30 01:44:20 +02:00
/*
* NimBLEClient.h
*
* Created: on Jan 26 2020
* Author H2zero
Conditionally compile code for specific roles. This allows NimBLE options in menuconfig to reduce code size based on the roles selected (scan/advertising/central/peripheral). Significant code space can be saved by removing unnecessary roles for the application.
2020-05-14 06:03:56 +02:00
*
Initial commit.
2020-03-30 01:44:20 +02:00
* Originally:
* BLEClient.h
*
* Created on: Mar 22, 2017
* Author: kolban
*/
[BREAKING]- Refactor client * General code cleanup and rename variables to use a consistent style. * Removes the disconnect timer and will use the BLE_GAP_EVENT_TERM_FAILURE event to handle failed disconnects. * `NimBLEClient::getConnId` has been renamed to `getConnHandle` to be consistent with bluetooth terminology. * `NimBLEClient::disconnect` now returns a `bool = true on success` instead of an int to be consistent with the rest of the library. * `NimBLEClient::setPeerAddress` now returns a bool, true on success. * `NimBLEClientCallbacks::onConfirmPIN` renamed to `NimBLEClientCallbacks::onConfirmPasskey` to be consistent with bluetooth terminology. * `NimBLEClient::setDataLen` now returns bool, true if successful. * `NimBLEClient::updateConnParams` now returns bool, true if successful. * `NimBLEClient::getServices` now returns a const reference to std::vector<NimBLERemoteService*> instead of a pointer to the internal vector.
2024-11-03 02:00:07 +01:00
#ifndef NIMBLE_CPP_CLIENT_H_
#define NIMBLE_CPP_CLIENT_H_
Initial commit.
2020-03-30 01:44:20 +02:00
Conditionally compile code for specific roles. This allows NimBLE options in menuconfig to reduce code size based on the roles selected (scan/advertising/central/peripheral). Significant code space can be saved by removing unnecessary roles for the application.
2020-05-14 06:03:56 +02:00
#include "nimconfig.h"
Refactor include directives to use different paths for arduino/idf. * Sets macros to allow compiling when Central role is enabled and Observer disabled, or Peripheral enabled and Broadcaster disabled. * Adds a macro definition for CONFIG_NIMBLE_CPP_IDF to enable different include paths/functionality for IDF / Arduino.
2021-09-07 05:14:43 +02:00
#if defined(CONFIG_BT_ENABLED) && defined(CONFIG_BT_NIMBLE_ROLE_CENTRAL)
Initial commit.
2020-03-30 01:44:20 +02:00
[BREAKING]- Refactor client * General code cleanup and rename variables to use a consistent style. * Removes the disconnect timer and will use the BLE_GAP_EVENT_TERM_FAILURE event to handle failed disconnects. * `NimBLEClient::getConnId` has been renamed to `getConnHandle` to be consistent with bluetooth terminology. * `NimBLEClient::disconnect` now returns a `bool = true on success` instead of an int to be consistent with the rest of the library. * `NimBLEClient::setPeerAddress` now returns a bool, true on success. * `NimBLEClientCallbacks::onConfirmPIN` renamed to `NimBLEClientCallbacks::onConfirmPasskey` to be consistent with bluetooth terminology. * `NimBLEClient::setDataLen` now returns bool, true if successful. * `NimBLEClient::updateConnParams` now returns bool, true if successful. * `NimBLEClient::getServices` now returns a const reference to std::vector<NimBLERemoteService*> instead of a pointer to the internal vector.
2024-11-03 02:00:07 +01:00
# if defined(CONFIG_NIMBLE_CPP_IDF)
# include "host/ble_gap.h"
# else
# include "nimble/nimble/host/include/host/ble_gap.h"
# endif
Initial commit.
2020-03-30 01:44:20 +02:00
[BREAKING]- Refactor client * General code cleanup and rename variables to use a consistent style. * Removes the disconnect timer and will use the BLE_GAP_EVENT_TERM_FAILURE event to handle failed disconnects. * `NimBLEClient::getConnId` has been renamed to `getConnHandle` to be consistent with bluetooth terminology. * `NimBLEClient::disconnect` now returns a `bool = true on success` instead of an int to be consistent with the rest of the library. * `NimBLEClient::setPeerAddress` now returns a bool, true on success. * `NimBLEClientCallbacks::onConfirmPIN` renamed to `NimBLEClientCallbacks::onConfirmPasskey` to be consistent with bluetooth terminology. * `NimBLEClient::setDataLen` now returns bool, true if successful. * `NimBLEClient::updateConnParams` now returns bool, true if successful. * `NimBLEClient::getServices` now returns a const reference to std::vector<NimBLERemoteService*> instead of a pointer to the internal vector.
2024-11-03 02:00:07 +01:00
# include "NimBLEAddress.h"
Initial commit.
2020-03-30 01:44:20 +02:00
[BREAKING]- Refactor client * General code cleanup and rename variables to use a consistent style. * Removes the disconnect timer and will use the BLE_GAP_EVENT_TERM_FAILURE event to handle failed disconnects. * `NimBLEClient::getConnId` has been renamed to `getConnHandle` to be consistent with bluetooth terminology. * `NimBLEClient::disconnect` now returns a `bool = true on success` instead of an int to be consistent with the rest of the library. * `NimBLEClient::setPeerAddress` now returns a bool, true on success. * `NimBLEClientCallbacks::onConfirmPIN` renamed to `NimBLEClientCallbacks::onConfirmPasskey` to be consistent with bluetooth terminology. * `NimBLEClient::setDataLen` now returns bool, true if successful. * `NimBLEClient::updateConnParams` now returns bool, true if successful. * `NimBLEClient::getServices` now returns a const reference to std::vector<NimBLERemoteService*> instead of a pointer to the internal vector.
2024-11-03 02:00:07 +01:00
# include <stdint.h>
# include <vector>
# include <string>
class NimBLEAddress;
class NimBLEUUID;
Initial commit.
2020-03-30 01:44:20 +02:00
class NimBLERemoteService;
NimBLEClient/ Add getCharacteristic() by handle. * Add getCharacteristic() by handle. Add a convenience method for getting a characteristic by the 16-bit handle.
2020-09-16 06:09:30 +02:00
class NimBLERemoteCharacteristic;
Initial commit.
2020-03-30 01:44:20 +02:00
class NimBLEAdvertisedDevice;
[BREAKING]- Refactor client * General code cleanup and rename variables to use a consistent style. * Removes the disconnect timer and will use the BLE_GAP_EVENT_TERM_FAILURE event to handle failed disconnects. * `NimBLEClient::getConnId` has been renamed to `getConnHandle` to be consistent with bluetooth terminology. * `NimBLEClient::disconnect` now returns a `bool = true on success` instead of an int to be consistent with the rest of the library. * `NimBLEClient::setPeerAddress` now returns a bool, true on success. * `NimBLEClientCallbacks::onConfirmPIN` renamed to `NimBLEClientCallbacks::onConfirmPasskey` to be consistent with bluetooth terminology. * `NimBLEClient::setDataLen` now returns bool, true if successful. * `NimBLEClient::updateConnParams` now returns bool, true if successful. * `NimBLEClient::getServices` now returns a const reference to std::vector<NimBLERemoteService*> instead of a pointer to the internal vector.
2024-11-03 02:00:07 +01:00
class NimBLEAttValue;
[BREAKING] Refactor attributes Refactor attributes to reduce code duplication and improve maintainability. * Add attribute base classes to provide common code. * Add const where possible to functions and parameters. * `NimBLECharacteristic::notify` no longer takes a `bool is_notification` parameter, instead `indicate()` should be called to send indications. * `NimBLECharacteristic::indicate` now takes the same parameters as `notify`. * `NimBLECharacteristicCallbacks` and `NimBLEDescriptorCallbacks` methods now take `const NimBLEConnInfo&` instead of non-const. * `NimBLECharacteristic::onNotify` callback removed as unnecessary, the library does not call notify without app input. * `NimBLERemoteCharacteristic::getRemoteService` now returns a `const NimBLERemoteService*` instead of non-const. * Add NimBLEUUID constructor that takes a reference to `ble_uuid_any_t`. * `NimBLERemoteService::getCharacteristics` now returns a `const std::vector<NimBLERemoteCharacteristic*>&` instead of non-const `std::vector<NimBLERemoteCharacteristic*>*` * `NimBLERemoteService::getValue` now returns `NimBLEAttValue` instead of `std::string` * `NimBLEService::getCharacteristics` now returns a `const std::vector<NimBLECharacteristic*>&` instead of a copy of std::vector<NimBLECharacteristic *>. * Remove const requirement for NimBLEConnInfo parameter in callbacks. Const is unnecessary as the data can't be changed by application code. * Change NimBLERemoteCharacteristic::getRemoteService to return const pointer.
2024-07-26 22:47:36 +02:00
class NimBLEClientCallbacks;
[BREAKING]- Refactor client * General code cleanup and rename variables to use a consistent style. * Removes the disconnect timer and will use the BLE_GAP_EVENT_TERM_FAILURE event to handle failed disconnects. * `NimBLEClient::getConnId` has been renamed to `getConnHandle` to be consistent with bluetooth terminology. * `NimBLEClient::disconnect` now returns a `bool = true on success` instead of an int to be consistent with the rest of the library. * `NimBLEClient::setPeerAddress` now returns a bool, true on success. * `NimBLEClientCallbacks::onConfirmPIN` renamed to `NimBLEClientCallbacks::onConfirmPasskey` to be consistent with bluetooth terminology. * `NimBLEClient::setDataLen` now returns bool, true if successful. * `NimBLEClient::updateConnParams` now returns bool, true if successful. * `NimBLEClient::getServices` now returns a const reference to std::vector<NimBLERemoteService*> instead of a pointer to the internal vector.
2024-11-03 02:00:07 +01:00
class NimBLEConnInfo;
[BREAKING] - Refactor NimBLEUtils * Add functions `NimBLEUtils::taskWait` and `NimBLEUtils::taskRelease` to simplify task blocking/messaging. * `NimBLEUtils::buildHexData` replaced with `NimBLEUtils::dataToHexString` * Add missing GAP event strings. * Add missing return code strings. * `NimBLEUtils::dumpGapEvent` function removed. * Event/error code strings optimized.
2024-11-10 21:31:37 +01:00
struct NimBLETaskData;
Initial commit.
2020-03-30 01:44:20 +02:00
/**
[BREAKING]- Refactor client * General code cleanup and rename variables to use a consistent style. * Removes the disconnect timer and will use the BLE_GAP_EVENT_TERM_FAILURE event to handle failed disconnects. * `NimBLEClient::getConnId` has been renamed to `getConnHandle` to be consistent with bluetooth terminology. * `NimBLEClient::disconnect` now returns a `bool = true on success` instead of an int to be consistent with the rest of the library. * `NimBLEClient::setPeerAddress` now returns a bool, true on success. * `NimBLEClientCallbacks::onConfirmPIN` renamed to `NimBLEClientCallbacks::onConfirmPasskey` to be consistent with bluetooth terminology. * `NimBLEClient::setDataLen` now returns bool, true if successful. * `NimBLEClient::updateConnParams` now returns bool, true if successful. * `NimBLEClient::getServices` now returns a const reference to std::vector<NimBLERemoteService*> instead of a pointer to the internal vector.
2024-11-03 02:00:07 +01:00
* @brief A model of a BLE client.
Initial commit.
2020-03-30 01:44:20 +02:00
*/
class NimBLEClient {
[BREAKING]- Refactor client * General code cleanup and rename variables to use a consistent style. * Removes the disconnect timer and will use the BLE_GAP_EVENT_TERM_FAILURE event to handle failed disconnects. * `NimBLEClient::getConnId` has been renamed to `getConnHandle` to be consistent with bluetooth terminology. * `NimBLEClient::disconnect` now returns a `bool = true on success` instead of an int to be consistent with the rest of the library. * `NimBLEClient::setPeerAddress` now returns a bool, true on success. * `NimBLEClientCallbacks::onConfirmPIN` renamed to `NimBLEClientCallbacks::onConfirmPasskey` to be consistent with bluetooth terminology. * `NimBLEClient::setDataLen` now returns bool, true if successful. * `NimBLEClient::updateConnParams` now returns bool, true if successful. * `NimBLEClient::getServices` now returns a const reference to std::vector<NimBLERemoteService*> instead of a pointer to the internal vector.
2024-11-03 02:00:07 +01:00
public:
Add const to NimBLEAdvertisedDevice* in NimBLEClient::connect overload Fixes an issue where the wrong connect overload is called if the NimBLEAdvertisedDevice* passed is const.
2024-11-25 00:17:01 +01:00
bool connect(const NimBLEAdvertisedDevice* device,
bool deleteAttributes = true,
bool asyncConnect = false,
bool exchangeMTU = true);
Add asyncronous client connect and MTU exchange. * Adds parameters `asyncConnect` and `exchangeMTU` to `NimBLEClient::connect`, default values work as the original connect method. * * `asyncConnect`; if true, will send the connect command and return immediately with a true value for successfully sending the command, else false. * * `exchangeMTU`; if true will send the exchange MTU command upon connection, otherwise not and the application can choose to do this later via the `exchangeMTU` method. * Adds `onMTUChange` callback to `NimBLEClientCallbacks` * Add `NimBLEDevice::getConnectedClients()` which returns a vector of pointers to the currently connected client instances. * Calling `NimBLEClient::connect` will no longer cancel already in progress connections.
2024-10-29 20:50:12 +01:00
bool connect(const NimBLEAddress& address, bool deleteAttributes = true, bool asyncConnect = false, bool exchangeMTU = true);
bool connect(bool deleteAttributes = true, bool asyncConnect = false, bool exchangeMTU = true);
[BREAKING]- Refactor client * General code cleanup and rename variables to use a consistent style. * Removes the disconnect timer and will use the BLE_GAP_EVENT_TERM_FAILURE event to handle failed disconnects. * `NimBLEClient::getConnId` has been renamed to `getConnHandle` to be consistent with bluetooth terminology. * `NimBLEClient::disconnect` now returns a `bool = true on success` instead of an int to be consistent with the rest of the library. * `NimBLEClient::setPeerAddress` now returns a bool, true on success. * `NimBLEClientCallbacks::onConfirmPIN` renamed to `NimBLEClientCallbacks::onConfirmPasskey` to be consistent with bluetooth terminology. * `NimBLEClient::setDataLen` now returns bool, true if successful. * `NimBLEClient::updateConnParams` now returns bool, true if successful. * `NimBLEClient::getServices` now returns a const reference to std::vector<NimBLERemoteService*> instead of a pointer to the internal vector.
2024-11-03 02:00:07 +01:00
bool disconnect(uint8_t reason = BLE_ERR_REM_USER_CONN_TERM);
Refactor client connection establishment and client deletion. * Removes the connection established flag as it should not be necessary. * Deleting the client instance from the `onDisconnect` callback is now supported. * `NimBLEDevice::deleteClient` no longer blocks tasks * Adds a new `Config` struct to `NimBLEClient` to efficiently set single bit config settings. * Adds `NimBLEClient::setSelfDelete` that takes the bool parameters `deleteOnDisconnect` and `deleteOnConnectFail` This will configure the client to delete itself when disconnected or the connection attempt fails. * Adds `NimBLEClient::setConfig` and `NimBLEClient::getConfig` which takes or returns a `NimBLEClient::Config` object respectively. * Reword `BLE_HS_EAPP` error string to be more accurate.
2024-11-14 23:55:09 +01:00
bool cancelConnect() const;
void setSelfDelete(bool deleteOnDisconnect, bool deleteOnConnectFail);
[BREAKING]- Refactor client * General code cleanup and rename variables to use a consistent style. * Removes the disconnect timer and will use the BLE_GAP_EVENT_TERM_FAILURE event to handle failed disconnects. * `NimBLEClient::getConnId` has been renamed to `getConnHandle` to be consistent with bluetooth terminology. * `NimBLEClient::disconnect` now returns a `bool = true on success` instead of an int to be consistent with the rest of the library. * `NimBLEClient::setPeerAddress` now returns a bool, true on success. * `NimBLEClientCallbacks::onConfirmPIN` renamed to `NimBLEClientCallbacks::onConfirmPasskey` to be consistent with bluetooth terminology. * `NimBLEClient::setDataLen` now returns bool, true if successful. * `NimBLEClient::updateConnParams` now returns bool, true if successful. * `NimBLEClient::getServices` now returns a const reference to std::vector<NimBLERemoteService*> instead of a pointer to the internal vector.
2024-11-03 02:00:07 +01:00
NimBLEAddress getPeerAddress() const;
bool setPeerAddress(const NimBLEAddress& address);
int getRssi() const;
bool isConnected() const;
void setClientCallbacks(NimBLEClientCallbacks* pClientCallbacks, bool deleteCallbacks = true);
std::string toString() const;
uint16_t getConnHandle() const;
void clearConnection();
bool setConnection(const NimBLEConnInfo& connInfo);
bool setConnection(uint16_t connHandle);
uint16_t getMTU() const;
Add asyncronous client connect and MTU exchange. * Adds parameters `asyncConnect` and `exchangeMTU` to `NimBLEClient::connect`, default values work as the original connect method. * * `asyncConnect`; if true, will send the connect command and return immediately with a true value for successfully sending the command, else false. * * `exchangeMTU`; if true will send the exchange MTU command upon connection, otherwise not and the application can choose to do this later via the `exchangeMTU` method. * Adds `onMTUChange` callback to `NimBLEClientCallbacks` * Add `NimBLEDevice::getConnectedClients()` which returns a vector of pointers to the currently connected client instances. * Calling `NimBLEClient::connect` will no longer cancel already in progress connections.
2024-10-29 20:50:12 +01:00
bool exchangeMTU();
[BREAKING]- Refactor client * General code cleanup and rename variables to use a consistent style. * Removes the disconnect timer and will use the BLE_GAP_EVENT_TERM_FAILURE event to handle failed disconnects. * `NimBLEClient::getConnId` has been renamed to `getConnHandle` to be consistent with bluetooth terminology. * `NimBLEClient::disconnect` now returns a `bool = true on success` instead of an int to be consistent with the rest of the library. * `NimBLEClient::setPeerAddress` now returns a bool, true on success. * `NimBLEClientCallbacks::onConfirmPIN` renamed to `NimBLEClientCallbacks::onConfirmPasskey` to be consistent with bluetooth terminology. * `NimBLEClient::setDataLen` now returns bool, true if successful. * `NimBLEClient::updateConnParams` now returns bool, true if successful. * `NimBLEClient::getServices` now returns a const reference to std::vector<NimBLERemoteService*> instead of a pointer to the internal vector.
2024-11-03 02:00:07 +01:00
bool secureConnection() const;
void setConnectTimeout(uint32_t timeout);
bool setDataLen(uint16_t txOctets);
bool discoverAttributes();
NimBLEConnInfo getConnInfo() const;
int getLastError() const;
bool updateConnParams(uint16_t minInterval, uint16_t maxInterval, uint16_t latency, uint16_t timeout);
void setConnectionParams(uint16_t minInterval,
uint16_t maxInterval,
uint16_t latency,
uint16_t timeout,
uint16_t scanInterval = 16,
uint16_t scanWindow = 16);
const std::vector<NimBLERemoteService*>& getServices(bool refresh = false);
Add iterators to client remote attributes. Add iterators for NimBLEScan: NimBLEadvertisedDevice, NimBLEClient: NimBLERemoteService, NimBLERemoteService: NimBLERemoteCharacteristic and NimBLERemoteCharacteristic: NimBLERemoteDescriptor This is handy e.g. for showing every address of the advertised devices from a scan. To do so, first get a new scan and next: ``` for(auto pAdvertisedDevice: pBLEScan->getResults()) { Serial.printf("Address is %s\n", std::string(pAdvertisedDevice->getAddress()).c_str()); } ``` Of course any other property of the advertised device can be shown (or looked up, if that is your use case) Also this is handy e.g. for showing every UUID in a peripheral. To do so, first connect to a peripheral and next: ``` for(auto pService: *pClient) { Serial.printf("Service UUID is %s\n", std::string(pService->getUUID()).c_str()); for(auto pCharacteristic: *pService) { Serial.printf("Characteristic UUID is %s\n", std::string(pCharacteristic->getUUID()).c_str()); for(auto pDescriptor: *pCharacteristic) { Serial.printf("Descriptor UUID is %s\n", std::string(pDescriptor->getUUID()).c_str()); } } } ``` Again of course any other property can be shown, or looked up.
2020-05-23 04:13:52 +02:00
std::vector<NimBLERemoteService*>::iterator begin();
std::vector<NimBLERemoteService*>::iterator end();
[BREAKING]- Refactor client * General code cleanup and rename variables to use a consistent style. * Removes the disconnect timer and will use the BLE_GAP_EVENT_TERM_FAILURE event to handle failed disconnects. * `NimBLEClient::getConnId` has been renamed to `getConnHandle` to be consistent with bluetooth terminology. * `NimBLEClient::disconnect` now returns a `bool = true on success` instead of an int to be consistent with the rest of the library. * `NimBLEClient::setPeerAddress` now returns a bool, true on success. * `NimBLEClientCallbacks::onConfirmPIN` renamed to `NimBLEClientCallbacks::onConfirmPasskey` to be consistent with bluetooth terminology. * `NimBLEClient::setDataLen` now returns bool, true if successful. * `NimBLEClient::updateConnParams` now returns bool, true if successful. * `NimBLEClient::getServices` now returns a const reference to std::vector<NimBLERemoteService*> instead of a pointer to the internal vector.
2024-11-03 02:00:07 +01:00
NimBLERemoteCharacteristic* getCharacteristic(uint16_t handle);
Remove automatic discovery in NimBLEClient::connect(). Instead of discovering the peripheral database on connection and consuming the associated resources this will give the user more control over the discovery operation. * Adds void NimBLEClient::discoverAtrributes() for the user to discover all the peripheral attributes as a replacement for the former functionality. * getServices(), getCharacteristics(), getDescriptors() now take an optional bool parameter (default false). If true it will clear the respective vector and retrieve all the respective attributes from the peripheral. If false it will retrieve the attributes only if the vector is empty, otherwise the vector is returned with the currently stored attributes. * getService(NimBLEUUID), getCharacteristic(NimBLEUUID), getDescriptor(NimBLEUUID) will now check the respective vectors for the attribute object and, if not found, will retrieve (only) the specified attribute from the peripheral.
2020-05-23 18:27:32 +02:00
NimBLERemoteService* getService(const char* uuid);
[BREAKING]- Refactor client * General code cleanup and rename variables to use a consistent style. * Removes the disconnect timer and will use the BLE_GAP_EVENT_TERM_FAILURE event to handle failed disconnects. * `NimBLEClient::getConnId` has been renamed to `getConnHandle` to be consistent with bluetooth terminology. * `NimBLEClient::disconnect` now returns a `bool = true on success` instead of an int to be consistent with the rest of the library. * `NimBLEClient::setPeerAddress` now returns a bool, true on success. * `NimBLEClientCallbacks::onConfirmPIN` renamed to `NimBLEClientCallbacks::onConfirmPasskey` to be consistent with bluetooth terminology. * `NimBLEClient::setDataLen` now returns bool, true if successful. * `NimBLEClient::updateConnParams` now returns bool, true if successful. * `NimBLEClient::getServices` now returns a const reference to std::vector<NimBLERemoteService*> instead of a pointer to the internal vector.
2024-11-03 02:00:07 +01:00
NimBLERemoteService* getService(const NimBLEUUID& uuid);
Make attribute delete functions public and selective by UUID * Make remote attribute delete functions public. * Rename clear...() functions to delete...(), with ... equals Service(-s), Characteristic(-s) or Descriptor(-s), depending on what the function actually deletes
2020-05-30 05:21:56 +02:00
void deleteServices();
[BREAKING]- Refactor client * General code cleanup and rename variables to use a consistent style. * Removes the disconnect timer and will use the BLE_GAP_EVENT_TERM_FAILURE event to handle failed disconnects. * `NimBLEClient::getConnId` has been renamed to `getConnHandle` to be consistent with bluetooth terminology. * `NimBLEClient::disconnect` now returns a `bool = true on success` instead of an int to be consistent with the rest of the library. * `NimBLEClient::setPeerAddress` now returns a bool, true on success. * `NimBLEClientCallbacks::onConfirmPIN` renamed to `NimBLEClientCallbacks::onConfirmPasskey` to be consistent with bluetooth terminology. * `NimBLEClient::setDataLen` now returns bool, true if successful. * `NimBLEClient::updateConnParams` now returns bool, true if successful. * `NimBLEClient::getServices` now returns a const reference to std::vector<NimBLERemoteService*> instead of a pointer to the internal vector.
2024-11-03 02:00:07 +01:00
size_t deleteService(const NimBLEUUID& uuid);
NimBLEAttValue getValue(const NimBLEUUID& serviceUUID, const NimBLEUUID& characteristicUUID);
bool setValue(const NimBLEUUID& serviceUUID,
const NimBLEUUID& characteristicUUID,
const NimBLEAttValue& value,
bool response = false);
# if CONFIG_BT_NIMBLE_EXT_ADV
void setConnectPhy(uint8_t mask);
# endif
Refactor client connection establishment and client deletion. * Removes the connection established flag as it should not be necessary. * Deleting the client instance from the `onDisconnect` callback is now supported. * `NimBLEDevice::deleteClient` no longer blocks tasks * Adds a new `Config` struct to `NimBLEClient` to efficiently set single bit config settings. * Adds `NimBLEClient::setSelfDelete` that takes the bool parameters `deleteOnDisconnect` and `deleteOnConnectFail` This will configure the client to delete itself when disconnected or the connection attempt fails. * Adds `NimBLEClient::setConfig` and `NimBLEClient::getConfig` which takes or returns a `NimBLEClient::Config` object respectively. * Reword `BLE_HS_EAPP` error string to be more accurate.
2024-11-14 23:55:09 +01:00
struct Config {
uint8_t deleteCallbacks : 1; // Delete the callback object when the client is deleted.
uint8_t deleteOnDisconnect : 1; // Delete the client when disconnected.
uint8_t deleteOnConnectFail : 1; // Delete the client when a connection attempt fails.
uint8_t asyncConnect : 1; // Connect asynchronously.
uint8_t exchangeMTU : 1; // Exchange MTU after connection.
};
Config getConfig() const;
void setConfig(Config config);
[BREAKING]- Refactor client * General code cleanup and rename variables to use a consistent style. * Removes the disconnect timer and will use the BLE_GAP_EVENT_TERM_FAILURE event to handle failed disconnects. * `NimBLEClient::getConnId` has been renamed to `getConnHandle` to be consistent with bluetooth terminology. * `NimBLEClient::disconnect` now returns a `bool = true on success` instead of an int to be consistent with the rest of the library. * `NimBLEClient::setPeerAddress` now returns a bool, true on success. * `NimBLEClientCallbacks::onConfirmPIN` renamed to `NimBLEClientCallbacks::onConfirmPasskey` to be consistent with bluetooth terminology. * `NimBLEClient::setDataLen` now returns bool, true if successful. * `NimBLEClient::updateConnParams` now returns bool, true if successful. * `NimBLEClient::getServices` now returns a const reference to std::vector<NimBLERemoteService*> instead of a pointer to the internal vector.
2024-11-03 02:00:07 +01:00
private:
NimBLEClient(const NimBLEAddress& peerAddress);
Initial commit.
2020-03-30 01:44:20 +02:00
~NimBLEClient();
[BREAKING]- Refactor client * General code cleanup and rename variables to use a consistent style. * Removes the disconnect timer and will use the BLE_GAP_EVENT_TERM_FAILURE event to handle failed disconnects. * `NimBLEClient::getConnId` has been renamed to `getConnHandle` to be consistent with bluetooth terminology. * `NimBLEClient::disconnect` now returns a `bool = true on success` instead of an int to be consistent with the rest of the library. * `NimBLEClient::setPeerAddress` now returns a bool, true on success. * `NimBLEClientCallbacks::onConfirmPIN` renamed to `NimBLEClientCallbacks::onConfirmPasskey` to be consistent with bluetooth terminology. * `NimBLEClient::setDataLen` now returns bool, true if successful. * `NimBLEClient::updateConnParams` now returns bool, true if successful. * `NimBLEClient::getServices` now returns a const reference to std::vector<NimBLERemoteService*> instead of a pointer to the internal vector.
2024-11-03 02:00:07 +01:00
NimBLEClient(const NimBLEClient&) = delete;
NimBLEClient& operator=(const NimBLEClient&) = delete;
bool retrieveServices(const NimBLEUUID* uuidFilter = nullptr);
static int handleGapEvent(struct ble_gap_event* event, void* arg);
Add asyncronous client connect and MTU exchange. * Adds parameters `asyncConnect` and `exchangeMTU` to `NimBLEClient::connect`, default values work as the original connect method. * * `asyncConnect`; if true, will send the connect command and return immediately with a true value for successfully sending the command, else false. * * `exchangeMTU`; if true will send the exchange MTU command upon connection, otherwise not and the application can choose to do this later via the `exchangeMTU` method. * Adds `onMTUChange` callback to `NimBLEClientCallbacks` * Add `NimBLEDevice::getConnectedClients()` which returns a vector of pointers to the currently connected client instances. * Calling `NimBLEClient::connect` will no longer cancel already in progress connections.
2024-10-29 20:50:12 +01:00
static int exchangeMTUCb(uint16_t conn_handle, const ble_gatt_error* error, uint16_t mtu, void* arg);
[BREAKING]- Refactor client * General code cleanup and rename variables to use a consistent style. * Removes the disconnect timer and will use the BLE_GAP_EVENT_TERM_FAILURE event to handle failed disconnects. * `NimBLEClient::getConnId` has been renamed to `getConnHandle` to be consistent with bluetooth terminology. * `NimBLEClient::disconnect` now returns a `bool = true on success` instead of an int to be consistent with the rest of the library. * `NimBLEClient::setPeerAddress` now returns a bool, true on success. * `NimBLEClientCallbacks::onConfirmPIN` renamed to `NimBLEClientCallbacks::onConfirmPasskey` to be consistent with bluetooth terminology. * `NimBLEClient::setDataLen` now returns bool, true if successful. * `NimBLEClient::updateConnParams` now returns bool, true if successful. * `NimBLEClient::getServices` now returns a const reference to std::vector<NimBLERemoteService*> instead of a pointer to the internal vector.
2024-11-03 02:00:07 +01:00
static int serviceDiscoveredCB(uint16_t connHandle,
const struct ble_gatt_error* error,
const struct ble_gatt_svc* service,
void* arg);
NimBLEAddress m_peerAddress;
mutable int m_lastErr;
int32_t m_connectTimeout;
[BREAKING] - Refactor NimBLEUtils * Add functions `NimBLEUtils::taskWait` and `NimBLEUtils::taskRelease` to simplify task blocking/messaging. * `NimBLEUtils::buildHexData` replaced with `NimBLEUtils::dataToHexString` * Add missing GAP event strings. * Add missing return code strings. * `NimBLEUtils::dumpGapEvent` function removed. * Event/error code strings optimized.
2024-11-10 21:31:37 +01:00
mutable NimBLETaskData* m_pTaskData;
[BREAKING]- Refactor client * General code cleanup and rename variables to use a consistent style. * Removes the disconnect timer and will use the BLE_GAP_EVENT_TERM_FAILURE event to handle failed disconnects. * `NimBLEClient::getConnId` has been renamed to `getConnHandle` to be consistent with bluetooth terminology. * `NimBLEClient::disconnect` now returns a `bool = true on success` instead of an int to be consistent with the rest of the library. * `NimBLEClient::setPeerAddress` now returns a bool, true on success. * `NimBLEClientCallbacks::onConfirmPIN` renamed to `NimBLEClientCallbacks::onConfirmPasskey` to be consistent with bluetooth terminology. * `NimBLEClient::setDataLen` now returns bool, true if successful. * `NimBLEClient::updateConnParams` now returns bool, true if successful. * `NimBLEClient::getServices` now returns a const reference to std::vector<NimBLERemoteService*> instead of a pointer to the internal vector.
2024-11-03 02:00:07 +01:00
std::vector<NimBLERemoteService*> m_svcVec;
NimBLEClientCallbacks* m_pClientCallbacks;
uint16_t m_connHandle;
uint8_t m_terminateFailCount;
Refactor client connection establishment and client deletion. * Removes the connection established flag as it should not be necessary. * Deleting the client instance from the `onDisconnect` callback is now supported. * `NimBLEDevice::deleteClient` no longer blocks tasks * Adds a new `Config` struct to `NimBLEClient` to efficiently set single bit config settings. * Adds `NimBLEClient::setSelfDelete` that takes the bool parameters `deleteOnDisconnect` and `deleteOnConnectFail` This will configure the client to delete itself when disconnected or the connection attempt fails. * Adds `NimBLEClient::setConfig` and `NimBLEClient::getConfig` which takes or returns a `NimBLEClient::Config` object respectively. * Reword `BLE_HS_EAPP` error string to be more accurate.
2024-11-14 23:55:09 +01:00
Config m_config;
[BREAKING]- Refactor client * General code cleanup and rename variables to use a consistent style. * Removes the disconnect timer and will use the BLE_GAP_EVENT_TERM_FAILURE event to handle failed disconnects. * `NimBLEClient::getConnId` has been renamed to `getConnHandle` to be consistent with bluetooth terminology. * `NimBLEClient::disconnect` now returns a `bool = true on success` instead of an int to be consistent with the rest of the library. * `NimBLEClient::setPeerAddress` now returns a bool, true on success. * `NimBLEClientCallbacks::onConfirmPIN` renamed to `NimBLEClientCallbacks::onConfirmPasskey` to be consistent with bluetooth terminology. * `NimBLEClient::setDataLen` now returns bool, true if successful. * `NimBLEClient::updateConnParams` now returns bool, true if successful. * `NimBLEClient::getServices` now returns a const reference to std::vector<NimBLERemoteService*> instead of a pointer to the internal vector.
2024-11-03 02:00:07 +01:00
# if CONFIG_BT_NIMBLE_EXT_ADV
uint8_t m_phyMask;
# endif
ble_gap_conn_params m_connParams;
friend class NimBLEDevice;
Conditionally compile code for specific roles. This allows NimBLE options in menuconfig to reduce code size based on the roles selected (scan/advertising/central/peripheral). Significant code space can be saved by removing unnecessary roles for the application.
2020-05-14 06:03:56 +02:00
}; // class NimBLEClient
Initial commit.
2020-03-30 01:44:20 +02:00
/**
* @brief Callbacks associated with a %BLE client.
*/
class NimBLEClientCallbacks {
[BREAKING]- Refactor client * General code cleanup and rename variables to use a consistent style. * Removes the disconnect timer and will use the BLE_GAP_EVENT_TERM_FAILURE event to handle failed disconnects. * `NimBLEClient::getConnId` has been renamed to `getConnHandle` to be consistent with bluetooth terminology. * `NimBLEClient::disconnect` now returns a `bool = true on success` instead of an int to be consistent with the rest of the library. * `NimBLEClient::setPeerAddress` now returns a bool, true on success. * `NimBLEClientCallbacks::onConfirmPIN` renamed to `NimBLEClientCallbacks::onConfirmPasskey` to be consistent with bluetooth terminology. * `NimBLEClient::setDataLen` now returns bool, true if successful. * `NimBLEClient::updateConnParams` now returns bool, true if successful. * `NimBLEClient::getServices` now returns a const reference to std::vector<NimBLERemoteService*> instead of a pointer to the internal vector.
2024-11-03 02:00:07 +01:00
public:
Initial commit.
2020-03-30 01:44:20 +02:00
virtual ~NimBLEClientCallbacks() {};
Fix comments for doxygen (#16) * Fix comments for doxygen * Add documentation and update readme.
2020-07-09 03:27:26 +02:00
/**
* @brief Called after client connects.
Add NimBLEClientCallbacks::onConnectFail callback Adds a callback that is called when the connection attempt fail while connecting asynchronously.
2024-11-25 03:46:34 +01:00
* @param [in] pClient A pointer to the connecting client object.
Fix comments for doxygen (#16) * Fix comments for doxygen * Add documentation and update readme.
2020-07-09 03:27:26 +02:00
*/
Merge bugfix branch into master
2020-04-14 03:13:51 +02:00
virtual void onConnect(NimBLEClient* pClient);
Fix comments for doxygen (#16) * Fix comments for doxygen * Add documentation and update readme.
2020-07-09 03:27:26 +02:00
Add NimBLEClientCallbacks::onConnectFail callback Adds a callback that is called when the connection attempt fail while connecting asynchronously.
2024-11-25 03:46:34 +01:00
/**
* @brief Called when a connection attempt fails.
* @param [in] pClient A pointer to the connecting client object.
* @param [in] reason Contains the reason code for the connection failure.
*/
virtual void onConnectFail(NimBLEClient* pClient, int reason);
Fix comments for doxygen (#16) * Fix comments for doxygen * Add documentation and update readme.
2020-07-09 03:27:26 +02:00
/**
* @brief Called when disconnected from the server.
* @param [in] pClient A pointer to the calling client object.
Add docs build.
2022-08-27 20:38:53 +02:00
* @param [in] reason Contains the reason code for the disconnection.
Fix comments for doxygen (#16) * Fix comments for doxygen * Add documentation and update readme.
2020-07-09 03:27:26 +02:00
*/
[Breaking] Add disconnect reason to client callback. (#398) (#81) Adds the reason code as a parameter to the client onDisconnect callback. * Update examples/docs.
2022-08-27 03:51:19 +02:00
virtual void onDisconnect(NimBLEClient* pClient, int reason);
Fix comments for doxygen (#16) * Fix comments for doxygen * Add documentation and update readme.
2020-07-09 03:27:26 +02:00
/**
* @brief Called when server requests to update the connection parameters.
* @param [in] pClient A pointer to the calling client object.
* @param [in] params A pointer to the struct containing the connection parameters requested.
Release 1.4.0 * Fix typos * Update docs
2022-07-31 19:00:12 +02:00
* @return True to accept the parameters.
Fix comments for doxygen (#16) * Fix comments for doxygen * Add documentation and update readme.
2020-07-09 03:27:26 +02:00
*/
Merge bugfix branch into master
2020-04-14 03:13:51 +02:00
virtual bool onConnParamsUpdateRequest(NimBLEClient* pClient, const ble_gap_upd_params* params);
Fix comments for doxygen (#16) * Fix comments for doxygen * Add documentation and update readme.
2020-07-09 03:27:26 +02:00
/**
* @brief Called when server requests a passkey for pairing.
[BREAKING] Asynchronous pin injections for Numeric Comparison and PassKey Input (#165) * Make NimBLEConnInfo functions const. * Update callback functions and update client to use new functions. * Update examples. * Update migration guide. --------- Co-authored-by: Casey Smith <csmith@morningstarcorp.com>
2024-06-07 03:36:14 +02:00
* @param [in] connInfo A reference to a NimBLEConnInfo instance containing the peer info.
Fix comments for doxygen (#16) * Fix comments for doxygen * Add documentation and update readme.
2020-07-09 03:27:26 +02:00
*/
[BREAKING] Refactor attributes Refactor attributes to reduce code duplication and improve maintainability. * Add attribute base classes to provide common code. * Add const where possible to functions and parameters. * `NimBLECharacteristic::notify` no longer takes a `bool is_notification` parameter, instead `indicate()` should be called to send indications. * `NimBLECharacteristic::indicate` now takes the same parameters as `notify`. * `NimBLECharacteristicCallbacks` and `NimBLEDescriptorCallbacks` methods now take `const NimBLEConnInfo&` instead of non-const. * `NimBLECharacteristic::onNotify` callback removed as unnecessary, the library does not call notify without app input. * `NimBLERemoteCharacteristic::getRemoteService` now returns a `const NimBLERemoteService*` instead of non-const. * Add NimBLEUUID constructor that takes a reference to `ble_uuid_any_t`. * `NimBLERemoteService::getCharacteristics` now returns a `const std::vector<NimBLERemoteCharacteristic*>&` instead of non-const `std::vector<NimBLERemoteCharacteristic*>*` * `NimBLERemoteService::getValue` now returns `NimBLEAttValue` instead of `std::string` * `NimBLEService::getCharacteristics` now returns a `const std::vector<NimBLECharacteristic*>&` instead of a copy of std::vector<NimBLECharacteristic *>. * Remove const requirement for NimBLEConnInfo parameter in callbacks. Const is unnecessary as the data can't be changed by application code. * Change NimBLERemoteCharacteristic::getRemoteService to return const pointer.
2024-07-26 22:47:36 +02:00
virtual void onPassKeyEntry(NimBLEConnInfo& connInfo);
Fix comments for doxygen (#16) * Fix comments for doxygen * Add documentation and update readme.
2020-07-09 03:27:26 +02:00
/**
* @brief Called when the pairing procedure is complete.
Add docs build.
2022-08-27 20:38:53 +02:00
* @param [in] connInfo A reference to a NimBLEConnInfo instance containing the peer info.\n
Fix comments for doxygen (#16) * Fix comments for doxygen * Add documentation and update readme.
2020-07-09 03:27:26 +02:00
* This can be used to check the status of the connection encryption/pairing.
*/
[BREAKING] Refactor attributes Refactor attributes to reduce code duplication and improve maintainability. * Add attribute base classes to provide common code. * Add const where possible to functions and parameters. * `NimBLECharacteristic::notify` no longer takes a `bool is_notification` parameter, instead `indicate()` should be called to send indications. * `NimBLECharacteristic::indicate` now takes the same parameters as `notify`. * `NimBLECharacteristicCallbacks` and `NimBLEDescriptorCallbacks` methods now take `const NimBLEConnInfo&` instead of non-const. * `NimBLECharacteristic::onNotify` callback removed as unnecessary, the library does not call notify without app input. * `NimBLERemoteCharacteristic::getRemoteService` now returns a `const NimBLERemoteService*` instead of non-const. * Add NimBLEUUID constructor that takes a reference to `ble_uuid_any_t`. * `NimBLERemoteService::getCharacteristics` now returns a `const std::vector<NimBLERemoteCharacteristic*>&` instead of non-const `std::vector<NimBLERemoteCharacteristic*>*` * `NimBLERemoteService::getValue` now returns `NimBLEAttValue` instead of `std::string` * `NimBLEService::getCharacteristics` now returns a `const std::vector<NimBLECharacteristic*>&` instead of a copy of std::vector<NimBLECharacteristic *>. * Remove const requirement for NimBLEConnInfo parameter in callbacks. Const is unnecessary as the data can't be changed by application code. * Change NimBLERemoteCharacteristic::getRemoteService to return const pointer.
2024-07-26 22:47:36 +02:00
virtual void onAuthenticationComplete(NimBLEConnInfo& connInfo);
Fix comments for doxygen (#16) * Fix comments for doxygen * Add documentation and update readme.
2020-07-09 03:27:26 +02:00
/**
* @brief Called when using numeric comparision for pairing.
[BREAKING] Asynchronous pin injections for Numeric Comparison and PassKey Input (#165) * Make NimBLEConnInfo functions const. * Update callback functions and update client to use new functions. * Update examples. * Update migration guide. --------- Co-authored-by: Casey Smith <csmith@morningstarcorp.com>
2024-06-07 03:36:14 +02:00
* @param [in] connInfo A reference to a NimBLEConnInfo instance containing the peer info.
Fix comments for doxygen (#16) * Fix comments for doxygen * Add documentation and update readme.
2020-07-09 03:27:26 +02:00
* @param [in] pin The pin to compare with the server.
*/
[BREAKING]- Refactor client * General code cleanup and rename variables to use a consistent style. * Removes the disconnect timer and will use the BLE_GAP_EVENT_TERM_FAILURE event to handle failed disconnects. * `NimBLEClient::getConnId` has been renamed to `getConnHandle` to be consistent with bluetooth terminology. * `NimBLEClient::disconnect` now returns a `bool = true on success` instead of an int to be consistent with the rest of the library. * `NimBLEClient::setPeerAddress` now returns a bool, true on success. * `NimBLEClientCallbacks::onConfirmPIN` renamed to `NimBLEClientCallbacks::onConfirmPasskey` to be consistent with bluetooth terminology. * `NimBLEClient::setDataLen` now returns bool, true if successful. * `NimBLEClient::updateConnParams` now returns bool, true if successful. * `NimBLEClient::getServices` now returns a const reference to std::vector<NimBLERemoteService*> instead of a pointer to the internal vector.
2024-11-03 02:00:07 +01:00
virtual void onConfirmPasskey(NimBLEConnInfo& connInfo, uint32_t pin);
Add server and client `onIdentity` callback. Adds a callback that is called when the identity address of the peer is resolved, this is useful for adding it to a whitelist.
2024-06-12 17:26:10 +02:00
/**
* @brief Called when the peer identity address is resolved.
* @param [in] connInfo A reference to a NimBLEConnInfo instance with information
*/
[BREAKING] Refactor attributes Refactor attributes to reduce code duplication and improve maintainability. * Add attribute base classes to provide common code. * Add const where possible to functions and parameters. * `NimBLECharacteristic::notify` no longer takes a `bool is_notification` parameter, instead `indicate()` should be called to send indications. * `NimBLECharacteristic::indicate` now takes the same parameters as `notify`. * `NimBLECharacteristicCallbacks` and `NimBLEDescriptorCallbacks` methods now take `const NimBLEConnInfo&` instead of non-const. * `NimBLECharacteristic::onNotify` callback removed as unnecessary, the library does not call notify without app input. * `NimBLERemoteCharacteristic::getRemoteService` now returns a `const NimBLERemoteService*` instead of non-const. * Add NimBLEUUID constructor that takes a reference to `ble_uuid_any_t`. * `NimBLERemoteService::getCharacteristics` now returns a `const std::vector<NimBLERemoteCharacteristic*>&` instead of non-const `std::vector<NimBLERemoteCharacteristic*>*` * `NimBLERemoteService::getValue` now returns `NimBLEAttValue` instead of `std::string` * `NimBLEService::getCharacteristics` now returns a `const std::vector<NimBLECharacteristic*>&` instead of a copy of std::vector<NimBLECharacteristic *>. * Remove const requirement for NimBLEConnInfo parameter in callbacks. Const is unnecessary as the data can't be changed by application code. * Change NimBLERemoteCharacteristic::getRemoteService to return const pointer.
2024-07-26 22:47:36 +02:00
virtual void onIdentity(NimBLEConnInfo& connInfo);
Add asyncronous client connect and MTU exchange. * Adds parameters `asyncConnect` and `exchangeMTU` to `NimBLEClient::connect`, default values work as the original connect method. * * `asyncConnect`; if true, will send the connect command and return immediately with a true value for successfully sending the command, else false. * * `exchangeMTU`; if true will send the exchange MTU command upon connection, otherwise not and the application can choose to do this later via the `exchangeMTU` method. * Adds `onMTUChange` callback to `NimBLEClientCallbacks` * Add `NimBLEDevice::getConnectedClients()` which returns a vector of pointers to the currently connected client instances. * Calling `NimBLEClient::connect` will no longer cancel already in progress connections.
2024-10-29 20:50:12 +01:00
/**
* @brief Called when the connection MTU changes.
* @param [in] pClient A pointer to the client that the MTU change is associated with.
* @param [in] MTU The new MTU value.
* about the peer connection parameters.
*/
virtual void onMTUChange(NimBLEClient* pClient, uint16_t MTU);
Initial commit.
2020-03-30 01:44:20 +02:00
};
Refactor include directives to use different paths for arduino/idf. * Sets macros to allow compiling when Central role is enabled and Observer disabled, or Peripheral enabled and Broadcaster disabled. * Adds a macro definition for CONFIG_NIMBLE_CPP_IDF to enable different include paths/functionality for IDF / Arduino.
2021-09-07 05:14:43 +02:00
#endif /* CONFIG_BT_ENABLED && CONFIG_BT_NIMBLE_ROLE_CENTRAL */
[BREAKING]- Refactor client * General code cleanup and rename variables to use a consistent style. * Removes the disconnect timer and will use the BLE_GAP_EVENT_TERM_FAILURE event to handle failed disconnects. * `NimBLEClient::getConnId` has been renamed to `getConnHandle` to be consistent with bluetooth terminology. * `NimBLEClient::disconnect` now returns a `bool = true on success` instead of an int to be consistent with the rest of the library. * `NimBLEClient::setPeerAddress` now returns a bool, true on success. * `NimBLEClientCallbacks::onConfirmPIN` renamed to `NimBLEClientCallbacks::onConfirmPasskey` to be consistent with bluetooth terminology. * `NimBLEClient::setDataLen` now returns bool, true if successful. * `NimBLEClient::updateConnParams` now returns bool, true if successful. * `NimBLEClient::getServices` now returns a const reference to std::vector<NimBLERemoteService*> instead of a pointer to the internal vector.
2024-11-03 02:00:07 +01:00
#endif /* NIMBLE_CPP_CLIENT_H_ */
Reference in a new issue Copy permalink