Skip to content

bluetooth: host: CS support for various HCI commands #79183

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
carlescufi merged 1 commit into from
Oct 18, 2024
Merged

bluetooth: host: CS support for various HCI commands #79183

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
101 changes: 101 additions & 0 deletions include/zephyr/bluetooth/conn.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1518,6 +1518,86 @@
BT_SECURITY_ERR_UNSPECIFIED,
};

enum bt_conn_le_cs_procedure_enable_state {
BT_CONN_LE_CS_PROCEDURES_DISABLED = BT_HCI_OP_LE_CS_PROCEDURES_DISABLED,
BT_CONN_LE_CS_PROCEDURES_ENABLED = BT_HCI_OP_LE_CS_PROCEDURES_ENABLED,
};

/** CS Test Tone Antennna Config Selection.
*
* These enum values are indices in the following table, where N_AP is the maximum
* number of antenna paths (in the range [1, 4]).
*
* +--------------+-------------+-------------------+-------------------+--------+
* | Config Index | Total Paths | Dev A: # Antennas | Dev B: # Antennas | Config |
* +--------------+-------------+-------------------+-------------------+--------+
* | 0 | 1 | 1 | 1 | 1:1 |
* | 1 | 2 | 2 | 1 | N_AP:1 |
* | 2 | 3 | 3 | 1 | N_AP:1 |
* | 3 | 4 | 4 | 1 | N_AP:1 |
* | 4 | 2 | 1 | 2 | 1:N_AP |
* | 5 | 3 | 1 | 3 | 1:N_AP |
* | 6 | 4 | 1 | 4 | 1:N_AP |
* | 7 | 4 | 2 | 2 | 2:2 |
* +--------------+-------------+-------------------+-------------------+--------+
*
* There are therefore four groups of possible antenna configurations:
*
* - 1:1 configuration, where both A and B support 1 antenna each
* - 1:N_AP configuration, where A supports 1 antenna, B supports N_AP antennas, and
* N_AP is a value in the range [2, 4]
* - N_AP:1 configuration, where A supports N_AP antennas, B supports 1 antenna, and
* N_AP is a value in the range [2, 4]
* - 2:2 configuration, where both A and B support 2 antennas and N_AP = 4
*/
enum bt_conn_le_cs_tone_antenna_config_selection {
BT_LE_CS_TONE_ANTENNA_CONFIGURATION_INDEX_ONE = BT_HCI_OP_LE_CS_ACI_0,
BT_LE_CS_TONE_ANTENNA_CONFIGURATION_INDEX_TWO = BT_HCI_OP_LE_CS_ACI_1,
BT_LE_CS_TONE_ANTENNA_CONFIGURATION_INDEX_THREE = BT_HCI_OP_LE_CS_ACI_2,
BT_LE_CS_TONE_ANTENNA_CONFIGURATION_INDEX_FOUR = BT_HCI_OP_LE_CS_ACI_3,
BT_LE_CS_TONE_ANTENNA_CONFIGURATION_INDEX_FIVE = BT_HCI_OP_LE_CS_ACI_4,
BT_LE_CS_TONE_ANTENNA_CONFIGURATION_INDEX_SIX = BT_HCI_OP_LE_CS_ACI_5,
BT_LE_CS_TONE_ANTENNA_CONFIGURATION_INDEX_SEVEN = BT_HCI_OP_LE_CS_ACI_6,
BT_LE_CS_TONE_ANTENNA_CONFIGURATION_INDEX_EIGHT = BT_HCI_OP_LE_CS_ACI_7,
};

struct bt_conn_le_cs_procedure_enable_complete {
/* The ID associated with the desired configuration (0 to 3) */
uint8_t config_id;

/* State of the CS procedure */
enum bt_conn_le_cs_procedure_enable_state state;

/* Antenna configuration index */
enum bt_conn_le_cs_tone_antenna_config_selection tone_antenna_config_selection;

/* Transmit power level used for CS procedures (-127 to 20 dB; 0x7F if unavailable) */
int8_t selected_tx_power;

/* Duration of each CS subevent in microseconds (1250 us to 4 s) */
uint32_t subevent_len;

/* Number of CS subevents anchored off the same ACL connection event (0x01 to 0x20) */
uint8_t subevents_per_event;

/* Time between consecutive CS subevents anchored off the same ACL connection event in
* units of 0.625 ms
*/
uint16_t subevent_interval;

/* Number of ACL connection events between consecutive CS event anchor points */
uint16_t event_interval;

/* Number of ACL connection events between consecutive CS procedure anchor points */
uint16_t procedure_interval;

/* Number of CS procedures to be scheduled (0 if procedures to continue until disabled) */
uint16_t procedure_count;

/* Maximum duration for each procedure in units of 0.625 ms (0x0001 to 0xFFFF) */
uint16_t max_procedure_len;
};

