NimBLE-Arduino 2.1.2
Loading...
Searching...
No Matches
NimBLEDevice.h
1/*
2 * Copyright 2020-2024 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
54class NimBLEExtAdvertising;
55# else
56class NimBLEAdvertising;
57# endif
58# endif
59
60# if defined(CONFIG_BT_NIMBLE_ROLE_PERIPHERAL)
61class NimBLEServer;
62# endif
63
64# if defined(CONFIG_BT_NIMBLE_ROLE_PERIPHERAL) || defined(CONFIG_BT_NIMBLE_ROLE_CENTRAL)
65class NimBLEConnInfo;
66# endif
67
68class NimBLEAddress;
69
70# define BLEDevice NimBLEDevice
71# define BLEClient NimBLEClient
72# define BLERemoteService NimBLERemoteService
73# define BLERemoteCharacteristic NimBLERemoteCharacteristic
74# define BLERemoteDescriptor NimBLERemoteDescriptor
75# define BLEAdvertisedDevice NimBLEAdvertisedDevice
76# define BLEScan NimBLEScan
77# define BLEUUID NimBLEUUID
78# define BLEAddress NimBLEAddress
79# define BLEUtils NimBLEUtils
80# define BLEClientCallbacks NimBLEClientCallbacks
81# define BLEAdvertisedDeviceCallbacks NimBLEScanCallbacks
82# define BLEScanResults NimBLEScanResults
83# define BLEServer NimBLEServer
84# define BLEService NimBLEService
85# define BLECharacteristic NimBLECharacteristic
86# define BLEAdvertising NimBLEAdvertising
87# define BLEServerCallbacks NimBLEServerCallbacks
88# define BLECharacteristicCallbacks NimBLECharacteristicCallbacks
89# define BLEAdvertisementData NimBLEAdvertisementData
90# define BLEDescriptor NimBLEDescriptor
91# define BLE2904 NimBLE2904
92# define BLEDescriptorCallbacks NimBLEDescriptorCallbacks
93# define BLEBeacon NimBLEBeacon
94# define BLEEddystoneTLM NimBLEEddystoneTLM
95# define BLEEddystoneURL NimBLEEddystoneURL
96# define BLEConnInfo NimBLEConnInfo
97
98# ifdef CONFIG_BT_NIMBLE_MAX_CONNECTIONS
99# define NIMBLE_MAX_CONNECTIONS CONFIG_BT_NIMBLE_MAX_CONNECTIONS
100# else
101# define NIMBLE_MAX_CONNECTIONS CONFIG_NIMBLE_MAX_CONNECTIONS
102# endif
103
104typedef int (*gap_event_handler)(ble_gap_event* event, void* arg);
105
109class NimBLEDevice {
110 public:
111 static bool init(const std::string& deviceName);
112 static bool deinit(bool clearAll = false);
113 static bool setDeviceName(const std::string& deviceName);
114 static bool isInitialized();
115 static NimBLEAddress getAddress();
116 static std::string toString();
117 static bool whiteListAdd(const NimBLEAddress& address);
118 static bool whiteListRemove(const NimBLEAddress& address);
119 static bool onWhiteList(const NimBLEAddress& address);
120 static size_t getWhiteListCount();
121 static NimBLEAddress getWhiteListAddress(size_t index);
122 static bool setOwnAddrType(uint8_t type);
123 static bool setOwnAddr(const NimBLEAddress& addr);
124 static bool setOwnAddr(const uint8_t* addr);
125 static void setScanDuplicateCacheSize(uint16_t cacheSize);
126 static void setScanFilterMode(uint8_t type);
127 static bool setCustomGapHandler(gap_event_handler handler);
128 static void setSecurityAuth(bool bonding, bool mitm, bool sc);
129 static void setSecurityAuth(uint8_t auth);
130 static void setSecurityIOCap(uint8_t iocap);
131 static void setSecurityInitKey(uint8_t initKey);
132 static void setSecurityRespKey(uint8_t respKey);
133 static void setSecurityPasskey(uint32_t passKey);
134 static uint32_t getSecurityPasskey();
135 static bool startSecurity(uint16_t connHandle, int* rcPtr = nullptr);
136 static bool setMTU(uint16_t mtu);
137 static uint16_t getMTU();
138 static void onReset(int reason);
139 static void onSync(void);
140 static void host_task(void* param);
141 static int getPower();
142 static bool setPower(int8_t dbm);
143
144# ifdef ESP_PLATFORM
145# ifndef CONFIG_IDF_TARGET_ESP32P4
146 static esp_power_level_t getPowerLevel(esp_ble_power_type_t powerType = ESP_BLE_PWR_TYPE_DEFAULT);
147 static bool setPowerLevel(esp_power_level_t powerLevel, esp_ble_power_type_t powerType = ESP_BLE_PWR_TYPE_DEFAULT);
148# endif
149# endif
150
151# if CONFIG_BT_NIMBLE_EXT_ADV
152 static bool setDefaultPhy(uint8_t txPhyMask, uint8_t rxPhyMask);
153# endif
154
155# if defined(CONFIG_BT_NIMBLE_ROLE_OBSERVER)
156 static NimBLEScan* getScan();
157# endif
158
159# if defined(CONFIG_BT_NIMBLE_ROLE_PERIPHERAL)
160 static NimBLEServer* createServer();
161 static NimBLEServer* getServer();
162# endif
163
164# if defined(CONFIG_BT_NIMBLE_ROLE_PERIPHERAL) || defined(CONFIG_BT_NIMBLE_ROLE_CENTRAL)
165 static bool injectConfirmPasskey(const NimBLEConnInfo& peerInfo, bool accept);
166 static bool injectPassKey(const NimBLEConnInfo& peerInfo, uint32_t pin);
167# endif
168
169# if defined(CONFIG_BT_NIMBLE_ROLE_BROADCASTER)
170# if CONFIG_BT_NIMBLE_EXT_ADV
171 static NimBLEExtAdvertising* getAdvertising();
172 static bool startAdvertising(uint8_t instId, int duration = 0, int maxEvents = 0);
173 static bool stopAdvertising(uint8_t instId);
174 static bool stopAdvertising();
175# endif
176# if !CONFIG_BT_NIMBLE_EXT_ADV || defined(_DOXYGEN_)
177 static NimBLEAdvertising* getAdvertising();
178 static bool startAdvertising(uint32_t duration = 0);
179 static bool stopAdvertising();
180# endif
181# endif
182
183# if defined(CONFIG_BT_NIMBLE_ROLE_CENTRAL)
184 static NimBLEClient* createClient();
185 static NimBLEClient* createClient(const NimBLEAddress& peerAddress);
186 static bool deleteClient(NimBLEClient* pClient);
187 static NimBLEClient* getClientByHandle(uint16_t connHandle);
188 static NimBLEClient* getClientByPeerAddress(const NimBLEAddress& peerAddress);
189 static NimBLEClient* getDisconnectedClient();
190 static size_t getCreatedClientCount();
191 static std::vector<NimBLEClient*> getConnectedClients();
192# endif
193
194# if defined(CONFIG_BT_NIMBLE_ROLE_CENTRAL) || defined(CONFIG_BT_NIMBLE_ROLE_PERIPHERAL)
195 static bool deleteBond(const NimBLEAddress& address);
196 static int getNumBonds();
197 static bool isBonded(const NimBLEAddress& address);
198 static bool deleteAllBonds();
199 static NimBLEAddress getBondedAddress(int index);
200# endif
201
202 private:
203 static bool m_synced;
204 static bool m_initialized;
205 static uint32_t m_passkey;
206 static ble_gap_event_listener m_listener;
207 static uint8_t m_ownAddrType;
208 static std::vector<NimBLEAddress> m_whiteList;
209
210# if defined(CONFIG_BT_NIMBLE_ROLE_OBSERVER)
211 static NimBLEScan* m_pScan;
212# endif
213
214# if defined(CONFIG_BT_NIMBLE_ROLE_PERIPHERAL)
215 static NimBLEServer* m_pServer;
216# endif
217
218# if defined(CONFIG_BT_NIMBLE_ROLE_BROADCASTER)
219# if CONFIG_BT_NIMBLE_EXT_ADV
220 static NimBLEExtAdvertising* m_bleAdvertising;
221# else
222 static NimBLEAdvertising* m_bleAdvertising;
223# endif
224# endif
225
226# if defined(CONFIG_BT_NIMBLE_ROLE_CENTRAL)
227 static std::array<NimBLEClient*, NIMBLE_MAX_CONNECTIONS> m_pClients;
228# endif
229
230# ifdef ESP_PLATFORM
231# ifdef CONFIG_BTDM_BLE_SCAN_DUPL
232 static uint16_t m_scanDuplicateSize;
233 static uint8_t m_scanFilterMode;
234# endif
235# endif
236
237# if defined(CONFIG_BT_NIMBLE_ROLE_CENTRAL)
238 friend class NimBLEClient;
239# endif
240
241# if defined(CONFIG_BT_NIMBLE_ROLE_OBSERVER)
242 friend class NimBLEScan;
243# endif
244
245# if defined(CONFIG_BT_NIMBLE_ROLE_PERIPHERAL)
246 friend class NimBLEServer;
247 friend class NimBLECharacteristic;
248# endif
249
250# if defined(CONFIG_BT_NIMBLE_ROLE_BROADCASTER)
251 friend class NimBLEAdvertising;
252# if CONFIG_BT_NIMBLE_EXT_ADV
253 friend class NimBLEExtAdvertising;
254 friend class NimBLEExtAdvertisement;
255# endif
256# endif
257};
258
259# if defined(CONFIG_BT_NIMBLE_ROLE_CENTRAL)
260# include "NimBLEClient.h"
261# include "NimBLERemoteService.h"
262# include "NimBLERemoteCharacteristic.h"
263# include "NimBLERemoteDescriptor.h"
264# endif
265
266# if defined(CONFIG_BT_NIMBLE_ROLE_OBSERVER)
267# include "NimBLEScan.h"
268# endif
269
270# if defined(CONFIG_BT_NIMBLE_ROLE_PERIPHERAL)
271# include "NimBLEServer.h"
272# include "NimBLEService.h"
273# include "NimBLECharacteristic.h"
274# include "NimBLEDescriptor.h"
275# endif
276
277# if defined(CONFIG_BT_NIMBLE_ROLE_BROADCASTER)
278# if CONFIG_BT_NIMBLE_EXT_ADV
279# include "NimBLEExtAdvertising.h"
280# else
281# include "NimBLEAdvertising.h"
282# endif
283# endif
284
285# if defined(CONFIG_BT_NIMBLE_ROLE_CENTRAL) || defined(CONFIG_BT_NIMBLE_ROLE_PERIPHERAL)
286# include "NimBLEConnInfo.h"
287# endif
288
289# include "NimBLEUtils.h"
290
291#endif // CONFIG_BT_ENABLED
292#endif // NIMBLE_CPP_DEVICE_H_
NimBLEAddress
A BLE device address.
Definition NimBLEAddress.h:41
NimBLEAdvertising
Perform and manage BLE advertising.
Definition NimBLEAdvertising.h:52
NimBLECharacteristic
The model of a BLE Characteristic.
Definition NimBLECharacteristic.h:40
NimBLEClient
A model of a BLE client.
Definition NimBLEClient.h:49
NimBLEConnInfo
Connection information.
Definition NimBLEConnInfo.h:32
NimBLEDevice
A model of a BLE Device from which all the BLE roles are created.
Definition NimBLEDevice.h:109
NimBLEDevice::createClient
static NimBLEClient * createClient()
Creates a new client object, each client can connect to 1 peripheral device.
Definition NimBLEDevice.cpp:291
NimBLEDevice::onSync
static void onSync(void)
Host synced with controller, all clear to make calls to the stack.
Definition NimBLEDevice.cpp:760
NimBLEDevice::getCreatedClientCount
static size_t getCreatedClientCount()
Get the number of created client objects.
Definition NimBLEDevice.cpp:351
NimBLEDevice::setDefaultPhy
static bool setDefaultPhy(uint8_t txPhyMask, uint8_t rxPhyMask)
Set the preferred default phy to use for connections.
Definition NimBLEDevice.cpp:733
NimBLEDevice::setOwnAddr
static bool setOwnAddr(const NimBLEAddress &addr)
Set the device address to use.
Definition NimBLEDevice.cpp:1033
NimBLEDevice::getDisconnectedClient
static NimBLEClient * getDisconnectedClient()
Finds the first disconnected client available.
Definition NimBLEDevice.cpp:396
NimBLEDevice::isBonded
static bool isBonded(const NimBLEAddress &address)
Checks if a peer device is bonded.
Definition NimBLEDevice.cpp:595
NimBLEDevice::setCustomGapHandler
static bool setCustomGapHandler(gap_event_handler handler)
Set a custom callback for gap events.
Definition NimBLEDevice.cpp:1207
NimBLEDevice::deleteAllBonds
static bool deleteAllBonds()
Deletes all bonding information.
Definition NimBLEDevice.cpp:572
NimBLEDevice::startAdvertising
static bool startAdvertising(uint8_t instId, int duration=0, int maxEvents=0)
Convenience function to begin advertising.
Definition NimBLEDevice.cpp:167
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:747
NimBLEDevice::deleteBond
static bool deleteBond(const NimBLEAddress &address)
Deletes a peer bond.
Definition NimBLEDevice.cpp:586
NimBLEDevice::setPower
static bool setPower(int8_t dbm)
Set the transmission power.
Definition NimBLEDevice.cpp:467
NimBLEDevice::init
static bool init(const std::string &deviceName)
Initialize the BLE environment.
Definition NimBLEDevice.cpp:819
NimBLEDevice::setOwnAddrType
static bool setOwnAddrType(uint8_t type)
Sets the address type to use.
Definition NimBLEDevice.cpp:1002
NimBLEDevice::stopAdvertising
static bool stopAdvertising()
Convenience function to stop all advertising.
Definition NimBLEDevice.cpp:207
NimBLEDevice::getServer
static NimBLEServer * getServer()
Get the instance of the server.
Definition NimBLEDevice.cpp:137
NimBLEDevice::isInitialized
static bool isInitialized()
Check if the initialization is complete.
Definition NimBLEDevice.cpp:968
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:532
NimBLEDevice::getWhiteListAddress
static NimBLEAddress getWhiteListAddress(size_t index)
Gets the address at the vector index.
Definition NimBLEDevice.cpp:705
NimBLEDevice::createServer
static NimBLEServer * createServer()
Create an instance of a server.
Definition NimBLEDevice.cpp:122
NimBLEDevice::injectPassKey
static bool injectPassKey(const NimBLEConnInfo &peerInfo, uint32_t pin)
Inject the provided passkey into the Security Manager.
Definition NimBLEDevice.cpp:1164
NimBLEDevice::getMTU
static uint16_t getMTU()
Get local MTU value set.
Definition NimBLEDevice.cpp:545
NimBLEDevice::deinit
static bool deinit(bool clearAll=false)
Shutdown the NimBLE stack/controller.
Definition NimBLEDevice.cpp:913
NimBLEDevice::getAddress
static NimBLEAddress getAddress()
Get our device address.
Definition NimBLEDevice.cpp:980
NimBLEDevice::getNumBonds
static int getNumBonds()
Gets the number of bonded peers stored.
Definition NimBLEDevice.cpp:557
NimBLEDevice::whiteListRemove
static bool whiteListRemove(const NimBLEAddress &address)
Remove a peer address from the whitelist.
Definition NimBLEDevice.cpp:674
NimBLEDevice::deleteClient
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:318
NimBLEDevice::startSecurity
static bool startSecurity(uint16_t connHandle, int *rcPtr=nullptr)
Start the connection securing and authorization for this connection.
Definition NimBLEDevice.cpp:1146
NimBLEDevice::getClientByHandle
static NimBLEClient * getClientByHandle(uint16_t connHandle)
Get a reference to a client by connection handle.
Definition NimBLEDevice.cpp:367
NimBLEDevice::getSecurityPasskey
static uint32_t getSecurityPasskey()
Get the current passkey used for pairing.
Definition NimBLEDevice.cpp:1136
NimBLEDevice::setSecurityAuth
static void setSecurityAuth(bool bonding, bool mitm, bool sc)
Set the authorization mode for this device.
Definition NimBLEDevice.cpp:1063
NimBLEDevice::getAdvertising
static NimBLEExtAdvertising * getAdvertising()
Get the instance of the extended advertising object.
Definition NimBLEDevice.cpp:152
NimBLEDevice::setDeviceName
static bool setDeviceName(const std::string &deviceName)
Set the BLEDevice name.
Definition NimBLEDevice.cpp:1192
NimBLEDevice::whiteListAdd
static bool whiteListAdd(const NimBLEAddress &address)
Add a peer address to the whitelist.
Definition NimBLEDevice.cpp:655
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:1107
NimBLEDevice::getWhiteListCount
static size_t getWhiteListCount()
Gets the count of addresses in the whitelist.
Definition NimBLEDevice.cpp:696
NimBLEDevice::host_task
static void host_task(void *param)
The main host task.
Definition NimBLEDevice.cpp:809
NimBLEDevice::setSecurityPasskey
static void setSecurityPasskey(uint32_t passKey)
Set the passkey the server will ask for when pairing.
Definition NimBLEDevice.cpp:1128
NimBLEDevice::setSecurityRespKey
static void setSecurityRespKey(uint8_t respKey)
Set the keys we are willing to accept during pairing.
Definition NimBLEDevice.cpp:1120
NimBLEDevice::setSecurityIOCap
static void setSecurityIOCap(uint8_t iocap)
Set the Input/Output capabilities of this device.
Definition NimBLEDevice.cpp:1094
NimBLEDevice::toString
static std::string toString()
Return a string representation of the address of this device.
Definition NimBLEDevice.cpp:1223
NimBLEDevice::getBondedAddress
static NimBLEAddress getBondedAddress(int index)
Get the address of a bonded peer device by index.
Definition NimBLEDevice.cpp:619
NimBLEDevice::getConnectedClients
static std::vector< NimBLEClient * > getConnectedClients()
Get a list of connected clients.
Definition NimBLEDevice.cpp:410
NimBLEDevice::onWhiteList
static bool onWhiteList(const NimBLEAddress &address)
Checks if a peer device is whitelisted.
Definition NimBLEDevice.cpp:640
NimBLEDevice::getPower
static int getPower()
Get the transmission power.
Definition NimBLEDevice.cpp:496
NimBLEDevice::getScan
static NimBLEScan * getScan()
Retrieve the Scan object that we use for scanning.
Definition NimBLEDevice.cpp:222
NimBLEDevice::getClientByPeerAddress
static NimBLEClient * getClientByPeerAddress(const NimBLEAddress &peerAddress)
Get a reference to a client by peer address.
Definition NimBLEDevice.cpp:382
NimBLEDevice::injectConfirmPasskey
static bool injectConfirmPasskey(const NimBLEConnInfo &peerInfo, bool accept)
Inject the provided numeric comparison response into the Security Manager.
Definition NimBLEDevice.cpp:1176
NimBLEExtAdvertisement
Extended advertisement data.
Definition NimBLEExtAdvertising.h:46
NimBLEExtAdvertising
Extended advertising class.
Definition NimBLEExtAdvertising.h:111
NimBLEScan
Perform and manage BLE scans.
Definition NimBLEScan.h:67
NimBLEServer
The model of a BLE server.
Definition NimBLEServer.h:60
ble_gap_event_listener
Definition ble_gap.h:2568
ble_gap_event
Definition ble_gap.h:510