nRF Cloud

Initializing
Connecting
- Configuration options for device ID
Firmware over-the-air (FOTA) updates
- Building FOTA images
Sending sensor data
Removing the link between device and user
Location services
API documentation

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 from supported sensor types to the cloud. The current implementation supports the following technologies:

GNSS and FLIP sensor data
TLS secured MQTT as the communication protocol
JSON as the data format

Initializing 

Before using any other APIs of the module, the application must call nrf_cloud_init(). If this API fails, the application must not use any APIs 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 status field of nrf_cloud_evt contains the connection status that is defined by nrf_cloud_connect_result. The event NRF_CLOUD_EVT_TRANSPORT_DISCONNECTED 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 certificates are generated using the device ID and PIN or HWID. 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 user association requests from the cloud.

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. When adding the device to an nRF Cloud account, the user must provide the correct device ID and PIN (for Thingy:91 and custom hardware) or HWID (for nRF9160 DK) to nRF Cloud.

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

$msc { hscale = "1.3"; Module,Application; Module<<Application [label="nrf_cloud_connect() returns successfully"]; Module>>Application [label="NRF_CLOUD_EVT_TRANSPORT_CONNECTED"]; Module>>Application [label="NRF_CLOUD_EVT_USER_ASSOCIATION_REQUEST"]; --- [label="Add the device to nRF Cloud account"]; Module>>Application [label="NRF_CLOUD_EVT_USER_ASSOCIATED"]; Module<<Application [label="nrf_cloud_disconnect() returns successfully"]; Module>>Application [label="NRF_CLOUD_EVT_TRANSPORT_DISCONNECTED"]; Module<<Application [label="nrf_cloud_connect() returns successfully"]; Module>>Application [label="NRF_CLOUD_EVT_TRANSPORT_CONNECTED"]; Module>>Application [label="NRF_CLOUD_EVT_USER_ASSOCIATED"]; Module>>Application [label="NRF_CLOUD_EVT_READY"]; }$

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 nrf_cloud_disconnect() 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:

$msc { hscale = "1.3"; Module,Application; Module<<Application [label="nrf_cloud_connect() returns successfully"]; Module>>Application [label="NRF_CLOUD_EVT_TRANSPORT_CONNECTED"]; Module>>Application [label="NRF_CLOUD_EVT_USER_ASSOCIATED"]; Module>>Application [label="NRF_CLOUD_EVT_READY"]; }$

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

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>). 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 nRF9160 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 32-character string with no hyphens. This option requires modem firmware v1.3.0 or higher.
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 run time. If the nRF Cloud library is used directly, set the NULL-terminated ID string in nrf_cloud_init_param when calling nrf_cloud_init().

Firmware over-the-air (FOTA) updates 

The nRF Cloud library supports FOTA updates for your nRF9160-based device. The CONFIG_NRF_CLOUD_FOTA 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_REBOOT
CONFIG_CJSON_LIB

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. nrf_cloud_service_info_json_encode() can be used to generate the proper JSON data to enable FOTA. Additionally, nrf_cloud_shadow_device_status_update() 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 the nRF9160, 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 Device API. When the device receives FOTA update information from nRF Cloud, the nRF Cloud library sends the NRF_CLOUD_EVT_FOTA_START event to the application. 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 and/or dfu_mcuboot.zip for a properly configured application. See Building FOTA images 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 APIs, nrf_cloud_sensor_data_send() and nrf_cloud_sensor_data_stream() (lowest QoS), for sending sensor data to the cloud.

To view sensor data on nRF Cloud, the device must first inform the cloud what types of sensor data to display. The device passes this information by writing a ui field, containing an array of sensor types, into the serviceInfo field in the device’s shadow. nrf_cloud_service_info_json_encode() can be used to generate the proper JSON data to enable FOTA. Additionally, nrf_cloud_shadow_device_status_update() can be used to generate the JSON data and perform the shadow update.

Following are the supported UI types on nRF Cloud:

GNSS
FLIP
TEMP
HUMIDITY
AIR_PRESS
RSRP

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 GPS - nRF Cloud A-GPS
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_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_FOTA_VER: Current FOTA version number

NRF_CLOUD_FOTA_VER_STR: Current FOTA version string used in device shadow

NRF_CLOUD_STAGE_ID_MAX_LEN: Max length of nRF Cloud’s stage/environment name

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_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_FOTA_JOB_ID_SIZE: Size of nRF Cloud FOTA job ID; version 4 UUID: 32 bytes, 4 hyphens, NULL

NRF_CLOUD_NO_TIMESTAMP

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.

enumerator NRF_CLOUD_EVT_FOTA_START: A FOTA update has started.

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

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_AGPS_PROC: Error processing A-GPS data

enumerator NRF_CLOUD_ERR_STATUS_PGPS_PROC: Error processing P-GPS data

enum nrf_cloud_disconnect_status

nRF Cloud disconnect status.

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.

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

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 to send pre-encoded 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.

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_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 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 modem info will be added.

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

Function to 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)

Function to 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)

Function to 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)

Function to 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)

Function to 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_handle_error_message(const char *const buf, const char *const app_id, const char *const msg_type, enum nrf_cloud_error *const err)

Function to check for a JSON error message in data received from nRF Cloud via 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 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_fota_pending_job_type_get(enum nrf_cloud_fota_type *const pending_fota_type)

Function to 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)

Function to 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)

Function to 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)

Function to 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)

Function to 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)

Function to 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_gnss_msg_json_encode(const struct nrf_cloud_gnss_data *const gnss, cJSON *const gnss_msg_obj)

Add GNSS location data, formatted as an nRF Cloud device message, to the provided cJSON object.

Parameters

gnss – [in] Service info to add.
gnss_msg_obj – [inout] cJSON object to which GNSS data will be added.

Return values

0 – If successful.

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.

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_tx_data

#include <nrf_cloud.h>

Structure used to send pre-encoded data to nRF Cloud.

Public Members

struct nrf_cloud_data data: Data that is to be published.

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>

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

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

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: Specify UI components to enable, set to NULL to remove the UI entry

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

struct nrf_cloud_gnss_pvt

#include <nrf_cloud.h>

PVT data.

Public Members

double lon: Longitude in degrees; required.

double lat: Latitude 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_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 negative value 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_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.

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.