/** @brief Connection callback structure.
*
* This structure is used for tracking the state of a connection.
Expand Down Expand Up @@ -1810,6 +1890,27 @@
*/
void (*le_cs_subevent_data_available)(struct bt_conn *conn,
struct bt_conn_le_cs_subevent_result *result);

/** @brief LE CS Security Enabled.
*
* This callback notifies the application that a Channel Sounding
* Security Enable procedure has completed
*
* @param conn Connection object.
*/
void (*le_cs_security_enabled)(struct bt_conn *conn);

/** @brief LE CS Procedure Enabled.
*
* This callback notifies the application that a Channel Sounding
* Procedure Enable procedure has completed
*
* @param conn Connection object.
* @param params CS Procedure Enable parameters
*/
void (*le_cs_procedure_enabled)(
struct bt_conn *conn, struct bt_conn_le_cs_procedure_enable_complete *params);

Check notice on line 1913 in include/zephyr/bluetooth/conn.h

View workflow job for this annotation

GitHub Actions / Run compliance checks on patch series (PR)

You may want to run clang-format on this change 

include/zephyr/bluetooth/conn.h:1913 
-	void (*le_cs_procedure_enabled)(
-		struct bt_conn *conn, struct bt_conn_le_cs_procedure_enable_complete *params);
+	void (*le_cs_procedure_enabled)(struct bt_conn *conn,
+					struct bt_conn_le_cs_procedure_enable_complete *params);
#endif

/** @internal Internally used field for list handling */
Expand Down
244 changes: 189 additions & 55 deletions include/zephyr/bluetooth/cs.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -88,62 +88,24 @@ enum bt_le_cs_test_cs_sync_antenna_selection {
BT_LE_CS_TEST_CS_SYNC_ANTENNA_SELECTION_FOUR = BT_HCI_OP_LE_CS_ANTENNA_SEL_FOUR,
};

/** CS Test Tone Antennna Config Selection.
*
* These enum values are indices in the following table, where N_AP is the maximum
* number of antenna paths (in the range [1, 4]).
*
* +--------------+-------------+-------------------+-------------------+--------+
* | Config Index | Total Paths | Dev A: # Antennas | Dev B: # Antennas | Config |
* +--------------+-------------+-------------------+-------------------+--------+
* | 0 | 1 | 1 | 1 | 1:1 |
* | 1 | 2 | 2 | 1 | N_AP:1 |
* | 2 | 3 | 3 | 1 | N_AP:1 |
* | 3 | 4 | 4 | 1 | N_AP:1 |
* | 4 | 2 | 1 | 2 | 1:N_AP |
* | 5 | 3 | 1 | 3 | 1:N_AP |
* | 6 | 4 | 1 | 4 | 1:N_AP |
* | 7 | 4 | 2 | 2 | 2:2 |
* +--------------+-------------+-------------------+-------------------+--------+
*
* There are therefore four groups of possible antenna configurations:
*
* - 1:1 configuration, where both A and B support 1 antenna each
* - 1:N_AP configuration, where A supports 1 antenna, B supports N_AP antennas, and
* N_AP is a value in the range [2, 4]
* - N_AP:1 configuration, where A supports N_AP antennas, B supports 1 antenna, and
* N_AP is a value in the range [2, 4]
* - 2:2 configuration, where both A and B support 2 antennas and N_AP = 4
*/
enum bt_le_cs_test_tone_antenna_config_selection {
BT_LE_CS_TEST_TONE_ANTENNA_CONFIGURATION_INDEX_ONE = BT_HCI_OP_LE_CS_TEST_ACI_0,
BT_LE_CS_TEST_TONE_ANTENNA_CONFIGURATION_INDEX_TWO = BT_HCI_OP_LE_CS_TEST_ACI_1,
BT_LE_CS_TEST_TONE_ANTENNA_CONFIGURATION_INDEX_THREE = BT_HCI_OP_LE_CS_TEST_ACI_2,
BT_LE_CS_TEST_TONE_ANTENNA_CONFIGURATION_INDEX_FOUR = BT_HCI_OP_LE_CS_TEST_ACI_3,
BT_LE_CS_TEST_TONE_ANTENNA_CONFIGURATION_INDEX_FIVE = BT_HCI_OP_LE_CS_TEST_ACI_4,
BT_LE_CS_TEST_TONE_ANTENNA_CONFIGURATION_INDEX_SIX = BT_HCI_OP_LE_CS_TEST_ACI_5,
BT_LE_CS_TEST_TONE_ANTENNA_CONFIGURATION_INDEX_SEVEN = BT_HCI_OP_LE_CS_TEST_ACI_6,
BT_LE_CS_TEST_TONE_ANTENNA_CONFIGURATION_INDEX_EIGHT = BT_HCI_OP_LE_CS_TEST_ACI_7,
};

