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.

Parameters

  • file – [in] The filename where the assertion occurred.

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

Parameters
Returns 0

MPSL is successfully initialized.

Returns -NRF_EPERM

MPSL is already initialized.

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

Returns 0

Success

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

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.

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

mpsl_clock_hfclk_is_running

See

mpsl_clock_hfclk_release

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.

Returns 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

mpsl_clock_hfclk_is_running

See

mpsl_clock_hfclk_request

Returns 0

Success

int32_t mpsl_clock_hfclk_is_running(uint32_t *p_is_running)

Checks if the high frequency crystal oscillator is running.

See

mpsl_clock_hfclk_request

See

mpsl_clock_hfclk_release

Parameters

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

Returns 0

Success

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.

  • 2-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 that 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.

Parameters
Returns

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.

Returns 0

The configuration was applied successfully.

Returns -NRF_EPERM

Timeslots need to be configured when no timeslots are open.

Returns -NRF_EINVAL

Invalid argument provided.

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

Returns 0

Request was successful.

Returns -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
Returns 0

Success

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

Returns 0

Success

Returns -NRF_EINVAL

The parameters of p_request are not valid

Returns -NRF_ENOENT

The session is not open.

Returns -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

MPSL_TIMESLOT_LENGTH_MIN_US,

See

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

MPSL_TIMESLOT_LENGTH_MIN_US,

See

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 Radio Notification

group mpsl_radio_notification

The MPSL radio interface provides APIs for configuring radio notifications. When radio notifications are enabled, the application is notified when an MPSL timeslot starts or ends. By using radio notifications, the application is informed when a protocol uses the radio.

Defines

MPSL_RADIO_NOTIFICATION_INACTIVE_GUARANTEED_TIME_US

Guaranteed time for application to process radio inactive notification.

Enums

enum MPSL_RADIO_NOTIFICATION_DISTANCES

Radio notification distances.

Values:

enumerator MPSL_RADIO_NOTIFICATION_DISTANCE_NONE

The event does not have a notification.

enumerator MPSL_RADIO_NOTIFICATION_DISTANCE_200US

The distance from the active notification to start of radio activity.

enumerator MPSL_RADIO_NOTIFICATION_DISTANCE_420US

The distance from the active notification to start of radio activity.

enumerator MPSL_RADIO_NOTIFICATION_DISTANCE_800US

The distance from the active notification to start of radio activity.

enumerator MPSL_RADIO_NOTIFICATION_DISTANCE_1740US

The distance from the active notification to start of radio activity.

enumerator MPSL_RADIO_NOTIFICATION_DISTANCE_2680US

The distance from the active notification to start of radio activity.

enumerator MPSL_RADIO_NOTIFICATION_DISTANCE_3620US

The distance from the active notification to start of radio activity.

enumerator MPSL_RADIO_NOTIFICATION_DISTANCE_4560US

The distance from the active notification to start of radio activity.

enumerator MPSL_RADIO_NOTIFICATION_DISTANCE_5500US

The distance from the active notification to start of radio activity.

enum MPSL_RADIO_NOTIFICATION_TYPES

Radio notification types.

Values:

enumerator MPSL_RADIO_NOTIFICATION_TYPE_NONE

The event does not have a radio notification signal.

enumerator MPSL_RADIO_NOTIFICATION_TYPE_INT_ON_ACTIVE

Using interrupt for notification when the radio will be enabled.

enumerator MPSL_RADIO_NOTIFICATION_TYPE_INT_ON_INACTIVE

Using interrupt for notification when the radio has been disabled.

enumerator MPSL_RADIO_NOTIFICATION_TYPE_INT_ON_BOTH

Using interrupt for notification both when the radio will be enabled and disabled.

Functions

int32_t mpsl_radio_notification_cfg_set(uint8_t type, uint8_t distance, IRQn_Type irq)

Configures the Radio Notification signal.

Note

  • The notification signal latency depends on the interrupt priority settings of IRQ used for notification signal.

  • To ensure that the radio notification signal behaves in a consistent way, the radio notifications must be configured when there is no protocol stack enabled. It is recommended that the radio notification signal is configured directly after the MPSL is enabled.

