lib: nrfcloud: add timestamped location request

Add feature to support timestamped location requests to nRF Cloud.

Signed-off-by: Maximilian Deubel <[email protected]>

Author: maxd-nordic

doc/nrf/releases_and_maturity/releases/release-notes-changelog.rst

@@ -740,6 +740,7 @@ Libraries for networking
 
 * :ref:`lib_nrf_cloud` library:
 
+  * Added the :c:func:`nrf_cloud_obj_location_request_create_timestamped` function to make location requests for past cellular or Wi-Fi scans.
   * Updated by refactoring the folder structure of the library to separate the different backend implementations.
 
 * :ref:`lib_downloader` library:

include/net/nrf_cloud_codec.h

@@ -636,6 +636,33 @@ int nrf_cloud_obj_cloud_encoded_free(struct nrf_cloud_obj *const obj);
 int nrf_cloud_obj_gnss_msg_create(struct nrf_cloud_obj *const obj,
 				  const struct nrf_cloud_gnss_data * const gnss);
 
+/**
+ * @brief Create an nRF Cloud Location request message object with a timestamp.
+ *
+ * @details If successful, memory is allocated for the provided object.
+ *          The @ref nrf_cloud_obj_free function should be called when finished with the object.
+ *
+ * @param[out] obj Uninitialzed object to contain the Location message.
+ * @param[in] cells_inf Cellular network data, can be NULL if wifi_inf is provided.
+ * @param[in] wifi_inf Wi-Fi network data, can be NULL if cells_inf is provided.
+ * @param[in] config Optional configuration of request. If NULL, use cloud defaults.
+ * @param[in] timestamp Optional UTC timestamp (milliseconds) of request, or 0 to omit.
+ *
+ * @retval -EINVAL Invalid parameter.
+ * @retval -EDOM Too few Wi-Fi networks, see NRF_CLOUD_LOCATION_WIFI_AP_CNT_MIN.
+ * @retval -EBADF Invalid object type.
+ * @retval -ENOTEMPTY Object already initialized.
+ * @retval -ENOMEM Out of memory.
+ * @retval 0 Success; GNSS message created.
+ */
+int nrf_cloud_obj_location_request_create_timestamped(
+	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,
+	int64_t timestamp
+);
+
 /**
  * @brief Create an nRF Cloud Location request message object.
  *

include/net/nrf_cloud_location.h

@@ -91,6 +91,9 @@ struct nrf_cloud_location_result {
 
 	/** Size of provided buffer */
 	size_t anchor_buf_sz;
+
+	/** Optional timestamp */
+	int64_t timestamp;
 };
 
 /** @brief Location request config */

subsys/net/lib/nrf_cloud/common/src/nrf_cloud_codec.c

@@ -945,10 +945,13 @@ int nrf_cloud_obj_modem_pvt_add(struct nrf_cloud_obj *const obj,
 }
 #endif /* CONFIG_NRF_MODEM */
 
-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)
+int nrf_cloud_obj_location_request_create_timestamped(
+	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,
+	int64_t timestamp
+)
 {
 	if ((!cells_inf && !wifi_inf) || !obj) {
 		return -EINVAL;
@@ -1035,6 +1038,10 @@ int nrf_cloud_obj_location_request_create(struct nrf_cloud_obj *const obj,
 	}
 	/* The data object now belongs to the location request object */
 
+	if (timestamp) {
+		cJSON_AddNumberToObjectCS(obj->json, NRF_CLOUD_MSG_TIMESTAMP_KEY, timestamp);
+	}
+
 	return 0;
 
 cleanup:
@@ -1044,6 +1051,16 @@ int nrf_cloud_obj_location_request_create(struct nrf_cloud_obj *const obj,
 	return err;
 }
 
+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)
+{
+	return nrf_cloud_obj_location_request_create_timestamped(
+		obj, cells_inf, wifi_inf, config, 0
+	);
+}
+
 #if defined(CONFIG_NRF_CLOUD_PGPS)
 int nrf_cloud_obj_pgps_request_create(struct nrf_cloud_obj *const obj,
 				      const struct gps_pgps_request *const request)

subsys/net/lib/nrf_cloud/common/src/nrf_cloud_codec_internal.c

@@ -2287,6 +2287,19 @@ static bool json_item_string_exists(const cJSON *const obj, const char *const ke
 	return (strcmp(str_val, val) == 0);
 }
 
+static int64_t get_timestamp(const cJSON *const obj)
+{
+	__ASSERT_NO_MSG(obj != NULL);
+
+	cJSON *item = cJSON_GetObjectItem(obj, NRF_CLOUD_MSG_TIMESTAMP_KEY);
+
+	if (item) {
+		return cJSON_GetNumberValue(item);
+	}
+
+	return 0;
+}
+
 static void
 nrf_cloud_parse_location_anchors_json(const cJSON *const loc_obj,
 				      struct nrf_cloud_location_result *const location_out)
@@ -2476,6 +2489,8 @@ int nrf_cloud_location_response_decode(const char *const buf,
 		goto cleanup;
 	}
 
+	result->timestamp = get_timestamp(loc_obj);
+
 	/* MQTT payload format found, parse the data */
 	data_obj = cJSON_GetObjectItem(loc_obj, NRF_CLOUD_JSON_DATA_KEY);
 	if (data_obj) {