| nRF5 SDK v12.0.0 |

Choose documentation: | nRF5 SDK | S130 SoftDevice API | S132 SoftDevice API | S212 SoftDevice API | S332 SoftDevice API

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

Enhanced ShockBurst (ESB) is a basic protocol that supports two-way data packet communication including packet buffering, packet acknowledgment, and automatic retransmission of lost packets. More...

## Modules
| ESB resources

## Data Structures
struct | nrf_esb_payload_t
| Enhanced ShockBurst payload. More...
struct | nrf_esb_evt_t
| Enhanced ShockBurst event. More...
struct | nrf_esb_config_t
| Main configuration structure for the module. More...

## Macros
#define | DEBUGPIN1 12
#define | DEBUGPIN2 13
#define | DEBUGPIN3 14
#define | DEBUGPIN4 15
#define | DEBUG_PIN_SET(a)
#define | DEBUG_PIN_CLR(a)
#define | NRF_ESB_MAX_PAYLOAD_LENGTH 32
#define | NRF_ESB_TX_FIFO_SIZE 8
#define | NRF_ESB_RX_FIFO_SIZE 8
#define | NRF_ESB_SYS_TIMER NRF_TIMER2
#define | NRF_ESB_SYS_TIMER_IRQ_Handler TIMER2_IRQHandler
#define | NRF_ESB_PPI_TIMER_START 10
#define | NRF_ESB_PPI_TIMER_STOP 11
#define | NRF_ESB_PPI_RX_TIMEOUT 12
#define | NRF_ESB_PPI_TX_START 13
#define | NRF_ESB_INT_TX_SUCCESS_MSK 0x01
#define | NRF_ESB_INT_TX_FAILED_MSK 0x02
#define | NRF_ESB_INT_RX_DR_MSK 0x04
#define | NRF_ESB_PID_RESET_VALUE 0xFF
#define | NRF_ESB_PID_MAX 3
#define | NRF_ESB_CRC_RESET_VALUE 0xFFFF
#define | ESB_EVT_IRQ SWI0_IRQn
#define | ESB_EVT_IRQHandler SWI0_IRQHandler
#define | NRF_ESB_ADDR_DEFAULT
#define | NRF_ESB_DEFAULT_CONFIG
#define | NRF_ESB_LEGACY_CONFIG
#define | NRF_ESB_CREATE_PAYLOAD(_pipe,...)

## Typedefs
typedef void(* | nrf_esb_event_handler_t )(nrf_esb_evt_t const *p_event)
| Definition of the event handler for the module.

## Enumerations
enum | nrf_esb_protocol_t { NRF_ESB_PROTOCOL_ESB, NRF_ESB_PROTOCOL_ESB_DPL }
| Enhanced ShockBurst protocols.
enum | nrf_esb_mode_t { NRF_ESB_MODE_PTX, NRF_ESB_MODE_PRX }
| Enhanced ShockBurst modes.
enum | nrf_esb_bitrate_t { NRF_ESB_BITRATE_2MBPS = RADIO_MODE_MODE_Nrf_2Mbit, NRF_ESB_BITRATE_1MBPS = RADIO_MODE_MODE_Nrf_1Mbit, NRF_ESB_BITRATE_250KBPS = RADIO_MODE_MODE_Nrf_250Kbit, NRF_ESB_BITRATE_1MBPS_BLE = RADIO_MODE_MODE_Ble_1Mbit }
| Enhanced ShockBurst bitrate modes. More...
enum | nrf_esb_crc_t { NRF_ESB_CRC_16BIT = RADIO_CRCCNF_LEN_Two, NRF_ESB_CRC_8BIT = RADIO_CRCCNF_LEN_One, NRF_ESB_CRC_OFF = RADIO_CRCCNF_LEN_Disabled }
| Enhanced ShockBurst CRC modes. More...
enum | nrf_esb_tx_power_t { NRF_ESB_TX_POWER_4DBM = RADIO_TXPOWER_TXPOWER_Pos4dBm, NRF_ESB_TX_POWER_0DBM = RADIO_TXPOWER_TXPOWER_0dBm, NRF_ESB_TX_POWER_NEG4DBM = RADIO_TXPOWER_TXPOWER_Neg4dBm, NRF_ESB_TX_POWER_NEG8DBM = RADIO_TXPOWER_TXPOWER_Neg8dBm, NRF_ESB_TX_POWER_NEG12DBM = RADIO_TXPOWER_TXPOWER_Neg12dBm, NRF_ESB_TX_POWER_NEG16DBM = RADIO_TXPOWER_TXPOWER_Neg16dBm, NRF_ESB_TX_POWER_NEG20DBM = RADIO_TXPOWER_TXPOWER_Neg20dBm, NRF_ESB_TX_POWER_NEG30DBM = RADIO_TXPOWER_TXPOWER_Neg30dBm }
| Enhanced ShockBurst radio transmission power modes. More...
enum | nrf_esb_tx_mode_t { NRF_ESB_TXMODE_AUTO, NRF_ESB_TXMODE_MANUAL, NRF_ESB_TXMODE_MANUAL_START }
| Enhanced ShockBurst transmission modes.
enum | nrf_esb_evt_id_t { NRF_ESB_EVENT_TX_SUCCESS, NRF_ESB_EVENT_TX_FAILED, NRF_ESB_EVENT_RX_RECEIVED }
| Enhanced ShockBurst event IDs used to indicate the type of the event. More...