/** CS Test Initiator SNR control options */
enum bt_le_cs_test_initiator_snr_control {
BT_LE_CS_TEST_INITIATOR_SNR_CONTROL_18dB = BT_HCI_OP_LE_CS_TEST_INITIATOR_SNR_18,
BT_LE_CS_TEST_INITIATOR_SNR_CONTROL_21dB = BT_HCI_OP_LE_CS_TEST_INITIATOR_SNR_21,
BT_LE_CS_TEST_INITIATOR_SNR_CONTROL_24dB = BT_HCI_OP_LE_CS_TEST_INITIATOR_SNR_24,
BT_LE_CS_TEST_INITIATOR_SNR_CONTROL_27dB = BT_HCI_OP_LE_CS_TEST_INITIATOR_SNR_27,
BT_LE_CS_TEST_INITIATOR_SNR_CONTROL_30dB = BT_HCI_OP_LE_CS_TEST_INITIATOR_SNR_30,
BT_LE_CS_TEST_INITIATOR_SNR_CONTROL_NOT_USED = BT_HCI_OP_LE_CS_TEST_INITIATOR_SNR_NOT_USED,
enum bt_le_cs_initiator_snr_control {
BT_LE_CS_INITIATOR_SNR_CONTROL_18dB = BT_HCI_OP_LE_CS_INITIATOR_SNR_18,
BT_LE_CS_INITIATOR_SNR_CONTROL_21dB = BT_HCI_OP_LE_CS_INITIATOR_SNR_21,
BT_LE_CS_INITIATOR_SNR_CONTROL_24dB = BT_HCI_OP_LE_CS_INITIATOR_SNR_24,
BT_LE_CS_INITIATOR_SNR_CONTROL_27dB = BT_HCI_OP_LE_CS_INITIATOR_SNR_27,
BT_LE_CS_INITIATOR_SNR_CONTROL_30dB = BT_HCI_OP_LE_CS_INITIATOR_SNR_30,
BT_LE_CS_INITIATOR_SNR_CONTROL_NOT_USED = BT_HCI_OP_LE_CS_INITIATOR_SNR_NOT_USED,
};

/** CS Test Reflector SNR control options */
enum bt_le_cs_test_reflector_snr_control {
BT_LE_CS_TEST_REFLECTOR_SNR_CONTROL_18dB = BT_HCI_OP_LE_CS_TEST_REFLECTOR_SNR_18,
BT_LE_CS_TEST_REFLECTOR_SNR_CONTROL_21dB = BT_HCI_OP_LE_CS_TEST_REFLECTOR_SNR_21,
BT_LE_CS_TEST_REFLECTOR_SNR_CONTROL_24dB = BT_HCI_OP_LE_CS_TEST_REFLECTOR_SNR_24,
BT_LE_CS_TEST_REFLECTOR_SNR_CONTROL_27dB = BT_HCI_OP_LE_CS_TEST_REFLECTOR_SNR_27,
BT_LE_CS_TEST_REFLECTOR_SNR_CONTROL_30dB = BT_HCI_OP_LE_CS_TEST_REFLECTOR_SNR_30,
BT_LE_CS_TEST_REFLECTOR_SNR_CONTROL_NOT_USED = BT_HCI_OP_LE_CS_TEST_REFLECTOR_SNR_NOT_USED,
enum bt_le_cs_reflector_snr_control {
BT_LE_CS_REFLECTOR_SNR_CONTROL_18dB = BT_HCI_OP_LE_CS_REFLECTOR_SNR_18,
BT_LE_CS_REFLECTOR_SNR_CONTROL_21dB = BT_HCI_OP_LE_CS_REFLECTOR_SNR_21,
BT_LE_CS_REFLECTOR_SNR_CONTROL_24dB = BT_HCI_OP_LE_CS_REFLECTOR_SNR_24,
BT_LE_CS_REFLECTOR_SNR_CONTROL_27dB = BT_HCI_OP_LE_CS_REFLECTOR_SNR_27,
BT_LE_CS_REFLECTOR_SNR_CONTROL_30dB = BT_HCI_OP_LE_CS_REFLECTOR_SNR_30,
BT_LE_CS_REFLECTOR_SNR_CONTROL_NOT_USED = BT_HCI_OP_LE_CS_REFLECTOR_SNR_NOT_USED,
};

/** CS Test Override 3 T_PM Tone Extension */
Expand Down Expand Up @@ -351,11 +313,11 @@ struct bt_le_cs_test_param {
/** Antenna Configuration Index used during antenna switching during
* the tone phases of CS steps.
*/
enum bt_le_cs_test_tone_antenna_config_selection tone_antenna_config_selection;
enum bt_conn_le_cs_tone_antenna_config_selection tone_antenna_config_selection;
/** Initiator SNR control options */
enum bt_le_cs_test_initiator_snr_control initiator_snr_control;
enum bt_le_cs_initiator_snr_control initiator_snr_control;
/** Reflector SNR control options */
enum bt_le_cs_test_reflector_snr_control reflector_snr_control;
enum bt_le_cs_reflector_snr_control reflector_snr_control;
/** Determines octets 14 and 15 of the initial value of the DRBG nonce. */
uint16_t drbg_nonce;

Expand Down Expand Up @@ -687,6 +649,178 @@ void bt_le_cs_step_data_parse(struct net_buf_simple *step_data_buf,
bool (*func)(struct bt_le_cs_subevent_step *step, void *user_data),
void *user_data);

/** @brief CS Security Enable
*
* This commmand is used to start or restart the Channel Sounding Security
* Start procedure in the local Controller for the ACL connection identified
* in the conn parameter.
*
* @note To use this API @kconfig{CONFIG_BT_CHANNEL_SOUNDING} must be set.
*
* @param conn Connection Object.
*
* @return Zero on success or (negative) error code on failure.
*/
int bt_le_cs_security_enable(struct bt_conn *conn);

struct bt_le_cs_procedure_enable_param {
uint8_t config_id;
enum bt_conn_le_cs_procedure_enable_state enable;
};

/** @brief CS Procedure Enable
*
* This command is used to enable or disable the scheduling of CS procedures
* by the local Controller, with the remote device identified in the conn
* parameter.
*
* @note To use this API @kconfig{CONFIG_BT_CHANNEL_SOUNDING} must be set.
*
* @param conn Connection Object.
* @param params Parameters for the CS Procedure Enable command.
*
* @return Zero on success or (negative) error code on failure.
*/
int bt_le_cs_procedure_enable(struct bt_conn *conn,
const struct bt_le_cs_procedure_enable_param *params);

enum bt_le_cs_procedure_phy {
BT_LE_CS_PROCEDURE_PHY_1M = BT_HCI_OP_LE_CS_PROCEDURE_PHY_1M,
BT_LE_CS_PROCEUDRE_PHY_2M = BT_HCI_OP_LE_CS_PROCEDURE_PHY_2M,
BT_LE_CS_PROCEDURE_PHY_CODED_S8 = BT_HCI_OP_LE_CS_PROCEDURE_PHY_CODED_S8,
BT_LE_CS_PROCEDURE_PHY_CODED_S2 = BT_HCI_OP_LE_CS_PROCEDURE_PHY_CODED_S2,
};

#define BT_LE_CS_PROCEDURE_PREFERRED_PEER_ANTENNA_1 BIT(0)
#define BT_LE_CS_PROCEDURE_PREFERRED_PEER_ANTENNA_2 BIT(1)
#define BT_LE_CS_PROCEDURE_PREFERRED_PEER_ANTENNA_3 BIT(2)
#define BT_LE_CS_PROCEDURE_PREFERRED_PEER_ANTENNA_4 BIT(3)

struct bt_le_cs_set_procedure_parameters_param {
/* The ID associated with the desired configuration (0 to 3) */
uint8_t config_id;

/* Max. duration for each CS procedure, where T = N * 0.625 ms (0x0001 to 0xFFFF) */
uint16_t max_procedure_len;

/* Min. number of connection events between consecutive CS procedures (0x0001 to 0xFFFF) */
uint16_t min_procedure_interval;

/* Max. number of connection events between consecutive CS procedures (0x0001 to 0xFFFF) */
uint16_t max_procedure_interval;

/* Max. number of procedures to be scheduled (0x0000 for no limit; otherwise 0x0001
* to 0xFFFF)
*/
uint16_t max_procedure_count;

/* Min. suggested duration for each CS subevent in microseconds (1250 us to 4 s) */
uint32_t min_subevent_len;

/* Max. suggested duration for each CS subevent in microseconds (1250 us to 4 s) */
uint32_t max_subevent_len;

/* Antenna configuration index */
enum bt_conn_le_cs_tone_antenna_config_selection tone_antenna_config_selection;

/* Phy */
enum bt_le_cs_procedure_phy phy;

/* Transmit power delta, in signed dB, to indicate the recommended difference between the
* remote device's power level for the CS tones and RTT packets and the existing power
* level for the Phy indicated by the Phy parameter (0x80 for no recommendation)
*/
int8_t tx_power_delta;

/* Preferred peer antenna (Bitmask of BT_LE_CS_PROCEDURE_PREFERRED_PEER_ANTENNA_*) */
uint8_t preferred_peer_antenna;

/* Initiator SNR control adjustment */
enum bt_le_cs_initiator_snr_control snr_control_initiator;

/* Reflector SNR control adjustment */
enum bt_le_cs_reflector_snr_control snr_control_reflector;
};

/** @brief CS Set Procedure Parameters
*
* This command is used to set the parameters for the scheduling of one
* or more CS procedures by the local controller.
*
* @note To use this API @kconfig{CONFIG_BT_CHANNEL_SOUNDING} must be set.
*
* @param conn Connection Object.
* @param params Parameters for the CS Set Procedure Parameters command.
*
* @return Zero on success or (negative) error code on failure.
*/
int bt_le_cs_set_procedure_parameters(struct bt_conn *conn,
const struct bt_le_cs_set_procedure_parameters_param *params);

/** @brief CS Set Channel Classification
*
* This command is used to update the channel classification based on
* its local information.
*
* The nth bitfield (in the range 0 to 78) contains the value for the CS
* channel index n. Channel Enabled = 1; Channel Disabled = 0.
*
* Channels n = 0, 1, 23, 24, 25, 77, and 78 shall be reserved for future
* use and shall be set to zero. At least 15 channels shall be enabled.
*
* The most significant bit (bit 79) is reserved for future use.
*
* @note To use this API, @kconfig{CONFIG_BT_CHANNEL_SOUNDING} must be set.
*
* @param channel_classification Bit fields
*
* @return Zero on success or (negative) error code on failure.
*/
int bt_le_cs_set_channel_classification(uint8_t channel_classification[10]);

/** @brief CS Read Local Supported Capabilities
*
* This command is used to read the CS capabilities that are supported
* by the local Controller.
*
* @note To use this API @kconfig{CONFIG_BT_CHANNEL_SOUNDING} must be set.
*
* @param ret Return values for the CS Procedure Enable command.
*
* @return Zero on success or (negative) error code on failure.
*/
int bt_le_cs_read_local_supported_capabilities(struct bt_conn_le_cs_capabilities *ret);

/** @brief CS Write Cached Remote Supported Capabilities
*
* This command is used to write the cached copy of the CS capabilities
* that are supported by the remote Controller for the connection
* identified.
*
* @note To use this API @kconfig{CONFIG_BT_CHANNEL_SOUNDING} must be set.
*
* @param conn Connection Object.
* @param params Parameters for the CS Write Cached Remote Supported Capabilities command.
*
* @return Zero on success or (negative) error code on failure.
*/
int bt_le_cs_write_cached_remote_supported_capabilities(
struct bt_conn *conn, const struct bt_conn_le_cs_capabilities *params);

/** @brief CS Write Cached Remote FAE Table
*
* This command is used to write a cached copy of the per-channel mode-0
* Frequency Actuation Error table of the remote device in the local Controller.
*
* @note To use this API @kconfig{CONFIG_BT_CHANNEL_SOUNDING} must be set.
*
* @param conn Connection Object.
* @param remote_fae_table Per-channel mode-0 FAE table of the local Controller
*
* @return Zero on success or (negative) error code on failure.
*/
int bt_le_cs_write_cached_remote_fae_table(struct bt_conn *conn, uint8_t remote_fae_table[72]);

#ifdef __cplusplus
}
#endif
Expand Down
Loading
Loading