nRF Cloud

The nRF Cloud library enables applications to connect to Nordic Semiconductor’s nRF Cloud. It abstracts and hides the details of the transport and the encoding scheme that is used for the payload and provides a simplified API interface for sending data to the cloud. The current implementation supports the following technologies:

• GNSS, TEMP, and other application-specific sensor data

• Cellular and Wi-Fi location data

• TLS-secured MQTT, TLS-secured REST, or DTLS-secured CoAP as the communication protocol

• JSON as the data format for MQTT and REST

• CBOR and JSON as the data format for CoAP

Note

The remainder of this document describes the nRF Cloud library’s MQTT connectivity support. See the nRF Cloud REST library and the nRF Cloud CoAP library for other connectivity options.

Initializing

Before using any other APIs of the module, the application must call the nrf_cloud_init() function. If this call fails, the application must not use any functions of the module.

Note

Initialize the module before starting any timers, sensor drivers, or communication on the link.

Connecting

The application can use the nrf_cloud_connect() function to connect to the cloud. This API triggers a series of events and actions in the system. If the API fails, the application must retry to connect.

If the CONFIG_NRF_CLOUD_CONNECTION_POLL_THREAD Kconfig option is not enabled, the application should monitor the connection socket. The nrf_cloud_connect() function blocks and returns success when the MQTT connection to the cloud completes.

If the CONFIG_NRF_CLOUD_CONNECTION_POLL_THREAD Kconfig option is enabled, an nRF Cloud library thread monitors the connection socket. The nrf_cloud_connect() function does not block and returns success if the connection monitoring thread has started.

When the CONFIG_NRF_CLOUD_CONNECTION_POLL_THREAD Kconfig option is enabled, an additional event, NRF_CLOUD_EVT_TRANSPORT_CONNECTING, is sent to the application. To adjust the stack size of the connection monitoring thread, set the CONFIG_NRF_CLOUD_CONNECTION_POLL_THREAD_STACK_SIZE Kconfig option. The NRF_CLOUD_EVT_TRANSPORT_CONNECT_ERROR event is sent if an error occurs while the transport connection is being established. The status field of the nrf_cloud_evt structure contains the reason for the error that is defined by nrf_cloud_connect_result. The NRF_CLOUD_EVT_TRANSPORT_DISCONNECTED event also contains additional information in the status field that is defined by nrf_cloud_disconnect_status.

First, the library tries to establish the transport for communicating with the cloud. This procedure involves a TLS handshake that might take up to three seconds. The API blocks for the duration of the handshake.

The cloud uses the certificates of the device for authentication. See Updating the nRF Cloud certificate and the Modem key management library for more information on modem credentials. The device ID is also the MQTT client ID. There are multiple configuration options for the device or client ID. See Configuration options for device ID for more information.

As the next step, the API subscribes to an MQTT topic to start receiving requests from the cloud.

Associating

This section applies to devices onboarding using JITP.

Every time nRF Cloud starts a communication session with a device, it verifies whether the device is uniquely associated with a user. If not, the user association procedure is triggered.

The following message sequence chart shows the flow of events and the expected application responses to each event during the user association procedure:

The chart shows the sequence of successful user association of an unassociated device.

Note

Currently, nRF Cloud requires that communication is re-established to update the device’s permission to send user data. The application must disconnect using the nrf_cloud_disconnect() function and then reconnect using nrf_cloud_connect().

When the device is successfully associated with a user on the cloud, subsequent connections to the cloud (also across power cycles) occur in the following sequence:

After receiving the NRF_CLOUD_EVT_READY event, the application can start sending sensor data to the cloud.

nRF Cloud onboarding options

You can add a device to an nRF Cloud account in the following three ways:

• Using the nRF Cloud device provisioning service and nRF Cloud Auto-onboarding: once the process completes, the device will be listed in your account.

• Using JITP with factory-installed certificates for Nordic development kits and Thingys: provide the device ID and PIN to nRF Cloud as indicated on the sticker.

• Using scripted provisioning and onboarding: upload the onboard.csv file to nRF Cloud’s Bulk Onboard screen or use the REST API.

See: the nRF Cloud Provisioning documentation and the Provisioning and onboarding section of the Cellular: nRF Cloud multi-service sample documentation for more information.

Configuration options for device ID

• CONFIG_NRF_CLOUD_CLIENT_ID_SRC_IMEI - If you enable this option, the ID is automatically generated using a prefix and the modem’s IMEI (<prefix><IMEI>). This is the default. You can configure the prefix by using CONFIG_NRF_CLOUD_CLIENT_ID_PREFIX. The default format of the prefix is nrf- and it is valid only for Nordic devices such as Thingy:91 or an nRF91 Series DK. For custom hardware, use a prefix other than nrf- by modifying CONFIG_NRF_CLOUD_CLIENT_ID_PREFIX.

• CONFIG_NRF_CLOUD_CLIENT_ID_SRC_INTERNAL_UUID - If you enable this option, the ID is automatically generated using the modem’s 128-bit internal UUID, which results in a 36 character string of hexadecimal values in the 8-4-4-4-12 UUID format.

  • This option requires modem firmware v1.3.0 or higher.

  • This option is required when using auto-onboarding.

  • This option only takes effect if the CONFIG_MODEM_JWT Kconfig option is also enabled. If the CONFIG_MODEM_JWT Kconfig option is not set to y, the default CONFIG_NRF_CLOUD_CLIENT_ID_SRC_IMEI Kconfig option will be selected instead.

• CONFIG_NRF_CLOUD_CLIENT_ID_SRC_COMPILE_TIME - If you enable this option, the ID is set at compile time using the value specified by CONFIG_NRF_CLOUD_CLIENT_ID.

• CONFIG_NRF_CLOUD_CLIENT_ID_SRC_HW_ID - If you enable this option, the ID is automatically generated using a unique hardware ID (for example, a MAC address). You can choose the required hardware ID using the HW_ID_LIBRARY_SOURCE Kconfig choice.

• CONFIG_NRF_CLOUD_CLIENT_ID_SRC_RUNTIME - If you enable this option, the ID is set at runtime. If the nRF Cloud library is used directly, set the NULL-terminated ID string in the nrf_cloud_init_param structure when calling the nrf_cloud_init() function.

Firmware over-the-air (FOTA) updates

The nRF Cloud library supports FOTA updates for your nRF91 Series device. The CONFIG_NRF_CLOUD_FOTA Kconfig option is enabled by default when CONFIG_NRF_CLOUD_MQTT is set. This enables FOTA functionality in the application.

nRF Cloud FOTA enables the following additional features and libraries:

• CONFIG_FOTA_DOWNLOAD enables FOTA download

• CONFIG_DFU_TARGET enables DFU target

• CONFIG_DOWNLOAD_CLIENT enables Download client

• CONFIG_FOTA_DOWNLOAD_PROGRESS_EVT

• CONFIG_FOTA_PROGRESS_EVT_INCREMENT

• CONFIG_REBOOT

• CONFIG_CJSON_LIB

• CONFIG_SETTINGS

For FOTA updates to work, the device must provide the information about the supported FOTA types to nRF Cloud. The device passes this information by writing a fota_v2 field containing an array of FOTA types into the serviceInfo field in the device’s shadow. The nrf_cloud_service_info_json_encode() function can be used to generate the proper JSON data to enable FOTA. Additionally, the nrf_cloud_shadow_device_status_update() function can be used to generate the JSON data and perform the shadow update.

Following are the supported FOTA types:

• "APP" - Updates the application.

• "BOOT" - Updates the Second-stage upgradable bootloader.

• "MDM_FULL" - Full modem FOTA updates the entire modem firmware image. Full modem updates require external flash memory with minimum 4 MB of available space. For an nRF91 Series device, a full modem firmware image is approximately 2 MB. Consider the power and network costs before deploying full modem FOTA updates.

• "MODEM" - Delta modem FOTA applies incremental changes between specific versions of the modem firmware. Delta modem updates are much smaller in size and do not require external memory.

For example, a device that supports all the FOTA types writes the following data into the device shadow:

{
"state": {
   "reported": {
      "device": {
         "serviceInfo": {
            "fota_v2": [
            "APP",
            "MODEM",
            "MDM_FULL",
            "BOOT"
            ]
}}}}}

You can initiate FOTA updates through nRF Cloud or by using the nRF Cloud REST API (v1). If the CONFIG_NRF_CLOUD_FOTA Kconfig option is enabled, FOTA update job information is requested by the device after the MQTT connection to nRF Cloud is completed. The CONFIG_NRF_CLOUD_FOTA_AUTO_START_JOB Kconfig option controls how FOTA jobs are started on the device.

• If enabled, the nRF Cloud library starts the FOTA update job immediately upon receipt of the FOTA update job information from nRF Cloud. If the job is successfully started, the library sends the NRF_CLOUD_EVT_FOTA_START event to the application.

• If disabled, the NRF_CLOUD_EVT_FOTA_JOB_AVAILABLE event is sent to the application. When the application is ready to start the FOTA update job it must call the nrf_cloud_fota_job_start() function.

The FOTA update is in progress until the application receives either the NRF_CLOUD_EVT_FOTA_DONE or NRF_CLOUD_EVT_FOTA_ERROR event. When receiving the NRF_CLOUD_EVT_FOTA_DONE event, the application must perform any necessary cleanup and reboot the device to complete the update. The message payload of the NRF_CLOUD_EVT_FOTA_DONE event contains the nrf_cloud_fota_type value. If the value equals NRF_CLOUD_FOTA_MODEM_DELTA, the application can optionally avoid a reboot by reinitializing the modem library and then calling the nrf_cloud_modem_fota_completed() function.

See nRF Cloud FOTA for details on the FOTA service in nRF Cloud. See nRF Cloud MQTT FOTA for MQTT-specific FOTA details such as topics and payload formats.

Building FOTA images

The build system will create the files dfu_application.zip or dfu_mcuboot.zip (or both) for a properly configured application. See Output build files (image files) for more information about FOTA zip files.

When you use the files dfu_application.zip or dfu_mcuboot.zip to create an update bundle, the nRF Cloud UI populates the Name and Version fields from the manifest.json file contained within. However, you are free to change them as needed. The UI populates the Version field from only the nRF Connect SDK version field in the manifest.json file.

Alternatively, you can use the app_update.bin file to create an update bundle, but you need to enter the Name and Version fields manually. See nRF Cloud Getting Started FOTA documentation to learn how to create an update bundle.

Modem firmware is controlled by Nordic Semiconductor. A user cannot build or upload modem firmware images. Modem FOTA update bundles (full and delta) are automatically uploaded to nRF Cloud and are available to all users.

Sending sensor data

The library offers two functions, nrf_cloud_sensor_data_send() and nrf_cloud_sensor_data_stream() (lowest QoS), for sending sensor data to the cloud.

Removing the link between device and user

If you want to remove the link between a device and an nRF Cloud account, you must do this from nRF Cloud. A device cannot remove itself from an nRF Cloud account.

Location services

nRF Cloud offers location services that allow you to obtain the location of your device. The following enhancements to this library can be used to interact with nRF Cloud Location Services:

