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 (3NRF_GZLL_DEFAULT_CHANNEL_TABLE_SIZENRF_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

enum nrf_gzll_mode_t

Enumerator
NRF_GZLL_MODE_DEVICE	Device mode.
NRF_GZLL_MODE_HOST	Host mode.

enum nrf_gzll_device_channel_selection_policy_t

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.

enum nrf_gzll_tx_power_t

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.

enum nrf_gzll_datarate_t

Enumerator
NRF_GZLL_DATARATE_250KBIT	250 Kbps datarate.
NRF_GZLL_DATARATE_1MBIT	1 Mbps datarate.
NRF_GZLL_DATARATE_2MBIT	2 Mbps datarate.

enum nrf_gzll_xosc_ctl_t

Enumerator
NRF_GZLL_XOSC_CTL_AUTO	Switch XOSC on/off automatically.
NRF_GZLL_XOSC_CTL_MANUAL	Switch XOSC on/off manually.

enum nrf_gzll_error_code_t

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

mode	The mode to initialize Gazell in.

Return values

true	if Gazell initialized.
false	if 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

false if 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

true	If Gazell is enabled.
false	If 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

pipe	is the pipe on which an ACK packet was received.
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_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

pipe	is the pipe on which the transmission failed.
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_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

pipe	is the pipe on which the data packet was received.
rx_info	struct 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

pipe	Pipe to which to add the payload. This value must be < NRF_GZLL_CONST_PIPE_COUNT.
payload	Pointer to the payload.
length	Number of bytes of the payload to transmit (0 to NRF_GZLL_CONST_MAX_PAYLOAD_LENGTH).

Return values

true	if the packet was successfully added to the TX FIFO.
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 *	payload,
		uint32_t *	length
	)

Parameters

pipe	Pipe from which to fetch the payload. This value must be < NRF_GZLL_CONST_PIPE_COUNT.
payload	Pointer to copy the payload to.
length	Length must be at least as large as the the number of bytes in the received payload length.

Return values

true	If the fetch was successful.
false	If unsuccessful, check nrf_gzll_error_code_t for more information.

int32_t nrf_gzll_get_tx_fifo_packet_count ( uint32_t pipe )

Parameters

pipe	The pipe for which to check. This value must be < NRF_GZLL_CONST_PIPE_COUNT.

Return values

>=0	The number of packets in the TX FIFO for the pipe.
-1	If the pipe number is invalid.

int32_t nrf_gzll_get_rx_fifo_packet_count ( uint32_t pipe )

Parameters

pipe	The pipe for which to check. This value must be < NRF_GZLL_CONST_PIPE_COUNT.

Return values

>=0	The number of packets in the RX FIFO for the pipe.
-1	If 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

pipe	The pip for which to check. This value must be < NRF_GZLL_CONST_PIPE_COUNT.

Return values

true	If there is another space.
false	If 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

pipe	is the pipe for which to flush. This value must be < NRF_GZLL_CONST_PIPE_COUNT.

Return values

true	if the pipe was flushed.
false	if 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

pipe	is the pipe for which to flush. This value must be < NRF_GZLL_CONST_PIPE_COUNT.

Return values

true	if the pipe was flushed.
false	if the pipe was not flushed.

bool nrf_gzll_set_mode ( nrf_gzll_mode_t mode )

Parameters

mode	The mode to be used. See nrf_gzll_mode_t for a list of valid modes.

Return values

true	If the parameter was set.
false	If 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_address The 4 byte base address. All bytes are used.

Return values

true	If 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_address The 4 byte base address.

Return values

true	If the parameter was set.
false	If 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

pipe	The pipe that the address should apply to. This value must be < NRF_GZLL_CONST_PIPE_COUNT.
address_prefix_byte	The address prefix byte.

Return values

true	If the parameter was set.
false	If 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

pipe	The pipe for which to get the address. This value must be < NRF_GZLL_CONST_PIPE_COUNT.
out_address_prefix_byte	The pointer in which to return the address prefix byte.

Return values

true	If the parameter was returned.
false	If 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

pipes A bitmap specifying which pipes to monitor.

Return values

true	If the parameter was set.
false	If 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_us The timeslot period in microseconds.

Return values

true	If the parameter was set.
false	If 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

policy The 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

true	If the parameter was set.
false	If 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

timeslots The number of timeslots to reside on each channel before channel switch.

Return values

true	If the parameter was set.
false	If 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

timeslots The number of timeslots to reside on each channel before channel switch.

Return values

true	If the parameter was set.
false	If 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

lifetime The sync lifetime in number of timeslots.

Return values

true	If the sync lifetime was set.
false	If 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_attempts The maximum number of TX attempts.

Return values

true	If the parameter was set.
false	If 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_table	Pointer to the channel table.
size	The size of the channel table.

Return values

true	If the channel table was set.
false	If 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_table	Pointer to copy the channel table to.
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.

Return values

true	If the channel table was copied to channel_table.
false	If 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_power TX power.

Return values

true	If the parameter was set.
false	If 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_rate Datarate.

Return values

true	If the parameter was set.
false	If 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_ctl setting for XOSC control.

Return values

true	if the parameter was set.
false	if 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_ticks Number 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.

Enumerations

General API functions

Device mode callback functions

Host mode callback functions

Callback functions for both Device and Host mode

Packet transmission and receiving functions

Configuration functions

Error handling functions

Hardware resources used by Gazell

Constant pipe and FIFO configuration

Default radio configuration

Default Address configuration

Default timeslot and synchronization configuration

Data Structures

Detailed Description

Enumeration Type Documentation

Function Documentation