API documentation

Multiprotocol Service Layer interface

group mpsl

The main APIs needed to configure, enable, and use the MPSL.

Defines

MPSL_HIGH_IRQ_PRIORITY

High IRQ priority.

High IRQ priority is used for realtime scheduling. It should not be used except when inside radio timeslot by the owner of the timeslot

MPSL_BUILD_REVISION_SIZE

Size of build revision array in bytes.

Typedefs

typedef void (*mpsl_assert_handler_t)(const char *const file, const uint32_t line)

Bitmask of (D)PPI channels reserved for MPSL.

Function prototype for the assert handler.

Note

If an internal assert occurs this function is called. It is supposed to log the assert and stop execution.

Param file:

[in] The filename where the assertion occurred.

Param line:

[in] The line number where the assertion occurred.

Functions

int32_t mpsl_init(mpsl_clock_lfclk_cfg_t const *p_clock_config, IRQn_Type low_prio_irq, mpsl_assert_handler_t p_assert_handler)

MPSL initialization.

Note

If CONFIG_SYSTEM_CLOCK_NO_WAIT is set to 0, never modify the SEVONPEND flag in the SCR register, while this function is executing. Doing so might lead to a deadlock.

Note

If only Front End Module functionality is needed, Initialization API of MPSL FEM can be called instead.

Parameters:
Return values:

  • 0 – MPSL is successfully initialized.

  • -NRF_EPERM – MPSL is already initialized.

  • -NRF_EINVAL – Invalid parameters supplied.

void mpsl_uninit(void)

Uninitialize MPSL. Stops clocks and scheduler. This will release all peripherals and reduce power usage.

Note

This function assumes no protocol stacks are running, and no timeslots are requested. All initialized protocol stacks need to be stopped before calling this function. Failing to do so will lead to undefined behavior.

bool mpsl_is_initialized(void)

Returns true if MPSL is already initialized, false otherwise.

Returns:

True if initialized, false if not.

int32_t mpsl_build_revision_get(uint8_t *p_build_revision)

Obtain build revision.

The application must provide a buffer that is at least MPSL_BUILD_REVISION_SIZE bytes long. MPSL will copy the build revision to the provided buffer.

Parameters:

  • p_build_revision – [inout] Build revision.

Return values:

  • 0 – Success

  • -NRF_EINVAL – Invalid argument provided

void MPSL_IRQ_RADIO_Handler(void)

RADIO interrupt handler.

Note

This handler should be placed in the interrupt vector table. The interrupt priority level should be priority 0.

void MPSL_IRQ_RTC0_Handler(void)

RTC0 interrupt handler.

Note

This handler should be placed in the interrupt vector table. The interrupt priority level should be priority 0

void MPSL_IRQ_TIMER0_Handler(void)

TIMER0 interrupt handler.

Note

This handler should be placed in the interrupt vector table. The interrupt priority level should be priority 0

void MPSL_IRQ_CLOCK_Handler(void)

POWER_CLOCK interrupt handler.

Note

This handler should be placed in the interrupt vector table. The interrupt priority level should be lower than priority 0.

void mpsl_low_priority_process(void)

MPSL low priority processing handler.

Note

This handler should be called when MPSL signals low priority processing should be executed (via low_prio_irq provided to mpsl_init) within reasonable time (a at least a few 100 ms). The caller is responsible to ensure this function is not called concurrently with any other low priority MPSL API functions, for more information see thread safety in the MPSL documentation.

void mpsl_calibration_timer_handle(void)

Application needs to call this when calibration shall occur.

In the nRF Connect SDK, it is designed to be called with a period of CONFIG_CLOCK_CONTROL_NRF_CALIBRATION_PERIOD

void mpsl_pan_rfu(void)

RFU.

RFU

MPSL Clock

group mpsl_clock

The MPSL clock interface provides APIs for controlling the clocks.

Defines

Recommended RC clock calibration timer interval.

Recommended RC clock calibration timer interval for temperature changes.

MPSL_DEFAULT_CLOCK_ACCURACY_PPM

Default LF clock accuracy in parts per million (ppm).

MPSL_DEFAULT_SKIP_WAIT_LFCLK_STARTED

MPSL waits for low frequency clock to start by default.

Typedefs

typedef void (*mpsl_clock_hfclk_callback_t)(void)

High frequency clock callback.

This callback will be called when the high frequency clock is started. It will be executed in the same execution priority as mpsl_low_priority_process.

Enums

enum MPSL_CLOCK_LF_SRC

Low frequency clock source.

Values:

enumerator MPSL_CLOCK_LF_SRC_RC

LFCLK RC oscillator.

enumerator MPSL_CLOCK_LF_SRC_XTAL

LFCLK crystal oscillator.

enumerator MPSL_CLOCK_LF_SRC_SYNTH

LFCLK Synthesized from HFCLK.

enum mpsl_clock_hfclk_latency_config_t

Values:

enumerator MPSL_CLOCK_HF_LATENCY_BEST
enumerator MPSL_CLOCK_HF_LATENCY_TYPICAL
enumerator MPSL_CLOCK_HF_LATENCY_WORST_CASE

Functions

int32_t mpsl_clock_hfclk_request(mpsl_clock_hfclk_callback_t hfclk_started_callback)

Request the high frequency crystal oscillator.

Will start the high frequency crystal oscillator, the startup time of the crystal varies and the mpsl_clock_hfclk_is_running function can be polled to check if it has started.

See also

mpsl_clock_hfclk_is_running

See also

mpsl_clock_hfclk_release

Note

Don’t use this API if the integration layer of MPSL provides a driver that uses this function. This is the case for applications in the nRF Connect SDK where there is a clock control driver with a corresponding on/off manager.

Parameters:

  • hfclk_started_callback – [in] Function to be called when the high frequency clock is started. The callback will be executed in the context as mpsl_low_priority_process.

Return values:

0 – Success

int32_t mpsl_clock_hfclk_release(void)

Releases the high frequency crystal oscillator.

Indicates that the high frequency crystal oscillator is not needed by the application. MPSL may continue to use the high frequency clock if it is requested by protocol stacks. MPSL will automatically turn it off when it is no longer needed.

See also

mpsl_clock_hfclk_is_running

See also

mpsl_clock_hfclk_request

Note

Don’t use this API if the integration layer of MPSL provides a driver that uses this function. This is the case for applications in the nRF Connect SDK where there is a clock control driver with a corresponding on/off manager.

Return values:

0 – Success

int32_t mpsl_clock_hfclk_is_running(uint32_t *p_is_running)

Checks if the high frequency crystal oscillator is running.

See also

mpsl_clock_hfclk_request

See also

mpsl_clock_hfclk_release

Parameters:

  • p_is_running – [out] 1 if the external crystal oscillator is running, 0 if not.

Return values:

0 – Success

int32_t mpsl_clock_hfclk_latency_set(mpsl_clock_hfclk_latency_config_t mpsl_clock_hfclk_latency_config)

Informs MPSL about the actual ramp-up time of the high-frequency crystal oscillator.

Parameters:

  • mpsl_clock_hfclk_latency_config – [in] Setting for the time it takes for the HFCLK to ramp up.

Return values:
void mpsl_clock_task_trigger_on_rtc_start_set(uint32_t task_address)

Trigger a task upon start of the RTC.

MPSL will trigger the task at the same time as the RTC is started.

Parameters:

  • task_address – [in] The task address to be triggered

struct mpsl_clock_lfclk_cfg_t
#include <mpsl_clock.h>

Type representing LFCLK oscillator source.

Public Members

uint8_t source

LF oscillator clock source, see MPSL_CLOCK_LF_SRC.

uint8_t rc_ctiv

Only for MPSL_CLOCK_LF_SRC_RC. Calibration timer interval in 1/4 second units.

Note

To avoid excessive clock drift, 0.5 degrees Celsius is the maximum temperature change allowed in one calibration timer interval. The interval should be selected to ensure this.

Note

Must be 0 if source is not MPSL_CLOCK_LF_SRC_RC.

uint8_t rc_temp_ctiv

Only for MPSL_CLOCK_LF_SRC_RC. How often (in number of calibration intervals) the RC oscillator shall be calibrated if the temperature hasn’t changed.

  • 0: Always calibrate even if the temperature hasn’t changed.

  • 1-33: Check the temperature and only calibrate if it has changed, however calibration will take place every rc_temp_ctiv intervals in any case.

Note

Must be 0 if source is not MPSL_CLOCK_LF_SRC_RC.

Note

