esp-nimble-cpp 2.3.3
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 "syscfg/syscfg.h"
22#if CONFIG_BT_NIMBLE_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 MYNEWT_VAL(BLE_ROLE_CENTRAL)
44# include <array>
45class NimBLEClient;
46# endif
47
48# if MYNEWT_VAL(BLE_ROLE_OBSERVER)
49class NimBLEScan;
50# endif
51
52# if MYNEWT_VAL(BLE_ROLE_BROADCASTER)
53# if MYNEWT_VAL(BLE_EXT_ADV)
54class NimBLEExtAdvertising;
55# else
56class NimBLEAdvertising;
57# endif
58# endif
59
60# if MYNEWT_VAL(BLE_ROLE_PERIPHERAL)
61class NimBLEServer;
62# if MYNEWT_VAL(BLE_L2CAP_COC_MAX_NUM)
63class NimBLEL2CAPServer;
64# endif
65# endif
66
67# if MYNEWT_VAL(BLE_ROLE_PERIPHERAL) || MYNEWT_VAL(BLE_ROLE_CENTRAL)
68class NimBLEConnInfo;
69# endif
70
71class NimBLEAddress;
72class NimBLEDeviceCallbacks;
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
109enum class NimBLETxPowerType { All = 0, Advertise = 1, Scan = 2, Connection = 3 };
110
111typedef int (*gap_event_handler)(ble_gap_event* event, void* arg);
112
116class NimBLEDevice {
117 public:
118 static bool init(const std::string& deviceName);
119 static bool deinit(bool clearAll = false);
120 static bool setDeviceName(const std::string& deviceName);
121 static bool isInitialized();
122 static NimBLEAddress getAddress();
123 static std::string toString();
124 static bool whiteListAdd(const NimBLEAddress& address);
125 static bool whiteListRemove(const NimBLEAddress& address);
126 static bool onWhiteList(const NimBLEAddress& address);
127 static size_t getWhiteListCount();
128 static NimBLEAddress getWhiteListAddress(size_t index);
129 static bool setOwnAddrType(uint8_t type);
130 static bool setOwnAddr(const NimBLEAddress& addr);
131 static bool setOwnAddr(const uint8_t* addr);
132 static void setDeviceCallbacks(NimBLEDeviceCallbacks* cb);
133 static void setScanDuplicateCacheSize(uint16_t cacheSize);
134 static void setScanFilterMode(uint8_t type);
135 static void setScanDuplicateCacheResetTime(uint16_t time);
136 static bool setCustomGapHandler(gap_event_handler handler);
137 static void setSecurityAuth(bool bonding, bool mitm, bool sc);
138 static void setSecurityAuth(uint8_t auth);
139 static void setSecurityIOCap(uint8_t iocap);
140 static void setSecurityInitKey(uint8_t initKey);
141 static void setSecurityRespKey(uint8_t respKey);
142 static void setSecurityPasskey(uint32_t passKey);
143 static uint32_t getSecurityPasskey();
144 static bool startSecurity(uint16_t connHandle, int* rcPtr = nullptr);
145 static bool setMTU(uint16_t mtu);
146 static uint16_t getMTU();
147 static void onReset(int reason);
148 static void onSync(void);
149 static void host_task(void* param);
150 static int getPower(NimBLETxPowerType type = NimBLETxPowerType::All);
151 static bool setPower(int8_t dbm, NimBLETxPowerType type = NimBLETxPowerType::All);
152 static bool setDefaultPhy(uint8_t txPhyMask, uint8_t rxPhyMask);
153
154# ifdef ESP_PLATFORM
155# ifndef CONFIG_IDF_TARGET_ESP32P4
156 static esp_power_level_t getPowerLevel(esp_ble_power_type_t powerType = ESP_BLE_PWR_TYPE_DEFAULT);
157 static bool setPowerLevel(esp_power_level_t powerLevel, esp_ble_power_type_t powerType = ESP_BLE_PWR_TYPE_DEFAULT);
158# endif
159# endif
160
161# if MYNEWT_VAL(BLE_ROLE_OBSERVER)
162 static NimBLEScan* getScan();
163# endif
164
165# if MYNEWT_VAL(BLE_ROLE_PERIPHERAL)
166 static NimBLEServer* createServer();
167 static NimBLEServer* getServer();
168# if MYNEWT_VAL(BLE_L2CAP_COC_MAX_NUM)
169 static NimBLEL2CAPServer* createL2CAPServer();
170 static NimBLEL2CAPServer* getL2CAPServer();
171# endif
172# endif
173
174# if MYNEWT_VAL(BLE_ROLE_PERIPHERAL) || MYNEWT_VAL(BLE_ROLE_CENTRAL)
175 static bool injectConfirmPasskey(const NimBLEConnInfo& peerInfo, bool accept);
176 static bool injectPassKey(const NimBLEConnInfo& peerInfo, uint32_t pin);
177# endif
178
179# if MYNEWT_VAL(BLE_ROLE_BROADCASTER)
180# if MYNEWT_VAL(BLE_EXT_ADV)
181 static NimBLEExtAdvertising* getAdvertising();
182 static bool startAdvertising(uint8_t instId, int duration = 0, int maxEvents = 0);
183 static bool stopAdvertising(uint8_t instId);
184 static bool stopAdvertising();
185# endif
186# if !MYNEWT_VAL(BLE_EXT_ADV) || defined(_DOXYGEN_)
187 static NimBLEAdvertising* getAdvertising();
188 static bool startAdvertising(uint32_t duration = 0);
189 static bool stopAdvertising();
190# endif
191# endif
192
193# if MYNEWT_VAL(BLE_ROLE_CENTRAL)
194 static NimBLEClient* createClient();
195 static NimBLEClient* createClient(const NimBLEAddress& peerAddress);
196 static bool deleteClient(NimBLEClient* pClient);
197 static NimBLEClient* getClientByHandle(uint16_t connHandle);
198 static NimBLEClient* getClientByPeerAddress(const NimBLEAddress& peerAddress);
199 static NimBLEClient* getDisconnectedClient();
200 static size_t getCreatedClientCount();
201 static std::vector<NimBLEClient*> getConnectedClients();
202# endif
203
204# if MYNEWT_VAL(BLE_ROLE_CENTRAL) || MYNEWT_VAL(BLE_ROLE_PERIPHERAL)
205 static bool deleteBond(const NimBLEAddress& address);
206 static int getNumBonds();
207 static bool isBonded(const NimBLEAddress& address);
208 static bool deleteAllBonds();
209 static NimBLEAddress getBondedAddress(int index);
210# endif
211
212 private:
213 static bool m_synced;
214 static bool m_initialized;
215 static uint32_t m_passkey;
216 static ble_gap_event_listener m_listener;
217 static uint8_t m_ownAddrType;
218 static std::vector<NimBLEAddress> m_whiteList;
219 static NimBLEDeviceCallbacks* m_pDeviceCallbacks;
220 static NimBLEDeviceCallbacks defaultDeviceCallbacks;
221
222# if MYNEWT_VAL(BLE_ROLE_OBSERVER)
223 static NimBLEScan* m_pScan;
224# endif
225
226# if MYNEWT_VAL(BLE_ROLE_PERIPHERAL)
227 static NimBLEServer* m_pServer;
228# if MYNEWT_VAL(BLE_L2CAP_COC_MAX_NUM)
229 static NimBLEL2CAPServer* m_pL2CAPServer;
230# endif
231# endif
232
233# if MYNEWT_VAL(BLE_ROLE_BROADCASTER)
234# if MYNEWT_VAL(BLE_EXT_ADV)
235 static NimBLEExtAdvertising* m_bleAdvertising;
236# else
237 static NimBLEAdvertising* m_bleAdvertising;
238# endif
239# endif
240
241# if MYNEWT_VAL(BLE_ROLE_CENTRAL)
242 static std::array<NimBLEClient*, MYNEWT_VAL(BLE_MAX_CONNECTIONS)> m_pClients;
243# endif
244
245# ifdef ESP_PLATFORM
246# if CONFIG_BTDM_BLE_SCAN_DUPL || CONFIG_BT_LE_SCAN_DUPL
247 static uint16_t m_scanDuplicateSize;
248 static uint8_t m_scanFilterMode;
249 static uint16_t m_scanDuplicateResetTime;
250# endif
251# endif
252
253# if MYNEWT_VAL(BLE_ROLE_CENTRAL)
254 friend class NimBLEClient;
255# endif
256
257# if MYNEWT_VAL(BLE_ROLE_OBSERVER)
258 friend class NimBLEScan;
259# endif
260
261# if MYNEWT_VAL(BLE_ROLE_PERIPHERAL)
262 friend class NimBLEServer;
263 friend class NimBLECharacteristic;
264# endif
265
266# if MYNEWT_VAL(BLE_ROLE_BROADCASTER)
267 friend class NimBLEAdvertising;
268# if MYNEWT_VAL(BLE_EXT_ADV)
269 friend class NimBLEExtAdvertising;
270 friend class NimBLEExtAdvertisement;
271# endif
272# endif
273};
274
275# if MYNEWT_VAL(BLE_ROLE_CENTRAL)
276# include "NimBLEClient.h"
277# include "NimBLERemoteService.h"
278# include "NimBLERemoteCharacteristic.h"
279# include "NimBLERemoteDescriptor.h"
280# endif
281
282# if MYNEWT_VAL(BLE_ROLE_OBSERVER)
283# include "NimBLEScan.h"
284# endif
285
286# if MYNEWT_VAL(BLE_ROLE_PERIPHERAL)
287# include "NimBLEServer.h"
288# include "NimBLEService.h"
289# include "NimBLECharacteristic.h"
290# include "NimBLEDescriptor.h"
291# if MYNEWT_VAL(BLE_L2CAP_COC_MAX_NUM)
292# include "NimBLEL2CAPServer.h"
293# include "NimBLEL2CAPChannel.h"
294# endif
295# endif
296
297# if MYNEWT_VAL(BLE_ROLE_BROADCASTER)
298# if MYNEWT_VAL(BLE_EXT_ADV)
299# include "NimBLEExtAdvertising.h"
300# else
301# include "NimBLEAdvertising.h"
302# endif
303# endif
304
305# if MYNEWT_VAL(BLE_ROLE_CENTRAL) || MYNEWT_VAL(BLE_ROLE_PERIPHERAL)
306# include "NimBLEConnInfo.h"
307# endif
308
309# include "NimBLEAddress.h"
310# include "NimBLEUtils.h"
311
315class NimBLEDeviceCallbacks {
316 public:
317 virtual ~NimBLEDeviceCallbacks() {};
318
331 virtual int onStoreStatus(struct ble_store_status_event* event, void* arg);
332};
333
334#endif // CONFIG_BT_NIMBLE_ENABLED
335#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:32
NimBLEDeviceCallbacks
Callbacks associated with a BLE device.
Definition NimBLEDevice.h:315
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:1345
NimBLEDevice
A model of a BLE Device from which all the BLE roles are created.
Definition NimBLEDevice.h:116
NimBLEDevice::onSync
static void onSync(void)
Host synced with controller, all clear to make calls to the stack.
Definition NimBLEDevice.cpp:821
NimBLEDevice::setDefaultPhy
static bool setDefaultPhy(uint8_t txPhyMask, uint8_t rxPhyMask)
Set the preferred default phy to use for connections.
Definition NimBLEDevice.cpp:795
NimBLEDevice::setOwnAddr
static bool setOwnAddr(const NimBLEAddress &addr)
Set the device address to use.
Definition NimBLEDevice.cpp:1133
NimBLEDevice::setCustomGapHandler
static bool setCustomGapHandler(gap_event_handler handler)
Set a custom callback for gap events.
Definition NimBLEDevice.cpp:1308
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:808
NimBLEDevice::init
static bool init(const std::string &deviceName)
Initialize the BLE environment.
Definition NimBLEDevice.cpp:880
NimBLEDevice::setOwnAddrType
static bool setOwnAddrType(uint8_t type)
Sets the address type to use.
Definition NimBLEDevice.cpp:1104
NimBLEDevice::isInitialized
static bool isInitialized()
Check if the initialization is complete.
Definition NimBLEDevice.cpp:1070
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:595
NimBLEDevice::getWhiteListAddress
static NimBLEAddress getWhiteListAddress(size_t index)
Gets the address at the vector index.
Definition NimBLEDevice.cpp:768
NimBLEDevice::getMTU
static uint16_t getMTU()
Get local MTU value set.
Definition NimBLEDevice.cpp:608
NimBLEDevice::getPower
static int getPower(NimBLETxPowerType type=NimBLETxPowerType::All)
Get the transmission power.
Definition NimBLEDevice.cpp:554
NimBLEDevice::deinit
static bool deinit(bool clearAll=false)
Shutdown the NimBLE stack/controller.
Definition NimBLEDevice.cpp:1009
NimBLEDevice::getAddress
static NimBLEAddress getAddress()
Get our device address.
Definition NimBLEDevice.cpp:1082
NimBLEDevice::whiteListRemove
static bool whiteListRemove(const NimBLEAddress &address)
Remove a peer address from the whitelist.
Definition NimBLEDevice.cpp:737
NimBLEDevice::startSecurity
static bool startSecurity(uint16_t connHandle, int *rcPtr=nullptr)
Start the connection securing and authorization for this connection.
Definition NimBLEDevice.cpp:1246
NimBLEDevice::getSecurityPasskey
static uint32_t getSecurityPasskey()
Get the current passkey used for pairing.
Definition NimBLEDevice.cpp:1236
NimBLEDevice::setSecurityAuth
static void setSecurityAuth(bool bonding, bool mitm, bool sc)
Set the authorization mode for this device.
Definition NimBLEDevice.cpp:1163
NimBLEDevice::setDeviceName
static bool setDeviceName(const std::string &deviceName)
Set the BLEDevice name.
Definition NimBLEDevice.cpp:1292
NimBLEDevice::whiteListAdd
static bool whiteListAdd(const NimBLEAddress &address)
Add a peer address to the whitelist.
Definition NimBLEDevice.cpp:718
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:1207
NimBLEDevice::getWhiteListCount
static size_t getWhiteListCount()
Gets the count of addresses in the whitelist.
Definition NimBLEDevice.cpp:759
NimBLEDevice::host_task
static void host_task(void *param)
The main host task.
Definition NimBLEDevice.cpp:870
NimBLEDevice::setSecurityPasskey
static void setSecurityPasskey(uint32_t passKey)
Set the passkey the server will ask for when pairing.
Definition NimBLEDevice.cpp:1228
NimBLEDevice::setSecurityRespKey
static void setSecurityRespKey(uint8_t respKey)
Set the keys we are willing to accept during pairing.
Definition NimBLEDevice.cpp:1220
NimBLEDevice::setSecurityIOCap
static void setSecurityIOCap(uint8_t iocap)
Set the Input/Output capabilities of this device.
Definition NimBLEDevice.cpp:1194
NimBLEDevice::toString
static std::string toString()
Return a string representation of the address of this device.
Definition NimBLEDevice.cpp:1324
NimBLEDevice::setPower
static bool setPower(int8_t dbm, NimBLETxPowerType type=NimBLETxPowerType::All)
Retrieve the Scan object that we use for scanning.
Definition NimBLEDevice.cpp:511
NimBLEDevice::onWhiteList
static bool onWhiteList(const NimBLEAddress &address)
Checks if a peer device is whitelisted.
Definition NimBLEDevice.cpp:703