samples: cellular: add nrf_cloud_coap_cell_location sample

maxd-nordic · nordicjm · commit 734f2ae80e90 · 2025-08-19T06:51:11.000+01:00
This sample demonstrates how to use the nRF Cloud CoAP API
to request position using cellular network information.

Signed-off-by: Maximilian Deubel &lt;maximilian.deubel@nordicsemi.no&gt;
diff --git a/doc/nrf/links.txt b/doc/nrf/links.txt
@@ -1480,6 +1480,7 @@
 .. _`nRF Cloud Location Services`: https://api.nrfcloud.com/v1#tag/Location-Services
 .. _`nRF Cloud REST API ProvisionDevices`: https://api.nrfcloud.com/v1#tag/IP-Devices/operation/ProvisionDevices
 .. _`nRF Cloud RegisterPublicKeys Endpoint`: https://api.nrfcloud.com/v1/#operation/RegisterPublicKeys
+.. _`nRF Cloud CoAP API`: https://docs.nordicsemi.com/bundle/nrf-cloud/page/APIs/CoAP/CoAPOverview.html
 
 .. _`Bulk Onboard Devices`:
 .. _`nRF Cloud Portal Bulk Onboard Devices`: https://nrfcloud.com/#/add-device/bulk
diff --git a/doc/nrf/releases_and_maturity/releases/release-notes-changelog.rst b/doc/nrf/releases_and_maturity/releases/release-notes-changelog.rst
@@ -261,11 +261,11 @@ Bluetooth Fast Pair samples
 Cellular samples
 ----------------
 
-* :ref:`nrf_cloud_rest_cell_location` sample:
+* Added the :ref:`nrf_cloud_coap_cell_location` sample to demonstrate how to use the `nRF Cloud CoAP API`_ for nRF Cloud's cellular location service.
 
-  * Added:
+* :ref:`nrf_cloud_rest_cell_location` sample:
 
-    * Runtime setting of the log level for the nRF Cloud logging feature.
+  * Added runtime setting of the log level for the nRF Cloud logging feature.
 
 Cryptography samples
 --------------------
