nRF Cloud REST

The nRF Cloud REST library enables applications to use nRF Cloud’s REST-based device API. This library is an enhancement to the nRF Cloud library.

To make a REST call, configure a nrf_cloud_rest_context structure with your desired parameters.

  • auth - Use Modem JWT to generate a JWT string. The sec_tag used for JWT generation must contain a credential that has been registered with nRF Cloud.

Pass the REST context structure, along with any other required parameters, to the desired function. When the function returns, the context contains the status of the API call. If the API call is successful, the context also contains the response data and length. Some functions also have an optional result parameter. If this parameter is provided, the response data is parsed into result.

Response is handled in the following way:

Configuration

Configure the CONFIG_NRF_CLOUD_REST option to enable or disable the use of this library.

Additionally, configure the following options for the needs of your application:

API documentation

Header file: include/net/nrf_cloud_rest.h
Source files: subsys/net/lib/nrf_cloud/src/
group nrf_cloud_rest

Defines

NRF_CLOUD_REST_TIMEOUT_MINIMUM
NRF_CLOUD_REST_TIMEOUT_NONE

Enums

enum nrf_cloud_http_status

HTTP status codes returned from nRF Cloud.

Values:

enumerator NRF_CLOUD_HTTP_STATUS_UNHANDLED
enumerator NRF_CLOUD_HTTP_STATUS_NONE
enumerator NRF_CLOUD_HTTP_STATUS_OK
enumerator NRF_CLOUD_HTTP_STATUS_ACCEPTED
enumerator NRF_CLOUD_HTTP_STATUS_PARTIAL
enumerator NRF_CLOUD_HTTP_STATUS_BAD_REQ
enumerator NRF_CLOUD_HTTP_STATUS_UNAUTH
enumerator NRF_CLOUD_HTTP_STATUS_FORBIDDEN
enumerator NRF_CLOUD_HTTP_STATUS_NOT_FOUND
enumerator NRF_CLOUD_HTTP_STATUS_BAD_RANGE
enumerator NRF_CLOUD_HTTP_STATUS_UNPROC_ENTITY
enum nrf_cloud_rest_agps_req_type

nRF Cloud AGPS REST request types

Values:

enumerator NRF_CLOUD_REST_AGPS_REQ_ASSISTANCE
enumerator NRF_CLOUD_REST_AGPS_REQ_LOCATION
enumerator NRF_CLOUD_REST_AGPS_REQ_CUSTOM
enumerator NRF_CLOUD_REST_AGPS_REQ_UNSPECIFIED

Functions

int nrf_cloud_rest_cell_pos_get(struct nrf_cloud_rest_context *const rest_ctx, struct nrf_cloud_rest_cell_pos_request const *const request, struct nrf_cloud_cell_pos_result *const result)

nRF Cloud location request.

Parameters

  • rest_ctx – [inout] Context for communicating with nRF Cloud’s REST API.

  • request – [in] Data to be provided in API call.

  • result – [inout] Optional; parsed results of API response. If NULL, user should inspect the response buffer of nrf_cloud_rest_context.

Return values

0 – If successful. Otherwise, a (negative) error code is returned.

int nrf_cloud_rest_agps_data_get(struct nrf_cloud_rest_context *const rest_ctx, struct nrf_cloud_rest_agps_request const *const request, struct nrf_cloud_rest_agps_result *const result)

nRF Cloud Assisted GPS (A-GPS) data request.

Parameters

  • rest_ctx – [inout] Context for communicating with nRF Cloud’s REST API.

  • request – [in] Data to be provided in API call.

  • result – [inout] Optional; Additional buffer for A-GPS data. This is necessary when the A-GPS data from the cloud is larger than the fragment size specified by rest_ctx->fragment_size.

Return values

0 – If successful. If result is NULL and the A-GPS data is larger than the fragment size specified by rest_ctx->fragment_size, a positive value is returned, which indicates the size (in bytes) of the necessary result buffer. Otherwise, a (negative) error code is returned.

int nrf_cloud_rest_pgps_data_get(struct nrf_cloud_rest_context *const rest_ctx, struct nrf_cloud_rest_pgps_request const *const request)

nRF Cloud Predicted GPS (P-GPS) data request.