• Assisted GNSS - nRF Cloud A-GNSS

• Predicted GPS - nRF Cloud P-GPS

• Cellular Positioning - nRF Cloud location

• nRF Cloud REST - nRF Cloud REST

API documentation

Header file: include/net/nrf_cloud.h

Source files: subsys/net/lib/nrf_cloud/src/

group nrf_cloud

Defines

NCT_MSG_ID_USE_NEXT_INCREMENT

MQTT message ID: not specified, use next incremented value

NCT_MSG_ID_CC_SUB

MQTT message ID: subscribe to control channel topics

NCT_MSG_ID_DC_SUB

MQTT message ID: subscribe to data channel topics

NCT_MSG_ID_FOTA_SUB

MQTT message ID: subscribe to FOTA topics

NCT_MSG_ID_CC_UNSUB

MQTT message ID: unsubscribe from control channel topics

NCT_MSG_ID_DC_UNSUB

MQTT message ID: unsubscribe from data channel topics

NCT_MSG_ID_FOTA_UNSUB

MQTT message ID: unsubscribe from FOTA topics

NCT_MSG_ID_STATE_REQUEST

MQTT message ID: request device state (shadow)

NCT_MSG_ID_FOTA_REQUEST

MQTT message ID: request FOTA job

NCT_MSG_ID_FOTA_BLE_REQUEST

MQTT message ID: request BLE FOTA job

NCT_MSG_ID_STATE_REPORT

MQTT message ID: update device state (shadow)

NCT_MSG_ID_PAIR_STATUS_REPORT

MQTT message ID: set pairing/associated state

NCT_MSG_ID_FOTA_REPORT

MQTT message ID: update FOTA job status

NCT_MSG_ID_FOTA_BLE_REPORT

MQTT message ID: update BLE FOTA job status

NCT_MSG_ID_INCREMENT_BEGIN

MQTT message ID: Start of incrementing range

NCT_MSG_ID_INCREMENT_END

MQTT message ID: End of incrementing range

NCT_MSG_ID_USER_TAG_BEGIN

MQTT message ID: Start of user specified (custom) range

NCT_MSG_ID_USER_TAG_END

MQTT message ID: End of user specified (custom) range

IS_VALID_USER_TAG(tag)

Determine if an MQTT message ID is a user specified tag to be used for ACK matching

NRF_CLOUD_JWT_VALID_TIME_S_MAX

Maximum valid duration for JWTs generated by nrf_cloud_jwt_generate

NRF_CLOUD_JWT_VALID_TIME_S_DEF

Default valid duration for JWTs generated by nrf_cloud_jwt_generate

NRF_CLOUD_NO_TIMESTAMP

Value used to disable sending a timestamp. Timestamps are in UNIX epoch format.

NRF_CLOUD_FOTA_JOB_ID_SIZE

Size of nRF Cloud FOTA job ID; version 4 UUID: 32 bytes, 4 hyphens, NULL

Typedefs

typedef void (*nrf_cloud_event_handler_t)(const struct nrf_cloud_evt *evt)

Event handler registered with the module to handle asynchronous events from the module.

Param evt:

[in] The event and any associated parameters.

Enums

enum nrf_cloud_evt_type

Asynchronous nRF Cloud events notified by the module.

Values:

enumerator NRF_CLOUD_EVT_TRANSPORT_CONNECTED

The transport to the nRF Cloud is established.

enumerator NRF_CLOUD_EVT_TRANSPORT_CONNECTING

In the process of connecting to nRF Cloud.

enumerator NRF_CLOUD_EVT_USER_ASSOCIATION_REQUEST

There was a request from nRF Cloud to associate the device with a user on the nRF Cloud.

enumerator NRF_CLOUD_EVT_USER_ASSOCIATED

The device is successfully associated with a user.

enumerator NRF_CLOUD_EVT_READY

The device can now start sending sensor data to the cloud.

enumerator NRF_CLOUD_EVT_RX_DATA_GENERAL

The device received non-specific data from the cloud.

enumerator NRF_CLOUD_EVT_RX_DATA_LOCATION

The device received location data from the cloud and no response callback was registered.

enumerator NRF_CLOUD_EVT_RX_DATA_SHADOW

The device received shadow related data from the cloud.

enumerator NRF_CLOUD_EVT_PINGRESP

The device has received a ping response from the cloud.

enumerator NRF_CLOUD_EVT_SENSOR_DATA_ACK

The data sent to the cloud was acknowledged.

enumerator NRF_CLOUD_EVT_TRANSPORT_DISCONNECTED

The transport was disconnected. The status field in the event struct will be populated with a nrf_cloud_disconnect_status value.

enumerator NRF_CLOUD_EVT_FOTA_START

A FOTA update has started. This event is only sent if CONFIG_NRF_CLOUD_FOTA_AUTO_START_JOB is enabled.

enumerator NRF_CLOUD_EVT_FOTA_DONE

The device should be restarted to apply a firmware upgrade

enumerator NRF_CLOUD_EVT_FOTA_ERROR

An error occurred during the FOTA update.

enumerator NRF_CLOUD_EVT_TRANSPORT_CONNECT_ERROR

An error occurred when connecting to the nRF Cloud. The status field in the event struct will be populated with a nrf_cloud_connect_result value.

enumerator NRF_CLOUD_EVT_FOTA_JOB_AVAILABLE

FOTA update job information has been received. When ready, the application should start the job by calling nrf_cloud_fota_job_start. This event is only sent if CONFIG_NRF_CLOUD_FOTA_AUTO_START_JOB is disabled.

enumerator NRF_CLOUD_EVT_ERROR

An error occurred. The status field in the event struct will be populated with a nrf_cloud_error_status value.

enum nrf_cloud_error_status

nRF Cloud error status, used to describe NRF_CLOUD_EVT_ERROR event.

Values:

enumerator NRF_CLOUD_ERR_STATUS_NONE

No error

enumerator NRF_CLOUD_ERR_STATUS_MQTT_CONN_FAIL

MQTT connection failed

enumerator NRF_CLOUD_ERR_STATUS_MQTT_CONN_BAD_PROT_VER

MQTT protocol version not supported by server

enumerator NRF_CLOUD_ERR_STATUS_MQTT_CONN_ID_REJECTED

MQTT client identifier rejected by server

enumerator NRF_CLOUD_ERR_STATUS_MQTT_CONN_SERVER_UNAVAIL

MQTT service is unavailable

enumerator NRF_CLOUD_ERR_STATUS_MQTT_CONN_BAD_USR_PWD

Malformed user name or password

enumerator NRF_CLOUD_ERR_STATUS_MQTT_CONN_NOT_AUTH

Client is not authorized to connect

enumerator NRF_CLOUD_ERR_STATUS_MQTT_SUB_FAIL

Failed to subscribe to MQTT topic

enumerator NRF_CLOUD_ERR_STATUS_AGNSS_PROC

Error processing A-GNSS data

enumerator NRF_CLOUD_ERR_STATUS_PGPS_PROC

Error processing P-GPS data

enum nrf_cloud_disconnect_status

nRF Cloud disconnect status, used to describe NRF_CLOUD_EVT_TRANSPORT_DISCONNECTED event.

Values:

enumerator NRF_CLOUD_DISCONNECT_USER_REQUEST

Disconnect was requested by user/application

enumerator NRF_CLOUD_DISCONNECT_CLOSED_BY_REMOTE

Disconnect was caused by the cloud

enumerator NRF_CLOUD_DISCONNECT_INVALID_REQUEST

Socket received POLLNVAL event

enumerator NRF_CLOUD_DISCONNECT_MISC

Socket poll returned an error value or POLLERR event

enum nrf_cloud_connect_result

nRF Cloud connect result. Used as return value for nrf_cloud_connect() and to describe NRF_CLOUD_EVT_TRANSPORT_CONNECT_ERROR event.

Values:

enumerator NRF_CLOUD_CONNECT_RES_SUCCESS

The connection was successful

enumerator NRF_CLOUD_CONNECT_RES_ERR_NOT_INITD

The library is not initialized; nrf_cloud_init

enumerator NRF_CLOUD_CONNECT_RES_ERR_NETWORK

A network error ocurred

enumerator NRF_CLOUD_CONNECT_RES_ERR_BACKEND

A connection error occurred relating to the nRF Cloud backend

enumerator NRF_CLOUD_CONNECT_RES_ERR_MISC

The connection failed due to an indeterminate reason

enumerator NRF_CLOUD_CONNECT_RES_ERR_NO_MEM

Insufficient memory is available

enumerator NRF_CLOUD_CONNECT_RES_ERR_PRV_KEY

Invalid private key

enumerator NRF_CLOUD_CONNECT_RES_ERR_CERT

Invalid CA or client cert

enumerator NRF_CLOUD_CONNECT_RES_ERR_CERT_MISC

Other cert issue

enumerator NRF_CLOUD_CONNECT_RES_ERR_TIMEOUT_NO_DATA

Timeout, SIM card may be out of data

enumerator NRF_CLOUD_CONNECT_RES_ERR_ALREADY_CONNECTED

The connection exists

enum nrf_cloud_error

nRF Cloud error codes. See the Error Codes section of nRF Cloud API documentation for more information.

Values:

enumerator NRF_CLOUD_ERROR_UNKNOWN

enumerator NRF_CLOUD_ERROR_NONE

enumerator NRF_CLOUD_ERROR_BAD_REQUEST

enumerator NRF_CLOUD_ERROR_INVALID_CERT

enumerator NRF_CLOUD_ERROR_DISSOCIATE

enumerator NRF_CLOUD_ERROR_ACCESS_DENIED

enumerator NRF_CLOUD_ERROR_DEV_ID_IN_USE

enumerator NRF_CLOUD_ERROR_INVALID_OWNER_CODE

enumerator NRF_CLOUD_ERROR_DEV_NOT_ASSOCIATED

enumerator NRF_CLOUD_ERROR_DATA_NOT_FOUND

enumerator NRF_CLOUD_ERROR_NRF_DEV_NOT_FOUND

enumerator NRF_CLOUD_ERROR_NO_DEV_NOT_PROV

enumerator NRF_CLOUD_ERROR_NO_DEV_DISSOCIATE

enumerator NRF_CLOUD_ERROR_NO_DEV_DELETE

enumerator NRF_CLOUD_ERROR_NOT_FOUND_NO_ERROR

enumerator NRF_CLOUD_ERROR_BAD_RANGE

enumerator NRF_CLOUD_ERROR_VALIDATION

enumerator NRF_CLOUD_ERROR_INTERNAL_SERVER

enum nrf_cloud_sensor

Sensor types supported by the nRF Cloud.

Values:

enumerator NRF_CLOUD_SENSOR_GNSS

The GNSS sensor on the device.

enumerator NRF_CLOUD_SENSOR_FLIP

The FLIP movement sensor on the device.

enumerator NRF_CLOUD_SENSOR_BUTTON

The Button press sensor on the device.

enumerator NRF_CLOUD_SENSOR_TEMP

The TEMP sensor on the device.

