A model of a BLE Device from which all the BLE roles are created. More...

Static Public Member Functions
static void	init (const std::string &deviceName)
	Initialize the BLE environment. More...

static void	deinit (bool clearAll=false)
	Shutdown the NimBLE stack/controller. More...

static bool	getInitialized ()
	Check if the initialization is complete. More...

static NimBLEAddress	getAddress ()
	Get our device address. More...

static std::string	toString ()
	Return a string representation of the address of this device. More...

static bool	whiteListAdd (const NimBLEAddress &address)
	Add a peer address to the whitelist. More...

static bool	whiteListRemove (const NimBLEAddress &address)
	Remove a peer address from the whitelist. More...

static bool	onWhiteList (const NimBLEAddress &address)
	Checks if a peer device is whitelisted. More...

static size_t	getWhiteListCount ()
	Gets the count of addresses in the whitelist. More...

static NimBLEAddress	getWhiteListAddress (size_t index)
	Gets the address at the vector index. More...

static NimBLEScan *	getScan ()
	Retrieve the Scan object that we use for scanning. More...

static NimBLEServer *	createServer ()
	Create a new instance of a server. More...

static NimBLEServer *	getServer ()
	Get the instance of the server. More...

static void	setPower (esp_power_level_t powerLevel, esp_ble_power_type_t powerType=ESP_BLE_PWR_TYPE_DEFAULT)
	Set the transmission power. More...

static int	getPower (esp_ble_power_type_t powerType=ESP_BLE_PWR_TYPE_DEFAULT)
	Get the transmission power. More...

static void	setCustomGapHandler (gap_event_handler handler)
	Set a custom callback for gap events. More...

static void	setSecurityAuth (bool bonding, bool mitm, bool sc)
	Set the authorization mode for this device. More...

static void	setSecurityAuth (uint8_t auth_req)
	Set the authorization mode for this device. More...

static void	setSecurityIOCap (uint8_t iocap)
	Set the Input/Output capabilities of this device. More...

static void	setSecurityInitKey (uint8_t init_key)
	If we are the initiator of the security procedure this sets the keys we will distribute. More...

static void	setSecurityRespKey (uint8_t init_key)
	Set the keys we are willing to accept during pairing. More...

static void	setSecurityPasskey (uint32_t pin)
	Set the passkey the server will ask for when pairing. More...

static uint32_t	getSecurityPasskey ()
	Get the current passkey used for pairing. More...

static void	setSecurityCallbacks (NimBLESecurityCallbacks *pCallbacks)
	Set callbacks that will be used to handle encryption negotiation events and authentication events. More...

static void	setOwnAddrType (uint8_t own_addr_type, bool useNRPA=false)
	Set the own address type. More...

static int	startSecurity (uint16_t conn_id)
	Start the connection securing and authorization for this connection. More...

static int	setMTU (uint16_t mtu)
	Setup local mtu that will be used to negotiate mtu during request from client peer. More...

static uint16_t	getMTU ()
	Get local MTU value set. More...

static bool	isIgnored (const NimBLEAddress &address)
	Check if the device address is on our ignore list. More...

static void	addIgnored (const NimBLEAddress &address)
	Add a device to the ignore list. More...

static void	removeIgnored (const NimBLEAddress &address)
	Remove a device from the ignore list. More...

static void	setScanDuplicateCacheSize (uint16_t cacheSize)
	Set the duplicate filter cache size for filtering scanned devices. More...

static void	setScanFilterMode (uint8_t type)
	Set the duplicate filter mode for filtering scanned devices. More...

static NimBLEAdvertising *	getAdvertising ()
	Get the instance of the advertising object. More...

static void	startAdvertising ()
	Convenience function to begin advertising.

static void	stopAdvertising ()
	Convenience function to stop advertising.

static NimBLEClient *	createClient (NimBLEAddress peerAddress=NimBLEAddress(""))
	Creates a new client object and maintains a list of all client objects each client can connect to 1 peripheral device. More...

static bool	deleteClient (NimBLEClient *pClient)
	Delete the client object and remove it from the list. Checks if it is connected or trying to connect and disconnects/stops it first. More...

static NimBLEClient *	getClientByID (uint16_t conn_id)
	Get a reference to a client by connection ID. More...

static NimBLEClient *	getClientByPeerAddress (const NimBLEAddress &peer_addr)
	Get a reference to a client by peer address. More...

static NimBLEClient *	getDisconnectedClient ()
	Finds the first disconnected client in the list. More...

