Bluetooth: host: Add CTE receive and sample enable API

Add functions that give possibility to enable or disable
CTE receive and sample in connectionless mode.

Signed-off-by: Piotr Pryga <piotr.pryga@nordicsemi.no>

include/bluetooth/direction.h

@@ -7,6 +7,47 @@
 #ifndef ZEPHYR_INCLUDE_BLUETOOTH_DF_H_
 #define ZEPHYR_INCLUDE_BLUETOOTH_DF_H_
 
+/** Constant Tone Extension (CTE) types. */
+enum bt_df_cte_type {
+	/** Convenience value for purposes where non of CTE types is allowed. */
+	BT_DF_CTE_TYPE_NONE = 0,
+	/** Angle of Arrival mode. Antenna switching done on receiver site. */
+	BT_DF_CTE_TYPE_AOA = BIT(0),
+	/** Angle of Departure mode with 1 us antenna switching slots.
+	 *  Antenna switching done on transmitter site.
+	 */
+	BT_DF_CTE_TYPE_AOD_1US = BIT(1),
+	/** Angle of Departure mode with 2 us antenna switching slots.
+	 *  Antenna switching done on transmitter site.
+	 */
+	BT_DF_CTE_TYPE_AOD_2US = BIT(2),
+	/** Convenience value that collects all possible CTE types in one entry. */
+	BT_DF_CTE_TYPE_ALL = (BT_DF_CTE_TYPE_AOA | BT_DF_CTE_TYPE_AOD_1US | BT_DF_CTE_TYPE_AOD_2US)
+};
+
+/** Allowed antenna switching slots: 1 us or 2 us */
+enum bt_df_antenna_switching_slot {
+	BT_DF_ANTENNA_SWITCHING_SLOT_1US = 0x1,
+	BT_DF_ANTENNA_SWITCHING_SLOT_2US = 0x2
+};
+
+/** Possible statuses of PDU that contained reported CTE. */
+enum bt_df_packet_status {
+	/** Received PDU had CRC OK */
+	BT_DF_CTE_CRC_OK = 0x0,
+	/** Received PDU had incorrect CRC, but Radio peripheral
+	 * was able to parse CTEInfo field of the PDU and process
+	 * sampling of CTE.
+	 */
+	BT_DF_CTE_CRC_ERR_CTE_BASED_TIME = 0x1,
+	/** Received PDU had incorrect CRC, but Radio peripheral
+	 * was able to process sampling of CTE in some other way.
+	 */
+	BT_DF_CTE_CRC_ERR_CTE_BASED_OTHER = 0x2,
+	/** There were no sufficient resources to sample CTE. */
+	BT_DF_CTE_INSUFFICIENT_RESOURCES = 0xFF
+};
+
 /** @brief Constant Tone Extension parameters for connectionless
  * transmission.
  *
@@ -14,20 +55,41 @@
  * in periodic advertising.
  */
 struct bt_df_adv_cte_tx_param {
-	/** Length of CTE in 8us units */
+	/** Length of CTE in 8us units. */
 	uint8_t  cte_len;
-	/** CTE Type: AoA, AoD 1us slots, AoD 2us slots */
+	/** CTE Type: AoA, AoD 1us slots, AoD 2us slots. */
 	uint8_t  cte_type;
-	/** Number of CTE to transmit in each periodic adv interval */
+	/** Number of CTE to transmit in each periodic adv interval. */
 	uint8_t  cte_count;
-	/** Number of Antenna IDs in the switch pattern */
+	/** Number of Antenna IDs in the switch pattern. */
 	uint8_t  num_ant_ids;
-	/** List of antenna IDs in the pattern */
+	/** List of antenna IDs in the pattern. */
 	uint8_t  *ant_ids;
 };
 
