esb.h

Go to the documentation of this file.

/*
 * Copyright (c) 2018 Nordic Semiconductor ASA
 *
 * SPDX-License-Identifier: LicenseRef-Nordic-5-Clause
 */
 
#ifndef __ESB_H
#define __ESB_H
 
#include <stdbool.h>
#include <errno.h>
 
#include <nrfx.h>
#include <hal/nrf_radio.h>
 
#include <zephyr/sys/util.h>
#include <zephyr/types.h>
 
#ifdef __cplusplus
extern "C" {
#endif
 
#define ESB_DEFAULT_CONFIG                                                     \
        {                                                                      \
                .protocol = ESB_PROTOCOL_ESB_DPL,                              \
                .mode = ESB_MODE_PTX,                                          \
                .event_handler = 0,                                            \
                .bitrate = ESB_BITRATE_2MBPS,                                  \
                .crc = ESB_CRC_16BIT,                                          \
                .tx_output_power = 0,                                          \
                .retransmit_delay = 600,                                       \
                .retransmit_count = 3,                                         \
                .tx_mode = ESB_TXMODE_AUTO,                                    \
                .payload_length = 32,                                          \
                .selective_auto_ack = false,                                   \
                .use_fast_ramp_up = false                                      \
        }
 
#define ESB_LEGACY_CONFIG                                                      \
        {                                                                      \
                .protocol = ESB_PROTOCOL_ESB,                                  \
                .mode = ESB_MODE_PTX,                                          \
                .event_handler = 0,                                            \
                .bitrate = ESB_BITRATE_2MBPS,                                  \
                .crc = ESB_CRC_8BIT,                                           \
                .tx_output_power = 0,                                          \
                .retransmit_delay = 600,                                       \
                .retransmit_count = 3,                                         \
                .tx_mode = ESB_TXMODE_AUTO,                                    \
                .payload_length = 32,                                          \
                .selective_auto_ack = false,                                   \
                .use_fast_ramp_up = false                                      \
        }
 
#define ESB_CREATE_PAYLOAD(_pipe, ...)                                         \
        {                                                                      \
                .pipe = _pipe,                                                 \
                .length = NUM_VA_ARGS_LESS_1(_pipe, __VA_ARGS__),              \
                .data = {                                                      \
                        __VA_ARGS__                                            \
                }                                                              \
        }
 
enum esb_protocol {
        ESB_PROTOCOL_ESB,       
        ESB_PROTOCOL_ESB_DPL    
};
 
enum esb_mode {
        ESB_MODE_PTX,           
        ESB_MODE_PRX,           
        ESB_MODE_MONITOR        
};
 
enum esb_bitrate {
        ESB_BITRATE_1MBPS = NRF_RADIO_MODE_NRF_1MBIT,
        ESB_BITRATE_2MBPS = NRF_RADIO_MODE_NRF_2MBIT,
 
#if defined(RADIO_MODE_MODE_Nrf_250Kbit) || defined(__DOXYGEN__)
        ESB_BITRATE_250KBPS = NRF_RADIO_MODE_NRF_250KBIT,
#endif /* defined(RADIO_MODE_MODE_Nrf_250Kbit) || defined(__DOXYGEN__) */
 
        ESB_BITRATE_1MBPS_BLE = NRF_RADIO_MODE_BLE_1MBIT,
 
#if defined(RADIO_MODE_MODE_Ble_2Mbit) || defined(__DOXYGEN__)
        ESB_BITRATE_2MBPS_BLE = NRF_RADIO_MODE_BLE_2MBIT,
#endif /* defined(RADIO_MODE_MODE_Ble_2Mbit) || defined(__DOXYGEN__) */
 
#if defined(RADIO_MODE_MODE_Nrf_4Mbit_0BT6) || defined(__DOXYGEN__)
        ESB_BITRATE_4MBPS = NRF_RADIO_MODE_NRF_4MBIT_BT_0_6,
#endif /* defined(RADIO_MODE_MODE_Nrf_4Mbit_0BT6) || defined(__DOXYGEN__) */
};
 
enum esb_crc {
        ESB_CRC_16BIT = RADIO_CRCCNF_LEN_Two,   
        ESB_CRC_8BIT = RADIO_CRCCNF_LEN_One,    
        ESB_CRC_OFF = RADIO_CRCCNF_LEN_Disabled 
};
 
enum esb_tx_power {
#if defined(RADIO_TXPOWER_TXPOWER_Pos10dBm) || defined(__DOXYGEN__)
        ESB_TX_POWER_10DBM = RADIO_TXPOWER_TXPOWER_Pos10dBm,
#endif
#if defined(RADIO_TXPOWER_TXPOWER_Pos9dBm) || defined(__DOXYGEN__)
        ESB_TX_POWER_9DBM = RADIO_TXPOWER_TXPOWER_Pos9dBm,
#endif
#if defined(RADIO_TXPOWER_TXPOWER_Pos8dBm) || defined(__DOXYGEN__)
        ESB_TX_POWER_8DBM = RADIO_TXPOWER_TXPOWER_Pos8dBm,
#endif
#if defined(RADIO_TXPOWER_TXPOWER_Pos7dBm) || defined(__DOXYGEN__)
        ESB_TX_POWER_7DBM = RADIO_TXPOWER_TXPOWER_Pos7dBm,
#endif
#if defined(RADIO_TXPOWER_TXPOWER_Pos6dBm) || defined(__DOXYGEN__)
        ESB_TX_POWER_6DBM = RADIO_TXPOWER_TXPOWER_Pos6dBm,
#endif
#if defined(RADIO_TXPOWER_TXPOWER_Pos5dBm) || defined(__DOXYGEN__)
        ESB_TX_POWER_5DBM = RADIO_TXPOWER_TXPOWER_Pos5dBm,
#endif
#if defined(RADIO_TXPOWER_TXPOWER_Pos4dBm) || defined(__DOXYGEN__)
        ESB_TX_POWER_4DBM = RADIO_TXPOWER_TXPOWER_Pos4dBm,
#endif
#if defined(RADIO_TXPOWER_TXPOWER_Pos3dBm) || defined(__DOXYGEN__)
        ESB_TX_POWER_3DBM = RADIO_TXPOWER_TXPOWER_Pos3dBm,
#endif
#if defined(RADIO_TXPOWER_TXPOWER_Pos2dBm) || defined(__DOXYGEN__)
        ESB_TX_POWER_2DBM = RADIO_TXPOWER_TXPOWER_Pos2dBm,
#endif
#if defined(RADIO_TXPOWER_TXPOWER_Pos1dBm) || defined(__DOXYGEN__)
        ESB_TX_POWER_1DBM = RADIO_TXPOWER_TXPOWER_Pos1dBm,
#endif
#if defined(RADIO_TXPOWER_TXPOWER_0dBm) || defined(__DOXYGEN__)
        ESB_TX_POWER_0DBM = RADIO_TXPOWER_TXPOWER_0dBm,
#endif
#if defined(RADIO_TXPOWER_TXPOWER_Neg1dBm) || defined(__DOXYGEN__)
        ESB_TX_POWER_NEG1DBM = RADIO_TXPOWER_TXPOWER_Neg1dBm,
#endif
#if defined(RADIO_TXPOWER_TXPOWER_Neg2dBm) || defined(__DOXYGEN__)
        ESB_TX_POWER_NEG2DBM = RADIO_TXPOWER_TXPOWER_Neg2dBm,
#endif
#if defined(RADIO_TXPOWER_TXPOWER_Neg3dBm) || defined(__DOXYGEN__)
        ESB_TX_POWER_NEG3DBM = RADIO_TXPOWER_TXPOWER_Neg3dBm,
#endif
#if defined(RADIO_TXPOWER_TXPOWER_Neg4dBm) || defined(__DOXYGEN__)
        ESB_TX_POWER_NEG4DBM = RADIO_TXPOWER_TXPOWER_Neg4dBm,
#endif
#if defined(RADIO_TXPOWER_TXPOWER_Neg5dBm) || defined(__DOXYGEN__)
        ESB_TX_POWER_NEG5DBM = RADIO_TXPOWER_TXPOWER_Neg5dBm,
#endif
#if defined(RADIO_TXPOWER_TXPOWER_Neg6dBm) || defined(__DOXYGEN__)
        ESB_TX_POWER_NEG6DBM = RADIO_TXPOWER_TXPOWER_Neg6dBm,
#endif
#if defined(RADIO_TXPOWER_TXPOWER_Neg7dBm) || defined(__DOXYGEN__)
        ESB_TX_POWER_NEG7DBM = RADIO_TXPOWER_TXPOWER_Neg7dBm,
#endif
#if defined(RADIO_TXPOWER_TXPOWER_Neg8dBm) || defined(__DOXYGEN__)
        ESB_TX_POWER_NEG8DBM = RADIO_TXPOWER_TXPOWER_Neg8dBm,
#endif
#if defined(RADIO_TXPOWER_TXPOWER_Neg9dBm) || defined(__DOXYGEN__)
        ESB_TX_POWER_NEG9DBM = RADIO_TXPOWER_TXPOWER_Neg9dBm,
#endif
#if defined(RADIO_TXPOWER_TXPOWER_Neg10dBm) || defined(__DOXYGEN__)
        ESB_TX_POWER_NEG10DBM = RADIO_TXPOWER_TXPOWER_Neg10dBm,
#endif
#if defined(RADIO_TXPOWER_TXPOWER_Neg12dBm) || defined(__DOXYGEN__)
        ESB_TX_POWER_NEG12DBM = RADIO_TXPOWER_TXPOWER_Neg12dBm,
#endif
#if defined(RADIO_TXPOWER_TXPOWER_Neg14dBm) || defined(__DOXYGEN__)
        ESB_TX_POWER_NEG14DBM = RADIO_TXPOWER_TXPOWER_Neg14dBm,
#endif
#if defined(RADIO_TXPOWER_TXPOWER_Neg16dBm) || defined(__DOXYGEN__)
        ESB_TX_POWER_NEG16DBM = RADIO_TXPOWER_TXPOWER_Neg16dBm,
#endif
#if defined(RADIO_TXPOWER_TXPOWER_Neg20dBm) || defined(__DOXYGEN__)
        ESB_TX_POWER_NEG20DBM = RADIO_TXPOWER_TXPOWER_Neg20dBm,
#endif
#if defined(RADIO_TXPOWER_TXPOWER_Neg26dBm) || defined(__DOXYGEN__)
        ESB_TX_POWER_NEG26DBM = RADIO_TXPOWER_TXPOWER_Neg26dBm,
#endif
#if defined(RADIO_TXPOWER_TXPOWER_Neg30dBm) || defined(__DOXYGEN__)
        ESB_TX_POWER_NEG30DBM = RADIO_TXPOWER_TXPOWER_Neg30dBm,
#endif
#if defined(RADIO_TXPOWER_TXPOWER_Neg40dBm) || defined(__DOXYGEN__)
        ESB_TX_POWER_NEG40DBM = RADIO_TXPOWER_TXPOWER_Neg40dBm,
#endif
#if defined(RADIO_TXPOWER_TXPOWER_Neg46dBm) || defined(__DOXYGEN__)
        ESB_TX_POWER_NEG46DBM = RADIO_TXPOWER_TXPOWER_Neg46dBm,
#endif
#if defined(RADIO_TXPOWER_TXPOWER_Neg70dBm) || defined(__DOXYGEN__)
        ESB_TX_POWER_NEG70DBM = RADIO_TXPOWER_TXPOWER_Neg70dBm,
#endif
};
 
enum esb_tx_mode {
        ESB_TXMODE_AUTO,
        ESB_TXMODE_MANUAL,
        ESB_TXMODE_MANUAL_START
};
 
enum esb_evt_id {
        ESB_EVENT_TX_SUCCESS,      
        ESB_EVENT_TX_FAILED,       
        ESB_EVENT_RX_RECEIVED,     
#if IS_ENABLED(CONFIG_ESB_MPSL_TIMESLOT) || defined(__DOXYGEN__)
        ESB_EVENT_TIMESLOT_FAILED, 
#endif
};
 
struct esb_payload {
        uint8_t length; 
        uint8_t pipe;   
        int8_t rssi;   
        uint8_t noack; 
        uint8_t pid;    
        uint8_t data[CONFIG_ESB_MAX_PAYLOAD_LENGTH]; 
};
 
struct esb_evt {
        enum esb_evt_id evt_id; 
        uint32_t tx_attempts;   
};
 
typedef void (*esb_event_handler)(const struct esb_evt *event);
 
struct esb_config {
        enum esb_protocol protocol;             
        enum esb_mode mode;                     
        esb_event_handler event_handler;        
        /* General RF parameters */
        enum esb_bitrate bitrate;               
        enum esb_crc crc;                       
        int8_t tx_output_power;                 
        uint16_t retransmit_delay; 
        uint16_t retransmit_count; 
        /* Control settings */
        enum esb_tx_mode tx_mode;       
        uint8_t payload_length; 
        bool selective_auto_ack; 
        bool use_fast_ramp_up; 
};
 
int esb_init(const struct esb_config *config);
 
int esb_suspend(void);
 
void esb_disable(void);
 
bool esb_is_idle(void);
 
int esb_write_payload(const struct esb_payload *payload);
 
int esb_read_rx_payload(struct esb_payload *payload);
 
int esb_start_tx(void);
 
int esb_start_rx(void);
 
int esb_stop_rx(void);
 
int esb_flush_tx(void);
 
int esb_pop_tx(void);
 
bool esb_tx_full(void);
 
int esb_flush_rx(void);
 
int esb_set_address_length(uint8_t length);
 
int esb_set_base_address_0(const uint8_t *addr);
 
int esb_set_base_address_1(const uint8_t *addr);
 
int esb_set_prefixes(const uint8_t *prefixes, uint8_t num_pipes);
 
int esb_enable_pipes(uint8_t enable_mask);
 
int esb_update_prefix(uint8_t pipe, uint8_t prefix);
 
int esb_set_rf_channel(uint32_t channel);
 
int esb_get_rf_channel(uint32_t *channel);
 
int esb_set_tx_power(int8_t tx_output_power);
 
int esb_set_retransmit_delay(uint16_t delay);
 
int esb_set_retransmit_count(uint16_t count);
 
int esb_set_bitrate(enum esb_bitrate bitrate);
 
int esb_reuse_pid(uint8_t pipe);
 
#ifdef __cplusplus
}
#endif
 
#endif /* ESB */