cs.h

Go to the documentation of this file.

 
/*
 * Copyright (c) 2024 Nordic Semiconductor ASA
 *
 * SPDX-License-Identifier: Apache-2.0
 */
#ifndef ZEPHYR_INCLUDE_BLUETOOTH_CS_H_
#define ZEPHYR_INCLUDE_BLUETOOTH_CS_H_
 
#include <stdint.h>
#include <stdbool.h>
 
#include <zephyr/bluetooth/hci_types.h>
#include <zephyr/bluetooth/conn.h>
#include <zephyr/net_buf.h>
#include <zephyr/sys/util_macro.h>
 
#ifdef __cplusplus
extern "C" {
#endif
 
#define BT_LE_CS_CHANNEL_BIT_GET(chmap, bit) (((chmap)[(bit) / 8] >> ((bit) % 8)) & 1)
 
#define BT_LE_CS_CHANNEL_BIT_SET_VAL(chmap, bit, val)                                              \
        ((chmap)[(bit) / 8] = ((chmap)[(bit) / 8] & ~BIT((bit) % 8)) | ((val) << ((bit) % 8)))
 
enum bt_le_cs_sync_antenna_selection_opt {
        BT_LE_CS_ANTENNA_SELECTION_OPT_ONE = BT_HCI_OP_LE_CS_ANTENNA_SEL_ONE,
        BT_LE_CS_ANTENNA_SELECTION_OPT_TWO = BT_HCI_OP_LE_CS_ANTENNA_SEL_TWO,
        BT_LE_CS_ANTENNA_SELECTION_OPT_THREE = BT_HCI_OP_LE_CS_ANTENNA_SEL_THREE,
        BT_LE_CS_ANTENNA_SELECTION_OPT_FOUR = BT_HCI_OP_LE_CS_ANTENNA_SEL_FOUR,
        BT_LE_CS_ANTENNA_SELECTION_OPT_REPETITIVE = BT_HCI_OP_LE_CS_ANTENNA_SEL_REP,
        BT_LE_CS_ANTENNA_SELECTION_OPT_NO_RECOMMENDATION = BT_HCI_OP_LE_CS_ANTENNA_SEL_NONE,
};
 
struct bt_le_cs_set_default_settings_param {
        bool enable_initiator_role;
        bool enable_reflector_role;
        enum bt_le_cs_sync_antenna_selection_opt cs_sync_antenna_selection;
        int8_t max_tx_power;
};
 
enum bt_le_cs_test_cs_sync_antenna_selection {
        BT_LE_CS_TEST_CS_SYNC_ANTENNA_SELECTION_ONE = BT_HCI_OP_LE_CS_ANTENNA_SEL_ONE,
        BT_LE_CS_TEST_CS_SYNC_ANTENNA_SELECTION_TWO = BT_HCI_OP_LE_CS_ANTENNA_SEL_TWO,
        BT_LE_CS_TEST_CS_SYNC_ANTENNA_SELECTION_THREE = BT_HCI_OP_LE_CS_ANTENNA_SEL_THREE,
        BT_LE_CS_TEST_CS_SYNC_ANTENNA_SELECTION_FOUR = BT_HCI_OP_LE_CS_ANTENNA_SEL_FOUR,
};
 
enum bt_le_cs_snr_control {
        BT_LE_CS_SNR_CONTROL_18dB = BT_HCI_OP_LE_CS_SNR_18,
        BT_LE_CS_SNR_CONTROL_21dB = BT_HCI_OP_LE_CS_SNR_21,
        BT_LE_CS_SNR_CONTROL_24dB = BT_HCI_OP_LE_CS_SNR_24,
        BT_LE_CS_SNR_CONTROL_27dB = BT_HCI_OP_LE_CS_SNR_27,
        BT_LE_CS_SNR_CONTROL_30dB = BT_HCI_OP_LE_CS_SNR_30,
        BT_LE_CS_SNR_CONTROL_NOT_USED = BT_HCI_OP_LE_CS_SNR_NOT_USED,
};
 
enum bt_le_cs_test_override_3_pm_tone_ext {
        BT_LE_CS_TEST_OVERRIDE_3_NO_TONE_EXT = BT_HCI_OP_LE_CS_TEST_TONE_EXT_NONE,
        BT_LE_CS_TEST_OVERRIDE_3_INITIATOR_TONE_EXT_ONLY = BT_HCI_OP_LE_CS_TEST_TONE_EXT_INIT,
        BT_LE_CS_TEST_OVERRIDE_3_REFLECTOR_TONE_EXT_ONLY = BT_HCI_OP_LE_CS_TEST_TONE_EXT_REFL,
        BT_LE_CS_TEST_OVERRIDE_3_INITIATOR_AND_REFLECTOR_TONE_EXT =
                BT_HCI_OP_LE_CS_TEST_TONE_EXT_BOTH,
        BT_LE_CS_TEST_OVERRIDE_3_REPETITIVE_TONE_EXT = BT_HCI_OP_LE_CS_TEST_TONE_EXT_REPEAT,
};
 
enum bt_le_cs_test_override_4_tone_antenna_permutation {
        BT_LE_CS_TEST_OVERRIDE_4_ANTENNA_PERMUTATION_INDEX_00 = BT_HCI_OP_LE_CS_TEST_AP_INDEX_00,
        BT_LE_CS_TEST_OVERRIDE_4_ANTENNA_PERMUTATION_INDEX_01 = BT_HCI_OP_LE_CS_TEST_AP_INDEX_01,
        BT_LE_CS_TEST_OVERRIDE_4_ANTENNA_PERMUTATION_INDEX_02 = BT_HCI_OP_LE_CS_TEST_AP_INDEX_02,
        BT_LE_CS_TEST_OVERRIDE_4_ANTENNA_PERMUTATION_INDEX_03 = BT_HCI_OP_LE_CS_TEST_AP_INDEX_03,
        BT_LE_CS_TEST_OVERRIDE_4_ANTENNA_PERMUTATION_INDEX_04 = BT_HCI_OP_LE_CS_TEST_AP_INDEX_04,
        BT_LE_CS_TEST_OVERRIDE_4_ANTENNA_PERMUTATION_INDEX_05 = BT_HCI_OP_LE_CS_TEST_AP_INDEX_05,
        BT_LE_CS_TEST_OVERRIDE_4_ANTENNA_PERMUTATION_INDEX_06 = BT_HCI_OP_LE_CS_TEST_AP_INDEX_06,
        BT_LE_CS_TEST_OVERRIDE_4_ANTENNA_PERMUTATION_INDEX_07 = BT_HCI_OP_LE_CS_TEST_AP_INDEX_07,
        BT_LE_CS_TEST_OVERRIDE_4_ANTENNA_PERMUTATION_INDEX_08 = BT_HCI_OP_LE_CS_TEST_AP_INDEX_08,
        BT_LE_CS_TEST_OVERRIDE_4_ANTENNA_PERMUTATION_INDEX_09 = BT_HCI_OP_LE_CS_TEST_AP_INDEX_09,
        BT_LE_CS_TEST_OVERRIDE_4_ANTENNA_PERMUTATION_INDEX_10 = BT_HCI_OP_LE_CS_TEST_AP_INDEX_10,
        BT_LE_CS_TEST_OVERRIDE_4_ANTENNA_PERMUTATION_INDEX_11 = BT_HCI_OP_LE_CS_TEST_AP_INDEX_11,
        BT_LE_CS_TEST_OVERRIDE_4_ANTENNA_PERMUTATION_INDEX_12 = BT_HCI_OP_LE_CS_TEST_AP_INDEX_12,
        BT_LE_CS_TEST_OVERRIDE_4_ANTENNA_PERMUTATION_INDEX_13 = BT_HCI_OP_LE_CS_TEST_AP_INDEX_13,
        BT_LE_CS_TEST_OVERRIDE_4_ANTENNA_PERMUTATION_INDEX_14 = BT_HCI_OP_LE_CS_TEST_AP_INDEX_14,
        BT_LE_CS_TEST_OVERRIDE_4_ANTENNA_PERMUTATION_INDEX_15 = BT_HCI_OP_LE_CS_TEST_AP_INDEX_15,
        BT_LE_CS_TEST_OVERRIDE_4_ANTENNA_PERMUTATION_INDEX_16 = BT_HCI_OP_LE_CS_TEST_AP_INDEX_16,
        BT_LE_CS_TEST_OVERRIDE_4_ANTENNA_PERMUTATION_INDEX_17 = BT_HCI_OP_LE_CS_TEST_AP_INDEX_17,
        BT_LE_CS_TEST_OVERRIDE_4_ANTENNA_PERMUTATION_INDEX_18 = BT_HCI_OP_LE_CS_TEST_AP_INDEX_18,
        BT_LE_CS_TEST_OVERRIDE_4_ANTENNA_PERMUTATION_INDEX_19 = BT_HCI_OP_LE_CS_TEST_AP_INDEX_19,
        BT_LE_CS_TEST_OVERRIDE_4_ANTENNA_PERMUTATION_INDEX_20 = BT_HCI_OP_LE_CS_TEST_AP_INDEX_20,
        BT_LE_CS_TEST_OVERRIDE_4_ANTENNA_PERMUTATION_INDEX_21 = BT_HCI_OP_LE_CS_TEST_AP_INDEX_21,
        BT_LE_CS_TEST_OVERRIDE_4_ANTENNA_PERMUTATION_INDEX_22 = BT_HCI_OP_LE_CS_TEST_AP_INDEX_22,
        BT_LE_CS_TEST_OVERRIDE_4_ANTENNA_PERMUTATION_INDEX_23 = BT_HCI_OP_LE_CS_TEST_AP_INDEX_23,
        BT_LE_CS_TEST_OVERRIDE_4_ANTENNA_PERMUTATION_INDEX_LOOP =
                BT_HCI_OP_LE_CS_TEST_AP_INDEX_LOOP,
};
 
enum bt_le_cs_test_override_7_ss_marker_value {
        BT_LE_CS_TEST_OVERRIDE_7_SS_MARKER_VAL_0011 = BT_HCI_OP_LE_CS_TEST_SS_MARKER_VAL_0011,
        BT_LE_CS_TEST_OVERRIDE_7_SS_MARKER_VAL_1100 = BT_HCI_OP_LE_CS_TEST_SS_MARKER_VAL_1100,
        BT_LE_CS_TEST_OVERRIDE_7_SS_MARKER_VAL_LOOP = BT_HCI_OP_LE_CS_TEST_SS_MARKER_VAL_LOOP,
};
 
enum bt_le_cs_test_override_8_cs_sync_payload_pattern {
        BT_LE_CS_TEST_OVERRIDE_8_PAYLOAD_PATTERN_PRBS9 = BT_HCI_OP_LE_CS_TEST_PAYLOAD_PRBS9,
        BT_LE_CS_TEST_OVERRIDE_8_PAYLOAD_PATTERN_11110000 = BT_HCI_OP_LE_CS_TEST_PAYLOAD_11110000,
        BT_LE_CS_TEST_OVERRIDE_8_PAYLOAD_PATTERN_10101010 = BT_HCI_OP_LE_CS_TEST_PAYLOAD_10101010,
        BT_LE_CS_TEST_OVERRIDE_8_PAYLOAD_PATTERN_PRBS15 = BT_HCI_OP_LE_CS_TEST_PAYLOAD_PRBS15,
        BT_LE_CS_TEST_OVERRIDE_8_PAYLOAD_PATTERN_11111111 = BT_HCI_OP_LE_CS_TEST_PAYLOAD_11111111,
        BT_LE_CS_TEST_OVERRIDE_8_PAYLOAD_PATTERN_00000000 = BT_HCI_OP_LE_CS_TEST_PAYLOAD_00000000,
        BT_LE_CS_TEST_OVERRIDE_8_PAYLOAD_PATTERN_00001111 = BT_HCI_OP_LE_CS_TEST_PAYLOAD_00001111,
        BT_LE_CS_TEST_OVERRIDE_8_PAYLOAD_PATTERN_01010101 = BT_HCI_OP_LE_CS_TEST_PAYLOAD_01010101,
        BT_LE_CS_TEST_OVERRIDE_8_PAYLOAD_PATTERN_USER = BT_HCI_OP_LE_CS_TEST_PAYLOAD_USER,
};
 
struct bt_le_cs_test_param {
        enum bt_conn_le_cs_main_mode main_mode;
        enum bt_conn_le_cs_sub_mode sub_mode;
        uint8_t main_mode_repetition;
        uint8_t mode_0_steps;
        enum bt_conn_le_cs_role role;
        enum bt_conn_le_cs_rtt_type rtt_type;
        enum bt_conn_le_cs_sync_phy cs_sync_phy;
        enum bt_le_cs_test_cs_sync_antenna_selection cs_sync_antenna_selection;
        uint32_t subevent_len;
        uint16_t subevent_interval;
        uint8_t max_num_subevents;
        uint8_t transmit_power_level;
        uint8_t t_ip1_time;
        uint8_t t_ip2_time;
        uint8_t t_fcs_time;
        uint8_t t_pm_time;
        uint8_t t_sw_time;
        enum bt_conn_le_cs_tone_antenna_config_selection tone_antenna_config_selection;
        enum bt_le_cs_snr_control initiator_snr_control;
        enum bt_le_cs_snr_control reflector_snr_control;
        uint16_t drbg_nonce;
 
        uint16_t override_config;
 
        struct {
                uint8_t channel_map_repetition;
                union {
                        struct {
                                uint8_t num_channels;
                                uint8_t *channels;
                        } set;
                        struct {
                                uint8_t channel_map[10];
                                enum bt_conn_le_cs_chsel_type channel_selection_type;
                                enum bt_conn_le_cs_ch3c_shape ch3c_shape;
                                uint8_t ch3c_jump;
                        } not_set;
                };
        } override_config_0;
 
        struct {
                uint8_t main_mode_steps;
        } override_config_2;
 
        struct {
                enum bt_le_cs_test_override_3_pm_tone_ext t_pm_tone_ext;
        } override_config_3;
 
        struct {
                enum bt_le_cs_test_override_4_tone_antenna_permutation tone_antenna_permutation;
        } override_config_4;
 
        struct {
                uint32_t cs_sync_aa_initiator;
                uint32_t cs_sync_aa_reflector;
        } override_config_5;
 
        struct {
                uint8_t ss_marker1_position;
                uint8_t ss_marker2_position;
        } override_config_6;
 
        struct {
                enum bt_le_cs_test_override_7_ss_marker_value ss_marker_value;
        } override_config_7;
 
        struct {
                enum bt_le_cs_test_override_8_cs_sync_payload_pattern cs_sync_payload_pattern;
                uint8_t cs_sync_user_payload[16];
        } override_config_8;
};
 
enum bt_le_cs_create_config_context {
        BT_LE_CS_CREATE_CONFIG_CONTEXT_LOCAL_ONLY,
        BT_LE_CS_CREATE_CONFIG_CONTEXT_LOCAL_AND_REMOTE
};
 
struct bt_le_cs_create_config_params {
        uint8_t id;
        enum bt_conn_le_cs_main_mode main_mode_type;
        enum bt_conn_le_cs_sub_mode sub_mode_type;
        uint8_t min_main_mode_steps;
        uint8_t max_main_mode_steps;
        uint8_t main_mode_repetition;
        uint8_t mode_0_steps;
        enum bt_conn_le_cs_role role;
        enum bt_conn_le_cs_rtt_type rtt_type;
        enum bt_conn_le_cs_sync_phy cs_sync_phy;
        uint8_t channel_map_repetition;
        enum bt_conn_le_cs_chsel_type channel_selection_type;
        enum bt_conn_le_cs_ch3c_shape ch3c_shape;
        uint8_t ch3c_jump;
        uint8_t channel_map[10];
};
 
struct bt_le_cs_test_cb {
        void (*le_cs_test_subevent_data_available)(struct bt_conn_le_cs_subevent_result *data);
        void (*le_cs_test_end_complete)(void);
};
 
struct bt_le_cs_subevent_step {
        uint8_t mode;
        uint8_t channel;
        uint8_t data_len;
        const uint8_t *data;
};
 
struct bt_le_cs_iq_sample {
        int16_t i;
        int16_t q;
};
 
struct bt_le_cs_iq_sample bt_le_cs_parse_pct(const uint8_t pct[3]);
 
void bt_le_cs_set_valid_chmap_bits(uint8_t channel_map[10]);
 
int bt_le_cs_read_remote_supported_capabilities(struct bt_conn *conn);
 
int bt_le_cs_set_default_settings(struct bt_conn *conn,
                                  const struct bt_le_cs_set_default_settings_param *params);
 
int bt_le_cs_read_remote_fae_table(struct bt_conn *conn);
 
int bt_le_cs_test_cb_register(struct bt_le_cs_test_cb cs_test_cb);
 
int bt_le_cs_start_test(const struct bt_le_cs_test_param *params);
 
int bt_le_cs_create_config(struct bt_conn *conn, struct bt_le_cs_create_config_params *params,
                           enum bt_le_cs_create_config_context context);
 
int bt_le_cs_remove_config(struct bt_conn *conn, uint8_t config_id);
 
int bt_le_cs_stop_test(void);
 
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);
 
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;
};
 
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_PROCEDURE_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_snr_control snr_control_initiator;
 
        /* Reflector SNR control adjustment */
        enum bt_le_cs_snr_control snr_control_reflector;
};
 
int bt_le_cs_set_procedure_parameters(struct bt_conn *conn,
                                      const struct bt_le_cs_set_procedure_parameters_param *params);
 
int bt_le_cs_set_channel_classification(uint8_t channel_classification[10]);
 
int bt_le_cs_read_local_supported_capabilities(struct bt_conn_le_cs_capabilities *ret);
 
int bt_le_cs_write_cached_remote_supported_capabilities(
        struct bt_conn *conn, const struct bt_conn_le_cs_capabilities *params);
 
int bt_le_cs_write_cached_remote_fae_table(struct bt_conn *conn, int8_t remote_fae_table[72]);
 
int bt_le_cs_get_antenna_path(uint8_t n_ap,
                              uint8_t antenna_path_permutation_index,
                              uint8_t tone_index);
 
#ifdef __cplusplus
}
#endif
 
#endif /* ZEPHYR_INCLUDE_BLUETOOTH_CS_H_ */