-/** @brief Set or update the Constant Tone Extension parameters for periodic
+/**
- * advertising set.
+ * @brief Constant Tone Extension parameters for connectionless reception.
+ *
+ * @note cte_type is a bit field that provides information about type of CTE an application
+ * expects (@ref bt_df_cte_type). In case cte_type bit BT_DF_CTE_TYPE_AOA is not set, members:
+ * slot_durations, num_ant_ids and ant_ids are not required and their values will be not verified
+ * for correctness.
+ */
+struct bt_df_per_adv_sync_cte_rx_param {
+	/* Bitmap with allowed CTE types (@ref bt_df_cte_type). */
+	uint8_t cte_type;
+	/** Antenna switching slots (@ref bt_df_antenna_switching_slot). */
+	uint8_t slot_durations;
+	/** Max number of CTEs to receive. Min is 1, max is 10, 0 means receive continuously. */
+	uint8_t max_cte_count;
+	/** Length of antenna switch pattern. */
+	uint8_t num_ant_ids;
+	/** Antenna switch pattern. */
+	const uint8_t *ant_ids;
+};
+
+/**
+ * @brief Set or update the Constant Tone Extension parameters for periodic advertising set.
  *
  * @param[in] adv               Advertising set object.
  * @param[in] params            Constant Tone Extension parameters.
@@ -37,12 +99,12 @@ struct bt_df_adv_cte_tx_param {
 int bt_df_set_adv_cte_tx_param(struct bt_le_ext_adv *adv,
 			       const struct bt_df_adv_cte_tx_param *params);
 
-/** @brief Enable transmission of Constant Tone Extension for the given
+/**
- *        advertising set.
+ * @brief Enable transmission of Constant Tone Extension for the given advertising set.
  *
- * Transmission of Constant Tone Extension may be enabled only after setting
+ * Transmission of Constant Tone Extension may be enabled only after setting periodic advertising
- * periodic advertising parameters (@ref bt_le_per_adv_set_param) and Constant
+ * parameters (@ref bt_le_per_adv_set_param) and Constant Tone Extension parameters
- * Tone Extension parameters (@ref bt_df_set_adv_cte_tx_param).
+ * (@ref bt_df_set_adv_cte_tx_param).
  *
  * @param[in] adv           Advertising set object.
  *
@@ -50,8 +112,8 @@ int bt_df_set_adv_cte_tx_param(struct bt_le_ext_adv *adv,
  */
 int bt_df_adv_cte_tx_enable(struct bt_le_ext_adv *adv);
 
-/** @brief Disable transmission of Constant Tone Extension for the given
+/**
- *        advertising set.
+ * @brief Disable transmission of Constant Tone Extension for the given advertising set.
  *
  * @param[in] adv           Advertising set object.
  *
@@ -59,4 +121,27 @@ int bt_df_adv_cte_tx_enable(struct bt_le_ext_adv *adv);
  */
 int bt_df_adv_cte_tx_disable(struct bt_le_ext_adv *adv);
 
+/**
+ * @brief Enable receive and sampling of Constant Tone Extension for the given sync set.
+ *
+ * Receive and sampling of Constant Tone Extension may be enabled only after periodic advertising
+ * sync is established.
+ *
+ * @param sync   Periodic advertising sync object.
+ * @param params CTE receive and sampling parameters.
+ *
+ * @return Zero on success or (negative) error code otherwise.
+ */
+int bt_df_per_adv_sync_cte_rx_enable(struct bt_le_per_adv_sync *sync,
+				     const struct bt_df_per_adv_sync_cte_rx_param *params);
+
+/**
+ * @brief Disable receive and sampling of Constant Tone Extension for the given sync set.
+ *
+ * @param sync Periodic advertising sync object.
+ *
+ * @return Zero on success or (negative) error code otherwise.
+ */
+int bt_df_per_adv_sync_cte_rx_disable(struct bt_le_per_adv_sync *sync);
+
 #endif /* ZEPHYR_INCLUDE_BLUETOOTH_DF_H_ */

subsys/bluetooth/host/direction.c

@@ -5,6 +5,7 @@
  */
 #include <stdint.h>
 #include <assert.h>
+#include <sys/check.h>
 #include <sys/byteorder.h>
 
 #include <bluetooth/bluetooth.h>
@@ -34,6 +35,9 @@ struct bt_le_df_ant_info {
 };
 
 static struct bt_le_df_ant_info df_ant_info;
+#if defined(CONFIG_BT_DF_CONNECTIONLESS_CTE_RX)
+const static uint8_t df_dummy_switch_pattern[BT_HCI_LE_SWITCH_PATTERN_LEN_MIN] = { 0, 0 };
+#endif /* CONFIG_BT_DF_CONNECTIONLESS_CTE_RX */
 
 #define DF_SUPP_TEST(feat, n)                   ((feat) & BIT((n)))
 
@@ -43,6 +47,17 @@ static struct bt_le_df_ant_info df_ant_info;
 						BT_HCI_LE_1US_AOD_RX))
 #define DF_AOA_RX_1US_SUPPORT(supp)             (DF_SUPP_TEST(supp, \
 						BT_HCI_LE_1US_AOA_RX))