enumerator NRF_CLOUD_SENSOR_HUMID

The Humidity sensor on the device.

enumerator NRF_CLOUD_SENSOR_AIR_PRESS

The Air Pressure sensor on the device.

enumerator NRF_CLOUD_SENSOR_AIR_QUAL

The Air Quality sensor on the device.

enumerator NRF_CLOUD_LTE_LINK_RSRP

The RSPR data obtained from the modem.

enumerator NRF_CLOUD_LOG

Log messages generated on the device.

enumerator NRF_CLOUD_DICTIONARY_LOG

Log messages generated on the device in dictionary (binary) format.

enumerator NRF_CLOUD_DEVICE_INFO

The descriptive DEVICE data indicating its status.

enumerator NRF_CLOUD_SENSOR_LIGHT

The light sensor on the device.

enum nrf_cloud_topic_type

Topic types supported by nRF Cloud.

Values:

enumerator NRF_CLOUD_TOPIC_STATE

Endpoint used to update the cloud-side device shadow state .

enumerator NRF_CLOUD_TOPIC_MESSAGE

Endpoint used to directly message the nRF Cloud Web UI.

enumerator NRF_CLOUD_TOPIC_BULK

Endpoint used to publish bulk messages to nRF Cloud. Bulk messages combine multiple messages into a single message that will be unwrapped and re-published to the message topic in the nRF Cloud backend.

enumerator NRF_CLOUD_TOPIC_BIN

Endpoint used to publish binary data to nRF Cloud for certain services. One example is dictionary formatted logs enabled by CONFIG_LOG_BACKEND_NRF_CLOUD_OUTPUT_DICTIONARY , which enables the Zephyr option CONFIG_LOG_DICTIONARY_SUPPORT . Binary data published to this topic should be prefixed by the binary header structure defined in nrf_cloud_codec.h - struct nrf_cloud_bin_hdr. A unique format value should be included to distinguish this data from binary logging.

enum nrf_cloud_fota_status

FOTA status reported to nRF Cloud.

Values:

enumerator NRF_CLOUD_FOTA_QUEUED

enumerator NRF_CLOUD_FOTA_IN_PROGRESS

enumerator NRF_CLOUD_FOTA_FAILED

enumerator NRF_CLOUD_FOTA_SUCCEEDED

enumerator NRF_CLOUD_FOTA_TIMED_OUT

enumerator NRF_CLOUD_FOTA_CANCELED

enumerator NRF_CLOUD_FOTA_REJECTED

enumerator NRF_CLOUD_FOTA_DOWNLOADING

enum nrf_cloud_fota_type

FOTA update type.

Values:

enumerator NRF_CLOUD_FOTA_TYPE__FIRST

enumerator NRF_CLOUD_FOTA_APPLICATION

Application update.

enumerator NRF_CLOUD_FOTA_MODEM_DELTA

Delta modem update

enumerator NRF_CLOUD_FOTA_BOOTLOADER

Bootloader update.

enumerator NRF_CLOUD_FOTA_MODEM_FULL

Full modem update

enumerator NRF_CLOUD_FOTA_TYPE__INVALID

enum nrf_cloud_fota_validate_status

Validity of an in-progress/installed FOTA update.

Values:

enumerator NRF_CLOUD_FOTA_VALIDATE_NONE

No FOTA update in progress

enumerator NRF_CLOUD_FOTA_VALIDATE_PENDING

The FOTA update has not yet been validated

enumerator NRF_CLOUD_FOTA_VALIDATE_PASS

Validation succeeded

enumerator NRF_CLOUD_FOTA_VALIDATE_FAIL

Validation failed

enumerator NRF_CLOUD_FOTA_VALIDATE_UNKNOWN

Validation result could not be determined

enumerator NRF_CLOUD_FOTA_VALIDATE_DONE

The validation process is finished

enumerator NRF_CLOUD_FOTA_VALIDATE_ERROR

An error occurred before validation

enum nrf_cloud_fota_bootloader_status_flags

Status flags for tracking the update process of the b1 bootloader (MCUBOOT)

Values:

enumerator NRF_CLOUD_FOTA_BL_STATUS_CLEAR

Initial state

enumerator NRF_CLOUD_FOTA_BL_STATUS_S0_FLAG_SET

Indicates if the NRF_CLOUD_FOTA_BL_STATUS_S0_WAS_ACTIVE flag has been updated

enumerator NRF_CLOUD_FOTA_BL_STATUS_S0_WAS_ACTIVE

Indicates if slot 0 was active prior to the update

enumerator NRF_CLOUD_FOTA_BL_STATUS_REBOOTED

Indicates if the planned reboot has occurred during the update install process

enum nrf_cloud_shadow_info

How the info sections are handled when encoding shadow data.

Values:

enumerator NRF_CLOUD_INFO_NO_CHANGE

Data will not be modified

enumerator NRF_CLOUD_INFO_SET

Data will be set/updated

enumerator NRF_CLOUD_INFO_CLEAR

Data section will be cleared

enum nrf_cloud_gnss_type

GNSS data type contained in nrf_cloud_gnss_data.

Values:

enumerator NRF_CLOUD_GNSS_TYPE_INVALID

Invalid data type

enumerator NRF_CLOUD_GNSS_TYPE_PVT

Specifies a data type of nrf_cloud_gnss_pvt

enumerator NRF_CLOUD_GNSS_TYPE_NMEA

Specifies a data type of nrf_cloud_gnss_nmea

enumerator NRF_CLOUD_GNSS_TYPE_MODEM_PVT

Specifies a data type of nrf_modem_gnss_pvt_data_frame

enumerator NRF_CLOUD_GNSS_TYPE_MODEM_NMEA

Specifies a data type of nrf_modem_gnss_nmea_data_frame

Functions

int nrf_cloud_init(const struct nrf_cloud_init_param *param)

Initialize the module.

Note

This API must be called prior to using nRF Cloud and it must return successfully.

Parameters:

• param – [in] Initialization parameters.

Return values:

• 0 – If successful.

• -EACCES – Already initialized or nrf_cloud_uninit is in progress.

Returns:

A negative value indicates an error.

int nrf_cloud_uninit(void)

Uninitialize nRF Cloud; disconnects cloud connection and cleans up allocated memory.

Note

If nRF Cloud FOTA is enabled and a FOTA job is active uninit will not be performed.

Note

This function is solely intended to allow this library to be deactivated when no longer needed. You can recover from any error state you may encounter without calling this function. See nrf_cloud_disconnect for a way to reset the nRF Cloud connection state without uninitializing the whole library.

Return values:

• 0 – If successful.

• -EBUSY – If a FOTA job is in progress.

• -EISCONN – If the expected disconnect event did not occur.

• -ETIME – If CONFIG_NRF_CLOUD_CONNECTION_POLL_THREAD is enabled and the connection poll thread did not become inactive.

Returns:

A negative value indicates an error.

int nrf_cloud_connect(void)

Connect to the cloud.

The NRF_CLOUD_EVT_TRANSPORT_CONNECTED event indicates that the cloud connection has been established. In any stage of connecting to the cloud, an NRF_CLOUD_EVT_ERROR might be received. If it is received before NRF_CLOUD_EVT_TRANSPORT_CONNECTED, the application may repeat the call to nrf_cloud_connect to try again.

Return values:

Connect – result defined by enum nrf_cloud_connect_result.

int nrf_cloud_sensor_data_send(const struct nrf_cloud_sensor_data *param)

Send sensor data reliably.

This API should only be called after receiving an NRF_CLOUD_EVT_READY event. If the API succeeds, you can expect the NRF_CLOUD_EVT_SENSOR_DATA_ACK event for data sent with a valid tag value.

Parameters:

• param – [in] Sensor data; the data pointed to by param->data.ptr must be a string.

Return values:

• 0 – If successful.

• -EACCES – Cloud connection is not established; wait for NRF_CLOUD_EVT_READY.

Returns:

A negative value indicates an error.

int nrf_cloud_shadow_device_status_update(const struct nrf_cloud_device_status *const dev_status)

Update the device status in the shadow.

Parameters:

• dev_status – [in] Device status to be encoded.

Return values:

• 0 – If successful.

• -EACCES – Cloud connection is not established; wait for NRF_CLOUD_EVT_READY.

Returns:

A negative value indicates an error.

int nrf_cloud_sensor_data_stream(const struct nrf_cloud_sensor_data *param)

Stream sensor data. Uses lowest QoS; no acknowledgment,.

This API should only be called after receiving an NRF_CLOUD_EVT_READY event.

Parameters:

• param – [in] Sensor data; tag value is ignored.

Return values:

• 0 – If successful.

• -EACCES – Cloud connection is not established; wait for NRF_CLOUD_EVT_READY.

Returns:

A negative value indicates an error.

int nrf_cloud_send(const struct nrf_cloud_tx_data *msg)

Send data to nRF Cloud.

This API is used for sending data to nRF Cloud.

Parameters:

• msg – [in] Pointer to a structure containing data and topic information.

Return values:

• 0 – If successful.

• -EACCES – Cloud connection is not established; wait for NRF_CLOUD_EVT_READY.

• -EIO – Error; failed to encode data.

Returns:

A negative value indicates an error.

int nrf_cloud_obj_shadow_update(struct nrf_cloud_obj *const shadow_obj)

Update the device’s shadow with the data from the provided object.

Parameters:

• shadow_obj – [in] Object containing data to be written to the device’s shadow.

Return values:

• 0 – If successful.

• -EINVAL – Error; invalid parameter.

• -EACCES – Cloud connection is not established; wait for NRF_CLOUD_EVT_READY.

• -EIO – Error; failed to encode data.

Returns:

A negative value indicates an error.

int nrf_cloud_disconnect(void)

Disconnect from the cloud.

This API may be called any time after receiving the NRF_CLOUD_EVT_TRANSPORT_CONNECTED event. The NRF_CLOUD_EVT_TRANSPORT_DISCONNECTED event indicates that the disconnect has completed successfully.

Return values:

• 0 – If successful.

• -EACCES – Cloud connection is not established; wait for NRF_CLOUD_EVT_TRANSPORT_CONNECTED.

Returns:

A negative value indicates an error.

int nrf_cloud_process(void)

Function that must be called periodically to keep the module functional.

Return values:

0 – If successful.

Returns:

A negative value indicates an error.

int nrf_cloud_modem_fota_completed(const bool fota_success)

The application has handled reinit after a modem FOTA update and the LTE link has been reestablished. This function must be called in order to complete the modem update. Depends on.

CONFIG_NRF_CLOUD_FOTA .

Parameters:

• fota_success – [in] true if modem update was successful, false otherwise.

Return values:

0 – If successful.

Returns:

A negative value indicates an error.

int nrf_cloud_client_id_get(char *id_buf, size_t id_len)

Retrieve the current device ID.

Parameters:

• id_buf – [inout] Buffer to receive the device ID.

• id_len – [in] Size of buffer (NRF_CLOUD_CLIENT_ID_MAX_LEN).

Return values:

0 – If successful.

Returns:

A negative value indicates an error.

