| nRF5 SDK v12.0.0 |

Choose documentation: | nRF5 SDK | S130 SoftDevice API | S132 SoftDevice API | S212 SoftDevice API | S332 SoftDevice API

All Data Structures Functions Variables Typedefs Enumerations Enumerator Groups Pages
Data Structures | Enumerations
Gazell Link Layer
Proprietary stacks

nRF51 only: Gazell Link Layer Application Programming Interface (API). More...

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

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

## Detailed Description

nRF51 only: Gazell Link Layer Application Programming Interface (API).

## Enumeration Type Documentation

enum nrf_gzll_datarate_t

Enumerator used for selecting the radio datarate.

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_device_channel_selection_policy_t

Enumerator used for selecting Gazell Device channel selection policy.

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_error_code_t

Enumerator used for error codes for Gazell API functions.

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.

enum nrf_gzll_mode_t

Enumerator used for selecting Gazell mode.

Enumerator
NRF_GZLL_MODE_DEVICE | Device mode.
NRF_GZLL_MODE_HOST | Host mode.

enum nrf_gzll_tx_power_t

Enumerator used for selecting the transmit (TX) power.

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_xosc_ctl_t

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

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

## Function Documentation

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.

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.

void nrf_gzll_device_tx_failed | ( | uint32_t | pipe,
|  | nrf_gzll_device_tx_info_t | tx_info
| ) |  |

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.

void nrf_gzll_device_tx_success | ( | uint32_t | pipe,
|  | nrf_gzll_device_tx_info_t | tx_info
| ) |  |

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.

void nrf_gzll_disable | ( | void |  | ) |

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_disabled | ( | void |  | ) |

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.

bool nrf_gzll_enable | ( | void |  | ) |

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.

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.

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.

bool nrf_gzll_flush_rx_fifo | ( | uint32_t | pipe | ) |

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.

bool nrf_gzll_flush_tx_fifo | ( | uint32_t | pipe | ) |

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.

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().

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.

uint32_t nrf_gzll_get_base_address_0 | ( | void |  | ) |

Get function counterpart to nrf_gzll_set_base_address_0().

Returns
  Base address 0.

uint32_t nrf_gzll_get_base_address_1 | ( | void |  | ) |

Get function counterpart to nrf_gzll_set_base_address_1().

Returns
  Base address 1.

bool nrf_gzll_get_channel_table | ( | uint8_t * | channel_table,
|  | uint32_t * | size
| ) |  |

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.

uint32_t nrf_gzll_get_channel_table_size | ( | void |  | ) |

Get the current channel table size.

Returns
  The current channel table size.

nrf_gzll_datarate_t nrf_gzll_get_datarate | ( | void |  | ) |

Get function counterpart to nrf_gzll_set_datarate().

Returns
  The current datarate.

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().

Returns
  the Device channel selection policy.

nrf_gzll_error_code_t nrf_gzll_get_error_code | ( | void |  | ) |

Gets the Gazell error code.

Returns
  The current error code.

uint16_t nrf_gzll_get_max_tx_attempts | ( | void |  | ) |

Get function counterpart to nrf_gzll_set_max_tx_attempts().

Returns
  The current max Device TX attempts.

nrf_gzll_mode_t nrf_gzll_get_mode | ( | void |  | ) |

Get function counterpart to nrf_gzll_set_mode().

Returns
  The current mode.

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.

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_rx_pipes_enabled | ( | void |  | ) |

Get function counterpart to nrf_gzll_set_rx_pipes_enabled().

Returns
  Bitmap holding the current enabled pipes.

uint32_t nrf_gzll_get_sync_lifetime | ( | void |  | ) |

Get function counterpart to nrf_gzll_set_sync_lifetime().

Returns
  The sync lifetime measured in number of timeslots.

uint32_t nrf_gzll_get_tick_count | ( | void |  | ) |

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

Returns
  Number of timeslot ticks.

uint32_t nrf_gzll_get_timeslot_period | ( | void |  | ) |

Get function counterpart to nrf_gzll_get_timeslot_period().

Returns
  The current timeslot period.

uint32_t nrf_gzll_get_timeslots_per_channel | ( | void |  | ) |

Get function counterpart to nrf_gzll_set_timeslots_per_channel().

Returns
  The current number of timeslots.

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().

Returns
  The current number of timeslots.

uint32_t nrf_gzll_get_total_allocated_packet_count | ( | void |  | ) |

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.

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.

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.

nrf_gzll_tx_power_t nrf_gzll_get_tx_power | ( | void |  | ) |

Get function counterpart to nrf_gzll_set_tx_power().

Returns
  The current TX power.

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_host_rx_data_ready | ( | uint32_t | pipe,
|  | nrf_gzll_host_rx_info_t | rx_info
| ) |  |

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.

bool nrf_gzll_init | ( | nrf_gzll_mode_t | mode | ) |

Initialize Gazell.

Parameters

  mode | The mode to initialize Gazell in.

Return values

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

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.

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.

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.

void nrf_gzll_reset_error_code | ( | void |  | ) |

Reset the Gazell error code.

The error code is reset to NRF_GZLL_ERROR_CODE_NO_ERRROR.

bool nrf_gzll_set_address_prefix_byte | ( | uint32_t | pipe,
|  | uint8_t | address_prefix_byte
| ) |  |

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.

void nrf_gzll_set_auto_disable | ( | uint32_t | num_ticks | ) |

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

Parameters

  num_ticks | Number of timeslot ticks.

bool nrf_gzll_set_base_address_0 | ( | uint32_t | base_address | ) |

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.

bool nrf_gzll_set_base_address_1 | ( | uint32_t | base_address | ) |

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.

bool nrf_gzll_set_channel_table | ( | uint8_t * | channel_table,
|  | uint32_t | size
| ) |  |

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.

bool nrf_gzll_set_datarate | ( | nrf_gzll_datarate_t | data_rate | ) |

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.

bool nrf_gzll_set_device_channel_selection_policy | ( | nrf_gzll_device_channel_selection_policy_t | policy | ) |

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.

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.

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.

bool nrf_gzll_set_mode | ( | nrf_gzll_mode_t | mode | ) |

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.

bool nrf_gzll_set_rx_pipes_enabled | ( | uint32_t | pipes | ) |

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.

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.

Parameters

  lifetime | The sync lifetime in number of timeslots.

Return values

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

bool nrf_gzll_set_timeslot_period | ( | uint32_t | period_us | ) |

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.

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.

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.

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.

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.

bool nrf_gzll_set_tx_power | ( | nrf_gzll_tx_power_t | tx_power | ) |

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.

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.

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.