The application must ensure calibration at least once every 8 seconds to ensure +/-500 ppm clock stability. The recommended configuration for MPSL_CLOCK_LF_SRC_RC is given by MPSL_RECOMMENDED_RC_CTIV and MPSL_RECOMMENDED_RC_TEMP_CTIV. This sets the calibration interval to 4 seconds and guarantees clock calibration every second calibration interval. That is, the clock will be calibrated every 8 seconds. If the temperature changes more than 0.5 every 4 seconds, the clock will be calibrated every 4 seconds. See the Product Specification for more information.

uint16_t accuracy_ppm

Accuracy of the low frequency clock in parts per million (ppm). Default value is MPSL_DEFAULT_CLOCK_ACCURACY_PPM.

bool skip_wait_lfclk_started

Determines whether MPSL waits for the low frequency clock to start during initialization or not. If it is set to true, MPSL will wait for the low frequency clock later, before the low frequency clock is used for the first time. Default value is MPSL_DEFAULT_SKIP_WAIT_LFCLK_STARTED.

Note

If this option is set to true and the application writes to NRF_CLOCK->TASKS_LFCLKSTART before mpsl_init() is called, the application shall either:

  • Write to NRF_CLOCK->TASKS_LFCLKSTOP.

  • Keep NRF_CLOCK->EVENTS_LFCLKSTARTED untouched.

MPSL Timeslot

group mpsl_timeslot

The Timeslot interface allows the application to run another radio protocol concurrently with Bluetooth LE activity. When a timeslot is granted, the application has exclusive access to the normally blocked RADIO, TIMER0, CCM, and AAR peripherals. The application can use the peripherals freely for the duration of the timeslot.

Defines

MPSL_TIMESLOT_LENGTH_MIN_US

The shortest allowed timeslot event in microseconds.

MPSL_TIMESLOT_LENGTH_MAX_US

The longest allowed timeslot event in microseconds.

MPSL_TIMESLOT_DISTANCE_MAX_US

The longest timeslot distance in microseconds allowed for the distance parameter see mpsl_timeslot_request_normal_t.

MPSL_TIMESLOT_EARLIEST_TIMEOUT_MAX_US

The longest timeout in microseconds allowed when requesting the earliest possible timeslot.

MPSL_TIMESLOT_START_JITTER_US

The maximum jitter in MPSL_TIMESLOT_SIGNAL_START relative to the requested start time.

MPSL_TIMESLOT_EXTENSION_TIME_MIN_US

The minimum allowed timeslot extension time.

MPSL_TIMESLOT_EXTENSION_PROCESSING_TIME_MAX_US

The maximum processing time to handle a timeslot extension.

MPSL_TIMESLOT_EXTENSION_MARGIN_MIN_US

The latest time before the end of a timeslot when timeslot can be extended.

MPSL_TIMESLOT_CONTEXT_SIZE

Size of a single timeslot context.

MPSL_TIMESLOT_CONTEXT_COUNT_MAX

Maximum number of timeslot sessions.

Typedefs

typedef uint8_t mpsl_timeslot_session_id_t

The timeslot session id type.

typedef mpsl_timeslot_signal_return_param_t *(*mpsl_timeslot_callback_t)(mpsl_timeslot_session_id_t session_id, uint32_t signal)

The timeslot signal callback type.

Note

In case of invalid return parameters, the timeslot will automatically end immediately after returning from the signal callback and the MPSL_TIMESLOT_SIGNAL_INVALID_RETURN event will be sent.

Note

The returned struct pointer must remain valid after the signal callback function returns. For instance, this means that it must not point to a stack variable.

Param session_id:

[in] Session id as returned by mpsl_timeslot_session_open.

Param signal:

[in] Type of signal, see MPSL_TIMESLOT_SIGNAL.

Return:

Pointer to structure containing action requested by the application.

Enums

enum MPSL_TIMESLOT_SIGNAL

The timeslot signal types.

Values:

enumerator MPSL_TIMESLOT_SIGNAL_START

This signal indicates the start of the timeslot. The signal will be executed in the same context as MPSL_IRQ_TIMER0_Handler.

enumerator MPSL_TIMESLOT_SIGNAL_TIMER0

This signal indicates the TIMER0 interrupt. The signal will be executed in the same context as MPSL_IRQ_TIMER0_Handler.

enumerator MPSL_TIMESLOT_SIGNAL_RADIO

This signal indicates the RADIO interrupt. The signal will be executed in the same context as MPSL_IRQ_RADIO_Handler.

enumerator MPSL_TIMESLOT_SIGNAL_EXTEND_FAILED

This signal indicates extend action failed. The signal will be executed in the same context as the previous signal.

enumerator MPSL_TIMESLOT_SIGNAL_EXTEND_SUCCEEDED

This signal indicates extend action succeeded. The signal will be executed in the same context as the previous signal.

enumerator MPSL_TIMESLOT_SIGNAL_BLOCKED

The previous request was blocked. The signal will be executed in the same context as mpsl_low_priority_process.

enumerator MPSL_TIMESLOT_SIGNAL_CANCELLED

The previous request was cancelled. The signal will be executed in the same context as mpsl_low_priority_process.

enumerator MPSL_TIMESLOT_SIGNAL_SESSION_IDLE

The timeslot session has no more pending requests. The signal will be executed in the same context as mpsl_low_priority_process.

enumerator MPSL_TIMESLOT_SIGNAL_INVALID_RETURN

The previous timeslot callback return value was invalid. The signal will be executed in the same context as the previous signal which had an invalid return value. The application should avoid to continuously provide invalid return values. Doing so, will lead to an infinite loop.

enumerator MPSL_TIMESLOT_SIGNAL_SESSION_CLOSED

The session has been closed.

enumerator MPSL_TIMESLOT_SIGNAL_OVERSTAYED

The timeslot event was closed too late. An assert will be triggered after the processing of this signal completes.

enum MPSL_TIMESLOT_SIGNAL_ACTION

The actions requested by the signal callback.

This code gives instructions about what action to take when the signal callback has returned.

Note

For signals executed in low priority returning any action other than MPSL_TIMESLOT_SIGNAL_ACTION_NONE will result in an assert.

Values:

enumerator MPSL_TIMESLOT_SIGNAL_ACTION_NONE

Return without action.

enumerator MPSL_TIMESLOT_SIGNAL_ACTION_EXTEND

Request an extension of the current timeslot event. Maximum execution time for this action: MPSL_TIMESLOT_EXTENSION_PROCESSING_TIME_MAX_US. This action must be started at least MPSL_TIMESLOT_EXTENSION_MARGIN_MIN_US before the end of a timeslot event.

Note

This signal action may only be used from within a timeslot event.

enumerator MPSL_TIMESLOT_SIGNAL_ACTION_END

End the current timeslot event.

Note

This signal action may only be called from within a timeslot event.

enumerator MPSL_TIMESLOT_SIGNAL_ACTION_REQUEST

Request a new timeslot event.

Note

If this signal action is used from within a timeslot, the current timeslot event is closed.

enum MPSL_TIMESLOT_HFCLK_CFG

Timeslot high frequency clock source configuration.

Values:

enumerator MPSL_TIMESLOT_HFCLK_CFG_XTAL_GUARANTEED

The high frequency clock source is the external crystal for the whole duration of the timeslot. This should be the preferred option for events that use the radio or require high timing accuracy.

Note

The external crystal will automatically be turned on and off at the beginning and end of the timeslot.

enumerator MPSL_TIMESLOT_HFCLK_CFG_NO_GUARANTEE

This configuration allows for earlier and tighter scheduling of timeslots. The RC oscillator may be the clock source in part or for the whole duration of the timeslot. The RC oscillator’s accuracy must therefore be taken into consideration.

Note

If the application will use the radio peripheral in timeslots with this configuration, it must ensure that the crystal is running and stable before starting the radio.

enum MPSL_TIMESLOT_PRIORITY

Timeslot event priorities.

Values:

enumerator MPSL_TIMESLOT_PRIORITY_HIGH

High priority.

enumerator MPSL_TIMESLOT_PRIORITY_NORMAL

Low priority.

enum MPSL_TIMESLOT_REQUEST_TYPE

Timeslot request type.

Values:

enumerator MPSL_TIMESLOT_REQ_TYPE_EARLIEST

Request timeslot as early as possible. This should always be used for the first request in a session.

Note

It is not permitted to request an earliest timeslot from within a timeslot.

enumerator MPSL_TIMESLOT_REQ_TYPE_NORMAL

Normal timeslot request.

Functions