## Functions
| STATIC_ASSERT (32<=252)
uint32_t | nrf_esb_init (nrf_esb_config_t const *p_config)
| Function for initializing the Enhanced ShockBurst module. More...
uint32_t | nrf_esb_suspend (void)
| Function for suspending the Enhanced ShockBurst module. More...
uint32_t | nrf_esb_disable (void)
| Function for disabling the Enhanced ShockBurst module. More...
bool | nrf_esb_is_idle (void)
| Function for checking if the Enhanced ShockBurst module is idle. More...
uint32_t | nrf_esb_write_payload (nrf_esb_payload_t const *p_payload)
| Function for writing a payload for transmission or acknowledgment. More...
uint32_t | nrf_esb_read_rx_payload (nrf_esb_payload_t *p_payload)
| Function for reading an RX payload. More...
uint32_t | nrf_esb_start_tx (void)
| Function for starting transmission. More...
uint32_t | nrf_esb_start_rx (void)
| Function for starting to transmit data from the FIFO buffer. More...
uint32_t | nrf_esb_stop_rx (void)
| Function for stopping data reception. More...
uint32_t | nrf_esb_flush_tx (void)
| Function for removing remaining items from the TX buffer. More...
uint32_t | nrf_esb_pop_tx (void)
| Function for removing the first item from the TX buffer. More...
uint32_t | nrf_esb_flush_rx (void)
| Function for removing remaining items from the RX buffer. More...
uint32_t | nrf_esb_set_address_length (uint8_t length)
| Function for setting the length of the address. More...
uint32_t | nrf_esb_set_base_address_0 (uint8_t const *p_addr)
| Function for setting the base address for pipe 0. More...
uint32_t | nrf_esb_set_base_address_1 (uint8_t const *p_addr)
| Function for setting the base address for pipe 1 to pipe 7. More...
uint32_t | nrf_esb_set_prefixes (uint8_t const *p_prefixes, uint8_t num_pipes)
| Function for setting the number of pipes and the pipe prefix addresses. More...
uint32_t | nrf_esb_enable_pipes (uint8_t enable_mask)
| Function for enabling pipes. More...
uint32_t | nrf_esb_update_prefix (uint8_t pipe, uint8_t prefix)
| Function for updating the prefix for a pipe. More...
uint32_t | nrf_esb_set_rf_channel (uint32_t channel)
| Function for setting the channel to use for the radio. More...
uint32_t | nrf_esb_rf_channel_get (uint32_t *p_channel)
| Function for getting the current radio channel. More...
uint32_t | nrf_esb_set_tx_power (nrf_esb_tx_power_t tx_output_power)
| Function for setting the radio output power. More...

## Detailed Description

