bluetooth: services: Add Channel Sounding Distance Estimation library

doc/nrf/libraries/bluetooth/cs_de.rst

@@ -0,0 +1,47 @@
+.. _cs_de_readme:
+
+Bluetooth Channel Sounding Distance Estimation
+##############################################
+
+.. contents::
+   :local:
+   :depth: 2
+
+Overview
+********
+
+This library implements distance estimation algorithms to be used with Bluetooth Channel Sounding and Ranging Profile/Service defined in the defined in the `Ranging Service Specification`_ and the `Ranging Profile Specification`_.
+
+Currently the following methods of computing the distance are available:
+
+* Fourier transform of the mixed signal between initiator and reflector. Distance is derived from the largest components in the amplitude spectrum.
+
+* Derivative of phase with respect to frequency, as described in `Distance estimation based on phase and amplitude information`_.
+
+* Round-trip timing, as described in `Distance estimation based on RTT packets`_.
+
+Configuration
+*************
+
+To enable this library, use the :kconfig:option:`CONFIG_BT_CS_DE` Kconfig option.
+
+Check and adjust the following Kconfig options:
+
+* :kconfig:option:`CONFIG_BT_CS_DE_512_NFFT` - Uses 512 samples to compute the fourier transform.
+
+* :kconfig:option:`CONFIG_BT_CS_DE_1024_NFFT` - Uses 1024 samples to compute the fourier transform.
+
+* :kconfig:option:`CONFIG_BT_CS_DE_2048_NFFT` - Uses 2048 samples to compute the fourier transform.
+
+Usage
+*****
+
+| See the sample: :file:`samples/bluetooth/channel_sounding_ras_initiator`
+
+API documentation
+*****************
+
+| Header file: :file:`include/bluetooth/cs_de.h`
+| Source files: :file:`subsys/bluetooth/cs_de`
+
+.. doxygengroup:: bt_cs_de

include/bluetooth/cs_de.h

@@ -0,0 +1,99 @@
+/*
+ * Copyright (c) 2025 Nordic Semiconductor ASA
+ *
+ * SPDX-License-Identifier: LicenseRef-Nordic-5-Clause
+ */
+
+#ifndef CS_DE_H__
+#define CS_DE_H__
+
+#include <zephyr/bluetooth/conn.h>
+#include <zephyr/net_buf.h>
+
+/**
+ * @brief Container of IQ values for local and remote measured tones
+ */
+typedef struct {
+	/** In-phase measurements of tones on this device */
+	float i_local[80];
+	/** Quadrature-phase measurement of tones on this device */
+	float q_local[80];
+	/** In-phase measurements of tones from remote device */
+	float i_remote[80];
+	/** Quadrature-phase measurements of tones from remote device */
+	float q_remote[80];
+} cs_de_iq_tones_t;
+
+typedef enum {
+	CS_DE_TONE_QUALITY_OK,
+	CS_DE_TONE_QUALITY_BAD,
+} cs_de_tone_quality_t;
+
+/**
+ * @brief Container of distance estimate results for a number of different
+ * methods, in meters.
+ */
+typedef struct {
+	/** Distance estimate based on fourier transform. */
+	float ifft;
+	/** Distance estimate based on average phase slope. */
+	float phase_slope;
+	/** Distance estimate based on RTT. */
+	float rtt;
+	/** Best effort distance estimate.
+	 *
+	 *  This is a convenience value which is automatically set to the most
+	 *  accurate of the estimation methods.
+	 */
+	float best;
+} cs_de_dist_estimates_t;
+
+/**
+ * @brief Quality of the procedure
+ */
+typedef enum {
+	CS_DE_QUALITY_OK,
+	CS_DE_QUALITY_DO_NOT_USE,
+} cs_de_quality_t;
+
+/**
+ * @brief Output data for distance estimation
+ */
+typedef struct {
+	/** CS Role. */
+	enum bt_conn_le_cs_role role;
+
+	/** Number of antenna paths present in data. */
+	uint8_t n_ap;
+
+	/** IQ values for local and remote measured tones. */
+	cs_de_iq_tones_t iq_tones[CONFIG_BT_RAS_MAX_ANTENNA_PATHS];
+
+	/** Tone quality indicators */
+	cs_de_tone_quality_t tone_quality[CONFIG_BT_RAS_MAX_ANTENNA_PATHS];
+
+	/** Distance estimate results */
+	cs_de_dist_estimates_t distance_estimates[CONFIG_BT_RAS_MAX_ANTENNA_PATHS];
+
+	/** Total time measured during RTT measurements */
+	int32_t rtt_accumulated_half_ns;
+
+	/** Number of RTT measurements taken */
+	uint8_t rtt_count;
+} cs_de_report_t;
+
+/**
+ * @brief Partially populate the report.
+ * This populates the report but does not set the distance estimates and the quality.
+ * @param[in] local_steps Buffer to the local step data to parse.
+ * @param[in] peer_steps   Buffer to the peer ranging data to parse.
+ * @param[in] role Role of the local controller.
+ * @param[out] p_report Report populated with the raw data from the last ranging.
+ */
+void cs_de_populate_report(struct net_buf_simple *local_steps, struct net_buf_simple *peer_steps,
+			   enum bt_conn_le_cs_role role, cs_de_report_t *p_report);
+
+/* Takes partially populated report and calculates distance estimates and quality. */
+cs_de_quality_t cs_de_calc(cs_de_report_t *p_report);
+
+#endif /* CS_DE_H__ */

