nRF51 SDK
 All Data Structures Functions Variables Typedefs Enumerations Enumerator Groups Pages
Application Programming Interface (API)

Gazell Link Layer Application Programming Interface (API). More...

Enumerations

enum  nrf_gzll_mode_t {
  NRF_GZLL_MODE_DEVICE,
  NRF_GZLL_MODE_HOST
}
 Enumerator used for selecting Gazell mode. More...
 
enum  nrf_gzll_device_channel_selection_policy_t {
  NRF_GZLL_DEVICE_CHANNEL_SELECTION_POLICY_USE_SUCCESSFUL,
  NRF_GZLL_DEVICE_CHANNEL_SELECTION_POLICY_USE_CURRENT
}
 Enumerator used for selecting Gazell Device channel selection policy. More...
 
enum  nrf_gzll_tx_power_t {
  NRF_GZLL_TX_POWER_4_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
}
 Enumerator used for selecting the transmit (TX) power. More...
 
enum  nrf_gzll_datarate_t {
  NRF_GZLL_DATARATE_250KBIT,
  NRF_GZLL_DATARATE_1MBIT,
  NRF_GZLL_DATARATE_2MBIT
}
 Enumerator used for selecting the radio datarate. More...
 
enum  nrf_gzll_xosc_ctl_t {
  NRF_GZLL_XOSC_CTL_AUTO,
  NRF_GZLL_XOSC_CTL_MANUAL
}
 Enumerator used for specifying whether switching the external 16 MHz oscillator on/off shall be handled automatically inside Gazell or manually by the application. More...
 
enum  nrf_gzll_error_code_t {
  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_NUMBER_OF_ERROR_CODES = 17
}
 Enumerator used for error codes for Gazell API functions. More...
 

General API functions

bool nrf_gzll_init (nrf_gzll_mode_t mode)
 Initialize Gazell. More...
 
bool nrf_gzll_enable (void)
 Enable Gazell. More...
 
void nrf_gzll_disable (void)
 Disable Gazell. More...
 
bool nrf_gzll_is_enabled (void)
 

Device mode callback functions

void nrf_gzll_device_tx_success (uint32_t pipe, nrf_gzll_device_tx_info_t tx_info)
 ACK received callback (Device mode only). More...
 
void nrf_gzll_device_tx_failed (uint32_t pipe, nrf_gzll_device_tx_info_t tx_info)
 Transmission failed callback (Device mode only). More...
 

Host mode callback functions

void nrf_gzll_host_rx_data_ready (uint32_t pipe, nrf_gzll_host_rx_info_t rx_info)
 Data packet received callback (Host mode only). More...
 

Callback functions for both Device and Host mode

void nrf_gzll_disabled (void)
 Disabled callback. More...
 

Packet transmission and receiving functions

bool nrf_gzll_add_packet_to_tx_fifo (uint32_t pipe, uint8_t *payload, uint32_t length)
 Add a packet to the tail of the TX FIFO. More...
 
bool nrf_gzll_fetch_packet_from_rx_fifo (uint32_t pipe, uint8_t *payload, uint32_t *length)
 Fetch a packet from the head of the RX FIFO. More...
 
int32_t nrf_gzll_get_tx_fifo_packet_count (uint32_t pipe)
 Get the number of packets in the TX FIFO on a specific pipe. More...
 
int32_t nrf_gzll_get_rx_fifo_packet_count (uint32_t pipe)
 Get the number of packets in the RX FIFO on a specific pipe. More...
 
uint32_t nrf_gzll_get_total_allocated_packet_count (void)
 Get the total number of packets residing in all TX and RX FIFOs. More...
 
bool nrf_gzll_ok_to_add_packet_to_tx_fifo (uint32_t pipe)
 Check if adding a packet to a pipe's TX FIFO should be successful. More...
 
bool nrf_gzll_flush_tx_fifo (uint32_t pipe)
 Flush the RX FIFO for a specific pipe. More...
 
bool nrf_gzll_flush_rx_fifo (uint32_t pipe)
 Flush the RX FIFO for a specific pipe. More...
 

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.

