samples: bluetooth: Add Channel Sounding Initiator with RREQ sample

This sample can be used to set up a Channel Sounding Initiator with
the GATT Ranging Requestor client.
It can connect to Channel Sounding Reflector with Ranging Responder
sample to request CS Ranging Data from.
A simple distance estimation algorithm is included. This uses the
same logic as the Zephyr Channel Sounding sample.

Signed-off-by: Sean Madigan <[email protected]>

CODEOWNERS

@@ -411,6 +411,7 @@
 /samples/bluetooth/central_nfc_pairing/   @nrfconnect/ncs-si-muffin
 /samples/bluetooth/central_smp_client/    @nrfconnect/ncs-si-muffin
 /samples/bluetooth/central_uart/          @nrfconnect/ncs-si-muffin
+/samples/bluetooth/channel_sounding_ras_initiator/ @nrfconnect/ncs-dragoon
 /samples/bluetooth/channel_sounding_ras_reflector/ @nrfconnect/ncs-dragoon
 /samples/bluetooth/conn_time_sync/        @nrfconnect/ncs-dragoon
 /samples/bluetooth/direction_finding_central/ @nrfconnect/ncs-dragoon

doc/nrf/links.txt

@@ -1013,6 +1013,9 @@
 .. _`Auracast™`: https://www.bluetooth.com/auracast/how-it-works/
 .. _`Basic Audio Profile specification`: https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/16212-BAP-html5/out/en/index-en.html#UUID-c9d31763-9ede-2270-6b9c-c042ae684cc3
 
+.. _`Distance estimation based on phase and amplitude information`: https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-60/out/en/architecture,-change-history,-and-conventions/architecture.html#UUID-a8d03618-5fcf-3043-2198-559653272b1b
+.. _`Distance estimation based on RTT packets`: https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-60/out/en/architecture,-change-history,-and-conventions/architecture.html#UUID-9d4969af-baa6-b7e4-03ca-70b340877adf
+
 .. ### Source: openmobilealliance.org
 
 .. _`SUPL context model`: https://www.openmobilealliance.org/release/SUPL/V1_0-20060127-C/OMA-AD-SUPL-V1_0-20060127-C.pdf#page=16

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

@@ -249,6 +249,7 @@ Bluetooth samples
 * Added:
 
   * The :ref:`channel_sounding_ras_reflector` sample demonstrating how to implement a Channel Sounding Reflector that exposes the Ranging Responder GATT Service.
+  * The :ref:`channel_sounding_ras_initiator` sample demonstrating basic distance estimation with Channel Sounding by setting up a Channel Sounding Initiator that acts as a Ranging Requestor GATT Client.
 
 * Updated:
 

samples/bluetooth/channel_sounding_ras_initiator/CMakeLists.txt

