Enhanced ShockBurst

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

See the ESB user guide for more information. Also, see the Enhanced ShockBurst: Transmitter and Enhanced ShockBurst: Receiver samples.

API documentation 

Header file: include/esb.h

Source files: subsys/esb/

group esb

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.

Defines

ESB_DEFAULT_CONFIG

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.

ESB_LEGACY_CONFIG

Default legacy radio parameters.

Identical to the nRF24Lxx defaults.

ESB_CREATE_PAYLOAD(_pipe, ...)

Macro to create an initializer for a TX data packet.

This macro generates an initializer.

Parameters:

_pipe – [in] 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.

Typedefs

typedef void (*esb_event_handler)(const struct esb_evt *event): Event handler prototype.

Enums

enum esb_protocol

Enhanced ShockBurst protocols.

Values:

enumerator ESB_PROTOCOL_ESB: Fixed payload length.

enumerator ESB_PROTOCOL_ESB_DPL: Dynamic payload length.

enum esb_mode

Enhanced ShockBurst modes.

Values:

enumerator ESB_MODE_PTX: Primary transmitter mode.

enumerator ESB_MODE_PRX: Primary receiver mode.

enum esb_bitrate

Enhanced ShockBurst bitrate modes.

Values:

enumerator ESB_BITRATE_1MBPS: 1 Mb radio mode.

enumerator ESB_BITRATE_2MBPS: 2 Mb radio mode.

enumerator ESB_BITRATE_250KBPS: 250 Kb radio mode.

enumerator ESB_BITRATE_1MBPS_BLE: 1 Mb radio mode using Bluetooth low energy radio parameters.

enum esb_crc

Enhanced ShockBurst CRC modes.

Values:

enumerator ESB_CRC_16BIT: Use two-byte CRC.

enumerator ESB_CRC_8BIT: Use one-byte CRC.

enumerator ESB_CRC_OFF: Disable CRC.

enum esb_tx_power

Enhanced ShockBurst radio transmission power modes.

Values:

enumerator ESB_TX_POWER_0DBM: 0 dBm radio transmit power.

enumerator ESB_TX_POWER_NEG4DBM: -4 dBm radio transmit power.

enumerator ESB_TX_POWER_NEG8DBM: -8 dBm radio transmit power.

enumerator ESB_TX_POWER_NEG12DBM: -12 dBm radio transmit power.

enumerator ESB_TX_POWER_NEG16DBM: -16 dBm radio transmit power.

enumerator ESB_TX_POWER_NEG20DBM: -20 dBm radio transmit power.

enumerator ESB_TX_POWER_NEG30DBM: -30 dBm radio transmit power.

enum esb_tx_mode

Enhanced ShockBurst transmission modes.

Values:

enumerator ESB_TXMODE_AUTO: Automatic TX mode: When the TX FIFO contains packets and the radio is idle, packets are sent automatically.

enumerator ESB_TXMODE_MANUAL: Manual TX mode: Packets are not sent until esb_start_tx is called. This mode can be used to ensure consistent packet timing.

enumerator ESB_TXMODE_MANUAL_START: Manual start TX mode: Packets are not sent until esb_start_tx is called. Then, transmission continues automatically until the TX FIFO is empty.

enum esb_evt_id

Enhanced ShockBurst event IDs.

Values:

enumerator ESB_EVENT_TX_SUCCESS: Event triggered on TX success.

enumerator ESB_EVENT_TX_FAILED: Event triggered on TX failure.

enumerator ESB_EVENT_RX_RECEIVED: Event triggered on RX received.

Functions

int esb_init(const struct esb_config *config)

Initialize the Enhanced ShockBurst module.

Parameters:

config – Parameters for initializing the module.

Returns:

Zero on success or (negative) error code otherwise.

int esb_suspend(void)

Suspend the Enhanced ShockBurst module.

Calling this function stops ongoing communications without changing the queues.

Return values:: 0 – If successful. Otherwise, a (negative) error code is returned.

void esb_disable(void)

Disable 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.

bool esb_is_idle(void)

Check if the Enhanced ShockBurst module is idle.

Returns:: True if the module is idle, false otherwise.

int esb_write_payload(const struct esb_payload *payload)

Write a payload for transmission or acknowledgement.

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 acknowledgement with payload.

Parameters:

payload – [in] The payload.

Return values:

0 – If successful. Otherwise, a (negative) error code is returned.

int esb_read_rx_payload(struct esb_payload *payload)

Read a payload.

Parameters:

payload – [inout] The payload to be received.

Return values:

0 – If successful. Otherwise, a (negative) error code is returned.

int esb_start_tx(void)

Start transmitting data.

Return values:: 0 – If successful. Otherwise, a (negative) error code is returned.

int esb_start_rx(void)

Start receiving data.

Return values:: 0 – If successful. Otherwise, a (negative) error code is returned.

int esb_stop_rx(void)

Stop data reception.

Return values:: 0 – If successful. Otherwise, a (negative) error code is returned.

int esb_flush_tx(void)

Flush the TX buffer.

This function clears the TX FIFO buffer.

Return values:: 0 – If successful. Otherwise, a (negative) error code is returned.

int esb_pop_tx(void)

Pop the first item from the TX buffer.

Return values:: 0 – If successful. Otherwise, a (negative) error code is returned.

bool esb_tx_full(void)

Check if there is some free space left in TX FIFO.

Return values:: true – when the TX FIFO is full, otherwise false.

int esb_flush_rx(void)

Flush the RX buffer.

Return values:: 0 – If successful. Otherwise, a (negative) error code is returned.

int esb_set_address_length(uint8_t length)

Set the length of the address.

Parameters:

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