bool nrf_gzll_set_mode (nrf_gzll_mode_t mode)
 Set the mode. More...
 
nrf_gzll_mode_t nrf_gzll_get_mode (void)
 Get function counterpart to nrf_gzll_set_mode(). More...
 
bool nrf_gzll_set_base_address_0 (uint32_t base_address)
 Set the base address for pipe 0. More...
 
uint32_t nrf_gzll_get_base_address_0 (void)
 Get function counterpart to nrf_gzll_set_base_address_0(). More...
 
bool nrf_gzll_set_base_address_1 (uint32_t base_address)
 Set the base address for pipes 1-7. More...
 
uint32_t nrf_gzll_get_base_address_1 (void)
 Get function counterpart to nrf_gzll_set_base_address_1(). More...
 
bool nrf_gzll_set_address_prefix_byte (uint32_t pipe, uint8_t address_prefix_byte)
 Set the address prefix byte for a specific pipe. More...
 
bool nrf_gzll_get_address_prefix_byte (uint32_t pipe, uint8_t *out_address_prefix_byte)
 Get function counterpart to nrf_gzll_set_address_prefix_byte(). More...
 
bool nrf_gzll_set_rx_pipes_enabled (uint32_t pipes)
 Set which pipes shall listen for packets in Host mode. More...
 
uint32_t nrf_gzll_get_rx_pipes_enabled (void)
 Get function counterpart to nrf_gzll_set_rx_pipes_enabled(). More...
 
bool nrf_gzll_set_timeslot_period (uint32_t period_us)
 Set the timeslot period. More...
 
uint32_t nrf_gzll_get_timeslot_period (void)
 Get function counterpart to nrf_gzll_get_timeslot_period(). More...
 
bool nrf_gzll_set_device_channel_selection_policy (nrf_gzll_device_channel_selection_policy_t policy)
 Set the Device channel selection policy. More...
 
nrf_gzll_device_channel_selection_policy_t nrf_gzll_get_device_channel_selection_policy (void)
 Get function counterpart to nrf_gzll_set_device_channel_selection_policy(). More...
 
bool nrf_gzll_set_timeslots_per_channel (uint32_t timeslots)
 Set the number of timeslots that Gazell shall reside on a single channel before switching to another channel. More...
 
uint32_t nrf_gzll_get_timeslots_per_channel (void)
 Get function counterpart to nrf_gzll_set_timeslots_per_channel(). More...
 
bool nrf_gzll_set_timeslots_per_channel_when_device_out_of_sync (uint32_t timeslots)
 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. More...
 
uint32_t nrf_gzll_get_timeslots_per_channel_when_device_out_of_sync (void)
 Get function counterpart to nrf_gzll_set_timeslots_per_channel_when_device_out_of_sync(). More...
 
bool nrf_gzll_set_sync_lifetime (uint32_t lifetime)
 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. More...
 
uint32_t nrf_gzll_get_sync_lifetime (void)
 Get function counterpart to nrf_gzll_set_sync_lifetime(). More...
 
bool nrf_gzll_set_max_tx_attempts (uint16_t max_tx_attempts)
 Set the maximum number of TX attempts that can be used for a single packet. More...
 
uint16_t nrf_gzll_get_max_tx_attempts (void)
 Get function counterpart to nrf_gzll_set_max_tx_attempts(). More...
 
bool nrf_gzll_set_channel_table (uint8_t *channel_table, uint32_t size)
 Set the table of Radio Frequency (RF) channels. More...
 
bool nrf_gzll_get_channel_table (uint8_t *channel_table, uint32_t *size)
 Get the table of Radio Frequency (RF) channels. More...
 
uint32_t nrf_gzll_get_channel_table_size (void)
 Get the current channel table size. More...
 
bool nrf_gzll_set_tx_power (nrf_gzll_tx_power_t tx_power)
 Set the radio TX power. More...
 
nrf_gzll_tx_power_t nrf_gzll_get_tx_power (void)
 Get function counterpart to nrf_gzll_set_tx_power(). More...
 
