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)
	Retrieve the Scan object that we use for scanning.

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

Detailed Description

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

Member Function Documentation

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

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

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

◆ getSecurityPasskey()

uint32_t NimBLEDevice::getSecurityPasskey ( )

static

Get the current passkey used for pairing.

Returns: The current passkey.

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

◆ 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

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.

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

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

◆ 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

◆ deinit()

◆ getAddress()

◆ getMTU()

◆ getPower()

◆ getSecurityPasskey()

◆ getWhiteListAddress()

◆ getWhiteListCount()

◆ init()

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

◆ startSecurity()

◆ toString()

◆ whiteListAdd()

◆ whiteListRemove()