The Instaburst TX module acts as a replacement for the regular advertiser, providing higher throughput at the expense of breaking spec-compliance. More...

Data Structures
struct	instaburst_tx_config_t
	Instaburst TX configuration. More...

struct	instaburst_tx_t
	Instaburst instance structure. More...

Macros
#define	INSTABURST_TX_BUFFER_MIN_SIZE
	Smallest packet buffer size allowed. More...

Typedefs
typedef void(*	instaburst_tx_complete_t) (struct instaburst_tx *p_tx, nrf_mesh_tx_token_t tx_token, timestamp_t timestamp)
	TX Complete callback to be called when all repeats of a buffer have been sent. More...

Functions
void	instaburst_tx_init (uint32_t lfclk_ppm)
	Initializes the Instaburst TX module. More...

void	instaburst_tx_instance_init (instaburst_tx_t p_instaburst, const instaburst_tx_config_t p_config, uint8_t *p_packet_buffer, uint32_t packet_buffer_size)
	Initializes an Instaburst TX instance. More...

void	instaburst_tx_enable (instaburst_tx_t *p_instaburst)
	Enables the given Instaburst instance. More...

void	instaburst_tx_disable (instaburst_tx_t *p_instaburst)
	Disables the given Instaburst instance. More...

bool	instaburst_tx_is_enabled (const instaburst_tx_t *p_instaburst)
	Checks if the Instaburst instance is enabled. More...

uint8_t *	instaburst_tx_buffer_alloc (instaburst_tx_t *p_instaburst, uint32_t data_len, nrf_mesh_tx_token_t tx_token)
	Allocates a buffer for transmission. More...

void	instaburst_tx_buffer_commit (instaburst_tx_t p_instaburst, const uint8_t p_buffer)
	Commits the given buffer for transmission. More...

void	instaburst_tx_buffer_discard (instaburst_tx_t p_instaburst, const uint8_t p_buffer)
	Discards the given buffer, freeing any memory associated with it. More...

bool	instaburst_tx_finalize (instaburst_tx_t *p_instaburst)
	Finalizes the TX event under construction, putting it up for transmission. More...

void	instaburst_tx_buffer_lock (bool lock)
	Locks the current buffer to prevent it from being automatically transmitted on the next advertisement. More...

void	instaburst_tx_interval_set (instaburst_tx_t *p_instaburst, uint32_t interval_ms)
	Sets the TX interval for the given Instaburst instance. More...

static uint32_t	instaburst_tx_interval_get (const instaburst_tx_t *p_instaburst)
	Gets the TX interval for the given Instaburst instance. More...

void	instaburst_tx_tx_power_set (instaburst_tx_t *p_instaburst, radio_tx_power_t tx_power)
	Sets the TX power for the given Instaburst instance. More...

static radio_tx_power_t	instaburst_tx_tx_power_get (const instaburst_tx_t *p_instaburst)
	Gets the TX power for the given Instaburst instance. More...

Detailed Description

The Instaburst TX module acts as a replacement for the regular advertiser, providing higher throughput at the expense of breaking spec-compliance.

The Instaburst TX module allocates user data in a generic buffer, then dynamically makes a decision on how to transmit the user data on every advertising event. If the buffer payload can fit inside a regular advertising packet when the advertising event starts, the module transmits the buffer as a regular advertising packet. Otherwise, it will transmit an Advertising Extension indication packet pointing to an Auxiliary advertising packet in a secondary advertising channel. This Auxiliary packet will contain the actual packet data, and may point to yet another Auxiliary packet if it can't fit all the user data into a single packet.

To distinguish Auxiliary packets, Instaburst makes a CRC16 hash of the buffer contents, and uses that as the Advertisement Data Identification. This way, a scanner may choose to ignore the Auxiliary packet if it has seen its contents before.

Warning: Instaburst is a Nordic-specific feature that does not adhere to the Bluetooth Mesh specification. It does not have the same requirements for test coverage, API stability or specification compliance as the rest of Nordic's nRF5 SDK for Mesh.