include/bluetooth/services/ras.h

@@ -505,7 +505,18 @@ int bt_ras_rreq_rd_overwritten_unsubscribe(struct bt_conn *conn);
  */
 int bt_ras_rreq_read_features(struct bt_conn *conn, bt_ras_rreq_features_read_cb_t cb);
 
-/** @brief Provide step header for each step back to the user.
+/** @brief Provide ranging header for the ranging data back to the user.
+ *
+ * @param[in] ranging_header Ranging header data.
+ * @param[in] user_data User data.
+ *
+ * @retval true if data parsing should continue.
+ *         false if data parsing should be stopped.
+ */
+typedef bool (*bt_ras_rreq_ranging_header_cb_t)(struct ras_ranging_header *ranging_header,
+						 void *user_data);
+
+/** @brief Provide subevent header for each subevent back to the user.
  *
  * @param[in] subevent_header Subevent header data.
  * @param[in] user_data       User data.
@@ -541,13 +552,15 @@ typedef bool (*bt_ras_rreq_step_data_cb_t)(struct bt_le_cs_subevent_step *local_
  * @param[in] peer_ranging_data_buf Buffer to the peer ranging data to parse.
  * @param[in] local_step_data_buf   Buffer to the local step data to parse.
  * @param[in] cs_role               Channel sounding role of local device.
+ * @param[in] ranging_header_cb     Callback called (once) for the ranging header.
  * @param[in] subevent_header_cb    Callback called with each subevent header.
  * @param[in] step_data_cb          Callback called with each peer and local step data.
  * @param[in] user_data             User data to be passed to the callbacks.
  */
 void bt_ras_rreq_rd_subevent_data_parse(struct net_buf_simple *peer_ranging_data_buf,
 					struct net_buf_simple *local_step_data_buf,
 					enum bt_conn_le_cs_role cs_role,
+					bt_ras_rreq_ranging_header_cb_t ranging_header_cb,
 					bt_ras_rreq_subevent_header_cb_t subevent_header_cb,
 					bt_ras_rreq_step_data_cb_t step_data_cb, void *user_data);
 

samples/bluetooth/channel_sounding_ras_initiator/README.rst

@@ -8,8 +8,7 @@ Bluetooth: Channel Sounding Initiator with Ranging Requestor
    :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 demonstrate the IQ data handling.
-The accuracy is not representative for Channel Sounding and should be replaced if accuracy is important.
+Distances estimates are then computed from the ranging data and logged to the terminal.
 
 Requirements
 ************
@@ -26,9 +25,6 @@ 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
 **************
 
@@ -51,6 +47,17 @@ After programming the sample to your development kit, you can test it by connect
 #. Wait until the scanner detects the Peripheral.
    In the terminal window, check for information similar to the following::
 
+      I: Starting Channel Sounding Initiator Sample
+      I: SoftDevice Controller build revision:
+      I: bd 8a c7 d2 9b 7c 24 05 |.....|$.
+      I: d3 20 24 a2 60 b9 62 44 |. $.`.bD
+      I: 1a dc cc 22             |..."
+      I: HW Platform: Nordic Semiconductor (0x0002)
+      I: HW Variant: nRF54Lx (0x0005)
+      I: Firmware: Standard Bluetooth controller (0x00) Version 189.51082 Build 612146130
+      I: Identity: XX:XX:XX:XX:XX:XX (random)
+      I: HCI: version 6.0 (0x0e) revision 0x30d5, manufacturer 0x0059
+      I: LMP: version 6.0 (0x0e) subver 0x30d5
       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)
@@ -60,13 +67,19 @@ After programming the sample to your development kit, you can test it by connect
       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 on antenna path A from X samples)
+      I: CS procedures enabled:
+       - config ID: 0
+       - antenna configuration index: 0
+       - TX power: 0 dbm
+       - subevent length: 28198 us
+       - subevents per event: 1
+       - subevent interval: 0
+       - event interval: 2
+       - procedure interval: 10
+       - procedure count: 0
+       - maximum procedure length: 1000
+      I: Distance estimates on antenna path 0: ifft: 1.039173, phase_slope: 1.581897, rtt: 3.075647
+      I: Sleeping for a few seconds...
 
 Dependencies
 ************

samples/bluetooth/channel_sounding_ras_initiator/prj.conf

@@ -53,3 +53,6 @@ CONFIG_FPU=y
 CONFIG_FPU_SHARING=y
 
 CONFIG_CBPRINTF_FP_SUPPORT=y
+
+CONFIG_BT_CS_DE=y
+CONFIG_BT_CS_DE_512_NFFT=y