xiaozhengsheng/HL-PDJ-1
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

初始版本

Browse Source
This commit is contained in:
xiaozhengsheng
2025-08-19 09:49:41 +08:00
parent 10f1ddf1c1
commit 6df0f7d96e
2974 changed files with 1712873 additions and 54 deletions
Download Patch File Download Diff File Expand all files Collapse all files

937
components/proprietary_rf/gzll/nrf_gzll.h Normal file
View File

@@ -0,0 +1,937 @@
/**
* Copyright (c) 2012 - 2020, Nordic Semiconductor ASA
*
* All rights reserved.
*
* Redistribution and use in source and binary forms, with or without modification,
* are permitted provided that the following conditions are met:
*
* 1. Redistributions of source code must retain the above copyright notice, this
* list of conditions and the following disclaimer.
*
* 2. Redistributions in binary form, except as embedded into a Nordic
* Semiconductor ASA integrated circuit in a product or a software update for
* such product, must reproduce the above copyright notice, this list of
* conditions and the following disclaimer in the documentation and/or other
* materials provided with the distribution.
*
* 3. Neither the name of Nordic Semiconductor ASA nor the names of its
* contributors may be used to endorse or promote products derived from this
* software without specific prior written permission.
*
* 4. This software, with or without modification, must only be used with a
* Nordic Semiconductor ASA integrated circuit.
*
* 5. Any software provided in binary form under this license must not be reverse
* engineered, decompiled, modified and/or disassembled.
*
* THIS SOFTWARE IS PROVIDED BY NORDIC SEMICONDUCTOR ASA "AS IS" AND ANY EXPRESS
* OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
* OF MERCHANTABILITY, NONINFRINGEMENT, AND FITNESS FOR A PARTICULAR PURPOSE ARE
* DISCLAIMED. IN NO EVENT SHALL NORDIC SEMICONDUCTOR ASA OR CONTRIBUTORS BE
* LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
* CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
* GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
* HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
* LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
* OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
*
*/
/**
* @file
* @brief Gazell Link Layer API.
*/
#ifndef NRF_GZLL_H__
#define NRF_GZLL_H__
#include <stdbool.h>
#include "nrf.h"
#include "nrf_gzll_constants.h"
#ifdef __cplusplus
extern "C" {
#endif
/**
* @defgroup gzll_02_api Gazell Link Layer
* @{
* @ingroup modules_01_gzll
* @brief Gazell Link Layer Application Programming Interface (API).
*/
/**
* @enum nrf_gzll_mode_t
* @brief Enumerator used for selecting Gazell mode.
*/
typedef enum
{
NRF_GZLL_MODE_DEVICE, ///< Device mode
NRF_GZLL_MODE_HOST, ///< Host mode
NRF_GZLL_MODE_SUSPEND, ///< Suspend mode ("disabled with timer running")
} nrf_gzll_mode_t;
/**
* @enum nrf_gzll_device_channel_selection_policy_t
* @brief Enumerator used for selecting Gazell Device channel
* selection policy.
*/
typedef enum
{
NRF_GZLL_DEVICE_CHANNEL_SELECTION_POLICY_USE_SUCCESSFUL, ///< Start on previous successful channel
NRF_GZLL_DEVICE_CHANNEL_SELECTION_POLICY_USE_CURRENT, ///< Start on channel currently monitored by Host
} nrf_gzll_device_channel_selection_policy_t;
/**
* @enum nrf_gzll_tx_power_t
* @brief Enumerator used for selecting the transmit (TX) power.
*/
typedef enum
{
NRF_GZLL_TX_POWER_4_DBM, ///< 4 dBm transmit power.
NRF_GZLL_TX_POWER_0_DBM, ///< 0 dBm transmit power.
NRF_GZLL_TX_POWER_N4_DBM, ///< -4 dBm transmit power.
NRF_GZLL_TX_POWER_N8_DBM, ///< -8 dBm transmit power.
NRF_GZLL_TX_POWER_N12_DBM, ///< -12 dBm transmit power.
NRF_GZLL_TX_POWER_N16_DBM, ///< -16 dBm transmit power.
NRF_GZLL_TX_POWER_N20_DBM ///< -20 dBm transmit power.
} nrf_gzll_tx_power_t;
/**
* @enum nrf_gzll_datarate_t
* @brief Enumerator used for selecting the radio datarate.
*/
typedef enum
{
#ifdef NRF51
NRF_GZLL_DATARATE_250KBIT = 0, ///< 250 Kbps datarate, available only for the nRF51.
#endif
NRF_GZLL_DATARATE_1MBIT = 1, ///< 1 Mbps datarate.
NRF_GZLL_DATARATE_2MBIT = 2 ///< 2 Mbps datarate.
} nrf_gzll_datarate_t;
/**
* @enum nrf_gzll_xosc_ctl_t
* @brief Enumerator used for specifying whether switching the
* external 16 MHz oscillator on/off shall be handled automatically
* inside Gazell or manually by the application.
*/
typedef enum
{
NRF_GZLL_XOSC_CTL_AUTO, ///< Switch XOSC on/off automatically
NRF_GZLL_XOSC_CTL_MANUAL ///< Switch XOSC on/off manually
} nrf_gzll_xosc_ctl_t;
/**
* @enum nrf_gzll_error_code_t
* @brief Enumerator used for error codes for Gazell API functions
*/
typedef enum
{
NRF_GZLL_ERROR_CODE_NO_ERROR = 0, ///< No error has been detected.
NRF_GZLL_ERROR_CODE_FAILED_TO_INITIALIZE = 1, ///< The function NRF_GZLL_init failed.
NRF_GZLL_ERROR_CODE_ATTEMPTED_TO_CONFIGURE_WHEN_ENABLED = 2, ///< A call to a configuration 'set' function was made while Gazell was enabled.
NRF_GZLL_ERROR_CODE_POINTER_IS_NULL = 3, ///< A null pointer was given as an input to a function.
NRF_GZLL_ERROR_CODE_INVALID_PIPE = 4, ///< An invalid pipe number was given as an input to a function.
NRF_GZLL_ERROR_CODE_INVALID_MODE = 5, ///< An invalid value for the nrf_gzll_mode_t enumerator was given as input to a function.
NRF_GZLL_ERROR_CODE_INVALID_PAYLOAD_LENGTH = 6, ///< An invalid payload length was given as an input to a function.
NRF_GZLL_ERROR_CODE_INVALID_CHANNEL_TABLE_SIZE = 7, ///< An invalid channel table size was given as an input to a function.
NRF_GZLL_ERROR_CODE_INSUFFICIENT_PACKETS_AVAILABLE = 8, ///< There are insufficient packets in the Gazell memory pool to successfully execute the operation.
NRF_GZLL_ERROR_CODE_ATTEMPTED_TO_ADD_TO_FULL_FIFO = 9, ///< There is insufficient space in the TX FIFO for the data packet.
NRF_GZLL_ERROR_CODE_NO_SPACE_IN_RX_FIFO_FOR_ACK = 10, ///< There is insufficient space in the RX FIFO for the ACK.
NRF_GZLL_ERROR_CODE_ATTEMPTED_TO_FETCH_FROM_EMPTY_FIFO = 11, ///< Attempted to fetch a packet from an empty FIFO. Use the functions nrf_gzll_get_tx_fifo_packet_count() or nrf_gzll_get_rx_fifo_packet_count()
NRF_GZLL_ERROR_CODE_ATTEMPTED_TO_FLUSH_WHEN_ENABLED = 12, ///< Attempted to fetch a packet from an empty FIFO. Use the functions nrf_gzll_get_tx_fifo_packet_count() or nrf_gzll_get_rx_fifo_packet_count()
NRF_GZLL_ERROR_CODE_INVALID_PARAMETER = 14, ///< Attempted to set a variable which was not valid.
NRF_GZLL_ERROR_CODE_INTERNAL_ASSERT_OCCURRED = 15, ///< An internal assert occurred.
NRF_GZLL_ERROR_CODE_CALLBACK_NOT_IMPLEMENTED = 16, ///< A callback was called but not implemented by the application.
NRF_GZLL_ERROR_CODE_INVALID_ADDRESS = 17, ///< Invalid pipe 0 address detected, see Anomaly 107 at nRF52832 errata document.
NRF_GZLL_ERROR_CODE_NUMBER_OF_ERROR_CODES = 18, ///< Number of possible error codes.
} nrf_gzll_error_code_t;
/**
* @struct nrf_gzll_device_tx_info_t;
* @brief Data structure containing information about the last packet
* transmission.
*/
typedef struct
{
bool payload_received_in_ack; ///< A payload was received in the ACK.
uint16_t num_tx_attempts; ///< Number of attempts used on previous Device packet transmission.
uint16_t num_channel_switches; ///< Number of channel switches needed during previous packet transmission.
int8_t rssi; ///< Received signal strength indicator in dBm. @sa nrf_gzll_enable_rssi().
uint8_t rf_channel; ///< Channel on which packet has been transmitted.
} nrf_gzll_device_tx_info_t;
/**
* @struct nrf_gzll_host_rx_info_t;
* @brief Data structure containing information about the last packet
* received.
*/
typedef struct
{
bool packet_removed_from_tx_fifo; ///< A payload was received in the ACK.
int8_t rssi; ///< Received signal strength indicator in dBm. @sa nrf_gzll_enable_rssi().
uint8_t rf_channel; ///< Channel on which packet has been received.
} nrf_gzll_host_rx_info_t;
typedef struct
{
uint32_t packets_num; ///< Number of succesfully transmitted packets
uint32_t timeouts_num; ///< Total timeouts number
uint32_t channel_timeouts[NRF_GZLL_CONST_MAX_CHANNEL_TABLE_SIZE]; ///< Transmission timeouts per channel
uint32_t channel_packets[NRF_GZLL_CONST_MAX_CHANNEL_TABLE_SIZE]; ///< Succesfully transmitted packets per channel
} nrf_gzll_tx_statistics_t;
/**< Transmission timeout callback function definition */
typedef void (*nrf_gzll_tx_timeout_callback)(uint32_t pipe, uint8_t rf_channel);
/**< Transmission CRC failure callback function definition */
typedef void (*nrf_gzll_crc_failure_callback)(uint32_t pipe, uint8_t rf_channel);
#if defined(NRF52_SERIES) || defined(__SDK_DOXYGEN__)
/**
* @brief Data structure holding external front
* end control configuration.
*/
typedef struct
{
bool pa_enabled; ///< Flag indicating if PA control is enabled.
bool pa_active_high; ///< Flag indicating if PA is active in high input state.
uint8_t pa_gpio_pin; ///< Number of output pin used for PA control.
uint8_t pa_gpiote_channel; ///< Number of GPIOTE channel used for PA control.
bool lna_enabled; ///< Flag indicating if LNA control is enabled.
bool lna_active_high; ///< Flag indicating if LNA is active in high input state.
uint8_t lna_gpio_pin; ///< Number of output pin used for LNA control.
uint8_t lna_gpiote_channel; ///< Number of GPIOTE channel used for LNA control.
NRF_TIMER_Type * timer; ///< Pointer to the TIMER instance.
uint8_t ppi_channels[NRF_GZLL_PA_LNA_PPI_CHANNELS_NUM]; ///< PPI channels used to control front end.
uint8_t ramp_up_time; ///< Determines how early should the PA/LNA be turned one before RADIO activity. Should be less than @ref NRF_GZLL_PA_LNA_MAX_RAMP_UP_TIME.
} nrf_gzll_pa_lna_cfg_t;
#endif
/******************************************************************************/
/** @name General API functions
* @{ */
/******************************************************************************/
/**
* @brief Initialize Gazell.
*
* @param mode The mode to initialize Gazell in.
*
* @retval true if Gazell initialized.
* @retval false if Gazell failed to initialize.
*/
bool nrf_gzll_init(nrf_gzll_mode_t mode);
/**
* @brief Enable Gazell.
*
* When enabled the behaviour described for the current Gazell Link Layer mode
* will apply.
*
* @retval false if nrf_gzll_init has not previously been called or invalid address
* has been set - see Anomaly 107 at nRF52832 errata document.
*/
bool nrf_gzll_enable(void);
/**
* @brief Disable Gazell.
*
* When calling this function the Gazell Link Layer will begin disabling,
* and will be fully disabled when Gazell calls nrf_gzll_disabled().
* If there are any pending notifications, or if any new notifications are
* being added to the internal notification queue while Gazell is disabling,
* these will be sent to the application before Gazell is fully disabled.
*
* After Gazell has been fully disabled, no more notifications will be sent to
* the application.
*/
void nrf_gzll_disable(void);
/** Check whether Gazell is enabled or disabled.
*
* @retval true If Gazell is enabled.
* @retval false If Gazell is disabled.
*/
bool nrf_gzll_is_enabled(void);
/** @} */
/******************************************************************************/
/** @name Device mode callback functions
* @{ */
/******************************************************************************/
/**
* @brief ACK received callback (Device mode only).
*
* This callback is made when the Device receives an ACK (acknowledgement)
* packet.
* @sa nrf_gzll_ack_payload_received.
*
* @param pipe is the pipe on which an ACK packet was received.
* @param tx_info struct used to indicate whether a payload was received in the
* ack, as well as the number of TX attempts and channel switches required.
*/
void nrf_gzll_device_tx_success(uint32_t pipe, nrf_gzll_device_tx_info_t tx_info);
/**
* @brief Transmission failed callback (Device mode only).
*
* This callback is made when a packet does not receive an ACK after
* nrf_gzll_max_retries is reached. The packet is deleted by Gazell.
*
* @param pipe is the pipe on which the transmission failed.
* @param tx_info struct used to indicate whether a payload was received
* in the ack, as well as RSSI and the number of TX attempts and
* channel switches required.
*/
void nrf_gzll_device_tx_failed(uint32_t pipe, nrf_gzll_device_tx_info_t tx_info);
/** @} */
/******************************************************************************/
/** @name Host mode callback functions
* @{ */
/******************************************************************************/
/**
* @brief Data packet received callback (Host mode only).
*
* This callback is made when a Host receives a data packet from a Device.
*
* @param pipe is the pipe on which the data packet was received.
* @param rx_info struct used to indicate whether a payload was removed from the
* pipe's TX FIFO, as well as RSSI.
*/
void nrf_gzll_host_rx_data_ready(uint32_t pipe, nrf_gzll_host_rx_info_t rx_info);
/** @} */
/******************************************************************************/
/** @name Callback functions for both Device and Host mode
* @{ */
/******************************************************************************/
/**
* @brief Disabled callback.
*
* This is called after Gazell enters the disabled state.
* There is no further CPU use by Gazell, the radio is disabled and the timer is
* powered down.
*/
void nrf_gzll_disabled(void);
/**
* @brief Mode changed callbackl.
*
* This function is called after the Gazell mode has been changed.
* This function can only be called when Gazell is enabled.
*/
void nrf_gzll_mode_changed(void);
/** @} */
/******************************************************************************/
/** @name Packet transmission and receiving functions
* @{ */
/******************************************************************************/
/**
* @brief Add a packet to the tail of the TX FIFO.
*
* In Device mode, the packet will be added.
* In Host mode, the payload will be piggybacked onto an ACK.
*
* @param pipe Pipe to which to add the payload. This value must be < NRF_GZLL_CONST_PIPE_COUNT.
* @param p_payload Pointer to the payload.
* @param length Number of bytes of the payload to transmit
* (0 to NRF_GZLL_CONST_MAX_PAYLOAD_LENGTH).
*
* @retval true if the packet was successfully added to the TX FIFO.
* @retval false if unsuccessful, check nrf_gzll_error_code_t for more information.
*/
bool nrf_gzll_add_packet_to_tx_fifo(uint32_t pipe, uint8_t * p_payload, uint32_t length);
/**
* @brief Fetch a packet from the head of the RX FIFO.
*
* @param pipe Pipe from which to fetch the payload. This value must be < NRF_GZLL_CONST_PIPE_COUNT.
* @param p_payload Pointer to copy the payload to.
* @param p_length Length must be at least as large as the the number of bytes
* in the received payload length.
*
* @retval true If the fetch was successful.
* @retval false If unsuccessful, check nrf_gzll_error_code_t for more information.
*/
bool nrf_gzll_fetch_packet_from_rx_fifo(uint32_t pipe, uint8_t * p_payload, uint32_t * p_length);
/**
* @brief Get the number of packets in the TX FIFO on a specific pipe.
*
* @param pipe The pipe for which to check. This value must be < NRF_GZLL_CONST_PIPE_COUNT.
*
* @retval >=0 The number of packets in the TX FIFO for the pipe.
* @retval -1 If the pipe number is invalid.
*/
int32_t nrf_gzll_get_tx_fifo_packet_count(uint32_t pipe);
/**
* @brief Get the number of packets in the RX FIFO on a specific pipe.
*
* @param pipe The pipe for which to check. This value must be < NRF_GZLL_CONST_PIPE_COUNT.
* @retval >=0 The number of packets in the RX FIFO for the pipe.
* @retval -1 If the pipe number is invalid.
*/
int32_t nrf_gzll_get_rx_fifo_packet_count(uint32_t pipe);
/**
* @brief Get the total number of packets residing in all TX and RX FIFOs.
*
* Can be used to check against NRF_GZLL_CONST_MAX_TOTAL_PACKETS to
* determine if there is free space in the memory pool for more packets.
*
* @return The number of packets residing in all TX and RX FIFOs.
*/
uint32_t nrf_gzll_get_total_allocated_packet_count(void);
/**
* @brief Check if adding a packet to a pipe's TX FIFO should be successful.
*
* Checks if there is another space in the pipe's TX and RX FIFOs
* as well as enough overall space in the packet pool.
*
* @param pipe The pip for which to check. This value must be < NRF_GZLL_CONST_PIPE_COUNT.
*
* @retval true If there is another space.
* @retval false If there is not enough space, or the pipe is invalid.
*/
bool nrf_gzll_ok_to_add_packet_to_tx_fifo(uint32_t pipe);
/**
* @brief Flush the RX FIFO for a specific pipe.
*
* Delete all the packets and free the memory of the TX FIFO for a
* specific pipe.
*
* Note that it is not allowed to flush a TX FIFO when
* Gazell is enabled.
*
* @param pipe is the pipe for which to flush. This value must be < NRF_GZLL_CONST_PIPE_COUNT.
* @retval true if the pipe was flushed.
* @retval false if the pipe was not flushed.
*/
bool nrf_gzll_flush_tx_fifo(uint32_t pipe);
/**
* @brief Flush the RX FIFO for a specific pipe.
*
* Delete all the packets and free the memory of the RX FIFO for a
* specific pipe.
*
* @param pipe is the pipe for which to flush. This value must be < NRF_GZLL_CONST_PIPE_COUNT.
* @retval true if the pipe was flushed.
* @retval false if the pipe was not flushed.
*/
bool nrf_gzll_flush_rx_fifo(uint32_t pipe);
/**
* @brief Function for enabling transmission statistics.
*
* @param p_statistics Pointer to the statistics structure.
*
* @return True if channel statistics has been enabled, false otherwise.
*/
bool nrf_gzll_tx_statistics_enable(nrf_gzll_tx_statistics_t * p_statistics);
/**
* @brief Function for disabling transmission statistics.
*/
void nrf_gzll_tx_statistics_disable(void);
/**
* @brief Function for obtaining number of transmission timeouts for specific channel.
*
* @param[in] channel_index Channel index in channel table.
* @param[out] p_timeouts Pointer for the result.
*
* @return True in case of success, false otherwise.
*/
bool nrf_gzll_get_channel_timeouts(uint8_t channel_index, uint32_t *p_timeouts);
/**
* @brief Function for clearing transmission statistic structure.
*/
void nrf_gzll_reset_tx_statistics(void);
/** @} */
/******************************************************************************/
/** @name Configuration functions
*
* Configuration 'set' functions may only be called while Gazell is disabled. The
* new parameter comes into effect when Gazell is enabled again.
*
* Configuration 'get' functions may be called at any time.
*
* @{ */
/******************************************************************************/
/**
* @brief Function for registering callback to be called on the transmission timeout.
*/
void nrf_gzll_tx_timeout_callback_register(nrf_gzll_tx_timeout_callback callback);
/**
* @brief Function for registering callback to be called on the packet CRC failure.
*/
void nrf_gzll_crc_failure_callback_register(nrf_gzll_crc_failure_callback callback);
/**
* @brief Set the mode.
*
* @param mode The mode to be used.
* See nrf_gzll_mode_t for a list of valid modes.
*
* It is allowed to change mode when Gazell is enabled. If the mode is
* being changed while Gazell is enabled, the mode will not change right away.
* In this case the callback function nrf_gzll_mode_changed() will be called
* after the mdoe has changed.
*
* @retval true If the parameter was set.
*/
bool nrf_gzll_set_mode(nrf_gzll_mode_t mode);
/**
* @brief Get function counterpart to nrf_gzll_set_mode().
*
* @return The current mode.
*/
nrf_gzll_mode_t nrf_gzll_get_mode(void);
/**
* @brief Set the base address for pipe 0.
*
* The full on-air address for each pipe is composed of a multi-byte base address
* prepended to a prefix byte.
*
* For packets to be received correctly, the most significant byte of
* the base address should not be an alternating sequence of 0s and 1s i.e.
* it should not be 0x55 or 0xAA.
*
* @param base_address The 4 byte base address. All bytes are used.
*
* @note Due to the nRF52 Anomaly 107, pipe 0 address should not have
* both prefix and two LSB of base address set to 0.
*
* @retval true If the parameter was set.
* @return false If Gazell was enabled.
*/
bool nrf_gzll_set_base_address_0(uint32_t base_address);
/**
* @brief Get function counterpart to nrf_gzll_set_base_address_0().
*
* @return Base address 0.
*/
uint32_t nrf_gzll_get_base_address_0(void);
/**
* @brief Set the base address for pipes 1-7.
*
* Pipes 1 through 7 share base_address_1. @sa nrf_gzll_set_base_address_0.
*
* @param base_address The 4 byte base address.
*
* @retval true If the parameter was set.
* @retval false If Gazell was enabled.
*/
bool nrf_gzll_set_base_address_1(uint32_t base_address);
/**
* @brief Get function counterpart to nrf_gzll_set_base_address_1().
*
* @return Base address 1.
*/
uint32_t nrf_gzll_get_base_address_1(void);
/**
* @brief Set the address prefix byte for a specific pipe.
*
* Each pipe should have its own unique prefix byte.
*
* @param pipe The pipe that the address should apply to.
* This value must be < NRF_GZLL_CONST_PIPE_COUNT.
* @param address_prefix_byte The address prefix byte.
*
* @note Due to the Anomaly 107, pipe 0 address should not have
* both prefix and two LSB of base address set to 0.
*
* @retval true If the parameter was set.
* @retval false If Gazell was enabled, or if the pipe was invalid.
*/
bool nrf_gzll_set_address_prefix_byte(uint32_t pipe, uint8_t address_prefix_byte);
/**
* @brief Get function counterpart to nrf_gzll_set_address_prefix_byte().
*
* @param pipe The pipe for which to get the address.
* This value must be < NRF_GZLL_CONST_PIPE_COUNT.
* @param p_out_address_prefix_byte The pointer in which to return the
* address prefix byte.
*
* @retval true If the parameter was returned.
* @retval false If Gazell was enabled, the pipe was invalid or
* out_address was a NULL pointer.
*/
bool nrf_gzll_get_address_prefix_byte(uint32_t pipe, uint8_t * p_out_address_prefix_byte);
/**
* @brief Set which pipes shall listen for packets in Host mode.
*
* This value is a bitmap, and each bit corresponds to a given pipe number.
* Bit 0 set to "1" enables pipes 0, bit 1 set to "1" enables pipe 1
* and so forth.
* The maximum number of pipes is defined by NRF_GZLL_CONST_PIPE_COUNT.
*
* @param pipes A bitmap specifying which pipes to monitor.
*
* @retval true If the parameter was set.
* @retval false If Gazell was enabled.
*/
bool nrf_gzll_set_rx_pipes_enabled(uint32_t pipes);
/**
* @brief Get function counterpart to nrf_gzll_set_rx_pipes_enabled().
*
* @return Bitmap holding the current enabled pipes.
*/
uint32_t nrf_gzll_get_rx_pipes_enabled(void);
/**
* @brief Set the timeslot period.
*
* The length in microseconds of a Gazell link layer timeslot.
*
* The minimum value of the timeslot period is dependent of the
* radio data rate (@sa nrf_gzll_set_datarate()).
*
* - For NRF_GZLL_DATARATE_2MBIT the timeslot period must be >= 600 us.
* - For NRF_GZLL_DATARATE_1MBIT the timeslot period must be >= 900 us.
* - For NRF_GZLL_DATARATE_250KBIT the timeslot period must be >= 2700 us.
*
* @param period_us The timeslot period in microseconds.
*
* @retval true If the parameter was set.
* @retval false If Gazell was enabled.
*/
bool nrf_gzll_set_timeslot_period(uint32_t period_us);
/**
* @brief Get function counterpart to nrf_gzll_get_timeslot_period().
*
* @return The current timeslot period.
*/
uint32_t nrf_gzll_get_timeslot_period(void);
/**
* @brief Set the Device channel selection policy
*
* The policy determines the initial channel when starting a new packet.
* transmission.
*
* @param policy The channel selection policy.
*
* @arg NRF_GZLL_DEVICE_CHANNEL_SELECTION_POLICY_USE_SUCCESSFUL specifies
* that a new packet transmission always shall use the previous
* successful channel from the channel table. If Gazell is "in sync", Gazell
* will wait until this channel is being monitored by the Host before starting
* the transmission.
*
* @arg NRF_GZLL_DEVICE_CHANNEL_SELECTION_POLICY_USE_CURRENT specifies that
* Gazell shall transmit on the channel that is currently being monitored by the
* Host. This parameter is only used when Gazell is "in sync". When "out of" sync,
* Gazell will always start using the "previous successful" channel.
*
* @retval true If the parameter was set.
* @retval false If Gazell was enabled or the policy was invalid.
*/
bool nrf_gzll_set_device_channel_selection_policy(nrf_gzll_device_channel_selection_policy_t policy);
/**
* @brief Get function counterpart to nrf_gzll_set_device_channel_selection_policy().
*
* @return the Device channel selection policy.
*/
nrf_gzll_device_channel_selection_policy_t nrf_gzll_get_device_channel_selection_policy(void);
/**
* @brief Set the number of timeslots that Gazell shall
* reside on a single channel before switching to another channel.
*
* This parameter applies in Host mode and for a Device that is
* in the "in sync" state.
*
* Since the Device and Host can not be in perfect synchronization, a
* transmission should overlap to adjacent timeslots on the Host.
* Therefore this value should be at least 2.
*
* @sa nrf_gzll_set_timeslots_per_channel_when_device_out_of_sync
*
* @param timeslots The number of timeslots to reside on
* each channel before channel switch.
*
* @retval true If the parameter was set.
* @retval false If Gazell was enabled.
*/
bool nrf_gzll_set_timeslots_per_channel(uint32_t timeslots);
/**
* @brief Get function counterpart to nrf_gzll_set_timeslots_per_channel().
*
* @return The current number of timeslots.
*/
uint32_t nrf_gzll_get_timeslots_per_channel(void);
/**
* @brief Set the number of timeslots that a Gazell shall
* reside on a single channel before switching to another channel when
* in the "out of sync" state.
*
* This value should be set so that the Device transmits on one channel
* while the Host goes through a full channel rotation, i.e.,
* channel_table_size*timeslots_per_channel.
* This ensures that the channels on the Device and Host will coincide
* at some point.
* Further increasing the value has been observed to provide better performance
* in the presence of interferers.
*
* @param timeslots The number of timeslots to reside on
* each channel before channel switch.
*
* @retval true If the parameter was set.
* @retval false If Gazell was enabled.
*/
bool nrf_gzll_set_timeslots_per_channel_when_device_out_of_sync(uint32_t timeslots);
/**
* @brief Get function counterpart to
* nrf_gzll_set_timeslots_per_channel_when_device_out_of_sync().
*
* @return The current number of timeslots.
*/
uint32_t nrf_gzll_get_timeslots_per_channel_when_device_out_of_sync(void);
/**
* @brief Set the number of timeslots after a successful
* reception of a Device or Host packet that the Gazell Link Layer shall assume
* that the link is synchronized. A value of 0 implies that the
* link is always out of sync.
*
* @param lifetime The sync lifetime in number of timeslots.
*
* @retval true If the sync lifetime was set.
* @retval false If Gazell was enabled.
*/
bool nrf_gzll_set_sync_lifetime(uint32_t lifetime);
/**
* @brief Get function counterpart to nrf_gzll_set_sync_lifetime().
*
* @return The sync lifetime measured in number of timeslots.
*/
uint32_t nrf_gzll_get_sync_lifetime(void);
/**
* @brief Set the maximum number of TX attempts
* that can be used for a single packet.
*
* After the maximum number of attempts have been spent without
* receiving any ACK from the Host, the transmission will be terminated
* and the nrf_gzll_device_tx_failed() callback will be called. A zero
* value of the function parameter implies the infinite number of TX attempts.
*
* @param max_tx_attempts The maximum number of TX attempts.
*/
void nrf_gzll_set_max_tx_attempts(uint16_t max_tx_attempts);
/**
* @brief Get function counterpart to nrf_gzll_set_max_tx_attempts().
*
* @return The current max Device TX attempts.
*/
uint16_t nrf_gzll_get_max_tx_attempts(void);
/**
* @brief Set the table of Radio Frequency (RF) channels.
*
* The valid channels are in the range 0 <= channel <= 125, where the
* actual centre frequency is (2400 + channel) MHz.
* The maximum channel table size is defined by
* NRF_GZLL_CONST_MAX_CHANNEL_TABLE_SIZE.
*
* @param p_channel_table Pointer to the channel table.
* @param size The size of the channel table.
*
* @retval true If the channel table was set.
* @retval false If Gazell was enabled, or the channel_table pointer was NULL,
* or the size was invalid.
*/
bool nrf_gzll_set_channel_table(uint8_t * p_channel_table, uint32_t size);
/**
* @brief Get the table of Radio Frequency (RF) channels.
*
* @param p_channel_table Pointer to copy the channel table to.
* @param p_size Pointer to copy the size of the channel table to.
* The value already at size must be at least the size
* of the channel table.
*
* @retval true If the channel table was copied to channel_table.
* @retval false If the channel_table pointer was NULL,
* or the size was not large enough.
*/
bool nrf_gzll_get_channel_table(uint8_t * p_channel_table, uint32_t * p_size);
/**
* @brief Get the current channel table size.
*
* @return The current channel table size.
*/
uint32_t nrf_gzll_get_channel_table_size(void);
/**
* @brief Set the radio TX power.
*
* @param tx_power TX power.
*
* @retval true If the parameter was set.
* @retval false If the TX power was invalid.
*/
bool nrf_gzll_set_tx_power(nrf_gzll_tx_power_t tx_power);
/**
* @brief Get function counterpart to nrf_gzll_set_tx_power().
*
* @return The current TX power.
*/
nrf_gzll_tx_power_t nrf_gzll_get_tx_power(void);
/**
* @brief Set the radio datarate.
*
* @param data_rate Datarate.
*
* @retval true If the parameter was set.
* @retval false If Gazell was enabled or the datarate was invalid.
*/
bool nrf_gzll_set_datarate(nrf_gzll_datarate_t data_rate);
/**
* @brief Get function counterpart to nrf_gzll_set_datarate().
*
* @return The current datarate.
*/
nrf_gzll_datarate_t nrf_gzll_get_datarate(void);
/**
* @brief Set whether start/stop of external oscillator (XOSC) shall be handled
* automatically inside Gazell or manually by the application.
*
* When controlling the XOSC manually from the application it is
* required that the XOSC is started before Gazell is enabled.
*
* When start/stop of the XOSC is handled automatically by Gazell,
* the XOSC will only be running when needed, that is when the radio
* is being used or when Gazell needs to maintain synchronization.
*
* It is required that the XOSC is started in order for the radio to be
* able to send or receive any packets.
*
* @param xosc_ctl setting for XOSC control.
*
* @retval true if the parameter was set.
* @retval false if Gazell was enabled or the xosc_ctl value was invalid.
*/
bool nrf_gzll_set_xosc_ctl(nrf_gzll_xosc_ctl_t xosc_ctl);
/**
* Get function counterpart for nrf_gzll_set_xosc_ctl();
*
* @return The XOSC control setting.
*/
nrf_gzll_xosc_ctl_t nrf_gzll_get_xosc_ctl(void);
/**
* @brief Set Gazell to disable automatically after a certain number of timeslot ticks.
*
* @param num_ticks Number of timeslot ticks.
*
*/
void nrf_gzll_set_auto_disable(uint32_t num_ticks);
#if defined(NRF52_SERIES) || defined(__SDK_DOXYGEN__)
/**
* @brief Set up external front end control.
*
* @param p_pa_lna_cfg Pointer to the configuration struct.
*/
bool nrf_gzll_set_pa_lna_cfg(nrf_gzll_pa_lna_cfg_t const * p_pa_lna_cfg);
#endif
/**
* @brief Get the number of timeslot ticks that have occurred since
* nrf_gzll_init() was called.
*
* @return Number of timeslot ticks.
*
*/
uint32_t nrf_gzll_get_tick_count(void);
/**
* @brief Clear the internal timeslot tick count variable that is read
* by nrf_gzll_get_tick_count().
*
*/
void nrf_gzll_clear_tick_count(void);
/** @} */
/******************************************************************************/
/** @name Error handling functions
* @{ */
/******************************************************************************/
/**
* @brief Gets the Gazell error code.
*
* @return The current error code.
*/
nrf_gzll_error_code_t nrf_gzll_get_error_code(void);
/**
* @brief Reset the Gazell error code.
*
* The error code is reset to NRF_GZLL_ERROR_CODE_NO_ERRROR.
*/
void nrf_gzll_reset_error_code(void);
/** @} */
/** @} */
#ifdef __cplusplus
}
#endif
#endif