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

#include <NimBLEDevice.h>

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

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

static bool	setDeviceName (const std::string &deviceName)
	Set the BLEDevice name.

static bool	isInitialized ()
	Check if the initialization is complete.

static NimBLEAddress	getAddress ()
	Get our device address.

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

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

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

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

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

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

static bool	setOwnAddrType (uint8_t type)
	Sets the address type to use.

static bool	setOwnAddr (const NimBLEAddress &addr)
	Set the device address to use.

static bool	setOwnAddr (const uint8_t *addr)
	Set the device address to use.

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

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

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

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

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

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

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

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

static bool	startSecurity (uint16_t connHandle, int *rcPtr=nullptr)
	Start the connection securing and authorization for this connection.

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

static uint16_t	getMTU ()
	Get local MTU value set.

static void	onReset (int reason)
	Host reset, we pass the message so we don't make calls until re-synced.

static void	onSync (void)
	Host synced with controller, all clear to make calls to the stack.

static void	host_task (void *param)
	The main host task.

static int	getPower (NimBLETxPowerType type=NimBLETxPowerType::All)
	Get the transmission power.

static bool	setPower (int8_t dbm, NimBLETxPowerType type=NimBLETxPowerType::All)
	Set the transmission power.

static bool	setDefaultPhy (uint8_t txPhyMask, uint8_t rxPhyMask)
	Set the preferred default phy to use for connections.

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

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

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

static bool	injectConfirmPasskey (const NimBLEConnInfo &peerInfo, bool accept)
	Inject the provided numeric comparison response into the Security Manager.

static bool	injectPassKey (const NimBLEConnInfo &peerInfo, uint32_t pin)
	Inject the provided passkey into the Security Manager.

static NimBLEExtAdvertising *	getAdvertising ()
	Get the instance of the extended advertising object.

static bool	startAdvertising (uint8_t instId, int duration=0, int maxEvents=0)
	Convenience function to begin advertising.

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

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

static bool	startAdvertising (uint32_t duration=0)
	Convenience function to begin advertising.

static NimBLEClient *	createClient ()
	Creates a new client object, each client can connect to 1 peripheral device.

static NimBLEClient *	createClient (const NimBLEAddress &peerAddress)
	Creates a new client object, each client can connect to 1 peripheral device.

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.

static NimBLEClient *	getClientByHandle (uint16_t connHandle)
	Get a reference to a client by connection handle.

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

static NimBLEClient *	getDisconnectedClient ()
	Finds the first disconnected client available.

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

static std::vector< NimBLEClient * >	getConnectedClients ()
	Get a list of connected clients.

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

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

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

static bool	deleteAllBonds ()
	Deletes all bonding information.

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

Detailed Description

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

Member Function Documentation

◆ createClient() [1/2]

NimBLEClient * NimBLEDevice::createClient ( )

static

Creates a new client object, each client can connect to 1 peripheral device.

Returns: A pointer to the new client object, or nullptr on error.

◆ createClient() [2/2]

NimBLEClient * NimBLEDevice::createClient ( const NimBLEAddress & peerAddress )

static

Creates a new client object, each client can connect to 1 peripheral device.

Parameters

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

Returns: A pointer to the new client object, or nullptr on error.

◆ createServer()

NimBLEServer * NimBLEDevice::createServer ( )

static

Create an instance of a server.

Returns: A pointer to the instance of the server.

◆ deinit()

bool NimBLEDevice::deinit ( bool clearAll = false )

static

Shutdown the NimBLE stack/controller.

Parameters

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

Note: If clearAll is true when called all objects created will be deleted and any references to the created objects become invalid. If clearAll is false, the objects will remain and can be used again after re-initializing the stack. If the stack was not already initialized, the objects created can be deleted when clearAll is true with no effect on the stack.

◆ deleteAllBonds()

bool NimBLEDevice::deleteAllBonds ( )

static

Deletes all bonding information.

Returns: True on success.

◆ 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 with the currently used address, or a NULL address if not set.

◆ getAdvertising()

NimBLEAdvertising * NimBLEDevice::getAdvertising ( )

static

