nRF51 SDK: Enhanced ShockBurst

| nRF51 SDK

- Home
- Related Pages
- API Reference
- Data Structures

All Data Structures Functions Variables Typedefs Enumerations Enumerator Groups Pages
Enumerations
Enhanced ShockBurst
Proprietary stacks

Enhanced ShockBurst Application Programming Interface (API). More...

## Enumerations

enum | nrf_esb_mode_t { NRF_ESB_MODE_PTX, NRF_ESB_MODE_PRX, NRF_ESB_MODE_PTX, NRF_ESB_MODE_PRX }
| Enumerator used for selecting the ESB mode. More...
enum | nrf_esb_packet_t { NRF_ESB_PACKET_USE_ACK, NRF_ESB_PACKET_NO_ACK, NRF_ESB_PACKET_USE_ACK, NRF_ESB_PACKET_NO_ACK }
| Enumerator used for selecting TX packet type used in PTX mode. More...
enum | nrf_esb_base_address_length_t { NRF_ESB_BASE_ADDRESS_LENGTH_2B, NRF_ESB_BASE_ADDRESS_LENGTH_3B, NRF_ESB_BASE_ADDRESS_LENGTH_4B, NRF_ESB_BASE_ADDRESS_LENGTH_2B, NRF_ESB_BASE_ADDRESS_LENGTH_3B, NRF_ESB_BASE_ADDRESS_LENGTH_4B }
| Enumerator used for selecting the base address length. More...

enum

nrf_esb_output_power_t {
NRF_ESB_OUTPUT_POWER_4_DBM, NRF_ESB_OUTPUT_POWER_0_DBM, NRF_ESB_OUTPUT_POWER_N4_DBM, NRF_ESB_OUTPUT_POWER_N8_DBM,
NRF_ESB_OUTPUT_POWER_N12_DBM, NRF_ESB_OUTPUT_POWER_N16_DBM, NRF_ESB_OUTPUT_POWER_N20_DBM, NRF_ESB_OUTPUT_POWER_4_DBM,
NRF_ESB_OUTPUT_POWER_0_DBM, NRF_ESB_OUTPUT_POWER_N4_DBM, NRF_ESB_OUTPUT_POWER_N8_DBM, NRF_ESB_OUTPUT_POWER_N12_DBM,
NRF_ESB_OUTPUT_POWER_N16_DBM, NRF_ESB_OUTPUT_POWER_N20_DBM
}

| Enumerator used for selecting the TX output power. More...
enum | nrf_esb_datarate_t { NRF_ESB_DATARATE_250_KBPS, NRF_ESB_DATARATE_1_MBPS, NRF_ESB_DATARATE_2_MBPS, NRF_ESB_DATARATE_250_KBPS, NRF_ESB_DATARATE_1_MBPS, NRF_ESB_DATARATE_2_MBPS }
| Enumerator used for selecting the radio data rate. More...
enum | nrf_esb_crc_length_t { NRF_ESB_CRC_OFF, NRF_ESB_CRC_LENGTH_1_BYTE, NRF_ESB_CRC_LENGTH_2_BYTE, NRF_ESB_CRC_OFF, NRF_ESB_CRC_LENGTH_1_BYTE, NRF_ESB_CRC_LENGTH_2_BYTE }
| Enumerator used for selecting the CRC length. More...
enum | nrf_esb_xosc_ctl_t { NRF_ESB_XOSC_CTL_AUTO, NRF_ESB_XOSC_CTL_MANUAL, NRF_ESB_XOSC_CTL_AUTO, NRF_ESB_XOSC_CTL_MANUAL }
| Enumerator used for specifying whether switching the external 16 MHz oscillator on/off shall be handled automatically inside ESB or manually by the application. More...
enum | nrf_esb_mode_t { NRF_ESB_MODE_PTX, NRF_ESB_MODE_PRX, NRF_ESB_MODE_PTX, NRF_ESB_MODE_PRX }
enum | nrf_esb_packet_t { NRF_ESB_PACKET_USE_ACK, NRF_ESB_PACKET_NO_ACK, NRF_ESB_PACKET_USE_ACK, NRF_ESB_PACKET_NO_ACK }
enum | nrf_esb_base_address_length_t { NRF_ESB_BASE_ADDRESS_LENGTH_2B, NRF_ESB_BASE_ADDRESS_LENGTH_3B, NRF_ESB_BASE_ADDRESS_LENGTH_4B, NRF_ESB_BASE_ADDRESS_LENGTH_2B, NRF_ESB_BASE_ADDRESS_LENGTH_3B, NRF_ESB_BASE_ADDRESS_LENGTH_4B }

enum

nrf_esb_output_power_t {
NRF_ESB_OUTPUT_POWER_4_DBM, NRF_ESB_OUTPUT_POWER_0_DBM, NRF_ESB_OUTPUT_POWER_N4_DBM, NRF_ESB_OUTPUT_POWER_N8_DBM,
NRF_ESB_OUTPUT_POWER_N12_DBM, NRF_ESB_OUTPUT_POWER_N16_DBM, NRF_ESB_OUTPUT_POWER_N20_DBM, NRF_ESB_OUTPUT_POWER_4_DBM,
NRF_ESB_OUTPUT_POWER_0_DBM, NRF_ESB_OUTPUT_POWER_N4_DBM, NRF_ESB_OUTPUT_POWER_N8_DBM, NRF_ESB_OUTPUT_POWER_N12_DBM,
NRF_ESB_OUTPUT_POWER_N16_DBM, NRF_ESB_OUTPUT_POWER_N20_DBM
}

