esp-nimble-cpp 2.6.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 "NimBLECppVersion.h"
22#include "syscfg/syscfg.h"
23#if CONFIG_BT_NIMBLE_ENABLED
24# ifdef ESP_PLATFORM
25# ifndef CONFIG_IDF_TARGET_ESP32P4
26# include <esp_bt.h>
27# endif
28# define NIMBLE_CPP_SCAN_DUPL_ENABLED \
29 (CONFIG_BTDM_BLE_SCAN_DUPL || CONFIG_BT_LE_SCAN_DUPL || CONFIG_BT_CTRL_BLE_SCAN_DUPL)
30# endif
31
32# ifdef USING_NIMBLE_ARDUINO_HEADERS
33# include "nimble/nimble/host/include/host/ble_gap.h"
34# else
35# include "host/ble_gap.h"
36# endif
37
38/**** FIX COMPILATION ****/
39# undef min
40# undef max
41/**************************/
42
43# include <string>
44# include <vector>
45# include <atomic>
46
47# if MYNEWT_VAL(BLE_ROLE_CENTRAL)
48# include <array>
49class NimBLEClient;
50# endif
51
52# if MYNEWT_VAL(BLE_ROLE_OBSERVER)
53class NimBLEScan;
54# endif
55
56# if MYNEWT_VAL(BLE_ROLE_BROADCASTER)
57# if MYNEWT_VAL(BLE_EXT_ADV)
58class NimBLEExtAdvertising;
59# else
61# endif
62# endif
63
64# if MYNEWT_VAL(BLE_ROLE_PERIPHERAL)
65class NimBLEServer;
66# if MYNEWT_VAL(BLE_L2CAP_COC_MAX_NUM)
67class NimBLEL2CAPServer;
68# endif
69# endif
70
71# if MYNEWT_VAL(BLE_ROLE_PERIPHERAL) || MYNEWT_VAL(BLE_ROLE_CENTRAL)
72class NimBLEConnInfo;
73# endif
74
75class NimBLEAddress;
77
78# define BLEDevice NimBLEDevice
79# define BLEClient NimBLEClient
80# define BLERemoteService NimBLERemoteService
81# define BLERemoteCharacteristic NimBLERemoteCharacteristic
82# define BLERemoteDescriptor NimBLERemoteDescriptor
83# define BLEAdvertisedDevice NimBLEAdvertisedDevice
84# define BLEScan NimBLEScan
85# define BLEUUID NimBLEUUID
86# define BLEAddress NimBLEAddress
87# define BLEUtils NimBLEUtils
88# define BLEClientCallbacks NimBLEClientCallbacks
89# define BLEAdvertisedDeviceCallbacks NimBLEScanCallbacks
90# define BLEScanResults NimBLEScanResults
91# define BLEServer NimBLEServer
92# define BLEService NimBLEService
93# define BLECharacteristic NimBLECharacteristic
94# define BLEAdvertising NimBLEAdvertising
95# define BLEServerCallbacks NimBLEServerCallbacks
96# define BLECharacteristicCallbacks NimBLECharacteristicCallbacks
97# define BLEAdvertisementData NimBLEAdvertisementData
98# define BLEDescriptor NimBLEDescriptor
99# define BLE2904 NimBLE2904
100# define BLEDescriptorCallbacks NimBLEDescriptorCallbacks
101# define BLEBeacon NimBLEBeacon
102# define BLEEddystoneTLM NimBLEEddystoneTLM
103# define BLEEddystoneURL NimBLEEddystoneURL
104# define BLEConnInfo NimBLEConnInfo
105# define BLEL2CAPServer NimBLEL2CAPServer
106# define BLEL2CAPService NimBLEL2CAPService
107# define BLEL2CAPServiceCallbacks NimBLEL2CAPServiceCallbacks
108# define BLEL2CAPClient NimBLEL2CAPClient
109# define BLEL2CAPClientCallbacks NimBLEL2CAPClientCallbacks
110# define BLEL2CAPChannel NimBLEL2CAPChannel
111# define BLEL2CAPChannelCallbacks NimBLEL2CAPChannelCallbacks
112
113enum class NimBLETxPowerType { All = 0, Advertise = 1, Scan = 2, Connection = 3 };
114
115typedef int (*gap_event_handler)(ble_gap_event* event, void* arg);
116
121 public:
122 static bool init(const std::string& deviceName);
123 static bool deinit(bool clearAll = false);
124 static bool setDeviceName(const std::string& deviceName);
125 static bool isInitialized();
126 static NimBLEAddress getAddress();
127 static std::string toString();
128 static const char* getVersion();
129 static bool whiteListAdd(const NimBLEAddress& address);
130 static bool whiteListRemove(const NimBLEAddress& address);
131 static bool onWhiteList(const NimBLEAddress& address);
132 static size_t getWhiteListCount();
133 static NimBLEAddress getWhiteListAddress(size_t index);
134 static bool setOwnAddrType(uint8_t type);
135 static bool setOwnAddr(const NimBLEAddress& addr);
136 static bool setOwnAddr(const uint8_t* addr);
137 static void setDeviceCallbacks(NimBLEDeviceCallbacks* cb);
138 static void setScanDuplicateCacheSize(uint16_t cacheSize);
139 static void setScanFilterMode(uint8_t type);
140 static void setScanDuplicateCacheResetTime(uint16_t time);
141 static bool setCustomGapHandler(gap_event_handler handler, void* arg = nullptr);
142 static void setSecurityAuth(bool bonding, bool mitm, bool sc);
143 static void setSecurityAuth(uint8_t auth);
144 static void setSecurityIOCap(uint8_t iocap);
145 static void setSecurityInitKey(uint8_t initKey);
146 static void setSecurityRespKey(uint8_t respKey);
147 static void setSecurityPasskey(uint32_t passKey);
148 static uint32_t getSecurityPasskey();
149 static bool startSecurity(uint16_t connHandle, int* rcPtr = nullptr);
150 static bool setMTU(uint16_t mtu);
151 static uint16_t getMTU();
152 static void onReset(int reason);
153 static void onSync(void);
154 static void host_task(void* param);
155 static int getPower(NimBLETxPowerType type = NimBLETxPowerType::All);
156 static bool setPower(int8_t dbm, NimBLETxPowerType type = NimBLETxPowerType::All);
157 static bool setDefaultPhy(uint8_t txPhyMask, uint8_t rxPhyMask);
158
159# ifdef ESP_PLATFORM
160# ifndef CONFIG_IDF_TARGET_ESP32P4
161 static esp_power_level_t getPowerLevel(esp_ble_power_type_t powerType = ESP_BLE_PWR_TYPE_DEFAULT);
162 static bool setPowerLevel(esp_power_level_t powerLevel, esp_ble_power_type_t powerType = ESP_BLE_PWR_TYPE_DEFAULT);
163# endif
164# endif
165
166# if MYNEWT_VAL(BLE_ROLE_OBSERVER)
167 static NimBLEScan* getScan();
168# endif
169
170# if MYNEWT_VAL(BLE_ROLE_PERIPHERAL)
171 static NimBLEServer* createServer();
172 static NimBLEServer* getServer();
173# if MYNEWT_VAL(BLE_L2CAP_COC_MAX_NUM)
174 static NimBLEL2CAPServer* createL2CAPServer();
175 static NimBLEL2CAPServer* getL2CAPServer();
176# endif
177# endif
178
179# if MYNEWT_VAL(BLE_ROLE_PERIPHERAL) || MYNEWT_VAL(BLE_ROLE_CENTRAL)
180 static bool injectConfirmPasskey(const NimBLEConnInfo& peerInfo, bool accept);
181 static bool injectPassKey(const NimBLEConnInfo& peerInfo, uint32_t pin);
182# endif
183
184# if MYNEWT_VAL(BLE_ROLE_BROADCASTER)
185# if MYNEWT_VAL(BLE_EXT_ADV)
186 static NimBLEExtAdvertising* getAdvertising();
187 static bool startAdvertising(uint8_t instId, int duration = 0, int maxEvents = 0);
188 static bool stopAdvertising(uint8_t instId);
189 static bool stopAdvertising();
190# endif
191# if !MYNEWT_VAL(BLE_EXT_ADV) || defined(_DOXYGEN_)
192 static NimBLEAdvertising* getAdvertising();
193 static bool startAdvertising(uint32_t duration = 0);
194 static bool stopAdvertising();
195# endif
196# endif
197
198# if MYNEWT_VAL(BLE_ROLE_CENTRAL)
199 static NimBLEClient* createClient();
200 static NimBLEClient* createClient(const NimBLEAddress& peerAddress);
201 static bool deleteClient(NimBLEClient* pClient);
202 static NimBLEClient* getClientByHandle(uint16_t connHandle);
203 static NimBLEClient* getClientByPeerAddress(const NimBLEAddress& peerAddress);
204 static NimBLEClient* getDisconnectedClient();
205 static size_t getCreatedClientCount();
206 static std::vector<NimBLEClient*> getConnectedClients();
207# endif
208
209# if MYNEWT_VAL(BLE_ROLE_CENTRAL) || MYNEWT_VAL(BLE_ROLE_PERIPHERAL)
210 static bool deleteBond(const NimBLEAddress& address);
211 static int getNumBonds();
212 static bool isBonded(const NimBLEAddress& address);
213 static bool deleteAllBonds();
214 static NimBLEAddress getBondedAddress(int index);
215# endif
216
217 private:
218 static std::atomic<bool> m_synced;
219 static std::atomic<bool> m_initialized;
220 static uint32_t m_passkey;
221 static ble_gap_event_listener m_listener;
222 static uint8_t m_ownAddrType;
223 static std::vector<NimBLEAddress> m_whiteList;
224 static NimBLEDeviceCallbacks* m_pDeviceCallbacks;
225 static NimBLEDeviceCallbacks defaultDeviceCallbacks;
226
227# if MYNEWT_VAL(BLE_ROLE_OBSERVER)
228 static NimBLEScan* m_pScan;
229# endif
230
231# if MYNEWT_VAL(BLE_ROLE_PERIPHERAL)
232 static NimBLEServer* m_pServer;
233# if MYNEWT_VAL(BLE_L2CAP_COC_MAX_NUM)
234 static NimBLEL2CAPServer* m_pL2CAPServer;
235# endif
236# endif
237
238# if MYNEWT_VAL(BLE_ROLE_BROADCASTER)
239# if MYNEWT_VAL(BLE_EXT_ADV)
240 static NimBLEExtAdvertising* m_bleAdvertising;
241# else
242 static NimBLEAdvertising* m_bleAdvertising;
243# endif
244# endif
245
246# if MYNEWT_VAL(BLE_ROLE_CENTRAL)
247 static std::array<NimBLEClient*, MYNEWT_VAL(BLE_MAX_CONNECTIONS)> m_pClients;
248# endif
249
250# ifdef ESP_PLATFORM
251# if NIMBLE_CPP_SCAN_DUPL_ENABLED
252 static uint16_t m_scanDuplicateSize;
253 static uint8_t m_scanFilterMode;
254 static uint16_t m_scanDuplicateResetTime;
255# endif
256# endif
257
258# if MYNEWT_VAL(BLE_ROLE_CENTRAL)
259 friend class NimBLEClient;
260# endif
261
262# if MYNEWT_VAL(BLE_ROLE_OBSERVER)
263 friend class NimBLEScan;
264# endif
265
266# if MYNEWT_VAL(BLE_ROLE_PERIPHERAL)
267 friend class NimBLEServer;
268 friend class NimBLECharacteristic;
269# endif
270
271# if MYNEWT_VAL(BLE_ROLE_BROADCASTER)
272 friend class NimBLEAdvertising;
273# if MYNEWT_VAL(BLE_EXT_ADV)
274 friend class NimBLEExtAdvertising;
275 friend class NimBLEExtAdvertisement;
276# endif
277# endif
278};
279
280# if MYNEWT_VAL(BLE_ROLE_CENTRAL)
281# include "NimBLEClient.h"
282# include "NimBLERemoteService.h"
283# include "NimBLERemoteCharacteristic.h"
284# include "NimBLERemoteDescriptor.h"
285# endif
286
287# if MYNEWT_VAL(BLE_ROLE_OBSERVER)
288# include "NimBLEScan.h"
289# endif
290
291# if MYNEWT_VAL(BLE_ROLE_PERIPHERAL)
292# include "NimBLEServer.h"
293# include "NimBLEService.h"
294# include "NimBLECharacteristic.h"
295# include "NimBLEDescriptor.h"
296# if MYNEWT_VAL(BLE_L2CAP_COC_MAX_NUM)
297# include "NimBLEL2CAPServer.h"
298# include "NimBLEL2CAPChannel.h"
299# endif
300# endif
301
302# if MYNEWT_VAL(BLE_ROLE_BROADCASTER)
303# if MYNEWT_VAL(BLE_EXT_ADV)
304# include "NimBLEExtAdvertising.h"
305# else
306# include "NimBLEAdvertising.h"
307# endif
308# endif
309
310# if MYNEWT_VAL(BLE_ROLE_CENTRAL) || MYNEWT_VAL(BLE_ROLE_PERIPHERAL)
311# include "NimBLEConnInfo.h"
312# include "NimBLEStream.h"
313# endif
314
315# include "NimBLEAddress.h"
316# include "NimBLEUtils.h"
317
322 public:
323 virtual ~NimBLEDeviceCallbacks() {};
324
337 virtual int onStoreStatus(struct ble_store_status_event* event, void* arg);
338};
339
340#endif // CONFIG_BT_NIMBLE_ENABLED
341#endif // NIMBLE_CPP_DEVICE_H_
A BLE device address.
Definition NimBLEAddress.h:42
Perform and manage BLE advertising.
Definition NimBLEAdvertising.h:51
Connection information.
Definition NimBLEConnInfo.h:33
Callbacks associated with a BLE device.
Definition NimBLEDevice.h:321
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:1404
A model of a BLE Device from which all the BLE roles are created.
Definition NimBLEDevice.h:120
static void onSync(void)
Host synced with controller, all clear to make calls to the stack.
Definition NimBLEDevice.cpp:835
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:1169
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 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:1140
static bool isInitialized()
Check if the initialization is complete.
Definition NimBLEDevice.cpp:1106
static bool setMTU(uint16_t mtu)
Setup local mtu that will be used to negotiate mtu during request from client peer.
Definition NimBLEDevice.cpp:591
static NimBLEAddress getWhiteListAddress(size_t index)
Gets the address at the vector index.
Definition NimBLEDevice.cpp:782
static uint16_t getMTU()
Get local MTU value set.
Definition NimBLEDevice.cpp:604
static int getPower(NimBLETxPowerType type=NimBLETxPowerType::All)
Get the transmission power.
Definition NimBLEDevice.cpp:550
static bool deinit(bool clearAll=false)
Shutdown the NimBLE stack/controller.
Definition NimBLEDevice.cpp:1035
static NimBLEAddress getAddress()
Get our device address.
Definition NimBLEDevice.cpp:1118
static bool whiteListRemove(const NimBLEAddress &address)
Remove a peer address from the whitelist.
Definition NimBLEDevice.cpp:747
static bool startSecurity(uint16_t connHandle, int *rcPtr=nullptr)
Start the connection securing and authorization for this connection.
Definition NimBLEDevice.cpp:1282
static uint32_t getSecurityPasskey()
Get the current passkey used for pairing.
Definition NimBLEDevice.cpp:1272
static void setSecurityAuth(bool bonding, bool mitm, bool sc)
Set the authorization mode for this device.
Definition NimBLEDevice.cpp:1199
static bool setDeviceName(const std::string &deviceName)
Set the BLEDevice name.
Definition NimBLEDevice.cpp:1342
static bool whiteListAdd(const NimBLEAddress &address)
Add a peer address to the whitelist.
Definition NimBLEDevice.cpp:728
static bool setCustomGapHandler(gap_event_handler handler, void *arg=nullptr)
Set a custom callback for gap events.
Definition NimBLEDevice.cpp:1359
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:1243
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:1264
static void setSecurityRespKey(uint8_t respKey)
Set the keys we are willing to accept during pairing.
Definition NimBLEDevice.cpp:1256
static void setSecurityIOCap(uint8_t iocap)
Set the Input/Output capabilities of this device.
Definition NimBLEDevice.cpp:1230
static std::string toString()
Return a string representation of the address of this device.
Definition NimBLEDevice.cpp:1375
static bool setPower(int8_t dbm, NimBLETxPowerType type=NimBLETxPowerType::All)
Retrieve the Scan object that we use for scanning.
Definition NimBLEDevice.cpp:507
static bool onWhiteList(const NimBLEAddress &address)
Checks if a peer device is whitelisted.
Definition NimBLEDevice.cpp:713
static const char * getVersion()
Return the library version as a string.
Definition NimBLEDevice.cpp:1383