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¶
include/esb.h
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_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.
-
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.
Enums
-
enum
esb_protocol
¶ Enhanced ShockBurst protocols.
Values:
-
enumerator
ESB_PROTOCOL_ESB
¶ Fixed payload length.
-
enumerator
ESB_PROTOCOL_ESB_DPL
¶ Dynamic payload length.
-
enumerator
-
enum
esb_mode
¶ Enhanced ShockBurst modes.
Values:
-
enumerator
ESB_MODE_PTX
¶ Primary transmitter mode.
-
enumerator
ESB_MODE_PRX
¶ Primary receiver mode.
-
enumerator
-
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.
-
enumerator
-
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.
-
enumerator
-
enum
esb_tx_power
¶ Enhanced ShockBurst radio transmission power modes.
Values:
-
enumerator
ESB_TX_POWER_4DBM
¶ 4 dBm radio transmit power.
-
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.
-
enumerator
ESB_TX_POWER_NEG40DBM
¶ -40 dBm radio transmit power.
-
enumerator
-
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.
-
enumerator
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.
- Returns 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.
- Returns 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.
- Returns 0
If successful. Otherwise, a (negative) error code is returned.
-
int
esb_start_tx
(void)¶ Start transmitting data.
- Returns 0
If successful. Otherwise, a (negative) error code is returned.
-
int
esb_start_rx
(void)¶ Start receiving data.
- Returns 0
If successful. Otherwise, a (negative) error code is returned.
-
int
esb_stop_rx
(void)¶ Stop data reception.
- Returns 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.
- Returns 0
If successful. Otherwise, a (negative) error code is returned.
-
int
esb_pop_tx
(void)¶ Pop the first item from the TX buffer.
- Returns 0
If successful. Otherwise, a (negative) error code is returned.
-
int
esb_flush_rx
(void)¶ Flush the RX buffer.
- Returns 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).
- Returns 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.
- Returns 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.
- Returns 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
.
- Returns 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 byCONFIG_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.
- Returns 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.
- Returns 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.
- Returns 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.
- Returns 0
If successful. Otherwise, a (negative) error code is returned.
-
int
esb_set_tx_power
(enum esb_tx_power tx_output_power)¶ Set the radio output power.
- Parameters
tx_output_power – [in] Output power.
- Returns 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.
- Returns 0
If successful. Otherwise, a (negative) error code is returned.
-
int
esb_set_retransmit_count
(uint16_t count)¶ Set the number of retransmission attempts.
- Parameters
count – [in] Number of retransmissions.
- Returns 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.
- Returns 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.
- Returns 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.
-
uint8_t
-
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.
-
enum esb_evt_id
-
struct
esb_config
¶ - #include <esb.h>
Main configuration structure for the module.
Public Members
-
enum esb_protocol
protocol
¶ Protocol.
-
esb_event_handler
event_handler
¶ Event handler.
-
enum esb_bitrate
bitrate
¶ Bitrate mode.
-
enum esb_tx_power
tx_output_power
¶ Radio TX power.
-
uint16_t
retransmit_delay
¶ The delay between each retransmission of unacknowledged packets.
-
uint16_t
retransmit_count
¶ The number of retransmission attempts before transmission fail.
-
enum esb_tx_mode
tx_mode
¶ Transmission mode.
-
uint8_t
radio_irq_priority
¶ nRF radio interrupt priority.
-
uint8_t
event_irq_priority
¶ ESB event interrupt priority.
-
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.
-
enum esb_protocol
-