enum | nrf_esb_datarate_t { NRF_ESB_DATARATE_250_KBPS, NRF_ESB_DATARATE_1_MBPS, NRF_ESB_DATARATE_2_MBPS, NRF_ESB_DATARATE_250_KBPS, NRF_ESB_DATARATE_1_MBPS, NRF_ESB_DATARATE_2_MBPS }
enum | nrf_esb_crc_length_t { NRF_ESB_CRC_OFF, NRF_ESB_CRC_LENGTH_1_BYTE, NRF_ESB_CRC_LENGTH_2_BYTE, NRF_ESB_CRC_OFF, NRF_ESB_CRC_LENGTH_1_BYTE, NRF_ESB_CRC_LENGTH_2_BYTE }
enum | nrf_esb_xosc_ctl_t { NRF_ESB_XOSC_CTL_AUTO, NRF_ESB_XOSC_CTL_MANUAL, NRF_ESB_XOSC_CTL_AUTO, NRF_ESB_XOSC_CTL_MANUAL }

## General API functions

bool | nrf_esb_init (nrf_esb_mode_t mode)
| Initialize ESB. More...
void | nrf_esb_enable (void)
| Enable ESB. More...
void | nrf_esb_disable (void)
| Disable ESB. More...
bool | nrf_esb_is_enabled (void)

## functions

void | nrf_esb_tx_success (uint32_t tx_pipe, int32_t rssi)
| TX success callback. More...
void | nrf_esb_tx_failed (uint32_t tx_pipe)
| TX failed callback (PTX mode only). More...
void | nrf_esb_rx_data_ready (uint32_t rx_pipe, int32_t rssi)
| RX data ready callback. More...
void | nrf_esb_disabled (void)
| Disabled callback. More...

## Packet transmission and receiving functions

bool | nrf_esb_add_packet_to_tx_fifo (uint32_t pipe, uint8_t *payload, uint32_t payload_length, nrf_esb_packet_t packet_type)
| Add a packet to the tail of the TX FIFO. More...
bool | nrf_esb_fetch_packet_from_rx_fifo (uint32_t pipe, uint8_t *payload, uint32_t *payload_length)
| Fetch a packet from the head of the RX FIFO. More...
uint32_t | nrf_esb_get_tx_fifo_packet_count (uint32_t pipe)
| Get the number of packets residing in the TX FIFO on a specific pipe. More...
uint32_t | nrf_esb_get_rx_fifo_packet_count (uint32_t pipe)
| Get the number of packets residing in the RX FIFO on a specific pipe. More...
void | nrf_esb_flush_tx_fifo (uint32_t pipe)
| Flush the RX FIFO for a specific pipe. More...
void | nrf_esb_flush_rx_fifo (uint32_t pipe)
| Flush the RX FIFO for a specific pipe. More...
uint16_t | nrf_esb_get_tx_attempts (void)
| Get the total number of transmission attempts used for sending the previous successful packet. More...

## Configuration functions

Configuration 'set' functions may only be called while ESB is disabled. The new parameter comes into effect when ESB is enabled again. Configuration 'get' functions may be called at any time.
bool | nrf_esb_set_mode (nrf_esb_mode_t mode)
| Set the mode. More...
nrf_esb_mode_t | nrf_esb_get_mode (void)
| Get function counterpart to nrf_esb_set_mode(). More...
bool | nrf_esb_set_base_address_length (nrf_esb_base_address_length_t length)
| Set the base address length. More...
nrf_esb_base_address_length_t | nrf_esb_get_base_address_length (void)
| Get function counterpart to nrf_esb_set_base_address_length(). More...
bool | nrf_esb_set_base_address_0 (uint32_t base_address)
| Set the base address for pipe 0. More...
uint32_t | nrf_esb_get_base_address_0 (void)
| Get function counterpart to nrf_esb_set_base_address_0(). More...
bool | nrf_esb_set_base_address_1 (uint32_t base_address)
| Set the base address for pipes 1-7. More...
uint32_t | nrf_esb_get_base_address_1 (void)
| Get function counterpart to nrf_esb_set_base_address_1(). More...
bool | nrf_esb_set_address_prefix_byte (uint32_t pipe, uint8_t address)
| Set the address prefix byte for a specific pipe. More...
bool | nrf_esb_get_address_prefix_byte (uint32_t pipe, uint8_t *out_address)
| Get function counterpart to nrf_esb_set_address_prefix_byte(). More...
bool | nrf_esb_set_enabled_prx_pipes (uint32_t pipes)
| Set which pipes the node shall listen on in PRX mode. More...
uint32_t | nrf_esb_get_enabled_prx_pipes (void)
| Get function counterpart to nrf_esb_set_enabled_prx_pipes(). More...
bool | nrf_esb_set_retransmit_delay (uint32_t delay_us)
| Set the retransmission delay. More...
uint32_t | nrf_esb_get_retransmit_delay (void)
| Get function counterpart to nrf_esb_set_retransmit_delay(). More...
bool | nrf_esb_set_max_number_of_tx_attempts (uint16_t attempts)
| Set the maximum number of TX attempts that can be used for a single packet. More...
uint16_t | nrf_esb_get_max_number_of_tx_attempts (void)
| Get function counterpart to nrf_esb_set_max_number_of_retransmits(). More...
bool | nrf_esb_set_channel (uint32_t channel)
| Set the Radio Frequency (RF) channel. More...
uint32_t | nrf_esb_get_channel (void)
| Get function counterpart to nrf_esb_set_channel(). More...
bool | nrf_esb_set_output_power (nrf_esb_output_power_t power)
| Set the radio TX output power. More...
nrf_esb_output_power_t | nrf_esb_get_output_power (void)
| Get function counterpart to nrf_esb_set_output_power(). More...
bool | nrf_esb_set_datarate (nrf_esb_datarate_t datarate)
| Set the radio datarate. More...
nrf_esb_datarate_t | nrf_esb_get_datarate (void)
| Get function counterpart to nrf_esb_set_datarate(). More...
bool | nrf_esb_set_crc_length (nrf_esb_crc_length_t length)
| Set the CRC length. More...
nrf_esb_crc_length_t | nrf_esb_get_crc_length (void)
| Get function counterpart to nrf_esb_set_crc_length(). More...
bool | nrf_esb_set_xosc_ctl (nrf_esb_xosc_ctl_t xosc_ctl)
| Set whether start/stop of external oscillator (XOSC) shall be handled automatically inside ESB or manually by the application. More...
void | nrf_esb_enable_dyn_ack (void)
| Enable dynamic ACK feature. After initialization this feature is disabled. More...
void | nrf_esb_disable_dyn_ack (void)
| Disable dynamic ACK feature. More...
nrf_esb_xosc_ctl_t | nrf_esb_get_xosc_ctl (void)