bool nrf_gzll_set_datarate (nrf_gzll_datarate_t data_rate)
 Set the radio datarate. More...
 
nrf_gzll_datarate_t nrf_gzll_get_datarate (void)
 Get function counterpart to nrf_gzll_set_datarate(). More...
 
bool nrf_gzll_set_xosc_ctl (nrf_gzll_xosc_ctl_t xosc_ctl)
 Set whether start/stop of external oscillator (XOSC) shall be handled automatically inside Gazell or manually by the application. More...
 
nrf_gzll_xosc_ctl_t nrf_gzll_get_xosc_ctl (void)
 
void nrf_gzll_set_auto_disable (uint32_t num_ticks)
 Set Gazell to disable automatically after a certain number of timeslot ticks. More...
 
uint32_t nrf_gzll_get_tick_count (void)
 Get the number of timeslot ticks that have occurred since nrf_gzll_init() was called. More...
 
void nrf_gzll_clear_tick_count (void)
 Clear the internal timeslot tick count variable that is read by nrf_gzll_get_tick_count().
 

Error handling functions

nrf_gzll_error_code_t nrf_gzll_get_error_code (void)
 Gets the Gazell error code. More...
 
void nrf_gzll_reset_error_code (void)
 Reset the Gazell error code. More...
 

Hardware resources used by Gazell

#define NRF_GZLL_HIGH_IRQ_PRIORITY   0
 Interrupt priority the Gazell timer and the radio.
 
#define NRF_GZLL_LOW_IRQ_PRIORITY   1
 Interrupt priority for Gazell callback functions.
 
#define NRF_GZLL_SWI_IRQn   SWI0_IRQn
 Software interrupt # used for callback functions.
 
#define NRF_GZLL_SWI_IRQ_HANDLER   SWI0_IRQHandler
 Software interrupt handler used for callback functions.
 
#define NRF_GZLL_TIMER   NRF_TIMER2
 Timer to be used as flywheel timer.
 
#define NRF_GZLL_TIMER_PERPOWER_Msk   POWER_PERPOWER_TIMER2_Msk
 PERPOWER mask for the timer.
 
#define NRF_GZLL_TIMER_IRQn   TIMER2_IRQn
 Interrupt # for the timer.
 
#define NRF_GZLL_TIMER_IRQ_HANDLER   TIMER2_IRQHandler
 Interrupt handler for the timer.
 
#define NRF_GZLL_PPI_EEP0   (NRF_PPI -> CH0_EEP)
 Gazell PPI event endpoint 0.
 
#define NRF_GZLL_PPI_TEP0   (NRF_PPI -> CH0_TEP)
 Gazell PPI task endpoint 0.
 
#define NRF_GZLL_PPI_EEP1   (NRF_PPI -> CH1_EEP)
 Gazell PPI event endpoint 1.
 
#define NRF_GZLL_PPI_TEP1   (NRF_PPI -> CH1_TEP)
 Gazell PPI task endpoint 1.
 
#define NRF_GZLL_PPI_EEP2   (NRF_PPI -> CH2_EEP)
 Gazell PPI event endpoint 2.
 
#define NRF_GZLL_PPI_TEP2   (NRF_PPI -> CH2_TEP)
 Gazell PPI task endpoint 2.
 
#define NRF_GZLL_PPI_CHEN_MSK_0_AND_1   (0x03)
 Channel enable/disable mask for PPI endpoint 0 and 1.
 
#define NRF_GZLL_PPI_CHEN_MSK_2   (0x04)
 Channel enable/disable mask for PPI endpoint 2.
 

Constant pipe and FIFO configuration

#define NRF_GZLL_CONST_PIPE_COUNT   8
 Number of TX pipes (at least one for each Device-Host pairs).
 
#define NRF_GZLL_CONST_PIPE_COUNT   8
 Number of TX pipes (at least one for each Device-Host pairs).
 
#define NRF_GZLL_CONST_FIFO_LENGTH   3
 Maximum number of packets allowed in a TX or RX FIFO.
 
