API documentation

Header file: include/modem/nrf_modem_lib.h, include/modem/nrf_modem_lib_trace.h
Source file: lib/nrf_modem_lib.c
group nrf_modem_lib

Modem library wrapper.

Defines

NRF_MODEM_LIB_ON_DFU_RES(name, _callback, _context)

Define a callback for DFU result nrf_modem_lib_init calls.

The callback function _callback is invoked after the library has been initialized.

Note

The NRF_MODEM_LIB_ON_DFU_RES callback can be used to subscribe to the result of a modem DFU operation.

Parameters:

  • name – Callback name

  • _callback – Callback function name

  • _context – User-defined context for the callback

NRF_MODEM_LIB_ON_INIT(name, _callback, _context)

Define a callback for nrf_modem_lib_init calls.

The callback function _callback is invoked after the library has been initialized.

Note

The NRF_MODEM_LIB_ON_INIT callback can be used to perform modem and library configurations that require the modem to be turned on in offline mode. It cannot be used to change the modem functional mode. Calls to lte_lc_connect and CFUN AT calls are not allowed, and must be done after nrf_modem_lib_init has returned. If a library needs to perform operations after the link is up, it can use the link controller and subscribe to a LTE_LC_ON_CFUN callback.

Parameters:

  • name – Callback name

  • _callback – Callback function name

  • _context – User-defined context for the callback

NRF_MODEM_LIB_ON_SHUTDOWN(name, _callback, _context)

Define a callback for nrf_modem_lib_shutdown calls.

The callback function _callback is invoked before the library is shutdown.

Parameters:

  • name – Callback name

  • _callback – Callback function name

  • _context – User-defined context for the callback

Enums

enum nrf_modem_lib_net_if_down_options

Options used to specify desired behavior when the network interface is brought down by calling net_if_down().

Values:

enumerator NRF_MODEM_LIB_NET_IF_DOWN_MODEM_SHUTDOWN

Shutdown modem - GNSS functionality will not be preserved.

enumerator NRF_MODEM_LIB_NET_IF_DOWN_LTE_DISCONNECT

Disconnect from LTE - GNSS functionality will be preserved.

enum nrf_modem_lib_net_if_options

Option types used to specify library behavior.

Values:

enumerator NRF_MODEM_LIB_NET_IF_DOWN

Sets desired behavior when net_if_down() is called.

Functions

int nrf_modem_lib_init(void)

Initialize the Modem library and turn on the modem.

The operation can take a few minutes when a firmware update is scheduled.

To switch between the bootloader mode and normal operating mode, shutdown the modem with nrf_modem_lib_shutdown() and re-initialize it in the desired mode. Use nrf_modem_lib_init() to initialize in normal mode and nrf_modem_lib_bootloader_init() to initialize the Modem library in bootloader mode.

Return values:

  • Zero – on success.

  • -NRF_EPERM – The Modem library is already initialized.

  • -NRF_EFAULT – init_params is NULL.

  • -NRF_ENOLCK – Not enough semaphores.

  • -NRF_ENOMEM – Not enough shared memory.

  • -NRF_EINVAL – Control region size is incorrect or missing handlers in init_params.

  • -NRF_ENOTSUPP – RPC version mismatch.

  • -NRF_ETIMEDOUT – Operation timed out.

  • -NRF_ACCESS – Modem firmware authentication failure.

  • -NRF_EAGAIN – Modem device firmware upgrade failure. DFU is scheduled at next initialization.

  • -NRF_EIO – Modem device firmware upgrade failure. Reprogramming the modem firmware is necessary to recover.

int nrf_modem_lib_bootloader_init(void)

Initialize the Modem library in bootloader mode and turn on the modem.

When the modem is initialized in bootloader mode, no other functionality is available. In particular, networking sockets and AT commands won’t be available.

To switch between the bootloader mode and normal operating mode, shutdown the modem with nrf_modem_lib_shutdown() and re-initialize it in the desired mode. Use nrf_modem_lib_init() to initialize in normal mode and nrf_modem_lib_bootloader_init() to initialize the Modem library in bootloader mode.

Return values:

  • Zero – on success.

  • -NRF_EPERM – The Modem library is already initialized.

  • -NRF_EFAULT – init_params is NULL.

  • -NRF_ENOLCK – Not enough semaphores.

  • -NRF_ENOMEM – Not enough shared memory.

  • -NRF_EINVAL – Missing handler in init_params.

  • -NRF_EACCES – Bad root digest.

  • -NRF_ETIMEDOUT – Operation timed out.

  • -NRF_EIO – Bootloader fault.

  • -NRF_ENOSYS – Operation not available.

int nrf_modem_lib_shutdown(void)

Shutdown the Modem library and turn off the modem.

Note

The modem must be put in minimal function mode before being shut down.

Returns:

