API documentation

Note

Starting from Modem library v1.2.0, the GNSS socket is deprecated and replaced with the GNSS API.

Library Management

group nrf_modem

Application interface offered for management of the Modem library.

Enums

enum nrf_modem_mode_t

Modem library mode.

Values:

enumerator NORMAL_MODE

Normal operation mode

enumerator FULL_DFU_MODE

DFU mode

Functions

char *nrf_modem_build_version(void)

Return version string of the Modem library build.

Returns Version

string if defined.

Returns Empty

string if version string is not defined.

int nrf_modem_init(const nrf_modem_init_params_t *init_params, enum nrf_modem_mode_t mode)

Initialize the Modem library.

Once initialized, the library uses the resources defined in nrf_modem_platform.h.

Library has two operation modes, normal and DFU. In normal operation mode, the DFU functionality is disabled.

Library can alternatively be initialized in DFU mode, which means that all shared memory regions are now reserved for DFU operation, and therefore no other modem functionality can be used.

To switch between DFU and normal modes, nrf_modem_shutdown() should be called in between.

Parameters

• init_params – [in] Initialization parameters. Cannot be NULL.

• mode – [in] Library mode.

Returns Zero

on success.

Returns A

positive value from Modem DFU when executing Modem firmware updates.

Returns -1

on error.

int nrf_modem_shutdown(void)

Shutdown the Modem library.

Resources reserved by the library in nrf_modem_platform.h are freed when the library is shutdown.

Note

The modem must be put into offline (CFUN=0) mode before shutting it down.

Returns Zero

on success.

Returns -1

on error.

void nrf_modem_recoverable_error_handler(uint32_t error)

Handler for library errors.

Parameters

• error – [in] The error reason.

struct nrf_modem_shmem_cfg

#include <nrf_modem.h>

Shared memory configuration.

Note

: Only the lower 128k of RAM may be shared with the modem core.

Public Members

struct nrf_modem_shmem_cfg.[anonymous] tx

TX memory, used to send data to the modem

struct nrf_modem_shmem_cfg.[anonymous] rx

RX memory, used to receive data from the modem

struct nrf_modem_shmem_cfg.[anonymous] trace

Trace memory, used to receive traces from the modem

struct nrf_modem_init_params_t

#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_init() return values for modem firmware updates

group nrf_modem_dfu

nrf_modem_init() return values when executing Modem firmware updates.

Defines

MODEM_DFU_RESULT_OK

Modem firmware update successful. The modem will run the updated firmware on reboot.

MODEM_DFU_RESULT_INTERNAL_ERROR

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

MODEM_DFU_RESULT_HARDWARE_ERROR

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

MODEM_DFU_RESULT_AUTH_ERROR

Modem firmware update failed, due to an authentication error. The modem will automatically run the previous (non-updated) firmware on reboot.

MODEM_DFU_RESULT_UUID_ERROR

Modem firmware update failed, due to UUID mismatch. The modem will automatically run the previous (non-updated) firmware on reboot.

Limits of the Modem library

group nrf_modem_limits

Upper and lower bound limits of the Modem library.

Defines

NRF_MODEM_MAX_SOCKET_COUNT

Maximum number of AT and IP sockets available at the same time.

NRF_MODEM_AT_MAX_CMD_SIZE

Maximum AT Command Size in bytes.

NRF_MODEM_IP_MAX_MESSAGE_SIZE

Maximum IP message size in bytes.

NRF_MODEM_TLS_MAX_MESSAGE_SIZE

Maximum TLS message size in bytes.

NRF_MODEM_MAX_PDN_COUNT

Maximum number of PDN connections that can be created.

Resources for the Modem library

group nrf_modem_platform_ipc

group nrf_modem_reserved_interrupts

Interrupts and priorities reserved by the library for communication with the application and the network layer.

Defines

NRF_MODEM_NETWORK_IRQ

Interrupt used for communication with the network layer.

NRF_MODEM_NETWORK_IRQ_PRIORITY

Interrupt priority used on interrupt for communication with the network layer.

NRF_MODEM_APPLICATION_IRQ

Interrupt used for communication with the application layer.

NRF_MODEM_APPLICATION_IRQ_PRIORITY

Interrupt priority used on interrupt for communication with the application layer.

Socket parameter enumerators

Socket families

group nrf_socket_families

Defines

NRF_AF_UNSPEC

Unspecified address family

NRF_AF_LOCAL

Family to identify protocols/operations local to Nordic device.

NRF_AF_INET

IPv4 socket family.

NRF_AF_PACKET

Raw packet family.

NRF_AF_INET6

IPv6 socket family.

NRF_AF_LTE

Nordic proprietary LTE socket 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.

NRF_SOCK_MGMT

Nordic specific management socket. Used for system or link management.

Deprecated:

since v1.1.0.

Socket protocols

group nrf_socket_protocols

Defines

NRF_IPPROTO_TCP

TCP protocol.

NRF_IPPROTO_UDP

UDP protocol.

NRF_SPROTO_TLS1v2

TLS1v2 protocol.

NRF_SPROTO_TLS1v3

TLS1v3 protocol.

NRF_SPROTO_DTLS1v2

DTLS1v2 protocol.

NRF_PROTO_AT

AT command protocol.

NRF_PROTO_PDN

PDN management protocol.

Deprecated:

since v1.1.0.

NRF_PROTO_DFU

DFU protocol.

NRF_PROTO_GNSS

GNSS protocol.

Deprecated:

since v1.2.0.

Socket option levels

group nrf_socket_options_levels

Defines

NRF_SOL_SOCKET

NRF_SOL_SECURE

NRF_SOL_PDN

Deprecated:

since v1.1.0.

NRF_SOL_DFU

NRF_SOL_GNSS

Deprecated:

since v1.2.0.

Generic socket options

group nrf_socket_options_sockets

Socket options used with both AT and IP sockets.

Defines

NRF_SO_ERROR

NRF_SO_RCVTIMEO

NRF_SO_SNDTIMEO

NRF_SO_BINDTODEVICE

NRF_SO_SILENCE_ALL

NRF_SO_IP_ECHO_REPLY

Boolean control for ICMP echo reply disable/enable (0/1). Default is 1 (enabled).

NRF_SO_IPV6_ECHO_REPLY

Boolean control for ICMPv6 echo reply disable/enable (0/1). Default is 1 (enabled).

NRF_SO_REUSEADDR

NRF_SO_RAI_LAST

Release Assistance Indication feature: This will indicate that the next call to send/sendto will be the last one for some time, which means that the modem can get out of connected mode quicker when this data is sent.

NRF_SO_RAI_NO_DATA

Release Assistance Indication feature: This will indicate that the application will not send any more data. This socket option will apply immediately, and does not require a call to send afterwards.

NRF_SO_RAI_ONE_RESP

Release Assistance Indication feature: This will indicate that after the next call to send/sendto, the application is expecting to receive one more data packet before this socket will not be used again for some time.

NRF_SO_RAI_ONGOING

Release Assistance Indication feature: If a client application expects to use the socket more it can indicate that by setting this socket option before the next send call which will keep the modem in connected mode longer.

NRF_SO_RAI_WAIT_MORE

Release Assistance Indication feature: If a server application expects to use the socket more it can indicate that by setting this socket option before the next send call.

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

Socket send and recv flags

group nrf_socket_send_recv_flags

Defines

NRF_MSG_DONTROUTE

Send only to hosts on directly connected networks.

NRF_MSG_DONTWAIT

Enables non-blocking operation.

NRF_MSG_OOB

Sends out-of-band data on sockets that support this.

NRF_MSG_PEEK

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

NRF_MSG_WAITALL

Request a blocking operation until the request is satisfied.

NRF_MSG_TRUNC

Control the data truncation.

fcntl parameters

group nrf_fcnt_commands

API used to manipulate the behaviour of AT and IP sockets using nrf_fcntl().