Enhanced ShockBurst (ESB) is a basic protocol that supports two-way data packet communication including packet buffering, packet acknowledgment, and automatic retransmission of lost packets.

## Macro Definition Documentation

#define ESB_EVT_IRQ SWI0_IRQn

The ESB event IRQ number when running on an nRF5x device.

#define ESB_EVT_IRQHandler SWI0_IRQHandler

The handler for ESB_EVT_IRQ when running on an nRF5x device.

#define NRF_ESB_ADDR_DEFAULT

Value:
{ \
.base_addr_p0 = { 0xE7, 0xE7, 0xE7, 0xE7 }, \
.base_addr_p1 = { 0xC2, 0xC2, 0xC2, 0xC2 }, \
.pipe_prefixes = { 0xE7, 0xC2, 0xC3, 0xC4, 0xC5, 0xC6, 0xC7, 0xC8 }, \
.addr_length = 5, \
.num_pipes = 8, \
.rf_channel = 2, \
.rx_pipes_enabled = 0xFF \
}

Default address configuration for ESB. Roughly equal to the nRF24Lxx default (except for the number of pipes, because more pipes are supported).

#define NRF_ESB_CRC_RESET_VALUE 0xFFFF

The CRC reset value.

#define NRF_ESB_CREATE_PAYLOAD | ( |  | _pipe,
|  |  | ...
| ) |  |

Value:
{.pipe = _pipe, .length = NUM_VA_ARGS(__VA_ARGS__), .data = {__VA_ARGS__}}; \
STATIC_ASSERT(NUM_VA_ARGS(__VA_ARGS__) > 0 && NUM_VA_ARGS(__VA_ARGS__) <= 63)

Macro to create an initializer for a TX data packet.

This macro generates an initializer. Using the initializer is more efficient than setting the individual parameters dynamically.

Parameters

  [in] | _pipe | The pipe to use for the data packet.
  [in] | ... | Comma separated list of character data to put in the TX buffer. Supported values consist of 1 to 63 characters.

Returns
  Initializer that sets up the pipe, length, and byte array for content of the TX data.

#define NRF_ESB_DEFAULT_CONFIG

Value:
{.protocol = NRF_ESB_PROTOCOL_ESB_DPL, \
.mode = NRF_ESB_MODE_PTX, \
.event_handler = 0, \
.bitrate = NRF_ESB_BITRATE_2MBPS, \
.crc = NRF_ESB_CRC_16BIT, \
.tx_output_power = NRF_ESB_TX_POWER_0DBM, \
.retransmit_delay = 250, \
.retransmit_count = 3, \
.tx_mode = NRF_ESB_TXMODE_AUTO, \
.radio_irq_priority = 1, \
.event_irq_priority = 2, \
.payload_length = 32, \
.selective_auto_ack = false \
}

Default radio parameters. Roughly equal to the nRF24Lxx default parameters (except for CRC, which is set to 16 bit, and protocol, which is set to DPL).

#define NRF_ESB_INT_RX_DR_MSK 0x04

The flag used to indicate that a packet was received since the last event.

#define NRF_ESB_INT_TX_FAILED_MSK 0x02

The flag used to indicate a failure since the last event.

#define NRF_ESB_INT_TX_SUCCESS_MSK 0x01

The flag used to indicate a success since the last event.

#define NRF_ESB_LEGACY_CONFIG

Value:
{.protocol = NRF_ESB_PROTOCOL_ESB, \
.mode = NRF_ESB_MODE_PTX, \
.event_handler = 0, \
.bitrate = NRF_ESB_BITRATE_2MBPS, \
.crc = NRF_ESB_CRC_8BIT, \
.tx_output_power = NRF_ESB_TX_POWER_0DBM, \
.retransmit_delay = 600, \
.retransmit_count = 3, \
.tx_mode = NRF_ESB_TXMODE_AUTO, \
.radio_irq_priority = 1, \
.event_irq_priority = 2, \
.payload_length = 32, \
.selective_auto_ack = false \
}

Default legacy radio parameters, identical to the nRF24Lxx defaults.

