Extended advertisement data. More...

#include <NimBLEExtAdvertising.h>

Public Member Functions
	NimBLEExtAdvertisement (uint8_t priPhy=BLE_HCI_LE_PHY_1M, uint8_t secPhy=BLE_HCI_LE_PHY_1M)
	Construct a BLE extended advertisement.

bool	setAppearance (uint16_t appearance)
	Set the appearance.

bool	addServiceUUID (const NimBLEUUID &serviceUUID)
	Add a service uuid to exposed list of services.

bool	addServiceUUID (const char *serviceUUID)
	Add a service uuid to exposed list of services.

bool	removeServiceUUID (const NimBLEUUID &serviceUUID)
	Remove a service UUID from the advertisement.

bool	removeServiceUUID (const char *serviceUUID)
	Remove a service UUID from the advertisement.

bool	removeServices ()
	Remove all service UUIDs from the advertisement.

bool	setCompleteServices (const NimBLEUUID &uuid)
	Set a single service to advertise as a complete list of services.

bool	setCompleteServices16 (const std::vector< NimBLEUUID > &uuids)
	Set the complete list of 16 bit services to advertise.

bool	setCompleteServices32 (const std::vector< NimBLEUUID > &uuids)
	Set the complete list of 32 bit services to advertise.

bool	setFlags (uint8_t flag)
	Set the advertisement flags.

bool	setManufacturerData (const uint8_t *data, size_t length)
	Set manufacturer specific data.

bool	setManufacturerData (const std::string &data)
	Set manufacturer specific data.

bool	setManufacturerData (const std::vector< uint8_t > &data)
	Set manufacturer specific data.

bool	setURI (const std::string &uri)
	Set the URI to advertise.

bool	setName (const std::string &name, bool isComplete=true)
	Set the complete name of this device.

bool	setPartialServices (const NimBLEUUID &uuid)
	Set a single service to advertise as a partial list of services.

bool	setPartialServices16 (const std::vector< NimBLEUUID > &uuids)
	Set the partial list of services to advertise.

bool	setPartialServices32 (const std::vector< NimBLEUUID > &uuids)
	Set the partial list of services to advertise.

bool	setServiceData (const NimBLEUUID &uuid, const uint8_t *data, size_t length)
	Set the service data advertised for the UUID.

bool	setServiceData (const NimBLEUUID &uuid, const std::string &data)
	Set the service data (UUID + data)

bool	setServiceData (const NimBLEUUID &uuid, const std::vector< uint8_t > &data)
	Set the service data advertised for the UUID.

bool	setShortName (const std::string &name)
	Set the short name.

bool	setData (const uint8_t *data, size_t length)
	Set the advertisement data.

bool	addData (const uint8_t *data, size_t length)
	Add data to the payload to be advertised.

bool	addData (const std::string &data)
	Add data to the payload to be advertised.

bool	setPreferredParams (uint16_t min, uint16_t max)
	Set the preferred min and max connection intervals to advertise.

void	addTxPower ()
	Adds Tx power level to the advertisement data.

void	setLegacyAdvertising (bool enable)
	Sets wether the advertisement should use legacy (BLE 4.0, 31 bytes max) advertising.

void	setConnectable (bool enable)
	Sets wether this advertisement should advertise as a connectable device.

void	setScannable (bool enable)
	Sets wether the advertisement has scan response data available.

void	setMinInterval (uint32_t mininterval)
	Set the minimum advertising interval.

void	setMaxInterval (uint32_t maxinterval)
	Set the maximum advertising interval.

void	setPrimaryPhy (uint8_t phy)
	Set the primary advertising PHY to use.

void	setSecondaryPhy (uint8_t phy)
	Set the secondary advertising PHY to use.

void	setScanFilter (bool scanRequestWhitelistOnly, bool connectWhitelistOnly)
	Set the filtering for the scan filter.

void	setDirectedPeer (const NimBLEAddress &addr)
	Sets the peer to directly advertise to.