## Hardware resources used by Enhanced ShockBurst

#define | NRF_ESB_HIGH_IRQ_PRIORITY 0
| Interrupt priority the ESB timer and the radio.
#define | NRF_ESB_LOW_IRQ_PRIORITY 1
| Interrupt priority for ESB callback functions.
#define | NRF_ESB_SWI_IRQn SWI0_IRQn
| Software interrupt # used for callback functions.
#define | NRF_ESB_SWI_IRQ_HANDLER SWI0_IRQHandler
| Software interrupt handler used for callback functions.
#define | NRF_ESB_TIMER NRF_TIMER2
| Timer to be used as flywheel timer.
#define | NRF_ESB_TIMER_PERPOWER_Msk POWER_PERPOWER_TIMER2_Msk
| PERPOWER mask for the timer.
#define | NRF_ESB_TIMER_IRQn TIMER2_IRQn
| Interrupt # for the timer.
#define | NRF_ESB_TIMER_IRQ_HANDLER TIMER2_IRQHandler
| Interrupt handler for the timer.
#define | NRF_ESB_PPI_EEP0 (NRF_PPI -> CH0_EEP)
| ESB PPI event endpoint 0.
#define | NRF_ESB_PPI_TEP0 (NRF_PPI -> CH0_TEP)
| ESB PPI task endpoint 0.
#define | NRF_ESB_PPI_EEP1 (NRF_PPI -> CH1_EEP)
| ESB PPI event endpoint 1.
#define | NRF_ESB_PPI_TEP1 (NRF_PPI -> CH1_TEP)
| ESB PPI task endpoint 1.
#define | NRF_ESB_PPI_EEP2 (NRF_PPI -> CH2_EEP)
| ESB PPI event endpoint 2.
#define | NRF_ESB_PPI_TEP2 (NRF_PPI -> CH2_TEP)
| ESB PPI task endpoint 2.
#define | NRF_ESB_PPI_CHEN_MSK_0_AND_1 (0x03)
| Channel enable/disable mask for PPI endpoint 0 and 1.
#define | NRF_ESB_PPI_CHEN_MSK_2 (0x04)
| Channel enable/disable mask for PPI endpoint 2.
#define | NRF_ESB_CONST_FIFO_LENGTH 3
| Maximum number of packets allowed in a TX or RX FIFO.

## Constant pipe and FIFO configuration

#define | NRF_ESB_CONST_PIPE_COUNT 8
| Number of TX pipes (at least one for each Device-Host pairs). More...
#define | NRF_ESB_CONST_PIPE_COUNT 8
| Number of TX pipes (at least one for each Device-Host pairs). More...
#define | NRF_ESB_CONST_MAX_TOTAL_PACKETS 6
| Maximum number of packets available for reservation at any one time.
#define | NRF_ESB_CONST_MAX_TOTAL_PACKETS 6
| Maximum number of packets available for reservation at any one time.
#define | NRF_ESB_CONST_MAX_PAYLOAD_LENGTH 32
| Maximum allowed payload length in bytes.
#define | NRF_ESB_CONST_MAX_PAYLOAD_LENGTH 32
| Maximum allowed payload length in bytes.
#define | NRF_ESB_CONST_CALLBACK_QUEUE_LENGTH 10
| Maximum number of notifications allowed in the callback queue.
#define | NRF_ESB_CONST_CALLBACK_QUEUE_LENGTH 10
| Maximum number of notifications allowed in the callback queue.
#define | NRF_ESB_CONST_QUEUE_LENGTH 3
| Maximum number of packets allowed in a TX or RX queue.

## Default parameters