Defines

NRF_F_SETFL

Set flag.

NRF_F_GETFL

Get flag.

NRF_O_NONBLOCK

Use non-blocking I/O.

Socket API

group nrf_socket_api

Functions

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

Function for creating a socket.

API to create a socket that can be used for network communication independently of lower protocol layers.

Parameters

• family – [in] The protocol family of the network protocol to use.

• type – [in] The protocol type to use for this socket.

• protocol – [in] The transport protocol to use for this socket.

Returns

A non-negative socket descriptor on success, or -1 on error.

int nrf_close(int sock)

Function for closing a socket and freeing any resources held by it.

If the socket is already closed, this function does nothing.

Parameters

• sock – [in] The socket to close.

Returns

0 on success, or -1 on error.

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 Descriptor manipulate API. For a list of supported flags, refer to nrf_fcnt_flags.

Parameters

• fd – [in] The descriptor to set options on.

• cmd – [in] The command class for options.

• flags – [in] The flags to set.

int nrf_connect(int sock, const void *p_servaddr, nrf_socklen_t addrlen)

Function for connecting to an endpoint with a given address.

The socket handle must be a valid handle that has not yet been connected. Running connect on a connected handle will return an error.

Parameters

• sock – [in] The socket to use for connection.

• p_servaddr – [in] The address of the server to connect to.

• addrlen – [in] The size of the p_servaddr argument.

Returns

0 on success, or -1 on error.

ssize_t nrf_send(int sock, const void *p_buff, size_t nbytes, int flags)

Function for sending data through a socket.

By default, this function will block unless the NRF_O_NONBLOCK socket option has been set, OR NRF_MSG_DONTWAIT is passed as a flag. In that case, the method will return immediately.

Parameters

• sock – [in] The socket to write data to.

• p_buff – [in] Buffer containing the data to send.

• nbytes – [in] Size of data contained on p_buff.

• flags – [in] Flags to control send behavior.

Returns

The number of bytes that were sent on success, or -1 on error.

ssize_t nrf_sendto(int sock, const void *p_buff, size_t nbytes, int flags, const void *p_servaddr, nrf_socklen_t addrlen)

Function for sending datagram through a socket.

By default, this function will block if the lower layers are not able to process the packet, unless the NRF_O_NONBLOCK socket option has been set, OR NRF_MSG_DONTWAIT is passed as a flag. In that case, the method will return immediately.

Parameters

• sock – [in] The socket to write data to.

• p_buff – [in] Buffer containing the data to send.

• nbytes – [in] Size of data contained in p_buff.

• flags – [in] Flags to control send behavior.

• p_servaddr – [in] The address of the server to send to.

• addrlen – [in] The size of the p_servaddr argument.

Returns

The number of bytes that were sent on success, or -1 on error.

ssize_t nrf_write(int sock, const void *p_buff, size_t nbytes)

Function for writing data to a socket. See nrf_send() for details.

Parameters

• sock – [in] The socket to write data to.

• p_buff – [in] Buffer containing the data to send.

• nbytes – [in] Size of data contained in p_buff.

Returns

The number of bytes that were sent on success, or -1 on error.

ssize_t nrf_recv(int sock, void *p_buff, size_t nbytes, int flags)

Function for receiving data on a socket.

API for receiving data from a socket. By default, this function will block, unless the NRF_O_NONBLOCK socket option has been set, or NRF_MSG_DONTWAIT is passed as a flag.

Parameters

• sock – [in] The socket to receive data from.

• p_buff – [out] Buffer to hold the data to be read.

• nbytes – [in] Number of bytes to read. Should not be larger than the size of p_buff.

• flags – [in] Flags to control receive behavior.

Returns

The number of bytes that were read, or -1 on error.

ssize_t nrf_recvfrom(int sock, void *p_buff, size_t nbytes, int flags, void *p_cliaddr, nrf_socklen_t *p_addrlen)

Function for receiving datagram on a socket.

API for receiving data from a socket. By default, this function will block, unless the NRF_O_NONBLOCK socket option has been set, or NRF_MSG_DONTWAIT is passed as a flag.

Parameters

• sock – [in] The socket to receive data from.

• p_buff – [out] Buffer to hold the data to be read.

• nbytes – [in] Number of bytes to read. Should not be larger than the size of p_buff.

• flags – [in] Flags to control receive behavior.

• p_cliaddr – [out] Socket address that will be set to the client’s address.

• p_addrlen – [inout] The size of the p_cliaddr passed. Might be modified by the function.

Returns

The number of bytes that were read, or -1 on error.

ssize_t nrf_read(int sock, void *p_buff, size_t nbytes)

Function for reading data from a socket. See nrf_recv() for details.

Parameters

• sock – [in] The socket to receive data from.

• p_buff – [out] Buffer to hold the data to be read.

• nbytes – [in] Number of bytes to read. Should not be larger than the size of p_buff.

Returns

The number of bytes that were read, or -1 on error.

int nrf_select(int nfds, nrf_fd_set *p_readset, nrf_fd_set *p_writeset, nrf_fd_set *p_exceptset, const struct nrf_timeval *p_timeout)

Function for waiting for read, write, or exception events on a socket.

Wait for a set of socket descriptors to be ready for reading, writing, or having exceptions. The set of socket descriptors is configured before calling this function. This function will block until any of the descriptors in the set has any of the required events. This function is mostly useful when using NRF_O_NONBLOCK or NRF_MSG_DONTWAIT options to enable asynchronous operation.

Parameters

• nfds – [in] The highest socket descriptor value contained in the sets.

• p_readset – [inout] The set of descriptors for which to wait for read events. Set to NULL if not used.

• p_writeset – [inout] The set of descriptors for which to wait for write events. Set to NULL if not used.

• p_exceptset – [inout] The set of descriptors for which to wait for exception events. Set to NULL if not used.

• p_timeout – [in] The timeout to use for select call. Set to NULL if waiting forever.

Returns

The number of ready descriptors contained in the descriptor sets on success, or -1 on error.

int nrf_poll(struct nrf_pollfd *p_fds, uint32_t nfds, int timeout)

Method to poll for events on one or more sockets.

Parameters

• p_fds – [inout] An array of sockets, and respective for each socket that the caller polls for. The occurred events per socket is returned in the revents field of nrf_pollfd structure. Shall not be NULL.

• nfds – [in] Positive number of sockets being polled for events. Shall not be more than NRF_MODEM_MAX_SOCKET_COUNT.

• timeout – [in] Timeout in milliseconds. The methods waits for this time period for the events to occur on the sockets.

Returns

A positive number less than or equal to nfds indicating sockets on which events occurred. 0 indicates the timed out occurred and no file descriptors were ready. -1 on error, and errno indicates the reason for failure.

int nrf_setsockopt(int sock, int level, int optname, const void *p_optval, nrf_socklen_t optlen)

Function for setting socket options for a given socket.

The options are grouped by level, and the option value should be the expected for the given option, and the lifetime must be longer than that of the socket.

Parameters

• sock – [in] The socket for which to set the option.

• level – [in] The level or group to which the option belongs.

• optname – [in] The name of the socket option.

• p_optval – [in] The value to be stored for this option.

• optlen – [in] The size of p_optval.

Returns

0 on success, or -1 on error.

int nrf_getsockopt(int sock, int level, int optname, void *p_optval, nrf_socklen_t *p_optlen)

Function for getting socket options for a given socket.

The options are grouped by level, and the option value is the value described by the option name.

Parameters

• sock – [in] The socket for which to set the option.

• level – [in] The level or group to which the option belongs.

• optname – [in] The name of the socket option.

• p_optval – [out] Pointer to the storage for the option value.

• p_optlen – [inout] The size of p_optval. Can be modified to the actual size of p_optval.

Returns

0 on success, or -1 on error.