int nrf_cloud_tenant_id_get(char *id_buf, size_t id_len)

Retrieve the current customer tenant ID.

Parameters:

• id_buf – [inout] Buffer to receive the tenant ID.

• id_len – [in] Size of buffer (NRF_CLOUD_TENANT_ID_MAX_LEN).

Return values:

0 – If successful.

Returns:

A negative value indicates an error.

int nrf_cloud_jwt_generate(uint32_t time_valid_s, char *const jwt_buf, size_t jwt_buf_sz)

Generate a JWT to be used with nRF Cloud’s REST API. This library’s configured values for client id and sec tag (NRF_CLOUD_SEC_TAG) will be used for generating the JWT.

Parameters:

• time_valid_s – [in] How long (seconds) the JWT will be valid. Maximum duration specified by NRF_CLOUD_JWT_VALID_TIME_S_MAX. If zero, NRF_CLOUD_JWT_VALID_TIME_S_DEF will be used.

• jwt_buf – [inout] Buffer to hold the JWT.

• jwt_buf_sz – [in] Size of the buffer (recommended size >= 600 bytes).

Return values:

• 0 – JWT generated successfully.

• -ETIME – Modem does not have valid date/time, JWT not generated.

Returns:

A negative value indicates an error.

int nrf_cloud_pending_fota_job_process(struct nrf_cloud_settings_fota_job *const job, bool *const reboot_required)

Process/validate a pending FOTA update job. Typically the job information is read from non-volatile storage on startup. This function is intended to be used by custom REST-based FOTA implementations. It is called internally if.

CONFIG_NRF_CLOUD_FOTA is enabled. For pending NRF_CLOUD_FOTA_MODEM_DELTA jobs the modem library must be initialized before calling this function, otherwise the job will be marked as completed without validation.

Parameters:

• job – [in] FOTA job state information.

• reboot_required – [out] A reboot is needed to complete a FOTA update.

Return values:

• 0 – A Pending FOTA job has been processed.

• -ENODEV – No pending/unvalidated FOTA job exists.

• -ENOENT – Error; unknown FOTA job type.

• -ESRCH – Error; not configured for FOTA job type.

int nrf_cloud_bootloader_fota_slot_set(struct nrf_cloud_settings_fota_job *const job)

Set the active bootloader (B1) slot flag which is needed to validate a bootloader FOTA update. For proper functionality,.

CONFIG_FOTA_DOWNLOAD must be enabled.

Parameters:

• job – [inout] FOTA job state information.

Return values:

0 – Flag set successfully or not a bootloader FOTA update.

Returns:

A negative value indicates an error.

int nrf_cloud_fota_pending_job_type_get(enum nrf_cloud_fota_type *const pending_fota_type)

Retrieve the FOTA type of a pending FOTA job. A value of NRF_CLOUD_FOTA_TYPE__INVALID indicates that there are no pending FOTA jobs. Depends on.

CONFIG_NRF_CLOUD_FOTA .

Parameters:

• pending_fota_type – [out] FOTA type of pending job.

Return values:

• 0 – FOTA type was retrieved.

• -EINVAL – Error; invalid parameter.

Returns:

A negative value indicates an error.

int nrf_cloud_fota_pending_job_validate(enum nrf_cloud_fota_type *const fota_type_out)

Validate a pending FOTA installation before initializing this library. This function enables the application to control the reboot/reinit process during FOTA updates. If this function is not called directly by the application, it will be called internally when nrf_cloud_init is executed. For pending NRF_CLOUD_FOTA_MODEM_DELTA jobs the modem library must be initialized before calling this function, otherwise the job will be marked as completed without validation. Depends on.

CONFIG_NRF_CLOUD_FOTA .

Parameters:

• fota_type_out – [out] FOTA type of pending job. NRF_CLOUD_FOTA_TYPE__INVALID if no pending job. Can be NULL.

Return values:

• 0 – Pending FOTA job processed.

• 1 – Pending FOTA job processed and requires the application to perform a reboot or, for modem FOTA types, reinitialization of the modem library.

• -ENODEV – No pending/unvalidated FOTA job exists.

• -EIO – Error; failed to load FOTA job info from settings module.

• -ENOENT – Error; unknown FOTA job type.

int nrf_cloud_fota_fmfu_dev_set(const struct dfu_target_fmfu_fdev *const fmfu_dev_inf)

Set the flash device used for full modem FOTA updates. This function is intended to be used by custom REST-based FOTA implementations. It is called internally when nrf_cloud_init is executed if.

CONFIG_NRF_CLOUD_FOTA is enabled. It can be called before nrf_cloud_init if required by the application.

Parameters:

• fmfu_dev_inf – [in] Flash device information.

Return values:

• 0 – Flash device was successfully set.

• 1 – Flash device has already been set.

Returns:

A negative value indicates an error.

int nrf_cloud_fota_fmfu_apply(void)

Install a full modem update from flash. If successful, reboot the device or reinit the modem to complete the update. This function is intended to be used by custom REST-based FOTA implementations. If.

CONFIG_NRF_CLOUD_FOTA is enabled, call nrf_cloud_fota_pending_job_validate to install a downloaded NRF_CLOUD_FOTA_MODEM_FULL update after the NRF_CLOUD_EVT_FOTA_DONE event is received. Depends on CONFIG_NRF_CLOUD_FOTA_FULL_MODEM_UPDATE .

Return values:

• 0 – Modem update installed successfully.

• -EACCES – Flash device not set; see nrf_cloud_fota_fmfu_dev_set or nrf_cloud_init.

Returns:

A negative value indicates an error. Modem update not installed.

bool nrf_cloud_fota_is_type_modem(const enum nrf_cloud_fota_type type)

Determine if FOTA type is modem related.

Returns:

true if FOTA is modem type, otherwise false.

bool nrf_cloud_fota_is_type_enabled(const enum nrf_cloud_fota_type type)

Determine if the specified FOTA type is enabled by the configuration. This function returns false if both.

CONFIG_NRF_CLOUD_FOTA and CONFIG_NRF_CLOUD_REST are disabled. REST-based applications are responsible for implementing FOTA updates for all configured types.

Parameters:

• type – [in] Fota type.

Return values:

• true – Specified FOTA type is enabled by the configuration.

• false – Specified FOTA type is not enabled by the configuration.

int nrf_cloud_fota_job_start(void)

Start the FOTA update job. This function should be called after the NRF_CLOUD_EVT_FOTA_JOB_AVAILABLE event is received. This function should only be called if.

CONFIG_NRF_CLOUD_FOTA_AUTO_START_JOB is disabled. Depends on CONFIG_NRF_CLOUD_FOTA .

Return values:

• 0 – FOTA update job started successfully.

• -ENOTSUP – Error; CONFIG_NRF_CLOUD_FOTA_AUTO_START_JOB is enabled.

• -ENOENT – Error; FOTA update job information has not been received.

• -EINPROGRESS – Error; a FOTA update job is in progress.

• -EPIPE – Error; failed to start FOTA download.

Returns:

A negative value indicates an error starting the job.

int nrf_cloud_credentials_check(struct nrf_cloud_credentials_status *const cs)

Check if credentials exist in the configured location.

Parameters:

• cs – [out] Results of credentials check.

Return values:

• 0 – Successfully obtained status of credentials.

• -EIO – Error checking if credential exists.

• -EINVAL – Error; invalid parameter.

Returns:

A negative value indicates an error.

int nrf_cloud_credentials_configured_check(void)

Check if the credentials required for connecting to nRF Cloud exist. The application’s configuration is used to determine which credentials are required.

Return values:

• 0 – Required credentials exist.

• -EIO – Error checking if credentials exists.

• -ENOTSUP – Required credentials do not exist.

Returns:

A negative value indicates an error.

struct nrf_cloud_fota_job_info

#include <nrf_cloud.h>

Common FOTA job info.

Public Members

char *id

Null-terminated FOTA job identifier

struct nrf_cloud_settings_fota_job

#include <nrf_cloud.h>

FOTA job info provided to the settings module to track FOTA job status.

struct nrf_cloud_data

#include <nrf_cloud.h>

Generic encapsulation for any data that is sent to the cloud.

Public Members

uint32_t len

Length of the data.

const void *ptr

Pointer to the data.

struct nrf_cloud_topic

#include <nrf_cloud.h>

MQTT topic.

Public Members

uint32_t len

Length of the topic.

const void *ptr

Pointer to the topic.

struct nrf_cloud_sensor_data

#include <nrf_cloud.h>

Sensor data transmission parameters.

Public Members

enum nrf_cloud_sensor type

The sensor that is the source of the data.

struct nrf_cloud_data data

Sensor data to be transmitted.

uint16_t tag

Unique tag to identify the sent data. Can be used to match acknowledgment on the NRF_CLOUD_EVT_SENSOR_DATA_ACK event. Valid range: NCT_MSG_ID_USER_TAG_BEGIN to NCT_MSG_ID_USER_TAG_END. Any other value will suppress the NRF_CLOUD_EVT_SENSOR_DATA_ACK event.

int64_t ts_ms

UNIX epoch timestamp (in milliseconds) of the data. If a value <= NRF_CLOUD_NO_TIMESTAMP (0) is provided, the timestamp will be ignored.

struct nrf_cloud_evt

#include <nrf_cloud.h>

Asynchronous events received from the module.

Public Members

enum nrf_cloud_evt_type type

The event that occurred.

uint32_t status

Any status associated with the event.

struct nrf_cloud_data data

Received data.

struct nrf_cloud_topic topic

Topic on which data was received.

struct nrf_cloud_obj_shadow_data *shadow

Decoded shadow data: valid for NRF_CLOUD_EVT_RX_DATA_SHADOW events.

struct nrf_cloud_tx_data

#include <nrf_cloud.h>

Structure used to send data to nRF Cloud.

Public Members

struct nrf_cloud_obj *obj

Object containing data to be published

struct nrf_cloud_data data

Pre-encoded data that is to be published if an object is not provided

enum nrf_cloud_topic_type topic_type

Endpoint topic type published to.

enum mqtt_qos qos

Quality of Service of the message.

uint32_t id

Message ID

struct nrf_cloud_svc_info_fota

#include <nrf_cloud.h>

Controls which values are added to the FOTA array in the “serviceInfo” shadow section.

Public Members

uint8_t bootloader

Flag to indicate if bootloader updates are supported

uint8_t modem

Flag to indicate if modem delta updates are supported

uint8_t application

Flag to indicate if application updates are supported

uint8_t modem_full

Flag to indicate if full modem image updates are supported

struct nrf_cloud_svc_info_ui

#include <nrf_cloud.h>

DEPRECATED - No longer used by nRF Cloud.

Public Members

uint8_t temperature

Temperature

uint8_t gnss

Location (map)

uint8_t flip

Orientation

uint8_t humidity

Humidity

uint8_t air_pressure

Air pressure

uint8_t rsrp

RSRP

uint8_t log

Logs

uint8_t dictionary_log

Dictionary (binary) Logs

uint8_t air_quality

Air Quality

uint8_t light_sensor

Light sensor

uint8_t button