static size_t	getClientListSize ()
	Get the number of created client objects. More...

static std::list< NimBLEClient * > *	getClientList ()
	Get the list of created client objects. More...

static bool	deleteBond (const NimBLEAddress &address)
	Deletes a peer bond. More...

static int	getNumBonds ()
	Gets the number of bonded peers stored.

static bool	isBonded (const NimBLEAddress &address)
	Checks if a peer device is bonded. More...

static void	deleteAllBonds ()
	Deletes all bonding information.

static NimBLEAddress	getBondedAddress (int index)
	Get the address of a bonded peer device by index. More...

Detailed Description

A model of a BLE Device from which all the BLE roles are created.

Member Function Documentation

◆ addIgnored()

void NimBLEDevice::addIgnored ( const NimBLEAddress & address )

static

Add a device to the ignore list.

Parameters

[in] address The address of the device we want to ignore.

◆ createClient()

NimBLEClient * NimBLEDevice::createClient ( NimBLEAddress peerAddress = NimBLEAddress("") )

static

Creates a new client object and maintains a list of all client objects each client can connect to 1 peripheral device.

Parameters

[in] peerAddress An optional peer address that is copied to the new client object, allows for calling NimBLEClient::connect(bool) without a device or address parameter.

Returns: A reference to the new client object.

◆ createServer()

NimBLEServer * NimBLEDevice::createServer ( )

static

Create a new instance of a server.

Returns: A new instance of the server.

◆ deinit()

void NimBLEDevice::deinit ( bool clearAll = false )

static

Shutdown the NimBLE stack/controller.

Parameters

[in] clearAll If true, deletes all server/advertising/scan/client objects after deinitializing.

Note: If clearAll is true when called, any references to the created objects become invalid.

◆ deleteBond()

bool NimBLEDevice::deleteBond ( const NimBLEAddress & address )

static

Deletes a peer bond.

Parameters

[in] address The address of the peer with which to delete bond info.

Returns: true on success.

◆ deleteClient()

bool NimBLEDevice::deleteClient ( NimBLEClient * pClient )

static

Delete the client object and remove it from the list.
Checks if it is connected or trying to connect and disconnects/stops it first.

Parameters

[in] pClient A pointer to the client object.

◆ getAddress()

NimBLEAddress NimBLEDevice::getAddress ( )

static

Get our device address.

Returns: A NimBLEAddress object of our public address if we have one, if not then our current random address.

◆ getAdvertising()

NimBLEAdvertising * NimBLEDevice::getAdvertising ( )

static

Get the instance of the advertising object.

Returns: A pointer to the advertising object.

◆ getBondedAddress()

NimBLEAddress NimBLEDevice::getBondedAddress ( int index )

static

Get the address of a bonded peer device by index.

Parameters

[in] index The index to retrieve the peer address of.

Returns: NimBLEAddress of the found bonded peer or nullptr if not found.

◆ getClientByID()

NimBLEClient * NimBLEDevice::getClientByID ( uint16_t conn_id )

static

Get a reference to a client by connection ID.

Parameters

[in] conn_id The client connection ID to search for.

Returns: A pointer to the client object with the spcified connection ID.

◆ getClientByPeerAddress()

NimBLEClient * NimBLEDevice::getClientByPeerAddress ( const NimBLEAddress & peer_addr )

static

Get a reference to a client by peer address.

Parameters

[in] peer_addr The address of the peer to search for.

Returns: A pointer to the client object with the peer address.

◆ getClientList()

std::list< NimBLEClient * > * NimBLEDevice::getClientList ( )

static

Get the list of created client objects.

Returns: A pointer to the list of clients.

◆ getClientListSize()

size_t NimBLEDevice::getClientListSize ( )

static

Get the number of created client objects.

Returns: Number of client objects created.

◆ getDisconnectedClient()

NimBLEClient * NimBLEDevice::getDisconnectedClient ( )

static

Finds the first disconnected client in the list.

Returns: A pointer to the first client object that is not connected to a peer.

◆ getInitialized()

bool NimBLEDevice::getInitialized ( )

static

Check if the initialization is complete.

Returns: true if initialized.

◆ getMTU()

uint16_t NimBLEDevice::getMTU ( )

static

Get local MTU value set.

Returns: The current preferred MTU setting.

◆ getPower()

int NimBLEDevice::getPower ( esp_ble_power_type_t powerType = ESP_BLE_PWR_TYPE_DEFAULT )

static

Get the transmission power.

