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, check out the Enhanced ShockBurst: Transmitter/Receiver sample.

API documentation¶

group nrf_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_EVT_IRQ¶: The ESB event IRQ number when running on an nRF5 device.

ESB_EVT_IRQHandler¶: The handler for ESB_EVT_IRQ when running on an nRF5 device.

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

NRF_ESB_LEGACY_CONFIG¶

Default legacy radio parameters.

Identical to the nRF24Lxx defaults.

NRF_ESB_CREATE_PAYLOAD(_pipe, ...)¶

Macro to create an initializer for a TX data packet.

This macro generates an initializer.

Return

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

Parameters

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

Typedefs

typedef void (*nrf_esb_event_handler)(const struct nrf_esb_evt *event)¶: Definition of the event handler for the module.

Enums

enum nrf_esb_protocol¶

Enhanced ShockBurst protocols.

Values:

NRF_ESB_PROTOCOL_ESB¶: Enhanced ShockBurst with fixed payload length.

NRF_ESB_PROTOCOL_ESB_DPL¶: Enhanced ShockBurst with dynamic payload length.

enum nrf_esb_mode¶

Enhanced ShockBurst modes.

Values:

NRF_ESB_MODE_PTX¶: Primary transmitter mode.

NRF_ESB_MODE_PRX¶: Primary receiver mode.

enum nrf_esb_bitrate¶

Enhanced ShockBurst bitrate modes.

Values:

NRF_ESB_BITRATE_1MBPS = RADIO_MODE_MODE_Nrf_1Mbit¶: 1 Mb radio mode.

NRF_ESB_BITRATE_2MBPS = RADIO_MODE_MODE_Nrf_2Mbit¶: 2 Mb radio mode.

NRF_ESB_BITRATE_250KBPS = RADIO_MODE_MODE_Nrf_250Kbit¶: 250 Kb radio mode.

NRF_ESB_BITRATE_1MBPS_BLE = RADIO_MODE_MODE_Ble_1Mbit¶: 1 Mb radio mode using Bluetooth low energy radio parameters.

enum nrf_esb_crc¶

Enhanced ShockBurst CRC modes.

Values:

NRF_ESB_CRC_16BIT = RADIO_CRCCNF_LEN_Two¶: Use two-byte CRC.

NRF_ESB_CRC_8BIT = RADIO_CRCCNF_LEN_One¶: Use one-byte CRC.

NRF_ESB_CRC_OFF = RADIO_CRCCNF_LEN_Disabled¶: Disable CRC.

enum nrf_esb_tx_power¶

Enhanced ShockBurst radio transmission power modes.

Values:

NRF_ESB_TX_POWER_4DBM = RADIO_TXPOWER_TXPOWER_Pos4dBm¶: 4 dBm radio transmit power.

NRF_ESB_TX_POWER_0DBM = RADIO_TXPOWER_TXPOWER_0dBm¶: 0 dBm radio transmit power.

NRF_ESB_TX_POWER_NEG4DBM = RADIO_TXPOWER_TXPOWER_Neg4dBm¶: -4 dBm radio transmit power.

NRF_ESB_TX_POWER_NEG8DBM = RADIO_TXPOWER_TXPOWER_Neg8dBm¶: -8 dBm radio transmit power.

NRF_ESB_TX_POWER_NEG12DBM = RADIO_TXPOWER_TXPOWER_Neg12dBm¶: -12 dBm radio transmit power.

NRF_ESB_TX_POWER_NEG16DBM = RADIO_TXPOWER_TXPOWER_Neg16dBm¶: -16 dBm radio transmit power.

NRF_ESB_TX_POWER_NEG20DBM = RADIO_TXPOWER_TXPOWER_Neg20dBm¶: -20 dBm radio transmit power.

NRF_ESB_TX_POWER_NEG30DBM = RADIO_TXPOWER_TXPOWER_Neg30dBm¶: -30 dBm radio transmit power.

NRF_ESB_TX_POWER_NEG40DBM = RADIO_TXPOWER_TXPOWER_Neg40dBm¶: -40 dBm radio transmit power.

enum nrf_esb_tx_mode¶

Enhanced ShockBurst transmission modes.

Values:

NRF_ESB_TXMODE_AUTO¶: Automatic TX mode: When the TX FIFO contains packets and the radio is idle, packets are sent automatically.

NRF_ESB_TXMODE_MANUAL¶: Manual TX mode: Packets are not sent until nrf_esb_start_tx is called. This mode can be used to ensure consistent packet timing.

NRF_ESB_TXMODE_MANUAL_START¶: Manual start TX mode: Packets are not sent until nrf_esb_start_tx is called. Then, transmission continues automatically until the TX FIFO is empty.

enum nrf_esb_evt_id¶

Enhanced ShockBurst event IDs.

Values:

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.

Functions

int nrf_esb_init(const struct nrf_esb_config *config)¶

Initialize the Enhanced ShockBurst module.

