nRF5 SDK for Mesh v3.2.0  08c60f6
Experimental Instaburst TX module

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 an experimental 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 proprietary feature that does not adhere to the Bluetooth Mesh specification. It is currently in an experimental stage, and does not have the same requirements to test coverage, API stability or spec-compliance as the rest of the Nordic 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 77 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_txInstaburst instance the buffer was allocated to.
[in]tx_tokenToken passed to the alloc call for this buffer.
[in]timestampTimestamp of the first bit of the packet header of the last packet in the chain (in device time).

Definition at line 92 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_ppmThe 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_instaburstInstance to initialize.
[in]p_configConfiguration to use for this instance.
[in,out]p_packet_bufferPacket buffer for this instance.
[in]packet_buffer_sizeSize 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_instaburstInstance to enable.

◆ instaburst_tx_disable()

void instaburst_tx_disable ( instaburst_tx_t *  p_instaburst)

Disables the given Instaburst instance.

Parameters
[in,out]p_instaburstInstance 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_instaburstInstaburst 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_instaburstInstaburst instance to allocate from.
[in]data_lenDesired buffer length.
[in]tx_tokenToken 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_instaburstInstaburst instance the buffer was allocated from.
[in]p_bufferBuffer 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_instaburstInstaburst instance the buffer was allocated from.
[in]p_bufferBuffer 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_instaburstInstance 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]lockFlag 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_instaburstInstaburst instance to configure.
[in]interval_msNew 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_instaburstInstaburst instance pointer.
Returns
the current TX interval in milliseconds.

Definition at line 279 of file instaburst_tx.h.

◆ 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_instaburstInstaburst instance to configure.
[in]tx_powerNew TX power.

◆ 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_instaburstInstaburst instance pointer.
Returns
the current TX power.

Definition at line 299 of file instaburst_tx.h.