#define NRF_GZLL_CONST_FIFO_LENGTH   3
 Maximum number of packets allowed in a TX or RX FIFO.
 
#define NRF_GZLL_CONST_MAX_TOTAL_PACKETS   6
 Maximum number of packets available for reservation at any one time.
 
#define NRF_GZLL_CONST_MAX_TOTAL_PACKETS   6
 Maximum number of packets available for reservation at any one time.
 
#define NRF_GZLL_CONST_MAX_PAYLOAD_LENGTH   32
 Maximum allowed payload length in bytes.
 
#define NRF_GZLL_CONST_MAX_PAYLOAD_LENGTH   32
 Maximum allowed payload length in bytes.
 
#define NRF_GZLL_CONST_CALLBACK_QUEUE_LENGTH   10
 Maximum number of notifications allowed in the callback queue.
 
#define NRF_GZLL_CONST_CALLBACK_QUEUE_LENGTH   10
 Maximum number of notifications allowed in the callback queue.
 

Default radio configuration

#define NRF_GZLL_DEFAULT_TX_POWER   NRF_GZLL_TX_POWER_0_DBM
 Default TX power.
 
#define NRF_GZLL_DEFAULT_DATARATE   NRF_GZLL_DATARATE_2MBIT
 Default data rate.
 
#define NRF_GZLL_DEFAULT_CHANNEL_TABLE   {4, 25, 42, 63, 77}
 Default channel table.
 
#define NRF_GZLL_DEFAULT_CHANNEL_TABLE_SIZE   5
 Default channel table size.
 
#define NRF_GZLL_CONST_MAX_CHANNEL_TABLE_SIZE   16
 Maximum channel table size allowed by Gazell.
 

Default Address configuration

#define NRF_GZLL_DEFAULT_FULL_ADDRESS_PIPE0   {0x01, 0x04, 0x07, 0x0A, 0x0D}
 Corresponding legacy Gazell pipe 0 address.
 
#define NRF_GZLL_DEFAULT_BASE_ADDRESS_0   0x0D0A0704
 Default base address 0.
 
#define NRF_GZLL_DEFAULT_BASE_ADDRESS_1   0x0E0B0805
 Default base address 1.
 
#define NRF_GZLL_DEFAULT_PREFIX_BYTE_0   1
 Default prefix address pipe 0.
 
#define NRF_GZLL_DEFAULT_PREFIX_BYTE_1   2
 Default prefix address pipe 1.
 
#define NRF_GZLL_DEFAULT_PREFIX_BYTE_2   3
 Default prefix address pipe 2.
 
#define NRF_GZLL_DEFAULT_PREFIX_BYTE_3   4
 Default prefix address pipe 3.
 
#define NRF_GZLL_DEFAULT_PREFIX_BYTE_4   5
 Default prefix address pipe 4.
 
#define NRF_GZLL_DEFAULT_PREFIX_BYTE_5   6
 Default prefix address pipe 5.
 
#define NRF_GZLL_DEFAULT_PREFIX_BYTE_6   7
 Default prefix address pipe 6.
 
#define NRF_GZLL_DEFAULT_PREFIX_BYTE_7   8
 Default prefix address pipe 7.
 
#define NRF_GZLL_DEFAULT_BASE_ADDRESS_LENGTH   NRF_GZLL_BASE_ADDRESS_LENGTH_4B
 Default on-air base address length.
 
#define NRF_GZLL_DEFAULT_RX_PIPES_ENABLED   0x000000FF
 Enabled Rx pipes. See nrf_gzll_set_rx_pipes_enabled().
 

Default timeslot and synchronization configuration

#define NRF_GZLL_DEFAULT_TIMESLOT_PERIOD   600
 Default timeslot period.
 
#define NRF_GZLL_DEFAULT_TIMESLOTS_PER_CHANNEL   2
 Timeslots use by the Host and by the Device when communication is in sync.
 