int nrf_bind(int sock, const void *p_myaddr, nrf_socklen_t addrlen)

Function for binding a socket to an address and port.

The provided address must be supported by the socket protocol family.

Parameters

• sock – [in] The socket descriptor to bind.

• p_myaddr – [in] The address to bind this socket to.

• addrlen – [in] The size of p_myaddr.

Returns

0 on success, or -1 on error.

int nrf_listen(int sock, int backlog)

Function to put the socket in listening mode for incoming connections.

Once a socket is marked to be in the listening state, it remains a listening socket until closed. It is important to consider the backlog parameter, as it will affect how much memory your application will use in the worst case.

Parameters

• sock – [in] The socket descriptor on which to set the listening options.

• backlog – [in] The max length of the queue of pending connections. A value of 0 means infinite.

Returns

0 on success, or -1 on error.

int nrf_accept(int sock, void *p_cliaddr, nrf_socklen_t *p_addrlen)

Function for waiting for the next client to connect.

This function will block if there are no clients attempting to connect.

Parameters

• sock – [in] The socket descriptor to use for waiting on client connections.

• p_cliaddr – [out] Socket address that will be set to the client’s address.

• p_addrlen – [out] The size of the p_cliaddr passed. Might be modified by the function.

Returns

A non-negative client descriptor on success, or -1 on error.

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_SO_SEC_ROLE

Socket option to set role for the connection. Accepts an nrf_sec_role_t with values:

• 0 - Client role.

• 1 - Server role.

NRF_SO_SEC_TAG_LIST

Socket option to select the security tags to be used.

See

nrf_sec_tag_t.

NRF_SO_SEC_SESSION_CACHE

Socket option to control TLS session caching. Accepts an nrf_sec_session_cache_t with values:

• 0 - Disabled.

• 1 - Enabled.

  See

  nrf_sec_session_cache_t.

NRF_SO_SEC_PEER_VERIFY

Socket option to set peer verification level. This option accepts an nrf_sec_peer_verify_t with values:

• 0 - None

• 1 - Optional

• 2 - Required

  See

  nrf_sec_peer_verify_t.

NRF_SO_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_CIPHERSUITE_LIST

Socket option to select which ciphersuites to use.

See

nrf_sec_cipher_t.

NRF_SO_CIPHER_IN_USE

Socket option to retrieve the ciphersuites used during the handshake. Currently unsupported.

See

nrf_sec_cipher_t.

NRF_SO_SEC_DTLS_HANDSHAKE_TIMEO

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

NRF_SO_SEC_SESSION_CACHE_PURGE

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

NRF_IFNAMSIZ

Maximum network interface name size.

Deprecated:

since v1.1.0.

Typedefs

typedef uint32_t nrf_sec_role_t

TLS role for the connection.

• 0 - TLS client role.

• 1 - TLS server role.

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 8 tags can be set per socket.

typedef uint8_t nrf_sec_session_cache_t

Session cache configuration for the TLS connection.

• 0 - Disabled.

• 1 - Enabled.

By default, the session cache is enabled.

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.

typedef uint32_t nrf_sec_cipher_t

A IANA cipher suite identifier.

struct nrf_sec_config_t

#include <nrf_socket.h>

Data type to combine all security configuration parameters.

Public Members

nrf_sec_role_t role

Local role to be played. See nrf_sec_role_t for details.

nrf_sec_peer_verify_t peer_verify

Indicates the preference for peer verification. See nrf_sec_peer_verify_t for details.

nrf_sec_session_cache_t session_cache

Indicates the preference for session caching. See nrf_sec_session_cache_t for details.

uint32_t cipher_count

Indicates the number of entries in the cipher list.

nrf_sec_cipher_t *p_cipher_list

Indicates the list of ciphers to be used for the session. See nrf_sec_cipher_t for details.

uint32_t sec_tag_count

Indicates the number of entries in the sec tag list.

nrf_sec_tag_t *p_sec_tag_list

Indicates the list of security tags to be used for the session. See nrf_sec_tag_t for details.

struct nrf_ifreq

#include <nrf_socket.h>

Data type for network interface.

Deprecated:

since v1.1.0.

DTLS handshake timeout values

group nrf_socket_tls_dtls_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_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

GNSS socket

GNSS socket options

group nrf_socket_gnss_options

Sockets options to configure behaviour of the socket.

Deprecated:

since v1.2.0.

Defines

NRF_SO_GNSS_FIX_INTERVAL

Identifies the option used to set 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…1800. The unit is seconds.

Deprecated:

since v1.2.0.

NRF_SO_GNSS_FIX_RETRY

Identifies the option used to set the GNSS fix retry interval 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.

Deprecated:

since v1.2.0.

NRF_SO_GNSS_SYSTEM

Identifies the option used to set and/or get the GNSS system used. See nrf_gnss_system_t for details.

Deprecated:

since v1.2.0.

NRF_SO_GNSS_NMEA_MASK

Identifies the option used to select the data format of the received data.

Deprecated:

since v1.2.0.

NRF_SO_GNSS_ELEVATION_MASK

Indicates at which elevation the GPS should stop tracking a satellite.

Deprecated:

since v1.2.0.

NRF_SO_GNSS_USE_CASE

Indicates the targeted start performance.

Deprecated:

since v1.2.0.

NRF_SO_GNSS_START

Identifies the option to start the GPS. nrf_gnss_delete_mask_t given as payload.

Deprecated:

since v1.2.0.

NRF_SO_GNSS_STOP

Identifies the option to stop the GPS. nrf_gnss_delete_mask_t given as payload.

Deprecated:

since v1.2.0.

NRF_SO_GNSS_POWER_SAVE_MODE

Identifies the option to set power save mode.

Deprecated:

since v1.2.0.

NRF_SO_GNSS_ENABLE_PRIORITY

Identifies the option to enable priority time window (with no payload).

Deprecated:

since v1.2.0.

NRF_SO_GNSS_DISABLE_PRIORITY

Identifies the option to disable priority time window (with no payload).

Deprecated:

since v1.2.0.

GNSS socket option data types

group nrf_socketopt_gnss_types

Data types defined to set and get socket options on GNSS sockets.

Deprecated:

since v1.2.0.

Typedefs

typedef uint16_t nrf_gnss_fix_interval_t

Defines the interval between each fix in seconds.

Allowed values are 0, 1, 10..1800, value 0 denotes single fix. Default interval is 1 second (continous mode), 0 denotes a single fix.

Deprecated:

since v1.2.0.

typedef uint16_t nrf_gnss_fix_retry_t

Defines how long (in seconds) the receiver should try to get a fix.

The default retry wait time is 60 seconds before it gives up. 0 denotes an infinite limit.

Deprecated:

since v1.2.0.

typedef uint8_t nrf_gnss_system_t

Defines which GNSS system to use.

0 denotes GPS. Currently, only GPS is supported and any other value returns an error.

Deprecated:

since v1.2.0.

typedef uint8_t nrf_gnss_elevation_mask_t

Defines at which elevation the GPS should track a satellite.

This option is used to make the GPS stop tracking GPSes on a certain elevation, because the information sent from the GPS gets more inaccurate as it gets closer to the horizon. Acceptable values are between 0 and 30 degrees.

Deprecated:

since v1.2.0.

typedef uint8_t nrf_gnss_use_case_t

Defines the targeted start performance.

0 denotes single cold start performance. 1 denotes multiple hot start performance.

Deprecated:

since v1.2.0.

typedef uint16_t nrf_gnss_nmea_mask_t

Defines if NMEA frames should be added.

Deprecated:

since v1.2.0.

typedef uint8_t nrf_gnss_power_save_mode_t

Defines which power mode policy to use for the GNSS module.

• NRF_GNSS_PSM_DISABLED for no power mode policy.

• NRF_GNSS_PSM_DUTY_CYCLING_PERFORMANCE for low power mode with better performance.