void	setDirected (bool enable, bool high_duty=true)
	Enable or disable direct advertisements to the peer set with `NimBLEExtAdvertisement::setDirectedPeer`

void	setAnonymous (bool enable)
	Sets whether the advertisement should be anonymous.

void	setPrimaryChannels (bool ch37, bool ch38, bool ch39)
	Sets The primary channels to advertise on.

void	setTxPower (int8_t dbm)
	Sets the transmission power level for this advertisement.

void	setAddress (const NimBLEAddress &addr)
	Set the address to use for this advertisement.

void	enableScanRequestCallback (bool enable)
	Sets whether the scan response request callback should be called.

void	clearData ()
	Clears the data stored in this instance, does not change settings.

int	getDataLocation (uint8_t type) const
	Get the location of the data in the payload.

bool	removeData (uint8_t type)
	Remove data from the advertisement data.

size_t	getDataSize () const
	Get the size of the current data.

std::string	toString () const
	Get the string representation of the advertisement data.

Detailed Description

Extended advertisement data.

Constructor & Destructor Documentation

◆ NimBLEExtAdvertisement()

NimBLEExtAdvertisement::NimBLEExtAdvertisement	(	uint8_t	priPhy = `BLE_HCI_LE_PHY_1M`,
		uint8_t	secPhy = `BLE_HCI_LE_PHY_1M`
	)

Construct a BLE extended advertisement.

Parameters

[in]	priPhy	The primary Phy to advertise on, can be one of: BLE_HCI_LE_PHY_1M BLE_HCI_LE_PHY_CODED
[in]	secPhy	The secondary Phy to advertise on, can be one of: BLE_HCI_LE_PHY_1M BLE_HCI_LE_PHY_2M BLE_HCI_LE_PHY_CODED

Member Function Documentation

◆ addData() [1/2]

bool NimBLEExtAdvertisement::addData ( const std::string & data )

Add data to the payload to be advertised.

Parameters

[in] data The data to be added to the payload.

Returns: True if successful, false if the data is too large.

◆ addData() [2/2]

bool NimBLEExtAdvertisement::addData	(	const uint8_t *	data,
		size_t	length
	)

Add data to the payload to be advertised.

Parameters

[in]	data	The data to be added to the payload.
[in]	length	The size of data to be added to the payload.

Returns: True if successful, false if the data is too large.

◆ addServiceUUID() [1/2]

bool NimBLEExtAdvertisement::addServiceUUID ( const char * serviceUUID )

Add a service uuid to exposed list of services.

Parameters

[in] serviceUUID The string representation of the service to expose.

Returns: True if successful.

◆ addServiceUUID() [2/2]

bool NimBLEExtAdvertisement::addServiceUUID ( const NimBLEUUID & serviceUUID )

Add a service uuid to exposed list of services.

Parameters

[in] serviceUUID The UUID of the service to expose.

◆ clearData()

void NimBLEExtAdvertisement::clearData ( )

Clears the data stored in this instance, does not change settings.

This will clear all data but preserves advertising parameter settings.

◆ enableScanRequestCallback()

void NimBLEExtAdvertisement::enableScanRequestCallback ( bool enable )

Sets whether the scan response request callback should be called.

Parameters

[in] enable If true the scan response request callback will be called for this advertisement.

◆ getDataLocation()

int NimBLEExtAdvertisement::getDataLocation ( uint8_t type ) const

Get the location of the data in the payload.

Parameters

[in] type The type of data to search for.

Returns: -1 if the data is not found, otherwise the index of the data in the payload.

◆ removeData()

bool NimBLEExtAdvertisement::removeData ( uint8_t type )

Remove data from the advertisement data.

Parameters

[in] type The type of data to remove.

Returns: True if successful, false if the data was not found.

◆ removeServiceUUID() [1/2]

bool NimBLEExtAdvertisement::removeServiceUUID ( const char * serviceUUID )

Remove a service UUID from the advertisement.

Parameters

[in] serviceUUID The UUID of the service to remove.

Returns: True if successful or uuid not found, false if uuid error or data could not be reset.