Return values:

0 – If successful. Otherwise, a (negative) error code is returned.

int esb_set_base_address_0(const uint8_t *addr)

Set the base address for pipe 0.

Parameters:

addr – [in] Address.

Return values:

0 – If successful. Otherwise, a (negative) error code is returned.

int esb_set_base_address_1(const uint8_t *addr)

Set the base address for pipe 1 to pipe 7.

Parameters:

addr – [in] Address.

Return values:

0 – If successful. Otherwise, a (negative) error code is returned.

int esb_set_prefixes(const uint8_t *prefixes, uint8_t num_pipes)

Set 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:

prefixes – [in] Prefixes for each pipe.
num_pipes – [in] Number of pipes. Must be less than or equal to CONFIG_ESB_PIPE_COUNT .

Return values:

0 – If successful. Otherwise, a (negative) error code is returned.

int esb_enable_pipes(uint8_t enable_mask)

Enable select pipes.

The enable_mask parameter must contain the same number of pipes as has been configured with esb_set_prefixes. This number may not be greater than the number defined by CONFIG_ESB_PIPE_COUNT

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:

0 – If successful. Otherwise, a (negative) error code is returned.

int esb_update_prefix(uint8_t pipe, uint8_t prefix)

Update pipe prefix.

Parameters:

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

Return values:

0 – If successful. Otherwise, a (negative) error code is returned.

int esb_set_rf_channel(uint32_t channel)

Set 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:

channel – [in] Channel to use for radio.

Return values:

0 – If successful. Otherwise, a (negative) error code is returned.

int esb_get_rf_channel(uint32_t *channel)

Get the current radio channel.

Parameters:

channel – [inout] Channel number.

Return values:

0 – If successful. Otherwise, a (negative) error code is returned.

int esb_set_tx_power(int8_t tx_output_power)

Set the radio output power.

Parameters:

tx_output_power – [in] Output power in dBm. The esb_tx_power values can be used to provide backward compatibility.

Return values:

0 – If successful. Otherwise, a (negative) error code is returned.

int esb_set_retransmit_delay(uint16_t delay)

Set the packet retransmit delay.

Parameters:

delay – [in] Delay between retransmissions.

Return values:

0 – If successful. Otherwise, a (negative) error code is returned.

int esb_set_retransmit_count(uint16_t count)

Set the number of retransmission attempts.

If the CONFIG_ESB_NEVER_DISABLE_TX Kconfig option is enabled, this is the delay between two consecutive transmissions. Depending on the reception processing time, a minimal value might be required (for example, a typical value for 32-bit payload is 20 µs).

Parameters:

count – [in] Number of retransmissions.

Return values:

0 – If successful. Otherwise, a (negative) error code is returned.

int esb_set_bitrate(enum esb_bitrate bitrate)

Set the radio bitrate.

Parameters:

bitrate – [in] Radio bitrate.

Return values:

0 – If successful. Otherwise, a (negative) error code is returned.

int esb_reuse_pid(uint8_t pipe)

Reuse a packet ID for a specific pipe.

The ESB protocol uses a 2-bit sequence number (packet ID) to identify retransmitted packets. By default, the packet ID is incremented for every uploaded packet. Use this function to prevent this and send two different packets with the same packet ID.

Parameters:

pipe – [in] Pipe.

Return values:

0 – If successful. Otherwise, a (negative) error code is returned.

struct esb_payload

#include <esb.h>

Enhanced ShockBurst payload.

The payload is used both for transmissions and for acknowledging a received packet with a payload.

Public Members

uint8_t length: Length of the packet when not in DPL mode.

uint8_t pipe: Pipe used for this payload.

int8_t rssi: RSSI for the received packet.

uint8_t noack: Flag indicating that this packet will not be acknowledged. Flag is ignored when selective auto ack is enabled.

uint8_t pid: PID assigned during communication.

uint8_t data[CONFIG_ESB_MAX_PAYLOAD_LENGTH]: The payload data.

struct esb_evt

#include <esb.h>

Enhanced ShockBurst event.

Public Members

enum esb_evt_id evt_id: Enhanced ShockBurst event ID.

uint32_t tx_attempts: Number of TX retransmission attempts.

struct esb_config

#include <esb.h>

Main configuration structure for the module.

Public Members

enum esb_protocol protocol: Protocol.

enum esb_mode mode: Mode.

esb_event_handler event_handler: Event handler.

enum esb_bitrate bitrate: Bitrate mode.

enum esb_crc crc: CRC mode.

int8_t tx_output_power: Radio TX power.

uint16_t retransmit_delay: The delay between each retransmission of unacknowledged packets. If the CONFIG_ESB_NEVER_DISABLE_TX Kconfig option is enabled, this is the delay between two consecutive transmissions. Depending on the reception processing time, a minimal value might be required (for example, a typical value for 32-bit payload is 20 µs).

uint16_t retransmit_count: The number of retransmission attempts before transmission fail.

enum esb_tx_mode tx_mode: Transmission mode.

uint8_t payload_length: Length of the payload (maximum length depends on the platforms that are used on each side).

bool selective_auto_ack: Selective auto acknowledgement. When this feature is disabled, all packets will be acknowledged ignoring the noack field.

bool use_fast_ramp_up: When this feature is enabled, radio TXEN and RXEN delays are reduced from 130 µs to 40 µs. The radio peripheral needs some time to start up analog components of the radio. On the nRF51 and nRF24L Series devices, a hard-coded 130 µs delay is implemented. If ESB connection is achieved only between nRF52 and/or nRF53 Series devices, this delay can be reduced to 40 µs.

Enhanced ShockBurst

API documentation

API documentation 