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

Data Structures
struct	nrf_esb_address_t
	Enhanced ShockBurst addresses. More...

struct	nrf_esb_payload_t
	Enhanced ShockBurst payload. More...

struct	nrf_esb_evt_t
	Enhanced ShockBurst event. More...

struct	nrf_esb_config_t
	Main nrf_esb configuration struct. 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 NRF_TIMER2

#define	NRF_ESB_SYS_TIMER_IRQ_Handler TIMER2_IRQHandler

#define	NRF_ESB_SYS_TIMER_IRQ_Handler TIMER2_IRQHandler

#define	NRF_ESB_PPI_TIMER_START 10

#define	NRF_ESB_PPI_TIMER_START 10

#define	NRF_ESB_PPI_TIMER_STOP 11

#define	NRF_ESB_PPI_TIMER_STOP 11

#define	NRF_ESB_PPI_RX_TIMEOUT 12

#define	NRF_ESB_PPI_RX_TIMEOUT 12

#define	NRF_ESB_PPI_TX_START 13

#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 protocol.

enum	nrf_esb_mode_t { NRF_ESB_MODE_PTX , NRF_ESB_MODE_PRX }
	Enhanced ShockBurst mode.

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 mode. 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 id 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 Enhanced ShockBurst. More...

uint32_t	nrf_esb_disable (void)
	Function for disabling Enhanced ShockBurst. More...

bool	nrf_esb_is_idle (void)
	Function to check if nrf_esb is idle. More...

uint32_t	nrf_esb_write_payload ( nrf_esb_payload_t const *p_payload)
	Function to write TX or ack payload. More...

uint32_t	nrf_esb_read_rx_payload ( nrf_esb_payload_t *p_payload)
	Function to read RX payload. More...

uint32_t	nrf_esb_start_tx (void)
	Function to start transmitting. More...

uint32_t	nrf_esb_start_rx (void)
	Function to start transmitting data in FIFO buffer. More...

uint32_t	nrf_esb_stop_rx (void)
	Function to stop receiving data. More...

uint32_t	nrf_esb_flush_tx (void)
	Function to remove remaining items from the TX buffer. More...

uint32_t	nrf_esb_pop_tx (void)
	Function to remove the first items from the TX buffer. More...

uint32_t	nrf_esb_flush_rx (void)
	Function to remove remaining items from the RX buffer. More...

uint32_t	nrf_esb_get_clear_interrupts (uint32_t *p_interrupts)
	Function to clear pending interrupts. More...

uint32_t	nrf_esb_set_address_length (uint8_t length)
	Function to set address length. More...

uint32_t	nrf_esb_set_base_address_0 (uint8_t const *p_addr)
	Function to set the base address 0. More...

uint32_t	nrf_esb_set_base_address_1 (uint8_t const *p_addr)
	Function to set the base address 1. More...

uint32_t	nrf_esb_set_prefixes (uint8_t const *p_prefixes, uint8_t num_pipes)
	Function to set pipe prefix addresses. More...

uint32_t	nrf_esb_enable_pipes (uint8_t enable_mask)
	Function to control what pipes are enabled. More...

uint32_t	nrf_esb_update_prefix (uint8_t pipe, uint8_t prefix)
	Function to update prefix per pipe. More...

uint32_t	nrf_esb_set_rf_channel (uint32_t channel)
	Function to set the channel to use for the radio. More...

uint32_t	nrf_esb_rf_channel_get (uint32_t *p_channel)
	Function to get the current rf_channel. More...

uint32_t	nrf_esb_set_tx_power ( nrf_esb_tx_power_t tx_output_power)
	Function to set the radio output power. More...

Detailed Description

Enhanced ShockBurst (ESB) is a basic protocol supporting 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

ESB Event IRQ number when running on a nRF51 device.

#define ESB_EVT_IRQHandler SWI0_IRQHandler