Parameters

  • rest_ctx – [inout] Context for communicating with nRF Cloud’s REST API. If successful, rest_ctx->result will point to the P-GPS data; which, along with rest_ctx->response_len, can be passed into nrf_cloud_pgps_process.

  • request – [in] Data to be provided in API call.

Return values

0 – If successful. Otherwise, a (negative) error code is returned.

int nrf_cloud_rest_fota_job_get(struct nrf_cloud_rest_context *const rest_ctx, const char *const device_id, struct nrf_cloud_fota_job_info *const job)

Requests nRF Cloud FOTA job info for the specified device.

Parameters

  • rest_ctx – [inout] Context for communicating with nRF Cloud’s REST API.

  • device_id – [in] Null-terminated, unique device ID registered with nRF Cloud.

  • job – [out] Optional; parsed job info. If no job exists, type will be set to invalid. If a job exists, user must call nrf_cloud_rest_fota_job_free to free the memory allocated by this function. If NULL, user should inspect the response buffer of nrf_cloud_rest_context.

Return values

0 – If successful. Otherwise, a (negative) error code is returned.

void nrf_cloud_rest_fota_job_free(struct nrf_cloud_fota_job_info *const job)

Frees memory allocated by nrf_cloud_rest_fota_job_get.

Parameters

  • job – [inout] Job info to be freed.

int nrf_cloud_rest_fota_job_update(struct nrf_cloud_rest_context *const rest_ctx, const char *const device_id, const char *const job_id, const enum nrf_cloud_fota_status status, const char *const details)

Updates the status of the specified nRF Cloud FOTA job.

Parameters

  • rest_ctx – [inout] Context for communicating with nRF Cloud’s REST API.

  • device_id – [in] Null-terminated, unique device ID registered with nRF Cloud.

  • job_id – [in] Null-terminated FOTA job identifier.

  • status – [in] Status of the FOTA job.

  • details – [in] Null-terminated string containing details of the job, such as an error description.

Return values

0 – If successful. Otherwise, a (negative) error code is returned.

int nrf_cloud_rest_shadow_state_update(struct nrf_cloud_rest_context *const rest_ctx, const char *const device_id, const char *const shadow_json)

Updates the device’s “state” in the shadow via the UpdateDeviceState endpoint.

Parameters

  • rest_ctx – [inout] Context for communicating with nRF Cloud’s REST API.

  • device_id – [in] Null-terminated, unique device ID registered with nRF Cloud.

  • shadow_json – [in] Null-terminated JSON string to be written to the device’s shadow.

Return values

0 – If successful. Otherwise, a (negative) error code is returned.

int nrf_cloud_rest_shadow_service_info_update(struct nrf_cloud_rest_context *const rest_ctx, const char *const device_id, const struct nrf_cloud_svc_info *const svc_inf)

Updates the device’s “ServiceInfo” in the shadow.

Parameters

  • rest_ctx – [inout] Context for communicating with nRF Cloud’s REST API.

  • device_id – [in] Null-terminated, unique device ID registered with nRF Cloud.

  • svc_inf – [in] Service info items to be updated in the shadow.

Return values

0 – If successful. Otherwise, a (negative) error code is returned.

int nrf_cloud_rest_disconnect(struct nrf_cloud_rest_context *const rest_ctx)

Closes the connection to the server.

Parameters

  • rest_ctx – [inout] Context for communicating with nRF Cloud’s REST API.

Return values

0 – If successful. Otherwise, a (negative) error code is returned.

int nrf_cloud_rest_jitp(const sec_tag_t nrf_cloud_sec_tag)

Performs just-in-time provisioning (JITP) with nRF Cloud.

Note

After a device has been provisioned with nRF Cloud, it must be associated with an nRF Cloud account before using any other functions in this library.

Parameters

  • nrf_cloud_sec_tag – [in] Modem sec_tag containing nRF Cloud JITP credentials

Return values

  • 0 – If successful; wait 30s before associating device with nRF Cloud account.

  • 1 – Device is already provisioned. Otherwise, a (negative) error code is returned.

int nrf_cloud_rest_send_device_message(struct nrf_cloud_rest_context *const rest_ctx, const char *const device_id, const char *const json_msg, const bool bulk, const char *const topic)

Send a JSON formatted device message using the SendDeviceMessage endpoint.