• NRF_GNSS_PSM_DUTY_CYCLING_POWER for low power mode with lower power consumption.

The available power modes determine whether duty-cycled tracking is allowed, and, if allowed what is the target performance.

Performance duty-cycled power mode: Duty-cycled tracking is engaged and run when conditions allow it without significant performance degradation.

Power duty-cycled power mode:: Duty-cycled tracking is engaged and run whenever it is possible with acceptable performance degradation.

The GNSS receiver keeps producing PVT estimates at the configured rate regardless of whether it is tracking continuously or in duty cycles. However, a failure to produce a valid PVT estimate during duty-cycled tracking may cause the GNSS receiver to resume continuous tracking.

Deprecated:

since v1.2.0.

typedef uint32_t nrf_gnss_delete_mask_t

Defines a mask of non-volatile data types to delete.

• Bit 0 denotes ephemerides data.

• Bit 1 denotes almanac data (excluding leap second and ionospheric correction parameters).

• Bit 2 denotes ionospheric correction parameters data.

• Bit 3 denotes last good fix (the last position) data.

• Bit 4 denotes GPS time-of-week (TOW) data.

• Bit 5 denotes GPS week number data.

• Bit 6 denotes leap second (UTC parameters) data.

• Bit 7 denotes local clock (TCXO) frequency offset data.

  Deprecated:

  since v1.2.0.

NMEA mask enumerator

group nrf_socket_gnss_nmea_str_mask

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.

Deprecated:

since v1.2.0.

Defines

NRF_GNSS_NMEA_GGA_MASK

Enables Global Positioning System Fix Data.

Deprecated:

since v1.2.0.

NRF_GNSS_NMEA_GLL_MASK

Enables Geographic Position Latitude/Longitude and time.

Deprecated:

since v1.2.0.

NRF_GNSS_NMEA_GSA_MASK

Enables DOP and active satellites.

Deprecated:

since v1.2.0.

NRF_GNSS_NMEA_GSV_MASK

Enables Satellites in view.

Deprecated:

since v1.2.0.

NRF_GNSS_NMEA_RMC_MASK

Enables Recommended minimum specific GPS/Transit data.

Deprecated:

since v1.2.0.

Power save mode enumerator

group nrf_socket_gnss_psm_modes

Use these values to select which power save mode the GNSS module should use.

Deprecated:

since v1.2.0.

Defines

NRF_GNSS_PSM_DISABLED

No power save mode is enabled.

Deprecated:

since v1.2.0.

NRF_GNSS_PSM_DUTY_CYCLING_PERFORMANCE

Enables duty-cycling performance policy power save mode.

Deprecated:

since v1.2.0.

NRF_GNSS_PSM_DUTY_CYCLING_POWER

Enables duty-cycling power policy power save mode.

Deprecated:

since v1.2.0.

Use case enumerator

group nrf_socket_gnss_use_case_modes

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

Deprecated:

since v1.2.0.

Defines

NRF_GNSS_USE_CASE_SINGLE_COLD_START

Single cold start performance bit 0 value

Deprecated:

since v1.2.0.

NRF_GNSS_USE_CASE_MULTIPLE_HOT_START

Multiple hot start performance bit 0 value

Deprecated:

since v1.2.0.

NRF_GNSS_USE_CASE_NORMAL_ACCURACY

Normal accuracy fixes bit 1 value

Deprecated:

since v1.2.0.

NRF_GNSS_USE_CASE_LOW_ACCURACY

Low accuracy fixes allowed bit 1 value

Deprecated:

since v1.2.0.

GNSS socket data frames

group nrf_socket_gnss_data_frame

GNSS Data frame formats. All data frames will be wrapped with the nrf_gnss_data_frame_t which will identify the frame type in the data_id struct element.

Deprecated:

since v1.2.0.

Defines

NRF_GNSS_MAX_SATELLITES

Deprecated:

since v1.2.0.

NRF_GNSS_NMEA_MAX_LEN

Deprecated:

since v1.2.0.

NRF_GNSS_AGPS_GPS_UTC_REQUEST

Deprecated:

since v1.2.0.

NRF_GNSS_AGPS_KLOBUCHAR_REQUEST

Deprecated:

since v1.2.0.

NRF_GNSS_AGPS_NEQUICK_REQUEST

Deprecated:

since v1.2.0.

NRF_GNSS_AGPS_SYS_TIME_AND_SV_TOW_REQUEST

Deprecated:

since v1.2.0.

NRF_GNSS_AGPS_POSITION_REQUEST

Deprecated:

since v1.2.0.

NRF_GNSS_AGPS_INTEGRITY_REQUEST

Deprecated:

since v1.2.0.

NRF_GNSS_PVT_DATA_ID

Deprecated:

since v1.2.0.

NRF_GNSS_NMEA_DATA_ID

Deprecated:

since v1.2.0.

NRF_GNSS_AGPS_DATA_ID

Deprecated:

since v1.2.0.

Typedefs

typedef char nrf_gnss_nmea_data_frame_t[83]

Single null-terminated NMEA sentence.

Deprecated:

since v1.2.0.

struct nrf_gnss_datetime_t

#include <nrf_socket.h>

Deprecated:

since v1.2.0.

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_gnss_sv_t

#include <nrf_socket.h>

Deprecated:

since v1.2.0.

Public Members

uint16_t sv

SV number 1…32 for GPS.

uint8_t signal

Signal type. 0: invalid, 1: GPS L1C/A, other values are reserved for other GNSSes or signals.

uint16_t cn0

0.1 dB/Hz.

int16_t elevation

SV elevation angle in degrees.

int16_t azimuth

SV azimuth angle in degrees.

uint8_t flags

Bit mask of measurement and position computation flags.

struct nrf_gnss_pvt_data_frame_t

#include <nrf_socket.h>

Deprecated:

since v1.2.0.

Public Members

double latitude

Latitude in degrees.

double longitude

Longitude in degrees.

float altitude

Altitude above WGS-84 ellipsoid in meters.

float accuracy

Accuracy (2D 1-sigma) in meters.

float speed

Horizontal speed in meters.

float heading

Heading of user movement in degrees.

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

Bit 0 (LSB): fix validity. Bit 1: Leap second validity. Bit 2: If set, the GNSS operation is blocked, for example, by LTE.

nrf_gnss_sv_t sv[12]

Describes up to 12 of the space vehicles used for the measurement.

struct nrf_gnss_agps_data_frame_t

#include <nrf_socket.h>

AGPS notification data frame used by the GPS module to let the application know it needs new APGS data.

Deprecated:

since v1.2.0.

Public Members

uint32_t sv_mask_ephe

Bit mask indicating the satellite PRNs for which the assistance GPS ephemeris data is needed.

uint32_t sv_mask_alm

Bit mask indicating the satellite PRNs for which the assistance GPS almanac data is needed.

uint32_t data_flags

Indicating other AGPS data models is needed by the GNSS module

struct nrf_gnss_data_frame_t

#include <nrf_socket.h>

Wrapper struct that used for all data frames read from the GNSS module.

Deprecated:

since v1.2.0.

Public Members

nrf_gnss_pvt_data_frame_t pvt

PVT (Position, Velocity, and Time) data notification frame

nrf_gnss_nmea_data_frame_t nmea

NMEA data notification frame

nrf_gnss_agps_data_frame_t agps

AGPS data request notification

GNSS socket AGPS data frames

group nrf_socket_gnss_data_agps

AGPS Data types.

Use these values in the address field when using sendto to write AGPS models to the GNSS module.

Deprecated:

since v1.2.0.

Deprecated:

since v1.2.0.

Defines

NRF_GNSS_AGPS_UTC_PARAMETERS

GPS UTC assistance AGPS parameters.

Deprecated:

since v1.2.0.

NRF_GNSS_AGPS_EPHEMERIDES

GPS ephemeris assistance AGPS parameters.

Deprecated:

