API documentation

Library Management

group nrf_modem

Application interface offered for management of the Modem library.

Functions

char *nrf_modem_build_version(void)

Return a statically allocated string identifying the Modem library build.

Return values:

• Version – string if defined.

• Empty – string if version string is not defined.

int nrf_modem_init(const struct nrf_modem_init_params *init_params)

Initialize the Modem library and turn on the modem.

Note

To switch between bootloader and normal modes, nrf_modem_shutdown must be called in between.

Parameters:

• init_params – [in] Initialization parameters.

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_EAGAIN – Modem firmware update not executed due to insufficient voltage, try again.

• -NRF_EIO – Modem firmware update failure or modem fault during initialization.

int nrf_modem_bootloader_init(const struct nrf_modem_bootloader_init_params *init_params)

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

Note

To switch between bootloader and normal modes, nrf_modem_shutdown must be called in between.

Parameters:

• init_params – [in] Bootloader initialization parameters.

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.

bool nrf_modem_is_initialized(void)

Check whether the modem is initialized.

Return values:

• true – If the modem is initialized.

• false – If the modem is uninitialized or in a fault state.

int nrf_modem_shutdown(void)

De-initialize the Modem library and turn off the modem.

Resources reserved by the library are freed when the library is shutdown.

Note

If the modem is initialized in normal mode, it must be put into offline mode (CFUN=0) before shutting it down.

Return values:

• Zero – on success.

• -NRF_EPERM – The Modem library is not initialized.

struct nrf_modem_init_params

#include <nrf_modem.h>

Modem library initialization parameters.

Public Members

struct nrf_modem_shmem_cfg shmem

Shared memory configuration

uint32_t ipc_irq_prio

IPC IRQ priority

nrf_modem_fault_handler_t fault_handler

Modem fault handler

nrf_modem_dfu_handler_t dfu_handler

Modem DFU handler

struct nrf_modem_bootloader_init_params

#include <nrf_modem.h>

Modem library bootloader initialization parameters.

Public Members

struct nrf_modem_bootloader_shmem_cfg shmem

Shared memory configuration

uint32_t ipc_irq_prio

IPC IRQ priority

nrf_modem_fault_handler_t fault_handler

Modem fault handler

nrf_modem_init() return values for modem firmware updates

group nrf_modem_dfu

nrf_modem_init() return values when executing Modem firmware updates.

Defines

NRF_MODEM_DFU_RESULT_OK

Modem firmware update successful. The modem is running the updated modem firmware.

NRF_MODEM_DFU_RESULT_INTERNAL_ERROR

Modem firmware update failed. The modem encountered a fatal internal error during firmware update.

NRF_MODEM_DFU_RESULT_HARDWARE_ERROR

Modem firmware update failed. The modem encountered a fatal hardware error during firmware update.

NRF_MODEM_DFU_RESULT_AUTH_ERROR

Modem firmware update failed, due to an authentication error. The modem is running the previous (non-updated) firmware.

NRF_MODEM_DFU_RESULT_UUID_ERROR

Modem firmware update failed, due to UUID mismatch. The modem is running the previous (non-updated) firmware.

NRF_MODEM_DFU_RESULT_VOLTAGE_LOW

Modem firmware update not executed due to low voltage. The modem will retry the update on reboot.

Modem traces

group nrf_modem_trace

API for handling modem traces.

Functions

int nrf_modem_trace_get(struct nrf_modem_trace_data **frags, size_t *n_frags, int timeout)

Get trace data.

The application may call this function to receive trace data from the modem. The trace fragments must be processed in order from the start of the array. Processed data must be freed by calling nrf_modem_trace_processed.

Parameters:

• frags – [out] On success, *frags is an array of trace data fragments.

• n_frags – [out] On success, *n_frags is the number of fragments in the *frags array.

• timeout – [in] Time to wait in milliseconds for trace data to become available or one of the special values NRF_MODEM_OS_FOREVER or NRF_MODEM_OS_NO_WAIT.

Return values:

• 0 – on success.

• -NRF_EFAULT – If frags or nfrags is NULL.

• -NRF_EINPROGRESS – Trace is already being processed by the application.

• -NRF_ENODATA – No more trace data is available until the modem is restarted.

• -NRF_ESHUTDOWN – Modem was shut down.

• -NRF_EAGAIN – If the request timed out.

• -NRF_ENOTSUP – Modem is not configured for trace output.

int nrf_modem_trace_processed(size_t len)

Notify the Modem library that the application has completed processing of trace data.

The application must call this function to let the Modem library free the trace memory. It is the application’s responsibility to call this function with the total size of all trace fragments received. If the data is processed in chunks, the function can be called with the size that is processed since last call.

Parameters:

• len – Length of trace data that is processed.

Return values:

• Zero – on success.

• -NRF_EINVAL – len is too large to be a valid trace length.

struct nrf_modem_trace_data

#include <nrf_modem_trace.h>

Trace data Structure to store trace data pointers and their respective sizes.

Modem fault reasons

group nrf_modem_fault_handling

Defines

NRF_MODEM_FAULT_UNDEFINED

Undefined fault (e.g. undefined interrupt)

NRF_MODEM_FAULT_HW_WD_RESET

HW WD reset detected

NRF_MODEM_FAULT_HARDFAULT

Hard fault

NRF_MODEM_FAULT_MEM_MANAGE

Memory management fault

NRF_MODEM_FAULT_BUS

Bus fault

NRF_MODEM_FAULT_USAGE

Usage fault

NRF_MODEM_FAULT_SECURE_RESET

Modem has been reset due to secure ctrl

NRF_MODEM_FAULT_PANIC_DOUBLE

Error handler has crashed

NRF_MODEM_FAULT_PANIC_RESET_LOOP

Modem startup has failed four times in row

NRF_MODEM_FAULT_ASSERT

Assert

NRF_MODEM_FAULT_PANIC

Unconditional SW reset

NRF_MODEM_FAULT_FLASH_ERASE

Flash erase fault

NRF_MODEM_FAULT_FLASH_WRITE

Flash write fault

NRF_MODEM_FAULT_POFWARN

Undervoltage fault

NRF_MODEM_FAULT_THWARN

Overtemperature fault

Typedefs

typedef void (*nrf_modem_fault_handler_t)(struct nrf_modem_fault_info *fault_info)

Modem fault handler.

typedef void (*nrf_modem_dfu_handler_t)(uint32_t dfu_result)

Modem DFU handler.

struct nrf_modem_fault_info

#include <nrf_modem.h>

Modem fault info struct.

Limits of the Modem library

group nrf_modem_limits

Modem library constants.

Maximum number of IP sockets.

Defines

NRF_MODEM_MAX_SHMEM_SIZE

Maximum size in bytes of shared modem and application memory.

Socket parameter enumerators

Socket families

group nrf_socket_families

Defines

NRF_AF_UNSPEC

Unspecified address family

NRF_AF_INET

IPv4 socket family.

NRF_AF_INET6

IPv6 socket family.

NRF_AF_PACKET

Raw packet family.

Socket types

group nrf_socket_types

Defines

NRF_SOCK_STREAM

TCP socket type.

NRF_SOCK_DGRAM

UDP socket type.

NRF_SOCK_RAW

RAW socket type.

Socket protocols

group nrf_socket_protocols

Protocol numbers from IANA/BSD.

Defines

NRF_IPPROTO_IP

IP protocol (pseudo-val for setsockopt())

NRF_IPPROTO_TCP

TCP protocol.

NRF_IPPROTO_UDP

UDP protocol.

NRF_IPPROTO_IPV6

IPv6 protocol (pseudo-val for setsockopt())

NRF_IPPROTO_RAW

Raw IP packets

NRF_IPPROTO_ALL

IPv4 and IPv6 protocol (pseudo-val for setsockopt())

NRF_SPROTO_TLS1v2

TLS1v2 protocol.

NRF_SPROTO_DTLS1v2

DTLS1v2 protocol.

Socket option levels

group nrf_socket_options_levels

Defines

NRF_SOL_SOCKET

NRF_SOL_SECURE

Generic socket options

group nrf_socket_options_sockets

Socket options used with IP sockets.

Defines

NRF_SO_REUSEADDR

Enable reuse of server addresses

NRF_SO_ERROR

Read and clear socket error status (read only).

NRF_SO_RCVTIMEO

Receive timeout.

NRF_SO_SNDTIMEO

Send timeout.

NRF_SO_SILENCE_ALL

Disable ICMP echo replies on both IPv4 and IPv6. Set to 1 to enable, or to 0 to disable. Default is 0, disabled.

NRF_SO_IP_ECHO_REPLY

Enable ICMP echo reply. Set to 1 to enable, or to 0 to disable. Default is 1, enabled.

NRF_SO_IPV6_ECHO_REPLY

Enable ICMPv6 echo reply. Set to 1 to enable, or to 0 to disable. Default is 1, enabled.

NRF_SO_EXCEPTIONAL_DATA

Send data related to an exceptional event.

NRF_SO_KEEPOPEN

Keep socket open when its PDN connection is lost.

NRF_SO_BINDTOPDN

Bind a socket to a Packet Data Network ID.

NRF_SO_TCP_SRV_SESSTIMEO

Configurable TCP server session timeout in minutes. Range is 0 to 135. 0 is no timeout and 135 is 2 h 15 min. Default is 0 (no timeout).

NRF_SO_POLLCB

Set a callback for poll events

NRF_SO_RAI

Release Assistance Indication (RAI). See Socket option values for RAI for allowed values.

NRF_SO_RAI_NO_DATA

Release Assistance Indication. Indicate that the application does not intend to send more data. This socket option applies immediately and lets the modem exit connected mode more quickly.

Deprecated:

since v2.6.0, use NRF_SO_RAI with value NRF_RAI_NO_DATA instead.

Note

This socket option requires the socket to be connected.

NRF_SO_RAI_LAST

Release Assistance Indication. Indicate that the application does not intend to send more data after the next call to send() or sendto(). This lets the modem exit connected mode more quickly after sending the data.

Deprecated:

since v2.6.0, use NRF_SO_RAI with value NRF_RAI_LAST instead.

NRF_SO_RAI_ONE_RESP

Release Assistance Indication. Indicate that the application is expecting to receive just one data packet after the next call to send() or sendto(). This lets the modem exit connected mode more quickly after having received the data.

Deprecated:

since v2.6.0, use NRF_SO_RAI with value NRF_RAI_ONE_RESP instead.

NRF_SO_RAI_ONGOING

Release Assistance Indication. Indicate that the socket is in active use by a client application. This lets the modem stay in connected mode longer.

Deprecated:

since v2.6.0, use NRF_SO_RAI with value NRF_RAI_ONGOING instead.

NRF_SO_RAI_WAIT_MORE

Release Assistance Indication. Indicate that the socket is in active use by a server application. This lets the modem stay in connected mode longer.

Deprecated:

since v2.6.0, use NRF_SO_RAI with value NRF_RAI_WAIT_MORE instead.

Socket send and recv flags

group nrf_socket_send_recv_flags

Defines

NRF_MSG_PEEK

Return data from the beginning of receive queue without removing data from the queue.

NRF_MSG_DONTWAIT

Enables non-blocking operation.

NRF_MSG_WAITALL

Request a blocking read operation until the request is satisfied.

NRF_MSG_WAITACK

Request a blocking send operation until the request is acknowledged. When used in nrf_send() or nrf_sendto(), the operation will block until the data has been sent on-air and acknowledged by the peer, if required by the network protocol.

fcntl parameters

group nrf_fcnt_commands

API commands used to control the behaviour of IP sockets using nrf_fcntl().

Defines

NRF_F_GETFL

Get flag.

NRF_F_SETFL

Set flag.

group nrf_fcnt_flags

Flags used to control the behaviour of IP sockets using nrf_fcntl().

Defines

NRF_O_NONBLOCK

Use non-blocking I/O.

Socket API

group nrf_socket_api

Functions

int nrf_socket(int family, int type, int protocol)

Create a network socket.

See POSIX.1-2017 article for normative description.

In addition, the function may return -1 and set the following errno:

• [NRF_ESHUTDOWN] Modem was shut down.

int nrf_close(int fildes)

Close a network socket.

See POSIX.1-2017 article for normative description.

In addition, the function may return -1 and set the following errno:

• [NRF_ESHUTDOWN] Modem was shut down.

int nrf_fcntl(int fd, int cmd, int flags)

Function for controlling file descriptor options.

Set or get file descriptor options or flags. For a list of supported commands, refer to File descriptor control option commands.. For a list of supported flags, refer to File descriptor control option flags..

Parameters:

• fd – The descriptor to set options on.

• cmd – The command class for options.

• flags – The flags to set.

Returns:

Value dependent on command class: NRF_F_GETFL - Value of file status flags. -1 on error, and errno indicates the reason for failure. 0 otherwise.

int nrf_connect(int socket, const struct nrf_sockaddr *address, nrf_socklen_t address_len)

Connect a socket.

See POSIX.1-2017 article for normative description.

In addition, the function may return -1 and set the following errno:

• [NRF_ESHUTDOWN] Modem was shut down.

In addition, an asynchronous connection attempt will fail and set NRF_SO_ERROR if:

• [NRF_EBUSY] Another TLS handshake was ongoing.

ssize_t nrf_send(int socket, const void *buffer, size_t length, int flags)

Send a message on a connected socket.

See POSIX.1-2017 article for normative description.

In addition, the function may return -1 and set the following errno:

• [NRF_ESHUTDOWN] Modem was shut down.

• [NRF_ECANCELED] Operation canceled because of APN rate control.

• [NRF_ENOMEM] TCP stream interrupted because of no heap memory.

• [NRF_EPROTO] Request failed because DTLS context was serialized.

ssize_t nrf_sendto(int socket, const void *message, size_t length, int flags, const struct nrf_sockaddr *dest_addr, nrf_socklen_t dest_len)

Send a message on a socket.

See POSIX.1-2017 article for normative description.

In addition, the function may return -1 and set the following errno:

• [NRF_ESHUTDOWN] Modem was shut down.

• [NRF_ECANCELED] Operation canceled because of APN rate control.

• [NRF_ENOMEM] TCP stream interrupted because of no heap memory.

• [NRF_EPROTO] Request failed because DTLS context was serialized.

ssize_t nrf_recv(int socket, void *buffer, size_t length, int flags)

Receive a message from a connected socket.

See POSIX.1-2017 article for normative description.

In addition, the function may return -1 and set the following errno:

• [NRF_ESHUTDOWN] Modem was shut down.

• [NRF_ENOMEM] TCP stream interrupted because of no heap memory.

ssize_t nrf_recvfrom(int socket, void *restrict buffer, size_t length, int flags, struct nrf_sockaddr *restrict address, nrf_socklen_t *restrict address_len)

Receive a message from a socket.

See POSIX.1-2017 article for normative description.

In addition, the function may return -1 and set the following errno:

• [NRF_ESHUTDOWN] Modem was shut down.

• [NRF_ENOMEM] TCP stream interrupted because of no heap memory.

int nrf_poll(struct nrf_pollfd fds[], nrf_nfds_t nfds, int timeout)

Poll multiple sockets for events.

See POSIX.1-2017 article for normative description.

Note

In Modem library, this function works only with Modem library sockets, not arbitrary file descriptors.

int nrf_setsockopt(int socket, int level, int option_name, const void *option_value, nrf_socklen_t option_len)

Set the socket options.

See POSIX.1-2017 article for normative description.

In addition, the function may return -1 and set the following errno:

• [NRF_EAGAIN] The option could not be set when requested, try again.

• [NRF_EDESTADDRREQ] The socket option NRF_SO_RAI_NO_DATA or the socket option NRF_SO_RAI with value NRF_RAI_NO_DATA cannot be set on a socket that is not connected.

• [NRF_EOPNOTSUPP] The option is not supported with the current socket configuration.

• [NRF_ESHUTDOWN] Modem was shut down.

Note

In Modem library this function supports a subset of socket options described by POSIX, but also some additional options.

int nrf_getsockopt(int socket, int level, int option_name, void *restrict option_value, nrf_socklen_t *restrict option_len)

Get the socket options.

See POSIX.1-2017 article for normative description.

In Modem library this function supports a subset of socket options described by POSIX, but also some additional options.

int nrf_bind(int socket, const struct nrf_sockaddr *address, nrf_socklen_t address_len)

Bind a name to a socket.

See POSIX.1-2017 article for normative description.

In addition, the function may return -1 and set the following errno:

• [NRF_ESHUTDOWN] Modem was shut down.

int nrf_listen(int sock, int backlog)

Listen for socket connections and limit the queue of incoming connections.

See POSIX.1-2017 article for normative description.

In addition, the function may return -1 and set the following errno:

• [NRF_ESHUTDOWN] Modem was shut down.

int nrf_accept(int socket, struct nrf_sockaddr *restrict address, nrf_socklen_t *restrict address_len)

Accept a new connection a socket.

See POSIX.1-2017 article for normative description.

In addition, the function may return -1 and set the following errno:

• [NRF_EAGAIN] The socket’s NRF_SO_RCVTIMEO timeout was exceeded.

• [NRF_ESHUTDOWN] Modem was shut down.

struct nrf_timeval

#include <nrf_socket.h>

Structure specifying time interval.

Public Members

uint32_t tv_sec

Time interval seconds.

uint32_t tv_usec

Time interval microseconds.

TLS socket

group nrf_socket_tls

TLS socket API.

Defines

NRF_SOCKET_TLS_MAX_MESSAGE_SIZE

Maximum TLS message size in bytes.

NRF_SOCKET_TLS_MAX_SEC_TAG_LIST_SIZE

Maximum number of security tags that can be associated with a socket.

NRF_SO_SEC_TAG_LIST

Write-only socket option to select the security tags to be used. This option accepts a list of.

See also

nrf_sec_tag_t.

NRF_SO_SEC_HOSTNAME

Socket option to set the hostname used for peer verification. This option accepts a string containing the hostname, and its length. The length may be set to zero to disable hostname verification.

NRF_SO_SEC_CIPHERSUITE_LIST

Write-only socket option to select which ciphersuites to use. This option accepts a prioritized array of selected cipher suites. See TLS Cipher suites for a list of allowed values.

NRF_SO_SEC_CIPHERSUITE_USED

Socket option to retrieve the cipher suite used during the TLS/DTLS handshake.

Note

This socket option is only supported with Modem firmware 2.0.0 and newer.

NRF_SO_SEC_PEER_VERIFY

Socket option to set peer verification level. See TLS peer verification options for a list of allowed values.

NRF_SO_SEC_ROLE

Write-only socket option to set role for the connection. See Role for the socket connection for a list of allowed values.

NRF_SO_SEC_SESSION_CACHE

Socket option to control TLS session caching. See TLS session cache options for a list of allowed values.

NRF_SO_SEC_SESSION_CACHE_PURGE

Socket option to purge session cache immediately. This option accepts any value.

NRF_SO_SEC_DTLS_HANDSHAKE_TIMEO

Socket option to set DTLS handshake timeout value. See DTLS handshake timeout values for allowed values.

NRF_SO_SEC_DTLS_CID

Socket option to enable/disable the connection ID. See DTLS Connection ID settings for allowed values.

Note