int32_t mpsl_timeslot_session_count_set(void *p_mem, uint8_t n_sessions)

Set or update the MPSL timeslot configuration.

Note

Resource configuration can only be performed when all timeslots are closed.

Parameters:

  • p_mem – [in] Pointer to a memory location for timeslot sessions. The size of the memory block needs to be at least n_sessions * MPSL_TIMESLOT_CONTEXT_SIZE bytes. The memory needs to reside in RAM. The pointer needs to be aligned to a 4-byte boundary.

  • n_sessions – [in] Number of timeslot sessions. Maximum number of supported timeslot sessions is MPSL_TIMESLOT_CONTEXT_COUNT_MAX.

Return values:

  • 0 – The configuration was applied successfully.

  • -NRF_EPERM – Timeslots need to be configured when no timeslots are open.

  • -NRF_EINVAL – Invalid argument provided.

  • -NRF_EFAULT – The memory is not aligned to a 4-byte boundary.

int32_t mpsl_timeslot_session_open(mpsl_timeslot_callback_t mpsl_timeslot_signal_callback, mpsl_timeslot_session_id_t *p_session_id)

Opens a session for timeslot requests.

Note

Only one session can be open at a time.

Note

mpsl_timeslot_signal_callback(MPSL_TIMESLOT_SIGNAL_START) will be called when the timeslot starts. From this point the RADIO, TIMER0, AAR, and CCM peripherals can be freely accessed by the application.

Note

mpsl_timeslot_signal_callback(MPSL_TIMESLOT_SIGNAL_TIMER0) is called whenever the TIMER0 interrupt occurs.

Note

mpsl_timeslot_signal_callback(MPSL_TIMESLOT_SIGNAL_RADIO) is called whenever the RADIO interrupt occurs.

Note

If the low frequency clock is not running when this function is called, the function will wait until the low frequency clock has started. See mpsl_clock_lfclk_cfg_t::skip_wait_lfclk_started.

Parameters:

  • mpsl_timeslot_signal_callback – [in] The signal callback.

  • p_session_id – [out] Pointer to the id of the session that was opened.

Return values:

  • 0 – Request was successful.

  • -NRF_ENOMEM – All sessions are already open.

int32_t mpsl_timeslot_session_close(mpsl_timeslot_session_id_t session_id)

Closes a session for timeslot requests.

Note

Any current timeslot will be finished before the session is closed.

Note

If a timeslot is scheduled when the session is closed, it will be canceled.

Parameters:
Return values:

  • 0 – Success

  • -NRF_EAGAIN – Session already closed

int32_t mpsl_timeslot_request(mpsl_timeslot_session_id_t session_id, mpsl_timeslot_request_t const *p_request)

Requests a timeslot.

Note

The first request in a session must always be of type MPSL_TIMESLOT_REQ_TYPE_EARLIEST.

Note

Successful requests will result in mpsl_timeslot_signal_callback_t(MPSL_TIMESLOT_SIGNAL_START). Unsuccessful requests will result in a MPSL_TIMESLOT_SIGNAL_BLOCKED event.

Note

The jitter in the start time of the timeslots is +/- MPSL_TIMESLOT_START_JITTER_US us.

Note

The mpsl_timeslot_signal_callback_t(MPSL_TIMESLOT_SIGNAL_START) call has a latency relative to the specified timeslot start, but this does not affect the actual start time of the timeslot.

Note

TIMER0 is reset at the start of the timeslot, and is clocked at 1MHz from the high frequency (16 MHz) clock source

Note

No stack will neither access the RADIO peripheral nor the TIMER0 peripheral during the timeslot.

Parameters:

  • session_id – [in] The session identifier as returned by mpsl_timeslot_session_open.

  • p_request – [in] Pointer to the request parameters.

Return values:

  • 0 – Success

  • -NRF_EINVAL – The parameters of p_request are not valid

  • -NRF_ENOENT – The session is not open.

  • -NRF_EAGAIN – The session is not IDLE.

struct mpsl_timeslot_request_earliest_t
#include <mpsl_timeslot.h>

Parameters for a request for a timeslot as early as possible.

Public Members

uint8_t hfclk

High frequency clock source, see MPSL_TIMESLOT_HFCLK_CFG.

uint8_t priority

The timeslot priority, see MPSL_TIMESLOT_PRIORITY.

uint32_t length_us

The timeslot length,

See also

MPSL_TIMESLOT_LENGTH_MIN_US,

See also

MPSL_TIMESLOT_LENGTH_MAX_US.

uint32_t timeout_us

Longest acceptable delay until the start of the requested timeslot, up to MPSL_TIMESLOT_EARLIEST_TIMEOUT_MAX_US microseconds.

struct mpsl_timeslot_request_normal_t
#include <mpsl_timeslot.h>

Parameters for a normal timeslot request.

Public Members

uint8_t hfclk

High frequency clock source, see MPSL_TIMESLOT_HFCLK_CFG.

uint8_t priority

The timeslot priority, see MPSL_TIMESLOT_PRIORITY.

uint32_t distance_us

Distance from the start of the previous timeslot up to MPSL_TIMESLOT_DISTANCE_MAX_US microseconds.

uint32_t length_us

The timeslot length,

See also

MPSL_TIMESLOT_LENGTH_MIN_US,

See also

MPSL_TIMESLOT_LENGTH_MAX_US.

struct mpsl_timeslot_request_t
#include <mpsl_timeslot.h>

Timeslot request parameters.

Public Members

uint8_t request_type

Type of request, see MPSL_TIMESLOT_REQUEST_TYPE.

mpsl_timeslot_request_earliest_t earliest

Parameters for requesting a timeslot as early as possible.

mpsl_timeslot_request_normal_t normal

Parameters for requesting a normal timeslot.

union mpsl_timeslot_request_t.[anonymous] params

Union containing parameters for the request specified.

struct mpsl_timeslot_signal_return_param_t
#include <mpsl_timeslot.h>

Return parameters of the timeslot signal callback.

Public Members

uint8_t callback_action

The action requested by the application when returning from the signal callback, see MPSL_TIMESLOT_SIGNAL_ACTION.

mpsl_timeslot_request_t *p_next

The request parameters for the next timeslot.

struct mpsl_timeslot_signal_return_param_t.[anonymous].[anonymous] request

Additional parameters for return_code MPSL_TIMESLOT_SIGNAL_ACTION_REQUEST.

uint32_t length_us

Requested extension of the timeslot duration. The minimum time is MPSL_TIMESLOT_EXTENSION_TIME_MIN_US).

struct mpsl_timeslot_signal_return_param_t.[anonymous].[anonymous] extend

Additional parameters for return_code MPSL_TIMESLOT_SIGNAL_ACTION_EXTEND.

union mpsl_timeslot_signal_return_param_t.[anonymous] params

Parameter union.

MPSL TX Power

group mpsl_tx_power

The MPSL TX Power interface provides APIs to set the maximum TX power per channel.

Defines

MPSL_TOTAL_NUM_OF_BLE_CHANNELS

The number of channels for Bluetooth LE protocol.

MPSL_TOTAL_NUM_OF_802154_CHANNELS

The number of channels for 802.15.4 protocol.

Typedefs

typedef int8_t mpsl_tx_power_t

TX power, dBm.

Enums

enum mpsl_phy_t

PHYs supported for limiting channel TX power.

Values:

enumerator MPSL_PHY_BLE_1M
enumerator MPSL_PHY_BLE_2M
enumerator MPSL_PHY_BLE_LR125Kbit
enumerator MPSL_PHY_BLE_LR500Kbit
enumerator MPSL_PHY_Ieee802154_250Kbit

Functions

int32_t mpsl_tx_power_channel_map_set(const mpsl_tx_power_envelope_t *const p_envelope)

Sets maximum TX power envelope. If the PHY already has an envelope configured, it will be over-written.

Note

Calling this function while an envelope is being used to limit current TX Power may lead to undefined behavior.

Note

The memory for the provided envelope is not copied and must be valid until it is replaced with another envelope for the same PHY.

Parameters:

  • p_envelope – [in] The pointer to an envelope, if NULL the envelopes for all PHYs are reset to maximum power possible.

Return values:

  • 0 – TX power channel successfully set.

  • -NRF_EINVAL – Invalid parameter provided.

mpsl_tx_power_t mpsl_tx_power_radio_supported_power_adjust(mpsl_tx_power_t req_radio_power, int8_t tx_power_ceiling)

Adjusts TX power to a value supported by the RADIO peripheral.

Parameters:

  • req_radio_power – [in] Requested TX power desired for RADIO peripheral.

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