since v1.2.0.

NRF_GNSS_AGPS_ALMANAC

GPS almanac assistance AGPS parameters.

Deprecated:

since v1.2.0.

NRF_GNSS_AGPS_KLOBUCHAR_IONOSPHERIC_CORRECTION

GPS ionospheric assistance AGPS parameters, Klobuchar model.

Deprecated:

since v1.2.0.

NRF_GNSS_AGPS_NEQUICK_IONOSPHERIC_CORRECTION

GPS ionospheric assistance AGPS parameters, NeQuick model.

Deprecated:

since v1.2.0.

NRF_GNSS_AGPS_GPS_SYSTEM_CLOCK_AND_TOWS

GPS system time and SV TOW assistance AGPS parameter.

Deprecated:

since v1.2.0.

NRF_GNSS_AGPS_LOCATION

GPS location assistance AGPS parameters

Deprecated:

since v1.2.0.

NRF_GNSS_AGPS_INTEGRITY

GPS integrity assistance AGPS parameters

Deprecated:

since v1.2.0.

NRF_GNSS_AGPS_MAX_SV_TOW

Deprecated:

since v1.2.0.

Typedefs

typedef uint16_t nrf_gnss_agps_data_type_t

Type used to select which AGPS data is written to the GPS module.

Goes into the p_servaddr parameter in the nrf_sendto function prototype. Possible values:

• NRF_GNSS_AGPS_UTC_PARAMETERS

• NRF_GNSS_AGPS_EPHEMERIDE

• NRF_GNSS_AGPS_ALMANAC

• NRF_GNSS_AGPS_KLOBUCHAR_IONOSPHERIC_CORRECTION

• NRF_GNSS_AGPS_NEQUICK_IONOSPHERIC_CORRECTION

• NRF_GNSS_AGPS_GPS_SYSTEM_CLOCK_AND_TOWS

• NRF_GNSS_AGPS_LOCATION

• NRF_GNSS_AGPS_INTEGRITY

  Deprecated:

  since v1.2.0.

struct nrf_gnss_agps_data_utc_t

#include <nrf_socket.h>

Deprecated:

since v1.2.0.

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_gnss_agps_data_ephemeris_t

#include <nrf_socket.h>

Deprecated:

since v1.2.0.

Public Members

uint8_t sv_id

Satellite ID (dimensionless). Range 1…32.

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_gnss_agps_data_almanac_t

#include <nrf_socket.h>

Deprecated:

since v1.2.0.

Public Members

uint8_t sv_id

Satellite ID (dimensionless). Range 1…32.

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_gnss_agps_data_klobuchar_t

#include <nrf_socket.h>

Deprecated:

since v1.2.0.

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_gnss_agps_data_nequick_t

#include <nrf_socket.h>

Deprecated:

since v1.2.0.

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_gnss_agps_data_tow_element_t

#include <nrf_socket.h>

Deprecated:

since v1.2.0.

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_gnss_agps_data_system_time_and_sv_tow_t

#include <nrf_socket.h>

Deprecated:

since v1.2.0.

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.

nrf_gnss_agps_data_tow_element_t sv_tow[32]

TOW assistance data for PRN n

struct nrf_gnss_agps_data_location_t

#include <nrf_socket.h>

Deprecated:

since v1.2.0.

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

#include <nrf_socket.h>

Deprecated:

since v1.2.0.

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.

DFU socket

group nrf_socket_dfu

DFU socket API.

Defines

NRF_SO_DFU_FW_VERSION

Socket option to read the modem firmware version (UUID).

See

nrf_dfu_fw_version_t.

NRF_SO_DFU_RESOURCES

Socket option to retrieve the size of the largest firmware image that can be transferred to the modem for firmware updates.

See

nrf_dfu_resources_t.

NRF_SO_DFU_TIMEO

Socket option to control the timeout to send a firmware fragment.

Note

Not implemented.

NRF_SO_DFU_APPLY

Socket option to schedule a modem firmware update at next boot. The result of the update is returned by nrf_modem_init, at next boot. The modem needs to be reset once more to run the updated firmware.

NRF_SO_DFU_REVERT

Socket option to schedule a rollback of a firmware update at next boot.

NRF_SO_DFU_BACKUP_DELETE

Socket option to delete a modem firmware image from the modem’s scratch area. This option removes the possibility to rollback to a previous version, and is necessary to receive new firmware images.

NRF_SO_DFU_OFFSET

Socket option read and write the offset of the downloaded firmware image in the modem’s scratch area. This option is used to determine whether a firmware image exists in the modem’s scratch area and its size. A value of 2.5 megabytes (2621440 bytes) is returned if the scratch area is dirty, and needs erasing (via NRF_SO_DFU_BACKUP_DELETE). If non-zero and different from 2.5 megabytes, the value indicates the size of the firmware image received so far.

NRF_SO_DFU_ERROR

Socket option to retrieve the latest DFU error, see DFU errors. Read-only.

Typedefs

typedef uint8_t nrf_dfu_fw_version_t[36]

Universally unique identifier of the modem firmware version. The UUID format is defined by RFC 4122.

typedef uint32_t nrf_dfu_resources_t

Maximum size for a firmware image, in bytes.

typedef uint32_t nrf_dfu_fw_offset_t

Size of the firmware image stored in flash, in bytes.

DFU errors

group nrf_dfu_errors

DFU socket errors.

Defines

DFU_NO_ERROR

DFU_RECEIVER_OUT_OF_MEMORY

DFU_RECEIVER_BLOCK_TOO_LARGE

DFU_INVALID_HEADER_DATA

DFU_ERROR_INTERNAL_00

DFU_INVALID_DATA

DFU_ERROR_INTERNAL_01

DFU_ERROR_INTERNAL_02

DFU_ERROR_INTERNAL_03

DFU_INVALID_UUID

DFU_INVALID_ADDRESS

DFU_AREA_NOT_BLANK

DFU_WRITE_ERROR

DFU_ERASE_ERROR

DFU_INVALID_FILE_OFFSET

DFU_PROGRESS_LOG_INVALID

DFU_INVALID_RESUME_ATTEMPT

DFU_ERASE_PENDING

DFU_OPERATION_NOT_ALLOWED

DFU_INCOMPLETE_DATA

DFU_INTERRUPTED_WRITE

Typedefs

typedef int32_t nrf_dfu_err_t

DFU socket error.

PDN socket

group nrf_socket_pdn

PDN socket API.

Data types defined to set and get socket options on a PDN socket.

Deprecated:

since v1.1.0. Use the nRF91 Packet Domain AT commands instead.

Deprecated:

since v1.1.0.

Defines

NRF_SO_PDN_AF

Socket option control the supported address families on the PDN.

Deprecated:

since v1.1.0.

See

nrf_pdn_af_list_t.

NRF_SO_PDN_CONTEXT_ID

Socket option to retrieve the context ID on the PDN.

Deprecated:

since v1.1.0.

See

nrf_pdn_context_id_t.

NRF_SO_PDN_STATE

Socket option to retrieve the PDN state, read-only.

Deprecated:

since v1.1.0.

See

nrf_pdn_state_t.

NRF_SO_PDN_AUTH

Socket option to set PDN authentication.

Deprecated:

since v1.1.0.

See

nrf_pdn_auth_t.

Typedefs

typedef nrf_sa_family_t *nrf_pdn_af_list_t

Deprecated:

since v1.1.0. List of address family(ies) for the PDN.

typedef uint8_t nrf_pdn_context_id_t

Context ID for the PDN.

Deprecated:

since v1.1.0.

typedef uint8_t nrf_pdn_state_t

PDN state. 1 - PDN is active. 0 - PDN is inactive.

Deprecated:

since v1.1.0.

Enums

enum nrf_pdn_auth_type_t

PDN authentication type.

Deprecated:

since v1.1.0.

Values:

