esp-nimble-cpp 2.3.1
Loading...
Searching...
No Matches
NimBLEClient.h
1/*
2 * Copyright 2020-2025 Ryan Powell <ryan@nable-embedded.io> and
3 * esp-nimble-cpp, NimBLE-Arduino contributors.
4 *
5 * Licensed under the Apache License, Version 2.0 (the "License");
6 * you may not use this file except in compliance with the License.
7 * You may obtain a copy of the License at
8 *
9 * http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17
18#ifndef NIMBLE_CPP_CLIENT_H_
19#define NIMBLE_CPP_CLIENT_H_
20
21#include "nimconfig.h"
22#if CONFIG_BT_ENABLED && CONFIG_BT_NIMBLE_ROLE_CENTRAL
23
24# if defined(CONFIG_NIMBLE_CPP_IDF)
25# include "host/ble_gap.h"
26# else
27# include "nimble/nimble/host/include/host/ble_gap.h"
28# endif
29
30# include "NimBLEAddress.h"
31
32# include <stdint.h>
33# include <vector>
34# include <string>
35
36class NimBLEAddress;
37class NimBLEUUID;
41class NimBLEAttValue;
43class NimBLEConnInfo;
44struct NimBLETaskData;
45
50 public:
51# if CONFIG_BT_NIMBLE_ROLE_OBSERVER
52 bool connect(const NimBLEAdvertisedDevice* device,
53 bool deleteAttributes = true,
54 bool asyncConnect = false,
55 bool exchangeMTU = true);
56# endif
57 bool connect(const NimBLEAddress& address, bool deleteAttributes = true, bool asyncConnect = false, bool exchangeMTU = true);
58 bool connect(bool deleteAttributes = true, bool asyncConnect = false, bool exchangeMTU = true);
59 bool disconnect(uint8_t reason = BLE_ERR_REM_USER_CONN_TERM);
60 bool cancelConnect() const;
61 void setSelfDelete(bool deleteOnDisconnect, bool deleteOnConnectFail);
63 bool setPeerAddress(const NimBLEAddress& address);
64 int getRssi() const;
65 bool isConnected() const;
66 void setClientCallbacks(NimBLEClientCallbacks* pClientCallbacks, bool deleteCallbacks = true);
67 std::string toString() const;
68 uint16_t getConnHandle() const;
69 uint16_t getMTU() const;
70 bool exchangeMTU();
71 bool secureConnection(bool async = false) const;
72 void setConnectTimeout(uint32_t timeout);
73 bool setDataLen(uint16_t txOctets);
74 bool discoverAttributes();
76 int getLastError() const;
77 bool updateConnParams(uint16_t minInterval, uint16_t maxInterval, uint16_t latency, uint16_t timeout);
78 void setConnectionParams(uint16_t minInterval,
79 uint16_t maxInterval,
80 uint16_t latency,
81 uint16_t timeout,
82 uint16_t scanInterval = 16,
83 uint16_t scanWindow = 16);
84 const std::vector<NimBLERemoteService*>& getServices(bool refresh = false);
85 std::vector<NimBLERemoteService*>::iterator begin();
86 std::vector<NimBLERemoteService*>::iterator end();
88 NimBLERemoteService* getService(const char* uuid);
90 void deleteServices();
91 size_t deleteService(const NimBLEUUID& uuid);
92 NimBLEAttValue getValue(const NimBLEUUID& serviceUUID, const NimBLEUUID& characteristicUUID);
93 bool setValue(const NimBLEUUID& serviceUUID,
94 const NimBLEUUID& characteristicUUID,
95 const NimBLEAttValue& value,
96 bool response = false);
97
98# if CONFIG_BT_NIMBLE_EXT_ADV
99 void setConnectPhy(uint8_t phyMask);
100# endif
101 bool updatePhy(uint8_t txPhysMask, uint8_t rxPhysMask, uint16_t phyOptions = 0);
102 bool getPhy(uint8_t* txPhy, uint8_t* rxPhy);
103
104 struct Config {
105 uint8_t deleteCallbacks : 1; // Delete the callback object when the client is deleted.
106 uint8_t deleteOnDisconnect : 1; // Delete the client when disconnected.
107 uint8_t deleteOnConnectFail : 1; // Delete the client when a connection attempt fails.
108 uint8_t asyncConnect : 1; // Connect asynchronously.
109 uint8_t exchangeMTU : 1; // Exchange MTU after connection.
110 };
111
112 Config getConfig() const;
113 void setConfig(Config config);
114
115 private:
116 NimBLEClient(const NimBLEAddress& peerAddress);
118 NimBLEClient(const NimBLEClient&) = delete;
119 NimBLEClient& operator=(const NimBLEClient&) = delete;
120
121 bool retrieveServices(const NimBLEUUID* uuidFilter = nullptr);
122 static int handleGapEvent(struct ble_gap_event* event, void* arg);
123 static int exchangeMTUCb(uint16_t conn_handle, const ble_gatt_error* error, uint16_t mtu, void* arg);
124 static int serviceDiscoveredCB(uint16_t connHandle,
125 const struct ble_gatt_error* error,
126 const struct ble_gatt_svc* service,
127 void* arg);
128
129 NimBLEAddress m_peerAddress;
130 mutable int m_lastErr;
131 int32_t m_connectTimeout;
132 mutable NimBLETaskData* m_pTaskData;
133 std::vector<NimBLERemoteService*> m_svcVec;
134 NimBLEClientCallbacks* m_pClientCallbacks;
135 uint16_t m_connHandle;
136 uint8_t m_terminateFailCount;
137 mutable uint8_t m_asyncSecureAttempt;
138 Config m_config;
139
140# if CONFIG_BT_NIMBLE_EXT_ADV
141 uint8_t m_phyMask;
142# endif
143 ble_gap_conn_params m_connParams;
144
145 friend class NimBLEDevice;
146 friend class NimBLEServer;
147}; // class NimBLEClient
148
153 public:
154 virtual ~NimBLEClientCallbacks() {};
155
160 virtual void onConnect(NimBLEClient* pClient);
161
167 virtual void onConnectFail(NimBLEClient* pClient, int reason);
168
174 virtual void onDisconnect(NimBLEClient* pClient, int reason);
175
182 virtual bool onConnParamsUpdateRequest(NimBLEClient* pClient, const ble_gap_upd_params* params);
183
188 virtual void onPassKeyEntry(NimBLEConnInfo& connInfo);
189
195 virtual void onAuthenticationComplete(NimBLEConnInfo& connInfo);
196
202 virtual void onConfirmPasskey(NimBLEConnInfo& connInfo, uint32_t pin);
203
208 virtual void onIdentity(NimBLEConnInfo& connInfo);
209
216 virtual void onMTUChange(NimBLEClient* pClient, uint16_t MTU);
217
229 virtual void onPhyUpdate(NimBLEClient* pClient, uint8_t txPhy, uint8_t rxPhy);
230};
231
232#endif // CONFIG_BT_ENABLED && CONFIG_BT_NIMBLE_ROLE_CENTRAL
233#endif // NIMBLE_CPP_CLIENT_H_
A BLE device address.
Definition NimBLEAddress.h:42
A representation of a BLE advertised device found by a scan.
Definition NimBLEAdvertisedDevice.h:45
A specialized container class to hold BLE attribute values.
Definition NimBLEAttValue.h:72
Callbacks associated with a BLE client.
Definition NimBLEClient.h:152
virtual void onPhyUpdate(NimBLEClient *pClient, uint8_t txPhy, uint8_t rxPhy)
Called when the PHY update procedure is complete.
Definition NimBLEClient.cpp:1305
virtual void onConfirmPasskey(NimBLEConnInfo &connInfo, uint32_t pin)
Called when using numeric comparision for pairing.
Definition NimBLEClient.cpp:1296
virtual bool onConnParamsUpdateRequest(NimBLEClient *pClient, const ble_gap_upd_params *params)
Called when server requests to update the connection parameters.
Definition NimBLEClient.cpp:1278
virtual void onMTUChange(NimBLEClient *pClient, uint16_t MTU)
Called when the connection MTU changes.
Definition NimBLEClient.cpp:1301
virtual void onConnect(NimBLEClient *pClient)
Called after client connects.
Definition NimBLEClient.cpp:1266
virtual void onPassKeyEntry(NimBLEConnInfo &connInfo)
Called when server requests a passkey for pairing.
Definition NimBLEClient.cpp:1283
virtual void onIdentity(NimBLEConnInfo &connInfo)
Called when the peer identity address is resolved.
Definition NimBLEClient.cpp:1292
virtual void onConnectFail(NimBLEClient *pClient, int reason)
Called when a connection attempt fails.
Definition NimBLEClient.cpp:1270
virtual void onDisconnect(NimBLEClient *pClient, int reason)
Called when disconnected from the server.
Definition NimBLEClient.cpp:1274
virtual void onAuthenticationComplete(NimBLEConnInfo &connInfo)
Called when the pairing procedure is complete.
Definition NimBLEClient.cpp:1288
A model of a BLE client.
Definition NimBLEClient.h:49
void setConnectPhy(uint8_t phyMask)
Set the PHY types to use when connecting to a server.
Definition NimBLEClient.cpp:414
std::vector< NimBLERemoteService * >::iterator end()
Get iterator to the end of the vector of remote service pointers.
Definition NimBLEClient.cpp:620
bool isConnected() const
Are we connected to a server?
Definition NimBLEClient.cpp:1222
size_t deleteService(const NimBLEUUID &uuid)
Delete a service by UUID from the local database to free resources.
Definition NimBLEClient.cpp:115
bool discoverAttributes()
Retrieves the full database of attributes that the peripheral has available.
Definition NimBLEClient.cpp:708
bool updatePhy(uint8_t txPhysMask, uint8_t rxPhysMask, uint16_t phyOptions=0)
Request a change to the PHY used for this peer connection.
Definition NimBLEClient.cpp:437
void setConnectionParams(uint16_t minInterval, uint16_t maxInterval, uint16_t latency, uint16_t timeout, uint16_t scanInterval=16, uint16_t scanWindow=16)
Set the connection parameters to use when connecting to a server.
Definition NimBLEClient.cpp:470
bool exchangeMTU()
Begin the MTU exchange process with the server.
Definition NimBLEClient.cpp:911
int getRssi() const
Ask the BLE server for the RSSI value.
Definition NimBLEClient.cpp:591
bool connect(const NimBLEAdvertisedDevice *device, bool deleteAttributes=true, bool asyncConnect=false, bool exchangeMTU=true)
Connect to an advertising device.
Definition NimBLEClient.cpp:140
bool secureConnection(bool async=false) const
Initiate a secure connection (pair/bond) with the server. Called automatically when a characteristic ...
Definition NimBLEClient.cpp:312
bool disconnect(uint8_t reason=BLE_ERR_REM_USER_CONN_TERM)
Disconnect from the peer.
Definition NimBLEClient.cpp:353
NimBLEAttValue getValue(const NimBLEUUID &serviceUUID, const NimBLEUUID &characteristicUUID)
Get the value of a specific characteristic associated with a specific service.
Definition NimBLEClient.cpp:811
NimBLEAddress getPeerAddress() const
Retrieve the address of the peer.
Definition NimBLEClient.cpp:568
bool setDataLen(uint16_t txOctets)
Request an update of the data packet length.
Definition NimBLEClient.cpp:520
NimBLEConnInfo getConnInfo() const
Get detailed information about the current peer connection.
Definition NimBLEClient.cpp:539
void setSelfDelete(bool deleteOnDisconnect, bool deleteOnConnectFail)
Set or unset a flag to delete this client when disconnected or connection failed.
Definition NimBLEClient.cpp:384
void deleteServices()
Delete all service objects created by this client and clear the vector.
Definition NimBLEClient.cpp:101
NimBLERemoteCharacteristic * getCharacteristic(uint16_t handle)
Get the remote characteristic with the specified handle.
Definition NimBLEClient.cpp:865
bool getPhy(uint8_t *txPhy, uint8_t *rxPhy)
Get the PHY used for this peer connection.
Definition NimBLEClient.cpp:452
uint16_t getMTU() const
Get the current mtu of this connection.
Definition NimBLEClient.cpp:883
bool setPeerAddress(const NimBLEAddress &address)
Set the peer address.
Definition NimBLEClient.cpp:577
std::string toString() const
Return a string representation of this client.
Definition NimBLEClient.cpp:1245
bool setValue(const NimBLEUUID &serviceUUID, const NimBLEUUID &characteristicUUID, const NimBLEAttValue &value, bool response=false)
Set the value of a specific characteristic associated with a specific service.
Definition NimBLEClient.cpp:838
std::vector< NimBLERemoteService * >::iterator begin()
Get iterator to the beginning of the vector of remote service pointers.
Definition NimBLEClient.cpp:612
Config getConfig() const
Get a copy of the clients configuration.
Definition NimBLEClient.cpp:393
uint16_t getConnHandle() const
Get the connection handle for this client.
Definition NimBLEClient.cpp:560
bool updateConnParams(uint16_t minInterval, uint16_t maxInterval, uint16_t latency, uint16_t timeout)
Update the connection parameters:
Definition NimBLEClient.cpp:494
void setConfig(Config config)
Set the client configuration options.
Definition NimBLEClient.cpp:401
const std::vector< NimBLERemoteService * > & getServices(bool refresh=false)
Get a pointer to the vector of found services.
Definition NimBLEClient.cpp:691
NimBLERemoteService * getService(const char *uuid)
Get the service BLE Remote Service instance corresponding to the uuid.
Definition NimBLEClient.cpp:629
int getLastError() const
Get the last error code reported by the NimBLE host.
Definition NimBLEClient.cpp:1262
void setConnectTimeout(uint32_t timeout)
Set the timeout to wait for connection attempt to complete.
Definition NimBLEClient.cpp:552
void setClientCallbacks(NimBLEClientCallbacks *pClientCallbacks, bool deleteCallbacks=true)
Set the callbacks that will be invoked when events are received.
Definition NimBLEClient.cpp:1231
bool cancelConnect() const
Cancel an ongoing connection attempt.
Definition NimBLEClient.cpp:368
Connection information.
Definition NimBLEConnInfo.h:32
A model of a BLE Device from which all the BLE roles are created.
Definition NimBLEDevice.h:122
A model of a remote BLE characteristic.
Definition NimBLERemoteCharacteristic.h:36
A model of a remote BLE service.
Definition NimBLERemoteService.h:34
The model of a BLE server.
Definition NimBLEServer.h:62
A model of a BLE UUID.
Definition NimBLEUUID.h:41
A structure to hold data for a task that is waiting for a response.
Definition NimBLEUtils.h:33