#define NRF_GZLL_DEFAULT_TIMESLOTS_PER_CHANNEL_WHEN_DEVICE_OUT_OF_SYNC   15
 Timeslots use by the Device before communication is in sync.
 
#define NRF_GZLL_DEFAULT_SYNC_LIFETIME   (3*NRF_GZLL_DEFAULT_CHANNEL_TABLE_SIZE*NRF_GZLL_DEFAULT_TIMESLOTS_PER_CHANNEL)
 Number of timeslots to keep the timer running so that communication remains synchronized.
 
#define NRF_GZLL_DEFAULT_DEVICE_CHANNEL_SELECTION_POLICY   NRF_GZLL_DEVICE_CHANNEL_SELECTION_POLICY_USE_SUCCESSFUL
 Default channel Gazell Device channel selection policy.
 
#define NRF_GZLL_DEFAULT_MAX_TX_ATTEMPTS   0
 Default maximum TX attempts for each packet. A value of zero implies maximum.
 
#define NRF_GZLL_DEFAULT_XOSC_CTL   NRF_GZLL_XOSC_CTL_AUTO
 Deafult setting for controlling the XOSC.
 

Data Structures

struct  nrf_gzll_device_tx_info_t
 Data structure containing information about the last packet transmission. More...
 
struct  nrf_gzll_host_rx_info_t
 Data structure containing information about the last packet received. More...
 

Detailed Description

Enumeration Type Documentation

Enumerator
NRF_GZLL_MODE_DEVICE 

Device mode.

NRF_GZLL_MODE_HOST 

Host mode.

Enumerator
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.

Enumerator
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.

Enumerator
NRF_GZLL_DATARATE_250KBIT 

250 Kbps datarate.

NRF_GZLL_DATARATE_1MBIT 

1 Mbps datarate.

NRF_GZLL_DATARATE_2MBIT 

2 Mbps datarate.

Enumerator
NRF_GZLL_XOSC_CTL_AUTO 

Switch XOSC on/off automatically.

NRF_GZLL_XOSC_CTL_MANUAL 

Switch XOSC on/off manually.

Enumerator
NRF_GZLL_ERROR_CODE_NO_ERROR 

No error has been detected.

NRF_GZLL_ERROR_CODE_FAILED_TO_INITIALIZE 

The function NRF_GZLL_init failed.

NRF_GZLL_ERROR_CODE_ATTEMPTED_TO_CONFIGURE_WHEN_ENABLED 

A call to a configuration 'set' function was made while Gazell was enabled.

NRF_GZLL_ERROR_CODE_POINTER_IS_NULL 

A null pointer was given as an input to a function.

NRF_GZLL_ERROR_CODE_INVALID_PIPE 

An invalid pipe number was given as an input to a function.

NRF_GZLL_ERROR_CODE_INVALID_MODE 

An invalid value for the nrf_gzll_mode_t enumerator was given as input to a function.

NRF_GZLL_ERROR_CODE_INVALID_PAYLOAD_LENGTH 

An invalid payload length was given as an input to a function.

NRF_GZLL_ERROR_CODE_INVALID_CHANNEL_TABLE_SIZE 

An invalid channel table size was given as an input to a function.

NRF_GZLL_ERROR_CODE_INSUFFICIENT_PACKETS_AVAILABLE 

There are insufficient packets in the Gazell memory pool to successfully execute the operation.

NRF_GZLL_ERROR_CODE_ATTEMPTED_TO_ADD_TO_FULL_FIFO 

There is insufficient space in the TX FIFO for the data packet.

NRF_GZLL_ERROR_CODE_NO_SPACE_IN_RX_FIFO_FOR_ACK 

There is insufficient space in the RX FIFO for the ACK.

NRF_GZLL_ERROR_CODE_ATTEMPTED_TO_FETCH_FROM_EMPTY_FIFO 

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 

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 

Attempted to set a variable which was not valid.

NRF_GZLL_ERROR_CODE_INTERNAL_ASSERT_OCCURRED 

An internal assert occurred.

NRF_GZLL_ERROR_CODE_CALLBACK_NOT_IMPLEMENTED 

