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.

Modules

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

Enumeration Type Documentation

Function Documentation