#define NRF_ESB_MAX_PAYLOAD_LENGTH 32

The maximum size of the payload. Valid values are 1 to 252.

#define NRF_ESB_PID_MAX 3

The maximum value for PID.

#define NRF_ESB_PID_RESET_VALUE 0xFF

Invalid PID value that is guaranteed to not collide with any valid PID value.

#define NRF_ESB_PPI_RX_TIMEOUT 12

The PPI channel used for RX time-out.

#define NRF_ESB_PPI_TIMER_START 10

The PPI channel used for timer start.

#define NRF_ESB_PPI_TIMER_STOP 11

The PPI channel used for timer stop.

#define NRF_ESB_PPI_TX_START 13

The PPI channel used for starting TX.

#define NRF_ESB_RX_FIFO_SIZE 8

The size of the reception first-in, first-out buffer.

#define NRF_ESB_SYS_TIMER NRF_TIMER2

The timer that is used by the module.

#define NRF_ESB_SYS_TIMER_IRQ_Handler TIMER2_IRQHandler

The handler that is used by NRF_ESB_SYS_TIMER.

#define NRF_ESB_TX_FIFO_SIZE 8

The size of the transmission first-in, first-out buffer.

## Enumeration Type Documentation

enum nrf_esb_bitrate_t

Enhanced ShockBurst bitrate modes.

Enumerator
NRF_ESB_BITRATE_2MBPS | 2 Mb radio mode.
NRF_ESB_BITRATE_1MBPS | 1 Mb radio mode.
NRF_ESB_BITRATE_250KBPS | 250 Kb radio mode.
NRF_ESB_BITRATE_1MBPS_BLE | 1 Mb radio mode using Bluetooth low energy radio parameters.

enum nrf_esb_crc_t

Enhanced ShockBurst CRC modes.

Enumerator
NRF_ESB_CRC_16BIT | Use two-byte CRC.
NRF_ESB_CRC_8BIT | Use one-byte CRC.
NRF_ESB_CRC_OFF | Disable CRC.

enum nrf_esb_evt_id_t

Enhanced ShockBurst event IDs used to indicate the type of the event.

Enumerator
NRF_ESB_EVENT_TX_SUCCESS | Event triggered on TX success.
NRF_ESB_EVENT_TX_FAILED | Event triggered on TX failure.
NRF_ESB_EVENT_RX_RECEIVED | Event triggered on RX received.

enum nrf_esb_tx_power_t

Enhanced ShockBurst radio transmission power modes.

Enumerator
NRF_ESB_TX_POWER_4DBM | 4 dBm radio transmit power.
NRF_ESB_TX_POWER_0DBM | 0 dBm radio transmit power.
NRF_ESB_TX_POWER_NEG4DBM | -4 dBm radio transmit power.
NRF_ESB_TX_POWER_NEG8DBM | -8 dBm radio transmit power.
NRF_ESB_TX_POWER_NEG12DBM | -12 dBm radio transmit power.
NRF_ESB_TX_POWER_NEG16DBM | -16 dBm radio transmit power.
NRF_ESB_TX_POWER_NEG20DBM | -20 dBm radio transmit power.
NRF_ESB_TX_POWER_NEG30DBM | -30 dBm radio transmit power.

## Function Documentation

uint32_t nrf_esb_disable | ( | void |  | ) |

Function for disabling the Enhanced ShockBurst module.

Calling this function disables the Enhanced ShockBurst module immediately. Doing so might stop ongoing communications.

Note
  All queues are flushed by this function.

Return values

  NRF_SUCCESS | If Enhanced ShockBurst was disabled.

uint32_t nrf_esb_enable_pipes | ( | uint8_t | enable_mask | ) |

Function for enabling pipes.

The `enable_mask` parameter must contain the same number of pipes as has been configured with nrf_esb_set_prefixes.

Parameters

  enable_mask | Bitfield mask to enable or disable pipes. Setting a bit to 0 disables the pipe. Setting a bit to 1 enables the pipe.

Return values

  NRF_SUCCESS | If the pipes were enabled and disabled successfully.
  NRF_ERROR_BUSY | If the function failed because the radio is busy.

