nRF5 SDK for Mesh v5.0.0
Data Structures | Macros | Typedefs | Functions
Advertiser

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_tadvertiser_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_advThe advertiser instance used in sending the packet.
[in]tokenTX token, as set by the application.
[in]timestampTimestamp 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_advThe advertiser instance to initialize, this must be a statically allocated object.
[in]tx_complete_cbThe transmit complete callback function pointer, or NULL.
[in]p_bufferThe 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_sizeThe buffer size in bytes.

◆ advertiser_enable()

void advertiser_enable ( advertiser_t p_adv)

Enables the advertiser instance given.

Parameters
[in,out]p_advAdvertiser 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_advAdvertiser 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_advThe advertiser instance to use, it must have been successfully initialized via advertiser_init.
[in]adv_payload_sizeThe 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_advAn already initialized advertiser instance.
[in,out]p_packetA 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_advAdvertiser owning the packet to discard.
[in,out]p_packetPacket 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_advAn already initialized advertiser instance.
[in]p_configThe 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_advAn already initialized advertiser instance.
[out]p_configA 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_advAdvertiser instance to configure.
[in]p_channelsNew 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_advAdvertiser instance to configure.
[in]p_addrNew 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_advAdvertiser instance pointer.
[out]p_addrGAP 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_advAdvertiser to configure.
[in]interval_msAdvertisement 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_advAdvertiser 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_advAdvertiser to configure.
[in]tx_powerNew 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_advAdvertiser 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_advAdvertiser 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_addrAddress 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_advAdvertiser instance pointer.
Returns
true if the given advertiser is enabled.

Definition at line 331 of file advertiser.h.

References advertiser_t::enabled.


Documentation feedback | Developer Zone | Subscribe | Updated