#define | NRF_ESB_DEFAULT_BASE_ADDRESS_0 0xE7E7E7E7
| Default base address 0.
#define | NRF_ESB_DEFAULT_BASE_ADDRESS_1 0xC2C2C2C2
| Default base address 1.
#define | NRF_ESB_DEFAULT_PREFIX_BYTE_0 0xE7
| Default prefix address pipe 0.
#define | NRF_ESB_DEFAULT_PREFIX_BYTE_1 0xC2
| Default prefix address pipe 1.
#define | NRF_ESB_DEFAULT_PREFIX_BYTE_2 0xC3
| Default prefix address pipe 2.
#define | NRF_ESB_DEFAULT_PREFIX_BYTE_3 0xC4
| Default prefix address pipe 3.
#define | NRF_ESB_DEFAULT_PREFIX_BYTE_4 0xC5
| Default prefix address pipe 4.
#define | NRF_ESB_DEFAULT_PREFIX_BYTE_5 0xC6
| Default prefix address pipe 5.
#define | NRF_ESB_DEFAULT_PREFIX_BYTE_6 0xC7
| Default prefix address pipe 6.
#define | NRF_ESB_DEFAULT_PREFIX_BYTE_7 0xC8
| Default prefix address pipe 7.
#define | NRF_ESB_DEFAULT_BASE_ADDRESS_LENGTH NRF_ESB_BASE_ADDRESS_LENGTH_4B
| Default on-air base address length.
#define | NRF_ESB_DEFAULT_CRC_LENGTH NRF_ESB_CRC_LENGTH_1_BYTE
| Default CRC length.
#define | NRF_ESB_DEFAULT_ENABLED_PRX_PIPES 0xFF
| Default enabled RX pipes.
#define | NRF_ESB_DEFAULT_MAX_NUMBER_OF_RETRANSMITS 15
| Default number of retransmits.
#define | NRF_ESB_DEFAULT_OUTPUT_POWER NRF_ESB_OUTPUT_POWER_0_DBM
| Default TX output power.
#define | NRF_ESB_DEFAULT_DATARATE NRF_ESB_DATARATE_2_MBPS
| Default datarate.
#define | NRF_ESB_DEFAULT_RETRANSMIT_DELAY 600
| Default retransmit delay.
#define | NRF_ESB_DEFAULT_CHANNEL (10)
#define | NRF_ESB_DEFAULT_XOSC_CTL NRF_ESB_XOSC_CTL_AUTO
| Default setting for controlling the XOSC.

## Detailed Description

Enhanced ShockBurst Application Programming Interface (API).

## Macro Definition Documentation

#define NRF_ESB_CONST_PIPE_COUNT 8

Number of TX pipes (at least one for each Device-Host pairs).

Number of transmission pipes (at least one for each Device-Host pairs).

#define NRF_ESB_CONST_PIPE_COUNT 8

Number of TX pipes (at least one for each Device-Host pairs).

Number of transmission pipes (at least one for each Device-Host pairs).

## Enumeration Type Documentation

enum nrf_esb_base_address_length_t

Enumerator used for selecting the base address length.

Enumerator
NRF_ESB_BASE_ADDRESS_LENGTH_2B | 2 byte address length
NRF_ESB_BASE_ADDRESS_LENGTH_3B | 3 byte address length
NRF_ESB_BASE_ADDRESS_LENGTH_4B | 4 byte address length
NRF_ESB_BASE_ADDRESS_LENGTH_2B | 2 byte address length
NRF_ESB_BASE_ADDRESS_LENGTH_3B | 3 byte address length
NRF_ESB_BASE_ADDRESS_LENGTH_4B | 4 byte address length

enum nrf_esb_base_address_length_t

Enumerator
NRF_ESB_BASE_ADDRESS_LENGTH_2B | 2 byte address length
NRF_ESB_BASE_ADDRESS_LENGTH_3B | 3 byte address length
NRF_ESB_BASE_ADDRESS_LENGTH_4B | 4 byte address length
NRF_ESB_BASE_ADDRESS_LENGTH_2B | 2 byte address length
NRF_ESB_BASE_ADDRESS_LENGTH_3B | 3 byte address length
NRF_ESB_BASE_ADDRESS_LENGTH_4B | 4 byte address length

enum nrf_esb_crc_length_t

Enumerator used for selecting the CRC length.

Enumerator
NRF_ESB_CRC_OFF | CRC check disabled.
NRF_ESB_CRC_LENGTH_1_BYTE | CRC check set to 8-bit.
NRF_ESB_CRC_LENGTH_2_BYTE | CRC check set to 16-bit.
NRF_ESB_CRC_OFF | CRC check disabled.
NRF_ESB_CRC_LENGTH_1_BYTE | CRC check set to 8-bit.
NRF_ESB_CRC_LENGTH_2_BYTE | CRC check set to 16-bit.

enum nrf_esb_crc_length_t

Enumerator
NRF_ESB_CRC_OFF | CRC check disabled.
NRF_ESB_CRC_LENGTH_1_BYTE | CRC check set to 8-bit.
NRF_ESB_CRC_LENGTH_2_BYTE | CRC check set to 16-bit.
NRF_ESB_CRC_OFF | CRC check disabled.
NRF_ESB_CRC_LENGTH_1_BYTE | CRC check set to 8-bit.
NRF_ESB_CRC_LENGTH_2_BYTE | CRC check set to 16-bit.

enum nrf_esb_datarate_t

Enumerator used for selecting the radio data rate.

