nrf_gzll.h

Go to the documentation of this file.

/*
 * Copyright (c) 2021 Nordic Semiconductor ASA
 *
 * SPDX-License-Identifier: LicenseRef-Nordic-5-Clause
 */
 
#ifndef NRF_GZLL_H__
#define NRF_GZLL_H__
 
#include <stdbool.h>
#include "nrf.h"
#include "nrf_gzll_constants.h"
 
#ifdef __cplusplus
extern "C" {
#endif
 
 
typedef enum
{
    NRF_GZLL_MODE_DEVICE,  
    NRF_GZLL_MODE_HOST,    
    NRF_GZLL_MODE_SUSPEND, 
} nrf_gzll_mode_t;
 
typedef enum
{
    NRF_GZLL_DEVICE_CHANNEL_SELECTION_POLICY_USE_SUCCESSFUL, 
    NRF_GZLL_DEVICE_CHANNEL_SELECTION_POLICY_USE_CURRENT,    
} nrf_gzll_device_channel_selection_policy_t;
 
typedef enum
{
    NRF_GZLL_TX_POWER_8_DBM,   
    NRF_GZLL_TX_POWER_7_DBM,   
    NRF_GZLL_TX_POWER_6_DBM,   
    NRF_GZLL_TX_POWER_5_DBM,   
    NRF_GZLL_TX_POWER_4_DBM,   
    NRF_GZLL_TX_POWER_3_DBM,   
    NRF_GZLL_TX_POWER_2_DBM,   
    NRF_GZLL_TX_POWER_0_DBM,   
    NRF_GZLL_TX_POWER_N4_DBM,  
    NRF_GZLL_TX_POWER_N8_DBM,  
    NRF_GZLL_TX_POWER_N12_DBM, 
    NRF_GZLL_TX_POWER_N16_DBM, 
    NRF_GZLL_TX_POWER_N20_DBM, 
#ifdef NRF51
    NRF_GZLL_TX_POWER_N30_DBM  
#else
    NRF_GZLL_TX_POWER_N40_DBM  
#endif
} nrf_gzll_tx_power_t;
 
typedef enum
{
#ifdef NRF51
    NRF_GZLL_DATARATE_250KBIT   = 0, 
#endif
    NRF_GZLL_DATARATE_1MBIT     = 1, 
    NRF_GZLL_DATARATE_2MBIT     = 2, 
    NRF_GZLL_DATARATE_1MBIT_BLE = 3, 
    NRF_GZLL_DATARATE_2MBIT_BLE = 4  
} nrf_gzll_datarate_t;
 
typedef enum
{
    NRF_GZLL_XOSC_CTL_AUTO,  
    NRF_GZLL_XOSC_CTL_MANUAL 
} nrf_gzll_xosc_ctl_t;
 
typedef enum
{
    NRF_GZLL_ERROR_CODE_NO_ERROR                            =  0, 
    NRF_GZLL_ERROR_CODE_FAILED_TO_INITIALIZE                =  1, 
    NRF_GZLL_ERROR_CODE_ATTEMPTED_TO_CONFIGURE_WHEN_ENABLED =  2, 
    NRF_GZLL_ERROR_CODE_POINTER_IS_NULL                     =  3, 
    NRF_GZLL_ERROR_CODE_INVALID_PIPE                        =  4, 
    NRF_GZLL_ERROR_CODE_INVALID_MODE                        =  5, 
    NRF_GZLL_ERROR_CODE_INVALID_PAYLOAD_LENGTH              =  6, 
    NRF_GZLL_ERROR_CODE_INVALID_CHANNEL_TABLE_SIZE          =  7, 
    NRF_GZLL_ERROR_CODE_INSUFFICIENT_PACKETS_AVAILABLE      =  8, 
    NRF_GZLL_ERROR_CODE_ATTEMPTED_TO_ADD_TO_FULL_FIFO       =  9, 
    NRF_GZLL_ERROR_CODE_NO_SPACE_IN_RX_FIFO_FOR_ACK         = 10, 
    NRF_GZLL_ERROR_CODE_ATTEMPTED_TO_FETCH_FROM_EMPTY_FIFO  = 11, 
    NRF_GZLL_ERROR_CODE_ATTEMPTED_TO_FLUSH_WHEN_ENABLED     = 12, 
    NRF_GZLL_ERROR_CODE_INVALID_PARAMETER                   = 14, 
    NRF_GZLL_ERROR_CODE_INTERNAL_ASSERT_OCCURRED            = 15, 
    NRF_GZLL_ERROR_CODE_CALLBACK_NOT_IMPLEMENTED            = 16, 
    NRF_GZLL_ERROR_CODE_INVALID_ADDRESS                     = 17, 
    NRF_GZLL_ERROR_CODE_NUMBER_OF_ERROR_CODES               = 18, 
} nrf_gzll_error_code_t;
 
typedef struct
{
    bool     payload_received_in_ack;    
    uint16_t num_tx_attempts;            
    uint16_t num_channel_switches;       
    int8_t   rssi;                       
    uint8_t  rf_channel;                 
} nrf_gzll_device_tx_info_t;
 
 
typedef struct
{
    bool    packet_removed_from_tx_fifo; 
    int8_t  rssi;                        
    uint8_t rf_channel;                  
} nrf_gzll_host_rx_info_t;
 
 
typedef struct 
{
    uint32_t packets_num;                                             
    uint32_t timeouts_num;                                            
    uint32_t channel_timeouts[NRF_GZLL_CONST_MAX_CHANNEL_TABLE_SIZE]; 
    uint32_t channel_packets[NRF_GZLL_CONST_MAX_CHANNEL_TABLE_SIZE];  
} nrf_gzll_tx_statistics_t;
 
 
typedef void (*nrf_gzll_tx_timeout_callback)(uint32_t pipe, uint8_t rf_channel);
 
 
typedef void (*nrf_gzll_crc_failure_callback)(uint32_t pipe, uint8_t rf_channel);
 
 
typedef void (*nrf_gzll_tick_timer_expired_callback)(void);
 
 
#if defined(NRF52_SERIES) || defined(__SDK_DOXYGEN__)
typedef struct
{
    bool             pa_enabled;                                     
    bool             pa_active_high;                                 
    uint8_t          pa_gpio_pin;                                    
    uint8_t          pa_gpiote_channel;                              
    bool             lna_enabled;                                    
    bool             lna_active_high;                                
    uint8_t          lna_gpio_pin;                                   
    uint8_t          lna_gpiote_channel;                             
    NRF_TIMER_Type * timer;                                          
    uint8_t          ppi_channels[NRF_GZLL_PA_LNA_PPI_CHANNELS_NUM]; 
    uint8_t          ramp_up_time;                                   
} nrf_gzll_pa_lna_cfg_t;
#endif
 
/******************************************************************************/
/******************************************************************************/
 
bool nrf_gzll_init(nrf_gzll_mode_t mode);
 
bool nrf_gzll_enable(void);
 
void nrf_gzll_disable(void);
 
bool nrf_gzll_is_enabled(void);
 
/******************************************************************************/
/******************************************************************************/
 
void nrf_gzll_device_tx_success(uint32_t pipe, nrf_gzll_device_tx_info_t tx_info);
 
void nrf_gzll_device_tx_failed(uint32_t pipe, nrf_gzll_device_tx_info_t tx_info);
 
/******************************************************************************/
/******************************************************************************/
 
void nrf_gzll_host_rx_data_ready(uint32_t pipe, nrf_gzll_host_rx_info_t rx_info);
 
/******************************************************************************/
/******************************************************************************/
 
void nrf_gzll_disabled(void);
 
void nrf_gzll_mode_changed(void);
 
/******************************************************************************/
/******************************************************************************/
 
bool nrf_gzll_add_packet_to_tx_fifo(uint32_t pipe, uint8_t const * p_payload, uint32_t length);
 
bool nrf_gzll_fetch_packet_from_rx_fifo(uint32_t pipe, uint8_t * p_payload, uint32_t * p_length);
 
int32_t nrf_gzll_get_tx_fifo_packet_count(uint32_t pipe);
 
int32_t nrf_gzll_get_rx_fifo_packet_count(uint32_t pipe);
 
uint32_t nrf_gzll_get_total_allocated_packet_count(void);
 
bool nrf_gzll_ok_to_add_packet_to_tx_fifo(uint32_t pipe);
 
bool nrf_gzll_flush_tx_fifo(uint32_t pipe);
 
bool nrf_gzll_flush_rx_fifo(uint32_t pipe);
 
bool nrf_gzll_tx_statistics_enable(nrf_gzll_tx_statistics_t * p_statistics);
 
void nrf_gzll_tx_statistics_disable(void);
 
bool nrf_gzll_get_channel_timeouts(uint8_t channel_index, uint32_t *p_timeouts);
 
void nrf_gzll_reset_tx_statistics(void);
 
/******************************************************************************/
/******************************************************************************/
 
void nrf_gzll_tx_timeout_callback_register(nrf_gzll_tx_timeout_callback callback);
 
 
void nrf_gzll_crc_failure_callback_register(nrf_gzll_crc_failure_callback callback);
 
 
bool nrf_gzll_set_mode(nrf_gzll_mode_t mode);
 
nrf_gzll_mode_t nrf_gzll_get_mode(void);
 
bool nrf_gzll_set_base_address_0(uint32_t base_address);
 
uint32_t nrf_gzll_get_base_address_0(void);
 
bool nrf_gzll_set_base_address_1(uint32_t base_address);
 
uint32_t nrf_gzll_get_base_address_1(void);
 
bool nrf_gzll_set_address_prefix_byte(uint32_t pipe, uint8_t address_prefix_byte);
 
bool nrf_gzll_get_address_prefix_byte(uint32_t pipe, uint8_t * p_out_address_prefix_byte);
 
bool nrf_gzll_set_rx_pipes_enabled(uint32_t pipes);
 
uint32_t nrf_gzll_get_rx_pipes_enabled(void);
 
bool nrf_gzll_set_timeslot_period(uint32_t period_us);
 
uint32_t nrf_gzll_get_timeslot_period(void);
 
bool nrf_gzll_set_device_channel_selection_policy(nrf_gzll_device_channel_selection_policy_t policy);
 
nrf_gzll_device_channel_selection_policy_t nrf_gzll_get_device_channel_selection_policy(void);
 
bool nrf_gzll_set_timeslots_per_channel(uint32_t timeslots);
 
uint32_t nrf_gzll_get_timeslots_per_channel(void);
 
bool nrf_gzll_set_timeslots_per_channel_when_device_out_of_sync(uint32_t timeslots);
 
uint32_t nrf_gzll_get_timeslots_per_channel_when_device_out_of_sync(void);
 
bool nrf_gzll_set_sync_lifetime(uint32_t lifetime);
 
uint32_t nrf_gzll_get_sync_lifetime(void);
 
void nrf_gzll_set_max_tx_attempts(uint16_t max_tx_attempts);
 
uint16_t nrf_gzll_get_max_tx_attempts(void);
 
bool nrf_gzll_set_channel_table(uint8_t * p_channel_table, uint32_t size);
 
bool nrf_gzll_get_channel_table(uint8_t * p_channel_table, uint32_t * p_size);
 
uint32_t nrf_gzll_get_channel_table_size(void);
 
bool nrf_gzll_set_tx_power(nrf_gzll_tx_power_t tx_power);
 
nrf_gzll_tx_power_t nrf_gzll_get_tx_power(void);
 
bool nrf_gzll_set_datarate(nrf_gzll_datarate_t data_rate);
 
nrf_gzll_datarate_t nrf_gzll_get_datarate(void);
 
bool nrf_gzll_set_xosc_ctl(nrf_gzll_xosc_ctl_t xosc_ctl);
 
nrf_gzll_xosc_ctl_t nrf_gzll_get_xosc_ctl(void);
 
void nrf_gzll_set_auto_disable(uint32_t num_ticks);
 
#if defined(NRF52_SERIES) || defined(__SDK_DOXYGEN__)
bool nrf_gzll_set_pa_lna_cfg(nrf_gzll_pa_lna_cfg_t const * p_pa_lna_cfg);
#endif
 
uint32_t nrf_gzll_get_tick_count(void);
 
void nrf_gzll_clear_tick_count(void);
 
bool nrf_gzll_set_tick_timer(uint32_t num_ticks, nrf_gzll_tick_timer_expired_callback callback);
 
/******************************************************************************/
/******************************************************************************/
 
nrf_gzll_error_code_t nrf_gzll_get_error_code(void);
 
 
void nrf_gzll_reset_error_code(void);
 
#ifdef __cplusplus
}
#endif
 
#endif