FEM abstraction layer

This library is a wrapper for the MPSL FEM.

Overview

The library simplifies low level usage of FEM hardware.

Configuration

To enable this library, use the CONFIG_FEM_AL_LIB.

Samples using the library

The following nRF Connect SDK samples use this library:

Dependencies

API documentation

Header file: include/fem_al/fem_al.h
Source files: lib/fem_al/
group fem_al

Front-end Abstraction layer library. This file is an abstraction for the MPSL FEM API and provides API for controlling front-end modules.

Typedefs

typedef uint8_t fem_tx_power_control

Type holding Tx power control to be applied to front-end module.

Note

The value stored in this type is specific to the FEM type in use.

Enums

enum fem_antenna

The front-end module (FEM) antennas.

Values:

enumerator FEM_ANTENNA_1

First antenna.

enumerator FEM_ANTENNA_2

Second antenna.

Functions

int fem_init(NRF_TIMER_Type *timer_instance, uint8_t compare_channel_mask)

Initialize the front-end module.

Parameters:

  • timer_instance – [in] Pointer to a 1-us resolution timer instance.

  • compare_channel_mask – [in] Mask of the compare channels that can be used by the Front End Module to schedule its own tasks.

Return values:

0 – If the operation was successful. Otherwise, a (negative) error code is returned.

int fem_power_up(void)

Power-up the front-end module.

The function is synchronous and waits a specific time for the front-end device to be activated.

Return values:

0 – If the operation was successful. Otherwise, a (negative) error code is returned.

int fem_power_down(void)

Power-down the front-end module.

This function switches off the front-end module. The gain setting will be reset to the default after calling this function. It can be called after a FEM configuration is cleared by fem_txrx_configuration_clear. The device will turn off after its specific time. This function does not block on that settling time and returns before the actual power-down.

Return values:

0 – If the operation was successful. Otherwise, a (negative) error code is returned.

int fem_tx_power_control_set(fem_tx_power_control tx_power_control)

Configure Tx power control of the front-end module.

Parameters:

  • tx_power_control – [in] Tx power control specific to the front-end module implementation. For nRF21540 GPIO/SPI, this is a register value. For nRF21540 GPIO, this is MODE pin value. Check your front-end module product specification for Tx power control value range.

Return values:

0 – If the operation was successful. Otherwise, a (negative) error code is returned.

uint32_t fem_default_ramp_up_time_get(bool rx, nrf_radio_mode_t mode)

Get the default radio ramp-up time for reception or transmission with a given data rate and modulation.

Parameters:

  • rx – [in] Get a delay for radio reception. If set to false get a delay for radio transmission.

  • mode – [in] Radio data rate and modulation.

Returns:

The activation delay value in microseconds.

int fem_tx_configure(uint32_t ramp_up_time)

Configure the front-end module to TX mode (PA).

Parameters:

  • ramp_up_time – [in] rump_up_time

Return values:

0 – If the operation was successful. Otherwise, a (negative) error code is returned.

int fem_rx_configure(uint32_t ramp_up_time)

Configure the front-end module to RX mode (LNA).

Parameters:

  • ramp_up_time – [in] Radio ramp-up time.

Return values:

0 – If the operation was successful. Otherwise, a (negative) error code is returned.

int fem_txrx_configuration_clear(void)

Clear up the configuration provided by the fem_tx_configure or fem_rx_configure.

void fem_txrx_stop(void)

Stop the front-end module RX/TX mode immediately.

int fem_antenna_select(enum fem_antenna ant)

Chooses one of two physical antenna outputs.

Parameters:

  • ant – [in] Selected antenna output

Return values:

0 – If the operation was successful. Otherwise, a (negative) error code is returned.

uint32_t fem_radio_tx_ramp_up_delay_get(bool fast, nrf_radio_mode_t mode)

Get the radio ramp-up time in transmit mode.

Parameters:

  • fast – [in] The radio is in the fast ramp-up mode.

  • mode – [in] Radio mode.

Return values:

Radio – ramp-up time in microseconds.

uint32_t fem_radio_rx_ramp_up_delay_get(bool fast, nrf_radio_mode_t mode)

Get the radio ramp-up time in receive mode.

Parameters:

  • fast – [in] The radio is in the fast ramp-up mode.

  • mode – [in] Radio mode.

Return values:

Radio – ramp-up time in microseconds.

int8_t fem_tx_output_power_prepare(int8_t power, int8_t *radio_tx_power, uint16_t freq_mhz)

Set the front-end module Tx power control and returns output power to be set on the radio peripheral to get requested output power.

This function calculates power value for RADIO peripheral register and sets front-end module Tx power control value.

Note

If the exact value of power cannot be achieved, this function attempts to use less power to not exceed the limits.

Parameters:

  • power – [in] TX power requested for transmission on air.

  • radio_tx_power – [out] Tx power value to be set on the radio peripheral.

  • freq_mhz – [in] Frequency in MHz. The output power is valid only for this frequency.

Returns:

The power in dBm that is achieved as device output power. It can be different from the value requested by power.

int8_t fem_tx_output_power_check(int8_t power, uint16_t freq_mhz, bool tx_power_ceiling)

Check a real Tx output power, for the SoC with the front-end module for given parameters.

Check if the requested output power can be achieved. This function returns the exact value or if this value is not available for given frequency, the closest greater or lower value to the requested output power.

Parameters:

  • power – [in] Tx power level to check.

  • freq_mhz – [in] Frequency in MHz. The output power check is valid only for this frequency.

  • tx_power_ceiling – [in] Flag to get the ceiling or floor of the requested transmit power level.

Returns:

The real Tx output power in dBm, which can be achieved for the given frequency. It might be different than power and depending on tx_power_ceiling it can be greater or lower than the requested one.

static inline int8_t fem_tx_output_power_min_get(uint16_t freq_mhz)

Get the minimum Tx output power for the SoC with the front-end module.

Parameters:

  • freq_mhz – [in] Frequency in MHz. The minimum output power is valid only for this frequency.

Returns:

The minimum output power in dBm.

static inline int8_t fem_tx_output_power_max_get(uint16_t freq_mhz)

Get the maximum Tx output power for the SoC with the front-end module.

Parameters:

  • freq_mhz – [in] Frequency in MHz. The maximum output power is valid only for this frequency.

Returns:

The maximum output power in dBm.

int8_t fem_default_tx_output_power_get(void)

Get the front-end module default Tx output power.

Returns:

The front-end module default Tx output power value.

void fem_errata_25X(nrf_radio_mode_t mode)

Apply the workaround for the Errata 254, 255, 256, 257 when appropriate.

This workaround is applied only if used with the correct hardware configuration.

Parameters:

  • mode – [in] Radio mode.