Parameters

[in]

powerType

The power level to set, can be one of:

ESP_BLE_PWR_TYPE_CONN_HDL0 = 0, For connection handle 0
ESP_BLE_PWR_TYPE_CONN_HDL1 = 1, For connection handle 1
ESP_BLE_PWR_TYPE_CONN_HDL2 = 2, For connection handle 2
ESP_BLE_PWR_TYPE_CONN_HDL3 = 3, For connection handle 3
ESP_BLE_PWR_TYPE_CONN_HDL4 = 4, For connection handle 4
ESP_BLE_PWR_TYPE_CONN_HDL5 = 5, For connection handle 5
ESP_BLE_PWR_TYPE_CONN_HDL6 = 6, For connection handle 6
ESP_BLE_PWR_TYPE_CONN_HDL7 = 7, For connection handle 7
ESP_BLE_PWR_TYPE_CONN_HDL8 = 8, For connection handle 8
ESP_BLE_PWR_TYPE_ADV = 9, For advertising
ESP_BLE_PWR_TYPE_SCAN = 10, For scan
ESP_BLE_PWR_TYPE_DEFAULT = 11, For default, if not set other, it will use default value

Returns: the power level currently used by the type specified.

◆ getScan()

NimBLEScan * NimBLEDevice::getScan ( )

static

Retrieve the Scan object that we use for scanning.

Returns: The scanning object reference. This is a singleton object. The caller should not try and release/delete it.

◆ getSecurityPasskey()

uint32_t NimBLEDevice::getSecurityPasskey ( )

static

Get the current passkey used for pairing.

Returns: The current passkey.

◆ getServer()

NimBLEServer * NimBLEDevice::getServer ( )

static

Get the instance of the server.

Returns: A pointer to the server instance.

◆ getWhiteListAddress()

NimBLEAddress NimBLEDevice::getWhiteListAddress ( size_t index )

static

Gets the address at the vector index.

Parameters

[in] index The vector index to retrieve the address from.

Returns: the NimBLEAddress at the whitelist index or nullptr if not found.

◆ getWhiteListCount()

size_t NimBLEDevice::getWhiteListCount ( )

static

Gets the count of addresses in the whitelist.

Returns: The number of addresses in the whitelist.

◆ init()

void NimBLEDevice::init ( const std::string & deviceName )

static

Initialize the BLE environment.

Parameters

[in] deviceName The device name of the device.

◆ isBonded()

bool NimBLEDevice::isBonded ( const NimBLEAddress & address )

static

Checks if a peer device is bonded.

Parameters

[in] address The address to check for bonding.

Returns: true if bonded.

◆ isIgnored()

bool NimBLEDevice::isIgnored ( const NimBLEAddress & address )

static

Check if the device address is on our ignore list.

Parameters

[in] address The address to look for.

Returns: True if ignoring.

◆ onWhiteList()

bool NimBLEDevice::onWhiteList ( const NimBLEAddress & address )

static

Checks if a peer device is whitelisted.

Parameters

[in] address The address to check for in the whitelist.

Returns: true if the address is in the whitelist.

◆ removeIgnored()

void NimBLEDevice::removeIgnored ( const NimBLEAddress & address )

static

Remove a device from the ignore list.

Parameters

[in] address The address of the device we want to remove from the list.

◆ setCustomGapHandler()

void NimBLEDevice::setCustomGapHandler ( gap_event_handler handler )

static

Set a custom callback for gap events.

Parameters

[in] handler The function to call when gap events occur.

◆ setMTU()

int NimBLEDevice::setMTU ( uint16_t mtu )

static

Setup local mtu that will be used to negotiate mtu during request from client peer.

Parameters

[in]

mtu

Value to set local mtu:

This should be larger than 23 and lower or equal to BLE_ATT_MTU_MAX = 527.

◆ setOwnAddrType()

void NimBLEDevice::setOwnAddrType	(	uint8_t	own_addr_type,
		bool	useNRPA = `false`
	)

static

Set the own address type.

Parameters

[in]	own_addr_type	Own Bluetooth Device address type. The available bits are defined as: 0x00: BLE_OWN_ADDR_PUBLIC 0x01: BLE_OWN_ADDR_RANDOM 0x02: BLE_OWN_ADDR_RPA_PUBLIC_DEFAULT 0x03: BLE_OWN_ADDR_RPA_RANDOM_DEFAULT
[in]	useNRPA	If true, and address type is random, uses a non-resolvable random address.

