/** * 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 #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