bluetooth: samples: Add sample showing basic channel sounding features

samples/bluetooth/channel_sounding/README.rst

@@ -0,0 +1,133 @@
+.. zephyr:code-sample:: ble_cs
+   :name: Channel Sounding
+   :relevant-api: bt_gap bluetooth
+
+   Use Channel Sounding functionality.
+
+Overview
+********
+
+These samples demonstrates how to use the Bluetooth Channel Sounding feature.
+
+The CS Test sample shows how to us the CS test command to override randomization of certain channel
+sounding parameters, experiment with different configurations, or evaluate the RF medium. It can
+be found under :zephyr_file:`samples/bluetooth/channel_sounding/cs_test`.
+
+The connected CS sample shows how to set up regular channel sounding procedures on a connection
+between two devices.
+It can be found under :zephyr_file:`samples/bluetooth/channel_sounding/connected_cs`
+
+A basic distance estimation algorithm is included in both.
+The Channel Sounding feature does not mandate a specific algorithm for computing distance estimates,
+but the mathematical representation described in [#phase_and_amplitude]_ and [#rtt_packets]_ is used
+as a starting point for these samples.
+
+Distance estimation using channel sounding requires data from two devices, and for that reason
+the channel sounding results in the sample are exchanged in a simple way using a GATT characteristic.
+This limits the amount of data that can be processed at once to about 512 bytes from each device,
+which is enough to estimate distance using a handful of RTT timings and PBR phase samples across
+about 35-40 channels, assuming a single antenna path.
+
+Both samples will perform channel sounding procedures repeatedly and print regular distance estimates to
+the console. They are designed assuming a single subevent per procedure.
+
+Diagrams illustrating the steps involved in setting up channel sounding procedures between two
+connected devices are available in [#cs_setup_phase]_ and [#cs_start]_.
+
+Requirements
+************
+
+* Two boards with Bluetooth LE and Channel Sounding support (such as an :ref:`nRF54L15 <nrf54l15dk_nrf54l15>`)
+* A controller that supports the Channel Sounding feature
+
+Building and Running
+********************
+
+These samples can be found under :zephyr_file:`samples/bluetooth/channel_sounding` in
+the Zephyr tree.
+
+See :zephyr:code-sample-category:`bluetooth` samples for details.
+
+These sample use two applications, so two devices need to be setup.
+Flash one device with the initiator application, and another device with the
+reflector application.
+
+The devices should perform distance estimations repeatedly every few seconds if they are close enough.
+
+Here is an example output from the connected CS sample:
+
+Reflector:
+
+.. code-block:: console
+
+        *** Using Zephyr OS v3.7.99-585fbd2e318c ***
+        Starting Channel Sounding Demo
+        Connected to EC:E7:DB:66:14:86 (random) (err 0x00)
+        MTU exchange success (247)
+        Discovery: attr 0x20006a2c
+        UUID 87654321-4567-2389-1254-f67f9fedcba8
+        Found expected UUID
+        CS capability exchange completed.
+        CS config creation complete. ID: 0
+        CS security enabled.
+        CS procedures enabled.
+
+
+Initiator:
+
+.. code-block:: console
+
+        *** Using Zephyr OS v3.7.99-585fbd2e318c ***
+        Starting Channel Sounding Demo
+        Found device with name CS Sample, connecting...
+        Connected to C7:78:79:CD:16:B9 (random) (err 0x00)
+        MTU exchange success (247)
+        CS capability exchange completed.
+        CS config creation complete. ID: 0
+        CS security enabled.
+        CS procedures enabled.
+        Estimated distance to reflector:
+        - Round-Trip Timing method: 2.633891 meters (derived from 7 samples)
+        - Phase-Based Ranging method: 0.511853 meters (derived from 38 samples)
+
+
+Here is an example output from the CS Test sample:
+
+Reflector:
+
+.. code-block:: console
+
+        *** Using Zephyr OS v3.7.99-585fbd2e318c ***
+        Starting Channel Sounding Demo
+        Connected to C7:78:79:CD:16:B9 (random) (err 0x00)
+        MTU exchange success (247)
+        Discovery: attr 0x20006544
+        UUID 87654321-4567-2389-1254-f67f9fedcba8
+        Found expected UUID
+        Disconnected (reason 0x13)
+        Re-running CS test...
+
+
+Initiator:
+
+.. code-block:: console
+
+        *** Using Zephyr OS v3.7.99-585fbd2e318c ***
+        Starting Channel Sounding Demo
+        Found device with name CS Test Sample, connecting...
+        Connected to EC:E7:DB:66:14:86 (random) (err 0x00)
+        MTU exchange success (247)
+        Estimated distance to reflector:
+        - Round-Trip Timing method: 0.374741 meters (derived from 4 samples)
+        - Phase-Based Ranging method: 0.588290 meters (derived from 35 samples)
+        Disconnected (reason 0x16)
+        Re-running CS test...
+
+
+References
+**********
+
+.. [#phase_and_amplitude] `Bluetooth Core Specification v. 6.0: Vol. 1, Part A, 9.2 <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>`_
+.. [#rtt_packets] `Bluetooth Core Specification v. 6.0: Vol. 1, Part A, 9.3 <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>`_
+.. [#cs_setup_phase] `Bluetooth Core Specification v. 6.0: Vol. 6, Part D, 6.34 <https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-60/out/en/low-energy-controller/message-sequence-charts.html#UUID-73ba2c73-f3c8-3b1b-2bdb-b18174b88059>`_
+.. [#cs_start] `Bluetooth Core Specification v. 6.0: Vol. 6, Part D, 6.35 <https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-60/out/en/low-energy-controller/message-sequence-charts.html#UUID-c75cd2f9-0dd8-bd38-9afc-c7becfa7f073>`_

samples/bluetooth/channel_sounding/connected_cs/initiator/CMakeLists.txt

@@ -0,0 +1,11 @@
+# SPDX-License-Identifier: Apache-2.0
+
+cmake_minimum_required(VERSION 3.20.0)
+find_package(Zephyr REQUIRED HINTS $ENV{ZEPHYR_BASE})
+project(connected_cs_initiator)
+
+target_sources(app PRIVATE ../../src/connected_cs_initiator.c ../../src/distance_estimation.c)
+
+zephyr_library_include_directories(
+        ${CMAKE_CURRENT_LIST_DIR}/../../include
+)

samples/bluetooth/channel_sounding/connected_cs/initiator/prj.conf

@@ -0,0 +1,16 @@
+CONFIG_BT=y
+CONFIG_BT_SMP=y
+CONFIG_BT_CENTRAL=y
+CONFIG_BT_GAP_AUTO_UPDATE_CONN_PARAMS=n
+CONFIG_BT_GATT_CLIENT=y
+CONFIG_BT_GATT_DYNAMIC_DB=y
+CONFIG_BT_ATT_PREPARE_COUNT=3
+CONFIG_BT_CHANNEL_SOUNDING=y
+
+CONFIG_BT_BUF_ACL_RX_SIZE=251
+CONFIG_BT_BUF_ACL_TX_SIZE=251
+CONFIG_BT_L2CAP_TX_MTU=247
+
+CONFIG_MAIN_STACK_SIZE=4096
+
+CONFIG_CBPRINTF_FP_SUPPORT=y

samples/bluetooth/channel_sounding/connected_cs/initiator/sample.yaml

@@ -0,0 +1,11 @@
+sample:
+  name: Bluetooth Channel Sounding - Initiator
+tests:
+  sample.bluetooth.channel_sounding.connected_cs.initiator:
+    harness: bluetooth
+    platform_allow:
+      - qemu_cortex_m3
+      - qemu_x86
+    tags: bluetooth
+    integration_platforms:
+      - qemu_cortex_m3

samples/bluetooth/channel_sounding/connected_cs/reflector/CMakeLists.txt

@@ -0,0 +1,11 @@
+# SPDX-License-Identifier: Apache-2.0
+
+cmake_minimum_required(VERSION 3.20.0)
+find_package(Zephyr REQUIRED HINTS $ENV{ZEPHYR_BASE})
+project(connected_cs_reflector)
+
+target_sources(app PRIVATE ../../src/connected_cs_reflector.c ../../src/distance_estimation.c)
+
+zephyr_library_include_directories(
+        ${CMAKE_CURRENT_LIST_DIR}/../../include
+)

samples/bluetooth/channel_sounding/connected_cs/reflector/prj.conf

@@ -0,0 +1,14 @@
+CONFIG_BT=y
+CONFIG_BT_SMP=y
+CONFIG_BT_PERIPHERAL=y
+CONFIG_BT_GAP_AUTO_UPDATE_CONN_PARAMS=n
+CONFIG_BT_GATT_CLIENT=y
+CONFIG_BT_CHANNEL_SOUNDING=y
+
+CONFIG_BT_BUF_ACL_RX_SIZE=251
+CONFIG_BT_BUF_ACL_TX_SIZE=251
+CONFIG_BT_L2CAP_TX_MTU=247
+
+CONFIG_MAIN_STACK_SIZE=4096
+
+CONFIG_CBPRINTF_FP_SUPPORT=y

samples/bluetooth/channel_sounding/connected_cs/reflector/sample.yaml

@@ -0,0 +1,11 @@
+sample:
+  name: Bluetooth Channel Sounding - Reflector
+tests:
+  sample.bluetooth.channel_sounding.connected_cs.reflector:
+    harness: bluetooth
+    platform_allow:
+      - qemu_cortex_m3
+      - qemu_x86
+    tags: bluetooth
+    integration_platforms:
+      - qemu_cortex_m3

samples/bluetooth/channel_sounding/cs_test/initiator/CMakeLists.txt

@@ -0,0 +1,11 @@
+# SPDX-License-Identifier: Apache-2.0
+
+cmake_minimum_required(VERSION 3.20.0)
+find_package(Zephyr REQUIRED HINTS $ENV{ZEPHYR_BASE})
+project(cs_test_initiator)
+
+target_sources(app PRIVATE ../../src/cs_test_initiator.c ../../src/distance_estimation.c)
+
+zephyr_library_include_directories(
+        ${CMAKE_CURRENT_LIST_DIR}/../../include
+)

samples/bluetooth/channel_sounding/cs_test/initiator/prj.conf

@@ -0,0 +1,15 @@
+CONFIG_BT=y
+CONFIG_BT_CENTRAL=y
+CONFIG_BT_GATT_CLIENT=y
+CONFIG_BT_GATT_DYNAMIC_DB=y
+CONFIG_BT_ATT_PREPARE_COUNT=3
+CONFIG_BT_CHANNEL_SOUNDING=y
+CONFIG_BT_CHANNEL_SOUNDING_TEST=y
+
+CONFIG_BT_BUF_ACL_RX_SIZE=251
+CONFIG_BT_BUF_ACL_TX_SIZE=251
+CONFIG_BT_L2CAP_TX_MTU=247
+
+CONFIG_MAIN_STACK_SIZE=4096
+
+CONFIG_CBPRINTF_FP_SUPPORT=y

samples/bluetooth/channel_sounding/cs_test/initiator/sample.yaml

@@ -0,0 +1,11 @@
+sample:
+  name: Bluetooth Channel Sounding Test - Initiator
+tests:
+  sample.bluetooth.channel_sounding.cs_test.initiator:
+    harness: bluetooth
+    platform_allow:
+      - qemu_cortex_m3
+      - qemu_x86
+    tags: bluetooth
+    integration_platforms:
+      - qemu_cortex_m3

samples/bluetooth/channel_sounding/cs_test/reflector/CMakeLists.txt

@@ -0,0 +1,11 @@
+# SPDX-License-Identifier: Apache-2.0
+
+cmake_minimum_required(VERSION 3.20.0)
+find_package(Zephyr REQUIRED HINTS $ENV{ZEPHYR_BASE})
+project(cs_test_reflector)
+
+target_sources(app PRIVATE ../../src/cs_test_reflector.c ../../src/distance_estimation.c)
+
+zephyr_library_include_directories(
+        ${CMAKE_CURRENT_LIST_DIR}/../../include
+)

samples/bluetooth/channel_sounding/cs_test/reflector/prj.conf

@@ -0,0 +1,13 @@
+CONFIG_BT=y
+CONFIG_BT_PERIPHERAL=y
+CONFIG_BT_GATT_CLIENT=y
+CONFIG_BT_CHANNEL_SOUNDING=y
+CONFIG_BT_CHANNEL_SOUNDING_TEST=y
+
+CONFIG_BT_BUF_ACL_RX_SIZE=251
+CONFIG_BT_BUF_ACL_TX_SIZE=251
+CONFIG_BT_L2CAP_TX_MTU=247
+
+CONFIG_MAIN_STACK_SIZE=4096
+
+CONFIG_CBPRINTF_FP_SUPPORT=y

samples/bluetooth/channel_sounding/cs_test/reflector/sample.yaml

@@ -0,0 +1,11 @@
+sample:
+  name: Bluetooth Channel Sounding Test - Reflector
+tests:
+  sample.bluetooth.channel_sounding.cs_test.reflector:
+    harness: bluetooth
+    platform_allow:
+      - qemu_cortex_m3
+      - qemu_x86
+    tags: bluetooth
+    integration_platforms:
+      - qemu_cortex_m3

samples/bluetooth/channel_sounding/include/common.h

@@ -0,0 +1,15 @@
+/*
+ * Copyright (c) 2024 Nordic Semiconductor ASA
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#include <zephyr/bluetooth/gatt.h>
+
+#define NAME_LEN          30
+#define STEP_DATA_BUF_LEN 512 /* Maximum GATT characteristic length */
+
+static struct bt_uuid_128 step_data_char_uuid =
+	BT_UUID_INIT_128(BT_UUID_128_ENCODE(0x87654321, 0x4567, 0x2389, 0x1254, 0xf67f9fedcba8));
+static const struct bt_uuid_128 step_data_svc_uuid =
+	BT_UUID_INIT_128(BT_UUID_128_ENCODE(0x87654321, 0x4567, 0x2389, 0x1254, 0xf67f9fedcba9));

samples/bluetooth/channel_sounding/include/cs_test_params.h

@@ -0,0 +1,58 @@
+/*
+ * Copyright (c) 2024 Nordic Semiconductor ASA
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#include <zephyr/bluetooth/cs.h>
+
+#define INITIATOR_ACCESS_ADDRESS 0x4D7B8A2F
+#define REFLECTOR_ACCESS_ADDRESS 0x96F93DB1
+#define NUM_MODE_0_STEPS         3
+
+static struct bt_le_cs_test_param test_params_get(enum bt_conn_le_cs_role role)
+{
+	struct bt_le_cs_test_param params;
+
+	params.role = role;
+	params.main_mode = BT_CONN_LE_CS_MAIN_MODE_2;
+	params.sub_mode = BT_CONN_LE_CS_SUB_MODE_1;
+	params.main_mode_repetition = 1;
+	params.mode_0_steps = NUM_MODE_0_STEPS;
+	params.rtt_type = BT_CONN_LE_CS_RTT_TYPE_AA_ONLY;
+	params.cs_sync_phy = BT_CONN_LE_CS_SYNC_1M_PHY;
+	params.cs_sync_antenna_selection = BT_LE_CS_TEST_CS_SYNC_ANTENNA_SELECTION_ONE;
+	params.subevent_len = 5000;
+	params.subevent_interval = 0;
+	params.max_num_subevents = 1;
+	params.transmit_power_level = BT_HCI_OP_LE_CS_TEST_MAXIMIZE_TX_POWER;
+	params.t_ip1_time = 145;
+	params.t_ip2_time = 145;
+	params.t_fcs_time = 150;
+	params.t_pm_time = 40;
+	params.t_sw_time = 0;
+	params.tone_antenna_config_selection = BT_LE_CS_TONE_ANTENNA_CONFIGURATION_INDEX_ONE;
+
+	params.initiator_snr_control = BT_LE_CS_INITIATOR_SNR_CONTROL_NOT_USED;
+	params.reflector_snr_control = BT_LE_CS_REFLECTOR_SNR_CONTROL_NOT_USED;
+
+	params.drbg_nonce = 0x1234;
+
+	params.override_config = BIT(2) | BIT(5);
+	params.override_config_0.channel_map_repetition = 1;
+
+	memset(params.override_config_0.not_set.channel_map, 0, 10);
+
+	for (uint8_t i = 40; i < 75; i++) {
+		BT_LE_CS_CHANNEL_BIT_SET_VAL(params.override_config_0.not_set.channel_map, i, 1);
+	}
+
+	params.override_config_0.not_set.channel_selection_type = BT_CONN_LE_CS_CHSEL_TYPE_3B;
+	params.override_config_0.not_set.ch3c_shape = BT_CONN_LE_CS_CH3C_SHAPE_HAT;
+	params.override_config_0.not_set.ch3c_jump = 2;
+	params.override_config_2.main_mode_steps = 8;
+	params.override_config_5.cs_sync_aa_initiator = INITIATOR_ACCESS_ADDRESS;
+	params.override_config_5.cs_sync_aa_reflector = REFLECTOR_ACCESS_ADDRESS;
+
+	return params;
+}

samples/bluetooth/channel_sounding/include/distance_estimation.h

@@ -0,0 +1,11 @@
+/*
+ * Copyright (c) 2024 Nordic Semiconductor ASA
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#include <stdint.h>
+#include <zephyr/bluetooth/cs.h>
+
+void estimate_distance(uint8_t *local_steps, uint16_t local_steps_len, uint8_t *peer_steps,
+		       uint16_t peer_steps_len, uint8_t n_ap, enum bt_conn_le_cs_role role);