uint32_t nrf_esb_flush_rx | ( | void |  | ) |

Function for removing remaining items from the RX buffer.

Return values

  NRF_SUCCESS | If the pending items in the RX buffer were successfully cleared.
  NRF_INVALID_STATE | If the module is not initialized.

uint32_t nrf_esb_flush_tx | ( | void |  | ) |

Function for removing remaining items from the TX buffer.

This function clears the TX FIFO buffer.

Return values

  NRF_SUCCESS | If pending items in the TX buffer were successfully cleared.
  NRF_INVALID_STATE | If the module is not initialized.

uint32_t nrf_esb_init | ( | nrf_esb_config_t const * | p_config | ) |

Function for initializing the Enhanced ShockBurst module.

Parameters

  p_config | Parameters for initializing the module.

Return values

  NRF_SUCCESS | If initialization was successful.
  NRF_ERROR_NULL | If the `p_config` argument was NULL.
  NRF_ERROR_BUSY | If the function failed because the radio is busy.

bool nrf_esb_is_idle | ( | void |  | ) |

Function for checking if the Enhanced ShockBurst module is idle.

Return values

  true | If the module is idle.
  false | If the module is busy.

uint32_t nrf_esb_pop_tx | ( | void |  | ) |

Function for removing the first item from the TX buffer.

Return values

  NRF_SUCCESS | If the operation completed successfully.
  NRF_INVALID_STATE | If the module is not initialized.
  NRF_ERROR_BUFFER_EMPTY | If there are no items in the queue to remove.

uint32_t nrf_esb_read_rx_payload | ( | nrf_esb_payload_t * | p_payload | ) |

Function for reading an RX payload.

Parameters

  [in,out] | p_payload | Pointer to the structure that contains information and state of the payload.

Return values

  NRF_SUCCESS | If the data was read successfully.
  NRF_ERROR_NULL | If the required parameter was NULL.
  NRF_INVALID_STATE | If the module is not initialized.

uint32_t nrf_esb_rf_channel_get | ( | uint32_t * | p_channel | ) |

Function for getting the current radio channel.

Parameters

  [in,out] | p_channel | Pointer to the channel data.

Return values

  NRF_SUCCESS | If the operation completed successfully.
  NRF_ERROR_NULL | If the required parameter was NULL.

uint32_t nrf_esb_set_address_length | ( | uint8_t | length | ) |

Function for setting the length of the address.

Parameters

  [in] | length | Length of the ESB address (in bytes).

Return values

  NRF_SUCCESS | If the address length was set successfully.
  NRF_ERROR_INVALID_PARAM | If the address length was invalid.
  NRF_ERROR_BUSY | If the function failed because the radio is busy.

uint32_t nrf_esb_set_base_address_0 | ( | uint8_t const * | p_addr | ) |

Function for setting the base address for pipe 0.

Parameters

  [in] | p_addr | Pointer to the address data.

Return values

  NRF_SUCCESS | If the base address was set successfully.
  NRF_ERROR_BUSY | If the function failed because the radio is busy.
  NRF_ERROR_NULL | If the required parameter was NULL.

uint32_t nrf_esb_set_base_address_1 | ( | uint8_t const * | p_addr | ) |

Function for setting the base address for pipe 1 to pipe 7.

Parameters

  [in] | p_addr | Pointer to the address data.

Return values

  NRF_SUCCESS | If the base address was set successfully.
  NRF_ERROR_BUSY | If the function failed because the radio is busy.
  NRF_ERROR_NULL | If the required parameter was NULL.

uint32_t nrf_esb_set_prefixes | ( | uint8_t const * | p_prefixes,
|  | uint8_t | num_pipes
| ) |  |

Function for setting the number of pipes and the pipe prefix addresses.

This function configures the number of available pipes, enables the pipes, and sets their prefix addresses.

Parameters

  [in] | p_prefixes | Pointer to a char array that contains the prefix for each pipe.
  [in] | num_pipes | Number of pipes.