Button

struct nrf_cloud_modem_info

#include <nrf_cloud.h>

Modem info data and which sections should be encoded.

Public Members

const struct modem_param_info *mpi

Pointer to a populated modem_param_info struct. If NULL, modem data will be fetched.

const char *application_version

Application version string to report to nRF Cloud. Used only if device parameter is NRF_CLOUD_INFO_SET.

struct nrf_cloud_svc_info

#include <nrf_cloud.h>

Structure to specify which components are added to the encoded service info object.

Public Members

struct nrf_cloud_svc_info_fota *fota

Specify FOTA components to enable, set to NULL to remove the FOTA entry

struct nrf_cloud_svc_info_ui *ui

DEPRECATED - nRF Cloud no longer requires the device to set UI values in the shadow

struct nrf_cloud_device_status

#include <nrf_cloud.h>

Structure to specify which components are added to the encoded device status object.

Public Members

struct nrf_cloud_modem_info *modem

Specify which modem info components to include, set to NULL to skip

struct nrf_cloud_svc_info *svc

Specify which service info components to include, set to NULL to skip

enum nrf_cloud_shadow_info conn_inf

Specify how the connection info data should be handled

struct nrf_cloud_gnss_pvt

#include <nrf_cloud.h>

PVT data.

Public Members

double lat

Latitude in degrees; required.

double lon

Longitude in degrees; required.

float accuracy

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

float alt

Altitude above WGS-84 ellipsoid in meters; optional.

float speed

Horizontal speed in m/s; optional.

float heading

Heading of user movement in degrees; optional.

uint8_t has_alt

Altitude value is set

uint8_t has_speed

Speed value is set

uint8_t has_heading

Heading value is set

struct nrf_cloud_credentials_status

#include <nrf_cloud.h>

struct nrf_cloud_gnss_nmea

#include <nrf_cloud.h>

NMEA data.

Public Members

const char *sentence

NULL-terminated NMEA sentence. Supported types are GPGGA, GPGLL, GPRMC. Max string length is NRF_MODEM_GNSS_NMEA_MAX_LEN - 1

struct nrf_cloud_gnss_data

#include <nrf_cloud.h>

GNSS data to be sent to nRF Cloud as a device message.

Public Members

enum nrf_cloud_gnss_type type

The type of GNSS data below.

int64_t ts_ms

UNIX epoch timestamp (in milliseconds) of the data. If a value <= NRF_CLOUD_NO_TIMESTAMP (0) is provided, the timestamp will be ignored.

struct nrf_cloud_gnss_pvt pvt

For type: NRF_CLOUD_GNSS_TYPE_PVT

struct nrf_cloud_gnss_nmea nmea

For type: NRF_CLOUD_GNSS_TYPE_NMEA

struct nrf_modem_gnss_nmea_data_frame *mdm_nmea

For type: NRF_CLOUD_GNSS_TYPE_MODEM_PVT

struct nrf_modem_gnss_pvt_data_frame *mdm_pvt

For type: NRF_CLOUD_GNSS_TYPE_MODEM_NMEA

struct nrf_cloud_gw_data

#include <nrf_cloud.h>

Structure to hold message received from nRF Cloud.

struct nrf_cloud_ctrl_data

#include <nrf_cloud.h>

Data to control behavior of the nrf_cloud library from the cloud side. This data is stored in the device shadow.

Public Members

bool alerts_enabled

If true, nrf_cloud_alert_send() or nrf_cloud_rest_alert_send() will transfer alerts to the cloud whenever they are raised. If false, alerts will be suppressed.

int log_level

If 0, the nrf_cloud library logging backend will be disabled. If values from 1 to 4, this level and any lower levels will be sent to the cloud. Level 1 is most urgent (LOG_ERR), level 4 least (LOG_DBG).

struct nrf_cloud_init_param

#include <nrf_cloud.h>

Initialization parameters for the module.

Public Members

nrf_cloud_event_handler_t event_handler

Event handler that is registered with the module.

char *client_id

NULL-terminated MQTT client ID string. Must not exceed NRF_CLOUD_CLIENT_ID_MAX_LEN. Must be set if NRF_CLOUD_CLIENT_ID_SRC_RUNTIME is enabled; otherwise, NULL.

struct dfu_target_fmfu_fdev *fmfu_dev_inf

Flash device information required for full modem FOTA updates. Only used if CONFIG_NRF_CLOUD_FOTA_FULL_MODEM_UPDATE is enabled. Ignored if CONFIG_DFU_TARGET_FULL_MODEM_USE_EXT_PARTITION is enabled.

struct nrf_cloud_os_mem_hooks *hooks

Optional hooks to override memory management functions. If set, nrf_cloud_os_mem_hooks_init will be called by nrf_cloud_init.

const char *application_version

Optional application version that is reported to nRF Cloud if CONFIG_NRF_CLOUD_SEND_DEVICE_STATUS is enabled.

nRF Cloud codec documentation

Header file: include/net/nrf_cloud_codec.h

group nrf_cloud_codec

Defines

NRF_CLOUD_OBJ_JSON_DEFINE(_name)

Define an nRF Cloud JSON object.

This macro defines a codec object with the type of NRF_CLOUD_OBJ_TYPE_JSON.

Parameters:

• _name – Name of the object.

NRF_CLOUD_OBJ_COAP_CBOR_DEFINE(_name)

NRF_CLOUD_OBJ_DEFINE(_name, _type)

Define an nRF Cloud codec object of the specified type.

Parameters:

• _name – Name of the object.

• _type – Type of the object.

NRF_CLOUD_OBJ_PRE_ENC_DEFINE(_name, _data, _len)

Define an nRF Cloud object with pre-encoded data.

This macro defines a codec object with the type of NRF_CLOUD_OBJ_TYPE__UNDEFINED and initializes the encoded data with the provided parameters.

Parameters:

• _name – Name of the object.

• _data – Pointer to pre-encoded data.

• _len – Size of the pre-encoded data.

NRF_CLOUD_OBJ_TYPE_VALID(_obj_ptr)

Check if the provided object is a valid nRF Cloud codec object type.

Parameters:

• _obj_ptr – Object to check for a valid type.

Return values:

• true – Type is valid.

• false – Type is invalid.

Enums

enum nrf_cloud_obj_type

Object types for encoding and decoding.

Values:

enumerator NRF_CLOUD_OBJ_TYPE__UNDEFINED

enumerator NRF_CLOUD_OBJ_TYPE_JSON

enumerator NRF_CLOUD_OBJ_TYPE_COAP_CBOR

This object type is to be used to store only one of enum nrf_cloud_data_type using the corresponding field in the union in struct nrf_cloud_obj_coap_cbor.

enumerator NRF_CLOUD_OBJ_TYPE__LAST

enum nrf_cloud_enc_src

Encoded data sources.

Values:

enumerator NRF_CLOUD_ENC_SRC_NONE

Encoded data is not set

enumerator NRF_CLOUD_ENC_SRC_CLOUD_ENCODED

Encoded data was set by nrf_cloud_obj_cloud_encode

enumerator NRF_CLOUD_ENC_SRC_PRE_ENCODED

Encoded data was set manually or by NRF_CLOUD_OBJ_PRE_ENC_DEFINE

enum nrf_cloud_data_type

Data types for nrf_cloud_sensor_data.

Values:

enumerator NRF_CLOUD_DATA_TYPE_NONE

enumerator NRF_CLOUD_DATA_TYPE_PVT

The struct nrf_cloud_gnss_pvt *pvt field points to the data.

enumerator NRF_CLOUD_DATA_TYPE_STR

The const char *str_val field points to a NULL-terminated string.

enumerator NRF_CLOUD_DATA_TYPE_DOUBLE

The double double_val field contains the data.

enumerator NRF_CLOUD_DATA_TYPE_INT

The int int_val field contains the data.

enum nrf_cloud_obj_shadow_type

Types of shadow updates.

Values:

enumerator NRF_CLOUD_OBJ_SHADOW_TYPE_DELTA

enumerator NRF_CLOUD_OBJ_SHADOW_TYPE_ACCEPTED

Functions

int nrf_cloud_obj_input_decode(struct nrf_cloud_obj *const obj, const struct nrf_cloud_data *const input)

Decode data received from nRF Cloud.

If the provided obj has a valid type value, decoding for only that type is performed. If the provided obj does not have a valid type value, decoding for each type is performed until successful. If successful, memory is allocated for the provided object. The nrf_cloud_obj_free function should be called when finished with the object.

Parameters:

• obj – [out] Object to be initialized with the decoded data.

• input – [in] Data received from nRF Cloud.

Return values:

• -EINVAL – Invalid parameter.

• -ENOTSUP – Action not supported for the object’s type.

• -ENOMSG – Unable to decode data to a known type.

• 0 – Data successfully decoded.

int nrf_cloud_obj_msg_check(const struct nrf_cloud_obj *const obj, const char *const app_id, const char *const msg_type)

Check if the object contains the specified app ID and message type.

Parameters:

• obj – [in] Object to check.

• app_id – [in] Desired app ID. If NULL, app ID is not checked.

• msg_type – [in] Desired message type. If NULL, message type is not checked.

Return values:

• -EINVAL – Invalid parameter.

• -ENOENT – Object is not initialized.

• -ENOTSUP – Action not supported for the object’s type.

• -ENOMSG – Object does not contain the specified values.

• 0 – Success; object contains the specified values.

int nrf_cloud_obj_num_get(const struct nrf_cloud_obj *const obj, const char *const key, double *num)

Get the number value associated with the provided key.

Parameters:

• obj – [in] Object containing the key and value.

• key – [in] Key.

• num – [out] Number associated with the provided key.

Return values:

• -EINVAL – Invalid parameter.

• -ENODEV – Object does not contain the provided key.

• -ENOENT – Object is not initialized.

• -ENOTSUP – Action not supported for the object’s type.

• -ENOMSG – Value associated with the key is not a number.

• 0 – Success; number found.

int nrf_cloud_obj_str_get(const struct nrf_cloud_obj *const obj, const char *const key, char **str)

Get the string value associated with the provided key.

Parameters:

• obj – [in] Object containing the key and value.

• key – [in] Key.

• str – [out] String associated with the provided key.

Return values:

• -EINVAL – Invalid parameter.

• -ENODEV – Object does not contain the provided key.

• -ENOENT – Object is not initialized.

• -ENOTSUP – Action not supported for the object’s type.

• -ENOMSG – Value associated with the key is not a string.

• 0 – Success; string found.

int nrf_cloud_obj_bool_get(const struct nrf_cloud_obj *const obj, const char *const key, bool *val)

Get the boolean value associated with the provided key.

Parameters:

• obj – [in] Object containing the key and value.

• key – [in] Key.

• val – [out] Boolean value associated with the provided key.

Return values:

• -EINVAL – Invalid parameter.

• -ENODEV – Object does not contain the provided key.

• -ENOENT – Object is not initialized.

• -ENOTSUP – Action not supported for the object’s type.

• -ENOMSG – Value associated with the key is not a boolean.

• 0 – Success; boolean found.

