Implements a Bluetooth LE 4.0 compliant advertiser. More...

Data Structures
struct	adv_packet_t
	The structure defining the contents of an advertisement packet. More...

struct	advertiser_channels_t
	Advertiser channel configuration. More...

struct	advertiser_config_t
	Configuration of the advertiser to be used when sending the packets. More...

struct	advertiser_tx_complete_params_t

struct	advertiser_t
	Single advertiser instance. More...

Macros
#define	ADVERTISER_INTERVAL_RANDOMIZATION_US MS_TO_US(10)
	Advertiser time randomization offset per interval, as defined by the Bluetooth Specification. More...

#define	ADVERTISER_REPEAT_INFINITE 0xFF
	Define usedd with adv_packet_t to make the packet transmit indefinitely. More...

#define	ADVERTISER_PACKET_BUFFER_PACKET_MAXLEN (sizeof(packet_buffer_packet_t) + sizeof(adv_packet_t))
	Maximum length of an advertisement packet in the buffer. More...

Typedefs
typedef void(*	advertiser_tx_complete_cb_t) (advertiser_t *p_adv, nrf_mesh_tx_token_t token, timestamp_t timestamp)
	Transmit complete callback for notifying the users after a given packet has been sent the desired number of times. More...

Functions
void	advertiser_init (void)
	Initialize the advertiser module.

void	advertiser_instance_init (advertiser_t p_adv, advertiser_tx_complete_cb_t tx_complete_cb, uint8_t p_buffer, uint32_t buffer_size)
	Initialize an advertiser instance. More...

void	advertiser_enable (advertiser_t *p_adv)
	Enables the advertiser instance given. More...

void	advertiser_disable (advertiser_t *p_adv)
	Disables the advertiser instance given, so that no more packets are sent from this advertiser even if advertiser_packet_send is called afterwards. More...

adv_packet_t *	advertiser_packet_alloc (advertiser_t *p_adv, uint32_t adv_payload_size)
	Allocates a buffer, if available, from the given advertiser instance. More...

