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...
|
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...
|
|
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.
#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 |
#define NRF_ESB_CREATE_PAYLOAD |
( |
|
_pipe, |
|
|
|
... |
|
) |
| |
Value:{.pipe = _pipe, .length =
NUM_VA_ARGS(__VA_ARGS__), .data = {__VA_ARGS__}}; \
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, \
.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, \
.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 |
#define NRF_ESB_TX_FIFO_SIZE 8 |
The size of the transmission first-in, first-out buffer.
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.
|
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.
|
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.
|
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.
|
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. |
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. |
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). |
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. |
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. |