+#define DF_SAMPLING_ANTENNA_NUMBER_MIN 0x2
+
+#if defined(CONFIG_BT_DF_CONNECTIONLESS_CTE_RX)
+static int validate_cte_rx_params(const struct bt_df_per_adv_sync_cte_rx_param *params);
+static void prepare_cte_rx_enable_cmd_params(struct bt_hci_cp_le_set_cl_cte_sampling_enable *cp,
+					     struct net_buf *buf, struct bt_le_per_adv_sync *sync,
+					     const struct bt_df_per_adv_sync_cte_rx_param *params,
+					     bool enable);
+static int hci_df_set_cl_cte_rx_enable(struct bt_le_per_adv_sync *sync, bool enable,
+				       const struct bt_df_per_adv_sync_cte_rx_param *params);
+#endif /* CONFIG_BT_DF_CONNECTIONLESS_CTE_RX */
 
 static int hci_df_set_cl_cte_tx_params(const struct bt_le_ext_adv *adv,
 				    const struct bt_df_adv_cte_tx_param *params)
@@ -189,6 +204,112 @@ static int hci_df_set_adv_cte_tx_enable(struct bt_le_ext_adv *adv,
 				   buf, NULL);
 }
 
+#if defined(CONFIG_BT_DF_CONNECTIONLESS_CTE_RX)
+static int validate_cte_rx_params(const struct bt_df_per_adv_sync_cte_rx_param *params)
+{
+	if (!(params->cte_type &
+	      (BT_DF_CTE_TYPE_AOA | BT_DF_CTE_TYPE_AOD_1US | BT_DF_CTE_TYPE_AOD_2US))) {
+		return -EINVAL;
+	}
+
+	if (params->cte_type & BT_DF_CTE_TYPE_AOA) {
+		if (df_ant_info.num_ant < DF_SAMPLING_ANTENNA_NUMBER_MIN ||
+		    !BT_FEAT_LE_ANT_SWITCH_RX_AOA(bt_dev.le.features)) {
+			return -EINVAL;
+		}
+
+		if (!(params->slot_durations == BT_HCI_LE_ANTENNA_SWITCHING_SLOT_2US ||
+		      (params->slot_durations == BT_HCI_LE_ANTENNA_SWITCHING_SLOT_1US &&
+		       DF_AOA_RX_1US_SUPPORT(df_ant_info.switch_sample_rates)))) {
+			return -EINVAL;
+		}
+
+		if (params->num_ant_ids < BT_HCI_LE_SWITCH_PATTERN_LEN_MIN ||
+		    params->num_ant_ids > df_ant_info.max_switch_pattern_len || !params->ant_ids) {
+			return -EINVAL;
+		}
+	}
+
+	return 0;
+}
+
+static void prepare_cte_rx_enable_cmd_params(struct bt_hci_cp_le_set_cl_cte_sampling_enable *cp,
+					     struct net_buf *buf, struct bt_le_per_adv_sync *sync,
+					     const struct bt_df_per_adv_sync_cte_rx_param *params,
+					     bool enable)
+{
+	const uint8_t *ant_ids;
+
+	cp = net_buf_add(buf, sizeof(*cp));
+	(void)memset(cp, 0, sizeof(*cp));
+
+	cp->sync_handle = sys_cpu_to_le16(sync->handle);
+	cp->sampling_enable = enable ? 1 : 0;
+
+	if (enable) {
+		uint8_t *dest_ant_ids;
+
+		cp->max_sampled_cte = params->max_cte_count;
+
+		if (params->cte_type & BT_DF_CTE_TYPE_AOA) {
+			cp->slot_durations = params->slot_durations;
+			cp->switch_pattern_len = params->num_ant_ids;
+			ant_ids = params->ant_ids;
+		} else {
+			/* Those values are put here due to constraints from HCI command
+			 * specification: Bluetooth Core Spec. Vol 4,Part E, sec 7.8.82.
+			 * There is no right way to successfully send the command to enable CTE
+			 * receive for AoD mode (e.g. device equipped with single antenna).
+			 */
+			cp->slot_durations = BT_HCI_LE_ANTENNA_SWITCHING_SLOT_2US;
+			cp->switch_pattern_len = ARRAY_SIZE(df_dummy_switch_pattern);
+			ant_ids = &df_dummy_switch_pattern[0];
+		}
+
+		dest_ant_ids =	net_buf_add(buf, params->num_ant_ids);
+		memcpy(dest_ant_ids, params->ant_ids, params->num_ant_ids);
+	}
+}
+
+static int hci_df_set_cl_cte_rx_enable(struct bt_le_per_adv_sync *sync, bool enable,
+				       const struct bt_df_per_adv_sync_cte_rx_param *params)
+{
+	struct bt_hci_cp_le_set_cl_cte_sampling_enable *cp;
+	struct bt_hci_cmd_state_set state;
+	struct net_buf *buf;
+	int err;
+
+	if (enable) {
+		err = validate_cte_rx_params(params);
+		if (err != 0) {
+			return err;
+		}
+	}
+
+	/* If CTE Rx is enabled, command parameters total length must include
+	 * antenna ids, so command size if extended by num_and_ids.
+	 */
+	buf = bt_hci_cmd_create(BT_HCI_OP_LE_SET_CL_CTE_SAMPLING_ENABLE,
+				sizeof(*cp) + (enable ? params->num_ant_ids : 0));
+	if (!buf) {
+		return -ENOBUFS;
+	}
+
+	prepare_cte_rx_enable_cmd_params(cp, buf, sync, params, enable);
+
+	bt_hci_cmd_state_set_init(buf, &state, sync->flags, BT_PER_ADV_SYNC_CTE_ENABLED, enable);
+
+	err = bt_hci_cmd_send_sync(BT_HCI_OP_LE_SET_CL_CTE_SAMPLING_ENABLE, buf, NULL);
+	if (err) {
+		return err;
+	}
+
+	sync->cte_type = (enable ? params->cte_type : 0);
+
+	return 0;
+}
+#endif /* CONFIG_BT_DF_CONNECTIONLESS_CTE_RX */
+
 #if defined(CONFIG_BT_CTLR_DF_CONN_CTE_RSP)
 /* @brief Function sets CTE parameters for connection object
  *
@@ -348,3 +469,47 @@ int bt_df_adv_cte_tx_disable(struct bt_le_ext_adv *adv)
 	__ASSERT_NO_MSG(adv);
 	return bt_df_set_adv_cte_tx_enabled(adv, false);
 }
+
+#if defined(CONFIG_BT_DF_CONNECTIONLESS_CTE_RX)
+static int
+bt_df_set_per_adv_sync_cte_rx_enable(struct bt_le_per_adv_sync *sync, bool enable,
+				     const struct bt_df_per_adv_sync_cte_rx_param *params)
+{
+	if (!BT_FEAT_LE_CONNECTIONLESS_CTE_RX(bt_dev.le.features)) {
+		return -ENOTSUP;
+	}
+
+	if (!atomic_test_bit(sync->flags, BT_PER_ADV_SYNC_SYNCED)) {
+		return -EINVAL;
+	}
+
+	if (!enable &&
+	    !atomic_test_bit(sync->flags, BT_PER_ADV_SYNC_CTE_ENABLED)) {
+		return -EALREADY;
+	}
+
+	return hci_df_set_cl_cte_rx_enable(sync, enable, params);
+}
+
+int bt_df_per_adv_sync_cte_rx_enable(struct bt_le_per_adv_sync *sync,
+				     const struct bt_df_per_adv_sync_cte_rx_param *params)
+{
+	CHECKIF(!sync) {
+		return -EINVAL;
+	}
+	CHECKIF(!params) {
+		return -EINVAL;
+	}
+
+	return bt_df_set_per_adv_sync_cte_rx_enable(sync, true, params);
+}
+
+int bt_df_per_adv_sync_cte_rx_disable(struct bt_le_per_adv_sync *sync)
+{
+	CHECKIF(!sync) {
+		return -EINVAL;
+	}
+
+	return bt_df_set_per_adv_sync_cte_rx_enable(sync, false, NULL);
+}
+#endif /* CONFIG_BT_DF_CONNECTIONLESS_CTE_RX */