Return values

  NRF_SUCCESS | If the prefix addresses were set successfully.
  NRF_ERROR_BUSY | If the function failed because the radio is busy.
  NRF_ERROR_NULL | If a required parameter was NULL.
  NRF_ERROR_INVALID_PARAM | If an invalid number of pipes was given.

uint32_t nrf_esb_set_rf_channel | ( | uint32_t | channel | ) |

Function for setting the channel to use for the radio.

The module must be in an idle state to call this function. As a PTX, the application must wait for an idle state and as a PRX, the application must stop RX before changing the channel. After changing the channel, operation can be resumed.

Parameters

  [in] | channel | Channel to use for radio.

Return values

  NRF_SUCCESS | If the operation completed successfully.
  NRF_INVALID_STATE | If the module is not initialized.
  NRF_ERROR_BUSY | If the module was not in idle state.
  NRF_ERROR_INVALID_PARAM | If the channel is invalid (larger than 125).

uint32_t nrf_esb_set_tx_power | ( | nrf_esb_tx_power_t | tx_output_power | ) |

Function for setting the radio output power.

Parameters

  [in] | tx_output_power | Output power.

Return values

  NRF_SUCCESS | If the operation completed successfully.
  NRF_ERROR_BUSY | If the function failed because the radio is busy.

uint32_t nrf_esb_start_rx | ( | void |  | ) |

Function for starting to transmit data from the FIFO buffer.

Return values

  NRF_SUCCESS | If the transmission was started successfully.
  NRF_ERROR_BUSY | If the function failed because the radio is busy.

uint32_t nrf_esb_start_tx | ( | void |  | ) |

Function for starting transmission.

Return values

  NRF_SUCCESS | If the TX started successfully.
  NRF_ERROR_BUFFER_EMPTY | If the TX does not start because the FIFO buffer is empty.
  NRF_ERROR_BUSY | If the function failed because the radio is busy.

uint32_t nrf_esb_stop_rx | ( | void |  | ) |

Function for stopping data reception.

Return values

  NRF_SUCCESS | If data reception was stopped successfully.
  NRF_ESB_ERROR_NOT_IN_RX_MODE | If the function failed because the module is not in RX mode.

uint32_t nrf_esb_suspend | ( | void |  | ) |

Function for suspending the Enhanced ShockBurst module.

Calling this function stops ongoing communications without changing the queues.

Return values

  NRF_SUCCESS | If Enhanced ShockBurst was suspended.
  NRF_ERROR_BUSY | If the function failed because the radio is busy.

uint32_t nrf_esb_update_prefix | ( | uint8_t | pipe,
|  | uint8_t | prefix
| ) |  |

Function for updating the prefix for a pipe.

Parameters

  pipe | Pipe for which to set the prefix.
  prefix | Prefix to set for the pipe.

Return values

  NRF_SUCCESS | If the operation completed successfully.
  NRF_ERROR_BUSY | If the function failed because the radio is busy.
  NRF_ERROR_INVALID_PARAM | If the given pipe number was invalid.

uint32_t nrf_esb_write_payload | ( | nrf_esb_payload_t const * | p_payload | ) |

Function for writing a payload for transmission or acknowledgment.

This function writes a payload that is added to the queue. When the module is in PTX mode, the payload is queued for a regular transmission. When the module is in PRX mode, the payload is queued for when a packet is received that requires an acknowledgment with payload.

Parameters

  [in] | p_payload | Pointer to the structure that contains information and state of the payload.

Return values

  NRF_SUCCESS | If the payload was successfully queued for writing.
  NRF_ERROR_NULL | If the required parameter was NULL.
  NRF_INVALID_STATE | If the module is not initialized.
  NRF_ERROR_NOT_SUPPORTED | If `p_payload->noack` was false, but selective acknowledgment is not enabled.
  NRF_ERROR_NO_MEM | If the TX FIFO is full.
  NRF_ERROR_INVALID_LENGTH | If the payload length was invalid (zero or larger than the allowed maximum).

STATIC_ASSERT | ( | 32<= | 252 | ) |

Parameters

  252 | The maximum size of the payload. Valid values are 1 to 252.