Return

Zero on success or (negative) error code otherwise.

Parameters

config: Parameters for initializing the module.

int nrf_esb_suspend(void)¶

Suspend the Enhanced ShockBurst module.

Calling this function stops ongoing communications without changing the queues.

Return Value

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

void nrf_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 nrf_esb_is_idle(void)¶

Check if the Enhanced ShockBurst module is idle.

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

int nrf_esb_write_payload(const struct nrf_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: The payload.

Return Value

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

int nrf_esb_read_rx_payload(struct nrf_esb_payload *payload)¶

Read a payload.

Parameters

payload: The payload to be received.

Return Value

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

int nrf_esb_start_tx(void)¶

Start transmitting data.

Return Value

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

int nrf_esb_start_rx(void)¶

Start receiving data.

Return Value

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

int nrf_esb_stop_rx(void)¶

Stop data reception.

Return Value

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

int nrf_esb_flush_tx(void)¶

Flush the TX buffer.

This function clears the TX FIFO buffer.

Return Value

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

int nrf_esb_pop_tx(void)¶

Pop the first item from the TX buffer.

Return Value

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

int nrf_esb_flush_rx(void)¶

Flush the RX buffer.

Return Value

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

int nrf_esb_set_address_length(u8_t length)¶

Set the length of the address.

Parameters

length: Length of the ESB address (in bytes).

Return Value

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

int nrf_esb_set_base_address_0(const u8_t *addr)¶

Set the base address for pipe 0.

Parameters

addr: Address.

Return Value

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

int nrf_esb_set_base_address_1(const u8_t *addr)¶

Set the base address for pipe 1 to pipe 7.

Parameters

addr: Address.

Return Value

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

int nrf_esb_set_prefixes(const u8_t *prefixes, u8_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: Prefixes for each pipe.
num_pipes: Number of pipes. Must be less than or equal to CONFIG_NRF_ESB_PIPE_COUNT.

Return Value

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

int nrf_esb_enable_pipes(u8_t enable_mask)¶

Enable select pipes.

The enable_mask parameter must contain the same number of pipes as has been configured with nrf_esb_set_prefixes. This number may not be greater than the number defined by CONFIG_NRF_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 Value

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

int nrf_esb_update_prefix(u8_t pipe, u8_t prefix)¶

Update pipe prefix.

Parameters

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

Return Value

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

int nrf_esb_set_rf_channel(u32_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: Channel to use for radio.

Return Value

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

int nrf_esb_get_rf_channel(u32_t *channel)¶

Get the current radio channel.

Parameters

channel: Channel number.

Return Value

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

int nrf_esb_set_tx_power(enum nrf_esb_tx_power tx_output_power)¶

Set the radio output power.

Parameters

tx_output_power: Output power.

Return Value

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

int nrf_esb_set_retransmit_delay(u16_t delay)¶

Set the packet retransmit delay.

Parameters

delay: Delay between retransmissions.

Return Value

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

int nrf_esb_set_retransmit_count(u16_t count)¶

Set the number of retransmission attempts.

Parameters

count: Number of retransmissions.

Return Value

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

int nrf_esb_set_bitrate(enum nrf_esb_bitrate bitrate)¶

Set the radio bitrate.

Parameters

bitrate: Radio bitrate.

Return Value

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

int nrf_esb_reuse_pid(u8_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: Pipe.

Return Value

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

struct nrf_esb_payload¶

#include <nrf_esb.h>

Enhanced ShockBurst payload.

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

Public Members

u8_t length¶: Length of the packet when not in DPL mode.

u8_t pipe¶: Pipe used for this payload.

s8_t rssi¶: RSSI for the received packet.

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

u8_t pid¶: PID assigned during communication.

u8_t data[CONFIG_NRF_ESB_MAX_PAYLOAD_LENGTH]¶: The payload data.

struct nrf_esb_evt¶

#include <nrf_esb.h>

Enhanced ShockBurst event.

Public Members

nrf_esb_evt_id evt_id¶: Enhanced ShockBurst event ID.

u32_t tx_attempts¶: Number of TX retransmission attempts.

struct nrf_esb_config¶

#include <nrf_esb.h>

Main configuration structure for the module.

Public Members

nrf_esb_protocol protocol¶: ESB protocol.

nrf_esb_mode mode¶: ESB mode.

nrf_esb_event_handler event_handler¶: ESB event handler.

nrf_esb_bitrate bitrate¶: Bitrate mode.

nrf_esb_crc crc¶: CRC mode.

nrf_esb_tx_power tx_output_power¶: Radio TX power.

u16_t retransmit_delay¶: The delay between each retransmission of unacknowledged packets.

u16_t retransmit_count¶: The number of retransmission attempts before transmission fail.

nrf_esb_tx_mode tx_mode¶: Transmission mode.

u8_t radio_irq_priority¶: nRF radio interrupt priority.

u8_t event_irq_priority¶: ESB event interrupt priority.

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