◆ removeServiceUUID() [2/2]

bool NimBLEExtAdvertisement::removeServiceUUID ( const NimBLEUUID & serviceUUID )

Remove a service UUID from the advertisement.

Parameters

[in] serviceUUID The UUID of the service to remove.

Returns: True if successful or uuid not found, false if uuid error or data could not be reset.

◆ setAddress()

void NimBLEExtAdvertisement::setAddress ( const NimBLEAddress & addr )

Set the address to use for this advertisement.

Parameters

[in] addr The address to use.

◆ setAnonymous()

void NimBLEExtAdvertisement::setAnonymous ( bool enable )

Sets whether the advertisement should be anonymous.

Parameters

[in] enable Set to true to enable anonymous advertising.

Anonymous advertising omits the device's address from the advertisement.

◆ setAppearance()

bool NimBLEExtAdvertisement::setAppearance ( uint16_t appearance )

Set the appearance.

Parameters

[in] appearance The appearance code value.

Returns: True if successful.

If the appearance value is 0 then it will be removed from the advertisement if set previously.

◆ setCompleteServices()

bool NimBLEExtAdvertisement::setCompleteServices ( const NimBLEUUID & uuid )

Set a single service to advertise as a complete list of services.

Parameters

[in] uuid The service to advertise.

Returns: True if successful.

◆ setCompleteServices16()

bool NimBLEExtAdvertisement::setCompleteServices16 ( const std::vector< NimBLEUUID > & v_uuid )

Set the complete list of 16 bit services to advertise.

Parameters

[in] v_uuid A vector of 16 bit UUID's to advertise.

Returns: True if successful.

◆ setCompleteServices32()

bool NimBLEExtAdvertisement::setCompleteServices32 ( const std::vector< NimBLEUUID > & v_uuid )

Set the complete list of 32 bit services to advertise.

Parameters

[in] v_uuid A vector of 32 bit UUID's to advertise.

Returns: True if successful.

◆ setConnectable()

void NimBLEExtAdvertisement::setConnectable ( bool enable )

Sets wether this advertisement should advertise as a connectable device.

Parameters

[in] enable True = connectable.

◆ setData()

bool NimBLEExtAdvertisement::setData	(	const uint8_t *	data,
		size_t	length
	)

Set the advertisement data.

Parameters

[in]	data	The data to be set as the payload.
[in]	length	The size of data.

Returns: True if successful, false if the data is too large.

This will completely replace any data that was previously set.

◆ setDirected()

void NimBLEExtAdvertisement::setDirected	(	bool	enable,
		bool	high_duty = `true`
	)

Enable or disable direct advertisements to the peer set with NimBLEExtAdvertisement::setDirectedPeer

Parameters

[in]	enable	true = send directed advertisements to peer.
[in]	high_duty	true = use fast advertising rate, default - true.

◆ setDirectedPeer()

void NimBLEExtAdvertisement::setDirectedPeer ( const NimBLEAddress & addr )

Sets the peer to directly advertise to.

Parameters

[in] addr The address of the peer to direct the advertisements.

◆ setFlags()

bool NimBLEExtAdvertisement::setFlags ( uint8_t flag )

Set the advertisement flags.

Parameters

[in]

flag

The flags to be set in the advertisement.

BLE_HS_ADV_F_DISC_LTD
BLE_HS_ADV_F_DISC_GEN
BLE_HS_ADV_F_BREDR_UNSUP - must always use with NimBLE

Returns: True if successful.

If the flag value is 0 then it will be removed from the advertisement if set previously.

◆ setLegacyAdvertising()

void NimBLEExtAdvertisement::setLegacyAdvertising ( bool enable )

Sets wether the advertisement should use legacy (BLE 4.0, 31 bytes max) advertising.

Parameters

[in] enable true = using legacy advertising.

◆ setManufacturerData() [1/3]

bool NimBLEExtAdvertisement::setManufacturerData ( const std::string & data )

Set manufacturer specific data.

