NRF52_esb

Embed: (wiki syntax)

« Back to documentation index

Show/hide line numbers nrf_esb.h Source File

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