Parameters

  • rest_ctx – [inout] Context for communicating with nRF Cloud’s REST API.

  • device_id – [in] Null-terminated, unique device ID registered with nRF Cloud.

  • json_msg – [in] Null-terminated JSON string containing the device message.

  • bulk – [in] Use the bulk message topic. If true, the topic parameter is ignored.

  • topic – [in] Optional; null-terminated MQTT topic string. If NULL, the d2c topic is used.

Return values

0 – If successful. Otherwise, a (negative) error code is returned.

int nrf_cloud_rest_send_location(struct nrf_cloud_rest_context *const rest_ctx, const char *const device_id, const char *const nmea_sentence, const int64_t ts_ms)

Send a supported NMEA sentence to nRF Cloud as a device message.

Parameters

  • rest_ctx – [inout] Context for communicating with nRF Cloud’s REST API.

  • device_id – [in] Null-terminated, unique device ID registered with nRF Cloud.

  • nmea_sentence – [in] Null-terminated NMEA sentence.

  • ts_ms – [in] UNIX epoch timestamp (in milliseconds) to include with the location data. A negative value will exclude the timestamp.

Return values

0 – If successful. Otherwise, a (negative) error code is returned.

struct nrf_cloud_rest_context
#include <nrf_cloud_rest.h>

Parameters and data for using the nRF Cloud REST API.

Public Members

int connect_socket

Connection socket; initialize to -1 and library will make the connection.

bool keep_alive

If the connection should remain after API call.

Note

A failed API call could result in the socket being closed.

int32_t timeout_ms

Timeout value, in milliseconds, for receiving response data. Minimum timeout value specified by NRF_CLOUD_REST_TIMEOUT_MINIMUM. For no timeout, set to NRF_CLOUD_REST_TIMEOUT_NONE.

Note

This parameter is currently not used; set CONFIG_REST_CLIENT_SCKT_RECV_TIMEOUT instead.

char *auth

Authentication string: JWT JWT generation. The nRF Cloud device ID must be included in the sub claim. If the device ID is the device’s internal UUID, the sub claim can be omitted for modem generated JWTs; the UUID is included in the iss claim.

char *rx_buf

User allocated buffer for receiving API response, which includes the HTTPS headers, any response data and a terminating NULL. Buffer size should be limited according to the maximum TLS receive size of the modem.

size_t rx_buf_len

Size of rx_buf

size_t fragment_size

Fragment size for downloads, set to zero to use CONFIG_NRF_CLOUD_REST_FRAGMENT_SIZE. The rx_buf must be able to hold the HTTPS headers plus this fragment size.

enum nrf_cloud_http_status status

Results from API call HTTP status of API call

char *response

Start of response content data in rx_buf

size_t response_len

Length of response content data

size_t total_response_len

Length of HTTPS headers + response content data

struct nrf_cloud_rest_cell_pos_request
#include <nrf_cloud_rest.h>

Data required for nRF Cloud cellular positioning request.

Public Members

struct lte_lc_cells_info *net_info

Network information used in request

struct nrf_cloud_rest_agps_request
#include <nrf_cloud_rest.h>

Data required for nRF Cloud Assisted GPS (A-GPS) request.

Public Members

struct nrf_modem_gnss_agps_data_frame *agps_req

Required for custom request type

struct lte_lc_cells_info *net_info

Optional; provide network info or set to NULL. The cloud cannot provide location assistance data if network info is NULL.

bool filtered

Reduce set of ephemerides to only those visible at current location. This reduces the overall size of the download, but may increase fix times towards the end of the validity period and/or if the device is actively traveling long distances.

uint8_t mask_angle

Constrain the set of ephemerides to only those currently visible at or above the specified elevation threshold angle in degrees. Range is 0 to 90.

struct nrf_cloud_rest_agps_result
#include <nrf_cloud_rest.h>

nRF Cloud Assisted GPS (A-GPS) result

Public Members

char *buf

User-provided buffer to hold AGPS data

size_t buf_sz

Size of user-provided buffer

size_t agps_sz

Size of the AGPS data copied into buffer

struct nrf_cloud_rest_pgps_request
#include <nrf_cloud_rest.h>

Data required for nRF Cloud Predicted GPS (P-GPS) request.

Public Members

const struct gps_pgps_request *pgps_req

Data to be included in the P-GPS request. To omit an item use the appropriate define in Omit item from P-GPS request.