Parameters

[in] data The manufacturer data to advertise.

Returns: True if successful.

◆ setManufacturerData() [2/3]

bool NimBLEExtAdvertisement::setManufacturerData ( const std::vector< uint8_t > & data )

Set manufacturer specific data.

Parameters

[in] data The manufacturer data to advertise.

Returns: True if successful.

◆ setManufacturerData() [3/3]

bool NimBLEExtAdvertisement::setManufacturerData	(	const uint8_t *	data,
		size_t	length
	)

Set manufacturer specific data.

Parameters

[in]	data	The manufacturer data to advertise.
[in]	length	The length of the data.

Returns: True if successful.

◆ setMaxInterval()

void NimBLEExtAdvertisement::setMaxInterval ( uint32_t maxinterval )

Set the maximum advertising interval.

Parameters

[in] maxinterval Maximum value for advertising interval in 0.625ms units, 0 = use default.

◆ setMinInterval()

void NimBLEExtAdvertisement::setMinInterval ( uint32_t mininterval )

Set the minimum advertising interval.

Parameters

[in] mininterval Minimum value for advertising interval in 0.625ms units, 0 = use default.

◆ setName()

bool NimBLEExtAdvertisement::setName	(	const std::string &	name,
		bool	isComplete = `true`
	)

Set the complete name of this device.

Parameters

[in]	name	The name to advertise.
[in]	isComplete	If true the name is complete, if false it is shortened.

Returns: True if successful.

◆ setPartialServices()

bool NimBLEExtAdvertisement::setPartialServices ( const NimBLEUUID & uuid )

Set a single service to advertise as a partial list of services.

Parameters

[in] uuid The service to advertise.

Returns: True if successful.

◆ setPartialServices16()

bool NimBLEExtAdvertisement::setPartialServices16 ( const std::vector< NimBLEUUID > & v_uuid )

Set the partial list of services to advertise.

Parameters

[in] v_uuid A vector of 16 bit UUID's to advertise.

Returns: True if successful.

◆ setPartialServices32()

bool NimBLEExtAdvertisement::setPartialServices32 ( const std::vector< NimBLEUUID > & v_uuid )

Set the partial list of services to advertise.

Parameters

[in] v_uuid A vector of 32 bit UUID's to advertise.

Returns: True if successful.

◆ setPreferredParams()

bool NimBLEExtAdvertisement::setPreferredParams	(	uint16_t	minInterval,
		uint16_t	maxInterval
	)

Set the preferred min and max connection intervals to advertise.

Parameters

[in]	minInterval	The minimum preferred connection interval.
[in]	maxInterval	The Maximum preferred connection interval.

Range = 0x0006(7.5ms) to 0x0C80(4000ms), values not within the range will be limited to this range.

Returns: True if successful.

◆ setPrimaryChannels()

void NimBLEExtAdvertisement::setPrimaryChannels	(	bool	ch37,
		bool	ch38,
		bool	ch39
	)

Sets The primary channels to advertise on.

Parameters

[in]	ch37	Advertise on channel 37.
[in]	ch38	Advertise on channel 38.
[in]	ch39	Advertise on channel 39.

This will set a bitmask using the input parameters to allow different
combinations. If all inputs are false then all 3 channels will be used.

◆ setPrimaryPhy()

void NimBLEExtAdvertisement::setPrimaryPhy ( uint8_t phy )

Set the primary advertising PHY to use.

Parameters

[in]

phy

Can be one of following constants:

BLE_HCI_LE_PHY_1M
BLE_HCI_LE_PHY_CODED

◆ setScanFilter()

void NimBLEExtAdvertisement::setScanFilter	(	bool	scanRequestWhitelistOnly,
		bool	connectWhitelistOnly
	)

Set the filtering for the scan filter.

Parameters

[in]	scanRequestWhitelistOnly	If true, only allow scan requests from those on the white list.
[in]	connectWhitelistOnly	If true, only allow connections from those on the white list.

◆ setScannable()