◆ setPower()

void NimBLEDevice::setPower	(	esp_power_level_t	powerLevel,
		esp_ble_power_type_t	powerType = `ESP_BLE_PWR_TYPE_DEFAULT`
	)

static

Set the transmission power.

Parameters

[in]	powerLevel	The power level to set, can be one of: ESP_PWR_LVL_N12 = 0, Corresponding to -12dbm ESP_PWR_LVL_N9 = 1, Corresponding to -9dbm ESP_PWR_LVL_N6 = 2, Corresponding to -6dbm ESP_PWR_LVL_N3 = 3, Corresponding to -3dbm ESP_PWR_LVL_N0 = 4, Corresponding to 0dbm ESP_PWR_LVL_P3 = 5, Corresponding to +3dbm ESP_PWR_LVL_P6 = 6, Corresponding to +6dbm ESP_PWR_LVL_P9 = 7, Corresponding to +9dbm
[in]	powerType	The BLE function to set the power level for, can be one of: ESP_BLE_PWR_TYPE_CONN_HDL0 = 0, For connection handle 0 ESP_BLE_PWR_TYPE_CONN_HDL1 = 1, For connection handle 1 ESP_BLE_PWR_TYPE_CONN_HDL2 = 2, For connection handle 2 ESP_BLE_PWR_TYPE_CONN_HDL3 = 3, For connection handle 3 ESP_BLE_PWR_TYPE_CONN_HDL4 = 4, For connection handle 4 ESP_BLE_PWR_TYPE_CONN_HDL5 = 5, For connection handle 5 ESP_BLE_PWR_TYPE_CONN_HDL6 = 6, For connection handle 6 ESP_BLE_PWR_TYPE_CONN_HDL7 = 7, For connection handle 7 ESP_BLE_PWR_TYPE_CONN_HDL8 = 8, For connection handle 8 ESP_BLE_PWR_TYPE_ADV = 9, For advertising ESP_BLE_PWR_TYPE_SCAN = 10, For scan ESP_BLE_PWR_TYPE_DEFAULT = 11, For default, if not set other, it will use default value

◆ setScanDuplicateCacheSize()

void NimBLEDevice::setScanDuplicateCacheSize ( uint16_t cacheSize )

static

Set the duplicate filter cache size for filtering scanned devices.

Parameters

[in] cacheSize The number of advertisements filtered before the cache is reset.
Range is 10-1000, a larger value will reduce how often the same devices are reported.

Must only be called before calling NimBLEDevice::init.

◆ setScanFilterMode()

void NimBLEDevice::setScanFilterMode ( uint8_t mode )

static

Set the duplicate filter mode for filtering scanned devices.

Parameters

[in]

mode

One of three possible options:

CONFIG_BTDM_SCAN_DUPL_TYPE_DEVICE (0) (default)
Filter by device address only, advertisements from the same address will be reported only once.
CONFIG_BTDM_SCAN_DUPL_TYPE_DATA (1)
Filter by data only, advertisements with the same data will only be reported once,
even from different addresses.
CONFIG_BTDM_SCAN_DUPL_TYPE_DATA_DEVICE (2)
Filter by address and data, advertisements from the same address will be reported only once,
except if the data in the advertisement has changed, then it will be reported again.

Must only be called before calling NimBLEDevice::init.

◆ setSecurityAuth() [1/2]

void NimBLEDevice::setSecurityAuth	(	bool	bonding,
		bool	mitm,
		bool	sc
	)

static

Set the authorization mode for this device.

Parameters

bonding	If true we allow bonding, false no bonding will be performed.
mitm	If true we are capable of man in the middle protection, false if not.
sc	If true we will perform secure connection pairing, false we will use legacy pairing.

◆ setSecurityAuth() [2/2]

void NimBLEDevice::setSecurityAuth ( uint8_t auth_req )

static

Set the authorization mode for this device.

Parameters

auth_req

A bitmap indicating what modes are supported.
The available bits are defined as:

0x01 BLE_SM_PAIR_AUTHREQ_BOND
0x04 BLE_SM_PAIR_AUTHREQ_MITM
0x08 BLE_SM_PAIR_AUTHREQ_SC
0x10 BLE_SM_PAIR_AUTHREQ_KEYPRESS - not yet supported.

◆ setSecurityCallbacks()

void NimBLEDevice::setSecurityCallbacks ( NimBLESecurityCallbacks * callbacks )

static

Set callbacks that will be used to handle encryption negotiation events and authentication events.

