Gazell Link Layer

Enumerator used for selecting the radio datarate.

Enumerator used for selecting Gazell Device channel selection policy.

Enumerator used for error codes for Gazell API functions.

Enumerator used for selecting Gazell mode.

Enumerator used for selecting the transmit (TX) power.

Enumerator used for specifying whether switching the external 16 MHz oscillator on/off shall be handled automatically inside Gazell or manually by the application.

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.

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.

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.

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.

ACK received callback (Device mode only).

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.

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.

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.

Enable Gazell.

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.

Fetch a packet from the head of the RX FIFO.

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.

Flush the RX FIFO for a specific 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.

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.

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.

Get function counterpart to nrf_gzll_set_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.

Get function counterpart to nrf_gzll_set_base_address_0() .

Returns

Base address 0.

Get function counterpart to nrf_gzll_set_base_address_1() .

Returns

Base address 1.

Get the table of Radio Frequency (RF) channels.

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.

Get the current channel table size.

Returns

The current channel table size.

Get function counterpart to nrf_gzll_set_datarate() .

Returns

The current datarate.

Get function counterpart to nrf_gzll_set_device_channel_selection_policy() .

Returns

the Device channel selection policy.

Gets the Gazell error code.

Returns

The current error code.

Get function counterpart to nrf_gzll_set_max_tx_attempts() .

Returns

The current max Device TX attempts.

Get function counterpart to nrf_gzll_set_mode() .

Returns

The current mode.

Get the number of packets in the RX FIFO on a specific 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.

Get function counterpart to nrf_gzll_set_rx_pipes_enabled() .

Returns

Bitmap holding the current enabled pipes.

Get function counterpart to nrf_gzll_set_sync_lifetime() .

Returns

The sync lifetime measured in number of timeslots.

Get the number of timeslot ticks that have occurred since nrf_gzll_init() was called.

Returns

Number of timeslot ticks.

Get function counterpart to nrf_gzll_get_timeslot_period() .

Returns

The current timeslot period.

Get function counterpart to nrf_gzll_set_timeslots_per_channel() .

Returns

The current number of timeslots.

Get function counterpart to nrf_gzll_set_timeslots_per_channel_when_device_out_of_sync() .

Returns

The current number of timeslots.

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.

Returns

The number of packets residing in all TX and RX FIFOs.

Get the number of packets in the TX FIFO on a specific 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.

Get function counterpart to nrf_gzll_set_tx_power() .

Returns

The current TX power.

Get function counterpart for nrf_gzll_set_xosc_ctl() ;

Returns

The XOSC control setting.

Data packet received callback (Host mode only).

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.

Initialize Gazell.

Parameters

mode	The mode to initialize Gazell in.

Return values

true	if Gazell initialized.
false	if Gazell failed to initialize.

Check whether Gazell is enabled or disabled.

Return values

true	If Gazell is enabled.
false	If Gazell is disabled.

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.

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.

Reset the Gazell error code.

The error code is reset to NRF_GZLL_ERROR_CODE_NO_ERRROR.

Set the address prefix byte for a specific pipe.

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.

Set Gazell to disable automatically after a certain number of timeslot ticks.

Parameters

num_ticks

Number of timeslot ticks.

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.

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.

Set the base address for pipes 1-7.

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.

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.

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.

Set the radio datarate.

Parameters

data_rate

Datarate.

Return values

true	If the parameter was set.
false	If Gazell was enabled or the datarate was invalid.

Set the Device channel selection 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.

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.

Parameters

max_tx_attempts

The maximum number of TX attempts.

Return values

true	If the parameter was set.
false	If Gazell was enabled.

Set the 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.

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.

Parameters

pipes

A bitmap specifying which pipes to monitor.

Return values

true	If the parameter was set.
false	If Gazell was enabled.

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.

Parameters

lifetime

The sync lifetime in number of timeslots.

Return values

true	If the sync lifetime was set.
false	If Gazell was enabled.

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 (

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.

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.

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.

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.

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.

Set the radio 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.

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.

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.