Get the instance of the extended advertising object.

Get the instance of the advertising object.

Returns: A pointer to the extended advertising object.; 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 null address if not found.

◆ getClientByHandle()

NimBLEClient * NimBLEDevice::getClientByHandle ( uint16_t connHandle )

static

Get a reference to a client by connection handle.

Parameters

[in] connHandle The client connection handle to search for.

Returns: A pointer to the client object with the specified connection handle or nullptr.

◆ getClientByPeerAddress()

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

static

Get a reference to a client by peer address.

Parameters

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

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

◆ getConnectedClients()

std::vector< NimBLEClient * > NimBLEDevice::getConnectedClients ( )

static

Get a list of connected clients.

Returns: A vector of connected client objects.

◆ getCreatedClientCount()

size_t NimBLEDevice::getCreatedClientCount ( )

static

Get the number of created client objects.

Returns: Number of client objects created.

◆ getDisconnectedClient()

NimBLEClient * NimBLEDevice::getDisconnectedClient ( )

static

Finds the first disconnected client available.

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

◆ getMTU()

uint16_t NimBLEDevice::getMTU ( )

static

Get local MTU value set.

Returns: The current preferred MTU setting.

◆ getPower()

int NimBLEDevice::getPower ( NimBLETxPowerType type = NimBLETxPowerType::All )

static

Get the transmission power.

Returns: The power level currently used in dbm or 0xFF on error.

◆ 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 or nullptr if none have been created.

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

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

static

Initialize the BLE environment.

Parameters

[in] deviceName The device name of the device.

◆ injectConfirmPasskey()

bool NimBLEDevice::injectConfirmPasskey	(	const NimBLEConnInfo &	peerInfo,
		bool	accept
	)

static

Inject the provided numeric comparison response into the Security Manager.

Parameters

[in]	peerInfo	Connection information for the peer.
[in]	accept	Whether the user confirmed or declined the comparison.

◆ injectPassKey()

bool NimBLEDevice::injectPassKey	(	const NimBLEConnInfo &	peerInfo,
		uint32_t	passkey
	)

static

Inject the provided passkey into the Security Manager.

Parameters

[in]	peerInfo	Connection information for the peer.
[in]	passkey	The 6-digit passkey to inject.

Returns: true if the passkey was injected successfully.

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

◆ isInitialized()

bool NimBLEDevice::isInitialized ( )

static

Check if the initialization is complete.

Returns: true if initialized.

◆ onReset()

void NimBLEDevice::onReset ( int reason )

static

Host reset, we pass the message so we don't make calls until re-synced.

Parameters

[in] reason The reason code for the reset.

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

◆ setCustomGapHandler()

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

Returns

◆ setDefaultPhy()

bool NimBLEDevice::setDefaultPhy	(	uint8_t	txPhyMask,
		uint8_t	rxPhyMask
	)

static

Set the preferred default phy to use for connections.

Parameters

[in]	txPhyMask	TX PHY. Can be mask of following: BLE_GAP_LE_PHY_1M_MASK BLE_GAP_LE_PHY_2M_MASK BLE_GAP_LE_PHY_CODED_MASK BLE_GAP_LE_PHY_ANY_MASK
[in]	rxPhyMask	RX PHY. Can be mask of following: BLE_GAP_LE_PHY_1M_MASK BLE_GAP_LE_PHY_2M_MASK BLE_GAP_LE_PHY_CODED_MASK BLE_GAP_LE_PHY_ANY_MASK

Returns: True if successful.

◆ setDeviceName()

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

static

Set the BLEDevice name.

Parameters

[in] deviceName The name to set.

◆ setMTU()

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

Returns: True if the mtu was set successfully.

◆ setOwnAddr() [1/2]

bool NimBLEDevice::setOwnAddr ( const NimBLEAddress & addr )

static

Set the device address to use.

Parameters

[in] addr The address to set.

Returns: True if the address was set successfully.

To use the address generated the address type must be set to random with setOwnAddrType.

◆ setOwnAddr() [2/2]

bool NimBLEDevice::setOwnAddr ( const uint8_t * addr )

static

Set the device address to use.