Parameters

[in] callbacks Pointer to NimBLESecurityCallbacks class

Deprecated:: For backward compatibility, New code should use client/server callback methods.

◆ setSecurityInitKey()

void NimBLEDevice::setSecurityInitKey ( uint8_t init_key )

static

If we are the initiator of the security procedure this sets the keys we will distribute.

Parameters

init_key

A bitmap indicating which keys to distribute during pairing.
The available bits are defined as:

0x01: BLE_SM_PAIR_KEY_DIST_ENC - Distribute the encryption key.
0x02: BLE_SM_PAIR_KEY_DIST_ID - Distribute the ID key (IRK).
0x04: BLE_SM_PAIR_KEY_DIST_SIGN
0x08: BLE_SM_PAIR_KEY_DIST_LINK

◆ setSecurityIOCap()

void NimBLEDevice::setSecurityIOCap ( uint8_t iocap )

static

Set the Input/Output capabilities of this device.

Parameters

iocap

One of the following values:

0x00 BLE_HS_IO_DISPLAY_ONLY DisplayOnly IO capability
0x01 BLE_HS_IO_DISPLAY_YESNO DisplayYesNo IO capability
0x02 BLE_HS_IO_KEYBOARD_ONLY KeyboardOnly IO capability
0x03 BLE_HS_IO_NO_INPUT_OUTPUT NoInputNoOutput IO capability
0x04 BLE_HS_IO_KEYBOARD_DISPLAY KeyboardDisplay Only IO capability

◆ setSecurityPasskey()

void NimBLEDevice::setSecurityPasskey ( uint32_t pin )

static

Set the passkey the server will ask for when pairing.

Parameters

[in] pin The passkey to use.

◆ setSecurityRespKey()

void NimBLEDevice::setSecurityRespKey ( uint8_t resp_key )

static

Set the keys we are willing to accept during pairing.

Parameters

resp_key

A bitmap indicating which keys to accept during pairing. The available bits are defined as:

0x01: BLE_SM_PAIR_KEY_DIST_ENC - Accept the encryption key.
0x02: BLE_SM_PAIR_KEY_DIST_ID - Accept the ID key (IRK).
0x04: BLE_SM_PAIR_KEY_DIST_SIGN
0x08: BLE_SM_PAIR_KEY_DIST_LINK

◆ startSecurity()

int NimBLEDevice::startSecurity ( uint16_t conn_id )

static

Start the connection securing and authorization for this connection.

Parameters

conn_id The connection id of the peer device.

Returns: NimBLE stack return code, 0 = success.

◆ toString()

std::string NimBLEDevice::toString ( )

static

Return a string representation of the address of this device.

Returns: A string representation of this device address.

◆ whiteListAdd()

bool NimBLEDevice::whiteListAdd ( const NimBLEAddress & address )

static

Add a peer address to the whitelist.

Parameters

[in] address The address to add to the whitelist.

Returns: true if successful.

◆ whiteListRemove()

bool NimBLEDevice::whiteListRemove ( const NimBLEAddress & address )

static

Remove a peer address from the whitelist.

Parameters

[in] address The address to remove from the whitelist.

Returns: true if successful.

Static Public Member Functions

Detailed Description

Member Function Documentation

◆ addIgnored()

◆ createClient()

◆ createServer()

◆ deinit()

◆ deleteBond()

◆ deleteClient()

◆ getAddress()

◆ getAdvertising()

◆ getBondedAddress()

◆ getClientByID()

◆ getClientByPeerAddress()

◆ getClientList()

◆ getClientListSize()

◆ getDisconnectedClient()

◆ getInitialized()

◆ getMTU()

◆ getPower()

◆ getScan()

◆ getSecurityPasskey()

◆ getServer()

◆ getWhiteListAddress()

◆ getWhiteListCount()

◆ init()

◆ isBonded()

◆ isIgnored()

◆ onWhiteList()

◆ removeIgnored()

◆ setCustomGapHandler()

◆ setMTU()

◆ setOwnAddrType()

◆ setPower()

◆ setScanDuplicateCacheSize()

◆ setScanFilterMode()

◆ setSecurityAuth() [1/2]

◆ setSecurityAuth() [2/2]

◆ setSecurityCallbacks()

◆ setSecurityInitKey()

◆ setSecurityIOCap()

◆ setSecurityPasskey()

◆ setSecurityRespKey()

◆ startSecurity()

◆ toString()

◆ whiteListAdd()

◆ whiteListRemove()