void NimBLEExtAdvertisement::setScannable ( bool enable )

Sets wether the advertisement has scan response data available.

Parameters

[in] enable true = scan response is available.

◆ setSecondaryPhy()

void NimBLEExtAdvertisement::setSecondaryPhy ( uint8_t phy )

Set the secondary advertising PHY to use.

Parameters

[in]

phy

Can be one of following constants:

BLE_HCI_LE_PHY_1M
BLE_HCI_LE_PHY_2M
BLE_HCI_LE_PHY_CODED

◆ setServiceData() [1/3]

bool NimBLEExtAdvertisement::setServiceData	(	const NimBLEUUID &	uuid,
		const std::string &	data
	)

Set the service data (UUID + data)

Parameters

[in]	uuid	The UUID to set with the service data.
[in]	data	The data to be associated with the service data advertised.

Returns: True if the service data was set successfully.

Note: If data length is 0 the service data will not be advertised.

◆ setServiceData() [2/3]

bool NimBLEExtAdvertisement::setServiceData	(	const NimBLEUUID &	uuid,
		const std::vector< uint8_t > &	data
	)

Set the service data advertised for the UUID.

Parameters

[in]	uuid	The UUID the service data belongs to.
[in]	data	The data to advertise.

Returns: True if the service data was set successfully.

Note: If data length is 0 the service data will not be advertised.

◆ setServiceData() [3/3]

bool NimBLEExtAdvertisement::setServiceData	(	const NimBLEUUID &	uuid,
		const uint8_t *	data,
		size_t	length
	)

Set the service data advertised for the UUID.

Parameters

[in]	uuid	The UUID the service data belongs to.
[in]	data	The data to advertise.
[in]	length	The length of the data.

Note: If data length is 0 the service data will not be advertised.

Returns: True if successful, false if data length is too long or could not be set.

◆ setShortName()

bool NimBLEExtAdvertisement::setShortName ( const std::string & name )

Set the short name.

Parameters

[in] name The short name of the device.

Returns: True if successful.

◆ setTxPower()

void NimBLEExtAdvertisement::setTxPower ( int8_t dbm )

Sets the transmission power level for this advertisement.

Parameters

[in] dbm the transmission power to use in dbm.

The allowable value range depends on device hardware.

◆ setURI()

bool NimBLEExtAdvertisement::setURI ( const std::string & uri )

Set the URI to advertise.

Parameters

[in] uri The uri to advertise.

Returns: True if successful.

◆ toString()

std::string NimBLEExtAdvertisement::toString ( ) const

Get the string representation of the advertisement data.

Returns: The string representation of the advertisement data.

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ NimBLEExtAdvertisement()

Member Function Documentation

◆ addData() [1/2]

◆ addData() [2/2]

◆ addServiceUUID() [1/2]

◆ addServiceUUID() [2/2]

◆ clearData()

◆ enableScanRequestCallback()

◆ getDataLocation()

◆ removeData()

◆ removeServiceUUID() [1/2]

◆ removeServiceUUID() [2/2]

◆ setAddress()

◆ setAnonymous()

◆ setAppearance()

◆ setCompleteServices()

◆ setCompleteServices16()

◆ setCompleteServices32()

◆ setConnectable()

◆ setData()

◆ setDirected()

◆ setDirectedPeer()

◆ setFlags()

◆ setLegacyAdvertising()

◆ setManufacturerData() [1/3]

◆ setManufacturerData() [2/3]

◆ setManufacturerData() [3/3]

◆ setMaxInterval()

◆ setMinInterval()

◆ setName()

◆ setPartialServices()

◆ setPartialServices16()

◆ setPartialServices32()

◆ setPreferredParams()

◆ setPrimaryChannels()

◆ setPrimaryPhy()

◆ setScanFilter()

◆ setScannable()

◆ setSecondaryPhy()

◆ setServiceData() [1/3]

◆ setServiceData() [2/3]

◆ setServiceData() [3/3]

◆ setShortName()

◆ setTxPower()

◆ setURI()

◆ toString()