Parameters
Returns -NRF_EINVAL

Invalid parameters supplied.

Returns -NRF_EAGAIN

A protocol stack or other SoftDevice is running. Stop all running activities and retry.

Returns 0

Success

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.

Returns 0

TX power channel successfully set.

Returns -NRF_EINVAL

Invalid parameter provided.

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.

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

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_t::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_t::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_t::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.

Returns 0

PA activation setup is successful.

Returns -NRF_EPERM

PA is currently disabled.

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

Returns 0

PA activation setup purge is successful.

Returns -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_t::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_t::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_t::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.

Returns 0

LNA activation setup is successful.

Returns -NRF_EPERM

LNA is currently disabled.

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

Returns 0

LNA activate setup purge is successful.

Returns -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(uint32_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] Address of the event which is triggered when the abort condition occurs.

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

Returns 0

Setting of the abort sequence path is successful.

Returns -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] PPI channel to add to the PPI group.

  • group – [in] The said PPI group.

Returns 0

Setting of the abort sequence path is successful.

Returns -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] PPI channel to remove from the PPI group.

  • group – [in] The said PPI group.

Returns 0

Setting of the abort sequence path is successful.

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

Returns 0

Clearing of the abort sequence path is successful.

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

void mpsl_fem_pa_is_configured(int8_t *const p_gain)

Checks if the PA signaling is configured and enabled, and gets the configured gain in dB.

Parameters

  • p_gain – [out] The configured gain in dB if PA is configured and enabled. If there is no PA present or the PA 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.

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.

Returns true

Whether the scheduling of the transition was successful.

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

uint32_t register_address

Address of event register.

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.

bool override_ppi

False to ignore the PPI channel below and use the one set by application. True to use the PPI channel below.

uint8_t ppi_ch_id

PPI channel to be used for this event.

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.

Returns true

DEVICE-CONFIG-254 shall be applied.

Returns false

DEVICE-CONFIG-254 shall not be applied.

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

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 gpio_pin

GPIO pin number for the pin.

uint8_t gpiote_ch_id

The GPIOTE channel used for toggling this pin.

MPSL FEM nRF21540 GPIO

group mpsl_fem_nrf21540_gpio

Defines

MPSL_FEM_NRF21540_GPIO_DEFAULT_PA_TIME_IN_ADVANCE_US

nRF21540 GPIO Front End Module Timings

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

MPSL_FEM_NRF21540_GPIO_DEFAULT_LNA_TIME_IN_ADVANCE_US

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

MPSL_FEM_NRF21540_GPIO_DEFAULT_PDN_SETTLE_US

The time between activating the PDN and asserting the RX_EN/TX_EN.

MPSL_FEM_NRF21540_GPIO_DEFAULT_TRX_HOLD_US

The time between deasserting the RX_EN/TX_EN and deactivating PDN.

MPSL_FEM_NRF21540_GPIO_PA_DEFAULT_GAIN_DB

nRF21540 GPIO Front End Module Gains

The provided gains are the default gains. The actual gain may depend on the temperature and the configuration of the Front End Module. See the Objective Product Specification for more details. Gain of the PA in dB.

MPSL_FEM_NRF21540_GPIO_LNA_DEFAULT_GAIN_DB

Gain of the LNA in dB.

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.

Returns 0

PA/LNA control successfully configured.

Returns -NRF_EPERM

PA/LNA is not available.

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

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.

uint32_t pdn_settle_us

The time between activating the PDN pin and activating the PA/LNA pin.

uint32_t trx_hold_us

The time between deactivating the PA/LNA pin and deactivating the PDN pin.

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_nrf21540_gpio_interface_config_t.[anonymous] fem_config

Configuration structure of the nRF21540 GPIO Front End Module.

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.

uint8_t ppi_channels[3]

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

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.

Returns 0

PA/LNA control successfully configured.

Returns -NRF_EPERM

PA/LNA is not available.

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 ppi_channels[2]

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

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.