Enumerator
NRF_ESB_DATARATE_250_KBPS | 250 Kbps datarate
NRF_ESB_DATARATE_1_MBPS | 1 Mbps datarate
NRF_ESB_DATARATE_2_MBPS | 1 Mbps datarate
NRF_ESB_DATARATE_250_KBPS | 250 Kbps datarate
NRF_ESB_DATARATE_1_MBPS | 1 Mbps datarate
NRF_ESB_DATARATE_2_MBPS | 1 Mbps datarate

enum nrf_esb_datarate_t

Enumerator
NRF_ESB_DATARATE_250_KBPS | 250 Kbps datarate
NRF_ESB_DATARATE_1_MBPS | 1 Mbps datarate
NRF_ESB_DATARATE_2_MBPS | 1 Mbps datarate
NRF_ESB_DATARATE_250_KBPS | 250 Kbps datarate
NRF_ESB_DATARATE_1_MBPS | 1 Mbps datarate
NRF_ESB_DATARATE_2_MBPS | 1 Mbps datarate

enum nrf_esb_mode_t

Enumerator used for selecting the ESB mode.

Enumerator
NRF_ESB_MODE_PTX | Primary Transmitter mode.
NRF_ESB_MODE_PRX | Primary Receiver mode.
NRF_ESB_MODE_PTX | Primary Transmitter mode.
NRF_ESB_MODE_PRX | Primary Receiver mode.

enum nrf_esb_mode_t

Enumerator
NRF_ESB_MODE_PTX | Primary Transmitter mode.
NRF_ESB_MODE_PRX | Primary Receiver mode.
NRF_ESB_MODE_PTX | Primary Transmitter mode.
NRF_ESB_MODE_PRX | Primary Receiver mode.

enum nrf_esb_output_power_t

Enumerator used for selecting the TX output power.

Enumerator
NRF_ESB_OUTPUT_POWER_4_DBM | 4 dBm output power.
NRF_ESB_OUTPUT_POWER_0_DBM | 0 dBm output power.
NRF_ESB_OUTPUT_POWER_N4_DBM | -4 dBm output power.
NRF_ESB_OUTPUT_POWER_N8_DBM | -8 dBm output power.
NRF_ESB_OUTPUT_POWER_N12_DBM | -12 dBm output power.
NRF_ESB_OUTPUT_POWER_N16_DBM | -16 dBm output power.
NRF_ESB_OUTPUT_POWER_N20_DBM | -20 dBm output power.
NRF_ESB_OUTPUT_POWER_4_DBM | 4 dBm output power.
NRF_ESB_OUTPUT_POWER_0_DBM | 0 dBm output power.
NRF_ESB_OUTPUT_POWER_N4_DBM | -4 dBm output power.
NRF_ESB_OUTPUT_POWER_N8_DBM | -8 dBm output power.
NRF_ESB_OUTPUT_POWER_N12_DBM | -12 dBm output power.
NRF_ESB_OUTPUT_POWER_N16_DBM | -16 dBm output power.
NRF_ESB_OUTPUT_POWER_N20_DBM | -20 dBm output power.

enum nrf_esb_output_power_t

Enumerator
NRF_ESB_OUTPUT_POWER_4_DBM | 4 dBm output power.
NRF_ESB_OUTPUT_POWER_0_DBM | 0 dBm output power.
NRF_ESB_OUTPUT_POWER_N4_DBM | -4 dBm output power.
NRF_ESB_OUTPUT_POWER_N8_DBM | -8 dBm output power.
NRF_ESB_OUTPUT_POWER_N12_DBM | -12 dBm output power.
NRF_ESB_OUTPUT_POWER_N16_DBM | -16 dBm output power.
NRF_ESB_OUTPUT_POWER_N20_DBM | -20 dBm output power.
NRF_ESB_OUTPUT_POWER_4_DBM | 4 dBm output power.
NRF_ESB_OUTPUT_POWER_0_DBM | 0 dBm output power.
NRF_ESB_OUTPUT_POWER_N4_DBM | -4 dBm output power.
NRF_ESB_OUTPUT_POWER_N8_DBM | -8 dBm output power.
NRF_ESB_OUTPUT_POWER_N12_DBM | -12 dBm output power.
NRF_ESB_OUTPUT_POWER_N16_DBM | -16 dBm output power.
NRF_ESB_OUTPUT_POWER_N20_DBM | -20 dBm output power.

enum nrf_esb_packet_t

Enumerator used for selecting TX packet type used in PTX mode.

Enumerator
NRF_ESB_PACKET_USE_ACK | PTX packet requires ACK.
NRF_ESB_PACKET_NO_ACK | PTX packet does not require ACK.
NRF_ESB_PACKET_USE_ACK | PTX packet requires ACK.
NRF_ESB_PACKET_NO_ACK | PTX packet does not require ACK.

enum nrf_esb_packet_t

Enumerator
NRF_ESB_PACKET_USE_ACK | PTX packet requires ACK.
NRF_ESB_PACKET_NO_ACK | PTX packet does not require ACK.
NRF_ESB_PACKET_USE_ACK | PTX packet requires ACK.
NRF_ESB_PACKET_NO_ACK | PTX packet does not require ACK.

enum nrf_esb_xosc_ctl_t

Enumerator used for specifying whether switching the external 16 MHz oscillator on/off shall be handled automatically inside ESB or manually by the application.