Macro Definition Documentation

◆ INSTABURST_TX_BUFFER_MIN_SIZE

#define INSTABURST_TX_BUFFER_MIN_SIZE

Value:

(sizeof(packet_buffer_packet_t) + sizeof(adv_ext_tx_event_t) + \

(sizeof(adv_ext_tx_packet_t) + ADV_EXT_PACKET_LEN_MAX) * ADV_EXT_TX_CHAIN_MAX_COUNT)

Smallest packet buffer size allowed.

Definition at line 76 of file instaburst_tx.h.

Typedef Documentation

◆ instaburst_tx_complete_t

typedef void(* instaburst_tx_complete_t) (struct instaburst_tx *p_tx, nrf_mesh_tx_token_t tx_token, timestamp_t timestamp)

TX Complete callback to be called when all repeats of a buffer have been sent.

Parameters

[in,out]	p_tx	Instaburst instance the buffer was allocated to.
[in]	tx_token	Token passed to the alloc call for this buffer.
[in]	timestamp	Timestamp of the first bit of the packet header of the last packet in the chain (in device time).

Definition at line 91 of file instaburst_tx.h.

Function Documentation

◆ instaburst_tx_init()

void instaburst_tx_init ( uint32_t lfclk_ppm )

Initializes the Instaburst TX module.

Parameters

[in] lfclk_ppm The accuracy of the low frequency clock in Parts Per Million (PPM).

◆ instaburst_tx_instance_init()

void instaburst_tx_instance_init	(	instaburst_tx_t *	p_instaburst,
		const instaburst_tx_config_t *	p_config,
		uint8_t *	p_packet_buffer,
		uint32_t	packet_buffer_size
	)

Initializes an Instaburst TX instance.

Parameters

[in,out]	p_instaburst	Instance to initialize.
[in]	p_config	Configuration to use for this instance.
[in,out]	p_packet_buffer	Packet buffer for this instance.
[in]	packet_buffer_size	Size of the given packet buffer. Must be at least INSTABURST_TX_BUFFER_MIN_SIZE bytes.

◆ instaburst_tx_enable()

void instaburst_tx_enable ( instaburst_tx_t * p_instaburst )

Enables the given Instaburst instance.

Parameters

[in,out] p_instaburst Instance to enable.

◆ instaburst_tx_disable()

void instaburst_tx_disable ( instaburst_tx_t * p_instaburst )

Disables the given Instaburst instance.

Parameters

[in,out] p_instaburst Instance to disable.

◆ instaburst_tx_is_enabled()

bool instaburst_tx_is_enabled ( const instaburst_tx_t * p_instaburst )

Checks if the Instaburst instance is enabled.

Parameters

[in] p_instaburst Instaburst instance pointer.

Returns: true if the Instaburst instance is enabled (scheduled), false otherwise.

◆ instaburst_tx_buffer_alloc()

uint8_t* instaburst_tx_buffer_alloc	(	instaburst_tx_t *	p_instaburst,
		uint32_t	data_len,
		nrf_mesh_tx_token_t	tx_token
	)

Allocates a buffer for transmission.

Warning: Only one buffer can be allocated at a time. To allocate a second buffer, free or discard the previous.

Parameters

[in,out]	p_instaburst	Instaburst instance to allocate from.
[in]	data_len	Desired buffer length.
[in]	tx_token	Token to pass to the buffer to identify it on the TX complete event.

Returns: A pointer to a newly allocated TX buffer, or NULL if the allocation wasn't successful.

◆ instaburst_tx_buffer_commit()

void instaburst_tx_buffer_commit	(	instaburst_tx_t *	p_instaburst,
		const uint8_t *	p_buffer
	)

Commits the given buffer for transmission.

Parameters

[in,out]	p_instaburst	Instaburst instance the buffer was allocated from.
[in]	p_buffer	Buffer to commit. Must have been acquired from a call to instaburst_tx_buffer_alloc.