int nrf_cloud_obj_object_detach(struct nrf_cloud_obj *const obj, const char *const key, struct nrf_cloud_obj *const obj_out)

Get and detach the object associated with the provided key.

If successful, the object data specified by the given key is removed from obj and moved into obj_out.

Parameters:

• obj – [in] Object containing the key and object.

• key – [in] Key.

• obj_out – [out] Object associated with the provided key.

Return values:

• -EINVAL – Invalid parameter.

• -ENODEV – Object does not contain the provided key.

• -ENOENT – Object is not initialized.

• -ENOTSUP – Action not supported for the object’s type.

• -ENOMSG – Value associated with the key is not an object.

• 0 – Success; string found.

int nrf_cloud_obj_msg_init(struct nrf_cloud_obj *const obj, const char *const app_id, const char *const msg_type)

Initialize an object as an nRF Cloud device message.

If successful, memory is allocated for the provided object. The nrf_cloud_obj_free function should be called when finished with the object.

Parameters:

• obj – [out] Object to initialize.

• app_id – [in] The desired app ID of the message.

• msg_type – [in] The desired message type; can be NULL.

Return values:

• -EINVAL – Invalid parameter.

• -ENOTEMPTY – Object already initialized.

• -ENOMEM – Out of memory.

• -ENOTSUP – Action not supported for the object’s type.

• 0 – Success; message initialized.

int nrf_cloud_obj_bulk_init(struct nrf_cloud_obj *const bulk)

Initialize an object as an nRF Cloud bulk message.

If successful, memory is allocated for the provided object. The nrf_cloud_obj_free function should be called when finished with the object.

Parameters:

• bulk – [out] Object to initialize.

Return values:

• -EINVAL – Invalid parameter.

• -ENOTEMPTY – Object already initialized.

• -ENOMEM – Out of memory.

• -ENOTSUP – Action not supported for the object’s type.

• 0 – Success; bulk message initialized.

int nrf_cloud_obj_init(struct nrf_cloud_obj *const obj)

Initialize an empty object.

If successful, memory is allocated for the provided object. The nrf_cloud_obj_free function should be called when finished with the object.

Parameters:

• obj – [out] Object to initialize.

Return values:

• -EINVAL – Invalid parameter.

• -ENOTEMPTY – Object already initialized.

• -ENOMEM – Out of memory.

• -ENOTSUP – Action not supported for the object’s type.

• 0 – Success; object initialized.

int nrf_cloud_obj_reset(struct nrf_cloud_obj *const obj)

Reset the state of an object; does not free memory.

Parameters:

• obj – [out] Object to reset.

Return values:

• -EINVAL – Invalid parameter.

• -ENOTSUP – Action not supported for the object’s type.

• 0 – Success; object initialized.

int nrf_cloud_obj_free(struct nrf_cloud_obj *const obj)

Free the memory of an initialized object.

Frees the object’s memory; use nrf_cloud_obj_cloud_encoded_free to free cloud encoded data.

Parameters:

• obj – [out] Object to initialize.

Return values:

• -EINVAL – Invalid parameter.

• -ENOMEM – Out of memory.

• -ENOTSUP – Action not supported for the object’s type.

• 0 – Success; memory freed.

bool nrf_cloud_obj_bulk_check(struct nrf_cloud_obj *const obj)

Check if an object is a JSON array eligible for bulk transfer.

Parameters:

• obj – [in] Object to check.

Returns:

bool True if the object is a JSON array.

int nrf_cloud_obj_bulk_add(struct nrf_cloud_obj *const bulk, struct nrf_cloud_obj *const obj)

Add an object to a bulk message object.

If successful, the object belongs to the bulk message and should not be freed directly.

Parameters:

• bulk – [out] Bulk container object.

• obj – [in] Object to add.

Return values:

• -EINVAL – Invalid parameter.

• -ENOENT – Object is not initialized.

• -ENODEV – Not a bulk container object.

• -EIO – Error adding object.

• -ENOTSUP – Action not supported for the object’s type.

• 0 – Success; item added.

int nrf_cloud_obj_ts_add(struct nrf_cloud_obj *const obj, const int64_t time_ms)

Add a timestamp to an object.

Parameters:

• obj – [out] Object to contain timestamp.

• time_ms – [in] Timestamp value in milliseconds. UNIX epoch format.

Return values:

• -EINVAL – Invalid parameter.

• -ENOENT – Object is not initialized.

• -ENOMEM – Out of memory.

• -ENOTSUP – Action not supported for the object’s type.

• 0 – Success; item added.

int nrf_cloud_obj_num_add(struct nrf_cloud_obj *const obj, const char *const key, const double val, const bool data_child)

Add a key string and number value to the provided object.

Parameters:

• obj – [out] Object to contain key and value.

• key – [in] Key string; must be valid and constant for the life of the object.

• val – [in] Number value.

• data_child – [in] If true, key and number will be added as a child to a “data” object. If false, key and number will be added as a child to the provided object.

Return values:

• -EINVAL – Invalid parameter.

• -ENOENT – Object is not initialized.

• -ENOMEM – Out of memory.

• -ENOTSUP – Action not supported for the object’s type.

• 0 – Success; item added.

int nrf_cloud_obj_str_add(struct nrf_cloud_obj *const obj, const char *const key, const char *const val, const bool data_child)

Add a key string and string value to the provided object.

Parameters:

• obj – [out] Object to contain key and value.

• key – [in] Key string; must be valid and constant for the life of the object.

• val – [in] String value.

• data_child – [in] If true, key and value will be added as a child to a “data” object. If false, key and value will be added as a child to the provided object.

Return values:

• -EINVAL – Invalid parameter.

• -ENOENT – Object is not initialized.

• -ENOMEM – Out of memory.

• -ENOTSUP – Action not supported for the object’s type.

• 0 – Success; item added.

int nrf_cloud_obj_bool_add(struct nrf_cloud_obj *const obj, const char *const key, const bool val, const bool data_child)

Add a key string and boolean value to the provided object.

Parameters:

• obj – [out] Object to contain key and value.

• key – [in] Key string; must be valid and constant for the life of the object.

• val – [in] Boolean value.

• data_child – [in] If true, key and value will be added as a child to a “data” object. If false, key and value will be added as a child to the provided object.

Return values:

• -EINVAL – Invalid parameter.

• -ENOENT – Object is not initialized.

• -ENOMEM – Out of memory.

• -ENOTSUP – Action not supported for the object’s type.

• 0 – Success; item added.

int nrf_cloud_obj_null_add(struct nrf_cloud_obj *const obj, const char *const key, const bool data_child)

Add a key string and null value to the provided object.

Parameters:

• obj – [out] Object to contain key and value.

• key – [in] Key string; must be valid and constant for the life of the object.

• data_child – [in] If true, key and value will be added as a child to a “data” object. If false, key and value will be added as a child to the provided object.

Return values:

• -EINVAL – Invalid parameter.

• -ENOENT – Object is not initialized.

• -ENOMEM – Out of memory.

• -ENOTSUP – Action not supported for the object’s type.

• 0 – Success; item added.

int nrf_cloud_obj_object_add(struct nrf_cloud_obj *const obj, const char *const key, struct nrf_cloud_obj *const obj_to_add, const bool data_child)

Add a key string and object to the provided object.

If successful, obj_to_add will be reset with nrf_cloud_obj_reset since its data has been moved to obj.

Parameters:

• obj – [out] Object to contain key and object.

• key – [in] Key string; must be valid and constant for the life of the object.

• obj_to_add – [in] Object.

• data_child – [in] If true, key and value will be added as a child to a “data” object. If false, key and value will be added as a child to the provided object.

Return values:

• -EINVAL – Invalid parameter.

• -ENOENT – Object is not initialized.

• -ENOMEM – Out of memory.

• -ENOTSUP – Action not supported for the object’s type.

• 0 – Success; item added.

int nrf_cloud_obj_int_array_add(struct nrf_cloud_obj *const obj, const char *const key, const uint32_t ints[], const uint32_t ints_cnt, const bool data_child)

Add a key string and integer array value to the provided object.

Parameters:

• obj – [out] Object to contain key and value.

• key – [in] Key string; must be valid and constant for the life of the object.

• ints – [in] Integer array.

• ints_cnt – [in] Number of items in array.

• data_child – [in] If true, key and value will be added as a child to a “data” object. If false, key and value will be added as a child to the provided object.

Return values:

• -EINVAL – Invalid parameter.

• -ENOENT – Object is not initialized.

• -ENOMEM – Out of memory.

• -ENOTSUP – Action not supported for the object’s type.

• 0 – Success; item added.

int nrf_cloud_obj_str_array_add(struct nrf_cloud_obj *const obj, const char *const key, const char *const strs[], const uint32_t strs_cnt, const bool data_child)

Add a key string and string array value to the provided object.

Parameters:

• obj – [out] Object to contain key and value.

• key – [in] Key string; must be valid and constant for the life of the object.

• strs – [in] String array.

• strs_cnt – [in] Number of items in array.

• data_child – [in] If true, key and value will be added as a child to a “data” object. If false, key and value will be added as a child to the provided object.

Return values:

• -EINVAL – Invalid parameter.

• -ENOENT – Object is not initialized.

• -ENOMEM – Out of memory.

• -ENOTSUP – Action not supported for the object’s type.

• 0 – Success; item added.

int nrf_cloud_obj_cloud_encode(struct nrf_cloud_obj *const obj)

Encode the object’s data for transport to nRF Cloud.

If successful, memory is allocated for the encoded data. The nrf_cloud_obj_cloud_encoded_free function should be called when finished with the object.

Parameters:

• obj – [out] Object to encode.

Return values:

• -EINVAL – Invalid parameter.

• -ENOMEM – Out of memory.

• -ENOTSUP – Action not supported for the object’s type.

• 0 – Success; object initialized.

int nrf_cloud_obj_cloud_encoded_free(struct nrf_cloud_obj *const obj)

Free the memory of the encoded data in the object.

Frees the memory allocated by nrf_cloud_obj_cloud_encode.

Parameters:

• obj – [out] Object.

Return values:

• -EINVAL – Invalid parameter.

• -EACCES – Encoded data was not encoded by nrf_cloud_obj_cloud_encode.

• -ENOTSUP – Action not supported for the object’s type.

• 0 – Success; memory freed.

int nrf_cloud_obj_gnss_msg_create(struct nrf_cloud_obj *const obj, const struct nrf_cloud_gnss_data *const gnss)

Create an nRF Cloud GNSS message object.

If successful, memory is allocated for the provided object. The nrf_cloud_obj_free function should be called when finished with the object.

Parameters:

• obj – [out] Uninitialzed object to contain the GNSS message.

• gnss – [in] GNSS data.

Return values:

• -EINVAL – Invalid parameter.

• -EBADF – Invalid object type.

• -ENOTEMPTY – Object already initialized.

• -ENOMEM – Out of memory.

• -ENOSYS – Modem library (NRF_MODEM) not enabled.

• -EFBIG – NMEA string too large, see NRF_MODEM_GNSS_NMEA_MAX_LEN.