Enumerator
NRF_ESB_XOSC_CTL_AUTO | Switch XOSC on/off automatically.
NRF_ESB_XOSC_CTL_MANUAL | Switch XOSC on/off manually.
NRF_ESB_XOSC_CTL_AUTO | Switch XOSC on/off automatically.
NRF_ESB_XOSC_CTL_MANUAL | Switch XOSC on/off manually.

enum nrf_esb_xosc_ctl_t

Enumerator
NRF_ESB_XOSC_CTL_AUTO | Switch XOSC on/off automatically.
NRF_ESB_XOSC_CTL_MANUAL | Switch XOSC on/off manually.
NRF_ESB_XOSC_CTL_AUTO | Switch XOSC on/off automatically.
NRF_ESB_XOSC_CTL_MANUAL | Switch XOSC on/off manually.

## Function Documentation

bool nrf_esb_add_packet_to_tx_fifo | ( | uint32_t | pipe,
|  | uint8_t * | payload,
|  | uint32_t | payload_length,
|  | nrf_esb_packet_t | packet_type
| ) |  |

Add a packet to the tail of the TX FIFO.

In PTX mode, the packet will be transmitted at the next occation when ESB is enabled. In PRX mode, the payload will be piggybacked to onto an ACK.

Parameters

  payload | Pointer to the payload.
  payload_length | The number of bytes of the payload to transmit.
  pipe | The pipe for which to add the payload. This value must be < NRF_ESB_CONST_PIPE_COUNT.
  packet_type | Specifies whether an ACK is required (ignored when in PRX mode, or when the dynamic ack feature is disabled).

See Also
  nrf_esb_enable_dyn_ack()

Return values

  true | If the packet was successfully added to the TX FIFO.
  false | If pipe was invalid, payload pointer was NULL, payload length was invalid, insufficient space in FIFO memory pool or insufficient packets in TX queue.

void nrf_esb_disable | ( | void |  | ) |

Disable ESB.

Equivalent to setting CE low in legacy ESB.

When calling this function ESB will begin disabling, and will be fully disabled when ESB calls nrf_esb_disabled(). If there are any pending notifications (callbacks) , or if any new notifications are being added to the internal notification queue while ESB is disabling, these will be sent to the application before ESB is fully disabled.

After ESB has been fully disabled, no more notifications will be sent to the application.

void nrf_esb_disable_dyn_ack | ( | void |  | ) |

Disable dynamic ACK feature.

See Also
  nrf_esb_enable_dyn_ack()

void nrf_esb_disabled | ( | void |  | ) |

Disabled callback.

This is called after ESB enters the disabled state. There is no further CPU use by ESB, the radio is disabled and the timer is powered down.

void nrf_esb_enable | ( | void |  | ) |

Enable ESB.

Equivalent to setting CE high in legacy ESB.

When enabled the behaviour described for the current ESB mode will apply.

void nrf_esb_enable_dyn_ack | ( | void |  | ) |

Enable dynamic ACK feature. After initialization this feature is disabled.

The dynamic ACK feature must be enabled in order for the packet_type parameter in the nrf_esb_add_packet_to_tx_fifo() function to have any effect, or for the ACK bit of received packets to be evaluated.

When the dynamic ACK feature is disabled, all packets will be ACK'ed.

bool nrf_esb_fetch_packet_from_rx_fifo | ( | uint32_t | pipe,
|  | uint8_t * | payload,
|  | uint32_t * | payload_length
| ) |  |

Fetch a packet from the head of the RX FIFO.

Parameters

  payload | Pointer to copy the payload to.
  payload_length | Pointer to copy the payload length to. The payload length is given in bytes (0 to NRF_ESB_CONST_MAX_PAYLOAD_LENGTH).
  pipe | Pipe for which to add the payload. This value must be < NRF_ESB_CONST_PIPE_COUNT.

Return values

  true | If the fetch was successful.
  false | If there was no packet in the FIFO or the payload pointer was NULL.

void nrf_esb_flush_rx_fifo | ( | uint32_t | pipe | ) |

Flush the RX FIFO for a specific pipe.

Delete all the packets and free the memory of the RX FIFO for a specific pipe.

Parameters

  pipe | The pipe for which to flush. This value must be < NRF_ESB_CONST_PIPE_COUNT.

void nrf_esb_flush_tx_fifo | ( | uint32_t | pipe | ) |

Flush the RX FIFO for a specific pipe.

Delete all the packets and free the memory of the TX FIFO for a specific pipe.

Note that it is not allowed to flush a TX FIFO when ESB is enabled.

Parameters

  pipe | The pipe for which to flush. This value must be < NRF_ESB_CONST_PIPE_COUNT.

bool nrf_esb_get_address_prefix_byte | ( | uint32_t | pipe,
|  | uint8_t * | out_address
| ) |  |

Get function counterpart to nrf_esb_set_address_prefix_byte().

Parameters

  pipe | the pipe for which to get the address. This value must be < NRF_ESB_CONST_PIPE_COUNT.
  out_address | is the pointer in which to return the address byte.

Return values

  true | If the value was set.
  false | If ESB was enabled, or the pipe was invalid, or the out_address pointer was NULL.

uint32_t nrf_esb_get_base_address_0 | ( | void |  | ) |

Get function counterpart to nrf_esb_set_base_address_0().

Returns
  Base address 0.

uint32_t nrf_esb_get_base_address_1 | ( | void |  | ) |

Get function counterpart to nrf_esb_set_base_address_1().

Returns
  Base address 1.