A callback was called but not implemented by the application.

NRF_GZLL_ERROR_CODE_NUMBER_OF_ERROR_CODES 

Number of possible error codes.

Function Documentation

bool nrf_gzll_init ( nrf_gzll_mode_t  mode)
Parameters
modeThe mode to initialize Gazell in.
Return values
trueif Gazell initialized.
falseif Gazell failed to initialize.
bool nrf_gzll_enable ( void  )

When enabled the behaviour described for the current Gazell Link Layer mode will apply.

Return values
falseif nrf_gzll_init has not previously been called.
void nrf_gzll_disable ( void  )

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.

bool nrf_gzll_is_enabled ( void  )

Check whether Gazell is enabled or disabled.

Return values
trueIf Gazell is enabled.
falseIf Gazell is disabled.
void nrf_gzll_device_tx_success ( uint32_t  pipe,
nrf_gzll_device_tx_info_t  tx_info 
)

This callback is made when the Device receives an ACK (acknowledgement) packet.

See Also
nrf_gzll_ack_payload_received.
Parameters
pipeis the pipe on which an ACK packet was received.
tx_infostruct 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_failed ( uint32_t  pipe,
nrf_gzll_device_tx_info_t  tx_info 
)

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.

Parameters
pipeis the pipe on which the transmission failed.
tx_infostruct 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_host_rx_data_ready ( uint32_t  pipe,
nrf_gzll_host_rx_info_t  rx_info 
)

This callback is made when a Host receives a data packet from a Device.

Parameters
pipeis the pipe on which the data packet was received.
rx_infostruct used to indicate whether a payload was removed from the pipe's TX FIFO, as well as RSSI.
void nrf_gzll_disabled ( void  )

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.

bool nrf_gzll_add_packet_to_tx_fifo ( uint32_t  pipe,
uint8_t *  payload,
uint32_t  length 
)

In Device mode, the packet will be added. In Host mode, the payload will be piggybacked onto an ACK.

Parameters
pipePipe to which to add the payload. This value must be < NRF_GZLL_CONST_PIPE_COUNT.
payloadPointer to the payload.
lengthNumber of bytes of the payload to transmit (0 to NRF_GZLL_CONST_MAX_PAYLOAD_LENGTH).
Return values
trueif the packet was successfully added to the TX FIFO.
falseif unsuccessful, check nrf_gzll_error_code_t for more information.
bool nrf_gzll_fetch_packet_from_rx_fifo ( uint32_t  pipe,
uint8_t *  payload,
uint32_t *  length 
)
Parameters
pipePipe from which to fetch the payload. This value must be < NRF_GZLL_CONST_PIPE_COUNT.
payloadPointer to copy the payload to.
lengthLength must be at least as large as the the number of bytes in the received payload length.
Return values
trueIf the fetch was successful.
falseIf unsuccessful, check nrf_gzll_error_code_t for more information.
int32_t nrf_gzll_get_tx_fifo_packet_count ( uint32_t  pipe)
Parameters
pipeThe pipe for which to check. This value must be < NRF_GZLL_CONST_PIPE_COUNT.
Return values
>=0The number of packets in the TX FIFO for the pipe.
-1If the pipe number is invalid.
int32_t nrf_gzll_get_rx_fifo_packet_count ( uint32_t  pipe)
Parameters
pipeThe pipe for which to check. This value must be < NRF_GZLL_CONST_PIPE_COUNT.
Return values
>=0The number of packets in the RX FIFO for the pipe.
-1If the pipe number is invalid.
uint32_t nrf_gzll_get_total_allocated_packet_count ( void  )

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.

Returns
The number of packets residing in all TX and RX FIFOs.
bool nrf_gzll_ok_to_add_packet_to_tx_fifo ( uint32_t  pipe)

Checks if there is another space in the pipe's TX and RX FIFOs as well as enough overall space in the packet pool.