The handler for ESB_EVT_IRQ when running on a nRF51 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 nRF24Lxx default (except pipe number which is only possible .

#define NRF_ESB_CRC_RESET_VALUE 0xFFFF

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 initializer for a TX data packet.

This macro generates an initializer. It 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 are from 1 to 63 characters.

Returns: Initializer that sets up pipe, length and the 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 nRF24Lxx default parameters (except CRC which is set to 16-bit, and protocol set to DPL).

#define NRF_ESB_INT_RX_DR_MSK 0x04

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

#define NRF_ESB_INT_TX_FAILED_MSK 0x02

The flag used to indicate a failiure since last event.

#define NRF_ESB_INT_TX_SUCCESS_MSK 0x01

The flag used to indicate a success since 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 nRF24L defaults.

#define NRF_ESB_MAX_PAYLOAD_LENGTH 32

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

#define NRF_ESB_PID_MAX 3

Maximum value for PID.

#define NRF_ESB_PID_RESET_VALUE 0xFF

Invalid PID value which is guaranteed to not colide with any valid PID value.

#define NRF_ESB_PPI_RX_TIMEOUT 12

The PPI channel used for RX timeout.

PPI channel for RX timeout.

#define NRF_ESB_PPI_RX_TIMEOUT 12

The PPI channel used for RX timeout.

PPI channel for RX timeout.

#define NRF_ESB_PPI_TIMER_START 10

The PPI channel used for timer start.

PPI channel for timer start.

#define NRF_ESB_PPI_TIMER_START 10

The PPI channel used for timer start.

PPI channel for timer start.

#define NRF_ESB_PPI_TIMER_STOP 11

The PPI channel used for timer stop.

PPI Channel for timer stop.

#define NRF_ESB_PPI_TIMER_STOP 11

The PPI channel used for timer stop.

PPI Channel for timer stop.

#define NRF_ESB_PPI_TX_START 13

The PPI channel used for starting TX.

PPI channel for TX start.

#define NRF_ESB_PPI_TX_START 13

The PPI channel used for starting TX.

PPI channel for TX start.

#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 which will be used by the module.

System timer used by nrf_esb

#define NRF_ESB_SYS_TIMER NRF_TIMER2

The timer which will be used by the module.

System timer used by nrf_esb

#define NRF_ESB_SYS_TIMER_IRQ_Handler TIMER2_IRQHandler

The handler which will be used by NRF_ESB_SYS_TIMER.

Timer IRQ handler used by nrf_esb

#define NRF_ESB_SYS_TIMER_IRQ_Handler TIMER2_IRQHandler

The handler which will be used by NRF_ESB_SYS_TIMER.

Timer IRQ handler used by nrf_esb

#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 mode.

Enumerator
NRF_ESB_BITRATE_2MBPS	2Mbit radio mode.
NRF_ESB_BITRATE_1MBPS	1Mbit radio mode.
NRF_ESB_BITRATE_250KBPS	250Kbit radio mode.
NRF_ESB_BITRATE_1MBPS_BLE	1Mbit 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 id 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 failed.
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 Enhanced ShockBurst.

Disable the Enhanced ShockBurst module immediately. This may stop ongoing communication.

Note: All queues are flushed by this function.

Return values

NRF_SUCCESS Enhanced ShockBurst was disabled.

uint32_t nrf_esb_enable_pipes ( uint8_t enable_mask )

Function to control what pipes are enabled.

Note: The enable_mask must correspond to the number of pipes that has been enabled with nrf_esb_set_prefixes. nrf_esb_set_pre

Parameters

enable_mask Bitfield mask to control enabling or disabling pipes. Setting bit to 0 disables the pipe. Setting bit to 1 enables the pipe.

uint32_t nrf_esb_flush_rx ( void )

Function to remove remaining items from the RX buffer.

Return values

NRF_SUCCESS	Pending items in the RX buffer was successfully cleared.
NRF_INVALID_STATE	Module is not initialized.

uint32_t nrf_esb_flush_tx ( void )

Function to remove remaining items from the TX buffer.

When this function is run, the TX fifo buffer will be cleared.

Return values

NRF_SUCCESS	Call was successful.
NRF_ERROR_NULL	Required parameter was NULL.
NRF_INVALID_STATE	Module is not initialized.

uint32_t nrf_esb_get_clear_interrupts ( uint32_t * p_interrupts )

Function to clear pending interrupts.

Parameters

[in,out] p_interrupts Pointer to value holding current interrupts.

Return values

NRF_SUCCESS	Call was successful.
NRF_ERROR_NULL	Required parameter was NULL.
NRF_INVALID_STATE	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	Initialization successful.
NRF_ERROR_NULL	The argument parameters was NULL.
NRF_ERROR_BUSY	Function failed because radio is busy.

bool nrf_esb_is_idle ( void )

Function to check if nrf_esb is idle.

Return values

idle	state True if nrf_esb is idle, otherwise false.

uint32_t nrf_esb_pop_tx ( void )

Function to remove the first items from the TX buffer.

Return values

NRF_SUCCESS	Call was successful.
NRF_INVALID_STATE	Module is not initialized.
NRF_ERROR_BUFFER_EMPTY	No items in queue to remove.

uint32_t nrf_esb_read_rx_payload ( nrf_esb_payload_t * p_payload )

Function to read RX payload.

Parameters

[in,out] p_payload Pointer to structure containing information and state of payload.

Return values

NRF_SUCCESS	Data read successfully.
NRF_ERROR_NULL	Required parameter was NULL.
NRF_INVALID_STATE	Module is not initialized.

uint32_t nrf_esb_rf_channel_get ( uint32_t * p_channel )

Function to get the current rf_channel.

Parameters

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

Return values

NRF_SUCCESS	Call was successful.
NRF_ERROR_NULL	Required parameter was NULL.

uint32_t nrf_esb_set_address_length ( uint8_t length )

Function to set address length.

Parameters

[in] length Length in bytes for esb address

Return values

NRF_SUCCESS	Call was successful.
NRF_ERROR_INVALID_PARAM	Invalid address length
NRF_ERROR_BUSY	Function failed because radio is busy.

uint32_t nrf_esb_set_base_address_0 ( uint8_t const * p_addr )

Function to set the base address 0.

Note: This base address is used by pipe 0.

Parameters

[in] p_addr Pointer to the address data.

Return values

NRF_SUCCESS	Call was successful.
NRF_ERROR_BUSY	Function failed because radio is busy.
NRF_ERROR_NULL	Required parameter was NULL.

uint32_t nrf_esb_set_base_address_1 ( uint8_t const * p_addr )

Function to set the base address 1.

Note: This base address is used by pipe 1 - 7.

Parameters

[in] p_addr Pointer to the address data.

Return values

NRF_SUCCESS	Call was successful.
NRF_ERROR_BUSY	Function failed because radio is busy.
NRF_ERROR_NULL	Required parameter was NULL.

uint32_t nrf_esb_set_prefixes	(	uint8_t const *	p_prefixes ,
		uint8_t	num_pipes
	)

Function to set pipe prefix addresses.

Parameters

[in]	p_prefixes	Pointer to char array containing prefixes for pipe 0 to 7.
	num_pipes	Number of pipes to set.

Return values

NRF_SUCCESS	Call was successful.
NRF_ERROR_BUSY	Function failed because radio is busy.
NRF_ERROR_NULL	Required parameter was NULL.
NRF_ERROR_INVALID_PARAM	Invalid pipe number given.

uint32_t nrf_esb_set_rf_channel ( uint32_t channel )

Function to set the channel to use for the radio.

Note: The module has to be in an idle state to call this function. As a PTX the application has to wait for an idle state and as an 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	Call was successful.
NRF_INVALID_STATE	Module is not initialized.
NRF_ERROR_BUSY	Module was not in idle state.
NRF_ERROR_INVALID_PARAM	Channel is invalid (larger than 125).

uint32_t nrf_esb_set_tx_power ( nrf_esb_tx_power_t tx_output_power )

Function to set the radio output power.

Parameters

[in] tx_output_power Output power.

Return values

NRF_SUCCESS	Call was successful.
NRF_ERROR_BUSY	Function failed because radio is busy.

uint32_t nrf_esb_start_rx ( void )

Function to start transmitting data in FIFO buffer.

Return values

NRF_SUCCESS	RX started successfully.
NRF_ERROR_BUSY	Function failed because radio is busy.

uint32_t nrf_esb_start_tx ( void )

Function to start transmitting.

Return values

NRF_SUCCESS	TX started successfully.
NRF_ESB_ERROR_TX_FIFO_EMPTY	TX won't start because FIFO buffer is empty.
NRF_ERROR_BUSY	Function failed because radio is busy.

uint32_t nrf_esb_stop_rx ( void )

Function to stop receiving data.

Return values

NRF_SUCCESS	Rx started successfully.
NRF_ERROR_BUSY	Function failed because radio is busy.

uint32_t nrf_esb_suspend ( void )

Function for suspending Enhanced ShockBurst.

Note: Will stop ongoing communications without changing the queues

Return values

NRF_SUCCESS	Enhanced ShockBurst was disabled.
NRF_ERROR_BUSY	Function failed because radio is busy.

uint32_t nrf_esb_update_prefix	(	uint8_t	pipe ,
		uint8_t	prefix
	)

Function to update prefix per pipe.

Parameters

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

Return values

NRF_SUCCESS	Call was successful.
NRF_ERROR_BUSY	Function failed because radio is busy.
NRF_ERROR_INVALID_PARAM	Invalid pipe number given.

uint32_t nrf_esb_write_payload ( nrf_esb_payload_t const * p_payload )

Function to write TX or ack payload.

Function for writing a payload to be added to the queue. When the module is in PTX mode, the payload will be queued for for a regular transmission. When the module is in PRX mode, the payload will be queued for when a packet is received with ack with payload.

Parameters

[in] p_payload Pointer to structure containing information and state of payload.

Return values

NRF_SUCCESS	Payload was successfully queued up for writing.
NRF_ERROR_NULL	Required parameter was NULL.
NRF_INVALID_STATE	Module is not initialized.
NRF_ERROR_NOT_SUPPORTED	p_payload->noack was false while selective ack was not enabled.
NRF_ERROR_INVALID_LENGTH	Payload length was invalid (zero or larger than max allowed).

STATIC_ASSERT ( 32<= 252 )

Parameters

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

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

Enumeration Type Documentation

Function Documentation