Returns:

RADIO TX power that is supported by the RADIO peripheral. If req_radio_power is less than the minimum TX power supported, the minimum supported TX power is returned. If req_radio_power is more than the maximum TX power supported, the maximum supported TX power is returned. Otherwise the closest supported value that is, depending on tx_power_ceiling, less or more, or equal to req_radio_power is returned.

uint32_t mpsl_tx_power_dbm_to_radio_register_convert(mpsl_tx_power_t req_radio_power)

Converts radio power in dBm to RADIO.TXPOWER register code.

Parameters:

  • req_radio_power – [in] Requested TX power desired for RADIO peripheral. The power value in dBm must be supported by the RADIO peripheral.

Returns:

RADIO.TXPOWER register code corresponding to radio power in dBm.

struct mpsl_tx_power_envelope_t
#include <mpsl_tx_power.h>

Max TX power envelope. It is up to the application to allocate memory for an envelope.

Public Members

mpsl_phy_t phy

The PHY that this envelope applies to.

mpsl_tx_power_t tx_power_ble[40]

Tx power per channel when mpsl_tx_power_envelope_t::phy is a Bluetooth LE PHY.

mpsl_tx_power_t tx_power_802154[16]

Tx power per channel when mpsl_tx_power_envelope_t::phy is a 802.15.4 PHY.

union mpsl_tx_power_envelope_t.[anonymous] envelope

Array of maximum TX power value per channel. From 11 to 26 for 802.15.4 protocol. From 0 to 40 for Bluetooth LE protocol.

MPSL FEM

group mpsl_fem

This module provides the interface for the protocols to use PA, LNA, or both in the radio transmission and the radio reception. Refer to the README.rst for the details.

Defines

MPSL_FEM_CAPS_FLAG_PA_SETUP_REQUIRED

PA setup is required before starting a transmission.

This flag applies to mpsl_fem_caps_t::flags.

If it is set, then mpsl_fem_pa_configuration_set must be called before transmission starts.

MPSL_FEM_CAPS_FLAG_LNA_SETUP_REQUIRED

LNA setup is required before starting a reception.

This flag applies to mpsl_fem_caps_t::flags.

If it is set, then mpsl_fem_lna_configuration_set must be called before reception starts.

Typedefs

typedef uint8_t mpsl_subscribable_hw_event_t

Type representing a multiple-subscribable hardware event.

For nRF52 series this is an address of an event within a peripheral. This event can be written to EEP register of a PPI channel, to make the PPI channel be driven by the event. For nRF52 series an event can be published to multiple PPI channels by hardware design, which makes it possible for multiple tasks to subscribe to it.

For nRF53 series, this is a number of a DPPI channel which is configured in such a way that certain event publishes to the DPPI channel and the DPPI channel is enabled. Ensuring above is responsibility of a user of the provided API. Multiple tasks can then subscribe to the DPPI channel (by hardware design), thus indirectly to the event.

Enums

enum mpsl_fem_functionality_t

PA and LNA functionality types.

Values:

enumerator MPSL_FEM_PA

PA Functionality.

enumerator MPSL_FEM_LNA

LNA Functionality.

enumerator MPSL_FEM_ALL

Both PA and LNA Functionalities.

enum mpsl_fem_event_type_t

PA and LNA activation event types.

Values:

enumerator MPSL_FEM_EVENT_TYPE_TIMER

Timer Event type.

enumerator MPSL_FEM_EVENT_TYPE_GENERIC

Generic Event type.

Functions

void mpsl_fem_caps_get(mpsl_fem_caps_t *p_caps)

Gets the capabilities of the FEM in use.

Parameters:

  • p_caps – [out] Pointer to the capabilities structure to be filled in.

int32_t mpsl_fem_disable(void)

Disable Front End Module.

Some Front End Module devices can be explicitly disabled after PA and LNA activities are finished to preserve power.

This function is intended to disable Front End Module shortly after radio operations are finished and the protocol does not expect more radio activities in short future, or passes radio control to other protocols in the system.

Front End Module disabling process is synchronous and immediate.

Return values:

  • 0 –

  • -NRF_EPERM – FEM is configured to enable PA or LNA.

int32_t mpsl_fem_pa_configuration_set(const mpsl_fem_event_t *const p_activate_event, const mpsl_fem_event_t *const p_deactivate_event)

Sets up PA using the provided events for the upcoming radio transmission.

Multiple configurations can be provided by repeating calls to this function (that is, you can set the activate and the deactivate events in multiple calls, and the configuration is preserved between calls).

The order of calls of this function and its lna counterpart must match the order of radio operations. I.e. if you want to listen first and then send the frame, you need first to issue mpsl_fem_lna_configuration_set and only after mpsl_fem_pa_configuration_set.

If a MPSL_FEM_EVENT_TYPE_TIMER timer event is provided, the PA will be configured to activate or deactivate at the application-configured time gap before the timer instance reaches the given register_value. The time gap is set via the corresponding configuration setter of the selected Front End Module.

If a MPSL_FEM_EVENT_TYPE_GENERIC event is provided, the PA will be configured to activate or deactivate when an event occurs.

The function sets up the PPIs and the GPIOTE channel to activate PA for the upcoming radio transmission. The PA pin will be active until deactivated, which can happen either by encountering a configured deactivation event or by using mpsl_fem_deactivate_now.

Note

If a timer event is provided, the caller of this function is responsible for starting the timer and configuring its shorts. Moreover, the caller is responsible for stopping the timer no earlier than the compare channel of the lowest ID among the provided ones does expire.

Note

The activation event can be only of type MPSL_FEM_EVENT_TYPE_TIMER. Using other activation event type leads to undefined module behavior.

Parameters:

  • p_activate_event – [in] Pointer to the activation event structure.

  • p_deactivate_event – [in] Pointer to the deactivation event structure.

Return values:

  • 0 – PA activation setup is successful.

  • -NRF_EPERM – PA is currently disabled.

  • -NRF_EINVAL – PA activation setup could not be performed due to invalid or missing configuration parameters in p_activate_event or p_deactivate_event, or both.

Pre:

To activate PA, the corresponding configuration setter of the selected Front End Module must have been called first.

int32_t mpsl_fem_pa_configuration_clear(void)

Clears up the configuration provided by the mpsl_fem_pa_configuration_set function.

Return values:

  • 0 – PA activation setup purge is successful.

  • -NRF_EPERM – PA is currently disabled.

int32_t mpsl_fem_lna_configuration_set(const mpsl_fem_event_t *const p_activate_event, const mpsl_fem_event_t *const p_deactivate_event)

Sets up LNA using the provided event for the upcoming radio reception.

Multiple configurations can be provided by repeating calls to this function (that is, you can set the activate and the deactivate event in multiple calls, and the configuration is preserved between calls).

The order of calls of this function and its pa counterpart must match the order of radio operations. I.e. if you want to listen first and then send the frame, you need first to issue mpsl_fem_lna_configuration_set and only after mpsl_fem_pa_configuration_set.

If a MPSL_FEM_EVENT_TYPE_TIMER timer event is provided, the LNA will be configured to activate or deactivate at the application-configured time gap before the timer instance reaches the given register_value. The time gap is set via the corresponding configuration setter of the selected Front End Module.

If a MPSL_FEM_EVENT_TYPE_GENERIC event is provided, the LNA will be configured to activate or deactivate when an event occurs.

The function sets up the PPIs and the GPIOTE channel to activate LNA for the upcoming radio transmission. The LNA pin will be active until deactivated, which can happen either by encountering a configured deactivation event or by using mpsl_fem_deactivate_now.

Note

If a timer event is provided, the caller of this function is responsible for starting the timer and configuring its shorts. Moreover, the caller is responsible for stopping the timer no earlier than the compare channel of the lowest ID among the provided ones does expire.

Note

The activation event can be only of type MPSL_FEM_EVENT_TYPE_TIMER. Using other activation event type leads to undefined module behavior.

Parameters:

  • p_activate_event – [in] Pointer to the activation event structure.

  • p_deactivate_event – [in] Pointer to the deactivation event structure.

Return values:

  • 0 – LNA activation setup is successful.

  • -NRF_EPERM – LNA is currently disabled.

  • -NRF_EINVAL – LNA activation setup could not be performed due to invalid or missing configuration parameters in p_activate_event or p_deactivate_event, or both.

Pre:

To activate LNA, the corresponding configuration setter of the selected Front End Module must have been called first.

int32_t mpsl_fem_lna_configuration_clear(void)

