esp-nimble-cpp 2.3.0
Loading...
Searching...
No Matches
NimBLEDevice.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_DEVICE_H_
19#define NIMBLE_CPP_DEVICE_H_
20
21#include "nimconfig.h"
22#if defined(CONFIG_BT_ENABLED)
23# ifdef ESP_PLATFORM
24# ifndef CONFIG_IDF_TARGET_ESP32P4
25# include <esp_bt.h>
26# endif
27# endif
28
29# if defined(CONFIG_NIMBLE_CPP_IDF)
30# include <host/ble_gap.h>
31# else
32# include <nimble/nimble/host/include/host/ble_gap.h>
33# endif
34
35/**** FIX COMPILATION ****/
36# undef min
37# undef max
38/**************************/
39
40# include <string>
41# include <vector>
42
43# if defined(CONFIG_BT_NIMBLE_ROLE_CENTRAL)
44# include <array>
45class NimBLEClient;
46# endif
47
48# if defined(CONFIG_BT_NIMBLE_ROLE_OBSERVER)
49class NimBLEScan;
50# endif
51
52# if defined(CONFIG_BT_NIMBLE_ROLE_BROADCASTER)
53# if CONFIG_BT_NIMBLE_EXT_ADV
55# else
57# endif
58# endif
59
60# if defined(CONFIG_BT_NIMBLE_ROLE_PERIPHERAL)
61class NimBLEServer;
62# if CONFIG_BT_NIMBLE_L2CAP_COC_MAX_NUM > 0
64# endif
65# endif
66
67# if defined(CONFIG_BT_NIMBLE_ROLE_PERIPHERAL) || defined(CONFIG_BT_NIMBLE_ROLE_CENTRAL)
68class NimBLEConnInfo;
69# endif
70
71class NimBLEAddress;
73
74# define BLEDevice NimBLEDevice
75# define BLEClient NimBLEClient
76# define BLERemoteService NimBLERemoteService
77# define BLERemoteCharacteristic NimBLERemoteCharacteristic
78# define BLERemoteDescriptor NimBLERemoteDescriptor
79# define BLEAdvertisedDevice NimBLEAdvertisedDevice
80# define BLEScan NimBLEScan
81# define BLEUUID NimBLEUUID
82# define BLEAddress NimBLEAddress
83# define BLEUtils NimBLEUtils
84# define BLEClientCallbacks NimBLEClientCallbacks
85# define BLEAdvertisedDeviceCallbacks NimBLEScanCallbacks
86# define BLEScanResults NimBLEScanResults
87# define BLEServer NimBLEServer
88# define BLEService NimBLEService
89# define BLECharacteristic NimBLECharacteristic
90# define BLEAdvertising NimBLEAdvertising
91# define BLEServerCallbacks NimBLEServerCallbacks
92# define BLECharacteristicCallbacks NimBLECharacteristicCallbacks
93# define BLEAdvertisementData NimBLEAdvertisementData
94# define BLEDescriptor NimBLEDescriptor
95# define BLE2904 NimBLE2904
96# define BLEDescriptorCallbacks NimBLEDescriptorCallbacks
97# define BLEBeacon NimBLEBeacon
98# define BLEEddystoneTLM NimBLEEddystoneTLM
99# define BLEEddystoneURL NimBLEEddystoneURL
100# define BLEConnInfo NimBLEConnInfo
101# define BLEL2CAPServer NimBLEL2CAPServer
102# define BLEL2CAPService NimBLEL2CAPService
103# define BLEL2CAPServiceCallbacks NimBLEL2CAPServiceCallbacks
104# define BLEL2CAPClient NimBLEL2CAPClient
105# define BLEL2CAPClientCallbacks NimBLEL2CAPClientCallbacks
106# define BLEL2CAPChannel NimBLEL2CAPChannel
107# define BLEL2CAPChannelCallbacks NimBLEL2CAPChannelCallbacks
108
109# ifdef CONFIG_BT_NIMBLE_MAX_CONNECTIONS
110# define NIMBLE_MAX_CONNECTIONS CONFIG_BT_NIMBLE_MAX_CONNECTIONS
111# else
112# define NIMBLE_MAX_CONNECTIONS CONFIG_NIMBLE_MAX_CONNECTIONS
113# endif
114
115enum class NimBLETxPowerType { All = 0, Advertise = 1, Scan = 2, Connection = 3 };
116
117typedef int (*gap_event_handler)(ble_gap_event* event, void* arg);
118
123 public:
124 static bool init(const std::string& deviceName);
125 static bool deinit(bool clearAll = false);
126 static bool setDeviceName(const std::string& deviceName);
127 static bool isInitialized();
128 static NimBLEAddress getAddress();
129 static std::string toString();
130 static bool whiteListAdd(const NimBLEAddress& address);
131 static bool whiteListRemove(const NimBLEAddress& address);
132 static bool onWhiteList(const NimBLEAddress& address);
133 static size_t getWhiteListCount();
134 static NimBLEAddress getWhiteListAddress(size_t index);
135 static bool setOwnAddrType(uint8_t type);
136 static bool setOwnAddr(const NimBLEAddress& addr);
137 static bool setOwnAddr(const uint8_t* addr);
138 static void setDeviceCallbacks(NimBLEDeviceCallbacks* cb);
139 static void setScanDuplicateCacheSize(uint16_t cacheSize);
140 static void setScanFilterMode(uint8_t type);
141 static void setScanDuplicateCacheResetTime(uint16_t time);
142 static bool setCustomGapHandler(gap_event_handler handler);
143 static void setSecurityAuth(bool bonding, bool mitm, bool sc);
144 static void setSecurityAuth(uint8_t auth);
145 static void setSecurityIOCap(uint8_t iocap);
146 static void setSecurityInitKey(uint8_t initKey);
147 static void setSecurityRespKey(uint8_t respKey);
148 static void setSecurityPasskey(uint32_t passKey);
149 static uint32_t getSecurityPasskey();
150 static bool startSecurity(uint16_t connHandle, int* rcPtr = nullptr);
151 static bool setMTU(uint16_t mtu);
152 static uint16_t getMTU();
153 static void onReset(int reason);
154 static void onSync(void);
155 static void host_task(void* param);
156 static int getPower(NimBLETxPowerType type = NimBLETxPowerType::All);
157 static bool setPower(int8_t dbm, NimBLETxPowerType type = NimBLETxPowerType::All);
158 static bool setDefaultPhy(uint8_t txPhyMask, uint8_t rxPhyMask);
159
160# ifdef ESP_PLATFORM
161# ifndef CONFIG_IDF_TARGET_ESP32P4
162 static esp_power_level_t getPowerLevel(esp_ble_power_type_t powerType = ESP_BLE_PWR_TYPE_DEFAULT);
163 static bool setPowerLevel(esp_power_level_t powerLevel, esp_ble_power_type_t powerType = ESP_BLE_PWR_TYPE_DEFAULT);
164# endif
165# endif
166
167# if defined(CONFIG_BT_NIMBLE_ROLE_OBSERVER)
168 static NimBLEScan* getScan();
169# endif
170
171# if defined(CONFIG_BT_NIMBLE_ROLE_PERIPHERAL)
172 static NimBLEServer* createServer();
173 static NimBLEServer* getServer();
174# if CONFIG_BT_NIMBLE_L2CAP_COC_MAX_NUM > 0
175 static NimBLEL2CAPServer* createL2CAPServer();
176 static NimBLEL2CAPServer* getL2CAPServer();
177# endif
178# endif
179
180# if defined(CONFIG_BT_NIMBLE_ROLE_PERIPHERAL) || defined(CONFIG_BT_NIMBLE_ROLE_CENTRAL)
181 static bool injectConfirmPasskey(const NimBLEConnInfo& peerInfo, bool accept);
182 static bool injectPassKey(const NimBLEConnInfo& peerInfo, uint32_t pin);
183# endif
184
185# if defined(CONFIG_BT_NIMBLE_ROLE_BROADCASTER)
186# if CONFIG_BT_NIMBLE_EXT_ADV
188 static bool startAdvertising(uint8_t instId, int duration = 0, int maxEvents = 0);
189 static bool stopAdvertising(uint8_t instId);
190 static bool stopAdvertising();
191# endif
192# if !CONFIG_BT_NIMBLE_EXT_ADV || defined(_DOXYGEN_)
194 static bool startAdvertising(uint32_t duration = 0);
195 static bool stopAdvertising();
196# endif
197# endif
198
199# if defined(CONFIG_BT_NIMBLE_ROLE_CENTRAL)
200 static NimBLEClient* createClient();
201 static NimBLEClient* createClient(const NimBLEAddress& peerAddress);
202 static bool deleteClient(NimBLEClient* pClient);
203 static NimBLEClient* getClientByHandle(uint16_t connHandle);
204 static NimBLEClient* getClientByPeerAddress(const NimBLEAddress& peerAddress);
206 static size_t getCreatedClientCount();
207 static std::vector<NimBLEClient*> getConnectedClients();
208# endif
209
210# if defined(CONFIG_BT_NIMBLE_ROLE_CENTRAL) || defined(CONFIG_BT_NIMBLE_ROLE_PERIPHERAL)
211 static bool deleteBond(const NimBLEAddress& address);
212 static int getNumBonds();
213 static bool isBonded(const NimBLEAddress& address);
214 static bool deleteAllBonds();
215 static NimBLEAddress getBondedAddress(int index);
216# endif
217
218 private:
219 static bool m_synced;
220 static bool m_initialized;
221 static uint32_t m_passkey;
222 static ble_gap_event_listener m_listener;
223 static uint8_t m_ownAddrType;
224 static std::vector<NimBLEAddress> m_whiteList;
225 static NimBLEDeviceCallbacks* m_pDeviceCallbacks;
226 static NimBLEDeviceCallbacks defaultDeviceCallbacks;
227
228# if defined(CONFIG_BT_NIMBLE_ROLE_OBSERVER)
229 static NimBLEScan* m_pScan;
230# endif
231
232# if defined(CONFIG_BT_NIMBLE_ROLE_PERIPHERAL)
233 static NimBLEServer* m_pServer;
234# if CONFIG_BT_NIMBLE_L2CAP_COC_MAX_NUM > 0
235 static NimBLEL2CAPServer* m_pL2CAPServer;
236# endif
237# endif
238
239# if defined(CONFIG_BT_NIMBLE_ROLE_BROADCASTER)
240# if CONFIG_BT_NIMBLE_EXT_ADV
241 static NimBLEExtAdvertising* m_bleAdvertising;
242# else
243 static NimBLEAdvertising* m_bleAdvertising;
244# endif
245# endif
246
247# if defined(CONFIG_BT_NIMBLE_ROLE_CENTRAL)
248 static std::array<NimBLEClient*, NIMBLE_MAX_CONNECTIONS> m_pClients;
249# endif
250
251# ifdef ESP_PLATFORM
252# if CONFIG_BTDM_BLE_SCAN_DUPL || CONFIG_BT_LE_SCAN_DUPL
253 static uint16_t m_scanDuplicateSize;
254 static uint8_t m_scanFilterMode;
255 static uint16_t m_scanDuplicateResetTime;
256# endif
257# endif
258
259# if defined(CONFIG_BT_NIMBLE_ROLE_CENTRAL)
260 friend class NimBLEClient;
261# endif
262
263# if defined(CONFIG_BT_NIMBLE_ROLE_OBSERVER)
264 friend class NimBLEScan;
265# endif
266
267# if defined(CONFIG_BT_NIMBLE_ROLE_PERIPHERAL)
268 friend class NimBLEServer;
269 friend class NimBLECharacteristic;
270# endif
271
272# if defined(CONFIG_BT_NIMBLE_ROLE_BROADCASTER)
273 friend class NimBLEAdvertising;
274# if CONFIG_BT_NIMBLE_EXT_ADV
275 friend class NimBLEExtAdvertising;
276 friend class NimBLEExtAdvertisement;
277# endif
278# endif
279};
280
281# if defined(CONFIG_BT_NIMBLE_ROLE_CENTRAL)
282# include "NimBLEClient.h"
283# include "NimBLERemoteService.h"
284# include "NimBLERemoteCharacteristic.h"
285# include "NimBLERemoteDescriptor.h"
286# endif
287
288# if defined(CONFIG_BT_NIMBLE_ROLE_OBSERVER)
289# include "NimBLEScan.h"
290# endif
291
292# if defined(CONFIG_BT_NIMBLE_ROLE_PERIPHERAL)
293# include "NimBLEServer.h"
294# include "NimBLEService.h"
295# include "NimBLECharacteristic.h"
296# include "NimBLEDescriptor.h"
297# if CONFIG_BT_NIMBLE_L2CAP_COC_MAX_NUM > 0
298# include "NimBLEL2CAPServer.h"
299# include "NimBLEL2CAPChannel.h"
300# endif
301# endif
302
303# if defined(CONFIG_BT_NIMBLE_ROLE_BROADCASTER)
304# if CONFIG_BT_NIMBLE_EXT_ADV
305# include "NimBLEExtAdvertising.h"
306# else
307# include "NimBLEAdvertising.h"
308# endif
309# endif
310
311# if defined(CONFIG_BT_NIMBLE_ROLE_CENTRAL) || defined(CONFIG_BT_NIMBLE_ROLE_PERIPHERAL)
312# include "NimBLEConnInfo.h"
313# endif
314
315# include "NimBLEUtils.h"
316
321 public:
322 virtual ~NimBLEDeviceCallbacks() {};
323
336 virtual int onStoreStatus(struct ble_store_status_event* event, void* arg);
337};
338
339#endif // CONFIG_BT_ENABLED
340#endif // NIMBLE_CPP_DEVICE_H_
A BLE device address.
Definition NimBLEAddress.h:41
Perform and manage BLE advertising.
Definition NimBLEAdvertising.h:52
The model of a BLE Characteristic.
Definition NimBLECharacteristic.h:40
A model of a BLE client.
Definition NimBLEClient.h:49
Connection information.
Definition NimBLEConnInfo.h:32
Callbacks associated with a BLE device.
Definition NimBLEDevice.h:320
virtual int onStoreStatus(struct ble_store_status_event *event, void *arg)
Indicates an inability to perform a store operation. This callback should do one of two things: -Addr...
Definition NimBLEDevice.cpp:1356
A model of a BLE Device from which all the BLE roles are created.
Definition NimBLEDevice.h:122
static NimBLEClient * createClient()
Creates a new client object, each client can connect to 1 peripheral device.
Definition NimBLEDevice.cpp:349
static void onSync(void)
Host synced with controller, all clear to make calls to the stack.
Definition NimBLEDevice.cpp:835
static size_t getCreatedClientCount()
Get the number of created client objects.
Definition NimBLEDevice.cpp:409
static bool setDefaultPhy(uint8_t txPhyMask, uint8_t rxPhyMask)
Set the preferred default phy to use for connections.
Definition NimBLEDevice.cpp:809
static bool setOwnAddr(const NimBLEAddress &addr)
Set the device address to use.
Definition NimBLEDevice.cpp:1145
static NimBLEClient * getDisconnectedClient()
Finds the first disconnected client available.
Definition NimBLEDevice.cpp:454
static bool isBonded(const NimBLEAddress &address)
Checks if a peer device is bonded.
Definition NimBLEDevice.cpp:672
static bool setCustomGapHandler(gap_event_handler handler)
Set a custom callback for gap events.
Definition NimBLEDevice.cpp:1319
static bool deleteAllBonds()
Deletes all bonding information.
Definition NimBLEDevice.cpp:649
static bool startAdvertising(uint8_t instId, int duration=0, int maxEvents=0)
Convenience function to begin advertising.
Definition NimBLEDevice.cpp:206
static void onReset(int reason)
Host reset, we pass the message so we don't make calls until re-synced.
Definition NimBLEDevice.cpp:822
static bool deleteBond(const NimBLEAddress &address)
Deletes a peer bond.
Definition NimBLEDevice.cpp:663
static bool init(const std::string &deviceName)
Initialize the BLE environment.
Definition NimBLEDevice.cpp:894
static bool setOwnAddrType(uint8_t type)
Sets the address type to use.
Definition NimBLEDevice.cpp:1116
static bool stopAdvertising()
Convenience function to stop all advertising.
Definition NimBLEDevice.cpp:246
static NimBLEServer * getServer()
Get the instance of the server.
Definition NimBLEDevice.cpp:155
static bool isInitialized()
Check if the initialization is complete.
Definition NimBLEDevice.cpp:1082
static bool setMTU(uint16_t mtu)
Setup local mtu that will be used to negotiate mtu during request from client peer.
Definition NimBLEDevice.cpp:609
static NimBLEAddress getWhiteListAddress(size_t index)
Gets the address at the vector index.
Definition NimBLEDevice.cpp:782
static NimBLEServer * createServer()
Create an instance of a server.
Definition NimBLEDevice.cpp:140
static bool injectPassKey(const NimBLEConnInfo &peerInfo, uint32_t pin)
Inject the provided passkey into the Security Manager.
Definition NimBLEDevice.cpp:1276
static uint16_t getMTU()
Get local MTU value set.
Definition NimBLEDevice.cpp:622
static int getPower(NimBLETxPowerType type=NimBLETxPowerType::All)
Get the transmission power.
Definition NimBLEDevice.cpp:568
static bool deinit(bool clearAll=false)
Shutdown the NimBLE stack/controller.
Definition NimBLEDevice.cpp:1021
static NimBLEAddress getAddress()
Get our device address.
Definition NimBLEDevice.cpp:1094
static int getNumBonds()
Gets the number of bonded peers stored.
Definition NimBLEDevice.cpp:634
static bool whiteListRemove(const NimBLEAddress &address)
Remove a peer address from the whitelist.
Definition NimBLEDevice.cpp:751
static bool deleteClient(NimBLEClient *pClient)
Delete the client object and remove it from the list. Checks if it is connected or trying to connect ...
Definition NimBLEDevice.cpp:376
static bool startSecurity(uint16_t connHandle, int *rcPtr=nullptr)
Start the connection securing and authorization for this connection.
Definition NimBLEDevice.cpp:1258
static NimBLEClient * getClientByHandle(uint16_t connHandle)
Get a reference to a client by connection handle.
Definition NimBLEDevice.cpp:425
static uint32_t getSecurityPasskey()
Get the current passkey used for pairing.
Definition NimBLEDevice.cpp:1248
static void setSecurityAuth(bool bonding, bool mitm, bool sc)
Set the authorization mode for this device.
Definition NimBLEDevice.cpp:1175
static NimBLEExtAdvertising * getAdvertising()
Get the instance of the extended advertising object.
Definition NimBLEDevice.cpp:191
static bool setDeviceName(const std::string &deviceName)
Set the BLEDevice name.
Definition NimBLEDevice.cpp:1304
static bool whiteListAdd(const NimBLEAddress &address)
Add a peer address to the whitelist.
Definition NimBLEDevice.cpp:732
static void setSecurityInitKey(uint8_t initKey)
If we are the initiator of the security procedure this sets the keys we will distribute.
Definition NimBLEDevice.cpp:1219
static size_t getWhiteListCount()
Gets the count of addresses in the whitelist.
Definition NimBLEDevice.cpp:773
static void host_task(void *param)
The main host task.
Definition NimBLEDevice.cpp:884
static void setSecurityPasskey(uint32_t passKey)
Set the passkey the server will ask for when pairing.
Definition NimBLEDevice.cpp:1240
static void setSecurityRespKey(uint8_t respKey)
Set the keys we are willing to accept during pairing.
Definition NimBLEDevice.cpp:1232
static void setSecurityIOCap(uint8_t iocap)
Set the Input/Output capabilities of this device.
Definition NimBLEDevice.cpp:1206
static std::string toString()
Return a string representation of the address of this device.
Definition NimBLEDevice.cpp:1335
static bool setPower(int8_t dbm, NimBLETxPowerType type=NimBLETxPowerType::All)
Set the transmission power.
Definition NimBLEDevice.cpp:525
static NimBLEAddress getBondedAddress(int index)
Get the address of a bonded peer device by index.
Definition NimBLEDevice.cpp:696
static std::vector< NimBLEClient * > getConnectedClients()
Get a list of connected clients.
Definition NimBLEDevice.cpp:468
static bool onWhiteList(const NimBLEAddress &address)
Checks if a peer device is whitelisted.
Definition NimBLEDevice.cpp:717
static NimBLEScan * getScan()
Retrieve the Scan object that we use for scanning.
Definition NimBLEDevice.cpp:261
static NimBLEClient * getClientByPeerAddress(const NimBLEAddress &peerAddress)
Get a reference to a client by peer address.
Definition NimBLEDevice.cpp:440
static bool injectConfirmPasskey(const NimBLEConnInfo &peerInfo, bool accept)
Inject the provided numeric comparison response into the Security Manager.
Definition NimBLEDevice.cpp:1288
Extended advertisement data.
Definition NimBLEExtAdvertising.h:46
Extended advertising class.
Definition NimBLEExtAdvertising.h:110
L2CAP server class.
Definition NimBLEL2CAPServer.h:20
Perform and manage BLE scans.
Definition NimBLEScan.h:67
The model of a BLE server.
Definition NimBLEServer.h:60