Parameters
pipeThe pip for which to check. This value must be < NRF_GZLL_CONST_PIPE_COUNT.
Return values
trueIf there is another space.
falseIf there is not enough space, or the pipe is invalid.
bool nrf_gzll_flush_tx_fifo ( uint32_t  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.

Parameters
pipeis the pipe for which to flush. This value must be < NRF_GZLL_CONST_PIPE_COUNT.
Return values
trueif the pipe was flushed.
falseif the pipe was not flushed.
bool nrf_gzll_flush_rx_fifo ( uint32_t  pipe)

Delete all the packets and free the memory of the RX FIFO for a specific pipe.

Parameters
pipeis the pipe for which to flush. This value must be < NRF_GZLL_CONST_PIPE_COUNT.
Return values
trueif the pipe was flushed.
falseif the pipe was not flushed.
bool nrf_gzll_set_mode ( nrf_gzll_mode_t  mode)
Parameters
modeThe mode to be used. See nrf_gzll_mode_t for a list of valid modes.
Return values
trueIf the parameter was set.
falseIf Gazell was enabled or the mode was invalid.
nrf_gzll_mode_t nrf_gzll_get_mode ( void  )
Returns
The current mode.
bool nrf_gzll_set_base_address_0 ( uint32_t  base_address)

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.

Parameters
base_addressThe 4 byte base address. All bytes are used.
Return values
trueIf the parameter was set.
Returns
false If Gazell was enabled.
uint32_t nrf_gzll_get_base_address_0 ( void  )
Returns
Base address 0.
bool nrf_gzll_set_base_address_1 ( uint32_t  base_address)

Pipes 1 through 7 share base_address_1.

See Also
nrf_gzll_set_base_address_0.
Parameters
base_addressThe 4 byte base address.
Return values
trueIf the parameter was set.
falseIf Gazell was enabled.
uint32_t nrf_gzll_get_base_address_1 ( void  )
Returns
Base address 1.
bool nrf_gzll_set_address_prefix_byte ( uint32_t  pipe,
uint8_t  address_prefix_byte 
)

Each pipe should have its own unique prefix byte.

Parameters
pipeThe pipe that the address should apply to. This value must be < NRF_GZLL_CONST_PIPE_COUNT.
address_prefix_byteThe address prefix byte.
Return values
trueIf the parameter was set.
falseIf Gazell was enabled, or if the pipe was invalid.
bool nrf_gzll_get_address_prefix_byte ( uint32_t  pipe,
uint8_t *  out_address_prefix_byte 
)
Parameters
pipeThe pipe for which to get the address. This value must be < NRF_GZLL_CONST_PIPE_COUNT.
out_address_prefix_byteThe pointer in which to return the address prefix byte.
Return values
trueIf the parameter was returned.
falseIf Gazell was enabled, the pipe was invalid or out_address was a NULL pointer.
bool nrf_gzll_set_rx_pipes_enabled ( uint32_t  pipes)

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.

Parameters
pipesA bitmap specifying which pipes to monitor.
Return values
trueIf the parameter was set.
falseIf Gazell was enabled.
uint32_t nrf_gzll_get_rx_pipes_enabled ( void  )
Returns
Bitmap holding the current enabled pipes.
bool nrf_gzll_set_timeslot_period ( uint32_t  period_us)

The length in microseconds of a Gazell link layer timeslot.

The minimum value of the timeslot period is dependent of the radio data rate (

See Also
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.
Parameters
period_usThe timeslot period in microseconds.
Return values
trueIf the parameter was set.
falseIf Gazell was enabled.
uint32_t nrf_gzll_get_timeslot_period ( void  )
Returns
The current timeslot period.
bool nrf_gzll_set_device_channel_selection_policy ( nrf_gzll_device_channel_selection_policy_t  policy)

The policy determines the initial channel when starting a new packet. transmission.

Parameters
policyThe channel selection policy.
  • 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.
  • 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.
Return values
trueIf the parameter was set.
falseIf Gazell was enabled or the policy was invalid.
nrf_gzll_device_channel_selection_policy_t nrf_gzll_get_device_channel_selection_policy ( void  )
Returns
the Device channel selection policy.
bool nrf_gzll_set_timeslots_per_channel ( uint32_t  timeslots)

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.

See Also
nrf_gzll_set_timeslots_per_channel_when_device_out_of_sync
Parameters
timeslotsThe number of timeslots to reside on each channel before channel switch.
Return values
trueIf the parameter was set.
falseIf Gazell was enabled.
uint32_t nrf_gzll_get_timeslots_per_channel ( void  )
Returns
The current number of timeslots.
bool nrf_gzll_set_timeslots_per_channel_when_device_out_of_sync ( uint32_t  timeslots)

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.

Parameters
timeslotsThe number of timeslots to reside on each channel before channel switch.
Return values
trueIf the parameter was set.
falseIf Gazell was enabled.
uint32_t nrf_gzll_get_timeslots_per_channel_when_device_out_of_sync ( void  )
Returns
The current number of timeslots.
bool nrf_gzll_set_sync_lifetime ( uint32_t  lifetime)
Parameters
lifetimeThe sync lifetime in number of timeslots.
Return values
trueIf the sync lifetime was set.
falseIf Gazell was enabled.
uint32_t nrf_gzll_get_sync_lifetime ( void  )
Returns
The sync lifetime measured in number of timeslots.
bool nrf_gzll_set_max_tx_attempts ( uint16_t  max_tx_attempts)

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.

Parameters
max_tx_attemptsThe maximum number of TX attempts.
Return values
trueIf the parameter was set.
falseIf Gazell was enabled.
uint16_t nrf_gzll_get_max_tx_attempts ( void  )
Returns
The current max Device TX attempts.
bool nrf_gzll_set_channel_table ( uint8_t *  channel_table,
uint32_t  size 
)

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.

Parameters
channel_tablePointer to the channel table.
sizeThe size of the channel table.
Return values
trueIf the channel table was set.
falseIf Gazell was enabled, or the channel_table pointer was NULL, or the size was invalid.
bool nrf_gzll_get_channel_table ( uint8_t *  channel_table,
uint32_t *  size 
)
Parameters
channel_tablePointer to copy the channel table to.
sizePointer to copy the size of the channel table to. The value already at size must be at least the size of the channel table.
Return values
trueIf the channel table was copied to channel_table.
falseIf the channel_table pointer was NULL, or the size was not large enough.
uint32_t nrf_gzll_get_channel_table_size ( void  )
Returns
The current channel table size.
bool nrf_gzll_set_tx_power ( nrf_gzll_tx_power_t  tx_power)
Parameters
tx_powerTX power.
Return values
trueIf the parameter was set.
falseIf Gazell was enabled or the TX power was invalid.
nrf_gzll_tx_power_t nrf_gzll_get_tx_power ( void  )
Returns
The current TX power.
bool nrf_gzll_set_datarate ( nrf_gzll_datarate_t  data_rate)
Parameters
data_rateDatarate.
Return values
trueIf the parameter was set.
falseIf Gazell was enabled or the datarate was invalid.
nrf_gzll_datarate_t nrf_gzll_get_datarate ( void  )
Returns
The current datarate.
bool nrf_gzll_set_xosc_ctl ( nrf_gzll_xosc_ctl_t  xosc_ctl)

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.

Parameters
xosc_ctlsetting for XOSC control.
Return values
trueif the parameter was set.
falseif Gazell was enabled or the xosc_ctl value was invalid.
nrf_gzll_xosc_ctl_t nrf_gzll_get_xosc_ctl ( void  )

Get function counterpart for nrf_gzll_set_xosc_ctl();

Returns
The XOSC control setting.
void nrf_gzll_set_auto_disable ( uint32_t  num_ticks)
Parameters
num_ticksNumber of timeslot ticks.
uint32_t nrf_gzll_get_tick_count ( void  )
Returns
Number of timeslot ticks.
nrf_gzll_error_code_t nrf_gzll_get_error_code ( void  )
Returns
The current error code.
void nrf_gzll_reset_error_code ( void  )

The error code is reset to NRF_GZLL_ERROR_CODE_NO_ERRROR.