This socket option is only supported with Modem firmware v1.3.5 and newer.

NRF_SO_SEC_DTLS_CID_STATUS

Socket option to get the connection ID status. See DTLS Connection ID statuses for allowed values.

Note

This socket option is only supported with Modem firmware v1.3.5 and newer.

NRF_SO_SEC_DTLS_CONN_SAVE

Socket option to save DTLS connection.

Serializes the socket and compresses it. After the socket option is successfully called, you must call NRF_SO_SEC_DTLS_CONN_LOAD before continuing to communicate on the socket.

Note

This socket option is only supported with Modem firmware v1.3.5 and newer.

NRF_SO_SEC_DTLS_CONN_LOAD

Socket option to load DTLS connection.

Note

This socket option is only supported with Modem firmware v1.3.5 and newer.

NRF_SO_SEC_HANDSHAKE_STATUS

Socket option to get end status of last completed TLS/DTLS handshake procedure. See TLS/DTLS Handshake statuses for allowed values.

Note

This socket option is only supported with Modem firmware 2.0.0 and newer.

Typedefs

typedef uint32_t nrf_sec_role_t

TLS role for the connection.

• 0 - TLS client role.

• 1 - TLS server role.

Deprecated:

since v2.6.0, use type int instead.

typedef uint32_t nrf_sec_tag_t

Security tags used on the TLS socket.

More than one security tags may be used on a socket. If more than one tag is used on the socket, pass an array of security tags.

A maximum of NRF_SOCKET_TLS_MAX_SEC_TAG_LIST_SIZE tags can be set per socket.

typedef uint32_t nrf_sec_session_cache_t

Session cache configuration for the TLS connection.

• 0 - Disabled.

• 1 - Enabled.

By default, the session cache is enabled.

Deprecated:

since v2.6.0, use type int instead.

Note

Session cache, may not be used if the peer does not support it.

typedef uint32_t nrf_sec_peer_verify_t

Peer verification level for the TLS connection.

• 0 - None.

• 1 - Optional.

• 2 - Required.

By default, peer verification is optional.

Deprecated:

since v2.6.0, use type int instead.

typedef uint32_t nrf_sec_cipher_t

An IANA cipher suite identifier.

Deprecated:

since v2.6.0, use type int instead.

DTLS handshake timeout values

group nrf_socket_so_sec_handshake_timeouts