enumerator NRF_PDN_AUTH_TYPE_NONE

enumerator NRF_PDN_AUTH_TYPE_PAP

enumerator NRF_PDN_AUTH_TYPE_CHAP

struct nrf_pdn_auth_t

#include <nrf_socket.h>

Structure for PDN authentication socket option.

Deprecated:

since v1.1.0.

Socket address resolution API

group nrf_socket_address_resolution

Address resolution utility functions.

Utility functions and macros for resolving host name and converting address information between human readable and a format the library expect.

Defines

NRF_HTONS(val)

Host to network byte-orders on half word.

NRF_HTONL(val)

Host to network byte-orders on full word.

NRF_NTOHS(val)

Network to host byte-orders on half word.

NRF_NTOHL(val)

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_PDN_MAX_USERNAME_LEN

Maximum length of PDN authentication username in string form, including null-termination character.

Deprecated:

since v1.1.0.

NRF_PDN_MAX_PASSWORD_LEN

Maximum length of PDN authentication password in string form, including null-termination character.

Deprecated:

since v1.1.0.

NRF_AI_NUMERICSERV

Assume service (port) is numeric. When specified together with the NRF_AI_PDNSERV flag, service shall 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.

NRF_AI_PDNSERV

Assume service contains a Packet Data Network (PDN) ID. When specified together with the NRF_AI_NUMERICSERV flag, service shall 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 int nrf_socket_family_t

Socket families.

For a list of valid values, refer to nrf_socket_families.

typedef nrf_socket_family_t nrf_sa_family_t

typedef uint32_t nrf_in_addr_t

IPv4 address.

typedef uint32_t nrf_socklen_t

Socket module size type.

Functions

int nrf_inet_pton(int family, const char *p_src, void *p_dst)

Function for converting a human-readable IP address to a form usable by the socket API.

This function will convert a string form of addresses and encode it into a byte array in network byte order.

Note

Currently not supporting mixed IPv4 and IPv6 format strings.

Parameters

• family – [in] Address family. NRF_AF_INET or NRF_AF_INET6.

• p_src – [in] Null-terminated string containing the address to convert.

• p_dst – [out] Pointer to a struct nrf_in_addr or nrf_in6_addr where the address will be stored.

Returns

1 on success, 0 if p_src does not contain a valid address, -1 and errno set in case of error.

const char *nrf_inet_ntop(int family, const void *p_src, char *p_dst, nrf_socklen_t size)

Function for converting an IP address to a human-readable string form.

This function will decode the IP bytes from network byte order and convert it to a string form of the address.

Note

Currently not supporting mixed IPv4 and IPv6 format strings.

Parameters

• family – [in] Address family. NRF_AF_INET or NRF_AF_INET6.

• p_src – [in] Pointer to a struct nrf_in_addr or nrf_in6_addr containing the address to convert.

• p_dst – [out] Pointer to a buffer where the string representation of the address will be stored.

• size – [in] Size of the provided buffer in p_dst.

Returns

Pointer to p_dst on success, NULL and errno set in case of error.

int nrf_getaddrinfo(const char *p_node, const char *p_service, const struct nrf_addrinfo *p_hints, struct nrf_addrinfo **pp_res)

Function to resolve the host name into IPv4 and/or IPv6 addresses.

Note

The memory pointed to by pp_res must be freed using nrf_freeaddrinfo when the address is no longer needed or before calling nrf_getaddrinfo again.

Parameters

• p_node – [in] Host name to resolve.

• p_service – [in] Service to resolve.

• p_hints – [in] Any hints to be used for the resolution.

• pp_res – [out] Pointer to the linked list of resolved addresses if the procedure was successful.

Returns

0 if the procedure succeeds, else, an errno indicating the reason for failure.

void nrf_freeaddrinfo(struct nrf_addrinfo *p_res)

Function for freeing the memory allocated for the result of nrf_getaddrinfo.

When the linked list of resolved addresses created by nrf_getaddrinfo is no longer needed, call this function to free the allocated memory.

Parameters

• p_res – [in] Pointer to the memory to be freed.

int nrf_setdnsaddr(int family, const void *in_addr)

Set a secondary DNS address.

The secondary DNS address is used automatically 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.

Parameters

• family – [in] Address family.

• in_addr – [in] An IPv4 or IPv6 address encoded in a nrf_in_addr or nrf_in6_addr structure, respectively. Pass NULL to unset the secondary DNS address.

Returns

int Zero on success, or an error from nrf_modem/include/nrf_errno.h otherwise.

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, as well as other socket options. All fields in this structure are compatible with the POSIX variant for API compatibility.

Public Members

uint8_t sin6_len

Length of this data structure.

nrf_sa_family_t sin6_family

Socket family.

nrf_in_port_t sin6_port

Port, in network byte order.

uint32_t sin6_flowinfo

IPv6 flow info parameters. Not used.

struct nrf_in6_addr sin6_addr

IPv6 address.

uint32_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. All fields in this structure are compatible with the POSIX variant for API compatibility.

Public Members

uint8_t sin_len

Length of this data structure.

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

uint8_t sa_len

Socket address length

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

File descriptor sets API

File descriptor sets are used as input to the nrf_select() function for doing I/O multiplexing. The maximum number of descriptors contained in a set is defined by NRF_FD_SETSIZE.

group nrf_fd_set_api

Types and macros used to manipulate the input data argument to the nrf_select() function.

File descriptor sets are used as input to the nrf_select() function for doing I/O multiplexing. The maximum number of descriptors contained in a set is defined by NRF_FD_SETSIZE.

Defines

NRF_FD_ZERO(set)

Clear the entire set.

NRF_FD_SET(fd, set)

Set a bit in the set.

NRF_FD_CLR(fd, set)

Clear a bit in the set.

NRF_FD_ISSET(fd, set)

Check if a bit in the set is set.

NRF_FD_SETSIZE

The max size of a set.

Typedefs

typedef uint32_t nrf_fd_set

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().

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

Defines

NRF_POLLIN

Event for data receive. Can be requested and returned.

NRF_POLLOUT

Event for data send. Can be requested and returned.

NRF_POLLERR

Event for error on the polled socket. Is set in returned events to indicate error on a polled socket. Ignored in requested events.

NRF_POLLHUP

Event to indicate that the polled socket has been closed by the peer. Ignored in requested events. Subsequent calls to read the socket will be possible until all outstanding data has been read, and return zero-length packets (EOF).

NRF_POLLNVAL

Event to indicate the polled socket is not open. Is set in returned events to indicate error on a polled socket. Ignored in requested events.

struct nrf_pollfd

#include <nrf_socket.h>

This structure is used to describe which events to poll for a given socket. Which is then given as argument to nrf_poll().

Public Members

int fd

Socket handle.

short events

Requested events, is a mask of events.

short revents

Returned events, is a mask of events.

GNSS API

group nrf_modem_gnss

API for accessing the GNSS module on the modem.

Defines

NRF_MODEM_GNSS_MAX_SATELLITES

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

NRF_MODEM_GNSS_NMEA_MAX_LEN

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

NRF_MODEM_GNSS_AGPS_MAX_SV_TOW

Maximum number of TOW elements in the TOW array.

See

nrf_modem_gnss_agps_data_system_time_and_sv_tow.

Typedefs

typedef void (*nrf_modem_gnss_event_handler_type_t)(int event)

Event handler prototype.

Parameters

• event – [in] Event ID, see Event type enumerator.

Functions

int32_t nrf_modem_gnss_init(void)

Initialize the GNSS interface.

This function is used to initialize the GNSS interface and must be called before any other function can be used.

Returns 0

on success.

Returns NRF_EPERM

if the interface is already initialized.

int32_t nrf_modem_gnss_deinit(void)

De-initialize the GNSS interface.

This function is used to de-initialize the GNSS interface. GNSS must not be running when this function is called.

Returns 0

on success.