Clears up the configuration provided by the mpsl_fem_lna_configuration_set function.

Return values:

  • 0 – LNA activate setup purge is successful.

  • -NRF_EPERM – LNA is currently disabled.

void mpsl_fem_deactivate_now(mpsl_fem_functionality_t type)

Deactivates PA/LNA with immediate effect.

Deactivates PA/LNA with immediate effect - contrary to mpsl_fem_lna_configuration_clear or mpsl_fem_pa_configuration_clear, which both just set up the infrastructure for events which shall disable the PA/LNA.

Parameters:
int32_t mpsl_fem_abort_set(mpsl_subscribable_hw_event_t event, uint32_t group)

Instruct Front End Module to disable PA and LNA as soon as possible using the group following the event.

Parameters:

  • event – [in] An event which is triggered when the abort condition occurs. (See doc for mpsl_subscribable_hw_event_t type.)

  • group – [in] (D)PPI Group which shall be disabled when the abort event is triggered.

Return values:

  • 0 – Setting of the abort sequence path is successful.

  • -NRF_EPERM – Setting of the abort sequence path could not be performed.

int32_t mpsl_fem_abort_extend(uint32_t channel_to_add, uint32_t group)

Adds one more PPI channel to the PPI Group prepared by the mpsl_fem_abort_set function.

Parameters:

  • channel_to_add – [in] (D)PPI channel to add to the (D)PPI group.

  • group – [in] The said PPI group.

Return values:

  • 0 – Setting of the abort sequence path is successful.

  • -NRF_EPERM – Setting of the abort sequence path could not be performed.

int32_t mpsl_fem_abort_reduce(uint32_t channel_to_remove, uint32_t group)

Removes one PPI channel from the PPI Group prepared by the mpsl_fem_abort_set function.

Parameters:

  • channel_to_remove – [in] (D)PPI channel to remove from the (D)PPI group.

  • group – [in] The said PPI group.

Return values:

  • 0 – Setting of the abort sequence path is successful.

  • -NRF_EPERM – Setting of the abort sequence path could not be performed.

int32_t mpsl_fem_abort_clear(void)

Clears up the configuration provided by the mpsl_fem_abort_set function.

Return values:

  • 0 – Clearing of the abort sequence path is successful.

  • -NRF_EPERM – Clearing was not done - the possible reason is that there was nothing to clear.

void mpsl_fem_cleanup(void)

Cleans up the configured PA/LNA hardware resources.

The function resets the hardware that has been set up for the PA/LNA activation. The PA and LNA module control configuration parameters are not deleted. The function is intended to be called after the radio DISABLED signal.

int8_t mpsl_fem_tx_power_split(const mpsl_tx_power_t power, mpsl_tx_power_split_t *const p_tx_power_split, uint16_t freq_mhz, bool tx_power_ceiling)

Splits transmit power value into components to be applied on each stage on transmit path.

Note

If the exact value of power cannot be achieved, this function attempts to either use available level lower than the requested level to not exceed constraint, or use the lowest available level greater than the requested level, depending on tx_power_ceiling.

Parameters:

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

  • p_tx_power_split – [out] Components of tx_power to be applied for stages on transmit path. If requested power is too high, the split will be set to a value representing maximum achievable power. If the requested power is too low, the split will be set to a value representing minimum achievable power.

  • freq_mhz – [in] Frequency in MHz to calculate the split for.

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

Returns:

The power in dBm that will be achieved if values returned through p_tx_power_split are applied.

int32_t mpsl_fem_pa_power_control_set(mpsl_fem_pa_power_control_t pa_power_control)

Sets the PA power control.

Setting the PA power control informs the FEM implementation how the PA is to be controlled before the next transmission.

The PA power control set by this function is to be applied to control signals or parameters. What signals and parameters are controlled and how does it happen depends on implementation of given FEM. The meaning of pa_power_control parameter is fully FEM type-dependent. For FEM type-independent protocol implementation please use the function mpsl_fem_tx_power_split and provide outcome of this function returned by the parameter p_tx_power_split to the call to mpsl_fem_pa_power_control_set. For applications intended for testing the FEM itself when mpsl_fem_tx_power_split is not used you must make the pa_power_control parameter on your own.

Note

The PA power control set by this function will be applied to radio transmissions following the call. If the function is called during radio transmission or during ramp-up for transmission it is unspecified if the control is applied.

Parameters:

  • pa_power_control – [in] PA power control to be applied to the FEM.

Return values:

  • 0 – PA power control has been applied successfully.

  • -NRF_EINVAL – PA power control could not be applied. Provided pa_power_control is invalid.

void mpsl_fem_lna_is_configured(int8_t *const p_gain)

Returns LNA gain if the LNA signal is configured and enabled, 0 otherwise.

Parameters:

  • p_gain – [out] The configured gain in dB if LNA is configured and enabled. If there is no LNA present or the LNA does not affect the signal gain, returns 0 dB.

bool mpsl_fem_prepare_powerdown(NRF_TIMER_Type *p_instance, uint32_t compare_channel, uint32_t ppi_id, uint32_t event_addr)

Prepares the Front End Module to switch to the Power Down state.

Deprecated:

This function is deprecated. Use mpsl_fem_disable instead.

This function makes sure the Front End Module shall be switched off in the appropriate time, using the hardware timer and its compare channel. The timer is owned by the protocol and must be started by the protocol. The timer stops after matching the provided compare channel (the call sets the short).

Parameters:

  • p_instance – [in] Timer instance that is used to schedule the transition to the Power Down state.

  • compare_channel – [in] Compare channel to hold a value for the timer.

  • ppi_id – [in] ID of the PPI channel used to switch to the Power Down state.

  • event_addr – [in] Address of the event which shall trigger the Timer start.

Return values:

  • true – Whether the scheduling of the transition was successful.

  • false – Whether the scheduling of the transition was not successful.

struct mpsl_fem_event_t
#include <mpsl_fem_protocol_api.h>

MPSL Front End Module event.

Public Members

mpsl_fem_event_type_t type

Type of event source.

NRF_TIMER_Type *p_timer_instance

Pointer to a 1-us resolution timer instance.

uint32_t start

Timer value when the Front End Module can start preparing PA/LNA.

uint32_t end

Timer value at which the PA/LNA have to be prepared. Radio operation shall start at this point.

struct mpsl_fem_event_t.[anonymous].[anonymous].[anonymous] counter_period

Counter period parameters

uint8_t compare_channel_mask

Mask of the compare channels that can be used by the Front End Module to schedule its own tasks.

struct mpsl_fem_event_t.[anonymous].[anonymous] timer

Parameters when type is MPSL_FEM_EVENT_TYPE_TIMER.

mpsl_subscribable_hw_event_t event

Event triggering required FEM operation.

struct mpsl_fem_event_t.[anonymous].[anonymous] generic

Parameters when type is MPSL_FEM_EVENT_TYPE_GENERIC.

union mpsl_fem_event_t.[anonymous] event

Implementation of the event.

struct mpsl_tx_power_split_t
#include <mpsl_fem_protocol_api.h>

Represents components of tx_power to be applied for stages on transmit path.

Public Members

mpsl_tx_power_t radio_tx_power

TX power to be applied to the RADIO peripheral.

mpsl_fem_pa_power_control_t fem_pa_power_control

FEM PA power control.

struct mpsl_fem_caps_t
#include <mpsl_fem_protocol_api.h>

Structure representing capabilities and characteristics of the FEM in use.

Public Members

uint32_t flags

Flags informing about the FEM in use.

The following flags apply: MPSL_FEM_CAPS_FLAG_PA_SETUP_REQUIRED, MPSL_FEM_CAPS_FLAG_LNA_SETUP_REQUIRED

MPSL FEM common configuration

group mpsl_fem_config_common

The MPSL Front End Module Common Configuration defines structures common for every supported Front End Module.

Functions

void mpsl_fem_device_config_254_apply_set(bool apply)

Sets flag which determines whether DEVICE-CONFIG-254 shall be applied.

Note

This function shall be called before initialization of any protocol stack.

Parameters:

  • apply – [in] Whether the DEVICE-CONFIG-254 option shall be applied.

bool mpsl_fem_device_config_254_apply_get(void)

Gets flag which determines whether DEVICE-CONFIG-254 shall be applied.

Return values:

  • true – DEVICE-CONFIG-254 shall be applied.

  • false – DEVICE-CONFIG-254 shall not be applied.

struct mpsl_fem_pin_t
#include <mpsl_fem_config_common.h>

GPIO pin and port to be used by Front End Module.

