The Instaburst TX module acts as an experimental replacement for the regular advertiser, providing higher throughput at the expense of breaking spec-compliance.
More...
|
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...
|
|
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.
◆ 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.
◆ instaburst_tx_complete_t
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 92 of file instaburst_tx.h.
◆ 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
-
◆ 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 279 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 299 of file instaburst_tx.h.