subsys/bluetooth/host/hci_core.h

@@ -144,7 +144,6 @@ struct bt_le_ext_adv {
 #endif /* defined(CONFIG_BT_EXT_ADV) */
 };
 
-
 enum {
 	/** Periodic Advertising Sync has been created in the host. */
 	BT_PER_ADV_SYNC_CREATED,
@@ -158,6 +157,11 @@ enum {
 	/** Periodic advertising is attempting sync sync */
 	BT_PER_ADV_SYNC_RECV_DISABLED,
 
+	/** Constant Tone Extension for Periodic Advertising has been enabled
+	 * in the controller.
+	 */
+	BT_PER_ADV_SYNC_CTE_ENABLED,
+
 	BT_PER_ADV_SYNC_NUM_FLAGS,
 };
 
@@ -180,6 +184,11 @@ struct bt_le_per_adv_sync {
 	/** Advertiser PHY */
 	uint8_t phy;
 
+#if defined(CONFIG_BT_DF_CONNECTIONLESS_CTE_RX)
+	/** Accepted CTE type */
+	uint8_t cte_type;
+#endif /* CONFIG_BT_DF_CONNECTIONLESS_CTE_RX */
+
 	/** Flags */
 	ATOMIC_DEFINE(flags, BT_PER_ADV_SYNC_NUM_FLAGS);
 };