• -EPROTO – Unhandled GNSS type.

• 0 – Success; GNSS message created.

int nrf_cloud_obj_location_request_create(struct nrf_cloud_obj *const obj, const struct lte_lc_cells_info *const cells_inf, const struct wifi_scan_info *const wifi_inf, const struct nrf_cloud_location_config *const config)

Create an nRF Cloud Location request message object.

If successful, memory is allocated for the provided object. The nrf_cloud_obj_free function should be called when finished with the object.

Parameters:

• obj – [out] Uninitialzed object to contain the Location message.

• cells_inf – [in] Cellular network data, can be NULL if wifi_inf is provided.

• wifi_inf – [in] Wi-Fi network data, can be NULL if cells_inf is provided.

• config – [in] Optional configuration of request. If NULL, use cloud defaults.

Return values:

• -EINVAL – Invalid parameter.

• -EDOM – Too few Wi-Fi networks, see NRF_CLOUD_LOCATION_WIFI_AP_CNT_MIN.

• -EBADF – Invalid object type.

• -ENOTEMPTY – Object already initialized.

• -ENOMEM – Out of memory.

• 0 – Success; GNSS message created.

int nrf_cloud_obj_pvt_add(struct nrf_cloud_obj *const obj, const struct nrf_cloud_gnss_pvt *const pvt)

Add PVT data to the provided object.

Parameters:

• obj – [out] Object to contain the PVT data.

• pvt – [in] PVT data.

Return values:

• -EINVAL – Invalid parameter.

• -EBADF – Invalid object type.

• -ENOTSUP – Action not supported for the object’s type.

• -ENOENT – Object is not initialized.

• -ENOMEM – Out of memory.

• 0 – Success; PVT data added to object.

int nrf_cloud_obj_modem_pvt_add(struct nrf_cloud_obj *const obj, const struct nrf_modem_gnss_pvt_data_frame *const mdm_pvt)

Add modem PVT data to the provided object.

Parameters:

• obj – [out] Object to contain the modem PVT data.

• mdm_pvt – [in] Modem PVT data.

Return values:

• -EINVAL – Invalid parameter.

• -EBADF – Invalid object type.

• -ENOTSUP – Action not supported for the object’s type.

• -ENOENT – Object is not initialized.

• -ENOMEM – Out of memory.

• -ENOSYS – Modem library (NRF_MODEM) not enabled.

• 0 – Success; modem PVT data added to object.

int nrf_cloud_obj_pgps_request_create(struct nrf_cloud_obj *const obj, const struct gps_pgps_request *const request)

Create an nRF Cloud P-GPS request device message object.

If successful, memory is allocated for the provided object. The nrf_cloud_obj_free function should be called when finished with the object.

Parameters:

• obj – [out] Uninitialzed object to contain the P-GPS request message.

• request – [in] P-GPS request data.

Return values:

• -EINVAL – Invalid parameter.

• -EBADF – Invalid object type.

• -ENOTEMPTY – Object already initialized.

• -ENOMEM – Out of memory.

• -ENOTSUP – Action not supported for the object’s type.

• 0 – Success; GNSS message created.

int nrf_cloud_gnss_msg_json_encode(const struct nrf_cloud_gnss_data *const gnss, cJSON *const gnss_msg_obj)

Create an nRF Cloud GNSS device message using the provided GNSS data.

Parameters:

• gnss – [in] Service info to add.

• gnss_msg_obj – [inout] cJSON object to which the GNSS message will be added.

Return values:

0 – If successful.

Returns:

A negative value indicates an error.

int nrf_cloud_service_info_json_encode(const struct nrf_cloud_svc_info *const svc_inf, cJSON *const svc_inf_obj)

Add service info into the provided cJSON object.

Parameters:

• svc_inf – [in] Service info to add.

• svc_inf_obj – [inout] cJSON object to which the service info will be added.

Return values:

0 – If successful.

Returns:

A negative value indicates an error.

int nrf_cloud_modem_info_json_encode(const struct nrf_cloud_modem_info *const mod_inf, cJSON *const mod_inf_obj)

Add modem info into the provided cJSON object.

Note

To add modem info, CONFIG_MODEM_INFO must be enabled.

Parameters:

• mod_inf – [in] Modem info to add.

• mod_inf_obj – [inout] cJSON object to which the modem info will be added.

Return values:

0 – If successful.

Returns:

A negative value indicates an error.

int nrf_cloud_error_msg_decode(const char *const buf, const char *const app_id, const char *const msg_type, enum nrf_cloud_error *const err)

Check for a JSON error message in the data received from nRF Cloud over MQTT.

Parameters:

• buf – [in] Data received from nRF Cloud.

• app_id – [in] appId value to check for. Set to NULL to skip appID check.

• msg_type – [in] messageType value to check for. Set to NULL to skip messageType check.

• err – [out] Error code found in message.

Return values:

• 0 – Error code found (and matched app_id and msg_type if provided).

• -ENOENT – Error code found, but did not match specified the app_id and msg_type.

• -ENOMSG – No error code found.

• -EBADMSG – Invalid error code data format.

• -ENODATA – JSON data was not found.

Returns:

A negative value indicates an error.

int nrf_cloud_obj_shadow_delta_response_encode(struct nrf_cloud_obj *const delta_state_obj, bool accept)

Encode the response to the shadow delta update.

A delta update occurs when the shadow’s “desired” and “reported” sections do not match. The JSON for a delta update contains the actual delta data in a “state” object, along with some additional information. Example: {“version”:123,”timestamp”:1695404679, “state”:{“myData”:{“myValue”:1}}, …}

The application must inspect the delta and either accept or reject the changes.

If accepting, the delta should be passed unmodified into this function as the input_obj parameter, with the accept flag set to true. Example input_obj: “myData”:{“myValue”:1}

If rejecting, the delta should be modified with the correct data and passed into this function as the delta_state_obj parameter, with the accept flag set to false. Example input_obj: “myData”:{“myValue”:3}

A value can be removed from the shadow by setting it to null. Example input_obj: “myData”:{“myValue”:null} On success, the delta_state_obj parameter can be sent to nRF Cloud using nrf_cloud_coap_shadow_state_update() for CoAP or nrf_cloud_obj_shadow_update() for MQTT.

Parameters:

• delta_state_obj – [in] The contents of the “state” object received in a shadow delta.

• accept – [in] Flag to indicate whether to accept (place in reported section) or reject (place in desired section).

struct nrf_cloud_obj_coap_cbor

#include <nrf_cloud_codec.h>

Object to support nRF Cloud CoAP CBOR messages.

Public Members

enum nrf_cloud_data_type type

type indicates which one of the fields in the union is valid.

struct nrf_cloud_obj

#include <nrf_cloud_codec.h>

Object used for building nRF Cloud messages.

Public Members

enum nrf_cloud_enc_src enc_src

Source of encoded data

struct nrf_cloud_data encoded_data

Encoded data

struct nrf_cloud_obj_shadow_delta

#include <nrf_cloud_codec.h>

Object containing shadow delta data.

Public Members

int ver

The shadow version number

int64_t ts

Timestamp of the delta event

struct nrf_cloud_obj state

The delta data in the “state” object

struct nrf_cloud_obj_shadow_accepted

#include <nrf_cloud_codec.h>

Object containing the accepted shadow data.

Public Members

struct nrf_cloud_obj desired

The “desired” shadow data

struct nrf_cloud_obj reported

The “reported” shadow data

struct nrf_cloud_obj config

The reported “config” shadow data. nRF Cloud separates this to allow for easier processing.

struct nrf_cloud_obj_shadow_data

#include <nrf_cloud_codec.h>

Object containing shadow update data.

Public Members

enum nrf_cloud_obj_shadow_type type

The type of shadow data provided in the union

struct nrf_cloud_obj_shadow_accepted *accepted

Accepted data; for type = NRF_CLOUD_OBJ_SHADOW_TYPE_ACCEPTED

struct nrf_cloud_obj_shadow_delta *delta

Delta data; for type = NRF_CLOUD_OBJ_SHADOW_TYPE_DELTA

nRF Cloud common definitions

Header file: include/net/nrf_cloud_defs.h

group nrf_cloud_defs

Defines

NRF_CLOUD_JSON_APPID_KEY

NRF_CLOUD_JSON_APPID_VAL_AGNSS

NRF_CLOUD_JSON_APPID_VAL_PGPS

NRF_CLOUD_JSON_APPID_VAL_GNSS

NRF_CLOUD_JSON_APPID_VAL_LOCATION

NRF_CLOUD_JSON_APPID_VAL_DEVICE

NRF_CLOUD_JSON_APPID_VAL_FLIP

NRF_CLOUD_JSON_APPID_VAL_BTN

NRF_CLOUD_JSON_APPID_VAL_TEMP

NRF_CLOUD_JSON_APPID_VAL_HUMID

NRF_CLOUD_JSON_APPID_VAL_AIR_PRESS

NRF_CLOUD_JSON_APPID_VAL_AIR_QUAL

NRF_CLOUD_JSON_APPID_VAL_RSRP

NRF_CLOUD_JSON_APPID_VAL_LIGHT

NRF_CLOUD_JSON_APPID_VAL_MODEM

NRF_CLOUD_JSON_APPID_VAL_ALERT

NRF_CLOUD_JSON_APPID_VAL_LOG

NRF_CLOUD_JSON_APPID_VAL_DICTIONARY_LOG

NRF_CLOUD_JSON_MSG_TYPE_KEY

NRF_CLOUD_JSON_MSG_TYPE_VAL_CMD

NRF_CLOUD_JSON_MSG_TYPE_VAL_DATA

NRF_CLOUD_JSON_MSG_TYPE_VAL_DISCONNECT

NRF_CLOUD_JSON_DATA_KEY

NRF_CLOUD_JSON_ERR_KEY

NRF_CLOUD_JSON_FULFILL_KEY

NRF_CLOUD_JSON_FILTERED_KEY

NRF_CLOUD_MSG_TIMESTAMP_KEY

NRF_CLOUD_JSON_MCC_KEY

NRF_CLOUD_JSON_MNC_KEY

NRF_CLOUD_JSON_AREA_CODE_KEY

NRF_CLOUD_JSON_CELL_ID_KEY

NRF_CLOUD_JSON_PHYCID_KEY

NRF_CLOUD_JSON_RSRP_KEY

NRF_CLOUD_CELL_POS_JSON_KEY_LTE

NRF_CLOUD_CELL_POS_JSON_KEY_ECI

NRF_CLOUD_CELL_POS_JSON_KEY_MCC

NRF_CLOUD_CELL_POS_JSON_KEY_MNC

NRF_CLOUD_CELL_POS_JSON_KEY_TAC

NRF_CLOUD_CELL_POS_JSON_KEY_AGE

NRF_CLOUD_CELL_POS_JSON_KEY_T_ADV

NRF_CLOUD_CELL_POS_JSON_KEY_EARFCN

NRF_CLOUD_CELL_POS_JSON_KEY_PCI

NRF_CLOUD_CELL_POS_JSON_KEY_NBORS