Public Members

NRF_GPIO_Type *p_port

GPIO port register address.

uint8_t port_no

GPIO port number.

uint8_t port_pin

GPIO pin number relative to the port.

struct mpsl_fem_gpiote_pin_config_t
#include <mpsl_fem_config_common.h>

Configuration parameters for pins that enable or disable (or both) either Power Amplifier (PA) or Low Noise Amplifier (LNA).

Public Members

mpsl_fem_pin_t gpio_pin

GPIO port number, register address and pin number relative to the port.

bool enable

Enable toggling for this pin.

bool active_high

If true, the pin will be active high. Otherwise, the pin will be active low.

uint8_t gpiote_ch_id

The GPIOTE channel used for toggling this pin.

struct mpsl_fem_gpio_pin_config_t
#include <mpsl_fem_config_common.h>

Configuration parameters for pins that enable or disable (or both) either Power Amplifier (PA) or Low Noise Amplifier (LNA).

Public Members

mpsl_fem_pin_t gpio_pin

GPIO port number, register address and pin number relative to the port.

bool enable

Enable toggling for this pin.

bool active_high

If true, the pin will be active high. Otherwise, the pin will be active low.

MPSL FEM common nRF21540 configuration

group mpsl_fem_nrf21540_common

Defines

MPSL_FEM_NRF21540_DEFAULT_PA_TIME_IN_ADVANCE_US

Time in microseconds when PA GPIO is activated before the radio is ready for transmission.

MPSL_FEM_NRF21540_DEFAULT_LNA_TIME_IN_ADVANCE_US

Time in microseconds when LNA GPIO is activated before the radio is ready for reception.

MPSL_FEM_NRF21540_DEFAULT_PDN_SETTLE_US

Time in microseconds between activating the PDN and asserting the RX_EN/TX_EN.

MPSL_FEM_NRF21540_DEFAULT_TRX_HOLD_US

Time in microseconds between deasserting the RX_EN/TX_EN and deactivating PDN.

MPSL_FEM_NRF21540_PA_POUTA_DEFAULT_GAIN_DB

Gain of the PA in dB when using POUTA.

MPSL_FEM_NRF21540_PA_POUTB_DEFAULT_GAIN_DB

Gain of the PA in dB when using POUTB.

MPSL_FEM_NRF21540_PA_DEFAULT_GAIN_DB

Default gain of the PA in dB.

MPSL_FEM_NRF21540_LNA_DEFAULT_GAIN_DB

Gain of the LNA in dB.

struct mpsl_fem_nrf21540_config_t
#include <mpsl_fem_config_nrf21540_common.h>

Configuration structure of the nRF21540 Front End Module.

Public Members

uint32_t pa_time_gap_us

Time in microseconds between the activation of the PA pin and the start of the radio transmission. Should be no bigger than Radio Ramp-Up time.

uint32_t lna_time_gap_us

Time in microseconds between the activation of the LNA pin and the start of the radio reception. Should be no bigger than Radio Ramp-Up time.

uint32_t pdn_settle_us

Time in microseconds between activating the PDN pin and activating the PA/LNA pin.

uint32_t trx_hold_us

Time in microseconds between deactivating the PA/LNA pin and deactivating the PDN pin.

int8_t pa_gain_db

Default PA gain in dB. Ignored if the amplifier is not supporting this feature.

int8_t pa_gains_db[2]

Available PA gains in dB. pa_gains_db[0] corresponds to POUTA and pa_gains_db[1] to POUTB.

int8_t lna_gain_db

Configurable LNA gain in dB. Ignored if the amplifier is not supporting this feature.

MPSL FEM nRF21540 GPIO

group mpsl_fem_nrf21540_gpio

Functions

int32_t mpsl_fem_nrf21540_gpio_interface_config_set(mpsl_fem_nrf21540_gpio_interface_config_t const *const p_config)

Configures the PA and LNA device interface.

This function sets device interface parameters for the PA/LNA module. The module can then be used to control PA or LNA (or both) through the given interface and resources.

The function also sets the PPI and GPIOTE channels to be configured for the PA/LNA interface.

Parameters:

  • p_config – [in] Pointer to the interface parameters for the PA/LNA device.

Return values:

  • 0 – PA/LNA control successfully configured.

  • -NRF_EPERM – PA/LNA control configuration error.

struct mpsl_fem_nrf21540_gpio_interface_config_t
#include <mpsl_fem_config_nrf21540_gpio.h>

Configuration parameters for the Power Amplifier (PA) and Low Noise Amplifier (LNA) interface in the nRF21540 GPIO variant.

Public Members

mpsl_fem_nrf21540_config_t fem_config

nRF21540 parameters configuration.

mpsl_fem_gpiote_pin_config_t pa_pin_config

PA pin configuration.

mpsl_fem_gpiote_pin_config_t lna_pin_config

LNA pin configuration.

mpsl_fem_gpiote_pin_config_t pdn_pin_config

PDN pin configuration.

mpsl_fem_gpio_pin_config_t mode_pin_config

MODE pin configuration. To enable runtime MODE pin switching mode_pin_config.enable must be set to true. The fem_config.pa_gains_db must contain correct values corresponding to POUTA and POUTB gains then.

uint8_t dppi_channels[4]

Array of DPPI channels which need to be provided to Front End Module to operate.

uint8_t egu_instance_no

Number of EGU instance for which egu_channels apply.

uint8_t egu_channels[3]

Array of EGU channels (belonging to EGU instance number egu_instance_no) which need to be provided to Front End Module to operate.

MPSL FEM nRF21540 GPIO/SPI

group mpsl_fem_nrf21540_gpio_spi

Functions

int32_t mpsl_fem_nrf21540_gpio_spi_interface_config_set(mpsl_fem_nrf21540_gpio_spi_interface_config_t const *const p_config)

Configures the PA and LNA device interface.

This function sets device interface parameters for the PA/LNA module. The module can then be used to control PA or LNA (or both) through the given interface and resources.

The function also sets the PPI and GPIOTE channels to be configured for the PA/LNA interface as well as SPI interface to be used.

Parameters:

  • p_config – [in] Pointer to the interface parameters for the PA/LNA device.

Return values:

  • 0 – PA/LNA control successfully configured.

  • -NRF_EPERM – PA/LNA control configuration error.

struct mpsl_fem_spi_config_t
#include <mpsl_fem_config_nrf21540_gpio_spi.h>

SPI interface.

Public Members

NRF_SPIM_Type *p_spim

Pointer to the SPI peripheral instance to be used.

mpsl_fem_pin_t mosi_pin

MOSI pin.

mpsl_fem_pin_t miso_pin

MISO pin.

mpsl_fem_pin_t sck_pin

SCK pin.

mpsl_fem_gpiote_pin_config_t cs_pin_config

CS pin.

struct mpsl_fem_nrf21540_gpio_spi_interface_config_t
#include <mpsl_fem_config_nrf21540_gpio_spi.h>

Configuration parameters for the Power Amplifier (PA), the Low Noise Amplifier (LNA) and the SPI interface in the nRF21540 GPIO/SPI variant.

Public Members

mpsl_fem_nrf21540_config_t fem_config

nRF21540 parameters configuration.

mpsl_fem_gpiote_pin_config_t pa_pin_config

PA pin configuration.

mpsl_fem_gpiote_pin_config_t lna_pin_config

LNA pin configuration.

mpsl_fem_gpiote_pin_config_t pdn_pin_config

PDN pin configuration.

mpsl_fem_gpio_pin_config_t mode_pin_config

MODE pin configuration.

mpsl_fem_spi_config_t spi_config

SPI interface configuration.

uint8_t dppi_channels[6]

Array of DPPI channels which need to be provided to Front End Module to operate.

uint8_t egu_instance_no

Number of EGU instance for which egu_channels apply.

uint8_t egu_channels[5]

Array of EGU channels (belonging to EGU instance number egu_instance_no) which need to be provided to Front End Module to operate.

bool pa_gain_runtime_control

Flag that indicates if PA gain should be changeable in runtime. If this flag is set, fem_config.pa_gains_db must contain correct values corresponding to POUTA and POUTB gains. Otherwise, PA gain is considered constant. In both cases there are SPI transfers performed to the nRF21540, so the SPI interface must be configured and operable.

MPSL FEM Simple GPIO

group mpsl_fem_simple_gpio

Defines

MPSL_FEM_SIMPLE_GPIO_DEFAULT_PA_TIME_IN_ADVANCE_US

Simple GPIO Front End Module Timings.

