ScStw/esp-nimble-cpp
2
0
Fork 0
mirror of https://github.com/h2zero/esp-nimble-cpp.git synced 2024-10-22 16:09:44 +02:00
Code Issues Projects Releases Packages Wiki Activity
esp-nimble-cpp/src/NimBLEClient.h

159 lines
6.3 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
*/
#ifndef MAIN_NIMBLECLIENT_H_
#define MAIN_NIMBLECLIENT_H_
#include "sdkconfig.h"
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
#if defined(CONFIG_BT_ENABLED)
#include "nimconfig.h"
#if defined(CONFIG_BT_NIMBLE_ROLE_CENTRAL)
Initial commit.
2020-03-30 01:44:20 +02:00
#include "NimBLEAddress.h"
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
#include "NimBLEUUID.h"
Replace semaphores with task notifications. (#9) * Replace all semaphores with task notifications. * use critical sections to prevent concurrent data access. * Ensure scan stop has been called before connecting. * Optimize and cleanup * Add template casting to NimBLERemoteDescriptor::readValue() * Removed storage of the descriptor value read as it did not serve any purpose.
2020-06-22 06:07:01 +02:00
#include "NimBLEUtils.h"
Initial commit.
2020-03-30 01:44:20 +02:00
#include "NimBLEAdvertisedDevice.h"
#include "NimBLERemoteService.h"
Breaking: Use std::vector instead of std::map in client classes (#46) * Exchange map for vector, saving 1,076 bytes of program memory and 5,024 bytes of heap for a small device (LYWSD03MMC) * Removing m_characteristicMapByHandle (using the handles form m_characteristicVector instead) saving in total (compared to the current master) 1,508 bytes of program memory and 6,500 bytes of heap for a small device (LYWSD03MMC) * Change NimBLEScan container from std::map to std::vector * Add function to get advertised device by address * Update documentation
2020-05-18 04:21:35 +02:00
#include <vector>
Initial commit.
2020-03-30 01:44:20 +02:00
#include <string>
class NimBLERemoteService;
class NimBLEClientCallbacks;
class NimBLEAdvertisedDevice;
/**
* @brief A model of a %BLE client.
*/
class NimBLEClient {
public:
Remove type parameter from NimBLEClient::connect() * The type is available in the NimBLEAddress parameter, no longer needed separately. Co-authored-by: wakwak-koba <wakwak-koba@users.noreply.github.com>
2020-07-30 18:09:27 +02:00
bool connect(NimBLEAdvertisedDevice* device, bool deleteAttibutes = true);
bool connect(const NimBLEAddress &address, bool deleteAttibutes = true);
Add doxygen comments in nimconfig.h
2020-08-18 23:02:57 +02:00
bool connect(bool deleteAttibutes = true);
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
int disconnect(uint8_t reason = BLE_ERR_REM_USER_CONN_TERM);
NimBLEAddress getPeerAddress();
Set peer address of client when creating the instance. * Adds new client connect method that will connect to the address already set. Co-authored-by: wakwak-koba <wakwak-koba@users.noreply.github.com>
2020-07-30 18:04:34 +02:00
void setPeerAddress(const NimBLEAddress &address);
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
int getRssi();
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();
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);
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();
size_t deleteService(const NimBLEUUID &uuid);
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
std::string getValue(const NimBLEUUID &serviceUUID, const NimBLEUUID &characteristicUUID);
bool setValue(const NimBLEUUID &serviceUUID, const NimBLEUUID &characteristicUUID,
const std::string &value);
bool isConnected();
void setClientCallbacks(NimBLEClientCallbacks *pClientCallbacks,
bool deleteCallbacks = true);
std::string toString();
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
uint16_t getConnId();
uint16_t getMTU();
bool secureConnection();
void setConnectTimeout(uint8_t timeout);
void setConnectionParams(uint16_t minInterval, uint16_t maxInterval,
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
uint16_t latency, uint16_t timeout,
uint16_t scanInterval=16, uint16_t scanWindow=16);
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
void updateConnParams(uint16_t minInterval, uint16_t maxInterval,
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
uint16_t latency, uint16_t timeout);
void discoverAttributes();
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
private:
Initialize peerAddress in client constructor. Co-authored-by: wakwak-koba <wakwak-koba@users.noreply.github.com>
2020-07-30 20:31:17 +02:00
NimBLEClient(const NimBLEAddress &peerAddress);
Initial commit.
2020-03-30 01:44:20 +02:00
~NimBLEClient();
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
friend class NimBLEDevice;
friend class NimBLERemoteService;
Initial commit.
2020-03-30 01:44:20 +02:00
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
static int handleGapEvent(struct ble_gap_event *event, void *arg);
static int serviceDiscoveredCB(uint16_t conn_handle,
const struct ble_gatt_error *error,
const struct ble_gatt_svc *service,
void *arg);
bool retrieveServices(const NimBLEUUID *uuid_filter = nullptr);
Initial commit.
2020-03-30 01:44:20 +02:00
Initialize peerAddress in client constructor. Co-authored-by: wakwak-koba <wakwak-koba@users.noreply.github.com>
2020-07-30 20:31:17 +02:00
NimBLEAddress m_peerAddress;
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
uint16_t m_conn_id;
Replace semaphores with task notifications. (#9) * Replace all semaphores with task notifications. * use critical sections to prevent concurrent data access. * Ensure scan stop has been called before connecting. * Optimize and cleanup * Add template casting to NimBLERemoteDescriptor::readValue() * Removed storage of the descriptor value read as it did not serve any purpose.
2020-06-22 06:07:01 +02:00
bool m_isConnected;
bool m_waitingToConnect;
bool m_deleteCallbacks;
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
int32_t m_connectTimeout;
Replace semaphores with task notifications. (#9) * Replace all semaphores with task notifications. * use critical sections to prevent concurrent data access. * Ensure scan stop has been called before connecting. * Optimize and cleanup * Add template casting to NimBLERemoteDescriptor::readValue() * Removed storage of the descriptor value read as it did not serve any purpose.
2020-06-22 06:07:01 +02:00
NimBLEClientCallbacks* m_pClientCallbacks;
ble_task_data_t *m_pTaskData;
Initial commit.
2020-03-30 01:44:20 +02:00
Breaking: Use std::vector instead of std::map in client classes (#46) * Exchange map for vector, saving 1,076 bytes of program memory and 5,024 bytes of heap for a small device (LYWSD03MMC) * Removing m_characteristicMapByHandle (using the handles form m_characteristicVector instead) saving in total (compared to the current master) 1,508 bytes of program memory and 6,500 bytes of heap for a small device (LYWSD03MMC) * Change NimBLEScan container from std::map to std::vector * Add function to get advertised device by address * Update documentation
2020-05-18 04:21:35 +02:00
std::vector<NimBLERemoteService*> m_servicesVector;
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
Merge bugfix branch into master
2020-04-14 03:13:51 +02:00
private:
friend class NimBLEClientCallbacks;
ble_gap_conn_params m_pConnParams;
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
}; // class NimBLEClient
Initial commit.
2020-03-30 01:44:20 +02:00
/**
* @brief Callbacks associated with a %BLE client.
*/
class NimBLEClientCallbacks {
public:
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.
* @param [in] pClient A pointer to the calling client object.
*/
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
/**
* @brief Called when disconnected from the server.
* @param [in] pClient A pointer to the calling client object.
*/
Merge bugfix branch into master
2020-04-14 03:13:51 +02:00
virtual void onDisconnect(NimBLEClient* pClient);
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.
* @return True to accept the parmeters.
*/
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.
* @return The passkey to be sent to the server.
*/
Merge bugfix branch into master
2020-04-14 03:13:51 +02:00
virtual uint32_t onPassKeyRequest();
Fix comments for doxygen (#16) * Fix comments for doxygen * Add documentation and update readme.
2020-07-09 03:27:26 +02:00
/*virtual void onPassKeyNotify(uint32_t pass_key);
virtual bool onSecurityRequest();*/
/**
* @brief Called when the pairing procedure is complete.
* @param [in] desc A pointer to the struct containing the connection information.\n
* This can be used to check the status of the connection encryption/pairing.
*/
Merge bugfix branch into master
2020-04-14 03:13:51 +02:00
virtual void onAuthenticationComplete(ble_gap_conn_desc* desc);
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.
* @param [in] pin The pin to compare with the server.
* @return True to accept the pin.
*/
Merge bugfix branch into master
2020-04-14 03:13:51 +02:00
virtual bool onConfirmPIN(uint32_t pin);
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
#endif // #if defined(CONFIG_BT_NIMBLE_ROLE_CENTRAL)
Initial commit.
2020-03-30 01:44:20 +02:00
#endif // CONFIG_BT_ENABLED
#endif /* MAIN_NIMBLECLIENT_H_ */
Reference in a new issue Copy permalink