NRF_CLOUD_CELL_POS_JSON_KEY_RSRP

NRF_CLOUD_CELL_POS_JSON_KEY_RSRQ

NRF_CLOUD_CELL_POS_JSON_KEY_TDIFF

NRF_CLOUD_LOCATION_JSON_KEY_CONFIG

NRF_CLOUD_LOCATION_JSON_KEY_DOREPLY

NRF_CLOUD_LOCATION_JSON_KEY_HICONF

NRF_CLOUD_LOCATION_JSON_KEY_FALLBACK

NRF_CLOUD_LOCATION_JSON_KEY_WIFI

NRF_CLOUD_LOCATION_JSON_KEY_APS

NRF_CLOUD_LOCATION_JSON_KEY_ANCHORS

NRF_CLOUD_LOCATION_JSON_KEY_ANC_NAME

NRF_CLOUD_LOCATION_JSON_KEY_ANC_MAC

NRF_CLOUD_LOCATION_JSON_KEY_WIFI_MAC

NRF_CLOUD_LOCATION_JSON_KEY_WIFI_CH

NRF_CLOUD_LOCATION_JSON_KEY_WIFI_RSSI

NRF_CLOUD_LOCATION_JSON_KEY_WIFI_SSID

NRF_CLOUD_LOCATION_JSON_KEY_LAT

NRF_CLOUD_LOCATION_JSON_KEY_LON

NRF_CLOUD_LOCATION_JSON_KEY_UNCERT

NRF_CLOUD_LOCATION_TYPE_VAL_MCELL

NRF_CLOUD_LOCATION_TYPE_VAL_SCELL

NRF_CLOUD_LOCATION_TYPE_VAL_WIFI

NRF_CLOUD_LOCATION_TYPE_VAL_ANCHOR

NRF_CLOUD_LOCATION_DOREPLY_DEFAULT

Current defaults in the cloud.

NRF_CLOUD_LOCATION_HICONF_DEFAULT

NRF_CLOUD_LOCATION_FALLBACK_DEFAULT

NRF_CLOUD_JSON_PGPS_PRED_COUNT

NRF_CLOUD_JSON_PGPS_INT_MIN

NRF_CLOUD_JSON_PGPS_GPS_DAY

NRF_CLOUD_JSON_PGPS_GPS_TIME

NRF_CLOUD_PGPS_RCV_ARRAY_IDX_HOST

NRF_CLOUD_PGPS_RCV_ARRAY_IDX_PATH

NRF_CLOUD_PGPS_RCV_REST_HOST

NRF_CLOUD_PGPS_RCV_REST_PATH

NRF_CLOUD_JSON_KEY_ELEVATION_MASK

NRF_CLOUD_JSON_KEY_AGNSS_TYPES

NRF_CLOUD_FOTA_TYPE_MODEM_DELTA

NRF_CLOUD_FOTA_TYPE_MODEM_FULL

NRF_CLOUD_FOTA_TYPE_BOOT

NRF_CLOUD_FOTA_TYPE_APP

NRF_CLOUD_FOTA_REST_KEY_JOB_DOC

NRF_CLOUD_FOTA_REST_KEY_JOB_ID

NRF_CLOUD_FOTA_REST_KEY_PATH

NRF_CLOUD_FOTA_REST_KEY_HOST

NRF_CLOUD_FOTA_REST_KEY_TYPE

NRF_CLOUD_FOTA_REST_KEY_SIZE

NRF_CLOUD_FOTA_REST_KEY_VER

NRF_CLOUD_FOTA_VER

Current FOTA version number

NRF_CLOUD_REST_ERROR_CODE_KEY

NRF_CLOUD_REST_ERROR_MSG_KEY

NRF_CLOUD_REST_TOPIC_KEY

NRF_CLOUD_REST_MSG_KEY

NRF_CLOUD_JSON_GNSS_PVT_KEY_LAT

NRF_CLOUD_JSON_GNSS_PVT_KEY_LON

NRF_CLOUD_JSON_GNSS_PVT_KEY_ACCURACY

NRF_CLOUD_JSON_GNSS_PVT_KEY_ALTITUDE

NRF_CLOUD_JSON_GNSS_PVT_KEY_SPEED

NRF_CLOUD_JSON_GNSS_PVT_KEY_HEADING

NRF_CLOUD_DEVICE_JSON_KEY_NET_INF

NRF_CLOUD_DEVICE_JSON_KEY_SIM_INF

NRF_CLOUD_DEVICE_JSON_KEY_DEV_INF

NRF_CLOUD_JSON_ALERT_SEQUENCE

NRF_CLOUD_JSON_ALERT_DESCRIPTION

NRF_CLOUD_JSON_ALERT_TYPE

NRF_CLOUD_JSON_ALERT_VALUE

NRF_CLOUD_JSON_LOG_KEY_SEQUENCE

NRF_CLOUD_JSON_LOG_KEY_DOMAIN

NRF_CLOUD_JSON_LOG_KEY_SOURCE

NRF_CLOUD_JSON_LOG_KEY_LEVEL

NRF_CLOUD_JSON_LOG_KEY_MESSAGE

NRF_CLOUD_SETTINGS_NAME

nRF Cloud’s string identifier for persistent settings

NRF_CLOUD_SETTINGS_FOTA_KEY

NRF_CLOUD_SETTINGS_FOTA_JOB

NRF_CLOUD_SETTINGS_FULL_FOTA

String used when defining a settings handler for FOTA

NRF_CLOUD_SETTINGS_FULL_FOTA_JOB

String used when saving FOTA job info to settings

NRF_CLOUD_JSON_KEY_STATE

NRF_CLOUD_JSON_KEY_REP

NRF_CLOUD_JSON_KEY_DES

NRF_CLOUD_JSON_KEY_DELTA

NRF_CLOUD_JSON_KEY_DEVICE

NRF_CLOUD_JSON_KEY_SRVC_INFO

NRF_CLOUD_JSON_KEY_SRVC_INFO_UI

NRF_CLOUD_JSON_KEY_SRVC_INFO_FOTA

NRF_CLOUD_JSON_KEY_CFG

NRF_CLOUD_JSON_KEY_CTRL

NRF_CLOUD_JSON_KEY_ALERT

NRF_CLOUD_JSON_KEY_LOG

NRF_CLOUD_JSON_KEY_TOPICS

NRF_CLOUD_JSON_KEY_STAGE

NRF_CLOUD_JSON_KEY_PAIRING

NRF_CLOUD_JSON_KEY_PAIR_STAT

NRF_CLOUD_JSON_KEY_TOPIC_PRFX

NRF_CLOUD_JSON_KEY_KEEPALIVE

NRF_CLOUD_JSON_KEY_CONN

NRF_CLOUD_JSON_KEY_APP_VER

NRF_CLOUD_JSON_KEY_CONN_INFO

NRF_CLOUD_JSON_KEY_PROTOCOL

NRF_CLOUD_JSON_KEY_METHOD

NRF_CLOUD_JSON_VAL_NOT_ASSOC

NRF_CLOUD_JSON_VAL_PAIRED

NRF_CLOUD_JSON_KEY_SHADOW_VERSION

NRF_CLOUD_JSON_KEY_SHADOW_TIMESTAMP

NRF_CLOUD_FOTA_VER_STR

NRF_CLOUD_STAGE_ID_MAX_LEN

NRF_CLOUD_TENANT_ID_MAX_LEN

Max length of a tenant ID on nRF Cloud

NRF_CLOUD_CLIENT_ID_MAX_LEN

Max length of a device’s MQTT client ID (device ID) on nRF Cloud

NRF_CLOUD_JSON_KEY_DEVICE_TO_CLOUD

NRF_CLOUD_JSON_KEY_CLOUD_TO_DEVICE

NRF_CLOUD_BULK_MSG_TOPIC

NRF_CLOUD_JSON_VAL_TOPIC_C2D

NRF_CLOUD_JSON_VAL_TOPIC_AGNSS

NRF_CLOUD_JSON_VAL_TOPIC_PGPS

NRF_CLOUD_JSON_VAL_TOPIC_GND_FIX

NRF_CLOUD_JSON_VAL_TOPIC_RCV

NRF_CLOUD_JSON_VAL_TOPIC_WILDCARD

NRF_CLOUD_JSON_VAL_TOPIC_BIN

NRF_CLOUD_JSON_VAL_PROTO_MQTT

NRF_CLOUD_JSON_VAL_PROTO_COAP

NRF_CLOUD_JSON_VAL_PROTO_REST

NRF_CLOUD_JSON_VAL_METHOD_LTE

NRF_CLOUD_JSON_VAL_METHOD_WIFI

nRF Cloud FOTA poll for REST and CoAP

Header file: include/net/nrf_cloud_fota_poll.h

group nrf_cloud_fota_poll

Typedefs

typedef void (*fota_reboot_handler_t)(enum nrf_cloud_fota_reboot_status status)

Event handler registered with the module to handle asynchronous events from the module.

Param status:

[in] The reason for the reboot request.

Enums

enum nrf_cloud_fota_reboot_status

Values:

enumerator FOTA_REBOOT_REQUIRED

enumerator FOTA_REBOOT_SUCCESS

Reboot to install update.

enumerator FOTA_REBOOT_FAIL

Reboot to complete FOTA job.

enumerator FOTA_REBOOT_SYS_ERROR

Reboot because FOTA job failed. Reboot because fatal system error occurred.

Functions

int nrf_cloud_fota_poll_init(struct nrf_cloud_fota_poll_ctx *ctx)

Initialize nRF Cloud FOTA polling assistance. Must be called before any other module functions.

Parameters:

• ctx – [in] Pointer to context used for FOTA polling operations.

Return values:

• 0 – If successful.

• -EINVAL – Invalid ctx.

Returns:

A negative value indicates an error.

int nrf_cloud_fota_poll_process_pending(struct nrf_cloud_fota_poll_ctx *ctx)

Process/validate a pending FOTA update job. This may initiate a reboot through the context’s reboot function.

Parameters:

• ctx – [in] Pointer to context used for FOTA polling operations.

Return values:

-EINVAL – Invalid ctx or module is not initialized.

Returns:

If successful, the pending FOTA job type is returned nrf_cloud_fota_type. NRF_CLOUD_FOTA_TYPE__INVALID indicates no pending FOTA job.

int nrf_cloud_fota_poll_process(struct nrf_cloud_fota_poll_ctx *ctx)

Perform the following FOTA tasks: Report the status of an in progress FOTA job. Check for a queued FOTA job. Execute FOTA job. Save status and request reboot.

Parameters:

• ctx – [in] Pointer to context used for FOTA polling operations.

Return values:

• -EINVAL – Invalid ctx or module is not initialized.

• -ENOTRECOVERABLE – Error performing FOTA action.

• -EBUSY – A reboot was requested but not performed by the application.

• -EFAULT – A FOTA job was not successful.

• -ENOENT – A FOTA job has finished and its status has been reported to the cloud.

• -EAGAIN – No FOTA job exists.

struct nrf_cloud_fota_poll_ctx

#include <nrf_cloud_fota_poll.h>