Wouter van Kleunen
/
nrf52_esb
NRF52_esb
Embed:
(wiki syntax)
Show/hide line numbers
nrf_esb.h
00001 /** 00002 * Copyright (c) 2016 - 2018, Nordic Semiconductor ASA 00003 * 00004 * All rights reserved. 00005 * 00006 * Redistribution and use in source and binary forms, with or without modification, 00007 * are permitted provided that the following conditions are met: 00008 * 00009 * 1. Redistributions of source code must retain the above copyright notice, this 00010 * list of conditions and the following disclaimer. 00011 * 00012 * 2. Redistributions in binary form, except as embedded into a Nordic 00013 * Semiconductor ASA integrated circuit in a product or a software update for 00014 * such product, must reproduce the above copyright notice, this list of 00015 * conditions and the following disclaimer in the documentation and/or other 00016 * materials provided with the distribution. 00017 * 00018 * 3. Neither the name of Nordic Semiconductor ASA nor the names of its 00019 * contributors may be used to endorse or promote products derived from this 00020 * software without specific prior written permission. 00021 * 00022 * 4. This software, with or without modification, must only be used with a 00023 * Nordic Semiconductor ASA integrated circuit. 00024 * 00025 * 5. Any software provided in binary form under this license must not be reverse 00026 * engineered, decompiled, modified and/or disassembled. 00027 * 00028 * THIS SOFTWARE IS PROVIDED BY NORDIC SEMICONDUCTOR ASA "AS IS" AND ANY EXPRESS 00029 * OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 00030 * OF MERCHANTABILITY, NONINFRINGEMENT, AND FITNESS FOR A PARTICULAR PURPOSE ARE 00031 * DISCLAIMED. IN NO EVENT SHALL NORDIC SEMICONDUCTOR ASA OR CONTRIBUTORS BE 00032 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 00033 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE 00034 * GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 00035 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 00036 * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT 00037 * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 00038 * 00039 */ 00040 #ifndef __NRF_ESB_H 00041 #define __NRF_ESB_H 00042 00043 #include <stdbool.h> 00044 #include <stdint.h> 00045 #include "nrf.h" 00046 #include "app_util.h" 00047 00048 #ifdef __cplusplus 00049 extern "C" { 00050 #endif 00051 00052 /** @defgroup nrf_esb Enhanced ShockBurst 00053 * @{ 00054 * @ingroup proprietary_api 00055 * 00056 * @brief Enhanced ShockBurst (ESB) is a basic protocol that supports two-way data 00057 * packet communication including packet buffering, packet acknowledgment, 00058 * and automatic retransmission of lost packets. 00059 */ 00060 00061 /** @name Debug pins 00062 * @{ 00063 * @brief If NRF_ESB_DEBUG is defined, these GPIO pins can be used for debug timing. 00064 */ 00065 00066 #define DEBUGPIN1 12 //!< If NRF_ESB_DEBUG is defined, this GPIO pin is set with every radio interrupt. 00067 #define DEBUGPIN2 13 //!< If NRF_ESB_DEBUG is defined, this GPIO pin is set with every NRF_RADIO->EVENTS_END. 00068 #define DEBUGPIN3 14 //!< If NRF_ESB_DEBUG is defined, this GPIO pin is set with every NRF_RADIO->EVENTS_DISABLED. 00069 #define DEBUGPIN4 15 //!< If NRF_ESB_DEBUG is defined, this GPIO pin is set when the radio is set to start transmission. 00070 00071 00072 #ifdef NRF_ESB_DEBUG 00073 #define DEBUG_PIN_SET(a) (NRF_GPIO->OUTSET = (1 << (a))) //!< Used internally to set debug pins. 00074 #define DEBUG_PIN_CLR(a) (NRF_GPIO->OUTCLR = (1 << (a))) //!< Used internally to clear debug pins. 00075 #else 00076 #define DEBUG_PIN_SET(a) //!< Used internally to set debug pins. 00077 #define DEBUG_PIN_CLR(a) //!< Used internally to clear debug pins. 00078 #endif 00079 00080 /** @} */ 00081 00082 #define NRF_ESB_RETRANSMIT_DELAY_MIN 135 00083 00084 // Hardcoded parameters - change if necessary 00085 #ifndef NRF_ESB_MAX_PAYLOAD_LENGTH 00086 #define NRF_ESB_MAX_PAYLOAD_LENGTH 32 //!< The maximum size of the payload. Valid values are 1 to 252. 00087 #endif 00088 00089 #define NRF_ESB_TX_FIFO_SIZE 8 //!< The size of the transmission first-in, first-out buffer. 00090 #define NRF_ESB_RX_FIFO_SIZE 8 //!< The size of the reception first-in, first-out buffer. 00091 00092 // 252 is the largest possible payload size according to the nRF5 architecture. 00093 STATIC_ASSERT(NRF_ESB_MAX_PAYLOAD_LENGTH <= 252); 00094 00095 #define NRF_ESB_SYS_TIMER NRF_TIMER2 //!< The timer that is used by the module. 00096 #define NRF_ESB_SYS_TIMER_IRQ_Handler TIMER2_IRQHandler //!< The handler that is used by @ref NRF_ESB_SYS_TIMER. 00097 00098 #define NRF_ESB_PPI_TIMER_START 10 //!< The PPI channel used for starting the timer. 00099 #define NRF_ESB_PPI_TIMER_STOP 11 //!< The PPI channel used for stopping the timer. 00100 #define NRF_ESB_PPI_RX_TIMEOUT 12 //!< The PPI channel used for RX time-out. 00101 #define NRF_ESB_PPI_TX_START 13 //!< The PPI channel used for starting TX. 00102 00103 /**@cond NO_DOXYGEN */ 00104 00105 // nRF52 address fix timer and PPI defines 00106 #ifdef NRF52 00107 #define NRF_ESB_PPI_BUGFIX1 9 00108 #define NRF_ESB_PPI_BUGFIX2 8 00109 #define NRF_ESB_PPI_BUGFIX3 7 00110 00111 #define NRF_ESB_BUGFIX_TIMER NRF_TIMER3 00112 #define NRF_ESB_BUGFIX_TIMER_IRQn TIMER3_IRQn 00113 #define NRF_ESB_BUGFIX_TIMER_IRQHandler TIMER3_IRQHandler 00114 #endif 00115 00116 /** @endcond */ 00117 00118 // Interrupt flags 00119 #define NRF_ESB_INT_TX_SUCCESS_MSK 0x01 //!< The flag used to indicate a success since the last event. 00120 #define NRF_ESB_INT_TX_FAILED_MSK 0x02 //!< The flag used to indicate a failure since the last event. 00121 #define NRF_ESB_INT_RX_DR_MSK 0x04 //!< The flag used to indicate that a packet was received since the last event. 00122 00123 #define NRF_ESB_PID_RESET_VALUE 0xFF //!< Invalid PID value that is guaranteed to not collide with any valid PID value. 00124 #define NRF_ESB_PID_MAX 3 //!< The maximum value for PID. 00125 #define NRF_ESB_CRC_RESET_VALUE 0xFFFF //!< The CRC reset value. 00126 00127 #define ESB_EVT_IRQ SWI0_IRQn //!< The ESB event IRQ number when running on an nRF5 device. 00128 #define ESB_EVT_IRQHandler SWI0_IRQHandler //!< The handler for @ref ESB_EVT_IRQ when running on an nRF5 device. 00129 00130 #if defined(NRF52) 00131 #define ESB_IRQ_PRIORITY_MSK 0x07 //!< The mask used to enforce a valid IRQ priority. 00132 #else 00133 #define ESB_IRQ_PRIORITY_MSK 0x03 //!< The mask used to enforce a valid IRQ priority. 00134 #endif 00135 00136 /** @brief Default address configuration for ESB. 00137 * @details Roughly equal to the nRF24Lxx default (except for the number of pipes, because more pipes are supported). */ 00138 #define NRF_ESB_ADDR_DEFAULT \ 00139 { \ 00140 .base_addr_p0 = { 0xE7, 0xE7, 0xE7, 0xE7 }, \ 00141 .base_addr_p1 = { 0xC2, 0xC2, 0xC2, 0xC2 }, \ 00142 .pipe_prefixes = { 0xE7, 0xC2, 0xC3, 0xC4, 0xC5, 0xC6, 0xC7, 0xC8 }, \ 00143 .addr_length = 5, \ 00144 .num_pipes = 8, \ 00145 .rf_channel = 2, \ 00146 .rx_pipes_enabled = 0xFF \ 00147 } 00148 00149 00150 /** @brief Default radio parameters. 00151 * @details Roughly equal to the nRF24Lxx default parameters (except for CRC, which is set to 16 bit, and protocol, which is set to DPL). */ 00152 #define NRF_ESB_DEFAULT_CONFIG {.protocol = NRF_ESB_PROTOCOL_ESB_DPL, \ 00153 .mode = NRF_ESB_MODE_PTX, \ 00154 .event_handler = 0, \ 00155 .bitrate = NRF_ESB_BITRATE_2MBPS, \ 00156 .crc = NRF_ESB_CRC_16BIT, \ 00157 .tx_output_power = NRF_ESB_TX_POWER_0DBM, \ 00158 .retransmit_delay = 250, \ 00159 .retransmit_count = 3, \ 00160 .tx_mode = NRF_ESB_TXMODE_AUTO, \ 00161 .radio_irq_priority = 1, \ 00162 .event_irq_priority = 2, \ 00163 .payload_length = 32, \ 00164 .selective_auto_ack = false \ 00165 } 00166 00167 00168 /** @brief Default legacy radio parameters. Identical to the nRF24Lxx defaults. */ 00169 #define NRF_ESB_LEGACY_CONFIG {.protocol = NRF_ESB_PROTOCOL_ESB, \ 00170 .mode = NRF_ESB_MODE_PTX, \ 00171 .event_handler = 0, \ 00172 .bitrate = NRF_ESB_BITRATE_2MBPS, \ 00173 .crc = NRF_ESB_CRC_8BIT, \ 00174 .tx_output_power = NRF_ESB_TX_POWER_0DBM, \ 00175 .retransmit_delay = 600, \ 00176 .retransmit_count = 3, \ 00177 .tx_mode = NRF_ESB_TXMODE_AUTO, \ 00178 .radio_irq_priority = 1, \ 00179 .event_irq_priority = 2, \ 00180 .payload_length = 32, \ 00181 .selective_auto_ack = false \ 00182 } 00183 00184 00185 /** @brief Macro to create an initializer for a TX data packet. 00186 * 00187 * @details This macro generates an initializer. Using the initializer is more efficient 00188 * than setting the individual parameters dynamically. 00189 * 00190 * @param[in] _pipe The pipe to use for the data packet. 00191 * @param[in] ... Comma separated list of character data to put in the TX buffer. 00192 * Supported values consist of 1 to 63 characters. 00193 * 00194 * @return Initializer that sets up the pipe, length, and byte array for content of the TX data. 00195 */ 00196 #define NRF_ESB_CREATE_PAYLOAD(_pipe, ...) \ 00197 {.pipe = _pipe, .length = NUM_VA_ARGS(__VA_ARGS__), .data = {__VA_ARGS__}}; \ 00198 STATIC_ASSERT(NUM_VA_ARGS(__VA_ARGS__) > 0 && NUM_VA_ARGS(__VA_ARGS__) <= 63) 00199 00200 00201 /**@brief Enhanced ShockBurst protocols. */ 00202 typedef enum { 00203 NRF_ESB_PROTOCOL_ESB, /**< Enhanced ShockBurst with fixed payload length. */ 00204 NRF_ESB_PROTOCOL_ESB_DPL /**< Enhanced ShockBurst with dynamic payload length. */ 00205 } nrf_esb_protocol_t; 00206 00207 00208 /**@brief Enhanced ShockBurst modes. */ 00209 typedef enum { 00210 NRF_ESB_MODE_PTX, /**< Primary transmitter mode. */ 00211 NRF_ESB_MODE_PRX /**< Primary receiver mode. */ 00212 } nrf_esb_mode_t; 00213 00214 00215 /**@brief Enhanced ShockBurst bitrate modes. */ 00216 typedef enum { 00217 NRF_ESB_BITRATE_2MBPS = RADIO_MODE_MODE_Nrf_2Mbit, /**< 2 Mb radio mode. */ 00218 NRF_ESB_BITRATE_1MBPS = RADIO_MODE_MODE_Nrf_1Mbit, /**< 1 Mb radio mode. */ 00219 NRF_ESB_BITRATE_250KBPS = RADIO_MODE_MODE_Nrf_250Kbit, /**< 250 Kb radio mode. */ 00220 NRF_ESB_BITRATE_1MBPS_BLE = RADIO_MODE_MODE_Ble_1Mbit, /**< 1 Mb radio mode using @e Bluetooth low energy radio parameters. */ 00221 #if defined(NRF52) 00222 NRF_ESB_BITRATE_2MBPS_BLE = 4 /**< 2 Mb radio mode using @e Bluetooth low energy radio parameters. */ 00223 #endif 00224 } nrf_esb_bitrate_t; 00225 00226 00227 /**@brief Enhanced ShockBurst CRC modes. */ 00228 typedef enum { 00229 NRF_ESB_CRC_16BIT = RADIO_CRCCNF_LEN_Two, /**< Use two-byte CRC. */ 00230 NRF_ESB_CRC_8BIT = RADIO_CRCCNF_LEN_One, /**< Use one-byte CRC. */ 00231 NRF_ESB_CRC_OFF = RADIO_CRCCNF_LEN_Disabled /**< Disable CRC. */ 00232 } nrf_esb_crc_t; 00233 00234 00235 /**@brief Enhanced ShockBurst radio transmission power modes. */ 00236 typedef enum { 00237 NRF_ESB_TX_POWER_4DBM = RADIO_TXPOWER_TXPOWER_Pos4dBm, /**< 4 dBm radio transmit power. */ 00238 #if defined(NRF52) 00239 NRF_ESB_TX_POWER_3DBM = RADIO_TXPOWER_TXPOWER_Pos3dBm, /**< 3 dBm radio transmit power. */ 00240 #endif 00241 NRF_ESB_TX_POWER_0DBM = RADIO_TXPOWER_TXPOWER_0dBm, /**< 0 dBm radio transmit power. */ 00242 NRF_ESB_TX_POWER_NEG4DBM = RADIO_TXPOWER_TXPOWER_Neg4dBm, /**< -4 dBm radio transmit power. */ 00243 NRF_ESB_TX_POWER_NEG8DBM = RADIO_TXPOWER_TXPOWER_Neg8dBm, /**< -8 dBm radio transmit power. */ 00244 NRF_ESB_TX_POWER_NEG12DBM = RADIO_TXPOWER_TXPOWER_Neg12dBm, /**< -12 dBm radio transmit power. */ 00245 NRF_ESB_TX_POWER_NEG16DBM = RADIO_TXPOWER_TXPOWER_Neg16dBm, /**< -16 dBm radio transmit power. */ 00246 NRF_ESB_TX_POWER_NEG20DBM = RADIO_TXPOWER_TXPOWER_Neg20dBm, /**< -20 dBm radio transmit power. */ 00247 NRF_ESB_TX_POWER_NEG30DBM = RADIO_TXPOWER_TXPOWER_Neg30dBm /**< -30 dBm radio transmit power. */ 00248 } nrf_esb_tx_power_t; 00249 00250 00251 /**@brief Enhanced ShockBurst transmission modes. */ 00252 typedef enum { 00253 NRF_ESB_TXMODE_AUTO, /**< Automatic TX mode: When the TX FIFO contains packets and the radio is idle, packets are sent automatically. */ 00254 NRF_ESB_TXMODE_MANUAL, /**< Manual TX mode: Packets are not sent until @ref nrf_esb_start_tx is called. This mode can be used to ensure consistent packet timing. */ 00255 NRF_ESB_TXMODE_MANUAL_START /**< Manual start TX mode: Packets are not sent until @ref nrf_esb_start_tx is called. Then, transmission continues automatically until the TX FIFO is empty. */ 00256 } nrf_esb_tx_mode_t; 00257 00258 00259 /**@brief Enhanced ShockBurst event IDs used to indicate the type of the event. */ 00260 typedef enum 00261 { 00262 NRF_ESB_EVENT_TX_SUCCESS, /**< Event triggered on TX success. */ 00263 NRF_ESB_EVENT_TX_FAILED, /**< Event triggered on TX failure. */ 00264 NRF_ESB_EVENT_RX_RECEIVED /**< Event triggered on RX received. */ 00265 } nrf_esb_evt_id_t; 00266 00267 00268 /**@brief Enhanced ShockBurst payload. 00269 * 00270 * @details The payload is used both for transmissions and for acknowledging a 00271 * received packet with a payload. 00272 */ 00273 typedef struct 00274 { 00275 uint8_t length; //!< Length of the packet (maximum value is @ref NRF_ESB_MAX_PAYLOAD_LENGTH). 00276 uint8_t pipe; //!< Pipe used for this payload. 00277 int8_t rssi; //!< RSSI for the received packet. 00278 uint8_t noack; //!< Flag indicating that this packet will not be acknowledgement. 00279 uint8_t pid; //!< PID assigned during communication. 00280 uint8_t data[NRF_ESB_MAX_PAYLOAD_LENGTH]; //!< The payload data. 00281 } nrf_esb_payload_t; 00282 00283 00284 /**@brief Enhanced ShockBurst event. */ 00285 typedef struct 00286 { 00287 nrf_esb_evt_id_t evt_id; //!< Enhanced ShockBurst event ID. 00288 uint32_t tx_attempts; //!< Number of TX retransmission attempts. 00289 } nrf_esb_evt_t; 00290 00291 00292 /**@brief Definition of the event handler for the module. */ 00293 typedef void (* nrf_esb_event_handler_t)(nrf_esb_evt_t const * p_event); 00294 00295 00296 /**@brief Main configuration structure for the module. */ 00297 typedef struct 00298 { 00299 nrf_esb_protocol_t protocol; //!< Enhanced ShockBurst protocol. 00300 nrf_esb_mode_t mode; //!< Enhanced ShockBurst mode. 00301 nrf_esb_event_handler_t event_handler; //!< Enhanced ShockBurst event handler. 00302 00303 // General RF parameters 00304 nrf_esb_bitrate_t bitrate; //!< Enhanced ShockBurst bitrate mode. 00305 nrf_esb_crc_t crc; //!< Enhanced ShockBurst CRC mode. 00306 00307 nrf_esb_tx_power_t tx_output_power; //!< Enhanced ShockBurst radio transmission power mode. 00308 00309 uint16_t retransmit_delay; //!< The delay between each retransmission of unacknowledged packets. 00310 uint16_t retransmit_count; //!< The number of retransmission attempts before transmission fail. 00311 00312 // Control settings 00313 nrf_esb_tx_mode_t tx_mode; //!< Enhanced ShockBurst transmission mode. 00314 00315 uint8_t radio_irq_priority; //!< nRF radio interrupt priority. 00316 uint8_t event_irq_priority; //!< ESB event interrupt priority. 00317 uint8_t payload_length; //!< Length of the payload (maximum length depends on the platforms that are used on each side). 00318 00319 bool selective_auto_ack; //!< Enable or disable selective auto acknowledgement. 00320 } nrf_esb_config_t; 00321 00322 00323 /**@brief Function for initializing the Enhanced ShockBurst module. 00324 * 00325 * @param p_config Parameters for initializing the module. 00326 * 00327 * @retval NRF_SUCCESS If initialization was successful. 00328 * @retval NRF_ERROR_NULL If the @p p_config argument was NULL. 00329 * @retval NRF_ERROR_BUSY If the function failed because the radio is busy. 00330 */ 00331 uint32_t nrf_esb_init(nrf_esb_config_t const * p_config); 00332 00333 00334 /**@brief Function for suspending the Enhanced ShockBurst module. 00335 * 00336 * Calling this function stops ongoing communications without changing the queues. 00337 * 00338 * @retval NRF_SUCCESS If Enhanced ShockBurst was suspended. 00339 * @retval NRF_ERROR_BUSY If the function failed because the radio is busy. 00340 */ 00341 uint32_t nrf_esb_suspend(void); 00342 00343 00344 /**@brief Function for disabling the Enhanced ShockBurst module. 00345 * 00346 * Calling this function disables the Enhanced ShockBurst module immediately. 00347 * Doing so might stop ongoing communications. 00348 * 00349 * @note All queues are flushed by this function. 00350 * 00351 * @retval NRF_SUCCESS If Enhanced ShockBurst was disabled. 00352 */ 00353 uint32_t nrf_esb_disable(void); 00354 00355 00356 /**@brief Function for checking if the Enhanced ShockBurst module is idle. 00357 * 00358 * @retval true If the module is idle. 00359 * @retval false If the module is busy. 00360 */ 00361 bool nrf_esb_is_idle(void); 00362 00363 00364 /**@brief Function for writing a payload for transmission or acknowledgement. 00365 * 00366 * This function writes a payload that is added to the queue. When the module is in PTX mode, the 00367 * payload is queued for a regular transmission. When the module is in PRX mode, the payload 00368 * is queued for when a packet is received that requires an acknowledgement with payload. 00369 * 00370 * @param[in] p_payload Pointer to the structure that contains information and state of the payload. 00371 * 00372 * @retval NRF_SUCCESS If the payload was successfully queued for writing. 00373 * @retval NRF_ERROR_NULL If the required parameter was NULL. 00374 * @retval NRF_INVALID_STATE If the module is not initialized. 00375 * @retval NRF_ERROR_NOT_SUPPORTED If @p p_payload->noack was false, but selective acknowledgement is not enabled. 00376 * @retval NRF_ERROR_NO_MEM If the TX FIFO is full. 00377 * @retval NRF_ERROR_INVALID_LENGTH If the payload length was invalid (zero or larger than the allowed maximum). 00378 */ 00379 uint32_t nrf_esb_write_payload(nrf_esb_payload_t const * p_payload); 00380 00381 00382 /**@brief Function for reading an RX payload. 00383 * 00384 * @param[in,out] p_payload Pointer to the structure that contains information and state of the payload. 00385 * 00386 * @retval NRF_SUCCESS If the data was read successfully. 00387 * @retval NRF_ERROR_NULL If the required parameter was NULL. 00388 * @retval NRF_INVALID_STATE If the module is not initialized. 00389 */ 00390 uint32_t nrf_esb_read_rx_payload(nrf_esb_payload_t * p_payload); 00391 00392 00393 /**@brief Function for starting transmission. 00394 * 00395 * @retval NRF_SUCCESS If the TX started successfully. 00396 * @retval NRF_ERROR_BUFFER_EMPTY If the TX did not start because the FIFO buffer is empty. 00397 * @retval NRF_ERROR_BUSY If the function failed because the radio is busy. 00398 */ 00399 uint32_t nrf_esb_start_tx(void); 00400 00401 00402 /**@brief Function for starting to transmit data from the FIFO buffer. 00403 * 00404 * @retval NRF_SUCCESS If the transmission was started successfully. 00405 * @retval NRF_ERROR_BUSY If the function failed because the radio is busy. 00406 */ 00407 uint32_t nrf_esb_start_rx(void); 00408 00409 00410 /** @brief Function for stopping data reception. 00411 * 00412 * @retval NRF_SUCCESS If data reception was stopped successfully. 00413 * @retval NRF_ESB_ERROR_NOT_IN_RX_MODE If the function failed because the module is not in RX mode. 00414 */ 00415 uint32_t nrf_esb_stop_rx(void); 00416 00417 00418 /**@brief Function for removing remaining items from the TX buffer. 00419 * 00420 * This function clears the TX FIFO buffer. 00421 * 00422 * @retval NRF_SUCCESS If pending items in the TX buffer were successfully cleared. 00423 * @retval NRF_INVALID_STATE If the module is not initialized. 00424 */ 00425 uint32_t nrf_esb_flush_tx(void); 00426 00427 00428 /**@brief Function for removing the first item from the TX buffer. 00429 * 00430 * @retval NRF_SUCCESS If the operation completed successfully. 00431 * @retval NRF_INVALID_STATE If the module is not initialized. 00432 * @retval NRF_ERROR_BUFFER_EMPTY If there are no items in the queue to remove. 00433 */ 00434 uint32_t nrf_esb_pop_tx(void); 00435 00436 00437 /**@brief Function for removing remaining items from the RX buffer. 00438 * 00439 * @retval NRF_SUCCESS If the pending items in the RX buffer were successfully cleared. 00440 * @retval NRF_INVALID_STATE If the module is not initialized. 00441 */ 00442 uint32_t nrf_esb_flush_rx(void); 00443 00444 00445 /**@brief Function for setting the length of the address. 00446 * 00447 * @param[in] length Length of the ESB address (in bytes). 00448 * 00449 * @retval NRF_SUCCESS If the address length was set successfully. 00450 * @retval NRF_ERROR_INVALID_PARAM If the address length was invalid. 00451 * @retval NRF_ERROR_BUSY If the function failed because the radio is busy. 00452 */ 00453 uint32_t nrf_esb_set_address_length(uint8_t length); 00454 00455 00456 /**@brief Function for setting the base address for pipe 0. 00457 * 00458 * @param[in] p_addr Pointer to the address data. 00459 * 00460 * @retval NRF_SUCCESS If the base address was set successfully. 00461 * @retval NRF_ERROR_BUSY If the function failed because the radio is busy. 00462 * @retval NRF_ERROR_INVALID_PARAM If the function failed because the address given was too close to a zero address. 00463 * @retval NRF_ERROR_NULL If the required parameter was NULL. 00464 */ 00465 uint32_t nrf_esb_set_base_address_0(uint8_t const * p_addr); 00466 00467 00468 /**@brief Function for setting the base address for pipe 1 to pipe 7. 00469 * 00470 * @param[in] p_addr Pointer to the address data. 00471 * 00472 * @retval NRF_SUCCESS If the base address was set successfully. 00473 * @retval NRF_ERROR_BUSY If the function failed because the radio is busy. 00474 * @retval NRF_ERROR_INVALID_PARAM If the function failed because the address given was too close to a zero address. 00475 * @retval NRF_ERROR_NULL If the required parameter was NULL. 00476 */ 00477 uint32_t nrf_esb_set_base_address_1(uint8_t const * p_addr); 00478 00479 00480 /**@brief Function for setting the number of pipes and the pipe prefix addresses. 00481 * 00482 * This function configures the number of available pipes, enables the pipes, 00483 * and sets their prefix addresses. 00484 * 00485 * @param[in] p_prefixes Pointer to a char array that contains the prefix for each pipe. 00486 * @param[in] num_pipes Number of pipes. 00487 * 00488 * @retval NRF_SUCCESS If the prefix addresses were set successfully. 00489 * @retval NRF_ERROR_BUSY If the function failed because the radio is busy. 00490 * @retval NRF_ERROR_NULL If a required parameter was NULL. 00491 * @retval NRF_ERROR_INVALID_PARAM If an invalid number of pipes was given or if the address given was too close to a zero address. 00492 */ 00493 uint32_t nrf_esb_set_prefixes(uint8_t const * p_prefixes, uint8_t num_pipes); 00494 00495 00496 /**@brief Function for enabling pipes. 00497 * 00498 * The @p enable_mask parameter must contain the same number of pipes as has been configured 00499 * with @ref nrf_esb_set_prefixes. 00500 * 00501 * @param enable_mask Bitfield mask to enable or disable pipes. Setting a bit to 00502 * 0 disables the pipe. Setting a bit to 1 enables the pipe. 00503 * 00504 * @retval NRF_SUCCESS If the pipes were enabled and disabled successfully. 00505 * @retval NRF_ERROR_BUSY If the function failed because the radio is busy. 00506 * @retval NRF_ERROR_INVALID_PARAM If the function failed because the address given was too close to a zero address. 00507 */ 00508 uint32_t nrf_esb_enable_pipes(uint8_t enable_mask); 00509 00510 00511 /**@brief Function for updating the prefix for a pipe. 00512 * 00513 * @param pipe Pipe for which to set the prefix. 00514 * @param prefix Prefix to set for the pipe. 00515 * 00516 * @retval NRF_SUCCESS If the operation completed successfully. 00517 * @retval NRF_ERROR_BUSY If the function failed because the radio is busy. 00518 * @retval NRF_ERROR_INVALID_PARAM If the given pipe number was invalid or if the address given was too close to a zero address. 00519 */ 00520 uint32_t nrf_esb_update_prefix(uint8_t pipe, uint8_t prefix); 00521 00522 00523 /** @brief Function for setting the channel to use for the radio. 00524 * 00525 * The module must be in an idle state to call this function. As a PTX, the 00526 * application must wait for an idle state and as a PRX, the application must stop RX 00527 * before changing the channel. After changing the channel, operation can be resumed. 00528 * 00529 * @param[in] channel Channel to use for radio. 00530 * 00531 * @retval NRF_SUCCESS If the operation completed successfully. 00532 * @retval NRF_INVALID_STATE If the module is not initialized. 00533 * @retval NRF_ERROR_BUSY If the module was not in idle state. 00534 * @retval NRF_ERROR_INVALID_PARAM If the channel is invalid (larger than 100). 00535 */ 00536 uint32_t nrf_esb_set_rf_channel(uint32_t channel); 00537 00538 00539 /**@brief Function for getting the current radio channel. 00540 * 00541 * @param[in, out] p_channel Pointer to the channel data. 00542 * 00543 * @retval NRF_SUCCESS If the operation completed successfully. 00544 * @retval NRF_ERROR_NULL If the required parameter was NULL. 00545 */ 00546 uint32_t nrf_esb_get_rf_channel(uint32_t * p_channel); 00547 00548 00549 /**@brief Function for setting the radio output power. 00550 * 00551 * @param[in] tx_output_power Output power. 00552 * 00553 * @retval NRF_SUCCESS If the operation completed successfully. 00554 * @retval NRF_ERROR_BUSY If the function failed because the radio is busy. 00555 */ 00556 uint32_t nrf_esb_set_tx_power(nrf_esb_tx_power_t tx_output_power); 00557 00558 00559 /**@brief Function for setting the packet retransmit delay. 00560 * 00561 * @param[in] delay Delay between retransmissions. 00562 * 00563 * @retval NRF_SUCCESS If the operation completed successfully. 00564 * @retval NRF_ERROR_BUSY If the function failed because the radio is busy. 00565 */ 00566 uint32_t nrf_esb_set_retransmit_delay(uint16_t delay); 00567 00568 00569 /**@brief Function for setting the number of retransmission attempts. 00570 * 00571 * @param[in] count Number of retransmissions. 00572 * 00573 * @retval NRF_SUCCESS If the operation completed successfully. 00574 * @retval NRF_ERROR_BUSY If the function failed because the radio is busy. 00575 */ 00576 uint32_t nrf_esb_set_retransmit_count(uint16_t count); 00577 00578 00579 /**@brief Function for setting the radio bitrate. 00580 * 00581 * @param[in] bitrate Radio bitrate. 00582 * 00583 * @retval NRF_SUCCESS If the operation completed successfully. 00584 * @retval NRF_ERROR_BUSY If the function failed because the radio is busy. 00585 */ 00586 uint32_t nrf_esb_set_bitrate(nrf_esb_bitrate_t bitrate); 00587 00588 00589 /**@brief Function for reusing a packet ID for a specific pipe. 00590 * 00591 * The ESB protocol uses a 2-bit sequence number (packet ID) to identify 00592 * retransmitted packets. By default, the packet ID is incremented for every 00593 * uploaded packet. Use this function to prevent this and send two different 00594 * packets with the same packet ID. 00595 * 00596 * @param[in] pipe Pipe. 00597 * 00598 * @retval NRF_SUCCESS If the operation completed successfully. 00599 * @retval NRF_ERROR_BUSY If the function failed because the radio is busy. 00600 */ 00601 uint32_t nrf_esb_reuse_pid(uint8_t pipe); 00602 00603 /** @} */ 00604 00605 #ifdef __cplusplus 00606 } 00607 #endif 00608 00609 #endif // NRF_ESB
Generated on Sun Jul 17 2022 00:47:52 by 1.7.2