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, uint32_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)
	Discard an allocated advertisement packet. More...

void	advertiser_config_set (advertiser_t p_adv, const advertiser_config_t p_config)
	Update 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)
	Set advertiser channels used by the given advertiser instance. More...

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

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

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

void	advertiser_address_default_get (ble_gap_addr_t *p_addr)
	Get the default advertisement address from device factory information structure. 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, uint32_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.

Warning: The TX complete callback comes in the radio IRQ level, and must finish within APPLICATION_TX_COMPLETE_OVERHEAD_US.

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

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

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

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

Set 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_interval_set()

void advertiser_interval_set	(	advertiser_t *	p_adv,
		uint32_t	interval_ms
	)

Set the advertisement interval for the given advertiser.

Parameters

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

◆ advertiser_flush()

void advertiser_flush ( advertiser_t * p_adv )

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

Parameters

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

◆ advertiser_address_default_get()

void advertiser_address_default_get ( ble_gap_addr_t * p_addr )

Get the default advertisement address from device factory information structure.

Parameters

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

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

◆ advertiser_flush()

◆ advertiser_address_default_get()