nrf_esb_base_address_length_t nrf_esb_get_base_address_length | ( | void |  | ) |

Get function counterpart to nrf_esb_set_base_address_length().

Returns
  The current base_address length.

uint32_t nrf_esb_get_channel | ( | void |  | ) |

Get function counterpart to nrf_esb_set_channel().

Returns
  The current RF channel.

nrf_esb_crc_length_t nrf_esb_get_crc_length | ( | void |  | ) |

Get function counterpart to nrf_esb_set_crc_length().

Returns
  The current CRC length.

nrf_esb_datarate_t nrf_esb_get_datarate | ( | void |  | ) |

Get function counterpart to nrf_esb_set_datarate().

Returns
  The current datarate.

uint32_t nrf_esb_get_enabled_prx_pipes | ( | void |  | ) |

Get function counterpart to nrf_esb_set_enabled_prx_pipes().

Returns
  Bitmap holding the current enabled pipes.

uint16_t nrf_esb_get_max_number_of_tx_attempts | ( | void |  | ) |

Get function counterpart to nrf_esb_set_max_number_of_retransmits().

Returns
  The current number of maximum retransmission attempts.

nrf_esb_mode_t nrf_esb_get_mode | ( | void |  | ) |

Get function counterpart to nrf_esb_set_mode().

Returns
  The current ESB mode.

nrf_esb_output_power_t nrf_esb_get_output_power | ( | void |  | ) |

Get function counterpart to nrf_esb_set_output_power().

Returns
  The output power.

uint32_t nrf_esb_get_retransmit_delay | ( | void |  | ) |

Get function counterpart to nrf_esb_set_retransmit_delay().

Returns
  The current retransmission delay.

uint32_t nrf_esb_get_rx_fifo_packet_count | ( | uint32_t | pipe | ) |

Get the number of packets residing in the RX FIFO on a specific pipe.

Parameters

  pipe | The pipe for which to check. This value must be < NRF_ESB_CONST_PIPE_COUNT.

Return values

  The | number of packets in the RX FIFO for the pipe.

uint16_t nrf_esb_get_tx_attempts | ( | void |  | ) |

Get the total number of transmission attempts used for sending the previous successful packet.

The value applies to the packet for which the latest nrf_esb_tx_data_sent callback was made.

Returns
  The number of transmission attempts for the previous transmitted packet.

uint32_t nrf_esb_get_tx_fifo_packet_count | ( | uint32_t | pipe | ) |

Get the number of packets residing in the TX FIFO on a specific pipe.

Parameters

  pipe | The pipe for which to check. This value must be < NRF_ESB_CONST_PIPE_COUNT.

Return values

  The | number of packets in the TX FIFO for the pipe.

nrf_esb_xosc_ctl_t nrf_esb_get_xosc_ctl | ( | void |  | ) |

Get function counterpart for nrf_esb_set_xosc_ctl();

Returns
  The XOSC control setting.

bool nrf_esb_init | ( | nrf_esb_mode_t | mode | ) |

Initialize ESB.

Parameters

  mode | The mode to initialize ESB in.

Return values

  true | If ESB initialized.
  false | If ESB failed to initialize.

bool nrf_esb_is_enabled | ( | void |  | ) |

Check whether ESB is enabled or disabled.

Return values

  true | If ESB is enabled.
  false | If ESB is disabled.

void nrf_esb_rx_data_ready | ( | uint32_t | rx_pipe,
|  | int32_t | rssi
| ) |  |

RX data ready callback.

PTX mode: This is called after an ACK is received from a PRX containing a payload.

PRX mode: This is called after a packet is received from a PTX ACK is received from a PRX containing a payload.

Parameters

  rx_pipe | is the pipe on which a packet was received. This value must be < NRF_ESB_CONST_PIPE_COUNT.
  rssi | Received signal strength indicator in dBm of packet.

As the RSSI measurement requires a minimum on-air duration of the received packet, the measured RSSI value will not be reliable when ALL of the following criteria are met:

- Datarate = 2 Mbps
- Payload length = 0
- CRC is off

bool nrf_esb_set_address_prefix_byte | ( | uint32_t | pipe,
|  | uint8_t | address
| ) |  |

Set the address prefix byte for a specific pipe.

Each pipe should have its own unique prefix byte.

Parameters

  pipe | The pipe that the address should apply to. This value must be < NRF_ESB_CONST_PIPE_COUNT.
  address | The address prefix byte.

Return values

  true | If the address prefix byte was set.
  false | If ESB was enabled or if the pipe was invalid.

bool nrf_esb_set_base_address_0 | ( | uint32_t | base_address | ) |

Set the base address for pipe 0.

The full on-air address for each pipe is composed of a multi-byte base address and a prefix address byte.

For packets to be received correctly, the most significant byte of the base address should not be an alternating sequence of 0s and 1s i.e. it should not be 0x55 or 0xAA.

Parameters

  base_address | is the 4 byte base address. The parameter is 4 bytes, however only the least L significant bytes are used, where L is set by nrf_esb_set_base_address_length().

Return values

  true | if base_address_0 was set.
  false | if ESB was enabled.

bool nrf_esb_set_base_address_1 | ( | uint32_t | base_address | ) |

Set the base address for pipes 1-7.

Pipes 1 through 7 share base_address_1.

See Also
  nrf_esb_set_base_address_0.