Allowed timeout values for DTLS handshake timeout socket option according to RFC6347 section 4.2.4.1. Default is 123 seconds. (https://tools.ietf.org/html/rfc6347#section-4.2.4.1)

Defines

NRF_SO_SEC_DTLS_HANDSHAKE_TIMEOUT_NONE

No timeout

NRF_SO_SEC_DTLS_HANDSHAKE_TIMEOUT_1S

1 second

NRF_SO_SEC_DTLS_HANDSHAKE_TIMEOUT_3S

1s + 2s

NRF_SO_SEC_DTLS_HANDSHAKE_TIMEOUT_7S

1s + 2s + 4s

NRF_SO_SEC_DTLS_HANDSHAKE_TIMEOUT_15S

1s + 2s + 4s + 8s

NRF_SO_SEC_DTLS_HANDSHAKE_TIMEOUT_31S

1s + 2s + 4s + 8s + 16s

NRF_SO_SEC_DTLS_HANDSHAKE_TIMEOUT_63S

1s + 2s + 4s + 8s + 16s + 32s

NRF_SO_SEC_DTLS_HANDSHAKE_TIMEOUT_123S

1s + 2s + 4s + 8s + 16s + 32s + 60s

TLS/DTLS peer verification options

group nrf_socket_sec_peer_verify_options

Allowed TLS peer verification options. By default, peer verification is optional.

Defines

NRF_SO_SEC_PEER_VERIFY_NONE

None

NRF_SO_SEC_PEER_VERIFY_OPTIONAL

Optional

NRF_SO_SEC_PEER_VERIFY_REQUIRED

Required

TLS/DTLS session cache options

group nrf_socket_session_cache_options

Allowed options for the TLS session cache. By default, the session cache is enabled.

Note

Session cache may not be used if the peer does not support it.

Defines

NRF_SO_SEC_SESSION_CACHE_DISABLED

Disabled

NRF_SO_SEC_SESSION_CACHE_ENABLED

Enabled

TLS/DTLS socket connection roles

group nrf_socket_sec_roles

Allowed roles for the socket connection.

Defines

NRF_SO_SEC_ROLE_CLIENT

Client

NRF_SO_SEC_ROLE_SERVER

Server

Supported cipher suites

group nrf_socket_tls_cipher_suites

Allowed IANA cipher suites for the nRF modem.

Defines

NRF_TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384

TLS 1.2

NRF_TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA

Not in SSL3!

NRF_TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256

TLS 1.2

NRF_TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA

Not in SSL3!

NRF_TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA

Not in SSL3!

NRF_TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256

TLS 1.2

NRF_TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA

Not in SSL3!

NRF_TLS_PSK_WITH_AES_256_CBC_SHA

NRF_TLS_PSK_WITH_AES_128_CBC_SHA256

NRF_TLS_PSK_WITH_AES_128_CBC_SHA

NRF_TLS_PSK_WITH_AES_128_CCM_8

TLS 1.2

NRF_TLS_EMPTY_RENEGOTIATIONINFO_SCSV

NRF_TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256

The following cipher suites are only supported with Modem firmware v1.3.x >= 1, Modem firmware v1.2.x >= 7 and Modem firmware v1.1.x >= 5. TLS 1.2

NRF_TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384

TLS 1.2

NRF_TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256

TLS 1.2

DTLS connection ID settings

group nrf_so_sec_dtls_cid_settings

Allowed values for DTLS connection ID setting socket option.

Defines

NRF_SO_SEC_DTLS_CID_DISABLED

Disabled - The connection ID extension is not included in the client hello, so the DTLS connection ID is not used.

NRF_SO_SEC_DTLS_CID_SUPPORTED

Supported - The connection ID extension with a zero-length CID is included in the client hello, so the modem will accept a DTLS connection ID from the server.

NRF_SO_SEC_DTLS_CID_ENABLED

Enabled - The connection ID extension with a valid CID is included in the client hello, so the modem will request DTLS connection ID support.

DTLS connection ID statuses

group nrf_so_sec_dtls_cid_statuses

Allowed values for DTLS connection ID status socket option.

Defines

NRF_SO_SEC_DTLS_CID_STATUS_DISABLED

Disabled - The DTLS connection ID is not included in DTLS records sent to and from the modem. This status is returned before the DTLS handshake is complete.

NRF_SO_SEC_DTLS_CID_STATUS_DOWNLINK

Downlink - The DTLS connection ID is included only in DTLS records sent to the modem.

NRF_SO_SEC_DTLS_CID_STATUS_UPLINK

Uplink - The DTLS connection ID is included only in DTLS records sent from the modem.

NRF_SO_SEC_DTLS_CID_STATUS_BIDIRECTIONAL

Bidirectional - The DTLS connection ID is included in DTLS records sent to and from the modem.

TLS/DTLS handshake statuses

group nrf_so_sec_handshake_statuses

Allowed values for DTLS connection ID status socket option.

Defines

NRF_SO_SEC_HANDSHAKE_STATUS_FULL

full

NRF_SO_SEC_HANDSHAKE_STATUS_CACHED

cached

Socket address resolution API

group nrf_socket_address_resolution

Address resolution utility functions.

Defines

NRF_HTONS(x)

Host to network byte-orders on half word.

NRF_HTONL(x)

Host to network byte-orders on full word.

NRF_NTOHS(x)

Network to host byte-orders on half word.

NRF_NTOHL(x)

Network to host byte-orders on full word.

nrf_htons(x)

Convert byte order from host to network (short).

nrf_htonl(x)

Convert byte order from host to network (long).

nrf_ntohs(x)

Convert byte order from network to host (short).

nrf_ntohl(x)

Convert byte order from network to host (long).

NRF_INET_ADDRSTRLEN

Maximum length of IPv4 in string form, including null-termination character.

NRF_INET6_ADDRSTRLEN

Maximum length of IPv6 in string form, including null-termination character.

NRF_AI_CANONNAME

Fill in ai_canonname

NRF_AI_NUMERICSERV

Assume service (port) is numeric.

NRF_AI_PDNSERV

Assume service contains a Packet Data Network (PDN) ID. When specified together with the NRF_AI_NUMERICSERV flag, service must be formatted as follows: “port:pdn_id” where “port” is the port number and “pdn_id” is the PDN ID. Example: “8080:1”, port 8080 PDN ID 1. Example: “42:0”, port 42 PDN ID 0.

Typedefs

typedef uint16_t nrf_in_port_t

Socket port type.

typedef unsigned short int nrf_sa_family_t

Socket families.

For a list of valid values, refer to nrf_socket_families.

typedef uint32_t nrf_in_addr_t

IPv4 address.

typedef uint32_t nrf_socklen_t

typedef uint32_t nrf_nfds_t

Functions

int nrf_inet_pton(int af, const char *restrict src, void *restrict dst)

Convert IPv4 and IPv6 addresses between binary and text form.

See POSIX.1-2017 article for normative description.

const char *nrf_inet_ntop(int af, const void *restrict src, char *restrict dst, nrf_socklen_t size)

Convert IPv4 and IPv6 addresses between binary and text form.

See POSIX.1-2017 article for normative description.

int nrf_getaddrinfo(const char *restrict nodename, const char *restrict servname, const struct nrf_addrinfo *restrict hints, struct nrf_addrinfo **restrict res)

Get address information.

See POSIX.1-2017 article for normative description.

In addition, the function may return -1 and set the following errno:

• [NRF_ESHUTDOWN] Modem was shut down.

Note

When using address family NRF_AF_UNSPEC the implementation attempts to resolve the IPv6 address first. If successful, the resolved address is returned. If not, the implementation attempts to resolve and return the IPv4 family address. This applies regardless of the PDN supporting IPv6 or not.

void nrf_freeaddrinfo(struct nrf_addrinfo *ai)

Free address information returned by nrf_getaddrinfo().

See POSIX.1-2017 article for normative description.

int nrf_getifaddrs(struct nrf_ifaddrs **ifa)

Get interface address information.

Create a linked list of nrf_ifaddrs structures describing the network interfaces and store the address of the first item of the list in *ifa.

The data returned by this function is dynamically allocated and must be freed using nrf_freeifaddrs() when no longer needed.

Parameters:

• ifa – [inout] First item in the linked list of interface addresses.

Return values:

• 0 – on success.

• -1 – on error, and set errno to indicate the reason.

void nrf_freeifaddrs(struct nrf_ifaddrs *ifa)

Free address information returned by nrf_getifaddrs().

Free a linked list of nrf_ifaddrs structures.

Parameters:

• ifa – First item in the linked list of interface addresses.

int nrf_setdnsaddr(int family, const void *in_addr, nrf_socklen_t in_size)

Set a secondary DNS address.

The secondary DNS address is only used in case the primary DNS address is unreachable, or if no DNS address is provided by the operator. The secondary DNS address does not override the primary DNS address.

The function may return -1 and set the following errno:

• [NRF_EPERM] The Modem library is not initialized.

• [NRF_EAFNOSUPPORT] The implementation does not support the specified address family.

• [NRF_EINVAL] Invalid parameters.

• [NRF_ENOBUFS] Not enough shared memory for this request.

• [NRF_ESHUTDOWN] Modem was shut down.

Note

It is not possible to unset a secondary DNS address set using this function.

Parameters:

• family – Address family.

• in_addr – An IPv4 or IPv6 address encoded in a nrf_in_addr or nrf_in6_addr structure, respectively.

• in_size – Size of the structure pointed to by in_addr.

Return values:

• 0 – On success

• -1 – On error, and set errno to indicate the reason.

Variables

const struct nrf_in6_addr nrf_in6addr_any

Global IPv6 any-address.

const struct nrf_in_addr nrf_inaddr_any

Global IPv4 any-address.

struct nrf_in6_addr

#include <nrf_socket.h>

IPv6 address.

struct nrf_in_addr

#include <nrf_socket.h>

IPv4 address structure.

struct nrf_sockaddr_in6

#include <nrf_socket.h>

Address record for IPv6 addresses.

Contains the address and port of the host.

Public Members

nrf_sa_family_t sin6_family

Socket family.

nrf_in_port_t sin6_port

Port, in network byte order.

struct nrf_in6_addr sin6_addr

IPv6 address.

uint8_t sin6_scope_id

IPv6 scope ID. Not used.

struct nrf_sockaddr_in

#include <nrf_socket.h>

Address record for IPv4 addresses.

Contains the address and port of the host.

Public Members

nrf_sa_family_t sin_family

Socket family.

nrf_in_port_t sin_port

Port, in network byte order.

struct nrf_in_addr sin_addr

IPv4 address.

struct nrf_sockaddr

#include <nrf_socket.h>

Generic socket address.

Only provided for API compatibility.

Public Members

nrf_sa_family_t sa_family

Socket address family

char sa_data[]

Socket address

struct nrf_addrinfo

#include <nrf_socket.h>

Address information.

Public Members

int ai_flags

Input flags.

int ai_family

Address family of the socket.

int ai_socktype

Socket type.

int ai_protocol

Protocol of the socket.

nrf_socklen_t ai_addrlen

Length of the socket address.

struct nrf_sockaddr *ai_addr

Address of the socket.

char *ai_canonname

Canonical name of service location.

struct nrf_addrinfo *ai_next

Pointer to next in list.

struct nrf_ifaddrs

#include <nrf_socket.h>

Interface address information.

Public Members

char *ifa_name

Interface name.

uint32_t ifa_flags

Interface flags.

struct nrf_sockaddr *ifa_addr

Interface address.

struct nrf_sockaddr *ifa_netmask

Interface netmask. Not supported by the modem.

struct nrf_sockaddr *ifa_broadaddr

Interface broadcast address. Not supported by the modem.

struct nrf_sockaddr *ifa_dstaddr

Interface destination address. Not supported by the modem.

void *ifa_data

Address specific data.

Socket polling API

Necessary data types and defines to poll for events on one or more sockets using nrf_poll().

group nrf_socket_api_poll

Data types and defines for use with nrf_poll().

Defines

NRF_POLLIN

Data other than high-priority data may be read without blocking

NRF_POLLOUT

Data may be written without blocking

NRF_POLLERR

An error has occurred (revents only)

NRF_POLLHUP

Device has been disconnected (revents only)

NRF_POLLNVAL

Invalid fd member (revents only)

Typedefs

typedef void (*nrf_modem_pollcb_t)(struct nrf_pollfd *pollfd)

Callback for poll events

struct nrf_pollfd

#include <nrf_socket.h>

This structure is used to describe which events to poll for a given socket.

Public Members

int fd

Socket handle

short events

The input event flags

short revents

The output event flags

struct nrf_modem_pollcb

#include <nrf_socket.h>

nrf_poll() callback

Public Members

nrf_modem_pollcb_t callback

Callback function

short events

Events mask

bool oneshot

Oneshot callback. If true, unset the callback after invoking it.

AT API

group nrf_modem_at

Modem library AT commands interface.

Defines

NRF_MODEM_AT_ERROR

Modem response type for ‘ERROR’ responses.

NRF_MODEM_AT_CME_ERROR

Modem response type for ‘+CME ERROR’ responses.

NRF_MODEM_AT_CMS_ERROR

Modem response type for ‘+CMS ERROR’ responses.

Typedefs

typedef void (*nrf_modem_at_notif_handler_t)(const char *notif)

AT Notification handler prototype.

Note

This handler is executed in an interrupt service routine. Offload any intensive operation as necessary.

Param notif:

The AT notification.

typedef void (*nrf_modem_at_cfun_handler_t)(int mode)

AT CFUN handler prototype.

Param mode:

CFUN mode.

typedef void (*nrf_modem_at_resp_handler_t)(const char *resp)

AT response handler prototype.

Note

This handler is executed in an interrupt service routine. Offload any intensive operations as necessary.

Param resp:

The AT command response.

typedef int (*nrf_modem_at_cmd_custom_handler_t)(char *buf, size_t len, char *at_cmd)

AT command handler prototype.

Implements a custom AT command in the application.

Param buf:

Buffer to receive the response into.

Param len:

Buffer length.

Param at_cmd:

AT command.

Retval 0:

On “OK” responses.

Retval -NRF_EPERM:

The Modem library is not initialized.

Retval -NRF_EFAULT:

buf or fmt are NULL.

Retval -NRF_ENOMEM:

Not enough shared memory for this request.

Retval -NRF_E2BIG:

The response is larger than the supplied buffer buf.

Return:

A positive value On “ERROR”, “+CME ERROR”, and “+CMS ERROR” responses. The type of error can be distinguished using nrf_modem_at_err_type. The error value can be retrieved using nrf_modem_at_err.

Functions

int nrf_modem_at_notif_handler_set(nrf_modem_at_notif_handler_t callback)

Set a handler function for AT notifications.

Note

The callback is executed in an interrupt service routine. Take care to offload any processing as appropriate.

Parameters:

• callback – The AT notification callback. Use NULL to unset handler.

Return values:

0 – On success.

void nrf_modem_at_cfun_handler_set(nrf_modem_at_cfun_handler_t handler)

Set a handler function for CFUN AT commands.

Note

The handler is executed after the CFUN command is successfully processed by the modem.

Parameters:

• handler – The CFUN handler. Use NULL to unset handler.

int nrf_modem_at_printf(const char *fmt, ...)

Send a formatted AT command to the modem.

Supports all format specifiers of printf() as implemented by the selected C library. This function can return a negative value, zero or a positive value.

Parameters:

• fmt – Command format.

• ... – Format arguments.

Return values:

• 0 – On “OK” responses.

• -NRF_EPERM – The Modem library is not initialized.

• -NRF_EFAULT – fmt is NULL.

• -NRF_EINVAL – Bad format fmt.

• -NRF_EAGAIN – Timed out while waiting for another AT command to complete.

• -NRF_ENOMEM – Not enough shared memory for this request.

• -NRF_ESHUTDOWN – If modem was shut down.

Returns:

A positive value On “ERROR”, “+CME ERROR”, and “+CMS ERROR” responses. The type of error can be distinguished using nrf_modem_at_err_type. The error value can be retrieved using nrf_modem_at_err.

int nrf_modem_at_scanf(const char *cmd, const char *fmt, ...)

Send an AT command to the modem and read the formatted response into the supplied argument list.

Supports all the format specifiers of scanf() as implemented by the selected C library. This function does not support retrieving the modem response beyond reading the formatted response into the argument list.

Parameters:

• cmd – AT command.

• fmt – Response format.

• ... – Variable argument list.

Return values:

• -NRF_EPERM – The Modem library is not initialized.

• -NRF_EFAULT – cmd or fmt are NULL.

• -NRF_EBADMSG – No arguments were matched.

• -NRF_EAGAIN – Timed out while waiting for another AT command to complete.

• -NRF_ENOMEM – Not enough shared memory for this request.

• -NRF_ESHUTDOWN – If the modem was shut down.

Returns:

The number of arguments matched.

int nrf_modem_at_cmd(void *buf, size_t len, const char *fmt, ...)

Send a formatted AT command to the modem and receive the response into the supplied buffer.

Parameters:

• buf – Buffer to receive the response into.

• len – Buffer length.

• fmt – Command format.

• ... – Format arguments.

Return values:

• 0 – On “OK” responses.

• -NRF_EPERM – The Modem library is not initialized.

• -NRF_EFAULT – buf or fmt are NULL.

• -NRF_EINVAL – Bad format fmt, or len is zero.

• -NRF_EAGAIN – Timed out while waiting for another AT command to complete.

• -NRF_ENOMEM – Not enough shared memory for this request.

• -NRF_E2BIG – The response is larger than the supplied buffer buf.

• -NRF_ESHUTDOWN – If the modem was shut down.

Returns:

A positive value On “ERROR”, “+CME ERROR”, and “+CMS ERROR” responses. The type of error can be distinguished using nrf_modem_at_err_type. The error value can be retrieved using nrf_modem_at_err.

int nrf_modem_at_cmd_async(nrf_modem_at_resp_handler_t callback, const char *fmt, ...)

Send a formatted AT command to the modem and receive the response asynchronously via a callback.

This function waits for the Modem to acknowledge the AT command but will return without waiting for the command execution.

Note

The callback is executed in an interrupt context. Take care to offload any processing as appropriate.

Parameters:

• callback – Callback to receive the response.

• fmt – Command format.

• ... – Format arguments.

Return values:

• 0 – On “OK” responses.

• -NRF_EPERM – The Modem library is not initialized.

• -NRF_EFAULT – callback or fmt are NULL.

• -NRF_EINVAL – Bad format fmt.

• -NRF_EINPROGRESS – Another AT command is executing.

• -NRF_ENOMEM – Not enough shared memory for this request.

• -NRF_ESHUTDOWN – If the modem was shut down.

int nrf_modem_at_cmd_custom_set(struct nrf_modem_at_cmd_custom *custom_commands, size_t len)

Set a list of custom AT commands that are implemented in the application.

When a custom AT command list is set, AT commands sent via nrf_modem_at_cmd that match any AT command in the list, will be redirected to the custom callback function instead of being sent to the modem.

Note

The custom commands are disabled by passing NULL to the custom_commands and 0 to the len.

Parameters:

• custom_commands – List of custom AT commands.

• len – Custom AT command list size.

Return values:

• 0 – On success.

• -NRF_EINVAL – On invalid parameters.

int nrf_modem_at_sem_timeout_set(int timeout_ms)

Configure how long to wait for ongoing AT commands to complete when sending AT commands.

AT commands are executed one at a time. While one AT command is being executed, the other AT commands wait on a semaphore for the ongoing AT command to complete.

This function configures how long nrf_modem_at_printf, nrf_modem_at_scanf and nrf_modem_at_cmd will wait for ongoing AT commands to complete.

By default, the timeout is infinite.

Parameters:

• timeout_ms – Timeout in milliseconds. Use NRF_MODEM_OS_FOREVER for infinite timeout or NRF_MODEM_OS_NO_WAIT for no timeout.

Returns:

int Zero on success, a negative errno otherwise.

static inline int nrf_modem_at_err_type(int error)

Return the error type represented by the return value of nrf_modem_at_printf and nrf_modem_at_cmd.

Parameters:

• error – The return value of nrf_modem_at_printf or nrf_modem_at_cmd.

Return values:

• NRF_MODEM_AT_ERROR – If the modem response was ‘ERROR’.

• NRF_MODEM_AT_CME_ERROR – If the modem response was ‘+CME ERROR’.

• NRF_MODEM_AT_CMS_ERROR – If the modem response was ‘+CMS ERROR’.

static inline int nrf_modem_at_err(int error)

Retrieve the specific CME or CMS error from the return value of a nrf_modem_at_printf or nrf_modem_at_cmd call.

Parameters:

• error – The return value of a nrf_modem_at_printf or nrf_modem_at_cmd call.

Returns:

int The CME or CMS error code.

struct nrf_modem_at_cmd_custom

#include <nrf_modem_at.h>

Custom AT command.

Application-defined AT command implementation.

Public Members

const char *const cmd

The AT command to implement.

const nrf_modem_at_cmd_custom_handler_t callback

The function implementing the AT command.

size_t cmd_strlen

Filter len

Bootloader API

group nrf_modem_bootloader

API for modem bootloader (Full DFU).

Defines

NRF_MODEM_BOOTLOADER_DIGEST_LEN

Digest buffer length.

NRF_MODEM_BOOTLOADER_UUID_LEN

UUID buffer length.

Functions

int nrf_modem_bootloader_bl_write(void *src, uint32_t len)

Write a segment of the bootloader to the modem.

Call after nrf_modem_bootloader_init() to upload the modem bootloader segments. Bootloader segments are appended together, so the bootloader may be uploaded with one or more call to this function. Once the entire bootloader is uploaded, call nrf_modem_bootloader_update().

Firmware segments can be uploaded after successful bootloader upload.

Parameters:

• src – [in] Pointer to the buffer where chunk data is stored.

• len – [in] Length of data to be written.

Return values:

• 0 – on success.

• -NRF_EINVAL – When src pointer is NULL or user tries to upload too big bootloader.

• -NRF_EOPNOTSUPP – If the modem is not in a state to receive.

int nrf_modem_bootloader_fw_write(uint32_t addr, void *src, uint32_t len)

Write a segment of the firmware to the modem.

Call after the modem bootloader have been written and updated to upload the modem firmware segments. Firmware segments are appended together, so the firmware may be uploaded with one or more call to this function. Once the entire firmware is uploaded, call nrf_modem_bootloader_update().

Parameters:

• addr – [in] Address to write the data to.

• src – [in] Pointer to the start of the buffer where the data to write is stored.

• len – [in] Length of the data to be written.

Return values:

• 0 – on success.

• -NRF_EINVAL – When src pointer is NULL, or user tries to upload too big bootloader, or addr parameter is zero after a bootloader upload.

• -NRF_EOPNOTSUPP – If the modem is not in a state to receive.

• -NRF_EPERM – When modem did not accept the flash programming request.

• -NRF_ENOEXEC – When flash programming failed.

• -NRF_ETIMEDOUT – When modem did not respond.

• -NRF_EIO – When incorrect response received from modem.

int nrf_modem_bootloader_update(void)

Complete bootloader or firmware update.

This call ensures that all parts from internal update buffers have been written to the modem. Call after the final bootloader segment or the final firmware segment has been written.

Return values:

• 0 – on success.

• -NRF_EOPNOTSUPP – If the modem is not in a state to receive.

• -NRF_EPERM – When modem did not accept the flash programming request.

• -NRF_ENOEXEC – When flash programming failed.

• -NRF_ETIMEDOUT – When modem did not respond.

• -NRF_EIO – When incorrect response received from modem.

int nrf_modem_bootloader_digest(struct nrf_modem_bootloader_fw_segment *segments, size_t num_segments, struct nrf_modem_bootloader_digest *digest_buffer)

Read a digest hash data from the modem.

Parameters:

• segments – [in] Firmware segments.

• num_segments – [in] Number of firmware segments.

• digest_buffer – [out] Pointer to the buffer to store digest hash data.

Return values:

• 0 – on success.

• -NRF_EINVAL – When digest_buffer pointer is NULL.

• -NRF_EOPNOTSUPP – If bootloader is not programmed.

• -NRF_EPERM – When modem did not accept RPC command.

• -NRF_ENOEXEC – When RPC command failed.

• -NRF_ETIMEDOUT – When modem did not respond.

• -NRF_EIO – When incorrect response received from modem.

int nrf_modem_bootloader_uuid(struct nrf_modem_bootloader_uuid *modem_uuid)

Read modem UUID data.

Parameters:

• modem_uuid – [out] Pointer to the buffer to store uuid data.

Return values:

• 0 – on success.

• -NRF_EINVAL – When modem_uuid pointer is NULL.

• -NRF_EOPNOTSUPP – If bootloader is not programmed.

• -NRF_EPERM – When modem did not accept RPC command.

• -NRF_ENOEXEC – When RPC command failed.

• -NRF_ETIMEDOUT – When modem did not respond.

• -NRF_EIO – When incorrect response received from modem.

int nrf_modem_bootloader_verify(const void *data, uint32_t len)

Verify the modem’ firmware signature.

Parameters:

• data – [in] Pointer to the buffer where the signature is stored.

• len – [in] Size of the signature.

Return values:

• 0 – on success.

• -NRF_EINVAL – When data pointer is NULL.

• -NRF_EOPNOTSUPP – If bootloader is not programmed.

• -NRF_EPERM – When modem did not accept RPC command.

• -NRF_ENOEXEC – When RPC command failed.

• -NRF_ETIMEDOUT – When modem did not respond.

• -NRF_EIO – When incorrect response received from modem.

struct nrf_modem_bootloader_digest

#include <nrf_modem_bootloader.h>

Storage for 256-bit digest/hash replies.

struct nrf_modem_bootloader_uuid

#include <nrf_modem_bootloader.h>

Modem UUID response.

struct nrf_modem_bootloader_fw_segment

#include <nrf_modem_bootloader.h>

Bootloader segment.

Delta DFU API

group nrf_modem_delta_dfu

API for Delta DFU.

Defines

NRF_MODEM_DELTA_DFU_UUID_LEN

Modem UUID length.

NRF_MODEM_DELTA_DFU_OFFSET_DIRTY

Offset value that indicates that the scratch area is dirty.

When the scratch area is dirty, it must be erased before a new firmware delta update can take place.

Functions

int nrf_modem_delta_dfu_uuid(struct nrf_modem_delta_dfu_uuid *modem_uuid)

Retrieve the modem firmware UUID.

Parameters:

• modem_uuid – Modem firmware UUID.

Return values:

• 0 – On success.

• -NRF_EPERM – The Modem library is not initialized.

• -NRF_ENOMEM – Not enough shared memory for this request.

• -NRF_EFAULT – If modem_uuid is NULL.

• -NRF_ESHUTDOWN – Modem was shut down.

Returns:

A positive error code from DFU errors, if the modem refused the operation.

int nrf_modem_delta_dfu_offset(size_t *off)

Retrieve the offset of the firmware image in the modem DFU area.

The offset will be zero if no image is in modem DFU area. The offset will be NRF_MODEM_DELTA_DFU_OFFSET_DIRTY if the modem DFU area needs to be erased before a new firmware update can be received.

Parameters:

• off – Offset of the firmware image.

Return values:

• 0 – On success.

• -NRF_EPERM – The Modem library is not initialized.

• -NRF_ENOMEM – Not enough shared memory for this request.

• -NRF_EFAULT – If off is NULL.

• -NRF_ESHUTDOWN – Modem was shut down.

Returns:

A positive error code from DFU errors, if the modem refused the operation.

int nrf_modem_delta_dfu_area(size_t *size)

Retrieve the size of the modem DFU area.

The size of the modem DFU area is the size of the FLASH area that the modem can use to receive an incoming firmware update.

Parameters:

• size – Size of the modem DFU area.

Return values:

• 0 – On success.

• -NRF_EPERM – The Modem library is not initialized.

• -NRF_ENOMEM – Not enough shared memory for this request.

• -NRF_EFAULT – If size is NULL.

• -NRF_ESHUTDOWN – Modem was shut down.

Returns:

A positive error code from DFU errors, if the modem refused the operation.

int nrf_modem_delta_dfu_write_init(void)

Ready the modem to receive a firmware update.

Ready the modem to receive a firmware update, acquiring the necessary resources. When a firmware update is not in progress, call nrf_modem_delta_dfu_write_done to release all resources.

Note

All functions of this interface, except nrf_modem_delta_dfu_write, are available regardless of the initialization status.

Return values:

• 0 – On success.

• -NRF_EPERM – The Modem library is not initialized.

• -NRF_EALREADY – Write already initialized.

• -NRF_ENOMEM – Not enough shared memory for this request.

• -NRF_ESHUTDOWN – Modem was shut down.

Returns:

A positive error code from DFU errors, if the modem refused the operation.

int nrf_modem_delta_dfu_write(const void *src, size_t len)

Write bytes from a delta patch to the modem DFU area.

Parameters:

• src – Firmware update bytes.

• len – Length of data being written.

Return values:

• 0 – On success.

• -NRF_EPERM – The Modem library is not initialized.

• -NRF_EFAULT – If src is NULL.

• -NRF_EINVAL – If len is zero.

• -NRF_ENOMEM – Not enough shared memory for this request.

• -NRF_ESHUTDOWN – Modem was shut down.

Returns:

A positive error code from DFU errors, if the modem refused the operation.

int nrf_modem_delta_dfu_write_done(void)

Pause receiving a modem firmware update and release resources.

Return values:

• 0 – On success.

• -NRF_EPERM – The Modem library is not initialized.

• -NRF_ENOMEM – Not enough shared memory for this request.

• -NRF_ESHUTDOWN – Modem was shut down.

Returns:

A positive error code from DFU errors, if the modem refused the operation.

int nrf_modem_delta_dfu_erase(void)

Erase the modem DFU area.

The modem DFU area must be erased before receiving a new firmware update. This function will return after commencing the erase operation, but it will not wait for its completion. Further calls to the delta DFU APIs will return MODEM_DELTA_DFU_ERASE_PENDING as long as the erase operation is pending or ongoing.

The application may poll the offset until it returns zero, to determine if the operation has completed.

Note

The erase operation may take longer when registered to the network than when not registered, i.e. in airplane mode.

Return values:

• 0 – On success.

• -NRF_EPERM – The Modem library is not initialized.

• -NRF_ENOMEM – Not enough shared memory for this request.

• -NRF_ESHUTDOWN – Modem was shut down.

Returns:

A positive error code from DFU errors, if the modem refused the operation.

int nrf_modem_delta_dfu_update(void)

Schedule execution of firmware update.

The modem needs to reboot to run the new firmware. To reboot the modem, uninitialize the Modem library and reinitialize it using the nrf_modem_deinit and nrf_modem_init respectively.

Note

The final result of the update operation is reported via nrf_modem_init.

Return values:

• 0 – On success.

• -NRF_EPERM – The Modem library is not initialized.

• -NRF_ENOMEM – Not enough shared memory for this request.

• -NRF_ESHUTDOWN – Modem was shut down.

Returns:

A positive error code from DFU errors, if the modem refused the operation.

int nrf_modem_delta_dfu_rollback(void)

Schedule a rollback to the previous firmware.

The modem needs to reboot to run the previous firmware. To reboot the modem, uninitialize the Modem library and reinitialize it using the nrf_modem_deinit and nrf_modem_init respectively.

Note

The final result of the rollback operation is reported via nrf_modem_init.

Return values:

• 0 – On success.

• -NRF_EPERM – The Modem library is not initialized.

• -NRF_ENOMEM – Not enough shared memory for this request.

• -NRF_ESHUTDOWN – Modem was shut down.

Returns:

A positive error code from DFU errors, if the modem refused the operation.

struct nrf_modem_delta_dfu_uuid

#include <nrf_modem_delta_dfu.h>

Modem UUID.

group nrf_modem_delta_dfu_errors

Delta DFU errors.

Defines

NRF_MODEM_DELTA_DFU_NO_ERROR

No error

NRF_MODEM_DELTA_DFU_RECEIVER_OUT_OF_MEMORY

Modem out of memory

NRF_MODEM_DELTA_DFU_RECEIVER_BLOCK_TOO_LARGE

Block too large

NRF_MODEM_DELTA_DFU_INVALID_HEADER_DATA

Invalid header

NRF_MODEM_DELTA_DFU_ERROR_INTERNAL_00

Internal error

NRF_MODEM_DELTA_DFU_INVALID_DATA

Invalid patch

NRF_MODEM_DELTA_DFU_ERROR_INTERNAL_01

Internal error

NRF_MODEM_DELTA_DFU_ERROR_INTERNAL_02

Internal error

NRF_MODEM_DELTA_DFU_ERROR_INTERNAL_03

Internal error

NRF_MODEM_DELTA_DFU_INVALID_UUID

Wrong patch for current modem

NRF_MODEM_DELTA_DFU_INVALID_ADDRESS

Invalid address

NRF_MODEM_DELTA_DFU_AREA_NOT_BLANK

Scratch area not erased

NRF_MODEM_DELTA_DFU_WRITE_ERROR

Failed to write

NRF_MODEM_DELTA_DFU_ERASE_ERROR

Failed to erase

NRF_MODEM_DELTA_DFU_INVALID_FILE_OFFSET

Invalid offset

NRF_MODEM_DELTA_DFU_PROGRESS_LOG_INVALID

Operation log corrupt

NRF_MODEM_DELTA_DFU_INVALID_RESUME_ATTEMPT

Invalid resume attempt

NRF_MODEM_DELTA_DFU_ERASE_PENDING

Erase operation is pending

NRF_MODEM_DELTA_DFU_OPERATION_NOT_ALLOWED

Operation not allowed

NRF_MODEM_DELTA_DFU_INCOMPLETE_DATA

Patch is incomplete

NRF_MODEM_DELTA_DFU_INTERRUPTED_WRITE

Write was interrupted

NRF_MODEM_DELTA_DFU_INVALID_OPERATION

Invalid operation

NRF_MODEM_DELTA_DFU_ERROR_INTERNAL_04

Internal error

NRF_MODEM_DELTA_DFU_NOT_ALLOWED_POFWARN_ON

Refused because of POFWARN

DECT NR+ PHY API

group nrf_modem_dect_phy

DECT PHY API.

Links to pertaining specification and regulations.

• [DECT-2020 NR Part 2: Radio reception and transmission requirements] (https://www.etsi.org/deliver/etsi_ts/103600_103699/10363602/01.05.01_60/ts_10363602v010501p.pdf)

• [DECT-2020 NR Part 4: MAC specification] (https://www.etsi.org/deliver/etsi_ts/103600_103699/10363604/01.05.01_60/ts_10363604v010501p.pdf)

• [DECT Harmonised Standard for access to radio spectrum; Part 2: DECT-2020 NR ] (https://etsi.org/deliver/etsi_en/301400_301499/30140602/03.01.01_60/en_30140602v030101p.pdf)

• [47 CFR Part 15.323] (https://www.ecfr.gov/current/title-47/section-15.323)

Defines

NRF_MODEM_DECT_MODEM_TIME_TICK_RATE_KHZ

Modem time tick rate.

NRF_MODEM_DECT_SYMBOL_DURATION

Duration of a single DECT symbol in modem time units.

NRF_MODEM_DECT_LBT_PERIOD_MAX

Maximum LBT measurement period in modem time units.

NRF_MODEM_DECT_LBT_PERIOD_MIN

Minimum LBT measurement period in modem time units.

NRF_MODEM_DECT_PHY_RSSI_NOT_MEASURED

Symbol RSSI not measured.

NRF_MODEM_DECT_PHY_TEMP_NOT_MEASURED

Temperature not measured.

NRF_MODEM_DECT_PHY_RSSI2_NOT_MEASURED

RSSI-2 not measured.

NRF_MODEM_DECT_PHY_SNR_NOT_MEASURED

Signal to noise ratio not measured.

NRF_MODEM_DECT_PHY_BS_CQI_NOT_USED

Buffer status and Channel quality indicator not used.

NRF_MODEM_DECT_PHY_LINK_UNSPECIFIED

Unspecified link identifier.

Enums

enum nrf_modem_dect_phy_err

DECT PHY errors.

Values:

enumerator NRF_MODEM_DECT_PHY_SUCCESS

Success.

enumerator NRF_MODEM_DECT_PHY_ERR_LBT_CHANNEL_BUSY

TX operation canceled because LBT channel was busy.

enumerator NRF_MODEM_DECT_PHY_ERR_UNSUPPORTED_OP

Operation is not an RX operation; only RX operations may be stopped.

enumerator NRF_MODEM_DECT_PHY_ERR_NO_ONGOING_OP

Operation is not executing; it cannot be stopped.

enumerator NRF_MODEM_DECT_PHY_ERR_NO_MEMORY

Modem out of memory.

enumerator NRF_MODEM_DECT_PHY_ERR_NOT_ALLOWED

Request not possible in current state.

enumerator NRF_MODEM_DECT_PHY_OK_WITH_HARQ_RESET

HARQ feedback transmission successful.

Out of memory for HARQ processes, HARQ reset requested with feedback format 6.

enumerator NRF_MODEM_DECT_PHY_ERR_OP_START_TIME_LATE

Operation start time is in the past.

enumerator NRF_MODEM_DECT_PHY_ERR_LBT_START_TIME_LATE

Listen-before-talk start time is in the past.

enumerator NRF_MODEM_DECT_PHY_ERR_RF_START_TIME_LATE

RF start time is in the past.

enumerator NRF_MODEM_DECT_PHY_ERR_INVALID_START_TIME

Another operation is executing; operation cannot start immediately.

enumerator NRF_MODEM_DECT_PHY_ERR_OP_SCHEDULING_CONFLICT

Another operation is scheduled to be executed at the specified time.

enumerator NRF_MODEM_DECT_PHY_ERR_OP_TIMEOUT

Operation start time missed and can’t be executed.

enumerator NRF_MODEM_DECT_PHY_ERR_NO_ONGOING_HARQ_RX

No ongoing HARQ RX; unable to transmit a HARQ response.

enumerator NRF_MODEM_DECT_PHY_ERR_PARAMETER_UNAVAILABLE

Could not copy parameters in time.

enumerator NRF_MODEM_DECT_PHY_ERR_PAYLOAD_UNAVAILABLE

Could not copy payload in time.

enumerator NRF_MODEM_DECT_PHY_ERR_OP_CANCELED

Operation canceled.

enumerator NRF_MODEM_DECT_PHY_ERR_COMBINED_OP_FAILED

Operation not executed because combined operation failed.

enumerator NRF_MODEM_DECT_PHY_ERR_UNSUPPORTED_CARRIER

Unsupported carrier.

enumerator NRF_MODEM_DECT_PHY_ERR_UNSUPPORTED_DATA_SIZE

Unsupported TBS size.

enumerator NRF_MODEM_DECT_PHY_ERR_INVALID_NETWORK_ID

Invalid network ID.

enumerator NRF_MODEM_DECT_PHY_ERR_INVALID_PHY_HEADER

Invalid physical header format or type.

enumerator NRF_MODEM_DECT_PHY_ERR_INVALID_DURATION

Operation duration out of allowed range.

enumerator NRF_MODEM_DECT_PHY_ERR_INVALID_PARAMETER

Invalid parameter.

enumerator NRF_MODEM_DECT_PHY_ERR_MODEM_ERROR

Modem error.

enumerator NRF_MODEM_DECT_PHY_ERR_MODEM_ERROR_RF_STATE

Modem error, invalid RF state.

enumerator NRF_MODEM_DECT_PHY_ERR_TEMP_HIGH

Modem temperature is equal or higher than the critical temperature limit.

enumerator NRF_MODEM_DECT_PHY_ERR_PROD_LOCK

Failed to lock device after production.

enum nrf_modem_dect_phy_rx_mode

Reception mode.

Values:

enumerator NRF_MODEM_DECT_PHY_RX_MODE_CONTINUOUS

Continuous reception.

The reception is continued automatically after PDC reception.

enumerator NRF_MODEM_DECT_PHY_RX_MODE_SEMICONTINUOUS

Semicontinous reception.

Similar to continuous reception, but will stop after receiving a unicast PDC.

enumerator NRF_MODEM_DECT_PHY_RX_MODE_SINGLE_SHOT

Single-shot reception.

The reception is terminated automatically after the first successful PDC reception.

enum nrf_modem_dect_phy_rssi_interval

RSSI reporting interval.

Values:

enumerator NRF_MODEM_DECT_PHY_RSSI_INTERVAL_OFF

Do not measure RSSI.

This value is only allowed for RX operations.

enumerator NRF_MODEM_DECT_PHY_RSSI_INTERVAL_12_SLOTS

RSSI reporting interval is 12 slots (5ms).

enumerator NRF_MODEM_DECT_PHY_RSSI_INTERVAL_24_SLOTS

RSSI reporting interval is 24 slots (10ms).

enum nrf_modem_dect_phy_hdr_status

Physical header status.

Values:

enumerator NRF_MODEM_DECT_PHY_HDR_STATUS_VALID

PHY header is valid; PDC can be received.

enumerator NRF_MODEM_DECT_PHY_HDR_STATUS_INVALID

PHY header is invalid; PDC can’t be received.

enumerator NRF_MODEM_DECT_PHY_HDR_STATUS_VALID_RX_END

PHY header is valid, but RX operation ends before PDC reception.

Functions

int nrf_modem_dect_phy_callback_set(const struct nrf_modem_dect_phy_callbacks *cb)

Set application callbacks for PHY operations.

The application must set the callbacks for PHY operations before attempting other operations. That includes PHY initialization itself, that is, nrf_modem_dect_phy_init().

Parameters:

• cb – Application callbacks.

Return values:

• -NRF_EFAULT – cb is NULL.

• -NRF_EINVAL – One of the fields in cb is NULL.

Returns:

0 On success.

int nrf_modem_dect_phy_capability_get(void)

Retrieve DECT PHY capabilities.

This operation is asynchronous. The result of the operation is sent to the nrf_modem_dect_phy_callbacks::capability_get callback.

Return values:

• -NRF_EPERM – The Modem library is not initialized.

• -NRF_EFAULT – Callback configuration is invalid.

• -NRF_ENOMEM – Not enough shared memory for this request.

Returns:

0 On success.

int nrf_modem_dect_phy_init(const struct nrf_modem_dect_phy_init_params *params)

Initialize DECT PHY interface.

This operation is asynchronous. The result of the operation is sent to the nrf_modem_dect_phy_callbacks::init callback.

Parameters:

• params – [in] Configuration parameters.

Return values:

• 0 – Request was sent to modem.

• -NRF_EPERM – The Modem library is not initialized.

• -NRF_EFAULT – Callback configuration is invalid, or params is NULL.

• -NRF_ENOMEM – Not enough shared memory for this request.

int nrf_modem_dect_phy_deinit(void)

De-initialize DECT PHY interface.

Cancel all operations and de-initialize the PHY.

This operation is asynchronous. The result of the operation is sent to the nrf_modem_dect_phy_callbacks::deinit callback.

Return values:

• 0 – Request was sent to modem.

• -NRF_EPERM – The Modem library is not initialized.

• -NRF_EFAULT – Callback configuration is invalid.

• -NRF_ENOMEM – Not enough shared memory for this request.

int nrf_modem_dect_phy_rx(const struct nrf_modem_dect_phy_rx_params *params)

Schedule a reception.

Schedule a continuous, semicontinuous or single shot reception at a given time, with parameters.

Incoming data received on the physical layer control and data channels is sent to the nrf_modem_dect_phy_callbacks::pcc and nrf_modem_dect_phy_callbacks::pdc callbacks.

When the operation has completed, either successfully or unsuccessfully, the result is sent to the nrf_modem_dect_phy_callbacks::op_complete callback, with a handle parameter equal to the handle specified in params.

Parameters:

• params – [in] Operation parameters.

Return values:

• 0 – Request was sent to modem.

• -NRF_EPERM – The Modem library is not initialized.

• -NRF_EFAULT – Callback configuration is invalid, or params is NULL.

• -NRF_ENOMEM – Not enough shared memory for this request.

int nrf_modem_dect_phy_tx(const struct nrf_modem_dect_phy_tx_params *params)

Schedule a transmission.

Schedule a data transmission with given parameters.

When the operation has completed, either successfully or unsuccessfully, the result is sent to the nrf_modem_dect_phy_callbacks::op_complete callback, with a handle parameter equal to the handle specified in params.

Parameters:

• params – [in] Operation parameters.

Return values:

• 0 – Request was sent to modem.

• -NRF_EPERM – The Modem library is not initialized.

• -NRF_EFAULT – Callback configuration is invalid, or params is NULL.

• -NRF_ENOMEM – Not enough shared memory for this request.

int nrf_modem_dect_phy_tx_harq(const struct nrf_modem_dect_phy_tx_params *params)

Schedule a HARQ response TX operation.

A HARQ response TX can be scheduled as a response to a PCC callback or PCC CRC failure callback.

Scheduling a HARQ response is time critical and therefore scheduling should be done directly from the PCC callback. The MAC should have prepared data towards possible HARQ recipients in advance so that it can directly call this function without further delays.

This function should only be used to send a Physical Layer Control Field: Type 2 packet with Feedback info format 1 in response to a PCC notification for an ongoing RX so that the receiver identity of the packet being transmitted matches the transmitter identity of the packet being received. In that case modem will inject ACK or NACK feedback into the Transmission feedback field based on the PDC reception result once the reception is complete.

When the operation has completed, either successfully or unsuccessfully, the result is sent to the nrf_modem_dect_phy_callbacks::op_complete callback, with a handle parameter equal to the handle specified in params.

Parameters:

• params – [in] Operation parameters.

Return values:

• 0 – Request was sent to modem.

• -NRF_EPERM – The Modem library is not initialized.

• -NRF_EFAULT – Callback configuration is invalid, or params is NULL.

• -NRF_ENOMEM – Not enough shared memory for this request.

int nrf_modem_dect_phy_tx_rx(const struct nrf_modem_dect_phy_tx_rx_params *params)

Schedule one TX and one RX operation.

Schedule one TX and one RX operation to be executed one after the other. The scheduling of both operations has to be successful, or no operation will be scheduled.

The RX operation is executed only if the TX operation is successful, including LBT, if used. The RX operation scheduling is relative to the end of the TX operation and must include the guard time.

When the TX operation has completed, either successfully or unsuccessfully, the result is sent to the nrf_modem_dect_phy_callbacks::op_complete callback, with a handle parameter equal to the handle specified in params.tx.

When the RX operation has completed, either successfully or unsuccessfully, the result is sent to the nrf_modem_dect_phy_callbacks::op_complete callback, with a handle parameter equal to the handle specified in params.rx.

Parameters:

• params – [in] Operation parameters.

Return values:

• 0 – Request was sent to the modem.

• -NRF_EPERM – The Modem library is not initialized.

• -NRF_EFAULT – Callback configuration is invalid, or params is NULL.

• -NRF_ENOMEM – Not enough shared memory for this request.

int nrf_modem_dect_phy_rssi(const struct nrf_modem_dect_phy_rssi_params *params)

Schedule an RSSI measurement operation.

Schedule an RSSI measurement operation with given parameters. The measurements are sent to the nrf_modem_dect_phy_callbacks::rssi callback.

When the operation has completed, either successfully or unsuccessfully, the result is sent to the nrf_modem_dect_phy_callbacks::op_complete callback, with a handle parameter equal to the handle specified in params.

Parameters:

• params – [in] Operation parameters.

Return values:

• 0 – Request was sent to modem.

• -NRF_EPERM – The Modem library is not initialized.

• -NRF_EFAULT – Callback configuration is invalid, or params is NULL.

• -NRF_ENOMEM – Not enough shared memory for this request.

int nrf_modem_dect_phy_rx_stop(uint32_t handle)

Stop an ongoing reception.

Stop an ongoing reception before its duration has ended; this can take more or less time depending on the internal state of the operation at the time the request is received.

This operation is asynchronous. The result of the operation is sent to the nrf_modem_dect_phy_callbacks::rx_stop callback.

Note

Only RX operations can be stopped.

Parameters:

• handle – Handle of the operation to be stopped.

Return values:

• 0 – Request was sent to modem.

• -NRF_EPERM – The Modem library is not initialized.

• -NRF_EFAULT – Callback configuration is invalid.

• -NRF_ENOMEM – Not enough shared memory for this request.

int nrf_modem_dect_phy_link_config(const struct nrf_modem_dect_phy_link_config_params *params)

Configure links.

This operation is asynchronous. The result of the operation is sent to the nrf_modem_dect_phy_callbacks::link_config callback.

Parameters:

• params – [in] Link configuration parameters.

Return values:

• 0 – Request was sent to modem.

• -NRF_EPERM – The Modem library is not initialized.

• -NRF_EFAULT – Callback configuration is invalid, or params is NULL.

• -NRF_ENOMEM – Not enough shared memory for this request.

• -NRF_ENOSYS – Functionality not implemented.

int nrf_modem_dect_phy_time_get(void)

Query modem time.

Retrieve modem time, in modem time units.

This operation is asynchronous. The result of the operation is sent to the nrf_modem_dect_phy_callbacks::time_get callback.

Return values:

• 0 – Request was sent to modem.

• -NRF_EPERM – The Modem library is not initialized.

• -NRF_EFAULT – Callback configuration is invalid.

• -NRF_ENOMEM – Not enough shared memory for this request.

struct nrf_modem_dect_phy_modem_cfg

#include <nrf_modem_dect_phy.h>

Modem PHY configuration.

Includes radio state transition latencies and operating temperature limit.

Public Members

int16_t temperature_limit

Maximum operating temperature, in degrees Celsius.

The minimum resolution is 1 degree Celsius.

uint32_t idle_to_rssi

From Idle to RSSI RF sampling start.

uint32_t rssi_to_idle

From RF sampling of RSSI to Idle.

uint32_t idle_to_rx

From Idle to RX RF sampling start.

uint32_t rx_to_idle

From RF sampling of RX to Idle.

uint32_t rx_rssi_to_idle

From RF sampling of RX with RSSI measurement to Idle.

uint32_t rx_stop_to_rf_off

From RX stop request to RF sampling stop.

uint32_t rx_rssi_stop_to_rf_off

From RX with RSSI measurement stop request to RF sampling stop.

uint32_t idle_to_tx

From Idle to TX RF sample transmission start.

uint32_t idle_to_tx_with_lbt

From Idle to TX with LBT monitoring RF sampling start.

uint32_t tx_to_idle

From TX RF sample transmission end (with or without LBT) to Idle.

uint32_t idle_to_txrx_with_lbt

From Idle to TX with LBT monitoring RF sampling start in TX-RX operation.

uint32_t txrx_tx_to_rx

From TX RF sample transmission end to RX RF sampling start in TX-RX operation.

struct nrf_modem_dect_phy_modem_cfg.[anonymous] latency

Latency of radio state transitions, in modem time units.

struct nrf_modem_dect_phy_capability

#include <nrf_modem_dect_phy.h>

Modem PHY capabilities.

Public Members

uint8_t dect_version

DECT NR+ version.

uint8_t variant_count

Number of elements in variant.

uint8_t power_class

Power class.

uint8_t rx_spatial_streams

Supported reception capability of spatial stream transmissions.

uint8_t rx_tx_diversity

Reception capability of TX diversity transmission.

int8_t rx_gain

Receiver sensitivity in dB.

uint8_t mcs_max

Maximum supported modulation and coding scheme for reception.

uint32_t harq_soft_buf_size

HARQ soft buffer size.

uint8_t harq_process_count_max

Maximum number of HARQ processes.

uint8_t harq_feedback_delay

HARQ feedback delay, in subslots.

uint8_t mu

Subcarrier scaling factor.

uint8_t beta

Fourier transform scaling factor.

struct nrf_modem_dect_phy_capability.[anonymous] variant[]

Capability variants.

union nrf_modem_dect_phy_hdr

#include <nrf_modem_dect_phy.h>

Physical header.

See 6.2.1 in DECT-2020 NR Part 4.

Public Members

uint8_t type_1[5]

Header type 1.

uint8_t type_2[10]

Header type 2.

struct nrf_modem_dect_phy_link_id

#include <nrf_modem_dect_phy.h>

Radio link identifier.

Radio link identifier identifies a radio link using fields that are available in Physical Layer Control Field.

Public Members

uint8_t short_network_id

Short Network ID.

See 6.2.1 in DECT-2020 NR Part 4.

uint16_t short_rd_id

Short Radio Device ID.

Big endian encoding. Used for transmitter identity in DECT-2020 NR Part 4.

struct nrf_modem_dect_phy_rx_filter

#include <nrf_modem_dect_phy.h>

Specification for reception filter.

For any enabled filter element the received PCC packet must match the corresponding filter element value for the PCC to be accepted. PCC rejection will stop PDC reception and return processing to synchronization search.

See 6.2.1 in DECT-2020 NR Part 4.

Public Members

uint8_t short_network_id

Short Network ID.

The Short Network ID field of a received PCC MAC Physical Header must match this value for the PCC to be accepted.

See 6.2.1 and 4.2.3.1 in DECT-2020 NR Part 4.

uint8_t is_short_network_id_used

Short Network ID filter activation.

Set to 0 to disable Short Network ID filtering. Set to 1 to enable Short Network ID filtering.

uint16_t receiver_identity

Receiver Identity.

If set to 0, filtering based on Receiver Identity is disabled.

For any other value, the Receiver Identify field in a packet’s MAC Physical Header must match the value (or contain the broadcast ID) for the packet to be accepted.

See 6.2.1 and 4.2.3.3 in DECT-2020 NR Part 4.

struct nrf_modem_dect_phy_rx_pcc_status

#include <nrf_modem_dect_phy.h>

Reception parameters (PCC).

Public Members

uint64_t stf_start_time

Synchronization Training Field start time.

Start time of the STF of this reception in modem time.

uint8_t phy_type

Physical layer control field type.

Valid values are 0 and 1 corresponding types 1 and 2, respectively.

See 6.2.1 in DECT-2020 NR Part 4.

enum nrf_modem_dect_phy_hdr_status header_status

Validity of the physical header.

int16_t rssi_2

Received signal strength indicator (RSSI-2).

Values are in dBm with 0.5 dBm resolution (Q14.1).

See 8.3 in DECT-2020 NR Part 2.

int16_t snr

Received signal to noise indicator (SNR).

Values are dB values with 0.25 dB resolution (Q13.2).

See 8.4 in DECT-2020 NR Part 2.

struct nrf_modem_dect_phy_rx_pdc_status

#include <nrf_modem_dect_phy.h>

Reception parameters (PDC).

Public Members

int16_t rssi_2

Received signal strength indicator (RSSI-2).

Values are in dBm with 0.5 dBm resolution (Q14.1).

See 8.3 in DECT-2020 NR Part 2.

int16_t snr

Received signal to noise indicator (SNR).

Values are dB values with 0.25 dB resolution (Q13.2).

See 8.4 in DECT-2020 NR Part 2.

struct nrf_modem_dect_phy_rx_pcc_crc_failure

#include <nrf_modem_dect_phy.h>

Reception parameters for PCC CRC failures.

Public Members

uint64_t stf_start_time

Synchronization Training Field start time.

Start time of the STF of this reception in modem time.

int16_t rssi_2

Received signal strength indicator (RSSI-2).

Values are in dBm with 0.5 dBm resolution (Q14.1).

See 8.3 in DECT-2020 NR Part 2.

int16_t snr

Received signal to noise indicator (SNR).

Values are dB values with 0.25 dB resolution (Q13.2).

See 8.4 in DECT-2020 NR Part 2.

struct nrf_modem_dect_phy_rx_pdc_crc_failure

#include <nrf_modem_dect_phy.h>

Reception parameters for PDC CRC failures.

Public Members

int16_t rssi_2

Received signal strength indicator (RSSI-2).

Values are in dBm with 0.5 dBm resolution (Q14.1).

If this value is not measured, it is reported as NRF_MODEM_DECT_PHY_RSSI2_NOT_MEASURED.

See 8.3 in DECT-2020 NR Part 2.

int16_t snr

Received signal to noise indicator (SNR).

Values are dB values with 0.25 dB resolution (Q13.2).

If this value is not measured, it is reported as NRF_MODEM_DECT_PHY_SNR_NOT_MEASURED.

See 8.4 in DECT-2020 NR Part 2.

struct nrf_modem_dect_phy_rssi_meas

#include <nrf_modem_dect_phy.h>

RSSI measurement.

Public Members

uint64_t meas_start_time

Measurement start time, in modem time units.

uint32_t handle

Handle of the operation.

uint16_t carrier

The absolute channel frequency number on which the measurements were made.

uint16_t meas_len

Number of measurements in meas.

int8_t *meas

RSSI measurements, in dBm.

If a symbol is measured, its measurement is in the interval [-1, -140]. If the measurement is saturated, the measured signal strength is reported as a positive integer. If a symbol is not measured, its value is reported as NRF_MODEM_DECT_PHY_RSSI_NOT_MEASURED.

struct nrf_modem_dect_phy_rx_params

#include <nrf_modem_dect_phy.h>

RX operation.

Public Members

uint64_t start_time

Operation start time as modem time.

If zero, the operation will be executed immediately.

This kind of scheduling can only be done when the modem is idle.

uint32_t handle

Handle for the RX operation.

An application-defined handle for the operation.

uint32_t network_id

Network ID for scrambling.

Can be zero if receiving only beacons.

enum nrf_modem_dect_phy_rx_mode mode

Reception mode.

enum nrf_modem_dect_phy_rssi_interval rssi_interval

RSSI measurement reporting interval.

struct nrf_modem_dect_phy_link_id link_id

Radio link identifier.

Set to NRF_MODEM_DECT_PHY_LINK_UNSPECIFIED if expecting to receive from any Radio Device within the primary network (either the primary link or any downlink device).

Set to the link id of a secondary link if expecting to receive over that link.

int8_t rssi_level

Expected antenna signal level of the reception.

Values in range [-128, -1] are dBm values for the expected reception level.

Value 0 is interpreted as MAC having no knowledge of the expected level. This initiates a fast AGC algorithm that tries to adjust the reception gain level based on the received signal level.

If the duration of the RX operation is long enough to receive multiple slots, rssi_level will only be used for the first successful reception. Subsequent receptions during the same RX operation are initiated using a level that has been adjusted based on the previous successful reception (slow AGC).

uint16_t carrier

The absolute channel frequency number for the reception.

See 5.4.2 of DECT-2020 NR Part 2.

uint32_t duration

Duration of reception in modem time units.

struct nrf_modem_dect_phy_rx_filter filter

Reception filter for this operation.

struct nrf_modem_dect_phy_tx_params

#include <nrf_modem_dect_phy.h>

TX operation.

Public Members

uint64_t start_time

Operation start time as modem time.

If zero, the operation will be executed immediately.

This kind of scheduling can only be done when the modem is idle.

uint32_t handle

Handle for the TX operation.

An application-defined handle for the operation.

uint32_t network_id

Network ID for scrambling.

Must not be zero.

uint8_t phy_type

Physical layer control field type.

Valid values are 0 and 1 corresponding Type 1 and Type 2.

See 6.2.1 of DECT-2020 NR Part 4.

int8_t lbt_rssi_threshold_max

Listen before talk maximum RSSI threshold, in dBm.

The measured RSSI-1 needs to be smaller than this value for the channel to be considered available for TX.

See 5.1.2 of DECT-2020 NR Part 4.

Note

RSSI measurements during LBT are quantized to implementation defined limits, so the value given here may not be exactly the applied LBT RSSI threshold.

uint16_t carrier

The absolute channel frequency number for the transmission.

See 5.4.2 of DECT-2020 NR Part 2.

Warning

You must ensure that you are complying with applicable regulations when transmitting. If you are operating your device in Europe, you must refer to table 4.3.2.3-2 of DECT Harmonised Standard. If you are operating your device in the United States, you must refer to 47 CFR Part 15.323.

uint32_t lbt_period

Listen before talk period in modem time units.

The period that the channel needs to be measured “free” or “possible” before initiating transmission.

The period is split into up to 64 individual integration periods, each period being an integer multiple of a symbol duration (2880 modem time units). All integration periods have the same length, maximum 7 symbols. The maximum number of integration periods is used. For example, LBT periods of up to 64 symbols will be split into one symbol long integration periods, and LBT periods of 65-128 symbols will be split into two symbol long integration periods. If necessary the LBT period may be shortened slightly to fit these constraints while still not exceeding the given LBT length, e.g. a period of 71 symbols will effectively be 70 symbols long (35 periods of 2 symbols).

In case the channel is initially detected “busy” the modem will not continue measuring the channel. Instead the modem will report an error. Rescheduling a transmission is left up to the higher layer.

If set to zero, LBT is not used. Otherwise the acceptable value range is [NRF_MODEM_DECT_LBT_PERIOD_MIN, NRF_MODEM_DECT_LBT_PERIOD_MAX].

union nrf_modem_dect_phy_hdr *phy_header

Physical header corresponding to the physical layer control field type.

uint8_t bs_cqi

Buffer status and channel quality indicator.

Only used for HARQ transmissions, with nrf_modem_dect_phy_tx_harq.

Set to NRF_MODEM_DECT_PHY_BS_CQI_NOT_USED otherwise.

See 6.2.2-3 and 6.2.2-4 of DECT-2020 NR Part 4.

uint8_t *data

The data to be sent.

uint32_t data_size

Size of the data in bytes.

struct nrf_modem_dect_phy_tx_rx_params

#include <nrf_modem_dect_phy.h>

Combined TX and RX operation.

Public Members

struct nrf_modem_dect_phy_tx_params tx

TX operation.

struct nrf_modem_dect_phy_rx_params rx

RX operation.

The start time of the RX operation is relative to the end of the TX operation and it must include the guard time.

struct nrf_modem_dect_phy_rssi_params

#include <nrf_modem_dect_phy.h>

RSSI-1 measurement operation.

Public Members

uint64_t start_time

Operation start time as modem time.

If zero, the operation will be executed immediately.

This kind of scheduling can only be done when the modem is idle.

uint32_t handle

Handle for the RSSI operation.

An application-defined handle for the operation.

uint16_t carrier

The absolute channel frequency number for the RSSI measurement operation.

See 5.4.2 of DECT-2020 NR Part 2.

uint32_t duration

Duration of measurement in subslots.

The maximum duration is 297600 subslots. The minimum duration is 1 subslot.

enum nrf_modem_dect_phy_rssi_interval reporting_interval

RSSI measurements reporting interval, in subslots.

struct nrf_modem_dect_phy_link_config_params

#include <nrf_modem_dect_phy.h>

Link configuration parameters.

Public Members

struct nrf_modem_dect_phy_link_id primary_link_id

Primary link.

The modem tracks the frequency of the primary link for Automatic Frequency Control purposes. This frequency is propagated down the tree, that is, the Radio Device uses this frequency for all its radio operations except those directed to secondary links.

uint8_t secondary_link_count

Number of secondary links.

struct nrf_modem_dect_phy_link_id secondary_link_ids[]

Secondary links.

The modem tracks the frequency of secondary links for Automatic Frequency Control purposes. When communicating with a secondary link the modem compensates the frequency difference between the secondary link and the primary link.

struct nrf_modem_dect_phy_callbacks

#include <nrf_modem_dect_phy.h>

DECT PHY callbacks.

Callbacks for user operations and incoming data.

Note

All callbacks are executed in ISR.

Public Members

void (*init)(const uint64_t *time, int16_t temp, enum nrf_modem_dect_phy_err err, const struct nrf_modem_dect_phy_modem_cfg *cfg)

DECT PHY initialization callback.

The err parameter indicates the result of the operation. It can be one of the following values:

• NRF_MODEM_DECT_PHY_SUCCESS

• NRF_MODEM_DECT_PHY_ERR_NOT_ALLOWED

• NRF_MODEM_DECT_PHY_ERR_TEMP_HIGH

• NRF_MODEM_DECT_PHY_ERR_PROD_LOCK

Param time:

[in] Modem time, in modem time units.

Param temp:

Temperature in degrees Celsius.

Param err:

Operation result.

Param cfg:

[in] Modem configuration.

void (*op_complete)(const uint64_t *time, int16_t temperature, enum nrf_modem_dect_phy_err err, uint32_t handle)

Callback to indicate the completion of RX, TX and RSSI measurement operations.

The err parameter indicates the result of the operation. It can be one of the following values:

• NRF_MODEM_DECT_PHY_SUCCESS

• NRF_MODEM_DECT_PHY_ERR_LBT_CHANNEL_BUSY

• NRF_MODEM_DECT_PHY_ERR_NO_MEMORY

• NRF_MODEM_DECT_PHY_ERR_NOT_ALLOWED

• NRF_MODEM_DECT_PHY_OK_WITH_HARQ_RESET

• NRF_MODEM_DECT_PHY_ERR_OP_START_TIME_LATE

• NRF_MODEM_DECT_PHY_ERR_LBT_START_TIME_LATE

• NRF_MODEM_DECT_PHY_ERR_RF_START_TIME_LATE

• NRF_MODEM_DECT_PHY_ERR_INVALID_START_TIME

• NRF_MODEM_DECT_PHY_ERR_OP_SCHEDULING_CONFLICT

• NRF_MODEM_DECT_PHY_ERR_OP_TIMEOUT

• NRF_MODEM_DECT_PHY_ERR_NO_ONGOING_HARQ_RX

• NRF_MODEM_DECT_PHY_ERR_PARAMETER_UNAVAILABLE

• NRF_MODEM_DECT_PHY_ERR_PAYLOAD_UNAVAILABLE

• NRF_MODEM_DECT_PHY_ERR_OP_CANCELED

• NRF_MODEM_DECT_PHY_ERR_COMBINED_OP_FAILED

• NRF_MODEM_DECT_PHY_ERR_UNSUPPORTED_CARRIER

• NRF_MODEM_DECT_PHY_ERR_UNSUPPORTED_DATA_SIZE

• NRF_MODEM_DECT_PHY_ERR_INVALID_NETWORK_ID

• NRF_MODEM_DECT_PHY_ERR_INVALID_PHY_HEADER

• NRF_MODEM_DECT_PHY_ERR_INVALID_DURATION

• NRF_MODEM_DECT_PHY_ERR_INVALID_PARAMETER

• NRF_MODEM_DECT_PHY_ERR_TEMP_HIGH

Param time:

[in] Modem time, in modem time units.

Param temp:

Temperature in degrees Celsius.

Param err:

Operation result.

Param handle:

Operation handle.

void (*rssi)(const uint64_t *time, const struct nrf_modem_dect_phy_rssi_meas *meas)

Callback to receive RSSI measurements.

Callback function to receive the RSSI measurements requested with nrf_modem_dect_phy_rssi or nrf_modem_dect_phy_rx.

Param time:

[in] Modem time, in modem time units.

Param meas:

[in] RSSI measurement.

void (*rx_stop)(const uint64_t *time, enum nrf_modem_dect_phy_err err, uint32_t handle)

Callback for nrf_modem_dect_phy_rx_stop.

When an RX operation is stopped, the operation complete callback will be called once the operation has fully stopped. That is, it is possible that the operation hasn’t been fully stopped at the time this callback is called.

The err parameter indicates the result of the operation. It can be one of the following values:

• NRF_MODEM_DECT_PHY_SUCCESS

• NRF_MODEM_DECT_PHY_ERR_UNSUPPORTED_OP

• NRF_MODEM_DECT_PHY_ERR_NO_ONGOING_OP

• NRF_MODEM_DECT_PHY_ERR_NOT_ALLOWED

Param time:

[in] Modem time, in modem time units.

Param err:

Operation result.

Param handle:

Operation handle.

void (*pcc)(const uint64_t *time, const struct nrf_modem_dect_phy_rx_pcc_status *status, const union nrf_modem_dect_phy_hdr *hdr)

Callback for control channel reception.

Param time:

[in] Modem time, in modem time units.

Param status:

Reception data.

Param hdr:

[in] Physical layer control header.

void (*pcc_crc_err)(const uint64_t *time, const struct nrf_modem_dect_phy_rx_pcc_crc_failure *crc_failure)

Callback for CRC failures on the physical control channel.

Param time:

[in] Modem time, in modem time units.

Param crc_failure:

[in] CRC failure information.

void (*pdc)(const uint64_t *time, const struct nrf_modem_dect_phy_rx_pdc_status *status, const void *data, uint32_t len)

Callback for data channel reception.

Param time:

[in] Modem time, in modem time units.

Param status:

Reception data.

Param data:

[in] Data received.

Param len:

Size of received data.

void (*pdc_crc_err)(const uint64_t *time, const struct nrf_modem_dect_phy_rx_pdc_crc_failure *crc_failure)

Callback for CRC failures on the physical data channel.

Param time:

[in] Modem time, in modem time units.

Param crc_failure:

[in] CRC failure information.

void (*link_config)(const uint64_t *time, enum nrf_modem_dect_phy_err err)

Callback for nrf_modem_dect_phy_link_config.

The err parameter indicates the result of the operation. It can be one of the following values:

• NRF_MODEM_DECT_PHY_SUCCESS

• NRF_MODEM_DECT_PHY_ERR_NO_MEMORY

• NRF_MODEM_DECT_PHY_ERR_NOT_ALLOWED

• NRF_MODEM_DECT_PHY_ERR_INVALID_PARAMETER

Param time:

[in] Modem time, in modem time units.

Param err:

Operation result.

void (*time_get)(const uint64_t *time, enum nrf_modem_dect_phy_err err)

Callback for nrf_modem_dect_phy_time_get.

The err parameter indicates the result of the operation. It can be one of the following values:

• NRF_MODEM_DECT_PHY_SUCCESS

Param time:

[in] Modem time, in modem time units.

Param err:

Operation result.

void (*capability_get)(const uint64_t *time, enum nrf_modem_dect_phy_err err, const struct nrf_modem_dect_phy_capability *capability)

Callback for nrf_modem_dect_phy_capability_get.

The err parameter indicates the result of the operation. It can be one of the following values:

• NRF_MODEM_DECT_PHY_SUCCESS

Param time:

[in] Modem time, in modem time units.

Param err:

Operation result.

Param capability:

[in] PHY capabilities.

void (*deinit)(const uint64_t *time, enum nrf_modem_dect_phy_err err)

Callback for nrf_modem_dect_phy_deinit.

The err parameter indicates the result of the operation. It can be one of the following values:

• NRF_MODEM_DECT_PHY_SUCCESS

• NRF_MODEM_DECT_PHY_ERR_NOT_ALLOWED

Param time:

[in] Modem time, in modem time units.

Param err:

Operation result.

struct nrf_modem_dect_phy_init_params

#include <nrf_modem_dect_phy.h>

Configuration for DECT PHY interface.

Public Members

uint32_t harq_rx_expiry_time_us

HARQ RX buffer expiry time, in microseconds.

A HARQ process soft buffer allocation is released when there have been no receptions to that buffer within the buffer’s expiry time.

Maximum supported value: 5000000.

uint8_t harq_rx_process_count

Number of HARQ processes.

The HARQ reception buffer is divided equally between processes. Supported values: 1, 2, 4, 8.

GNSS API

group nrf_modem_gnss

API for accessing the GNSS module on the modem.

Defines

NRF_MODEM_GNSS_MAX_SYSTEMS

The maximum number of positioning systems supported by the interface (GPS, QZSS, etc.).

NRF_MODEM_GNSS_MAX_SIGNALS

The maximum number of positioning signals supported by the interface (GPS L1 C/A, QZSS L1 C/A, etc.).

NRF_MODEM_GNSS_MAX_SATELLITES

Maximum number of satellites that can be tracked at the same time.

NRF_MODEM_GNSS_NUM_GPS_SATELLITES

The number of GPS satellites.

NRF_MODEM_GNSS_NMEA_MAX_LEN

Maximum length of an NMEA string including the null-terminator.

NRF_MODEM_GNSS_MAX_SV_EXPIRY_TIMES

The maximum number of satellites expiry times are given for.

NRF_MODEM_GNSS_AGNSS_GPS_MAX_SV_TOW

Maximum number of TOW elements in the TOW array.

See also

nrf_modem_gnss_agnss_gps_data_system_time_and_sv_tow.

Typedefs

typedef void (*nrf_modem_gnss_event_handler_type_t)(int event)

Event handler prototype.

Param event:

[in] Event ID, see Event type enumerator.

Functions

int32_t nrf_modem_gnss_event_handler_set(nrf_modem_gnss_event_handler_type_t handler)

Sets the GNSS event handler.

This function is used to set the function that handles events from GNSS.

Note

The event handler is executed in interrupt context so a lot of processing inside the handler may have performance implications and side effects. It’s recommended to use the handler only for signaling or re-scheduling processing to a separate thread. Data can be read at any time while GNSS is running, the events are only signaling that the data has been updated.

Parameters:

• handler – [in] Pointer to the event handler function or NULL.

Return values:

0 – on success.

int32_t nrf_modem_gnss_signal_mask_set(uint8_t signal_mask)

Sets the supported GNSS signals. Signals which have the corresponding bit set are enabled.

Default value: All signals supported by the modem firmware are enabled

Note

GPS L1 C/A can’t be disabled and remains enabled even if the corresponding bit is not set.

Parameters:

• signal_mask – [in] Signal bitmask, see GNSS signal bitmask values.

Return values:

• 0 – on success.

• -NRF_EPERM – The Modem library is not initialized.

• -NRF_EACCES – GNSS is not enabled in system or functional mode.

• -NRF_EINVAL – The GNSS stack returned an error or the operation cannot be executed while GNSS is running.

• -NRF_ENOMEM – There is not enough shared memory for this request.

• -NRF_ESHUTDOWN – The modem was shut down.

int32_t nrf_modem_gnss_elevation_threshold_set(uint8_t angle)

Set below which elevation angle GNSS should stop tracking a satellite.

Satellites with elevation angle less than the threshold are excluded from the estimation.

Default value: 5 deg

Parameters:

• angle – [in] Value between 0 and 90 (degrees above the horizon).

Return values:

• 0 – on success.

• -NRF_EPERM – The Modem library is not initialized.

• -NRF_EACCES – GNSS is not enabled in system or functional mode.

• -NRF_EINVAL – The GNSS stack returned an error or the operation cannot be executed while GNSS is running.

• -NRF_ENOMEM – There is not enough shared memory for this request.

• -NRF_ESHUTDOWN – The modem was shut down.

int32_t nrf_modem_gnss_use_case_set(uint8_t use_case)

Sets targeted start and runtime performance.

Default value: NRF_MODEM_GNSS_USE_CASE_MULTIPLE_HOT_START

Parameters:

• use_case – [in] Bit mask, see Use case bitmask values.

Return values:

• 0 – on success.

• -NRF_EPERM – The Modem library is not initialized.

• -NRF_EACCES – GNSS is not enabled in system or functional mode.

• -NRF_EINVAL – The GNSS stack returned an error or the operation cannot be executed while GNSS is running.

• -NRF_ENOMEM – There is not enough shared memory for this request.

• -NRF_ESHUTDOWN – The modem was shut down.

int32_t nrf_modem_gnss_fix_interval_set(uint16_t fix_interval)

Sets the GNSS fix interval in seconds.

Single fix navigation mode is engaged by setting the fix interval to 0.

Continuous navigation mode is engaged by setting fix interval to 1.

Periodic navigation mode is engaged by setting the fix interval to value 10…65535. The unit is seconds.

Default value: 1 (continuous navigation)

Note

In periodic navigation mode, when GNSS determines it needs to download ephemerides or almanacs from the broadcast, the fix interval and fix retry parameters are temporarily ignored. GNSS will perform scheduled downloads until it has downloaded the data it needs, after which normal operation is resumed.

Parameters:

• fix_interval – [in] 0 for single fix, 1 for continuous navigation or fix interval in seconds.

Return values:

• 0 – on success.

• -NRF_EPERM – The Modem library is not initialized.

• -NRF_EACCES – GNSS is not enabled in system or functional mode.

• -NRF_EINVAL – The GNSS stack returned an error or the operation cannot be executed while GNSS is running.

• -NRF_ENOMEM – There is not enough shared memory for this request.

• -NRF_ESHUTDOWN – The modem was shut down.

int32_t nrf_modem_gnss_fix_retry_set(uint16_t fix_retry)

Sets the GNSS fix retry period in seconds.

Fix retry parameter controls the maximum time the GNSS receiver is allowed to run while trying to produce a valid PVT estimate. If the fix retry time is non-zero, the GNSS receiver is turned off after the fix retry time is up regardless of whether a valid PVT estimate was produced or not. If fix retry parameter is set to zero, the GNSS receiver is allowed to run indefinitely until a valid PVT estimate is produced.

Default value: 60s

Note

For the first fix in periodic navigation mode the GNSS receiver is allowed to run for 60 seconds even if the retry interval is set shorter.

Note

Fix retry has no effect in continuous navigation mode.

Parameters:

• fix_retry – [in] Fix retry period in seconds.

Return values:

• 0 – on success.

• -NRF_EPERM – The Modem library is not initialized.

• -NRF_EACCES – GNSS is not enabled in system or functional mode.

• -NRF_EINVAL – The GNSS stack returned an error or the operation cannot be executed while GNSS is running.

• -NRF_ENOMEM – There is not enough shared memory for this request.

• -NRF_ESHUTDOWN – The modem was shut down.

int32_t nrf_modem_gnss_nmea_mask_set(uint16_t nmea_mask)

Sets which NMEA strings are enabled.

Default value: 0

Parameters:

• nmea_mask – [in] Bit mask, see NMEA string bitmask values.

Return values:

• 0 – on success.

• -NRF_EPERM – The Modem library is not initialized.

• -NRF_EACCES – GNSS is not enabled in system or functional mode.

• -NRF_EINVAL – The GNSS stack returned an error or the operation cannot be executed while GNSS is running.

• -NRF_ENOMEM – There is not enough shared memory for this request.

• -NRF_ESHUTDOWN – The modem was shut down.

int32_t nrf_modem_gnss_power_mode_set(uint8_t power_mode)

Sets the used power saving mode.

Valid only in continuous navigation mode.

Default value: NRF_MODEM_GNSS_PSM_DISABLED

Parameters:

• power_mode – [in] See Power save mode enumerator.

Return values:

• 0 – on success.

• -NRF_EPERM – The Modem library is not initialized.

• -NRF_EACCES – GNSS is not enabled in system or functional mode.

• -NRF_EINVAL – The GNSS stack returned an error or the operation cannot be executed while GNSS is running.

• -NRF_ENOMEM – There is not enough shared memory for this request.

• -NRF_ESHUTDOWN – The modem was shut down.

int32_t nrf_modem_gnss_timing_source_set(uint8_t timing_source)

Sets the used timing source during GNSS sleep.

Using TCXO instead of RTC during GNSS sleep periods might be beneficial when used with 1PPS. When GNSS is not running all the time (periodic navigation or duty cycling is used), 1PPS accuracy can be improved by using TCXO. It may also improve sensitivity for periodic navigation when the fix interval is short.

Default value: NRF_MODEM_GNSS_TIMING_SOURCE_RTC

Note

Use of TCXO significantly raises the idle current consumption.

Parameters:

• timing_source – [in] See Sleep timing source enumerator.

Return values:

• 0 – on success.

• -NRF_EPERM – The Modem library is not initialized.

• -NRF_EACCES – GNSS is not enabled in system or functional mode.

• -NRF_EINVAL – The GNSS stack returned an error or the operation cannot be executed while GNSS is running.

• -NRF_ENOMEM – There is not enough shared memory for this request.

• -NRF_ESHUTDOWN – The modem was shut down.

int32_t nrf_modem_gnss_qzss_nmea_mode_set(uint8_t nmea_mode)

Sets the used QZSS NMEA mode.

NMEA 4.10 standard does not support QZSS satellites, so in standard NMEA mode QZSS satellites are not reported in GPGSA and GPGSV sentences. In custom NMEA mode satellite IDs 193…202 are used for QZSS satellites.

Default value: NRF_MODEM_GNSS_QZSS_NMEA_MODE_STANDARD

Parameters:

• nmea_mode – [in] See QZSS NMEA mode enumerator.

Return values:

• 0 – on success.

• -NRF_EPERM – The Modem library is not initialized.

• -NRF_EACCES – GNSS is not enabled in system or functional mode.

• -NRF_EINVAL – The GNSS stack returned an error or the operation cannot be executed while GNSS is running.

• -NRF_ENOMEM – There is not enough shared memory for this request.

• -NRF_ESHUTDOWN – The modem was shut down.

int32_t nrf_modem_gnss_qzss_prn_mask_set(uint16_t prn_mask)

Sets which QZSS PRNs are enabled.

QZSS satellite acquisition and tracking can be configured per satellite using QZSS PRN mask. Bits 0…9 correspond to QZSS PRNs 193…202, respectively. When a bit is set, usage of the corresponding QZSS satellite is enabled. Bits 10…15 are reserved and their value is ignored.

Default value: All QZSS PRNs (193…202) are enabled.

Parameters:

• prn_mask – [in] QZSS PRN mask.

Return values:

• 0 – on success.

• -NRF_EPERM – The Modem library is not initialized.

• -NRF_EACCES – GNSS is not enabled in system or functional mode.

• -NRF_EINVAL – The GNSS stack returned an error or the operation cannot be executed while GNSS is running.

• -NRF_ENOMEM – There is not enough shared memory for this request.

• -NRF_ESHUTDOWN – The modem was shut down.

int32_t nrf_modem_gnss_start(void)

Starts GNSS.

Return values:

• 0 – on success.

• -NRF_EPERM – The Modem library is not initialized.

• -NRF_EACCES – GNSS is not enabled in system or functional mode.

• -NRF_EINVAL – The GNSS stack returned an error.

• -NRF_ENOMEM – There is not enough shared memory for this request.

• -NRF_ESHUTDOWN – The modem was shut down.

int32_t nrf_modem_gnss_stop(void)

Stops GNSS.

Return values:

• 0 – on success.

• -NRF_EPERM – The Modem library is not initialized.

• -NRF_EACCES – GNSS is not enabled in system or functional mode.

• -NRF_EINVAL – The GNSS stack returned an error.

• -NRF_ENOMEM – There is not enough shared memory for this request.

• -NRF_ESHUTDOWN – The modem was shut down.

int32_t nrf_modem_gnss_nv_data_delete(uint32_t delete_mask)

Deletes GNSS data from non-volatile memory.

This function is used to delete downloaded data objects stored in non-volatile memory. The GNSS module stores this between sessions to get a fix faster on the next startup. This can for instance be used to trigger cold or warm starts.

Note

This is considered a debug feature, and is not supposed to be used in production code.

Parameters:

• delete_mask – [in] Objects to be deleted as a bitmask, see Delete bitmask values.

Return values:

• 0 – on success.

• -NRF_EPERM – The Modem library is not initialized.

• -NRF_EACCES – GNSS is not enabled in system or functional mode.

• -NRF_EINVAL – The GNSS stack returned an error or the operation cannot be executed while GNSS is running.

• -NRF_ENOMEM – There is not enough shared memory for this request.

• -NRF_ESHUTDOWN – The modem was shut down.

int32_t nrf_modem_gnss_prio_mode_enable(void)

Enables GNSS priority over LTE idle mode procedures.

GNSS can produce a cold start fix when there are long enough gaps in LTE idle mode operations. LTE idle eDRX cycles approximately 1 min and above will usually guarantee the ability to produce a fix. Shorter DRX cycles will be enough after GNSS has got ephemerides. GNSS priority can be enabled to help getting GNSS into that state, if there are not long enough gaps in LTE idle mode functionality. Priority for GNSS should be used only when fix has been blocked by LTE idle mode operations, which can be detected by NRF_MODEM_GNSS_PVT_FLAG_NOT_ENOUGH_WINDOW_TIME bit being set in the PVT data frame flags member. The application should not make the decision based on a single PVT event, but should enable priority only in case this flag has been set in several consecutive PVT events. Priority will be disabled automatically after producing the first fix.

Note

GNSS priority may interfere with LTE operations, if possible it would be good to time the use of priority to moments where data transfer is not anticipated. In general, long enough eDRX cycles, or PSM, will ensure better functionality for both GNSS and LTE.

Note

Priority will not stop LTE connections.

Return values:

• 0 – on success.

• -NRF_EPERM – The Modem library is not initialized.

• -NRF_EACCES – GNSS is not enabled in system or functional mode.

• -NRF_EINVAL – The GNSS stack returned an error or the operation cannot be executed while GNSS is stopped.

• -NRF_ENOMEM – There is not enough shared memory for this request.

• -NRF_ESHUTDOWN – The modem was shut down.

int32_t nrf_modem_gnss_prio_mode_disable(void)

Disables GNSS priority over LTE idle mode procedures.

Return values:

• 0 – on success.

• -NRF_EPERM – The Modem library is not initialized.

• -NRF_EACCES – GNSS is not enabled in system or functional mode.

• -NRF_EINVAL – The GNSS stack returned an error or the operation cannot be executed while GNSS is stopped.

• -NRF_ENOMEM – There is not enough shared memory for this request.

• -NRF_ESHUTDOWN – The modem was shut down.

int32_t nrf_modem_gnss_dyn_mode_change(uint32_t mode)

Changes GNSS dynamics mode.

Dynamics mode can be used to tune GNSS performance for a specific use case. Use of a matching dynamics mode improves the positioning performance. Dynamics mode can be changed without disruption in positioning. The selected dynamics mode is stored into non-volatile memory.

Default value: NRF_MODEM_GNSS_DYNAMICS_GENERAL_PURPOSE

Parameters:

• mode – [in] Selected dynamics mode, see Dynamics mode enumerator.

Return values:

• 0 – on success.

• -NRF_EPERM – The Modem library is not initialized.

• -NRF_EACCES – GNSS is not enabled in system or functional mode.

• -NRF_EINVAL – The GNSS stack returned an error or the operation cannot be executed while GNSS is stopped.

• -NRF_ENOMEM – There is not enough shared memory for this request.

• -NRF_ESHUTDOWN – The modem was shut down.

int32_t nrf_modem_gnss_1pps_enable(const struct nrf_modem_gnss_1pps_config *config)

Enables 1PPS functionality.

nrf_modem_gnss_1pps_config contains the used 1PPS configuration. GNSS only starts giving pulses after it has got at least one fix. After this, the pulses will continue also when GNSS is no longer running, but the precision will start degrading.

Note

The 1PPS feature must not be used when LTE is enabled.

Parameters:

• config – [in] Pointer to the configuration struct.

Return values:

• 0 – on success.

• -NRF_EPERM – The Modem library is not initialized.

• -NRF_EACCES – GNSS is not enabled in system or functional mode.

• -NRF_EINVAL – The config pointer is NULL, GNSS returned an error or the operation cannot be executed while GNSS is running.

• -NRF_ENOMEM – There is not enough shared memory for this request.

• -NRF_ESHUTDOWN – The modem was shut down.

int32_t nrf_modem_gnss_1pps_disable(void)

Disables 1PPS functionality.

Return values:

• 0 – on success.

• -NRF_EPERM – The Modem library is not initialized.

• -NRF_EACCES – GNSS is not enabled in system or functional mode.

• -NRF_EINVAL – The GNSS stack returned an error or the operation cannot be executed while GNSS is running.

• -NRF_ENOMEM – There is not enough shared memory for this request.

• -NRF_ESHUTDOWN – The modem was shut down.

int32_t nrf_modem_gnss_read(void *buf, int32_t buf_len, int type)

Reads data from GNSS.

This function is used to read any data from GNSS. The data type is specified using the type argument to this function.

Parameters:

• buf – [out] Pointer to a buffer that can hold the selected data type.

• buf_len – [in] Length of the buffer.

• type – [in] The data type to read, see Data type enumerator.

Return values:

• 0 – on success.

• -NRF_EINVAL – The selected data type don’t exist or supplied buffer is NULL.

• -NRF_EMSGSIZE – The buffer supplied by the application is too small for the selected data type.

• -NRF_ENOMSG – There is no data to read for the selected data type.

int32_t nrf_modem_gnss_agnss_write(void *buf, int32_t buf_len, uint16_t type)

Writes A-GNSS data to GNSS.

This function is used to write A-GNSS data to GNSS to decrease the time to first fix.

Parameters:

• buf – [in] Pointer to a buffer that contains A-GNSS data.

• buf_len – [in] Length of the buffer.

• type – [in] A-GNSS data type identifier, see A-GNSS data type enumerator.

Return values:

• 0 – on success.

• -NRF_EPERM – The Modem library is not initialized.

• -NRF_EACCES – GNSS is not enabled in system or functional mode.

• -NRF_EINVAL – The buffer supplied by the application is NULL, buffer length is 0, the A-GNSS data type doesn’t exist or the A-GNSS data was not accepted by GNSS.

• -NRF_ENOMEM – There is not enough shared memory for this request.

• -NRF_ESHUTDOWN – The modem was shut down.

int32_t nrf_modem_gnss_agnss_expiry_get(struct nrf_modem_gnss_agnss_expiry *agnss_expiry)

Reads the current A-GNSS data need and expiry times from GNSS.

Returns detailed information about the current GNSS A-GNSS data need. The data structure contains expiry times in seconds for different types of assistance data. This function can be called at any time. If GNSS doesn’t know the current GPS system time, the expiry times can not be calculated

Note

When A-GNSS data has been injected but GNSS has not yet been started, ephemerides and almanacs are in some cases reported as expired. This happens when ephemerides and almanacs are injected before GPS system time. This can be prevented by either injecting GPS system time before ephemerides and almanacs or briefly starting and stopping GNSS before calling the function.

Parameters:

• agnss_expiry – [out] Pointer to a buffer where the data is stored to.

Return values:

• -NRF_EPERM – The Modem library is not initialized.

• -NRF_EACCES – GNSS is not enabled in system or functional mode.

• -NRF_EINVAL – The buffer supplied by the application is NULL or The GNSS stack returned an error.

• -NRF_ENOMEM – There is not enough shared memory for this request.

• -NRF_EOPNOTSUPP – The operation is not supported by the modem firmware.

• -NRF_ESHUTDOWN – The modem was shut down.

Returns:

0 on success.

struct nrf_modem_gnss_1pps_config

#include <nrf_modem_gnss.h>

Configuration for the nrf_modem_gnss_1pps_enable function.

Public Members

uint16_t pulse_interval

Pulse interval in seconds. Range 0…1800s. Value 0 denotes one-time pulse mode.

uint16_t pulse_width

Pulse width in milliseconds. Range 1…500ms.

bool apply_start_time

If true, pulses are started at given start time. If false, the date and time fields are ignored.

uint16_t year

Gregorian year. Range 0…4000.

uint8_t month

Month of the year. Range 1…12.

uint8_t day

Day of the month. Range 1…31.

uint8_t hour

Hour of the day. Range 0…23.

uint8_t minute

Minute of the hour. Range 0…59.

uint8_t second

Second of the minute. Range 0…59.

struct nrf_modem_gnss_datetime

#include <nrf_modem_gnss.h>

Date and time.

Public Members

uint16_t year

4-digit representation (Gregorian calendar).

uint8_t month

1…12

uint8_t day

1…31

uint8_t hour

0…23

uint8_t minute

0…59

uint8_t seconds

0…59

uint16_t ms

0…999

struct nrf_modem_gnss_sv

#include <nrf_modem_gnss.h>

Space Vehicle (SV) information.

Public Members

uint16_t sv

Satellite ID. 1…32 for GPS 193…202 for QZSS.

uint8_t signal

Signal type, see GNSS signal IDs.

uint16_t cn0

0.1 dB/Hz.

int16_t elevation

Satellite elevation angle in degrees.

int16_t azimuth

Satellite azimuth angle in degrees.

uint8_t flags

See Satellite flags bitmask values.

struct nrf_modem_gnss_pvt_data_frame

#include <nrf_modem_gnss.h>

Position, Velocity and Time (PVT) data frame.

Public Members

double latitude

Latitude in degrees.

double longitude

Longitude in degrees.

float altitude

Altitude above WGS-84 ellipsoid in meters.

float accuracy

Position accuracy (2D 1-sigma) in meters.

float altitude_accuracy

Altitude accuracy (1-sigma) in meters.

float speed

Horizontal speed in m/s.

float speed_accuracy

Speed accuracy (1-sigma) in m/s.

float vertical_speed

Vertical speed in m/s. Positive is up.

float vertical_speed_accuracy

Vertical speed accuracy (1-sigma) in m/s.

float heading

Heading of user movement in degrees.

float heading_accuracy

Heading accuracy (1-sigma) in degrees.

struct nrf_modem_gnss_datetime datetime

Date and time.

float pdop

Position dilution of precision.

float hdop

Horizontal dilution of precision.

float vdop

Vertical dilution of precision.

float tdop

Time dilution of precision.

uint8_t flags

See Bitmask values for flags in the PVT notification.

struct nrf_modem_gnss_sv sv[12]

Describes up to 12 of the satellites used for the measurement.

uint32_t execution_time

Cumulative GNSS execution time since last start in milliseconds.

struct nrf_modem_gnss_nmea_data_frame

#include <nrf_modem_gnss.h>

Single null-terminated NMEA sentence.

Public Members

char nmea_str[83]

Null-terminated NMEA sentence.

struct nrf_modem_gnss_agnss_system_data_need

#include <nrf_modem_gnss.h>

Ephemeris and almanac data need for a system.

Public Members

uint8_t system_id

System ID, see GNSS system IDs.

uint64_t sv_mask_ephe

Bit mask indicating the satellites for which the assistance ephemeris data is needed.

uint64_t sv_mask_alm

Bit mask indicating the satellites for which the assistance almanac data is needed.

struct nrf_modem_gnss_agnss_data_frame

#include <nrf_modem_gnss.h>

A-GNSS notification data frame used by GNSS to let the application know it needs new assistance data.

Public Members

uint32_t data_flags

Indicating what kind of A-GNSS data is needed by GNSS.

See A-GNSS data request bitmask values.

uint8_t system_count

Number of systems assistance data need is indicated for.

struct nrf_modem_gnss_agnss_system_data_need system[4]

Ephemeris and almanac data need for each system.

struct nrf_modem_gnss_agnss_sv_expiry

#include <nrf_modem_gnss.h>

Ephemeris and almanac expiry times for a satellite.

Public Members

uint8_t sv_id

Satellite ID.

uint8_t system_id

System ID, see GNSS system IDs.

uint16_t ephe_expiry

Ephemeris expiry time in minutes.

uint16_t alm_expiry

Almanac expiry time in minutes.

struct nrf_modem_gnss_agnss_expiry

#include <nrf_modem_gnss.h>

A-GNSS data expiry.

Expiry times are given in minutes. 0 indicates that data is needed immediately. 0xffff indicates that data is not used by GNSS.

Public Members

uint32_t data_flags

Flags indicating the A-GNSS data types needed by GNSS.

See A-GNSS data request bitmask values. If bit NRF_MODEM_GNSS_AGNSS_GPS_SYS_TIME_AND_SV_TOW_REQUEST is set, GNSS doesn’t have the GPS system time and all expiry time fields for ephemerides and almanacs are set to zero.

uint16_t utc_expiry

UTC parameters expiry time.

uint16_t klob_expiry

Klobuchar ionospheric correction parameters expiry time.

uint16_t neq_expiry

NeQuick ionospheric correction parameters expiry time.

uint16_t integrity_expiry

Integrity assistance parameters expiry time.

uint16_t position_expiry

Position assistance expiry time.

uint8_t sv_count

Number of satellites for which expiry times are given.

struct nrf_modem_gnss_agnss_sv_expiry sv[127]

Ephemeris and almanac expiry times for satellites.

struct nrf_modem_gnss_agnss_gps_data_utc

#include <nrf_modem_gnss.h>

A-GNSS GPS UTC parameters.

Public Members

int32_t a1

First order term of polynomial (sec/sec). Scale factor 2^-50. Range -8388608…8388607 (25 bits).

int32_t a0

Constant term of polynomial (sec). Scale factor 2^-30.

uint8_t tot

UTC reference GPS time-of-week (sec). Scale factor 2^12. Range 0..147.

uint8_t wn_t

UTC reference GPS week number modulo 256.

int8_t delta_tls

Current or past leap second count (sec).

uint8_t wn_lsf

Leap second reference GPS week number modulo 256.

int8_t dn

Leap second reference GPS day-of-week (day). Range 1…7.

int8_t delta_tlsf

Current or future leap second count (sec) (total size of the type-specific assistance data).

struct nrf_modem_gnss_agnss_gps_data_ephemeris

#include <nrf_modem_gnss.h>

A-GNSS GPS/QZSS ephemeris data.

Public Members

uint8_t sv_id

Satellite ID (dimensionless). 1…32: GPS 193…202: QZSS

uint8_t health

Satellite health (dimensionless).

uint16_t iodc

Issue of data, clock parameters (dimensionless). Range 0…2047 (11 bits).

uint16_t toc

Clock parameters reference GPS time-of-week (sec). Scale factor 2^4. Range 0…37799.

int8_t af2

Clock drift rate (sec/sec2). Scale factor 2^-55.

int16_t af1

Clock drift (sec/sec). Scale factor 2^-43.

int32_t af0

Clock bias (sec). Scale factor 2^-31. Range -2097152…2097151 (22 bit)

int8_t tgd

Group delay (sec). Scale factor 2^-31.

uint8_t ura

URA index (dimensionless). Range 0…15.

uint8_t fit_int

Curve fit interval indication. Range 0…1.

uint16_t toe

Ephemeris parameters reference GPS time-of-week (sec). Scale factor 2^4. Range 0…37799.

int32_t w

Argument of perigee (semi-circle). Scale factor 2^-31.

int16_t delta_n

Mean motion difference (semi-circle/sec). Scale factor 2^-43.

int32_t m0

Mean anomaly at reference time (semi-circle). Scale factor 2^-31.

int32_t omega_dot

Rate of right ascension (semi-circle/sec). Scale factor 2^-43. Range -8388608…8388607 (24 bits).

uint32_t e

Eccentricity (dimensionless). Scale factor 2^-33.

int16_t idot

Rate of inclination angle (semi-circle/sec). Scale factor 2-43. Range -8192…8191 (14 bits).

uint32_t sqrt_a

Square root of semi-major axis (m). Scale factor 2^-19.

int32_t i0

Inclination angle at reference time (semi-circle). Scale factor 2^-31.

int32_t omega0

Longitude of ascending node at weekly epoch (semi-circle). Scale factor 2^-31.

int16_t crs

Orbit radius, sine harmonic amplitude (m). Scale factor 2^-5.

int16_t cis

Inclination angle, sine harmonic amplitude (rad). Scale factor 2^-29.

int16_t cus

Argument of latitude, sine harmonic amplitude (rad). Scale factor 2^-29.

int16_t crc

Orbit radius, cosine harmonic amplitude (m). Scale factor 2^-5.

int16_t cic

Inclination angle, cosine harmonic amplitude (rad). Scale factor 2^-29.

int16_t cuc

Argument of latitude, cosine harmonic amplitude (rad). Scale factor 2^-29.

struct nrf_modem_gnss_agnss_gps_data_almanac

#include <nrf_modem_gnss.h>

A-GNSS GPS/QZSS almanac data.

Public Members

uint8_t sv_id

Satellite ID (dimensionless). 1…32: GPS 193…202: QZSS

uint8_t wn

Almanac reference GPS week number modulo 256.

uint8_t toa

Almanac reference GPS time-of-week (sec). Scale factor 2^12. Range 0…147.

uint8_t ioda

Issue of data, almanac (dimensionless). Range 0…3 (2 bits).

uint16_t e

Eccentricity (dimensionless). Scale factor 2^-21.

int16_t delta_i

Correction to inclination (semi-circle). Scale factor 2^-19.

int16_t omega_dot

Rate of right ascension (semi-circle/sec). Scale factor 2^-38.

uint8_t sv_health

Satellite health (dimensionless)

uint32_t sqrt_a

Square root of semi-major axis (m^(1/2)). Scale factor 2^-11. Range 0…16777215 (24 bit).

int32_t omega0

Longitude of ascending node at weekly epoch (semi-circle). Scale factor 2^-23. Range -8388608…8388607 (24 bits).

int32_t w

Argument of perigee (semi-circle). Scale factor 2^-23.

int32_t m0

Mean anomaly at reference time (semi-circle). Scale factor 2^-23. Range -8388608…8388608 (24 bits).

int16_t af0

Clock bias (sec). Scale factor 2^-20. Range -1024…1023 (11 bits).

int16_t af1

Clock drift (sec/sec). Scale factor 2^-38. Range -1024…1023 (11 bits).

struct nrf_modem_gnss_agnss_data_klobuchar

#include <nrf_modem_gnss.h>

A-GNSS Klobuchar ionospheric correction data.

Public Members

int8_t alpha0

Constant term (sec). Scale factor 2^-30.

int8_t alpha1

First-order coefficient (sec/semi-circle). Scale factor 2^-27.

int8_t alpha2

Second-order coefficient (sec/semi-circle^2). Scale factor 2^-24.

int8_t alpha3

Third-order coefficient (sec/semi-circle^3). Scale factor 2^-24.

int8_t beta0

Constant term (sec). Scale factor 2^11.

int8_t beta1

First-order coefficient (sec/semi-circle). Scale factor 2^14.

int8_t beta2

Second-order coefficient (sec/semi-circle^2). Scale factor 2^16.

int8_t beta3

Third-order coefficient (sec/semi-circle^3). Scale factor 2^16.

struct nrf_modem_gnss_agnss_data_nequick

#include <nrf_modem_gnss.h>

A-GNSS NeQuick ionospheric correction data.

Public Members

int16_t ai0

Effective ionisation level 1st order parameter (SFU). Scale factor 2^-2. Range 0…2047 (11 bits).

int16_t ai1

Effective ionisation level 2nd order parameter (SFU/deg). Scale factor 2^-8. Range -1024…1023 (11 bits).

int16_t ai2

Effective ionisation level 3rd order parameter (SFU/deg^2). Scale factor 2^-15. Range -8192…8191 (14 bits).

uint8_t storm_cond

Storm condition bit mask indicating the ionospheric storm condition for different regions.

uint8_t storm_valid

Storm validity bit mask indicating for which regions the ionospheric storm condition bit is valid.

struct nrf_modem_gnss_agnss_gps_data_tow_element

#include <nrf_modem_gnss.h>

A-GNSS GPS TOW assistance data for a satellite.

Public Members

uint16_t tlm

First two bits (MSB) represent the reserved bit and integrity status flag in the telemetry message (TLM) word. The following 14 bits represent the TLM being broadcast by the satellite.

uint8_t flags

Bit 0 (LSB): anti-spoof flag. Bit 1: alert flag.

struct nrf_modem_gnss_agnss_gps_data_system_time_and_sv_tow

#include <nrf_modem_gnss.h>

A-GNSS GPS system time and satellite TOW data.

Public Members

uint16_t date_day

Day number since Jan 6th, 1980 00:00:00 UTC (USNO).

uint32_t time_full_s

Full seconds part of time-of-day (s). Range 0…86399.

uint16_t time_frac_ms

Fraction of a second part of time-of-day (ms). Range 0…999.

uint32_t sv_mask

Bit mask indicating the satellite PRNs for which the satellite-specific TOW assistance data is valid.

struct nrf_modem_gnss_agnss_gps_data_tow_element sv_tow[32]

TOW assistance data for satellites.

struct nrf_modem_gnss_agnss_data_location

#include <nrf_modem_gnss.h>

A-GNSS location data.

Public Members

int32_t latitude

Geodetic latitude in WGS-84. Range -8388607…8388607. The relation between the coded number N and the latitude range X (in degrees) is as follows: N <= (2^23/90) * X < N + 1. For N = 2^23 - 1, the range is extended to include N+1. Range of X (in degrees) -90…90.

int32_t longitude

Geodetic longitude in WGS-84. Range -8388607..8388607. The relation between the coded number N and the longitude range X (in degrees) is as follows: N <= (2^24/360) * X < N + 1. Range of X (in degrees) -180…180.

int16_t altitude

Altitude. Above (positive value) or below (negative value) WGS-84 ellipsoid surface. Range -32767…32767. The relation between the coded number N and the altitude range a (in meters) is as follows: N <= a < N + 1. For N = 2^15 - 1 the range is extended to include all greater values of a.

uint8_t unc_semimajor

Uncertainty, semi-major. Range 0…127 or 255 for missing latitude and longitude. The uncertainty (in meters) is mapped from the coded number K with following formula: r = C * ((1 + x)^K - 1), where C = 10 and x = 0,1. Range of r (in kilometers) 0…1800.

uint8_t unc_semiminor

Uncertainty, semi-minor. Range 0…127 or 255 for missing latitude and longitude. The uncertainty (in meters) is mapped from the coded number K with following formula: r = C * ((1 + x)^K - 1), where C = 10 and x = 0,1. Range of r (in kilometers) 0…1800.

uint8_t orientation_major

Orientation angle between the major axis and north. Range in degrees 0…179.

uint8_t unc_altitude

Uncertainty, altitude. Range 0…127 or 255 for missing altitude. The uncertainty in altitude h (in meters) is mapped from the coded number K with following formula: h = C * ((1 + x)^K - 1), where C = 45 and x = 0,025. Range of h (in meters) 0…990,5.

uint8_t confidence

The confidence level (expressed as a percentage) with which the position of a target entity is included within the uncertainty ellipsoid. Range 0…128. ‘0’ indicates ‘no information’. Values 101..128 should be treated as ‘0’.

struct nrf_modem_gnss_agps_data_integrity

#include <nrf_modem_gnss.h>

A-GPS satellite integrity data.

Public Members

uint32_t integrity_mask

Bit mask indicating the unhealthy GPS satellite PRNs. When a mask bit is set, the corresponding GPS satellite PRN is unhealthy.

struct nrf_modem_gnss_agnss_data_signal_integrity

#include <nrf_modem_gnss.h>

A-GNSS satellite integrity mask for a signal.

Public Members

uint8_t signal_id

Signal ID, see GNSS signal IDs.

uint64_t integrity_mask

Bit mask indicating the unhealthy satellite numbers for the signal. When a mask bit is set, the corresponding satellite is unhealthy. GPS: 32 LSBs correspond to PRN 1 .. 32 QZSS: 10 LSBs correspond to PRN 193 .. 202

struct nrf_modem_gnss_agnss_data_integrity

#include <nrf_modem_gnss.h>

A-GNSS satellite integrity data.

Public Members

uint8_t signal_count

Number of signals integrity is indicated for.

struct nrf_modem_gnss_agnss_data_signal_integrity signal[4]

Satellite integrity mask for each signal.

Event types

group nrf_modem_gnss_event_type

Event types that trigger the handler function.

The event parameter in the handler function will hold one of these values. Some of the events have associated payload which can be read using nrf_modem_gnss_read.

Defines

NRF_MODEM_GNSS_EVT_PVT

PVT event.

Payload is of type nrf_modem_gnss_pvt_data_frame.

NRF_MODEM_GNSS_EVT_FIX

GNSS fix event.

Payload is of type nrf_modem_gnss_pvt_data_frame.

Note

In periodic navigation mode with modem firmware v2.0.0 or later, this event is not sent when GNSS is running because of a scheduled download.

NRF_MODEM_GNSS_EVT_NMEA

NMEA event.

Payload is of type nrf_modem_gnss_nmea_data_frame.

NRF_MODEM_GNSS_EVT_AGNSS_REQ

Need new A-GNSS data event.

Payload is of type nrf_modem_gnss_agnss_data_frame.

NRF_MODEM_GNSS_EVT_BLOCKED

GNSS is blocked by LTE event.

This event doesn’t have any payload.

NRF_MODEM_GNSS_EVT_UNBLOCKED

GNSS is unblocked by LTE event.

This event doesn’t have any payload.

NRF_MODEM_GNSS_EVT_PERIODIC_WAKEUP

GNSS woke up in periodic mode.

This event is sent when GNSS receiver is turned on in periodic mode. This happens when GNSS starts acquiring the next periodic fix but also when a scheduled download starts.

This event doesn’t have any payload.

NRF_MODEM_GNSS_EVT_SLEEP_AFTER_TIMEOUT

GNSS enters sleep because fix retry timeout was reached in periodic or single fix mode.

This event doesn’t have any payload.

NRF_MODEM_GNSS_EVT_SLEEP_AFTER_FIX

GNSS enters sleep because fix was achieved in periodic mode.

This event doesn’t have any payload.

NRF_MODEM_GNSS_EVT_REF_ALT_EXPIRED

Reference altitude for 3-satellite fix expired.

This event doesn’t have any payload.

Data types

group nrf_modem_gnss_data_type

Use these values to indicate the type of data read using nrf_modem_gnss_read.

Defines

NRF_MODEM_GNSS_DATA_PVT

PVT (Position-Velocity-Time) data.

Use this data type to read PVT data using the nrf_modem_gnss_read function. New PVT data will be available when an NRF_MODEM_GNSS_EVT_PVT or NRF_MODEM_GNSS_EVT_FIX event is received.

NRF_MODEM_GNSS_DATA_NMEA

NMEA data.

Use this data type to read NMEA data using the nrf_modem_gnss_read function. New NMEA data will be available when an NRF_MODEM_GNSS_EVT_NMEA event is received.

Note

There’s no buffering for NMEA data. Because of this NMEA data needs to be read inside the event handler function, otherwise some of the data may be overwritten before it’s read.

NRF_MODEM_GNSS_DATA_AGNSS_REQ

A-GNSS request data.

Use this data type to read A-GNSS request data using the nrf_modem_gnss_read function. New A-GNSS request data is received when an NRF_MODEM_GNSS_EVT_AGNSS_REQ event is received.

PVT notification flags bitmask values

group nrf_modem_gnss_pvt_flag_bitmask

Bitmask values for the flags member in the nrf_modem_gnss_pvt_data_frame.

Defines

NRF_MODEM_GNSS_PVT_FLAG_FIX_VALID

A valid fix has been acquired.

NRF_MODEM_GNSS_PVT_FLAG_LEAP_SECOND_VALID

The leap second information is valid.

This bit in the notification flags tells if receiver has decoded leap second from the navigation message. The leap second is needed for determining GPS-UTC time offset (in seconds). If it is not decoded (bit is zero), the value of 18 seconds is used. This is the effective value since January 1st 2017.

NRF_MODEM_GNSS_PVT_FLAG_SLEEP_BETWEEN_PVT

At least one sleep period has passed since the last PVT notification.

Indicates sleep periods during duty-cycled tracking.

NRF_MODEM_GNSS_PVT_FLAG_DEADLINE_MISSED

Notification deadline was missed.

Indicates that GNSS has not received a time window since the last PVT notification due to LTE activity, blocking GNSS operation.

NRF_MODEM_GNSS_PVT_FLAG_NOT_ENOUGH_WINDOW_TIME

Average time windows granted to GNSS may be too short.

Indicates that the inability to produce a valid PVT estimate is likely caused by too short GNSS time windows. Usually this happens when eDRX and/or PSM are not used, because LTE needs to monitor pagings from the network with a short interval.

NRF_MODEM_GNSS_PVT_FLAG_VELOCITY_VALID

The velocity estimate is valid.

NRF_MODEM_GNSS_PVT_FLAG_SCHED_DOWNLOAD

The PVT notification was sent because of a scheduled download.

Indicates that GNSS is running because of a scheduled download. This flag is only used in the periodic navigation mode.

Note

This flag is only supported by modem firmware v2.0.0 or later.

Satellite flags bitmask values

group nrf_modem_gnss_sv_flag_bitmask

Bitmask values for the flags member in the SV elements in the PVT notification struct.

Defines

NRF_MODEM_GNSS_SV_FLAG_USED_IN_FIX

The satellite is used in the position calculation.

NRF_MODEM_GNSS_SV_FLAG_UNHEALTHY

The satellite is unhealthy.

A-GNSS data request bitmask values

group nrf_modem_gnss_agnss_data_bitmask

Bitmask values for the data_flags member in the nrf_modem_gnss_agnss_data_frame.

Defines

NRF_MODEM_GNSS_AGNSS_GPS_UTC_REQUEST

GPS UTC parameters assistance data.

NRF_MODEM_GNSS_AGNSS_KLOBUCHAR_REQUEST

Klobuchar ionospheric correction parameters assistance data.

NRF_MODEM_GNSS_AGNSS_NEQUICK_REQUEST

NeQuick ionospheric correction parameters assistance data.

NRF_MODEM_GNSS_AGNSS_GPS_SYS_TIME_AND_SV_TOW_REQUEST

GPS system time and SV TOWs assistance data.

NRF_MODEM_GNSS_AGNSS_POSITION_REQUEST

Position assistance parameters assistance data.

NRF_MODEM_GNSS_AGNSS_INTEGRITY_REQUEST

Integrity assistance parameters assistance data.

A-GNSS data type enumerator

group nrf_modem_gnss_agnss_data_type

Use these values to indicate the type of A-GNSS data written using nrf_modem_gnss_agnss_write.

Defines

NRF_MODEM_GNSS_AGNSS_GPS_UTC_PARAMETERS

GPS UTC assistance A-GNSS parameters.

Data model nrf_modem_gnss_agnss_gps_data_utc.

NRF_MODEM_GNSS_AGNSS_GPS_EPHEMERIDES

GPS/QZSS ephemeris assistance A-GNSS parameters.

Data model nrf_modem_gnss_agnss_gps_data_ephemeris.

NRF_MODEM_GNSS_AGNSS_GPS_ALMANAC

GPS/QZSS almanac assistance A-GNSS parameters.

Data model nrf_modem_gnss_agnss_gps_data_almanac.

NRF_MODEM_GNSS_AGNSS_KLOBUCHAR_IONOSPHERIC_CORRECTION

Ionospheric assistance A-GNSS parameters, Klobuchar model.

Data model nrf_modem_gnss_agnss_data_klobuchar.

NRF_MODEM_GNSS_AGNSS_NEQUICK_IONOSPHERIC_CORRECTION

Ionospheric assistance A-GNSS parameters, NeQuick model.

Data model nrf_modem_gnss_agnss_data_nequick.

NRF_MODEM_GNSS_AGNSS_GPS_SYSTEM_CLOCK_AND_TOWS

GPS system time and satellite TOW assistance A-GNSS parameters.

Data model nrf_modem_gnss_agnss_gps_data_system_time_and_sv_tow.

NRF_MODEM_GNSS_AGNSS_LOCATION

Location assistance A-GNSS parameters.

Data model nrf_modem_gnss_agnss_data_location.

NRF_MODEM_GNSS_AGPS_INTEGRITY

Integrity assistance A-GPS parameters.

Data model nrf_modem_gnss_agps_data_integrity.

NRF_MODEM_GNSS_AGNSS_INTEGRITY

Integrity assistance A-GNSS parameters.

Data model nrf_modem_gnss_agnss_data_integrity.

Note

This type is only supported by modem firmware v2.0.0 or later.

Delete bitmask values

group nrf_modem_gnss_delete_bitmask

Bitmask values to be used as an argument for function nrf_modem_gnss_nv_data_delete.

Defines

NRF_MODEM_GNSS_DELETE_EPHEMERIDES

Ephemerides.

NRF_MODEM_GNSS_DELETE_ALMANACS

Almanacs (excluding leap second and ionospheric correction).

NRF_MODEM_GNSS_DELETE_IONO_CORRECTION_DATA

Ionospheric correction parameters.

NRF_MODEM_GNSS_DELETE_LAST_GOOD_FIX

Last good fix (the last position).

NRF_MODEM_GNSS_DELETE_GPS_TOW

GPS time-of-week (TOW).

NRF_MODEM_GNSS_DELETE_GPS_WEEK

GPS week number.

NRF_MODEM_GNSS_DELETE_UTC_DATA

Leap second (UTC parameters).

NRF_MODEM_GNSS_DELETE_TCXO_OFFSET

Local clock (TCXO) frequency offset.

NRF_MODEM_GNSS_DELETE_GPS_TOW_PRECISION

Precision estimate of GPS time-of-week (TOW).

NRF_MODEM_GNSS_DELETE_EKF

Extended Kalman Filter (EKF) state (last position/velocity/time solution).

Note

This value is only supported by modem firmware v2.0.1 or later.

GNSS signal bitmask values

group nrf_modem_gnss_signal_bitmask

Use these bitmask values to enable different GNSS signals.

The values can be OR’ed together to enable multiple GNSS signals at the same time. If a signal bit is 0, the corresponding signal is disabled.

Defines

NRF_MODEM_GNSS_SYSTEM_GPS_L1_CA_MASK

Global Positioning System (GPS) L1 C/A.

Note

GPS L1 C/A can’t be disabled and remains enabled even if the corresponding bit is not set.

NRF_MODEM_GNSS_SYSTEM_QZSS_L1_CA_MASK

Quasi-Zenith Satellite System (QZSS) L1 C/A.

NMEA string bitmask values

group nrf_modem_gnss_nmea_string_bitmask

Use these bitmask values to enable different type of NMEA output strings.

The values can be OR’ed together to enable multiple string types at the same time. Writing 0 to the bit position will disable the corresponding NMEA string type.

Defines

NRF_MODEM_GNSS_NMEA_GGA_MASK

Enables Global Positioning System Fix Data.

NRF_MODEM_GNSS_NMEA_GLL_MASK

Enables Geographic Position Latitude/Longitude and time.

NRF_MODEM_GNSS_NMEA_GSA_MASK

Enables DOP and active satellites.

NRF_MODEM_GNSS_NMEA_GSV_MASK

Enables Satellites in view.

NRF_MODEM_GNSS_NMEA_RMC_MASK

Enables Recommended minimum specific GPS/Transit data.

Power save modes

group nrf_modem_gnss_power_save_modes

Use these values to select which power save mode GNSS should use. This only affects continuous navigation mode. When GNSS engages duty-cycled tracking, it only tracks for 20% of time and spends the rest of the time in sleep. The different modes control how aggressively GNSS engages duty-cycled tracking, but the duty-cycling itself is the same with both modes.

Defines

NRF_MODEM_GNSS_PSM_DISABLED

No power save mode is enabled.

NRF_MODEM_GNSS_PSM_DUTY_CYCLING_PERFORMANCE

Enables duty-cycling performance policy power save mode.

NRF_MODEM_GNSS_PSM_DUTY_CYCLING_POWER

Enables duty-cycling power policy power save mode.

Use case bitmask values

group nrf_modem_gnss_use_case_bitmask

Use these bit values to select which use case mode GNSS should use. A use case mode is a combination of the values of all of the bits.

Defines

NRF_MODEM_GNSS_USE_CASE_MULTIPLE_HOT_START

Multiple hot starts performance mode.

Note

This is the only start mode currently supported, but the bit should always be set when setting the use-case modes to keep the code compliant with future versions of the modem firmware.

NRF_MODEM_GNSS_USE_CASE_LOW_ACCURACY

Low accuracy fixes allowed.

The error in position calculation can be larger than in normal accuracy mode. In addition, GNSS might only use three satellites to determine a fix, while in normal accuracy mode at least four satellites are used.

NRF_MODEM_GNSS_USE_CASE_SCHED_DOWNLOAD_DISABLE

Disable scheduled downloads.

By default, in periodic navigation mode, when GNSS determines it needs to download ephemerides or almanacs from the broadcast, the fix interval and fix retry parameters are temporarily ignored. GNSS will perform scheduled downloads until it has downloaded the data it needs, after which normal operation is resumed.

When this bit is set, scheduled downloads are disabled. This is recommended when A-GNSS is used to supply assistance data to the GNSS. It is also possible to use this option without A-GNSS, but it should be noted that in that case GNSS will never get some data (for example ionospheric corrections), which may affect the accuracy.

This option is only valid in periodic navigation mode, because scheduled downloads are not performed in other navigation modes.

Sleep timing sources

group nrf_modem_gnss_timing_source

Used to select which sleep timing source GNSS uses.

Using TCXO instead of RTC during GNSS sleep periods might be beneficial when used with 1PPS. When GNSS is not running all the time (periodic navigation or duty-cycling is used), 1PPS accuracy can be improved by using TCXO. It may also improve sensitivity for periodic navigation when the fix interval is short.

Note

Use of TCXO significantly raises the idle current consumption.

Defines

NRF_MODEM_GNSS_TIMING_SOURCE_RTC

Real time clock (RTC).

NRF_MODEM_GNSS_TIMING_SOURCE_TCXO

Temperature compensated crystal oscillator (TCXO).

QZSS NMEA modes

group nrf_modem_gnss_qzss_nmea_mode

Use these values to select if QZSS satellites are reported in NMEA sentences or not.

Defines

NRF_MODEM_GNSS_QZSS_NMEA_MODE_STANDARD

Standard NMEA reporting.

QZSS satellites not reported in GPGSA and GPGSV sentences.

NRF_MODEM_GNSS_QZSS_NMEA_MODE_CUSTOM

Custom NMEA reporting with QZSS satellites.

QZSS satellites reported in GPGSA and GPGSV sentences using satellite IDs 193…202.

Dynamics modes

group nrf_modem_gnss_dynamics_mode

Dynamics mode values to be used as an argument for function nrf_modem_gnss_dyn_mode_change.

The maximum speeds listed below are for modem firmware v2.0.0 or later. For older modem firmware versions, the assumed maximum speed for all modes is 100 km/h.

The maximum speed is not a hard limit, but if the receiver speed is higher than the assumed maximum speed for the selected mode, GNSS will operate with suboptimal predictions.

Defines

NRF_MODEM_GNSS_DYNAMICS_GENERAL_PURPOSE

General purpose mode. Assumed maximum speed 100 km/h.

NRF_MODEM_GNSS_DYNAMICS_STATIONARY

Optimize for stationary use case. Assumed maximum speed 5 km/h.

NRF_MODEM_GNSS_DYNAMICS_PEDESTRIAN

Optimize for pedestrian use case. Assumed maximum speed 30 km/h.

NRF_MODEM_GNSS_DYNAMICS_AUTOMOTIVE

Optimize for automotive use case. Assumed maximum speed > 100 km/h.

SoftSIM API

group nrf_modem_softsim

API to mediate SoftSIM exchanges between Modem and application.

Typedefs

typedef void (*nrf_modem_softsim_req_handler_t)(enum nrf_modem_softsim_cmd cmd, uint16_t req_id, void *data, uint16_t data_len)

Handle a SoftSIM request.

This handler lets the application process a SoftSIM request. The application must then call nrf_modem_softsim_res with the response data requested.

Note

This handler is executed in an interrupt service routine. Offload any intensive operations as necessary.

Param cmd:

SoftSIM request command.

Param req_id:

Request ID used to match request and response.

Param data:

[in] Pointer to the data of the SoftSIM request.

Param data_len:

Length of the data of the SoftSIM request.

Enums

enum nrf_modem_softsim_cmd

SoftSIM request command type.

Values:

enumerator NRF_MODEM_SOFTSIM_INIT

Initialization command.

enumerator NRF_MODEM_SOFTSIM_APDU

Transport command, issued by the Modem to request data from the application.

enumerator NRF_MODEM_SOFTSIM_DEINIT

Deinitialization command.

enumerator NRF_MODEM_SOFTSIM_RESET

Reset command, issued by the Modem when a request becomes unresponsive.

Functions

int nrf_modem_softsim_req_handler_set(nrf_modem_softsim_req_handler_t handler)

Set a handler function for SoftSIM requests.

Note

The handler is executed in an interrupt service routine. Take care to offload any processing as appropriate.

Parameters:

• handler – The SoftSIM request handler. Use NULL to unset handler.

Return values:

0 – On success.

int nrf_modem_softsim_res(enum nrf_modem_softsim_cmd cmd, uint16_t req_id, void *data, uint16_t data_len)

Sends a SoftSIM response to a request.

This function is used to respond to the Modem with the data requested by a specific request.

Parameters:

• cmd – SoftSIM response command.

• req_id – Request ID used to match request and response.

• data – [in] Pointer to the data of the SoftSIM response.

• data_len – Length of the data of the SoftSIM response.

Return values:

• 0 – on success.

• -NRF_EINVAL – If input data is invalid.

• -NRF_ENOMEM – If memory allocation failed.

int nrf_modem_softsim_err(enum nrf_modem_softsim_cmd cmd, uint16_t req_id)

Sends a SoftSIM error to a request.

This function is used to inform the Modem that an error occurred for a specific request.

Parameters:

• cmd – SoftSIM response command.

• req_id – Request ID used to match request and response.

Return values:

• 0 – on success.

• -NRF_ENOMEM – If memory allocation failed.

void nrf_modem_softsim_data_free(void *data)

Free the data of a SoftSIM request.

Parameters:

• data – Data to free.

OS specific definitions

group nrf_modem_os

Defines

NRF_MODEM_OS_NO_WAIT

Zero time-out.

NRF_MODEM_OS_FOREVER

Infinite time-out.

NRF_MODEM_OS_NUM_SEM_REQUIRED

Number of OS semaphores required.

NRF_MODEM_OS_NUM_MUTEX_REQUIRED

Number of OS mutexes required.

Enums

enum log_level

Values:

enumerator NRF_MODEM_LOG_LEVEL_NONE

enumerator NRF_MODEM_LOG_LEVEL_ERR

enumerator NRF_MODEM_LOG_LEVEL_WRN

enumerator NRF_MODEM_LOG_LEVEL_INF

enumerator NRF_MODEM_LOG_LEVEL_DBG

Functions

void nrf_modem_os_init(void)

Initialize the glue layer.

void nrf_modem_os_shutdown(void)

Deinitialize the glue layer.

When shutdown is called, all pending calls to nrf_modem_os_timedwait exit and return -NRF_ESHUTDOWN.

void *nrf_modem_os_shm_tx_alloc(size_t bytes)

Allocate a buffer on the TX area of shared memory.

Parameters:

• bytes – Buffer size.

Returns:

A pointer to the allocated memory buffer or NULL if allocation failed.

void nrf_modem_os_shm_tx_free(void *mem)

Free a shared memory buffer in the TX area.

Parameters:

• mem – Buffer to free.

void *nrf_modem_os_alloc(size_t bytes)

Allocate a buffer on the library heap.

Parameters:

• bytes – Buffer size.

Returns:

A pointer to the allocated memory buffer or NULL if allocation failed.

void nrf_modem_os_free(void *mem)

Free a memory buffer in the library heap.

Parameters:

• mem – Buffer to free.

void nrf_modem_os_busywait(int32_t usec)

Busy wait.

Parameters:

• usec – Microseconds to busy wait for.

int32_t nrf_modem_os_timedwait(uint32_t context, int32_t *timeout)

Put a thread to sleep for a specific time or until an event occurs.

The thread is woken if the timeout has expired and by a nrf_modem_event_notify call if

• The context equals the event context.

• The context is zero (thread wakes on all calls to event notify).

• The event context is zero (wake all sleeping threads).

The timeout parameter is updated to contain the amount of time left to sleep.

Parameters:

• context – Library context.

• timeout – [inout] Timeout in milliseconds, or NRF_MODEM_OS_FOREVER for no timeout. Specifies the timeout value on input and the remaining time to sleep on output.

Return values:

• 0 – The thread is woken before the timeout expired.

• -NRF_EAGAIN – The timeout expired.

• -NRF_ESHUTDOWN – Modem is not initialized, or was shut down.

void nrf_modem_os_event_notify(uint32_t context)

Notify the application that an event has occurred.

This function wakes up a thread sleeping in nrf_modem_os_timedwait if:

• The thread context equals context.

• The thread context is zero (thread wakes on all calls to event notify).

• The context is zero (wake all sleeping threads).

Parameters:

• context – Library context.

int nrf_modem_os_sleep(uint32_t timeout)

Put a thread to sleep for a specific amount of time.

Parameters:

• timeout – Timeout in millisec.

Returns:

0 on success, a negative errno otherwise.

void nrf_modem_os_errno_set(int errno_val)

Set errno.

Parameters:

• errno_val – errno to set.

bool nrf_modem_os_is_in_isr(void)

Check if executing in interrupt context.

Return values:

• true – If in interrupt context.

• false – If not in interrupt context.

int nrf_modem_os_sem_init(void **sem, unsigned int initial_count, unsigned int limit)

Initialize a semaphore.

The function initializes a semaphore and returns its address as an output. If an address of an already allocated semaphore is provided as an input, the allocation part is skipped and the semaphore is only reinitialized.

Parameters:

• sem – [inout] The address of the semaphore.

• initial_count – Initial semaphore count.

• limit – Maximum semaphore count.

Returns:

0 on success, a negative errno otherwise.

void nrf_modem_os_sem_give(void *sem)

Give a semaphore.

Note

Can be called from an ISR.

Parameters:

• sem – The semaphore.

int nrf_modem_os_sem_take(void *sem, int timeout)

Take a semaphore.

Note

timeout must be set to NRF_MODEM_OS_NO_WAIT if called from ISR.

Parameters:

• sem – The semaphore.

• timeout – Timeout in milliseconds. NRF_MODEM_OS_FOREVER indicates infinite timeout. NRF_MODEM_OS_NO_WAIT indicates no timeout.

Return values:

• 0 – on success.

• -NRF_EAGAIN – If the semaphore could not be taken.

unsigned int nrf_modem_os_sem_count_get(void *sem)

Get a semaphore’s count.

Parameters:

• sem – The semaphore.

Returns:

Current semaphore count.

int nrf_modem_os_mutex_init(void **mutex)

Initialize a mutex.

The function shall allocate and initialize a mutex and return its address as an output. If an address of an already allocated mutex is provided as an input, the allocation part is skipped and the mutex is only reinitialized.

Parameters:

• mutex – [inout] The address of the mutex.

Returns:

0 on success, a negative errno otherwise.

int nrf_modem_os_mutex_lock(void *mutex, int timeout)

Lock a mutex.

Parameters:

• mutex – The mutex.

• timeout – Timeout in milliseconds. NRF_MODEM_OS_FOREVER indicates infinite timeout. NRF_MODEM_OS_NO_WAIT indicates no timeout.

Return values:

• 0 – on success.

• -NRF_EAGAIN – If the mutex could not be taken.

int nrf_modem_os_mutex_unlock(void *mutex)

Unlock a mutex.

Parameters:

• mutex – The mutex.

Return values:

• 0 – on success.

• -NRF_EPERM – if the current thread does not own the mutex.

• -NRF_EINVAL – if the mutex is not locked.

void nrf_modem_os_log(int level, const char *fmt, ...)

Generic logging procedure.

Parameters:

• level – Log level.

• fmt – Format string.

• ... – Varargs.

void nrf_modem_os_logdump(int level, const char *str, const void *data, size_t len)

Logging procedure for dumping hex representation of object.

Parameters:

• level – Log level.

• str – String to print in the log.

• data – Data whose hex representation we want to log.

• len – Length of the data to hex dump.