void	advertiser_packet_send (advertiser_t p_adv, adv_packet_t p_packet)
	Sends a given packet using the given advertiser instance, this can be called multiple times without having to wait for a tx_complete (. More...

void	advertiser_packet_discard (advertiser_t p_adv, adv_packet_t p_packet)
	Discards an allocated advertisement packet. More...

void	advertiser_config_set (advertiser_t p_adv, const advertiser_config_t p_config)
	Updates the advertiser configuration. More...

void	advertiser_config_get (const advertiser_t p_adv, advertiser_config_t p_config)
	Gets the current advertiser configuration. More...

void	advertiser_channels_set (advertiser_t p_adv, const advertiser_channels_t p_channels)
	Sets the advertiser channels used by the given advertiser instance. More...

void	advertiser_address_set (advertiser_t p_adv, const ble_gap_addr_t p_addr)
	Sets the advertiser address used by the given advertiser instance. More...

static void	advertiser_address_get (const advertiser_t p_adv, ble_gap_addr_t p_addr)
	Gets the advertiser address used by the given advertiser instance. More...

void	advertiser_interval_set (advertiser_t *p_adv, uint32_t interval_ms)
	Sets the advertisement interval for the given advertiser. More...

static uint32_t	advertiser_interval_get (const advertiser_t *p_adv)
	Gets the given advertiser's advertisement interval. More...

void	advertiser_tx_power_set (advertiser_t *p_adv, radio_tx_power_t tx_power)
	Sets the TX power for the given advertiser. More...

static radio_tx_power_t	advertiser_tx_power_get (const advertiser_t *p_adv)
	Gets the TX power for the given advertiser. More...

void	advertiser_flush (advertiser_t *p_adv)
	Flushes the given advertiser's packet queue. More...

void	advertiser_address_default_get (ble_gap_addr_t *p_addr)
	Gets the default advertisement address from device factory information structure. More...

static bool	advertiser_is_enabled (const advertiser_t *p_adv)
	Checks if an advertiser is enabled. More...

Detailed Description

Implements a Bluetooth LE 4.0 compliant advertiser.

Macro Definition Documentation

◆ ADVERTISER_INTERVAL_RANDOMIZATION_US

#define ADVERTISER_INTERVAL_RANDOMIZATION_US MS_TO_US(10)

Advertiser time randomization offset per interval, as defined by the Bluetooth Specification.

Definition at line 56 of file advertiser.h.

◆ ADVERTISER_REPEAT_INFINITE

#define ADVERTISER_REPEAT_INFINITE 0xFF

Define usedd with adv_packet_t to make the packet transmit indefinitely.

Definition at line 58 of file advertiser.h.

◆ ADVERTISER_PACKET_BUFFER_PACKET_MAXLEN

#define ADVERTISER_PACKET_BUFFER_PACKET_MAXLEN (sizeof(packet_buffer_packet_t) + sizeof(adv_packet_t))

Maximum length of an advertisement packet in the buffer.

Can be used to create buffers that can fit an exact number of packets.

Definition at line 62 of file advertiser.h.

Typedef Documentation

◆ advertiser_tx_complete_cb_t

typedef void(* advertiser_tx_complete_cb_t) (advertiser_t *p_adv, nrf_mesh_tx_token_t token, timestamp_t timestamp)

Transmit complete callback for notifying the users after a given packet has been sent the desired number of times.

Packets that are repeated indefinitely will get this callback on every transmission.

Note: The timestamp parameter is clocked the last time the packet goes on air (the last channel in the configuration, on the last repeat), at the time when the first bit of the p_packet->packet goes on air.

Parameters

[in]	p_adv	The advertiser instance used in sending the packet.
[in]	token	TX token, as set by the application.
[in]	timestamp	Timestamp of the last transmission of the packet, in microseconds.

Definition at line 117 of file advertiser.h.

Function Documentation

◆ advertiser_instance_init()

void advertiser_instance_init	(	advertiser_t *	p_adv,
		advertiser_tx_complete_cb_t	tx_complete_cb,
		uint8_t *	p_buffer,
		uint32_t	buffer_size
	)

Initialize an advertiser instance.

Note: This function can be called multiple times to initialize different advertiser instances

Parameters

[in,out]	p_adv	The advertiser instance to initialize, this must be a statically allocated object.
[in]	tx_complete_cb	The transmit complete callback function pointer, or NULL.
[in]	p_buffer	The raw buffer to use when sending packets, this must be a statically allocated buffer that is only dedicated to the given advertiser instance `p_adv`.
[in]	buffer_size	The buffer size in bytes.

◆ advertiser_enable()

void advertiser_enable ( advertiser_t * p_adv )

Enables the advertiser instance given.

Parameters

[in,out] p_adv Advertiser to enable.

◆ advertiser_disable()

void advertiser_disable ( advertiser_t * p_adv )

Disables the advertiser instance given, so that no more packets are sent from this advertiser even if advertiser_packet_send is called afterwards.

Parameters

[in,out] p_adv Advertiser to disable.

◆ advertiser_packet_alloc()

adv_packet_t* advertiser_packet_alloc	(	advertiser_t *	p_adv,
		uint32_t	adv_payload_size
	)

Allocates a buffer, if available, from the given advertiser instance.

Note: The returned packet has all headerfields set with default values. The token is set to 0, and may be altered by the application.

Parameters

[in,out]	p_adv	The advertiser instance to use, it must have been successfully initialized via advertiser_init.
[in]	adv_payload_size	The advertisement packet payload size.

Returns: A pointer to the allocated advertisement packet.

◆ advertiser_packet_send()

void advertiser_packet_send	(	advertiser_t *	p_adv,
		adv_packet_t *	p_packet
	)

Sends a given packet using the given advertiser instance, this can be called multiple times without having to wait for a tx_complete (.

See also: advertiser_tx_complete_cb_t) on the previous packets.

Note: Once the packet is sent successfully, the tx_complete_callback in the p_adv will be called with p_packet and p_adv as parameters to the callback.

Parameters

[in,out]	p_adv	An already initialized advertiser instance.
[in,out]	p_packet	A valid packet that was allocated using advertiser_packet_alloc, and the the same advertiser instance as given to this function.

◆ advertiser_packet_discard()

void advertiser_packet_discard	(	advertiser_t *	p_adv,
		adv_packet_t *	p_packet
	)

Discards an allocated advertisement packet.

The packet memory will be freed, and all contents will be lost.

Parameters

[in,out]	p_adv	Advertiser owning the packet to discard.
[in,out]	p_packet	Packet to discard.

◆ advertiser_config_set()

void advertiser_config_set	(	advertiser_t *	p_adv,
		const advertiser_config_t *	p_config
	)

Updates the advertiser configuration.

Note: The defaults will be already set on advertiser_init, to see what the defaults are see advertiser_config_t.

Parameters

[in,out]	p_adv	An already initialized advertiser instance.
[in]	p_config	The new configuration to use with the given advertiser instance.

◆ advertiser_config_get()

void advertiser_config_get	(	const advertiser_t *	p_adv,
		advertiser_config_t *	p_config
	)

Gets the current advertiser configuration.

Parameters

[in]	p_adv	An already initialized advertiser instance.
[out]	p_config	A configuration instance to populate.

◆ advertiser_channels_set()

void advertiser_channels_set	(	advertiser_t *	p_adv,
		const advertiser_channels_t *	p_channels
	)

Sets the advertiser channels used by the given advertiser instance.

Parameters

[in,out]	p_adv	Advertiser instance to configure.
[in]	p_channels	New channel configuration.

◆ advertiser_address_set()

void advertiser_address_set	(	advertiser_t *	p_adv,
		const ble_gap_addr_t *	p_addr
	)

Sets the advertiser address used by the given advertiser instance.

Note: Only BLE_GAP_ADDR_TYPE_PUBLIC and BLE_GAP_ADDR_TYPE_RANDOM_STATIC address types are supported. The advertisement address may be altered to ensure Bluetooth Core Specification v4.0 compliance.

Parameters

[in,out]	p_adv	Advertiser instance to configure.
[in]	p_addr	New GAP advertisement address.

◆ advertiser_address_get()

static void advertiser_address_get	(	const advertiser_t *	p_adv,
		ble_gap_addr_t *	p_addr
	)

inlinestatic

Gets the advertiser address used by the given advertiser instance.

Parameters

[in]	p_adv	Advertiser instance pointer.
[out]	p_addr	GAP address pointer to write the address.

Definition at line 259 of file advertiser.h.

References advertiser_config_t::adv_addr, advertiser_interval_set(), and advertiser_t::config.

◆ advertiser_interval_set()

void advertiser_interval_set	(	advertiser_t *	p_adv,
		uint32_t	interval_ms
	)

Sets the advertisement interval for the given advertiser.

Parameters

[in,out]	p_adv	Advertiser to configure.
[in]	interval_ms	Advertisement interval in milliseconds.

Referenced by advertiser_address_get().

◆ advertiser_interval_get()

static uint32_t advertiser_interval_get ( const advertiser_t * p_adv )

inlinestatic

Gets the given advertiser's advertisement interval.

Parameters

[in] p_adv Advertiser instance pointer.

Returns: Advertisement interval in milliseconds.

Definition at line 279 of file advertiser.h.

References advertiser_config_t::advertisement_interval_us, advertiser_tx_power_set(), and advertiser_t::config.

◆ advertiser_tx_power_set()

void advertiser_tx_power_set	(	advertiser_t *	p_adv,
		radio_tx_power_t	tx_power
	)

Sets the TX power for the given advertiser.

Parameters

[in,out]	p_adv	Advertiser to configure.
[in]	tx_power	New TX power.

Referenced by advertiser_interval_get().

◆ advertiser_tx_power_get()

static radio_tx_power_t advertiser_tx_power_get ( const advertiser_t * p_adv )

inlinestatic

Gets the TX power for the given advertiser.

Parameters

[in] p_adv Advertiser instance pointer.

Returns: the TX power value.

Definition at line 299 of file advertiser.h.

References advertiser_address_default_get(), advertiser_flush(), and advertiser_t::broadcast.

◆ advertiser_flush()

void advertiser_flush ( advertiser_t * p_adv )

Flushes the given advertiser's packet queue.

Warning: If called in the middle of a transmission, the ongoing transmission will finish, and produce a TX-complete event, potentially after the call to this function returns.; Any packets that have been allocated, but not sent must either be sent or freed before this call.

Parameters

[in,out] p_adv Advertiser instance to flush and disable.

Referenced by advertiser_tx_power_get().

◆ advertiser_address_default_get()

void advertiser_address_default_get ( ble_gap_addr_t * p_addr )

Gets the default advertisement address from device factory information structure.

Parameters

[in,out] p_addr Address structure to return the address in.

Referenced by advertiser_tx_power_get().

◆ advertiser_is_enabled()

static bool advertiser_is_enabled ( const advertiser_t * p_adv )

inlinestatic

Checks if an advertiser is enabled.

Parameters

[in] p_adv Advertiser instance pointer.

Returns: true if the given advertiser is enabled.

Definition at line 331 of file advertiser.h.

References advertiser_t::enabled.

Data Structures

Macros

Typedefs

Functions

Detailed Description

Macro Definition Documentation

◆ ADVERTISER_INTERVAL_RANDOMIZATION_US

◆ ADVERTISER_REPEAT_INFINITE

◆ ADVERTISER_PACKET_BUFFER_PACKET_MAXLEN

Typedef Documentation

◆ advertiser_tx_complete_cb_t

Function Documentation

◆ advertiser_instance_init()

◆ advertiser_enable()

◆ advertiser_disable()

◆ advertiser_packet_alloc()

◆ advertiser_packet_send()

◆ advertiser_packet_discard()

◆ advertiser_config_set()

◆ advertiser_config_get()

◆ advertiser_channels_set()

◆ advertiser_address_set()

◆ advertiser_address_get()

◆ advertiser_interval_set()

◆ advertiser_interval_get()

◆ advertiser_tx_power_set()

◆ advertiser_tx_power_get()

◆ advertiser_flush()

◆ advertiser_address_default_get()

◆ advertiser_is_enabled()