Returns NRF_EPERM

if GNSS is running or not initialized.

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.

Returns 0

on success.

Returns NRF_EPERM

if GNSS is running or not initialized.

int32_t nrf_modem_gnss_system_mask_set(uint8_t system_mask)

Sets the supported GNSS systems. Systems which have the corresponding bit set are enabled.

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

Note

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

Parameters

• system_mask – [in] System bitmask, see GNSS system bitmask values.

Returns 0

on success.

Returns NRF_EPERM

if GNSS is running or not initialized.

Returns NRF_EINVAL

if GNSS returned an error.

Returns NRF_EAGAIN

if out of memory.

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

Returns 0

on success.

Returns NRF_EPERM

if GNSS is running or not initialized.

Returns NRF_EINVAL

if GNSS returned an error.

Returns NRF_EAGAIN

if out of memory.

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.

Returns 0

on success.

Returns NRF_EPERM

if GNSS is running or not initialized.

Returns NRF_EINVAL

if GNSS returned an error.

Returns NRF_EAGAIN

if out of memory.

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

Fix interval values over 1800 seconds are only supported by modem firmware v1.3.0 or later.

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.

Returns 0

on success.

Returns NRF_EPERM

if GNSS is running or not initialized.

Returns NRF_EINVAL

if GNSS returned an error.

Returns NRF_EAGAIN

if out of memory.

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.

Returns 0

on success.

Returns NRF_EPERM

if GNSS is running or not initialized.

Returns NRF_EINVAL

if GNSS returned an error.

Returns NRF_EAGAIN

if out of memory.

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.

Returns 0

on success.

Returns NRF_EPERM

if GNSS is running or not initialized.

Returns NRF_EINVAL

if GNSS returned an error.

Returns NRF_EAGAIN

if out of memory.

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.

Returns 0

on success.

Returns NRF_EPERM

if GNSS is running or not initialized.

Returns NRF_EINVAL

if GNSS returned an error.

Returns NRF_EAGAIN

if out of memory.

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.

Note

This feature is only supported by modem firmware v1.3.0 or later.

Parameters

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

Returns 0

on success.

Returns NRF_EPERM

if GNSS is running or not initialized.

Returns NRF_EINVAL

if GNSS returned an error.

Returns NRF_EAGAIN

if out of memory.

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

Note

This feature is only supported by modem firmware v1.3.0 or later.

Parameters

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

Returns 0

on success.

Returns NRF_EPERM

if GNSS is running or not initialized.

Returns NRF_EINVAL

if GNSS returned an error.

Returns NRF_EAGAIN

if out of memory.

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.

Note

This feature is only supported by modem firmware v1.3.0 or later.

Parameters

• prn_mask – [in] QZSS PRN mask.

Returns 0

on success.

Returns NRF_EPERM

if GNSS is running or not initialized.

Returns NRF_EINVAL

if GNSS returned an error.

Returns NRF_EAGAIN

if out of memory.

int32_t nrf_modem_gnss_start(void)

Starts GNSS.

Returns 0

on success.

Returns NRF_EPERM

if GNSS is running or not initialized.

Returns NRF_EINVAL

if GNSS returned an error.

Returns NRF_EAGAIN

if out of memory.

int32_t nrf_modem_gnss_stop(void)

Stops GNSS.

Returns 0

on success.

Returns NRF_EPERM

if GNSS is not running.

Returns NRF_EINVAL

if GNSS returned an error.

Returns NRF_EAGAIN

if out of memory.

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.

Returns 0

on success.

Returns NRF_EPERM

if GNSS is running or not initialized.

Returns NRF_EINVAL

if GNSS returned an error.

Returns NRF_EAGAIN

if out of memory.

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

Returns 0

on success.

Returns NRF_EPERM

if GNSS is not running.

Returns NRF_EINVAL

if GNSS returned an error.

Returns NRF_EAGAIN

if out of memory.

int32_t nrf_modem_gnss_prio_mode_disable(void)

Disables GNSS priority over LTE idle mode procedures.

Returns 0

on success.

Returns NRF_EPERM

if GNSS is not running.

Returns NRF_EINVAL

if GNSS returned an error.

Returns NRF_EAGAIN

if out of memory.

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

Note

This feature is only supported by modem firmware v1.3.0 or later.

Parameters

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

Returns 0

on success.

Returns NRF_EPERM

if GNSS is not running.

Returns NRF_EINVAL

if GNSS returned an error.

Returns NRF_EAGAIN

if out of memory.

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

This feature is only supported by modem firmware v1.3.0 or later.

Parameters

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

Returns 0

on success.

Returns NRF_EPERM

if GNSS is running or not initialized.

Returns NRF_EINVAL

if the config pointer is NULL or GNSS returned an error.

Returns NRF_EAGAIN

if out of memory.

int32_t nrf_modem_gnss_1pps_disable(void)

Disables 1PPS functionality.

Note

This feature is only supported by modem firmware v1.3.0 or later.

Returns 0

on success.

Returns NRF_EPERM

if GNSS is running or not initialized.

Returns NRF_EINVAL

if GNSS returned an error.

Returns NRF_EAGAIN

if out of memory.

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.

Returns 0

on success.

Returns NRF_EPERM

if GNSS is not running.

Returns NRF_EINVAL

if the selected data type don’t exist or supplied buffer is NULL.

Returns NRF_EMSGSIZE

if the buffer supplied by the application is too small for the selected data type.

Returns NRF_EIO

if there is no data to read for the selected data type.

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

Writes A-GPS data to GNSS.

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

Parameters

• buf – [in] Pointer to a buffer that contain A-GPS data.

• buf_len – [in] Length of the buffer.

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

Returns 0

on success.

Returns NRF_EINVAL

if the buffer supplied by the application is NULL, buffer length is 0 or the A-GPS data type doesn’t exist.

Returns NRF_EPERM

if GNSS is not initialized.

Returns NRF_EAGAIN

if out of memory.

Returns NRF_EIO

if the A-GPS data was not accepted by GNSS.

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

SV number 1…32 for GPS, 193…202 for QZSS.

uint8_t signal

Signal type. 0: invalid, 1: GPS L1C/A, 3: QZSS L1C/A, other values are reserved for other GNSSes or signals.

uint16_t cn0

0.1 dB/Hz.

int16_t elevation

SV elevation angle in degrees.

int16_t azimuth

SV 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

Accuracy (2D 1-sigma) in meters.

float speed

Horizontal speed in m/s.

float speed_accuracy

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

Note

Only valid with modem firmware v1.3.0 or later.

float heading

Heading of user movement 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 space vehicles used for the measurement.

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_agps_data_frame

#include <nrf_modem_gnss.h>

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

Public Members

uint32_t sv_mask_ephe

Bit mask indicating the satellite PRNs for which the assistance GPS ephemeris data is needed.

uint32_t sv_mask_alm

Bit mask indicating the satellite PRNs for which the assistance GPS almanac data is needed.

uint32_t data_flags

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

See A-GPS data request bitmask values.

struct nrf_modem_gnss_agps_data_utc

#include <nrf_modem_gnss.h>

A-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_agps_data_ephemeris

#include <nrf_modem_gnss.h>

A-GPS ephemeris data.

Public Members

uint8_t sv_id

Satellite ID (dimensionless). Range 1…32.

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_agps_data_almanac

#include <nrf_modem_gnss.h>

A-GPS almanac data.

Public Members

uint8_t sv_id

Satellite ID (dimensionless). Range 1…32.

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_agps_data_klobuchar

#include <nrf_modem_gnss.h>

A-GPS 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_agps_data_nequick

#include <nrf_modem_gnss.h>

A-GPS 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_agps_data_tow_element

#include <nrf_modem_gnss.h>

A-GPS TOW assistance data for a SV.

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_agps_data_system_time_and_sv_tow

#include <nrf_modem_gnss.h>