diff --git a/samples/cellular/nrf_cloud_coap_cell_location/CMakeLists.txt b/samples/cellular/nrf_cloud_coap_cell_location/CMakeLists.txt
@@ -0,0 +1,12 @@
+#
+# Copyright (c) 2025 Nordic Semiconductor
+#
+# SPDX-License-Identifier: LicenseRef-Nordic-5-Clause
+#
+
+cmake_minimum_required(VERSION 3.20.0)
+
+find_package(Zephyr REQUIRED HINTS $ENV{ZEPHYR_BASE})
+project(nrf_cloud_coap_cell_location_sample)
+
+target_sources(app PRIVATE src/main.c)
diff --git a/samples/cellular/nrf_cloud_coap_cell_location/Kconfig b/samples/cellular/nrf_cloud_coap_cell_location/Kconfig
@@ -0,0 +1,45 @@
+#
+# Copyright (c) 2025 Nordic Semiconductor ASA
+#
+# SPDX-License-Identifier: LicenseRef-Nordic-5-Clause
+#
+
+menu "nRF Cloud CoAP Cellular Location Sample"
+
+config COAP_CELL_GCI_COUNT
+	int "Maximum number of cells to be searched"
+	range 2 15
+	default 5
+
+config COAP_CELL_CHANGE_CONFIG
+	bool "Change the location request configuration on button press"
+	default y
+	help
+	  After attempting both single and multi cell location requests,
+	  try the next combination of the struct nrf_cloud_location_config
+	  hi_conf and fallback flags. The do_reply flag is not modified.
+
+config COAP_CELL_DEFAULT_DOREPLY_VAL
+	bool "Default value for the do_reply configuration flag"
+	default y
+
+config COAP_CELL_DEFAULT_FALLBACK_VAL
+	bool "Default value for the fallback configuration flag"
+	default y
+
+config COAP_CELL_DEFAULT_HICONF_VAL
+	bool "Default value for the hi_conf configuration flag"
+
+config COAP_CELL_SEND_DEVICE_STATUS
+	bool "Send device status to nRF Cloud on initial connection"
+	default y
+
+module = NRF_CLOUD_COAP_CELL_LOCATION_SAMPLE
+module-str = nRF Cloud CoAP Cellular Location Sample
+source "${ZEPHYR_BASE}/subsys/logging/Kconfig.template.log_config"
+
+endmenu
+
+menu "Zephyr Kernel"
+source "Kconfig.zephyr"
+endmenu
diff --git a/samples/cellular/nrf_cloud_coap_cell_location/README.rst b/samples/cellular/nrf_cloud_coap_cell_location/README.rst
@@ -0,0 +1,198 @@
+.. _nrf_cloud_coap_cell_location:
+
+Cellular: nRF Cloud CoAP cellular location
+##########################################
+
+.. contents::
+   :local:
+   :depth: 2
+
+This sample demonstrates how to use the `nRF Cloud CoAP API`_ for nRF Cloud's cellular location service on your device.
+
+Requirements
+************
+
+The sample supports the following development kits:
+
+.. table-from-sample-yaml::
+
+.. include:: /includes/tfm.txt
+
+The sample requires an `nRF Cloud`_ account.
+Your device must be onboarded to nRF Cloud.
+If it is not, follow the instructions in `Device on-boarding <nrf_cloud_coap_cell_location_onboarding>`_.
+
+.. note::
+   This sample requires modem firmware v1.3.x or later for an nRF9160 DK, or modem firmware v2.x.x for the nRF9161 and nRF9151 DKs.
+
+Overview
+********
+
+The sample can work in two modes: single-cell mode and multi-cell mode.
+
+After the sample initializes and connects to the network, it enters the single-cell mode and sends a single-cell location request to nRF Cloud.
+For this purpose, the sample uses network data obtained from the :ref:`modem_info_readme` library.
+In the multi-cell mode, the sample requests for neighbor cell measurement using the :ref:`lte_lc_readme` library.
+
+If the modem provides neighbor cell data, the sample sends a multi-cell location request to nRF Cloud.
+Otherwise, the request is single-cell.
+
+In either mode, the sample sends a new location request if a change in cell ID is detected.
+
+See the `nRF Cloud Location Services documentation`_ for additional information.
+
+User interface
+**************
+
+Button 1:
+   Toggle between the single-cell and multi-cell mode.
+
+.. _nrf_cloud_coap_cell_location_onboarding:
+
+Setup
+=====
+
+You must onboard your device to nRF Cloud for this sample to function.
+You only need to do this once for each device.
+To onboard your device, install `nRF Cloud Utils`_ and follow the instructions in the README.
+
+Configuration
+*************
+
+|config|
+
+Configuration options
+=====================
+
+Check and configure the following Kconfig options for the sample:
+
+.. _CONFIG_COAP_CELL_CHANGE_CONFIG:
+
+CONFIG_COAP_CELL_CHANGE_CONFIG - Enable changing request configuration
+   Set this to use the next combination of ``hi_conf`` and ``fallback`` flags after performing both single- and multi-cell location requests.
+
+.. _CONFIG_COAP_CELL_DEFAULT_DOREPLY_VAL:
+
+CONFIG_COAP_CELL_DEFAULT_DOREPLY_VAL - Enable return of location from cloud
+   If enabled, request the cloud to return the location information.
+
+.. _CONFIG_COAP_CELL_DEFAULT_FALLBACK_VAL:
+
+CONFIG_COAP_CELL_DEFAULT_FALLBACK_VAL - Enable fallback to coarse location
+   If enabled and the location of the cell tower or Wi-Fi® access points cannot be found, return area-level location based on the cellular tracking area code.
+   Otherwise an error will be returned indicating location is not known.
+
+.. _CONFIG_COAP_CELL_DEFAULT_HICONF_VAL:
+
+CONFIG_COAP_CELL_DEFAULT_HICONF_VAL - Enable high-confidence result
+   Enable a 95% confidence interval for the location, instead of the default 68%.
+
+.. _CONFIG_COAP_CELL_SEND_DEVICE_STATUS:
+
+CONFIG_COAP_CELL_SEND_DEVICE_STATUS - Send device status
+   Send device status to nRF Cloud on initial connection.
+
+.. include:: /libraries/modem/nrf_modem_lib/nrf_modem_lib_trace.rst
+   :start-after: modem_lib_sending_traces_UART_start
+   :end-before: modem_lib_sending_traces_UART_end
+
+Building and running
+********************
+
+.. |sample path| replace:: :file:`samples/cellular/nrf_cloud_coap_cell_location`
+
+.. include:: /includes/build_and_run_ns.txt
+
+Testing
+=======
+
+|test_sample|
+
+#. |connect_kit|
+#. |connect_terminal|
+#. Reset the development kit.
+#. Observe in the terminal window that the application starts.
+   This is indicated by output similar to the following (there is also a lot of additional information about the LTE connection):
+
+   .. code-block:: console
+
+      *** Booting nRF Connect SDK v3.0.99-065f86a42eaa ***
+      *** Using Zephyr OS v4.1.99-82973b4f6d2a ***
+      Attempting to boot slot 0.
+      Attempting to boot from address 0x8200.
+      I: Trying to get Firmware version
+      I: Verifying signature against key 0.
+      I: Hash: 0x3e...f9
+      I: Firmware signature verified.
+      Firmware version 2
+      �[00:00:00.254,821] <inf> spi_nor: GD25LE255E@0: 32 MiBy flash
+      *** Booting My Application v1.0.0-065f86a42eaa ***
+      *** Using nRF Connect SDK v3.0.99-065f86a42eaa ***
+      *** Using Zephyr OS v4.1.99-82973b4f6d2a ***
+      [00:00:00.292,907] <inf> nrf_cloud_coap_cell_location_sample: nRF Cloud CoAP Cellular Location Sample, version: 1.0.0
+      [00:00:00.715,637] <inf> nrf_cloud_coap_cell_location_sample: Device ID: 7e699894-79b6-11f0-a2b4-db93a314a2aa
+      [00:00:00.721,313] <inf> nrf_cloud_coap_cell_location_sample: Using LTE LC neighbor search type GCI extended complete for 5 cells
+      [00:00:01.023,040] <inf> nrf_cloud_credentials: Sec Tag: 16842753; CA: Yes, Client Cert: Yes, Private Key: Yes
+      [00:00:01.023,101] <inf> nrf_cloud_credentials: CA Size: 1824, AWS: Likely, CoAP: Likely
+      [00:00:01.023,101] <inf> nrf_cloud_coap_cell_location_sample: nRF Cloud credentials detected!
+      [00:00:01.023,132] <inf> nrf_cloud_coap_cell_location_sample: Enabling connectivity...
+      +CGEV: EXCE STATUS 0
+      +CEREG: 2,"0910","020A6B0C",7
+      %MDMEV: PRACH CE-LEVEL 0
+      +CSCON: 1
+      [00:00:02.995,330] <inf> nrf_cloud_coap_cell_location_sample: RRC mode: connected
+      +CGEV: ME PDN ACT 0,0
+      +CNEC_ESM: 50,0
+      %MDMEV: SEARCH STATUS 2
+      +CEREG: 5,"0910","020A6B0C",7,,,"11100000","11100000"
+      [00:00:07.840,423] <inf> nrf_cloud_coap_cell_location_sample: Connected to network
+      [00:00:07.840,515] <inf> nrf_cloud_coap_cell_location_sample: Waiting for modem to acquire network time...
+      [00:00:10.841,247] <inf> nrf_cloud_coap_cell_location_sample: Network time obtained
+      [00:00:10.841,308] <inf> nrf_cloud_info: Device ID: 7e699894-79b6-11f0-a2b4-db93a314a2aa
+      [00:00:10.841,857] <inf> nrf_cloud_info: IMEI:      359400123456789
+      [00:00:10.941,680] <inf> nrf_cloud_info: UUID:      7e699894-79b6-11f0-a2b4-db93a314a2aa
+      [00:00:10.948,211] <inf> nrf_cloud_info: Modem FW:  mfw_nrf91x1_2.0.2
+      [00:00:10.948,242] <inf> nrf_cloud_info: Protocol:          CoAP
+      [00:00:10.948,272] <inf> nrf_cloud_info: Download protocol: HTTPS
+      [00:00:10.948,303] <inf> nrf_cloud_info: Sec tag:           16842753
+      [00:00:10.948,303] <inf> nrf_cloud_info: CoAP JWT Sec tag:  16842753
+      [00:00:10.948,333] <inf> nrf_cloud_info: Host name:         coap.nrfcloud.com
+      [00:00:12.721,099] <inf> nrf_cloud_coap_transport: Request authorization with JWT
+      [00:00:12.986,877] <inf> nrf_cloud_coap_transport: Authorization result_code: 2.01
+      [00:00:12.986,999] <inf> nrf_cloud_coap_transport: Authorized
+      [00:00:12.987,213] <inf> nrf_cloud_coap_transport: DTLS CID is active
+      [00:00:13.716,003] <inf> nrf_cloud_coap_cell_location_sample: Device status sent to nRF Cloud
+      [00:00:13.716,033] <inf> nrf_cloud_coap_cell_location_sample: Getting current cell info...
+      [00:00:13.725,494] <inf> nrf_cloud_coap_cell_location_sample: Current cell info: Cell ID: 34237196, TAC: 2320, MCC: 242, MNC: 2
+      [00:00:13.725,524] <inf> nrf_cloud_coap_cell_location_sample: Performing single-cell request
+      [00:00:13.725,524] <inf> nrf_cloud_coap_cell_location_sample: Request configuration:
+      [00:00:13.725,555] <inf> nrf_cloud_coap_cell_location_sample:   High confidence interval   = false
+      [00:00:13.725,616] <inf> nrf_cloud_coap_cell_location_sample:   Fallback to rough location = true
+      [00:00:13.725,646] <inf> nrf_cloud_coap_cell_location_sample:   Reply with result          = true
+      [00:00:13.991,180] <inf> nrf_cloud_coap_cell_location_sample: Cellular location request fulfilled with single-cell
+      [00:00:13.991,210] <inf> nrf_cloud_coap_cell_location_sample: Lat: 63.423740, Lon: 10.435896, Uncertainty: 1056 m
+
+Troubleshooting
+===============
+
+If you are not getting the output similar to the one in `Testing`_, check the following potential issues:
+
+The network carrier does not provide date and time
+   The sample requires the network carrier to provide date and time to the modem.
+   Without a valid date and time, the modem cannot generate JWTs with an expiration time.
+
+Dependencies
+************
+
+This sample uses the following |NCS| libraries:
+
+* :ref:`lib_nrf_cloud`
+* :ref:`lib_nrf_cloud_coap`
+* :ref:`lib_modem_jwt`
+* :ref:`lte_lc_readme`
+* :ref:`modem_info_readme`
+* :ref:`dk_buttons_and_leds_readme`
+
+In addition, it uses the following secure firmware component:
+
+* :ref:`Trusted Firmware-M <ug_tfm>`
diff --git a/samples/cellular/nrf_cloud_coap_cell_location/VERSION b/samples/cellular/nrf_cloud_coap_cell_location/VERSION
@@ -0,0 +1,5 @@
+VERSION_MAJOR = 1
+VERSION_MINOR = 0
+PATCHLEVEL = 0
+VERSION_TWEAK = 0
+EXTRAVERSION =
diff --git a/samples/cellular/nrf_cloud_coap_cell_location/prj.conf b/samples/cellular/nrf_cloud_coap_cell_location/prj.conf
@@ -0,0 +1,77 @@
+# Sample
+CONFIG_NRF_CLOUD_COAP_CELL_LOCATION_SAMPLE_LOG_LEVEL_INF=y
+
+# nRF Cloud CoAP
+CONFIG_NRF_CLOUD=y
+CONFIG_NRF_CLOUD_CLIENT_ID_SRC_INTERNAL_UUID=y
+CONFIG_MODEM_JWT=y
+CONFIG_POSIX_API=y
+CONFIG_NRF_CLOUD_CHECK_CREDENTIALS=y
+CONFIG_NRF_CLOUD_COAP=y
+CONFIG_NRF_CLOUD_COAP_DOWNLOADS=n
+
+# AT Host
+CONFIG_AT_HOST_LIBRARY=y
+CONFIG_NRF_MODEM_LIB=y
+CONFIG_AT_MONITOR_HEAP_SIZE=4096
+CONFIG_AT_HOST_STACK_SIZE=2048
+
+# Button support
+CONFIG_DK_LIBRARY=y
+CONFIG_GPIO=y
+
+# Networking
+CONFIG_NETWORKING=y
+CONFIG_NET_SOCKETS=y
+CONFIG_NET_SOCKETS_OFFLOAD=y
+
+# Enable LTE Connectivity using Connection Manager
+CONFIG_NET_IPV4=y
+CONFIG_NET_IPV6=y
+CONFIG_NET_IPV6_NBR_CACHE=n
+CONFIG_NET_IPV6_MLD=n
+CONFIG_NET_CONNECTION_MANAGER=y
+CONFIG_NRF_MODEM_LIB=y
+CONFIG_NRF_MODEM_LIB_NET_IF=y
+CONFIG_NRF_MODEM_LIB_NET_IF_AUTO_DOWN=y
+CONFIG_NRF_MODEM_LIB_NET_IF_DOWN_DEFAULT_LTE_DISCONNECT=y
+CONFIG_NET_CONNECTION_MANAGER_MONITOR_STACK_SIZE=1024
+CONFIG_NET_MGMT_EVENT_STACK_SIZE=1024
+
+# Modem/LTE Link
+CONFIG_LTE_LINK_CONTROL=y
+CONFIG_LTE_LC_NEIGHBOR_CELL_MEAS_MODULE=y
+
+# Modem info
+CONFIG_MODEM_INFO=y
+CONFIG_MODEM_INFO_ADD_DEVICE=y
+CONFIG_MODEM_INFO_ADD_NETWORK=y
+CONFIG_MODEM_INFO_ADD_DATE_TIME=n
+CONFIG_MODEM_INFO_ADD_SIM=y
+CONFIG_MODEM_INFO_ADD_SIM_ICCID=n
+CONFIG_MODEM_INFO_ADD_SIM_IMSI=n
+
+# System
+CONFIG_HEAP_MEM_POOL_SIZE=8192
+CONFIG_MAIN_STACK_SIZE=8192
+CONFIG_SYSTEM_WORKQUEUE_STACK_SIZE=8192
+CONFIG_ASSERT=y
+CONFIG_REBOOT=y
+CONFIG_FPU=y
+CONFIG_PICOLIBC_IO_FLOAT=y
+CONFIG_EVENTS=y
+
+# Logging
+CONFIG_LOG=y
+CONFIG_LOG_MODE_DEFERRED=y
+CONFIG_UART_INTERRUPT_DRIVEN=y
+
+# LTE Link Control
+CONFIG_LTE_LINK_CONTROL=y
+CONFIG_LTE_LC_PSM_MODULE=y
+
+# CoAP Client
+CONFIG_COAP_CLIENT_BLOCK_SIZE=1024
+CONFIG_COAP_CLIENT_STACK_SIZE=6144
+CONFIG_COAP_CLIENT_THREAD_PRIORITY=0
+CONFIG_COAP_EXTENDED_OPTIONS_LEN_VALUE=40
diff --git a/samples/cellular/nrf_cloud_coap_cell_location/sample.yaml b/samples/cellular/nrf_cloud_coap_cell_location/sample.yaml
@@ -0,0 +1,20 @@
+sample:
+  name: nRF Cloud CoAP cellular location
+tests:
+  sample.cellular.nrf_cloud_coap_cell_pos:
+    sysbuild: true
+    build_only: true
+    integration_platforms:
+      - nrf9151dk/nrf9151/ns
+      - nrf9160dk/nrf9160/ns
+      - nrf9161dk/nrf9161/ns
+      - thingy91x/nrf9151/ns
+    platform_allow:
+      - nrf9151dk/nrf9151/ns
+      - nrf9160dk/nrf9160/ns
+      - nrf9161dk/nrf9161/ns
+      - thingy91x/nrf9151/ns
+    tags:
+      - ci_build
+      - sysbuild
+      - ci_samples_cellular
diff --git a/samples/cellular/nrf_cloud_coap_cell_location/src/main.c b/samples/cellular/nrf_cloud_coap_cell_location/src/main.c
