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

#include <NimBLEDevice.h>

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 void	setDeviceName (const std::string &deviceName)
	Set the BLEDevice's name. 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	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 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 NimBLEExtAdvertising *	getAdvertising ()
	Get the instance of the advertising object. More...

static bool	startAdvertising (uint8_t inst_id, int duration=0, int max_events=0)
	Convenience function to begin advertising. More...

static bool	stopAdvertising (uint8_t inst_id)
	Convenience function to stop advertising a data set. More...

static bool	stopAdvertising ()
	Convenience function to stop all advertising. More...

static bool	startAdvertising ()
	Convenience function to begin advertising. More...

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.

◆ 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.

◆ setDeviceName()

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

static

Set the BLEDevice's name.

Parameters

[in] deviceName The device name of the device.

◆ 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.

◆ 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

◆ startAdvertising() [1/2]

bool NimBLEDevice::startAdvertising ( )

static

Convenience function to begin advertising.

Returns: True if advertising started successfully.

◆ startAdvertising() [2/2]

bool NimBLEDevice::startAdvertising	(	uint8_t	inst_id,
		int	duration = `0`,
		int	max_events = `0`
	)

static

Convenience function to begin advertising.

Parameters

[in]	inst_id	The extended advertisement instance ID to start.
[in]	duration	How long to advertise for in milliseconds, 0 = forever (default).
[in]	max_events	Maximum number of advertisement events to send, 0 = no limit (default).

Returns: True if advertising started successfully.

◆ 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.

◆ stopAdvertising() [1/2]

bool NimBLEDevice::stopAdvertising ( )

static

Convenience function to stop all advertising.

Returns: True if advertising stopped successfully.

◆ stopAdvertising() [2/2]

bool NimBLEDevice::stopAdvertising ( uint8_t inst_id )

static

Convenience function to stop advertising a data set.

Parameters

[in] inst_id The extended advertisement instance ID to stop advertising.

Returns: True if advertising stopped successfully.

◆ 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()

◆ getScan()

◆ getSecurityPasskey()

◆ getServer()

◆ getWhiteListAddress()

◆ getWhiteListCount()

◆ init()

◆ isBonded()

◆ isIgnored()

◆ onWhiteList()

◆ removeIgnored()

◆ setCustomGapHandler()

◆ setDeviceName()

◆ setMTU()

◆ setSecurityAuth() [1/2]

◆ setSecurityAuth() [2/2]

◆ setSecurityCallbacks()

◆ setSecurityInitKey()

◆ setSecurityIOCap()

◆ setSecurityPasskey()

◆ setSecurityRespKey()

◆ startAdvertising() [1/2]

◆ startAdvertising() [2/2]

◆ startSecurity()

◆ stopAdvertising() [1/2]

◆ stopAdvertising() [2/2]

◆ toString()

◆ whiteListAdd()

◆ whiteListRemove()