A-GPS system time and SV 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_agps_data_tow_element sv_tow[32]

TOW assistance data for SVs.

struct nrf_modem_gnss_agps_data_location

#include <nrf_modem_gnss.h>

A-GPS 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.

Note

Value 255 is only supported by modem firmware v1.3.0 or later.

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.

Note

Value 255 is only supported by modem firmware v1.3.0 or later.

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.

Note

Value 255 is only supported by modem firmware v1.3.0 or later.

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.

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.

NRF_MODEM_GNSS_EVT_NMEA

NMEA event.

Payload is of type nrf_modem_gnss_nmea_data_frame.

NRF_MODEM_GNSS_EVT_AGPS_REQ

Need new APGS data event.

Payload is of type nrf_modem_gnss_agps_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.

Note

This event is only supported by modem firmware v1.3.0 or later.

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.

Note

This event is only supported by modem firmware v1.3.0 or later.

NRF_MODEM_GNSS_EVT_SLEEP_AFTER_FIX

GNSS enters sleep because fix was achieved in periodic mode.

This event doesn’t have any payload.

Note

This event is only supported by modem firmware v1.3.0 or later.

NRF_MODEM_GNSS_EVT_REF_ALT_EXPIRED

Reference altitude for 3-satellite fix expired.

This event doesn’t have any payload.

Note

This event is only supported by modem firmware v1.3.0 or later.

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_AGPS_REQ

A-GPS request data.

Use this data type to read A-GPS request data using the nrf_modem_gnss_read function. New A-GPS request data is received when an NRF_MODEM_GNSS_EVT_AGPS_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 last PVT notification.

NRF_MODEM_GNSS_PVT_FLAG_DEADLINE_MISSED

Notification deadline was missed.

NRF_MODEM_GNSS_PVT_FLAG_NOT_ENOUGH_WINDOW_TIME

Operation is blocked by insufficient time windows.

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-GPS data request bitmask values

group nrf_modem_gnss_agps_data_bitmask

Bitmask values for the data_flags member in the nrf_modem_gnss_agps_data_frame.

Defines

NRF_MODEM_GNSS_AGPS_GPS_UTC_REQUEST

GPS UTC parameters assistance data.

NRF_MODEM_GNSS_AGPS_KLOBUCHAR_REQUEST

Klobuchar ionospheric correction parameters assistance data.

NRF_MODEM_GNSS_AGPS_NEQUICK_REQUEST

NeQuick ionospheric correction parameters assistance data.

NRF_MODEM_GNSS_AGPS_SYS_TIME_AND_SV_TOW_REQUEST

GPS system time and SV TOWs assistance data.

NRF_MODEM_GNSS_AGPS_POSITION_REQUEST

Position assistance parameters assistance data.

NRF_MODEM_GNSS_AGPS_INTEGRITY_REQUEST

Integrity assistance parameters assistance data.

A-GPS data types

group nrf_modem_gnss_agps_data_type

Use these values to indicate the type of A-GPS data written using nrf_modem_gnss_agps_write.

Defines

NRF_MODEM_GNSS_AGPS_UTC_PARAMETERS

GPS UTC assistance A-GPS parameters.

Data model nrf_modem_gnss_agps_data_utc.

NRF_MODEM_GNSS_AGPS_EPHEMERIDES

GPS ephemeris assistance A-GPS parameters.

Data model nrf_modem_gnss_agps_data_ephemeris.

NRF_MODEM_GNSS_AGPS_ALMANAC

GPS almanac assistance A-GPS parameters.

Data model nrf_modem_gnss_agps_data_almanac.

NRF_MODEM_GNSS_AGPS_KLOBUCHAR_IONOSPHERIC_CORRECTION

GPS ionospheric assistance A-GPS parameters, Klobuchar model.

Data model nrf_modem_gnss_agps_data_klobuchar.

NRF_MODEM_GNSS_AGPS_NEQUICK_IONOSPHERIC_CORRECTION

GPS ionospheric assistance A-GPS parameters, NeQuick model.

Data model nrf_modem_gnss_agps_data_nequick.

NRF_MODEM_GNSS_AGPS_GPS_SYSTEM_CLOCK_AND_TOWS

GPS system time and SV TOW assistance A-GPS parameter.

Data model nrf_modem_gnss_agps_data_system_time_and_sv_tow.

NRF_MODEM_GNSS_AGPS_LOCATION

GPS location assistance A-GPS parameters.

Data model nrf_modem_gnss_agps_data_location.

NRF_MODEM_GNSS_AGPS_INTEGRITY

GPS integrity assistance A-GPS parameters.

Data model nrf_modem_gnss_agps_data_integrity.

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

NRF_MODEM_GNSS_DELETE_ALMANACS

Almanac data (excluding leap second and ionospheric correction).

NRF_MODEM_GNSS_DELETE_IONO_CORRECTION_DATA

Ionospheric correction parameters data.

NRF_MODEM_GNSS_DELETE_LAST_GOOD_FIX

Last good fix (the last position) data.

NRF_MODEM_GNSS_DELETE_GPS_TOW

GPS time-of-week (TOW) data.

NRF_MODEM_GNSS_DELETE_GPS_WEEK

GPS week number data.

NRF_MODEM_GNSS_DELETE_UTC_DATA

Leap second (UTC parameters) data.

NRF_MODEM_GNSS_DELETE_TCXO_OFFSET

Local clock (TCXO) frequency offset data.

GNSS system bitmask values

group nrf_modem_gnss_system_bitmask

Use these bitmask values to enable different GNSS systems.

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

Defines

NRF_MODEM_GNSS_SYSTEM_GPS_MASK

Global Positioning System (GPS).

Note

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

NRF_MODEM_GNSS_SYSTEM_QZSS_MASK

Quasi-Zenith Satellite System (QZSS).

Note

Only supported by modem firmware v1.3.0 or later.

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.

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.

Defines

NRF_MODEM_GNSS_DYNAMICS_GENERAL_PURPOSE

General purpose mode.

NRF_MODEM_GNSS_DYNAMICS_STATIONARY

Optimize for stationary use case.

NRF_MODEM_GNSS_DYNAMICS_PEDESTRIAN

Optimize for pedestrian use case.

NRF_MODEM_GNSS_DYNAMICS_AUTOMOTIVE

Optimize for automotive use case.

OS specific definitions

group nrf_modem_os

Defines

NRF_MODEM_OS_NO_WAIT

Zero time-out.

NRF_MODEM_OS_FOREVER

Infinite time-out.

Functions

void nrf_modem_os_init(void)

Initialize the glue layer.

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

void*

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

void*

void nrf_modem_os_free(void *mem)

Free a memory buffer in the library heap.

Parameters

• mem – Buffer to free.

int32_t nrf_modem_os_timedwait(uint32_t context, int32_t *timeout)

void nrf_modem_os_errno_set(int errno_val)

Set errno.

Parameters

• errno_val – errno to set.

void nrf_modem_os_application_irq_set(void)

Set the application IRQ, NRF_MODEM_APPLICATION_IRQ.

void nrf_modem_os_application_irq_clear(void)

Clear the application IRQ, NRF_MODEM_APPLICATION_IRQ.

void nrf_modem_os_trace_irq_set(void)

Set the Trace IRQ.

void nrf_modem_os_trace_irq_clear(void)

Clear the Trace IRQ.

int32_t nrf_modem_os_trace_put(const uint8_t *data, uint32_t len)

Output Trace data from the trace buffer.

Parameters

• data – Memory buffer containing the output trace data.

• len – Memory buffer length.

Returns

int32_t 0 on success, an errno otherwise.

void nrf_modem_os_application_irq_handler(void)

Application IRQ handler in the modem library.

Call this function when handling the Application IRQ.

void nrf_modem_os_trace_irq_handler(void)

Trace IRQ handler in the modem library.

Call this function when handling the Trace IRQ.