@@ -0,0 +1,17 @@
+#
+# Copyright (c) 2024 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(NONE)
+
+FILE(GLOB app_sources src/*.c)
+# NORDIC SDK APP START
+target_sources(app PRIVATE
+	${app_sources}
+)
+# NORDIC SDK APP END

samples/bluetooth/channel_sounding_ras_initiator/README.rst

@@ -0,0 +1,91 @@
+.. _channel_sounding_ras_initiator:
+
+Bluetooth: Channel Sounding Initiator with Ranging Requestor
+############################################################
+
+.. contents::
+   :local:
+   :depth: 2
+
+This sample demonstrates how to use the ranging service to request ranging data from a server.
+It also provides a basic distance estimation algorithm to show how channel sounding can be used to estimate distance between two devices.
+
+Requirements
+************
+
+The sample supports the following development kits:
+
+.. table-from-sample-yaml::
+
+The sample also requires a device running a Channel Sounding Reflector with Ranging Responder to connect to, such as the :ref:`channel_sounding_ras_reflector` sample.
+
+Overview
+********
+
+The sample demonstrates a basic Bluetooth® Low Energy Central role functionality that acts as a GATT Ranging Requestor client and configures the Channel Sounding initiator role.
+Regular Channel Sounding procedures are set up, local subevent data is stored, and peer ranging data is fetched.
+
+A basic distance estimation algorithm is included in the sample.
+The mathematical representations described in `Distance estimation based on phase and amplitude information`_ and `Distance estimation based on RTT packets`_ are used as the basis for this algorithm.
+
+User interface
+**************
+
+The sample does not require user input and will scan for a device advertising with the GATT Ranging Service UUID.
+The first LED on the development kit will be lit when a connection has been established.
+
+Building and running
+********************
+.. |sample path| replace:: :file:`samples/bluetooth/channel_sounding_ras_initiator`
+
+.. include:: /includes/build_and_run.txt
+
+Testing
+=======
+
+After programming the sample to your development kit, you can test it by connecting to another device programmed with a Channel Sounding Reflector role with Ranging Responder, such as the :ref:`channel_sounding_ras_reflector` sample.
+
+1. |connect_terminal_specific|
+#. Reset both kits.
+#. Wait until the scanner detects the Peripheral.
+   In the terminal window, check for information similar to the following::
+
+      I: Filters matched. Address: XX:XX:XX:XX:XX:XX (random) connectable: 1
+      I: Connecting
+      I: Connected to XX:XX:XX:XX:XX:XX (random) (err 0x00)
+      I: Security changed: XX:XX:XX:XX:XX:XX (random) level 2
+      I: MTU exchange success (498)
+      I: The discovery procedure succeeded
+      I: CS capability exchange completed.
+      I: CS config creation complete. ID: 0
+      I: CS security enabled.
+      I: CS procedures enabled.
+      I: Subevent result callback 0
+      I: Ranging data ready 0
+      I: Ranging data get completed for ranging counter 0
+      I: Estimated distance to reflector:
+      I: - Round-Trip Timing method: X.XXXXX meters (derived from X samples)
+      I: - Phase-Based Ranging method: X.XXXXX meters (derived from X samples)
+
+Dependencies
+************
+
+This sample uses the following |NCS| libraries:
+
+* :ref:`dk_buttons_and_leds_readme`
+* :file:`include/bluetooth/gatt_dm.h`
+* :file:`include/bluetooth/services/ras.h`
+
+This sample uses the following Zephyr libraries:
+
+* :file:`include/sys/printk.h`
+* :file:`include/zephyr/types.h`
+* :ref:`zephyr:kernel_api`:
+
+  * :file:`include/kernel.h`
+
+* :ref:`zephyr:bluetooth_api`:
+
+* :file:`include/bluetooth/bluetooth.h`
+* :file:`include/bluetooth/conn.h`
+* :file:`include/bluetooth/cs.h`

samples/bluetooth/channel_sounding_ras_initiator/prj.conf

@@ -0,0 +1,37 @@
+#
+# Copyright (c) 2024 Nordic Semiconductor ASA
+#
+# SPDX-License-Identifier: LicenseRef-Nordic-5-Clause
+#
+
+CONFIG_NCS_SAMPLES_DEFAULTS=y
+CONFIG_DK_LIBRARY=y
+
+CONFIG_BT=y
+CONFIG_BT_SMP=y
+CONFIG_BT_CENTRAL=y
+CONFIG_BT_MAX_CONN=1
+CONFIG_BT_BONDABLE=n
+
+CONFIG_BT_GATT_CLIENT=y
+CONFIG_BT_GATT_DYNAMIC_DB=y
+
+CONFIG_BT_CHANNEL_SOUNDING=y
+CONFIG_BT_RAS=y
+CONFIG_BT_RAS_RREQ=y
+
+CONFIG_BT_SCAN=y
+CONFIG_BT_SCAN_FILTER_ENABLE=y
+CONFIG_BT_SCAN_UUID_CNT=1
+
+# The Ranging Profile recommends a MTU of at least 247 octets.
+CONFIG_BT_L2CAP_TX_MTU=498
+CONFIG_BT_BUF_ACL_TX_SIZE=502
+CONFIG_BT_BUF_ACL_RX_SIZE=502
+CONFIG_BT_ATT_PREPARE_COUNT=3
+CONFIG_BT_CTLR_DATA_LENGTH_MAX=251
+
+# This allows CS and ACL to use different PHYs
+CONFIG_BT_TRANSMIT_POWER_CONTROL=y
+
+CONFIG_CBPRINTF_FP_SUPPORT=y

samples/bluetooth/channel_sounding_ras_initiator/sample.yaml

@@ -0,0 +1,12 @@
+sample:
+  description: Bluetooth Low Energy Channel Sounding Initiator with Ranging Service Requestor
+  name: Bluetooth LE Channel Sounding Initiator with RREQ
+tests:
+  sample.bluetooth.channel_sounding_ras_initiator:
+    sysbuild: true
+    build_only: true
+    integration_platforms:
+      - nrf54l15dk/nrf54l15/cpuapp
+    platform_allow:
+      - nrf54l15dk/nrf54l15/cpuapp
+    tags: bluetooth ci_build sysbuild