/*
|
* 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 RANGING_H_
|
#define RANGING_H_
|
#include "ranging_custom_task.h"
|
#include "wsf_timer.h"
|
#include "mk_mac.h"
|
#include "uwb_api.h"
|
#include "lib_ranging.h"
|
|
#ifndef ASYNC_MODE_EN
|
#define ASYNC_MODE_EN (0)
|
#endif
|
|
#ifndef RESPONDER_NUM
|
#define RESPONDER_NUM (1)
|
#endif
|
|
#ifndef AOA_3D_EN
|
#define AOA_3D_EN (0)
|
#endif
|
|
#ifndef PDOA_3D_EN
|
#define PDOA_3D_EN (0)
|
#endif
|
|
#ifndef RANGING_RESULT_REPORT_EN
|
#define RANGING_RESULT_REPORT_EN (0)
|
#endif
|
|
#ifndef RANGING_FOM_FILTER_EN
|
#define RANGING_FOM_FILTER_EN (1)
|
#endif
|
|
#if RANGING_FOM_FILTER_EN
|
#define RFRAME_INF_SIZE (4 + CIR_LEN / CE_WIN - 1)
|
#else
|
#define RFRAME_INF_SIZE (2)
|
#endif
|
|
#define MSG_SESSION_ID_IDX 0
|
#define MSG_SEQ_NUM_IDX 2
|
#define MSG_TYPE_IDX 4
|
#define MSG_HEADER_LEN 5
|
|
#define MSG_POLL_RESPONDER_NUM_IDX (0)
|
// x : 0 ~ RESPONDER_NUM-1
|
#define MSG_POLL_RESPONDER_ID_IDX(x) (1 + (x)*3)
|
#define MSG_POLL_RESPONDER_SLOT_IDX(x) (1 + (x)*3 + 2)
|
#define MSG_POLL_TX_PWR_IDX (1 + RESPONDER_NUM * 3)
|
#define MSG_POLL_USER_DATA_IDX (1 + RESPONDER_NUM * 3 + 1)
|
#define MSG_POLL_USER_DATA_LEN (125 - MSG_HEADER_LEN - MSG_POLL_USER_DATA_IDX)
|
|
#define MSG_RESPONSE_RESPONDER_ID_IDX 0
|
#define MSG_RESPONSE_TX_PWR_IDX (2)
|
#define MSG_RESPONSE_USER_DATA_IDX (3)
|
#define MSG_RESPONSE_USER_DATA_LEN (125 - MSG_HEADER_LEN - MSG_RESPONSE_USER_DATA_IDX)
|
|
#define MSG_FINAL_RESPONDER_NUM_IDX 0
|
#define MSG_FINAL_TREPLY_IDX 1
|
// x : 0 ~ RESPONDER_NUM-1
|
#define MSG_FINAL_TROUND_IDX(x) (6 + (x)*5)
|
#define MSG_FINAL_FOM_IDX(x) (6 + RESPONDER_NUM * 5 + (x)*RFRAME_INF_SIZE)
|
#define MSG_FINAL_NLOS_IDX(x) (MSG_FINAL_FOM_IDX(x) + 1)
|
#define MSG_FINAL_FAP_VALID_IDX(x) (MSG_FINAL_FOM_IDX(x) + 2)
|
#define MSG_FINAL_GAPS_NUM_IDX(x) (MSG_FINAL_FOM_IDX(x) + 3)
|
#define MSG_FINAL_GAPS_IDX(x) (MSG_FINAL_FOM_IDX(x) + 4)
|
#define MSG_FINAL_USER_DATA_IDX (MSG_FINAL_FOM_IDX(RESPONDER_NUM))
|
#define MSG_FINAL_USER_DATA_LEN (125 - MSG_HEADER_LEN - MSG_FINAL_USER_DATA_IDX)
|
|
#define MSG_RESULT_INFO_LEN (8)
|
|
#if (MSG_POLL_USER_DATA_LEN < 0) || (MSG_RESPONSE_USER_DATA_LEN < 0) || (MSG_FINAL_USER_DATA_LEN < 0)
|
#error "RESPONDER_NUM is out of range"
|
#endif
|
|
/*
|
* The content of the ranging packet is customized by the user, but the first five bytes of
|
* each data packet are fixed, 2 bytes of session-id, 2 bytes of seq-num, 1 byte of packet type
|
* The length of the air interface data packet transmitted by the actual UWB shall prevail.
|
*/
|
struct RANGING_USER_PKT_T
|
{
|
uint16_t session_id;
|
uint16_t seq_num;
|
uint8_t msg_type;
|
union
|
{
|
/* responder_num (1B) || [responder_id(2B) || responder_slot_idx(1B)] * RESPONDER_NUM || Tx power level (1B) || user data, poll-msg can be used to
|
* transmit user private data
|
*/
|
uint8_t poll_msg[MSG_POLL_USER_DATA_IDX + MSG_POLL_USER_DATA_LEN];
|
/* responder_id(2B) || Tx power level (1B) || user data, response-msg can be used to transmit user private data */
|
uint8_t response_msg[MSG_RESPONSE_USER_DATA_IDX + MSG_RESPONSE_USER_DATA_LEN];
|
/* responder_num (1B) || Ttotal (tx_final_time - tx_poll_time (5B, 0 ~ 17.2s)) || responder Tround1 (x*5B, x=(0 ~ RESPONDER_NUM-1)) || responder
|
* Fom(1B) + NLoS(1B) [+ fap_valid(1B) + gaps_num(1B) + gaps(CIR_LEN/CE_WIN-1)] (x*RFRAME_INF_SIZE, x=(0 ~ RESPONDER_NUM-1))
|
*/
|
uint8_t final_msg[MSG_FINAL_USER_DATA_IDX + MSG_FINAL_USER_DATA_LEN];
|
|
/* responder_id(2B) || ranging_distance(2B) || poll Fom (1B) + NLoS (1B) || Final Fom (1B) + NLoS (1B) */
|
uint8_t result_msg[MSG_RESULT_INFO_LEN];
|
} msg;
|
} __PACKED;
|
|
struct RANGING_FRAME_INF_T
|
{
|
uint8_t fom;
|
uint8_t NLoS;
|
#if RANGING_FOM_FILTER_EN
|
uint8_t fap_valid;
|
uint8_t gaps_num;
|
uint8_t gaps[CIR_LEN / CE_WIN - 1];
|
#endif
|
} __PACKED;
|
|
/* Custom ranging environment variable */
|
struct RANGING_ENV_T
|
{
|
int64_t tx_poll_time;
|
int64_t tx_response_time;
|
int64_t tx_final_time;
|
int64_t rx_poll_time;
|
int64_t rx_response_time[RESPONDER_NUM];
|
int64_t rx_final_time;
|
|
struct RANGING_FRAME_INF_T frame[MAX(RESPONDER_NUM, 2)];
|
|
uint32_t anchor_point;
|
uint32_t ranging_period;
|
uint32_t slot_interval;
|
uint32_t tof;
|
|
uint8_t lost_cnt;
|
uint8_t enable;
|
uint8_t count;
|
uint8_t responder_num;
|
uint16_t responder_list[RESPONDER_NUM];
|
uint8_t responder_slot_idx;
|
uint8_t responder_response_flag;
|
uint8_t responder_final_flag;
|
uint8_t initiator_result_flag;
|
uint8_t synced;
|
uint8_t slot_idx;
|
uint8_t count_last;
|
uint8_t main_ant_id;
|
|
struct RANGE_DATA_T range_data;
|
};
|
|
/* Main control block of the ranging task */
|
struct RANGING_CB_T
|
{
|
wsfQueue_t msg_queue;
|
wsfHandlerId_t handle_id;
|
wsfTimer_t daemon_timer;
|
};
|
|
#ifdef __cplusplus
|
extern "C" {
|
#endif
|
|
extern struct RANGING_ENV_T ranging_env;
|
|
/**
|
* @brief Initialize ranging task.
|
*
|
* @param [in] handle_id Task handle ID
|
*/
|
int ranging_init(uint8_t handle_id);
|
|
/**
|
* @brief De-initialize ranging task.
|
*/
|
int ranging_deinit(void);
|
|
/**
|
* @brief Configure ranging environment variable, configure UWB subsystem.
|
*/
|
void ranging_configure(void);
|
|
/**
|
* @brief Start ranging procedure.
|
*/
|
void ranging_start(void);
|
|
/**
|
* @brief Stop ranging procedure.
|
*/
|
void ranging_stop(void);
|
|
/**
|
* @brief Restart ranging procedure.
|
* @note This function can be called once detected link loss from peer device
|
*/
|
void ranging_restart(void);
|
|
/**
|
* @brief Get ranging UWB TX power.
|
* @return ranging UWB TX power in dBm
|
*/
|
int8_t ranging_tx_power_get(void);
|
|
/**
|
* @brief Get ranging count for link loss detection.
|
* @return ranging count
|
*/
|
uint8_t ranging_count_get(void);
|
|
/**
|
* @brief Set local device short address.
|
* @param[in] short_addr Device short address
|
*/
|
void ranging_local_addr_set(uint16_t short_addr);
|
|
/**
|
* @brief Set peer device short address.
|
* @param[in] short_addr Device short address
|
*/
|
void ranging_peer_addr_set(uint16_t short_addr);
|
|
/**
|
* @brief Add responder device into responder device list for one-to-many case.
|
* @param[in] addr Device short address
|
* @return 1: successful, 0: fail
|
*/
|
uint8_t ranging_responder_addr_add(uint16_t addr);
|
|
/**
|
* @brief Set responder device into responder device list.
|
* @param[in] idx Responder device index
|
* @param[in] addr Device short address
|
* @return 1: successful, 0: fail
|
*/
|
uint8_t ranging_responder_addr_set(uint8_t idx, uint16_t addr);
|
|
/**
|
* @brief Clear responder list.
|
*/
|
void ranging_responder_list_clr(void);
|
|
/**
|
* @brief Get responder short address from responder device list.
|
* @param[in] idx Responder device index
|
* @return short address of responder
|
*/
|
uint16_t ranging_responder_addr_get(uint8_t idx);
|
|
/**
|
* @brief Get responder index by device address.
|
* @param[in] addr Responder device address
|
* @return 0xFF if the device not found else return responder index
|
*/
|
uint8_t ranging_responder_idx_get(uint16_t addr);
|
|
/**
|
* @brief Get responder devices number.
|
* @return number of responder
|
*/
|
uint8_t ranging_responder_num_get(void);
|
|
/**
|
* @brief Set user data for poll packet.
|
* @param[in] data_len User data length
|
* @param[in] data Pointer of user data
|
* @return 0: successful, 1: fail
|
*/
|
uint8_t ranging_poll_msg_set(uint16_t data_len, const uint8_t *data);
|
|
/**
|
* @brief Set user data for response packet.
|
* @param[in] data_len User data length
|
* @param[in] data Pointer of user data
|
* @return 0: successful, 1: fail
|
*/
|
uint8_t ranging_response_msg_set(uint16_t data_len, const uint8_t *data);
|
|
/**
|
* @brief Calculate timestamp difference.
|
* @param[in] ts_a Ranging timestamp a
|
* @param[in] ts_b Ranging timestamp b
|
* @return ts_a - ts_b
|
*/
|
int64_t ranging_timestamp_diff(int64_t ts_a, int64_t ts_b);
|
|
/**
|
* @brief Calculate ranging Tround.
|
* @param[in] role Device role @enum DEV_ROLE_T
|
* @param[in] dev_idx Device index in one-to-many case
|
* @return Tround value, unit: 15.6ps
|
*/
|
int64_t ranging_tround(enum DEV_ROLE_T role, uint8_t dev_idx);
|
|
/**
|
* @brief Calculate ranging Treply.
|
* @param[in] role Device role @enum DEV_ROLE_T
|
* @param[in] dev_idx Device index in one-to-many case
|
* @return Treply value, unit: 15.6ps
|
*/
|
int64_t ranging_treply(enum DEV_ROLE_T role, uint8_t dev_idx);
|
|
/**
|
* @brief Construct ranging poll packet.
|
*/
|
void ranging_poll_pkt_construct(void);
|
|
/**
|
* @brief Construct ranging response packet.
|
*/
|
void ranging_response_pkt_construct(void);
|
|
/**
|
* @brief Construct ranging final packet.
|
*/
|
void ranging_final_pkt_construct(void);
|
|
/**
|
* @brief Construct ranging result packet.
|
*/
|
void ranging_result_pkt_construct(void);
|
|
/**
|
* @brief Process ranging poll packet.
|
* @param[in] pkt_data Pointer of poll packet data
|
* @param[in] pkt_len Poll packet length
|
* @return 1: poll packet parse successful
|
*/
|
uint8_t ranging_poll_pkt_process(uint8_t *pkt_data, uint16_t pkt_len);
|
|
/**
|
* @brief Ranging FSM, to process MAC TX or RX done event in MAC interrupt handler.
|
* @param[in] ind Pointer of MAC HW report
|
* @return next ranging stage
|
*/
|
enum RANGING_STAGE_T ranging_fsm(const struct MAC_HW_REPORT_T *ind);
|
|
#ifdef __cplusplus
|
}
|
#endif
|
|
#endif /* RANGING_H_ */
|