A Simple GPIO Front End Module may be used with all Front End Modules which use one wire for PA and one wire for LNA. The timing restrictions should be obtained from its corresponding datasheet. Time in microseconds when PA GPIO is activated before the radio is ready for transmission.

MPSL_FEM_SIMPLE_GPIO_DEFAULT_LNA_TIME_IN_ADVANCE_US

Time in microseconds when LNA GPIO is activated before the radio is ready for reception.

MPSL_FEM_SIMPLE_GPIO_PA_DEFAULT_GAIN_DB

Simple GPIO Front End Module Gains.

A Simple GPIO Front End Module may be used with all Front End Modules which use one wire for PA and one wire for LNA. The gains should be obtained from its corresponding datasheet. Gain of the PA in dB.

MPSL_FEM_SIMPLE_GPIO_LNA_DEFAULT_GAIN_DB

Gain of the LNA in dB.

Functions

int32_t mpsl_fem_simple_gpio_interface_config_set(mpsl_fem_simple_gpio_interface_config_t const *const p_config)

Configures the PA and LNA device interface.

This function sets device interface parameters for the PA/LNA module. The module can then be used to control PA or LNA (or both) through the given interface and resources.

The function also sets the PPI and GPIOTE channels to be configured for the PA/LNA interface.

Parameters:

  • p_config – [in] Pointer to the interface parameters for the PA/LNA device.

Return values:

  • 0 – PA/LNA control successfully configured.

  • -NRF_EPERM – PA/LNA is not available.

int32_t mpsl_fem_simple_gpio_interface_config_get(mpsl_fem_simple_gpio_interface_config_t *const p_config)

Returns the PA and LNA device configuration.

This function gets device interface parameters for the PA/LNA module.

If the passed pointer is incorrect, the function returns the error code. If the corresponding setter was not called beforehand, the function returns the error code.

Parameters:

  • p_config – [out] Pointer to the interface parameters for the PA/LNA device to populate.

Return values:

  • 0 – PA/LNA configuration successfully populated.

  • -NRF_EPERM – PA/LNA was not configured beforehand.

struct mpsl_fem_simple_gpio_interface_config_t
#include <mpsl_fem_config_simple_gpio.h>

Configuration parameters for the Front End Module Simple GPIO variant.

A Simple GPIO Front End Module may be used with all Front End Modules which use one wire for a Power Amplifier (PA) and one wire for a Linear Noise Amplifier (LNA).

Public Members

uint32_t pa_time_gap_us

Time between the activation of the PA pin and the start of the radio transmission. Should be no bigger than Radio Ramp-Up time.

uint32_t lna_time_gap_us

Time between the activation of the LNA pin and the start of the radio reception. Should be no bigger than Radio Ramp-Up time.

int8_t pa_gain_db

Configurable PA gain. Ignored if the amplifier is not supporting this feature.

int8_t lna_gain_db

Configurable LNA gain. Ignored if the amplifier is not supporting this feature.

struct mpsl_fem_simple_gpio_interface_config_t.[anonymous] fem_config

Configration structure of the Simple GPIO Front End Module.

mpsl_fem_gpiote_pin_config_t pa_pin_config

Power Amplifier pin configuration.

mpsl_fem_gpiote_pin_config_t lna_pin_config

Low Noise Amplifier pin configuration.

uint8_t dppi_channels[3]

Array of DPPI channels which need to be provided to Front End Module to operate.

uint8_t egu_instance_no

Number of EGU instance for which egu_channels apply.

uint8_t egu_channels[3]

Array of EGU channels (belonging to EGU instance number egu_instance_no) which need to be provided to Front End Module to operate.

MPSL FEM power model

group mpsl_fem_power_model

Typedefs

typedef void (*mpsl_fem_power_model_output_fetch_t)(int8_t requested_power, uint16_t freq_mhz, mpsl_fem_power_model_output_t *p_output, bool tx_power_ceiling)

Pointer to function to be used by MPSL to retrieve the model’s output.

Warning

This function must execute in maximum 2 microseconds in the worst case scenario. Failing to meet this requirement will lead to undefined behavior of the protocol stacks.

Param requested_power:

[in] Requested power on the antenna in dBm.

Param freq_mhz:

[in] Frequency in MHz.

Param p_output:

[out] Output of the model. For details, refer to mpsl_fem_power_model_output_t.

Param tx_power_ceiling:

[in] Flag to get ceiling or floor of requested RADIO TX power level.

typedef void (*mpsl_fem_power_model_init_t)(const mpsl_fem_calibration_data_t *p_calibration_data)

Pointer to function to be used by MPSL to initialize the model.

When MPSL configures interface of the Front-End Module selected by the application, it retrieves and calculates data that might be useful to the power model. When it finishes, MPSL calls this function. As a result, this function can be used to initialize the power model and to utilize the data acquired by MPSL.

Note

This function is called before the main application starts.

Param p_calibration_data:

[in] Pointer to calibration data relevant to the Front-End Module selected by the application. Lifetime of the object behind this pointer is limited to the duration of this function.

Functions

int32_t mpsl_fem_power_model_set(const mpsl_fem_power_model_t *p_model)

Sets Front-End Module power model.

This function sets up the control flow for handling the power model.

If nRF21540 Front-End Module is used, the value returned by mpsl_fem_nrf21540_power_model_builtin_get can be used as p_model. In that case, the built-in model provided by MPSL is used and the application is responsible for triggering the model’s recalculation through mpsl_fem_nrf21540_power_model_builtin_update. If the model is not updated as external conditions change, it will output inaccurate data.

In all other cases, if p_model is not NULL, custom model provided by the application is used. In that case, the application is responsible for maintaining the model out of scope of MPSL. Calling mpsl_fem_nrf21540_power_model_builtin_update is then pointless.

If p_model equal NULL is passed to the function, the call is treated as a request to not use any model.

Note

This function must be called before mpsl_fem_nrf21540_gpio_spi_interface_config_set, mpsl_fem_nrf21540_gpio_interface_config_set or mpsl_fem_simple_gpio_interface_config_set, depending on which one is called to select appropriate Front-End Module driver.

Parameters:

  • p_model – [in] Pointer to the model to be used by MPSL.

Return values:

  • -NRF_EINVAL – Provided pointer is invalid.

  • 0 – The model has been initialized successfully.

void mpsl_fem_nrf21540_power_model_builtin_update(const mpsl_fem_external_conditions_t *p_environment)

Update the built-in nRF21540 model using provided parameters.

For given values of p_environment, this function populates the contents of an internally stored, built-in MPSL nRF21540 power model.

If the value of parameter passed to mpsl_fem_power_model_set was different than the return value of mpsl_fem_nrf21540_power_model_builtin_get, this function does nothing.

Note

This function takes a significant amount of time to execute (approximately 5ms). Calling it from high priority contexts might lead to degraded performance or starving other contexts of the application.

Parameters:

  • p_environment – [in] Pointer to a structure that holds current external conditions to recalculate the model for.

const mpsl_fem_power_model_t *mpsl_fem_nrf21540_power_model_builtin_get(void)

Get the pointer to the built-in nRF21540 model.

The pointer returned by this function can be used as a parameter to mpsl_fem_power_model_set that results in the built-in model being selected.

Returns:

Pointer to the internal, built-in nRF21540 model.

struct mpsl_fem_power_model_output_t
#include <mpsl_fem_power_model.h>

Decomposition of a single value of output power on the antenna.

Public Members

int8_t soc_pwr

SoC power in dBm. When returned by a model, this field is expected to contain value supported by the SoC that can safely be applied directly to RADIO registers.

mpsl_fem_pa_power_control_t fem_pa_power_control

PA power control to be applied to the FEM.

This value is FEM type-dependent. The produced value is to be passed to the call to mpsl_fem_pa_power_control_set.

int8_t achieved_pwr

Achieved power on the antenna in dBm.

struct mpsl_fem_power_model_t
#include <mpsl_fem_power_model.h>

Front-End Module power model.

This structure contains data that the application must pass to MPSL in case it provides a custom model for power decomposition between SoC and nRF21540.

Public Members

mpsl_fem_power_model_output_fetch_t fetch

Pointer to function to be used to retrieve the model’s output. This function can be called from high priority interrupts. It can preempt update of model parameters, which is expected to be executed in lower priority contexts.

mpsl_fem_power_model_init_t init

Pointer to function to be used to initialize the model. If NULL, no function will be called when the Front-End Module driver is initialized. It is assumed that it is safe to call the fetch method without any additional actions.