Parameters

  base_address | is the 4 byte base address. The parameter is 4 bytes, however only the least L significant bytes are used, where L is set by nrf_esb_set_base_address_length().

Return values

  true | If base_address_1 was set.
  false | If ESB was enabled.

bool nrf_esb_set_base_address_length | ( | nrf_esb_base_address_length_t | length | ) |

Set the base address length.

Parameters

  length | The base address length.

Return values

  true | If the address length was set.
  false | If the length was invalid.

bool nrf_esb_set_channel | ( | uint32_t | channel | ) |

Set the Radio Frequency (RF) channel.

The valid channels are in the range 0 <= channel <= 125, where the actual centre frequency is (2400 + channel) MHz.

Parameters

  channel | The RF Channel to use.

Returns
  false If ESB was enabled.

bool nrf_esb_set_crc_length | ( | nrf_esb_crc_length_t | length | ) |

Set the CRC length.

The CRC length should be the same on both PTX and PRX in order to ensure correct operation.

Parameters

  length | The CRC length.

Return values

  false | If ESB was enabled or the length was invalid.

bool nrf_esb_set_datarate | ( | nrf_esb_datarate_t | datarate | ) |

Set the radio datarate.

Parameters

  datarate | Datarate.

Return values

  false | If the datarate was invalid.

bool nrf_esb_set_enabled_prx_pipes | ( | uint32_t | pipes | ) |

Set which pipes the node shall listen on in PRX mode.

This value is a bitmap, and each bit corresponds to a given pipe number. Bit 0 set to "1" enables pipes 0, bit 1 set to "1" enables pipe 1 and so forth. The maximum number of pipes is defined by NRF_CONST_ESB_PIPE_COUNT.

Parameters

  pipes | A bitmap specifying which pipes to monitor.

Return values

  true | If the bitmap was set.
  false | If ESB was enabled.

bool nrf_esb_set_max_number_of_tx_attempts | ( | uint16_t | attempts | ) |

Set the maximum number of TX attempts that can be used for a single packet.

Parameters

  attempts | The maximum number of TX attempts. 0 indicates that a packet can use a infinite number of attempts.

Return values

  false | If ESB was enabled.

bool nrf_esb_set_mode | ( | nrf_esb_mode_t | mode | ) |

Set the mode.

Parameters

  mode | The mode to be used. See nrf_esb_mode_t for a list of valid modes.

Return values

  true | if the mode was set properly.
  false | if the mode is invalid.

bool nrf_esb_set_output_power | ( | nrf_esb_output_power_t | power | ) |

Set the radio TX output power.

Parameters

  power | The output power.

Returns
  false If the output_power was invalid.

bool nrf_esb_set_retransmit_delay | ( | uint32_t | delay_us | ) |

Set the retransmission delay.

The retransmission delay is the delay from the start of a packet that failed to receive the ACK until the start of the retransmission attempt.

The minimum value of the retransmission delay is dependent of the radio data rate and the payload size(s).(

See Also
  nrf_esb_set_datarate()). As a rule of thumb, when using 32 byte payloads in each direction (forward and ACK):

- For NRF_ESB_DATARATE_2_MBPS the retransmission delay must be >= 600 us.
- For NRF_ESB_DATARATE_1_MBPS the retransmission delay must >= 900 us.
- For NRF_ESB_DATARATE_250_KBPS the retransmission delay must be >= 2700 us.

Parameters

  delay_us | The delay in microseconds between each retransmission attempt.

Return values

  true | If the retransmit delay was set.
  false | If ESB was enabled.

bool nrf_esb_set_xosc_ctl | ( | nrf_esb_xosc_ctl_t | xosc_ctl | ) |

Set whether start/stop of external oscillator (XOSC) shall be handled automatically inside ESB or manually by the application.

When controlling the XOSC manually from the application it is required that the XOSC is started before ESB is enabled.

When start/stop of the XOSC is handled automatically by ESB, the XOSC will only be running when needed, that is when the radio is being used or when ESB needs to maintain synchronization.

It is required that the XOSC is started in order for the radio to be able to send or receive any packets.

Parameters

  xosc_ctl | setting for XOSC control.

Return values

  true | if the parameter was set.
  false | if Gazell was enabled or the xosc_ctl value was invalid.

void nrf_esb_tx_failed | ( | uint32_t | tx_pipe | ) |

TX failed callback (PTX mode only).

This is called after the maximum number of TX attempts were reached for a packet. The packet is deleted from the TX FIFO.

Note that when NRF_ESB_PACKET_NO_ACK is used this callback is always made after sending a packet.

See Also
  nrf_esb_set_max_number_of_tx_attempts().

Parameters

  tx_pipe | The pipe that failed to send a packet.

void nrf_esb_tx_success | ( | uint32_t | tx_pipe,
|  | int32_t | rssi
| ) |  |

TX success callback.

In PTX mode this function is called after the PTX has sent a packet and received the corresponding ACK packet from a PRX.

In PRX mode this function is called after a payload in ACK is assumed successfully transmitted, that is when the PRX received a new packet (new PID or CRC) and the previous ACK sent to a PTX contained a payload.

Parameters

  tx_pipe | The pipe on which the ACK packet was received.
  rssi | Received signal strength indicator in dBm of measured ACK.

As the RSSI measurement requires a minimum on-air duration of the received packet, the measured RSSI value will not be reliable when ALL of the following criteria are met:

- Datarate = 2 Mbps
- Payload length = 0
- CRC is off