◆ instaburst_tx_buffer_discard()

void instaburst_tx_buffer_discard	(	instaburst_tx_t *	p_instaburst,
		const uint8_t *	p_buffer
	)

Discards the given buffer, freeing any memory associated with it.

Parameters

[in,out]	p_instaburst	Instaburst instance the buffer was allocated from.
[in]	p_buffer	Buffer to discard. Must have been acquired from a call to instaburst_tx_buffer_alloc.

◆ instaburst_tx_finalize()

bool instaburst_tx_finalize ( instaburst_tx_t * p_instaburst )

Finalizes the TX event under construction, putting it up for transmission.

This function is automatically called at every advertising event, and the user does not have to call it for the module to operate normally.

Note: If the buffer lock is active, this function does nothing. See instaburst_tx_buffer_lock.

Parameters

[in,out] p_instaburst Instance to finalize a packet of.

Returns: Whether the current packet was successfully finalized.

◆ instaburst_tx_buffer_lock()

void instaburst_tx_buffer_lock ( bool lock )

Locks the current buffer to prevent it from being automatically transmitted on the next advertisement.

Use this function to ensure that all buffers committed while the lock is active end up in the same event.

Note: This function holds a counter, allowing multiple locks to occur. Each lock has to correspond to an unlock.

Parameters

[in] lock Flag indicating whether the buffer should be locked.

◆ instaburst_tx_interval_set()

void instaburst_tx_interval_set	(	instaburst_tx_t *	p_instaburst,
		uint32_t	interval_ms
	)

Sets the TX interval for the given Instaburst instance.

Parameters

[in,out]	p_instaburst	Instaburst instance to configure.
[in]	interval_ms	New transmission interval in milliseconds. Must be between BEARER_ADV_INT_MIN_MS and BEARER_ADV_INT_MAX_MS.

◆ instaburst_tx_interval_get()

static uint32_t instaburst_tx_interval_get ( const instaburst_tx_t * p_instaburst )

inlinestatic

Gets the TX interval for the given Instaburst instance.

Parameters

[in] p_instaburst Instaburst instance pointer.

Returns: the current TX interval in milliseconds.

Definition at line 278 of file instaburst_tx.h.

References instaburst_tx_tx_power_set().

◆ instaburst_tx_tx_power_set()

void instaburst_tx_tx_power_set	(	instaburst_tx_t *	p_instaburst,
		radio_tx_power_t	tx_power
	)

Sets the TX power for the given Instaburst instance.

Parameters

[in,out]	p_instaburst	Instaburst instance to configure.
[in]	tx_power	New TX power.

Referenced by instaburst_tx_interval_get().

◆ instaburst_tx_tx_power_get()

static radio_tx_power_t instaburst_tx_tx_power_get ( const instaburst_tx_t * p_instaburst )

inlinestatic

Gets the TX power for the given Instaburst instance.

Parameters

[in] p_instaburst Instaburst instance pointer.

Returns: the current TX power.

Definition at line 298 of file instaburst_tx.h.

Data Structures

Macros

Typedefs

Functions

Detailed Description

Macro Definition Documentation

◆ INSTABURST_TX_BUFFER_MIN_SIZE

Typedef Documentation

◆ instaburst_tx_complete_t

Function Documentation

◆ instaburst_tx_init()

◆ instaburst_tx_instance_init()

◆ instaburst_tx_enable()

◆ instaburst_tx_disable()

◆ instaburst_tx_is_enabled()

◆ instaburst_tx_buffer_alloc()

◆ instaburst_tx_buffer_commit()

◆ instaburst_tx_buffer_discard()

◆ instaburst_tx_finalize()

◆ instaburst_tx_buffer_lock()

◆ instaburst_tx_interval_set()

◆ instaburst_tx_interval_get()

◆ instaburst_tx_tx_power_set()

◆ instaburst_tx_tx_power_get()