Parameters

[in] addr The address to set.

Returns: True if the address was set successfully.

To use the address generated the address type must be set to random with setOwnAddrType.

◆ setOwnAddrType()

bool NimBLEDevice::setOwnAddrType ( uint8_t type )

static

Sets the address type to use.

Parameters

[in]

type

Bluetooth Device address type. The available types are defined as:

0x00: BLE_OWN_ADDR_PUBLIC - Public address; Uses the hardware static address.
0x01: BLE_OWN_ADDR_RANDOM - Random static address; Uses the hardware or generated random static address.
0x02: BLE_OWN_ADDR_RPA_PUBLIC_DEFAULT - Resolvable private address, defaults to public if no RPA available.
0x03: BLE_OWN_ADDR_RPA_RANDOM_DEFAULT - Resolvable private address, defaults to random static if no RPA available.

◆ setPower()

bool NimBLEDevice::setPower	(	int8_t	dbm,
		NimBLETxPowerType	type = `NimBLETxPowerType::All`
	)

static

Set the transmission power.

Parameters

[in] dbm The power level to set in dBm.

Returns: True if the power level was set successfully.

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

◆ setSecurityInitKey()

void NimBLEDevice::setSecurityInitKey ( uint8_t initKey )

static

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

Parameters

initKey

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 passkey )

static

Set the passkey the server will ask for when pairing.

Parameters

[in] passkey The passkey to use.

◆ setSecurityRespKey()

void NimBLEDevice::setSecurityRespKey ( uint8_t respKey )

static

Set the keys we are willing to accept during pairing.

Parameters

respKey

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 ( uint32_t duration = 0 )

static

Convenience function to begin advertising.

Parameters

[in] duration The duration in milliseconds to advertise for, default = forever.

Returns: True if advertising started successfully.

◆ startAdvertising() [2/2]

bool NimBLEDevice::startAdvertising	(	uint8_t	instId,
		int	duration = `0`,
		int	maxEvents = `0`
	)

static

Convenience function to begin advertising.

Parameters

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

Returns: True if advertising started successfully.

◆ startSecurity()

bool NimBLEDevice::startSecurity	(	uint16_t	connHandle,
		int *	rcPtr = `nullptr`
	)

static

Start the connection securing and authorization for this connection.

Parameters

connHandle	The connection handle of the peer device.
rcPtr	Optional pointer to pass the return code to the caller.

Returns: True if successfully started, success = 0 or BLE_HS_EALREADY.

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

static

Convenience function to stop advertising a data set.

Parameters

[in] instId 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

◆ createClient() [1/2]

◆ createClient() [2/2]

◆ createServer()

◆ deinit()

◆ deleteAllBonds()

◆ deleteBond()

◆ deleteClient()

◆ getAddress()

◆ getAdvertising()

◆ getBondedAddress()

◆ getClientByHandle()

◆ getClientByPeerAddress()

◆ getConnectedClients()

◆ getCreatedClientCount()

◆ getDisconnectedClient()

◆ getMTU()

◆ getPower()

◆ getScan()

◆ getSecurityPasskey()

◆ getServer()

◆ getWhiteListAddress()

◆ getWhiteListCount()

◆ init()

◆ injectConfirmPasskey()

◆ injectPassKey()

◆ isBonded()

◆ isInitialized()

◆ onReset()

◆ onWhiteList()

◆ setCustomGapHandler()

◆ setDefaultPhy()

◆ setDeviceName()

◆ setMTU()

◆ setOwnAddr() [1/2]

◆ setOwnAddr() [2/2]

◆ setOwnAddrType()

◆ setPower()

◆ setSecurityAuth() [1/2]

◆ setSecurityAuth() [2/2]

◆ setSecurityInitKey()

◆ setSecurityIOCap()

◆ setSecurityPasskey()

◆ setSecurityRespKey()

◆ startAdvertising() [1/2]

◆ startAdvertising() [2/2]

◆ startSecurity()

◆ stopAdvertising() [1/2]

◆ stopAdvertising() [2/2]

◆ toString()

◆ whiteListAdd()

◆ whiteListRemove()