/* * Copyright (c) 2019-2023 Beijing Hanwei Innovation Technology Ltd. Co. and * its subsidiaries and affiliates (collectly called MKSEMI). * * All rights reserved. * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions are met: * * 1. Redistributions of source code must retain the above copyright notice, * this list of conditions and the following disclaimer. * * 2. Redistributions in binary form, except as embedded into an MKSEMI * integrated circuit in a product or a software update for such product, * must reproduce the above copyright notice, this list of conditions and * the following disclaimer in the documentation and/or other materials * provided with the distribution. * * 3. Neither the name of MKSEMI nor the names of its contributors may be used * to endorse or promote products derived from this software without * specific prior written permission. * * 4. This software, with or without modification, must only be used with a * MKSEMI integrated circuit. * * 5. Any software provided in binary form under this license must not be * reverse engineered, decompiled, modified and/or disassembled. * * THIS SOFTWARE IS PROVIDED BY MKSEMI "AS IS" AND ANY EXPRESS OR IMPLIED * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF * MERCHANTABILITY, NONINFRINGEMENT, AND FITNESS FOR A PARTICULAR PURPOSE ARE * DISCLAIMED. IN NO EVENT SHALL MKSEMI OR CONTRIBUTORS BE LIABLE FOR ANY * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. */ #ifndef UWB_API_H_ #define UWB_API_H_ #include "mk_common.h" #include "mk_uwb.h" #include "lib_ranging.h" /** * @addtogroup MK8000_UCI_CMDS * @{ */ /** Fira Certification */ #ifndef FIRA_TEST_EN #define FIRA_TEST_EN (1) #endif #ifndef MCTT_TEST_EN #define MCTT_TEST_EN (0) #endif #ifndef DYNAMIC_UPDATE_MAIN_ANTENNA_EN #define DYNAMIC_UPDATE_MAIN_ANTENNA_EN (0) #endif #ifndef UWB_DUAL_RADAR #define UWB_DUAL_RADAR (0) #endif #define RANGING_CORR (0) /// Session State Code #define SESSION_STATE_INIT (0x00) #define SESSION_STATE_DEINIT (0x01) #define SESSION_STATE_ACTIVE (0x02) #define SESSION_STATE_IDLE (0x03) /** UWBS is initialized and ready for UWB */ #define DEVICE_STATE_READY (0x01) /** UWBS is busy with UWB session */ #define DEVICE_STATE_ACTIVE (0x02) /** Error occurred within the UWBS */ #define DEVICE_STATE_ERROR (0xFF) #define DEVICE_STATE_NONE (0x00) // type of session, 0x01-0x9F RFU #define SESSION_TYPE_RANGING (0x00) #define SESSION_TYPE_RANGING_IN_BAND_DATA (0x01) #define SESSION_TYPE_DATA_TRANSFER (0x02) #define SESSION_TYPE_RANGING_ONLY (0x03) #define SESSION_TYPE_IN_BAND_DATA (0x04) #define SESSION_TYPE_RANGING_WITH_DATA (0x05) // 0xA0-0x9F Reserved for Vendor Specific use case // device test mode, 0xD1-0xDF RFU #define SESSION_TYPE_DEVICE_TEST_MODE (0xD0) // 0xE0-0xFE Vendor Specific use #define SESSION_TYPE_VENDOR_RANGING_AND_RADAR (0xFD) #define SESSION_TYPE_VENDOR_ALONE_RADAR (0xFE) #define FREQ_OFFSET_SAMPLES_NUM 5 #define INITIATION_NUM (4) // In Fira spec the number of controlees 1~8 #ifndef RESPONDER_NUM_MAX #define RESPONDER_NUM_MAX (8) #endif #ifndef BIT_MAP_SIZE_MAX #define BIT_MAP_SIZE_MAX (32) #endif #define MEASUREMENT_NUM_MAX (RESPONDER_NUM_MAX) #define SLOT_NUM_PER_ROUND(x) (4 + 2 * (x)) #define SLOT_NUM_PER_ROUND_FOR_SS_TWR(x) (3 + 2 * (x)) #define SLOT_NUM_PER_ROUND_FOR_NON_DEFERRED_DS_TWR(x) (2 + 2 * (x)) #define SLOT_NUM_PER_ROUND_FOR_NON_DEFERRED_SS_TWR(x) (1 + (x)) #define UCI_MAJOR 1 #define UCI_MINOR 1 #define UCI_MAINTENANCE 0 #define MAC_MAJOR 1 #define MAC_MINOR 3 #define MAC_MAINTENANCE 0 #define PHY_MAJOR 1 #define PHY_MINOR 3 #define PHY_MAINTENANCE 0 #define UCI_TEST_MAJOR 1 #define UCI_TEST_MINOR 1 #define UCI_TEST_MAINTENANCE 0 #define UCI_HEADER_SIZE (4) #define UCI_MAX_PAYLOAD_SIZE (255) #define UWB_MODE_IDLE 0 #define UWB_MODE_READY 1 #define UWB_MODE_TX 2 #define UWB_MODE_RX 4 #define UWB_MODE_RANGING 3 #define UWB_MODE_TEST_PERIODIC_TX 6 #define UWB_MODE_TEST_PER_RX 7 #define UWB_MODE_TEST_RX 8 #define UWB_MODE_VENDOR_RX 9 #define UWB_MODE_VENDOR_CARRIER_TX 10 #define UWB_MODE_TEST_SS_TWR 11 /** UWB status */ enum UWB_STATUS_T { STATUS_OK = 0x00, STATUS_REJECTED = 0x01, STATUS_FAILED = 0x02, STATUS_SYNTAX_ERROR = 0x03, STATUS_INVALID_PARAM = 0x04, STATUS_INVALID_RANGE = 0x05, STATUS_INVALID_MESSAGE_SIZE = 0x06, STATUS_UNKNOWN_GID = 0x07, STATUS_UNKNOWN_OID = 0x08, STATUS_READ_ONLY = 0x09, STATUS_COMMAND_RETRY = 0x0A, STATUS_ERROR_SESSION_NOT_EXIST = 0x11, STATUS_ERROR_SESSION_DUPLICATE = 0x12, STATUS_ERROR_SESSION_ACTIVE = 0x13, STATUS_ERROR_MAX_SESSIONS_EXCEEDED = 0x14, STATUS_ERROR_SESSION_NOT_CONFIGURED = 0x15, STATUS_ERROR_ACTIVE_SESSIONS_ONGOING = 0x16, STATUS_ERROR_MULTICAST_LIST_FULL = 0x17, STATUS_ERROR_ADDRESS_NOT_FOUND = 0x18, STATUS_ERROR_ADDRESS_ALREADY_PRESENT = 0x19, STATUS_ERROR_UWB_INITIATION_TIME_TOO_OLD = 0x1A, STATUS_OK_NEGATIVE_DISTANCE_REPORT = 0x1B, STATUS_RANGING_TX_FAILED = 0x20, STATUS_RANGING_RX_TIMEOUT = 0x21, STATUS_RANGING_RX_PHY_DEC_FAILED = 0x22, STATUS_RANGING_RX_PHY_TOA_FAILED = 0x23, STATUS_RANGING_RX_PHY_STS_FAILED = 0x24, STATUS_RANGING_RX_MAC_DEC_FAILED = 0x25, STATUS_RANGING_RX_MAC_IE_DEC_FAILED = 0x26, STATUS_RANGING_RX_MAC_IE_MISSING = 0x27, STATUS_ERROR_ROUND_INDEX_NOT_ACTIVATED = 0x28, STATUS_ERROR_NUMBER_OF_ACTIVE_RANGING_ROUNDS_EXCEEDED = 0x29, STATUS_ERROR_ROUND_INDEX_NOT_SET_AS_INITIATOR = 0x2A, STATUS_ERROR_DL_TDOA_DEVICE_ADDRESS_NOT_MATCHING_IN_REPLY_TIME_LIST = 0x2B, STATUS_DEBUG_FLASH_IS_CLOSED = 0x30, STATUS_DEBUG_ERASE_ERROR = 0x31, STATUS_DEBUG_READ_MEM_ERROR = 0x32, STATUS_DEBUG_WRITE_MEM_ERROR = 0x33, STATUS_DEBUG_SE_INIT_FAILED = 0x33, STATUS_DEBUG_SE_READ_AID_FAILED = 0x34, STATUS_RANGING_RX_RESPONSE_OK = 0x35, /* Vendor Specific status code 0x55 - 0xFF */ STATUS_VENDOR_RESERVED = 0xFF, }; /** UCI Action */ typedef enum { ACTION_ADD_DEV = 0, ACTION_DELETE_DEV = 1, } ACTION_T; /** UWB device type */ enum DEV_TYPE_T { DEV_TYPE_CONTROLEE = 0, DEV_TYPE_CONTROLLER = 1, }; /** UWB device role */ enum DEV_ROLE_T { DEV_ROLE_RESPONDER = 0, DEV_ROLE_INITIATOR = 1, DEV_ROLE_UT_SYNC_ANCHOR = 2, /*!< UT-Synchronization Anchor */ DEV_ROLE_UT_ANCHOR = 3, /*!< UT-Anchor */ DEV_ROLE_UT_TAG = 4, /*!< UT-Tag */ DEV_ADVERTISER = 5, /*!< Advertiser */ DEV_OBSERVER = 6, /*!< Observer */ DEV_DT_ANCHOR = 7, /*!< DT-Anchor */ DEV_DT_TAG = 8, /*!< DT-Tag */ DEV_ROLE_GATE_CONTROLLER = 9, DEV_ROLE_GATE_CONTROLEE = 10, DEV_ROLE_TAG = 11, }; /** UWB ranging method */ enum RANGING_MODE_T { OWR_UL_TDOA = 0, SS_TWR_DEFERRED = 1, DS_TWR_DEFERRED = 2, SS_TWR = 3, DS_TWR = 4, OWR_DL_TDOA = 5, OWR_AOA = 6, ESS_TWR_CONTENTION = 7, DS_TWR_CONTENTION = 8, HYBRID_MODE = 9, DATA_TRANSFER_PHASE = 10, TWS_MODE = 11, UWB_AUDIO_MODE = 12, }; /** Multi node mode */ enum MULTI_NODE_MODE_T { UNICAST = 0, ONE_TO_MANY = 1, MANY_TO_MANY = 2, }; /** OWR message type */ enum OWR_MESSAGE_TYPE_T { OWR_BLINK_UTM = 0, OWR_SYNV_UTM = 1, OWR_POLL_DTM = 2, OWR_RESPONSE_DTM = 3, OWR_FINAL_DTM = 4, OWR_AOA_ADV = 5, }; /** UWB SFD ID */ enum SFD_ID_T { SFD0_LEN8 = 0, SFD1_LEN4 = 1, SFD2_LEN8 = 2, SFD3_LEN16 = 3, SFD4_LEN32 = 4, /* MKSEMI parameters */ SFD5_NON_STD_LEN8 = 5, // non-std 8 SFD6_NON_STD_LEN16 = 6, // non-std 16 SFD7_STD_LONG_LEN64 = 7, // 15.4a long }; /** UWB PSDU data rate */ enum PSDU_DATA_RATE_T { BPS_6M8 = 0, // K = 3 BPS_7M8 = 1, // K = 7 BPS_27M2 = 2, // K = 3 BPS_31M2 = 3, // K = 7 BPS_850K = 4, // K = 3 BPS_54M4 = 5, BPS_110K = 6, }; /** UWB Preamble length */ enum PREAMBLE_DURATION_T { SYMBOLS_32 = 0, SYMBOLS_64 = 1, /* MKSEMI parameter */ SYMBOLS_16 = 7, SYMBOLS_24 = 8, SYMBOLS_48 = 9, SYMBOLS_96 = 10, SYMBOLS_128 = 11, SYMBOLS_256 = 12, SYMBOLS_512 = 13, SYMBOLS_1024 = 14, SYMBOLS_2048 = 15, SYMBOLS_4096 = 16, }; /** UWB mean PRF mode */ enum PRF_MODE_T { /* Fira standard parameter */ PRF_62M4 = 0, // BPRF PRF_124M8 = 1, // HPRF PRF_249M6 = 2, // HPRF 27.2M 31.2M /* MKSEMI parameters */ PRF_154A_15M6 = 7, PRF_154A_62M4 = 8, PRF_PROPRI_15M6 = 9, PRF_PROPRI_62M4 = 10, }; /** UWB STS segments number */ enum STS_SEGMENTS_NUM_T { STS_SEGMENTS_NO = 0, STS_SEGMENTS_1 = 1, STS_SEGMENTS_2 = 2, STS_SEGMENTS_3 = 3, STS_SEGMENTS_4 = 4, }; /** UWB STS segments length */ enum STS_SEGMENTS_LENGTH_T { // Fira parameters STS_SEG_LEN32 = 0, STS_SEG_LEN64 = 1, STS_SEG_LEN128 = 2, // MKSEMI MK8000 support sts segments length STS_SEG_LEN16 = 7, STS_SEG_LEN256 = 8, }; /** UWB MAC address mode */ enum MAC_ADDRESS_MODE_T { ARRD_SHORT_USE_SHORT = 0, // MAC address is 2 bytes and 2 bytes to be used in MAC header ADDR_LONG_USE_SHORT = 1, // MAC address is 8 bytes and 2 bytes to be used in MAC header (Not supported) ADDR_LONG_USE_LONG = 2, // MAC address is 8 bytes and 8 bytes to be used in MAC header }; /** CRC type in MAC footer */ enum MAC_FCS_TYPE_T { FCS_CRC_16 = 0, // CRC 16 (default) FCS_CRC_32 = 1, // CRC 32 }; /** UWB STS config */ enum STS_CONFIG_T { STS_STATIC = 0, STS_DYNAMIC = 1, STS_DYNAMIC_SUB = 2, }; /** UWB Rframe type */ enum RFRAME_TYPE_T { SP0 = 0, SP1 = 1, SP3 = 3, }; /** UWB ranging flow mode */ enum RANGING_FLOW_MODE_T { RANGING_FLOW_FIRA = 0, RANGING_FLOW_CUSTOM = 1, RANGING_FLOW_CCC = 2, RANGING_FLOW_NONE = 3, RANGING_FLOW_SIMPLE = 4, RANGING_FLOW_CONTENTION = 5, RANGING_FLOW_DATA_TRANSFER = 6, }; /** UWB ranging stage */ enum RANGING_STAGE_T { // Simple/Custom RANGING_IDLE = 0x00, RANGING_SYNC = 0x01, RANGING_POLL = 0x02, RANGING_RESPONSE = 0x03, RANGING_FINAL = 0x04, RANGING_CFG = 0x05, RANGING_RESULT = 0x06, // CCC RANGING_PRE_POLL = 0x07, RANGING_FINAL_DATA = 0x08, // FIRA RANGING_RMM = 0x09, RANGING_RCM = 0x0A, RANGING_RIM = 0x0B, RANGING_RRM = 0x0C, RANGING_RFM = 0x0D, RANGING_MRM = 0x0E, RANGING_RRRM = 0x0F, // Contention-based RANGING_MRM_TX = 0x10, RANGING_MRM_RX = 0x11, // Data Transfer RANGING_DTPCM = 0x12, RANGING_DM_TX = 0x13, RANGING_DM_RX = 0x14, #if UWB_DUAL_RADAR // Ranging Radar RANGING_RADAR = 0x15, #endif }; /** UWB device config parameters */ struct DEVICE_CFG_PARAM_T { uint8_t device_state; uint8_t low_power_mode; }; /** UWB application config parameters */ struct APP_CFG_PARAM_T { uint8_t device_type; // 0x00 uint8_t ranging_round_usage; // 0x01 uint8_t sts_config; // 0x02 uint8_t multi_node_mode; // 0x03 uint8_t ch_num; // 0x04 uint8_t controlees_num; // 0x05 uint8_t res1[2]; uint8_t src_dev_mac_addr[8]; // 0x06 uint8_t dst_dev_mac_addr[64]; // 0x07 uint16_t slot_duration; // 0x08 uint8_t res2[2]; uint32_t ranging_interval; // 0x09 uint32_t sts_index; // 0x0A uint8_t mac_fcs_type; // 0x0B uint8_t ranging_round_control; // 0x0C uint8_t aoa_result_req; // 0x0D uint8_t session_info_ntf_cfg; // 0x0E uint16_t near_proximity_cfg; // 0x0F uint16_t far_proximity_cfg; // 0x10 uint8_t device_role; // 0x11 uint8_t rframe_config; // 0x12 uint8_t rssi_reporting; // 0x13 uint8_t preamble_code_index; // 0x14 uint8_t sfd_id; // 0x15 uint8_t psdu_data_rate; // 0x16 uint8_t preamble_duration; // 0x17 uint8_t link_layer_mode; // 0x18 uint8_t data_repetition_count; // 0x19 uint8_t ranging_time_struct; // 0x1A uint8_t slots_per_round; // 0x1B uint8_t tx_adaptive_payload_pwr; // 0x1C int16_t azimuth_lower_bound; // 0x1D Octet[1:0] int16_t azimuth_upper_bound; // 0x1D Octet[2:3] int16_t elevation_lower_bound; // 0x1D Octet[5:4] int16_t elevation_upper_bound; // 0x1D Octet[6:7] uint8_t responder_slot_idx; // 0x1E uint8_t prf_mode; // 0x1F uint8_t max_cap_size; // 0x20 Octet[0] uint8_t min_cap_size; // 0x20 Octet[1] uint8_t tx_jitter_win_size; // 0x21 uint8_t scheduled_mode; // 0x22 uint8_t key_rotation; // 0x23 uint8_t key_rotation_rate; // 0x24 uint8_t session_priority; // 0x25 uint8_t mac_address_mode; // 0x26 uint8_t vendor_id[2]; // 0x27 uint8_t static_sts_iv[6]; // 0x28 uint8_t sts_segment_num; // 0x29 uint8_t res3; uint16_t max_rr_retry; // 0x2A uint8_t res4[2]; #if FIRA_TEST_EN uint32_t uwb_initiation_time; // 0x2B #else uint64_t uwb_initiation_time; // 0x2B #endif uint8_t hopping_mode; // 0x2C uint8_t stride_length; // 0x2D uint8_t result_report_config; // 0x2E uint8_t inband_term_attempt_cnt; // 0x2F uint32_t sub_session_id; // 0x30 uint8_t bprf_phr_data_rate; // 0x31 uint8_t res5; uint16_t max_num_measurements; // 0x32 uint32_t ul_tdoa_tx_interval; // 0x33 uint32_t ul_tdoa_random_window; // 0x34 uint8_t sts_segment_len; // 0x35 uint8_t suspend_ranging_rounds; // 0x36 uint8_t res6[2]; uint8_t ul_tdoa_ntf_report_config[3]; // 0x37 uint8_t ul_tdoa_device_id[9]; // 0x38 uint8_t ul_tdoa_tx_timestamp; // 0x39 uint8_t min_frames_per_rr; // 0x3A uint16_t mtu_size; // 0x3B uint8_t inter_frame_interval; // 0x3C uint8_t dl_tdoa_ranging_method; // 0x3D uint8_t dl_tdoa_tx_timestamp_conf; // 0x3E uint8_t dl_tdoa_hop_count; // 0x3F uint8_t dl_tdoa_anchor_cfo; // 0x40 uint8_t res7[2]; uint8_t dl_tdoa_anchor_location[13]; // 0x41 uint8_t dl_tdoa_tx_active_ranging_rounds; // 0x42 uint8_t dl_tdoa_block_striding; // 0x43 uint8_t dl_tdoa_time_reference_anchor; // 0x44 uint8_t res8; uint8_t session_key[16]; // 0x45 uint8_t sub_session_key[16]; // 0x46 uint8_t data_trans_st_ntf_cfg; // 0x47 uint8_t res9[2]; uint8_t session_tb_ctrl; // 0x48 Octet[0] ctrl uint32_t session_tb_sesshdl; // 0x48 Octet[1:4] session handle uint32_t session_tb_offset; // 0x48 Octet[5:8] Session offset time in microseconds uint8_t dl_tdoa_responder_tof; // 0x49 uint8_t secure_ranging_nefa_level; // 0x4A uint8_t search_ranging_csw_length; // 0x4B uint8_t app_data_endpoint; // 0x4C /* Reserved for Vendor Specific use 0xA0-0xDF */ /* Additional configuration applicable only for CCC */ uint32_t hop_mode_key; // 0xA0 uint16_t ranging_proto_ver; // 0xA3 uint16_t uwb_cfg_id; // 0xA4 uint8_t pulseshape_combo; // 0xA5 /* Reserved for Vendor Specific Use */ uint8_t tx_power_level; // 0xF2 uint8_t rx_ant_id; // 0xF3 uint8_t per_payload_check; // 0xF4 /* Coded in us with bit 15 == 0 */ /* Coded in ms when bit 15 == 1 */ uint16_t ranging_anchor_resp_delay; // 0xF5 uint16_t ranging_tag_resp_delay; // 0xF6 /* UWB radar channel num {5, 9} * (default = 9) */ uint8_t uwb_radar_channel_num; // 0xF7 Octet[0] /* UWB radar STS segment length * 0x00: UWB_RADAR_STS_SEGLEN16 * 0x01: UWB_RADAR_STS_SEGLEN32 * 0x02: UWB_RADAR_STS_SEGLEN64 * (default = 0x02) */ uint8_t uwb_radar_sts_len; // 0xF7 Octet[1] /* UWB radar pulse period * 0x0: UWB_RADAR_PULSE_PERIOD 16ns * 0x1: UWB_RADAR_PULSE_PERIOD 32ns * 0x2: UWB_RADAR_PULSE_PERIOD 64ns * 0x3: UWB_RADAR_PULSE_PERIOD 128ns * 0x4: UWB_RADAR_PULSE_PERIOD 256ns * (default 64ns) */ uint8_t uwb_radar_pulse_period; // 0xF7 Octet[2] /* UWB radar rx filter gain level * 0 ~ 21 (default = 15) */ uint8_t uwb_radar_rx_gain_level; // 0xF7 Octet[3] /* UWB radar lna gain level 0 ~ 5 * (defalut = 5) */ uint8_t uwb_radar_lna_gain_level; // 0xF7 Octet[4] /* UWB radar tx power level */ uint8_t uwb_radar_tx_power_level; // 0xF7 Octet[5] /* UWB radar tx pulse width * 0x00: 2ns (Bandwidth 500M) * 0x01: 0.92ns (Bandwidth 900M) * 0x02: 0.75ns (Bandwidth 1.3G) * (defalut = 0x02) */ uint8_t uwb_radar_bandwidth; // 0xF7 Octet[6] /* UWB radar rx antenna port ID * 0x00: UWB_RX_ANTENNA 0 * 0x01: UWB_RX_ANTENNA 1 * 0x02: UWB_RX_ANTENNA 2 * (defalut = 0x00) */ uint8_t uwb_radar_rx_ant_id; // 0xF7 Octet[7] uint8_t uwb_radar_req; // 0xF7 Octet[8] }; /** UWB test config parameters */ struct TEST_CFG_PARAM_T { // 0 - No randomization (default) // 1 - Take first byte of data supplied by command and it SHALL be used as a seed for randomizing PSDU across // packets uint8_t randomize_psdu; // 0x00: STS_INDEX config value is used for all PER Rx/ Periodic TX test. (default) // 0x01: STS_INDEX value SHALL be incremented for every frame in PER Rx/Periodic TX test uint8_t sts_index_auto_inc; uint8_t reserved; // Number of packets (default 1000) uint32_t num_packets; // Gap between start of one packet to the next in us (default 2000us) uint32_t t_gap; // Max. time from the start of T_GAP to SFD found state in us (default 450us) // The SFD detection timeout uint32_t t_start; // Max. time for which RX is looking for a packet from the start of T_GAP in us (default 750us) uint32_t t_win; // Start time tx uint32_t rmarker_tx_start; // Start time rx uint32_t rmarker_rx_start; }; /** UWB core device informantion */ struct CORE_DEVICE_INFO_T { uint16_t uci_generic_version; uint16_t mac_version; uint16_t phy_version; uint16_t uci_test_version; }; /** UWB core device capability */ struct CORE_DEVICE_CAPS_INFO_T { // TBD uint8_t none; }; /** UWB session controlee device */ struct SESSION_CONTROLEE_DEV_T { uint8_t short_addr[2]; uint8_t sub_session_id[4]; }; /* Multicast update status */ struct CONTROLEE_STATUS { #define CONTROLEE_STATUS_FIX_LEN (7) #define STATUS_OK_MULTICAST_LIST_UPDATE (0x00) #define STATUS_ERROR_MULTICAST_LIST_Full (0x01) #define STATUS_ERROR_KEY_FETCH_FAIL (0x02) #define STATUS_ERROR_SUB_SESSION_ID_NOT_FOUND (0x03) #define STATUS_ERROR_ADDRESS_NOT_FOUND (0x07) #define STATUS_ERROR_ADDRESS_ALREADY_PRESENT (0x08) // Controlee short MAC address uint8_t mac_addr[2]; // Sub-session for which multicast update requested uint8_t sub_sessionID[4]; // Multicast update status uint8_t status; }; /** UWB RX TEST report */ struct TEST_RX_T { uint32_t rx_done_ts_int; const uint8_t *psdu_data; uint16_t rx_done_ts_frac; // Q9.7 int16_t aoa_azimuth; int16_t aoa_elevation; uint16_t phr; uint16_t psdu_data_len; uint8_t toa_gap; uint8_t status; }; /** UWB PER RX report */ struct TEST_PER_RX_T { uint8_t status; uint8_t reserved[3]; uint32_t attempts; uint32_t acq_detect; uint32_t acq_reject; uint32_t rx_fail; uint32_t sync_cir_ready; uint32_t sfd_fail; uint32_t sfd_found; uint32_t phr_dec_error; uint32_t phr_bit_error; uint32_t psdu_dec_error; uint32_t psdu_bit_error; uint32_t sts_found; uint32_t eof; }; /* UWB test packet TX done indication */ struct TEST_TX_DONE_IND_T { uint32_t phy_timer_count; uint32_t timestamp_int; /*!< Integer part of timestamp 1/124.8Mhz ticks. */ uint16_t timestamp_frac; /*!< Fractional part of timestamp in 1/(128 * 499.2Mhz) ticks */ uint16_t length; uint16_t status; uint8_t *data; }; /* UWB test packet RX done indication */ struct TEST_RX_DONE_IND_T { uint32_t phy_timer_count; uint32_t timestamp_int; /*!< Integer part of timestamp 1/124.8Mhz ticks. */ uint16_t timestamp_frac; /*!< Fractional part of timestamp in 1/(128 * 499.2Mhz) ticks */ uint16_t phr_bits; int8_t rssi; int8_t snr; uint16_t length; uint16_t status; uint8_t *data; }; /** UWB ranging measurement report */ struct RANGING_MEASUREMENT_T { uint8_t mac_addr[8]; uint8_t status; uint8_t NLoS; uint16_t distance; // Q9.7 int16_t aoa_azimuth; int16_t aoa_elevation; uint8_t aoa_azimuth_fom; uint8_t aoa_elevation_fom; // Q9.7 int16_t aoa_dst_azimuth; int16_t aoa_dst_elevation; uint8_t aoa_dst_azimuth_fom; uint8_t aoa_dst_elevation_fom; uint8_t slot_idx; uint8_t rfu[12]; uint8_t reserved; }; /** UWB ranging data report */ struct RANGE_DATA_T { uint32_t sequence_num; uint32_t session_id; // unit: ms uint32_t ranging_interval; uint8_t rcr_ind; uint8_t ranging_type; uint8_t mac_addr_mode; uint8_t measurements_num; struct RANGING_MEASUREMENT_T measurements[MEASUREMENT_NUM_MAX]; }; /** UWB test environment variable */ struct TEST_ENV_T { uint8_t enable; uint8_t sync_flag; uint16_t tx_pkt_len; uint8_t *tx_pkt_data; uint32_t trx_count_packet; /* This variable used to count how many packets were received or sent */ uint32_t sync_time; /* This variable is used to record the timestamp of the synchronization moment (unit:8ns) */ }; /** UWB operations handler */ struct UWB_OP_T { void (*session_configure)(void); void (*session_start)(void); void (*session_stop)(void); void (*session_local_addr_set)(uint16_t short_addr); void (*session_peer_addr_set)(uint16_t short_addr); uint8_t (*session_responder_addr_add)(uint16_t addr); void (*session_responder_list_clr)(void); uint8_t (*session_responder_num_get)(void); uint16_t (*session_responder_addr_get)(uint8_t idx); uint8_t (*session_dynamic_update_responder_list)(uint8_t action, uint16_t addr); void (*session_set_ccc_ursk)(const uint8_t *ursk); void (*vendor_session_start)(void); void (*vendor_session_stop)(void); void (*vendor_session_configure)(void); }; /** UWB application configuration */ struct UWB_APP_CFG_T { struct UWB_CONFIG_T ppdu_params; struct APP_CFG_PARAM_T session_param; struct TEST_CFG_PARAM_T test_param; uint8_t uwb_mode; uint8_t low_power_en; uint8_t filter_en; uint8_t session_type; uint8_t session_count; uint8_t session_state; uint8_t ranging_stage; uint8_t ranging_flow_mode; uint8_t responder_num_max; uint16_t cal_rounds; uint16_t cal_count; uint16_t target_cm; int32_t delay_rstu; int32_t ant_cal_distance_sum; uint32_t session_id; uint32_t ranging_count; // report int32_t rssi_total; int16_t rssi_num; int8_t rssi_min; int8_t rssi_max; }; #ifdef __cplusplus extern "C" { #endif extern struct UWB_APP_CFG_T uwb_app_config; extern struct TEST_ENV_T test_env; extern struct TEST_PER_RX_T uci_test_rx_per; extern struct TEST_RX_T uci_test_rx; typedef void (*range_report_cb_t)(void *report); typedef void (*test_periodic_tx_report_cb_t)(uint32_t *send_num_pkt); typedef void (*test_per_rx_report_cb_t)(struct TEST_PER_RX_T *report); typedef void (*test_rx_report_cb_t)(struct TEST_RX_T *report); typedef void (*test_ss_twr_report_cb_t)(uint8_t *, uint32_t); typedef void (*vendor_rx_report_cb_t)(const uint16_t *data_len, const uint8_t *data); typedef uint8_t (*vendor_user_defined_data_process_cb_t)(uint16_t cmd_len, const uint8_t *p_cmd); // UWB API /** * @brief Reset UWB subsystem, all the sessions context de-initialized/destroyed, internal states are re-initialized. * @return UWB Status code @ref UWB_STATUS_T */ uint8_t uwbapi_core_device_reset(void); /** * @brief Retrieve the device information like (UCI version and other vendor specific info). * @param[out] info @ref CORE_DEVICE_INFO_T buffer for the return information. * @return UWB Status code @ref UWB_STATUS_T */ uint8_t uwbapi_core_get_device_info(struct CORE_DEVICE_INFO_T *info); /** * @brief Get the capability of the UWB subsystem. * @param[out] info @ref CORE_DEVICE_CAPS_INFO_T buffer for the return information. * @return UWB Status code @ref UWB_STATUS_T */ uint8_t uwbapi_core_get_caps_info(struct CORE_DEVICE_CAPS_INFO_T *info); /** * @brief Set the configuration parameters on the UWB subsystem. * @param[in] cfg @ref DEVICE_CFG_PARAM_T configuration to be set. * @return UWB Status code @ref UWB_STATUS_T */ uint8_t uwbapi_core_set_config(struct DEVICE_CFG_PARAM_T *cfg); /** * @brief Get UWBS device state. * @return UWBS device state */ uint8_t uwbapi_get_device_state(void); /** * @brief Get the current configuration parameters of the UWB subsystem. * @param[out] cfg @ref DEVICE_CFG_PARAM_T buffer for the return configuration. * @return UWB Status code @ref UWB_STATUS_T */ uint8_t uwbapi_core_get_config(struct DEVICE_CFG_PARAM_T *cfg); /** * @brief Create a new UWB session. * @param[in] session_id session ID. * @param[in] session_type session type. * @return UWB Status code @ref UWB_STATUS_T */ uint8_t uwbapi_session_init(uint32_t session_id, uint8_t session_type); /** * @brief De-initialize the session, cleanup the UWB session data associated with the session ID. * @param[in] session_id session ID. * @return UWB Status code @ref UWB_STATUS_T */ uint8_t uwbapi_session_deinit(uint32_t session_id); /** * @brief Set application configuration parameters for the requested UWB session. * @param[in] session_id session ID. * @param[in] param @ref APP_CFG_PARAM_T parameter to be set. * @return UWB Status code @ref UWB_STATUS_T */ uint8_t uwbapi_session_set_app_config(uint32_t session_id, struct APP_CFG_PARAM_T *param); /** * @brief Retrieve the current application configuration parameters of the requested UWB session. * @param[in] session_id session ID. * @param[out] param @ref APP_CFG_PARAM_T buffer for the return configuration. * @return UWB Status code @ref UWB_STATUS_T */ uint8_t uwbapi_session_get_app_config(uint32_t session_id, struct APP_CFG_PARAM_T *param); /** * @brief Retrieve number of UWB sessions in the system. * @return The number of UWB sessions. */ uint8_t uwbapi_session_get_count(void); /** * @brief Query the current state of the UWB session * @param[in] session_id session ID. * @return UWB session state */ uint8_t uwbapi_session_get_state(uint32_t session_id); /** * @brief Set state for the UWB session * @param[in] session_id session ID. * @param[in] session_state sesstion state * @return UWB Status code @ref UWB_STATUS_T */ uint8_t uwbapi_session_update_state(uint32_t session_id, uint8_t session_state); /** * @brief Add or delete controlees dynamically during multicast ranging. * @param[in] action add or delete * @param[in] controlees_num number of controlees to be added or deleted * @param[in] session_id sesstion ID * @param[in] controlee_list controlee list * @return UWB Status code @ref UWB_STATUS_T */ uint8_t uwbapi_session_update_controller_multicast_list(uint8_t action, uint8_t controlees_num, uint32_t session_id, const struct SESSION_CONTROLEE_DEV_T *controlee_list, struct CONTROLEE_STATUS *controlees_status_list); /** * @brief Start the UWB session, while the UWB session is ongoing, the UWB subsystem shall report ranging result when the ranging round is complete. * @param[in] session_id session ID. * @param[in] func callback function to report ranging result. * @return UWB Status code @ref UWB_STATUS_T */ uint8_t uwbapi_session_start(uint32_t session_id, range_report_cb_t func); /** * @brief Stop the UWB session. * @param[in] session_id session ID. * @return UWB Status code @ref UWB_STATUS_T */ uint8_t uwbapi_session_stop(uint32_t session_id); /** * @brief Get the number of times ranging has been attempted during the ranging session. * @param[in] session_id session ID. * @param[out] count buffer for the return ranging count value. * @return UWB Status code @ref UWB_STATUS_T */ uint8_t uwbapi_range_get_ranging_count(uint32_t session_id, uint8_t *count); /** * @brief Set the configuration parameters for the test session. * @param[out] param @ref TEST_CFG_PARAM_T configuration parameters to be set. * @return UWB Status code @ref UWB_STATUS_T */ uint8_t uwbapi_test_config_set(struct TEST_CFG_PARAM_T *param); /** * @brief Get the current configuration parameters of the test session. * @param[out] param @ref TEST_CFG_PARAM_T buffer for the return configuration parameters. * @return UWB Status code @ref UWB_STATUS_T */ uint8_t uwbapi_test_config_get(struct TEST_CFG_PARAM_T *param); /** * @brief Start periodic TX test. * @param[in] psdu_len the length of packet to be sent periodically. * @param[in] psdu_data the packet data to be sent periodically, including FCS. * @param[in] func callback function to notify a configured number of packets have been sent. * @return UWB Status code @ref UWB_STATUS_T */ uint8_t uwbapi_test_periodic_tx(uint16_t psdu_len, const uint8_t *psdu_data, test_periodic_tx_report_cb_t func); /** * @brief Start packet error rate (PER) RX test. * @param[in] psdu_len the length of packet to be received periodically. * @param[in] psdu_data the packet data to be received periodically, including FCS. * @param[in] func callback function to report PER result when a configured number of packets have been elapsed. * @return UWB Status code @ref UWB_STATUS_T */ uint8_t uwbapi_test_per_rx(uint16_t psdu_len, const uint8_t *psdu_data, test_per_rx_report_cb_t func); /** * @brief Start RX test, this API is used to receive single packet and report signal parameters like SNR, AoA etc. * @param[in] func callback function to report RX test result. * @return UWB Status code @ref UWB_STATUS_T */ uint8_t uwbapi_test_rx(test_rx_report_cb_t func); /** * @brief Start loopback test, this API can be used as self-test to verify functional capabilities of UWBS device without any other UWBS device. * @param[in] psdu_len test packet length. * @param[in] psdu_data test packet data. * @return UWB Status code @ref UWB_STATUS_T */ uint8_t uwbapi_test_loopback(uint8_t psdu_len, const uint8_t *psdu_data); /** * @brief Start SS-TWR test, This API can be used to measure single SS-TWR ToF using SP3 packets. * @param[in] func callback function to report result. * @return UWB Status code @ref UWB_STATUS_T */ uint8_t uwbapi_test_ss_twr(test_ss_twr_report_cb_t func); /** * @brief Stop the test session. * @return UWB Status code @ref UWB_STATUS_T */ uint8_t uwbapi_test_stop_session(void); /** * @brief Start vendor defined continuous RX test. * @param[in] func callback function to report result. * @return UWB Status code @ref UWB_STATUS_T */ uint8_t uwbapi_vendor_rx_pkt_start(vendor_rx_report_cb_t func); /** * @brief Stop vendor defined continuous RX test. * @return UWB Status code @ref UWB_STATUS_T */ uint8_t uwbapi_vendor_rx_pkt_stop(void); /** * @brief Start ouput carrier. * @param[in] data_len data length. * @param[in] data payload * @return UWB Status code @ref UWB_STATUS_T */ uint8_t uwbapi_vendor_tx_carrier_only_start(uint8_t data_len, const uint8_t *data); /** * @brief Stop ouput carrier. * @return UWB Status code @ref UWB_STATUS_T */ uint8_t uwbapi_vendor_tx_carrier_only_stop(void); /** * @brief Start to transmit UWB CW in blocking mode. * @param[in] data_len data length. * @param[in] data payload * @return UWB Status code @ref UWB_STATUS_T */ uint8_t uwbapi_vendor_block_tx_start(uint8_t data_len, const uint8_t *data); /** * @brief Report uwb radar raw data from UWBS to host * @param[in] data_len radar raw data length. * @param[in] raw_data radar raw data */ void uwbapi_report_radar_raw_data(uint16_t data_len, const uint8_t *raw_data); /** * @brief Report channel status information * @param[in] csi channel status information */ void uwbapi_report_debug_csi_data(struct RANGING_CSI_T *csi); /** * @brief Report ranging data from UWBS to host * @param[in] report report data. */ void uwbapi_report_ranging_data(void *report); /** * @brief Report periodic tx test result from UWBS to host * @param[in] send_num_pkt packet number. */ void uwbapi_report_periodic_tx_data(uint32_t *send_num_pkt); /** * @brief Report PER RX test result from UWBS to host * @param[in] report report data. */ void uwbapi_report_per_rx_data(struct TEST_PER_RX_T *report); /** * @brief Report RX test result from UWBS to host * @param[in] report report data. */ void uwbapi_report_rx_test_data(struct TEST_RX_T *report); /** * @brief Report vendor defined continuous RX test result from UWBS to host. * @param[in] data_len packet length to be reported. * @param[in] p_data packet data to be reported. */ void uwbapi_report_vendor_rx_pkt(const uint16_t *data_len, const uint8_t *data); /** * @brief Report user defined data through UCI. * @note The initialization of the UCI needs to be completed before calling this function. * @note This function sends user-defined data to the host through the uci channel and you * can call this function where you need it to transfer data to the host. * @note The format of the data packet follows the UCI NTF data packet format GID=0xE, OID=0x5. * | Octet0 | Octet1 | Octet2 | Octet3 | Octet4-Octet(4+L) | * | NTF-PBF-GID | RFU-OID | RFU | rsp-length | Report-data | * | 0x6E | 0x05 | 0x00 | xx | xx | * @param[in] data_len packet length to be reported. * @param[in] p_data packet data to be reported. */ void uwbapi_report_user_defined_data(uint8_t data_len, const uint8_t *p_data); /** * @brief Registered user defined data processing function. * @note Only after UCI is initialized, the registered function will be called in the interaction process between host and slave. * @note The function will only be executed after the host sends a data in the following format, GID=0xE, OID=0x5. * | Octet0 | Octet1 | Octet2 | Octet3 | Octet4-Octet(4+L) | * | CMD-PBF-GID | RFU-OID | RFU | cmd-length | user-cmd-data | * | 0x2E | 0x05 | 0x00 | xx | CMD DATA | * @note The packet format of the Slave response is as follows and the value of code-err is the return * value of this function. If the function is not registered, the value of code-err defaults to 0xFF. * | Octet0 | Octet1 | Octet2 | Octet3 | Octet4 | Octet5 | * | RSP-PBF-GID | RFU-OID | RFU | rsp-length | STATUS_OK | code-err | * | 0x4E | 0x05 | 0x00 | 0x02 | 0x00 | default 0xFF | * @note Do not perform delay operations in this function to avoid the slave response timeout. * @param[in] func user-defined data processing function. */ void uwbapi_set_user_defined_data_process_handler(vendor_user_defined_data_process_cb_t func); /** * @brief Set URSK for CCC work mode * @param[in] ursk URSK data. * @param[in] len URSK length. * @return UWB Status code @ref UWB_STATUS_T */ uint8_t uwbapi_vendor_set_ccc_ursk(const uint8_t *ursk, uint16_t len); /** * @} */ // UWB Subsystem API /** * @addtogroup MK8000_UWB_SUBSYSTEM * @{ */ /** * @brief UWBS initialization. */ void uwbs_init(void); /** * @brief Initialize UWBS process handler. * @param[in] op processing handler list. */ void uwbs_handler_init(struct UWB_OP_T *op); /** * @brief Configure UWB transceiver work at TX or RX mode. * @param[in] mode work mode, PHY_TX or PHY_RX or both. * @param[in] tx_power_level TX power level */ void uwbs_configure(uint8_t mode, uint8_t tx_power_level); /** * @brief Get mac addr mode. * @return Mac addr mode : short or long */ uint8_t uwbs_mac_addr_mode_get(void); /** * @brief Set UWB mac addr mode. * @param[in] mode mac addr mode @ref enum MAC_ADDRESS_MODE_T * @return 0: success, -1: failed */ int uwbs_mac_addr_mode_set(enum MAC_ADDRESS_MODE_T mode); /** * @brief Get UWBS local short address. * @return Local short address */ uint16_t uwbs_local_short_addr_get(void); /** * @brief Get UWBS peer short address. * @return Peer short address */ uint16_t uwbs_peer_short_addr_get(void); /** * @brief Set UWBS local short address. * @param[in] short_addr Local short address to be set */ void uwbs_local_short_addr_set(uint16_t short_addr); /** * @brief Set UWBS peer short address. * @param[in] short_addr Peer short address to be set */ void uwbs_peer_short_addr_set(uint16_t short_addr); /** * @brief Set UWBS local long address. * @param[in] long_addr Local long address to be set */ void uwbs_local_long_addr_set(uint8_t long_addr[8]); /** * @brief Set UWBS peer long address. * @param[in] long_addr Peer long address to be set */ void uwbs_peer_long_addr_set(uint8_t long_addr[8]); /** * @brief Get UWBS local long address. * @return Local long address */ uint8_t *uwbs_local_long_addr_get(void); /** * @brief Get UWBS peer long address. * @return Peer long address */ uint8_t *uwbs_peer_long_addr_get(void); /** * @brief Get UWBS pan ID. * @return Pan ID */ uint16_t uwbs_pan_id_get(void); /** * @brief Set UWBS pan ID. * @param[in] pan_id Pan ID to be set */ void uwbs_pan_id_set(uint16_t pan_id); /** * @brief Enable or disable UWBS security. * @param[in] en Enable or disable */ void uwbs_security_enable_set(uint8_t en); /** * @brief Set UWB configuration id for CCC. * @param[in] uwb_cfg_id CCC UWB configuration id */ uint8_t uwbs_ccc_uwb_config_id_set(uint16_t uwb_cfg_id); /** * @brief Clear RSSI statistical result in PER test procedure. */ void uwbs_clear_rssi(void); /** * @brief update RSSI for statistic. * @param[in] rssi new RSSI value */ void uwbs_update_rssi(int8_t rssi); /** * @brief Get RSSI statistical result. * @param[in] rssi_avg output RSSI average result * @param[in] rssi_min output RSSI minimum value * @param[in] rssi_max output RSSI maximum value */ void uwbs_get_rssi(int8_t *rssi_avg, int8_t *rssi_min, int8_t *rssi_max); /** * @brief Check SE connection. * @param[in] p_des_data output test data * @param[in] p_des_len output test data length * @return 1: Connected, 0: NC */ uint8_t uwbs_check_se(uint8_t *p_des_data, uint8_t *p_des_len); /** * @brief Set UWB tx and rx shared buffer for test session. * @param[in] buffer output RSSI average result */ void uwbs_test_pkt_buffer_set(uint8_t *buffer); /** * @brief Transform angle format for FiRa UWB packet * @param[in] angle angle in Q9.7 format * @param[in] range 180 for azimuth, 90 for elevation * @return formatted angle, unit is 360 * 2^-16 */ int16_t uwbapi_q7_to_angle_ota_format(int16_t angle, int16_t range); /** * @brief Transform angle in FiRa UWB packet to Q9.7 format * @param[in] data angle in UWB packet, unit is 360 * 2^-16 * @param[in] range 180 for azimuth, 90 for elevation * @return angle Q9.7 format */ int16_t uwbapi_angle_ota_format_to_q7(int16_t data, int16_t range); /** * @brief Get ranging flow mode * @return ranging flow mode @ref enum RANGING_FLOW_MODE_T */ uint8_t uwbs_ranging_flow_mode_get(void); /** * @brief Get ranging stage * @return ranging stage @ref enum RANGING_STAGE_T */ uint8_t uwbs_ranging_stage_get(void); /** * @brief Get ranging device role * @return ranging device role @ref enum DEV_ROLE_T */ uint8_t uwbs_ranging_role_get(void); #ifdef __cplusplus } #endif /** * @} */ #endif /* UWB_API_H_ */