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