int Zero on success, non-zero otherwise.

void nrf_modem_fault_handler(struct nrf_modem_fault_info *fault_info)

Modem fault handler.

Parameters:

  • fault_info – [in] Modem fault information. Contains the fault reason and, in some cases, the modem program counter.

const char *nrf_modem_lib_fault_strerror(int fault)

Retrieve a statically allocated textual description of a given fault.

Parameters:

  • fault – The fault.

Returns:

const char* Textual description of the given fault.

int nrf_modem_lib_diag_stats_get(struct nrf_modem_lib_diag_stats *stats)

Retrieve heap runtime statistics.

Retrieve runtime statistics for the shared memory and library heaps.

Returns:

int Zero on success, non-zero otherwise.

struct nrf_modem_lib_dfu_cb
#include <nrf_modem_lib.h>

Modem library dfu callback struct.

Public Members

void (*callback)(int dfu_res, void *ctx)

Callback function.

Param dfu_res:

The return value of nrf_modem_init()

Param ctx:

User-defined context

void *context

User defined context

struct nrf_modem_lib_init_cb
#include <nrf_modem_lib.h>

Modem library initialization callback struct.

Public Members

void (*callback)(int ret, void *ctx)

Callback function.

Param ret:

The return value of nrf_modem_init()

Param ctx:

User-defined context

void *context

User defined context

struct nrf_modem_lib_shutdown_cb
#include <nrf_modem_lib.h>

Modem library shutdown callback struct.

Public Members

void (*callback)(void *ctx)

Callback function.

Param ctx:

User-defined context

void *context

User defined context

struct nrf_modem_lib_diag_stats
#include <nrf_modem_lib.h>
group nrf_modem_lib_trace

Enums

enum nrf_modem_lib_trace_level

Trace level.

The trace level can be used to filter the traces.

Values:

enumerator NRF_MODEM_LIB_TRACE_LEVEL_OFF

Disable output.

enumerator NRF_MODEM_LIB_TRACE_LEVEL_COREDUMP_ONLY

Coredump only.

enumerator NRF_MODEM_LIB_TRACE_LEVEL_FULL

LTE, IP, GNSS, and coredump.

enumerator NRF_MODEM_LIB_TRACE_LEVEL_IP_ONLY

IP.

enumerator NRF_MODEM_LIB_TRACE_LEVEL_LTE_AND_IP

LTE and IP.

enum nrf_modem_lib_trace_event

Trace event.

Values:

enumerator NRF_MODEM_LIB_TRACE_EVT_FULL

Trace storage is full.

Functions

void nrf_modem_lib_trace_callback(enum nrf_modem_lib_trace_event evt)

Trace callback that is called by the trace library when an event occour.

Note

This callback must be defined by the application with some trace backends.

Parameters:

  • evt – Occurring event

Returns:

Zero on success, non-zero otherwise.

int nrf_modem_lib_trace_processing_done_wait(k_timeout_t timeout)

Wait for trace to have finished processing after coredump or shutdown.

This function blocks until the trace module has finished processing data after a modem fault (coredump) or modem shutdown.

Parameters:

  • timeout – Time to wait for trace processing to be done.

Returns:

Zero on success, non-zero otherwise.

int nrf_modem_lib_trace_level_set(enum nrf_modem_lib_trace_level trace_level)

Set trace level.

Parameters:

  • trace_level – Trace level

Returns:

Zero on success, non-zero otherwise.

size_t nrf_modem_lib_trace_data_size(void)

Get the number of bytes stored in the compile-time selected trace backend.

Note

To ensure the retrieved number of bytes is correct, this function should only be called when the backend is done processing traces. This operation is only supported with some trace backends. If not supported, the function returns -ENOTSUP.

Returns:

Number of bytes stored in the trace backend.

int nrf_modem_lib_trace_read(uint8_t *buf, size_t len)

Read trace data.

Read out the trace data. After read, the backend can choose to free the space and prepare it for further write operations.

Note

This operation is only supported with some trace backends. If not supported, the function returns -ENOTSUP.

Parameters:

  • buf – Output buffer

  • len – Size of output buffer

Returns:

read number of bytes, negative errno on failure.

int nrf_modem_lib_trace_clear(void)

Clear captured trace data.

Clear all captured trace data and prepare for capturing new traces.

Note

This operation is only supported with some trace backends. If not supported, the function returns -ENOTSUP.

Returns:

0 on success, negative errno on failure.

uint32_t nrf_modem_lib_trace_backend_bitrate_get(void)

Get the last measured rolling average bitrate of the trace backend.

This function returns the last measured rolling average bitrate of the trace backend calculated over the last CONFIG_NRF_MODEM_LIB_TRACE_BACKEND_BITRATE_PERIOD_MS period.

Returns:

Rolling average bitrate of the trace backend