struct mpsl_fem_external_conditions_t
#include <mpsl_fem_power_model.h>

External conditions that affect Front-End Module’s power model.

Public Members

int8_t temperature

Temperature in degrees Celsius.

uint8_t voltage

Voltage in units of 0.1 Volt.

MPSL CX (Coexistence)

group mpsl_cx

This module provides the interface for the protocols to communicate with a coexistence arbitrator, Packet Traffic Arbitrator, PTA.

Concurrency model of this module: Each function defined in this interface may be called from any execution context (thread, including preemptive thread in operating system, or handler). However, none of the functions is re-entrant. It is responsibility of API user to ensure that even if one function is preempted by other execution context, the other execution context does not call preempted function.

It is not allowed to call a function defined in this module while the same function is called from another preempted context. It is allowed to call any function defined in this module while any other is preempted. It is allowed to call any function defined in this module from mpsl_cx_cb_t implementation. Callback function mpsl_cx_cb_t called from this module may be called from thread or handler context. But it never preempts itself.

Typedefs

typedef uint8_t mpsl_cx_op_map_t

Bitmap representing a list of radio operations.

Logical OR of radio operations defined in mpsl_cx_op_t.

typedef uint8_t mpsl_cx_prio_t

Priority of given radio operation.

This numerical value is translated by given PTA interface driver to appropriate signal. The straightforward translation would be <= UINT8_MAX/2 is low priority, while > UINT8_MAX/2 is high priority. More complicated PTAs support more than 2 priority levels and valid matching must be implemented for such devices.

Priority values must be aligned between all users of this API in given system. When multiple radio protocols are enabled (like Bluetooth LE and IEEE 802.15.4), all protocols must use aligned values (Bluetooth low priority operations must use numerically lower value than IEEE 802.15.4 high priority operations).

typedef void (*mpsl_cx_cb_t)(mpsl_cx_op_map_t granted_ops)

Callback used to notify radio protocol about changes of granted radio operations.

Param granted_ops:

[in] List of all operations currently allowed by PTA.

Enums

enum mpsl_cx_op_t

Radio operations which may be requested from or granted by PTA.

Values:

enumerator MPSL_CX_OP_IDLE_LISTEN

Listening for asynchronous transmissions

enumerator MPSL_CX_OP_RX

Active reception

This value may be used to indicate:

  • RX window:

    • in BLE connection event

    • 802.15.4 CSL

    • …

  • Detected a frame transmitted asynchronously:

    • during BLE scanning

    • during 802.15.4 idle listening

    • …

enumerator MPSL_CX_OP_TX

Active transmission

enum mpsl_cx_req_trig_t

Coexistence request signal triggers.

Values:

enumerator MPSL_CX_REQ_TRIG_INSTANT

Request is triggered instantly, during mpsl_cx_request call.

Functions

int32_t mpsl_cx_request(const mpsl_cx_request_t *p_req_params)

Request radio operation from PTA.

This function is to be called before transceiver is enabled to inform PTA about planned radio operation which is about to start and about the priority of this operation.

Each call of this function overrides the last request.

This function is usually called shortly before scheduled radio operations, or just after detection of asynchronous events indicating radio operations.

Call to this function cannot preempt a call to mpsl_cx_release. It is responsibility of user of this interface to prevent such preemption.

Parameters:

  • p_req_params – [in] Pointer to a structure containing parameters of given request.

Return values:

  • 0 – Requested radio operation from PTA

  • -EINVAL – Incorrect value of any field in p_req_params or p_req_params is NULL.

int32_t mpsl_cx_release(void)

Release last radio operation requested from PTA.

This function is to be called after transceiver is disabled to inform PTA that any previously requested operations by mpsl_cx_request are not requested anymore.

This function releases requested radio operations immediately.

Call to this function cannot preempt a call to mpsl_cx_request. It is responsibility of user of this interface to prevent such preemption.

Return values:

  • 0 – Last request is released.

  • -EALREADY – There was no request to release.

int32_t mpsl_cx_granted_ops_get(mpsl_cx_op_map_t *p_granted_ops)

Get list of radio operations currently granted by PTA.

Note

PTA may change granted radio operations list at any time. It is possible that value returned by this function is outdated before the function ends its execution.

Parameters:

  • p_granted_ops – [out] Map of granted radio operations.

Return values:

  • 0 – List of granted radio operations is stored in the passed memory address.

  • -EINVAL – granted_ops is NULL pointer.

uint32_t mpsl_cx_req_grant_delay_get(void)

Get time PTA needs to respond with grant signal to request signal.

There are three ways to manage the grant signal by PTA:

  1. Keep grant signal in denied state by default and provide grant only after request. The maximum delay between request and grant signal is known.

  2. Keep grant signal in approved state by default and deny only if given request cannot be accepted. Radio is not allowed to start any operation for known time after the request signal is set. After this delay the grant signal can indicate denial anytime to prevent or to abort radio operation.

  3. Manage the granted signal constantly, even if there is no request from given radio.

This function is to be used to verify how long the user of this interface should wait from calling mpsl_cx_request (return from function) to mpsl_cx_granted_ops_get (call to function) to prevent getting false results while PTA is responding to the last request.

Return values:

  • >0 – Minimal delay from setting the request signal to the time grant signal gets meaningful value. In microseconds, rounded up

  • 0 – Grant signal has always meaningful value. Can be checked before, during, or after setting the request signal.

int32_t mpsl_cx_register_callback(mpsl_cx_cb_t cb)

Register callback function called when radio operations granted by PTA change.

This function is used by radio protocols that require CPU processing when list of granted operations changes. One example is a protocol waiting with asynchronous transmission until TX operation is granted.

When radio protocol stops using Coexistence interface to hand it over to another protocol, it shall reset callback by calling this function with NULL value passed in cb.

Parameters:

  • cb – [in] Pointer to a callback function called when radio operations granted by PTA change. If NULL, callback function is reset and nothing is called when granted radio operations change.

Return values:

0 – Successfully set or reset callback function.

struct mpsl_cx_request_t
#include <mpsl_cx_protocol_api.h>

Structure with parameters describing next coexistence request.

Public Members

mpsl_cx_op_map_t ops

List of requested radio operations.

mpsl_cx_prio_t prio

Priority of requested radio operation.

mpsl_cx_req_trig_t trigger

When request is to be triggered.

MPSL Temp

group mpsl_temp

The MPSL temperature sensor interface provides APIs for measuring the chip temperature.

Functions

int32_t mpsl_temperature_get(void)

Get the temperature measured on the chip.

This function will block until the temperature measurement is done. It takes around 50 us from call to return.

Returns:

Result of temperature measurement. Die temperature in 0.25 degrees Celsius.

MPSL DPPI Protocol

group mpsl_dppi_protocol_api

API for fixed DPPI channel.

Fixed DPPI channels are DPPI channels where a publisher or subscriber remain attached to the channel for the entire duration of a radio event. This allows the application to add additional subscribers to channels that have a fixed publisher. For example, the application can configure a pin to toggle on every transaction by connecting NRF_GPIOTE->SUBSCRIBE_OUT[i] to MPSL_DPPI_RADIO_PUBLISH_READY_CHANNEL_IDX or NRF_GPIOTE->SUBSCRIBE_OUT[i] to MPSL_DPPI_RADIO_PUBLISH_DISABLED_CH_IDX.

Defines

MPSL_DPPI_RADIO_PUBLISH_READY_CHANNEL_IDX

Fixed channel for NRF_RADIO->PUBLISH_READY.

MPSL_DPPI_RADIO_PUBLISH_ADDRESS_CHANNEL_IDX

Fixed channel for NRF_RADIO->PUBLISH_ADDRESS.

MPSL_DPPI_RADIO_PUBLISH_END_CHANNEL_IDX

Fixed channel for NRF_RADIO->PUBLISH_END.

MPSL_DPPI_RADIO_PUBLISH_DISABLED_CH_IDX

Fixed channel for NRF_RADIO->PUBLISH_DISABLED.

MPSL_DPPI_RADIO_PUBLISH_PHYEND_CHANNEL_IDX

Fixed channel for NRF_RADIO->PUBLISH_PHYEND.

MPSL_DPPI_RADIO_SUBSCRIBE_DISABLED_CHANNEL_IDX

Fixed channel for NRF_RADIO->SUBSCRIBE_DISABLE. Publishing to this channel will result in undefined behavior.

Functions

void mpsl_dppi_fixed_channels_set(void)

Setup the DPPI channels.

void mpsl_dppi_fixed_channels_clear(void)

Clear the DPPI channels.