cs.h

Go to the documentation of this file.

/******************************************************************************

 @file  cs.h

 @brief This file contains the structures used by Channel Sounding.

 Group: WCS, BTS
 $Target Device: DEVICES $

 ******************************************************************************
 $License: TI_TEXT 2025 $
 ******************************************************************************
 $Release Name: PACKAGE NAME $
 $Release Date: PACKAGE RELEASE DATE $
 *****************************************************************************/
#ifndef CS_H
#define CS_H
/*******************************************************************************
 * INCLUDES
 */
#include "ti/ble/stack_util/cs_types.h"

/*******************************************************************************
 * MACROS
 */
#define STEP_HDR_LEN    3U  

/*******************************************************************************
 * TYPEDEFS
 */
typedef enum
{
  CS_READ_REMOTE_SUPPORTED_CAPABILITIES_COMPLETE_EVENT ,  
  CS_READ_REMOTE_FAE_TABLE_COMPLETE_EVENT              ,  
  CS_SECURITY_ENABLE_COMPLETE_EVENT                    ,  
  CS_CONFIG_COMPLETE_EVENT                             ,  
  CS_PROCEDURE_ENABLE_COMPLETE_EVENT                   ,  
  CS_SUBEVENT_RESULT                                   ,  
  CS_SUBEVENT_CONTINUE_RESULT                          ,  
} csEventOpcodes_e;

typedef struct
{
  uint8_t opcode;     // CS Event Opcode @ref csEventOpcodes_e
} csEvtHdr_t;

/*
* @brief Host CS Callback
*
* @param pEvt - the CS event struct
*
* @return None
*/
typedef void(*pfnCsCB_t)(void *pEvt);

typedef struct
{
  pfnCsCB_t pfnCsEvtCB;    
} csCBs_t;

typedef struct
{
  csEventOpcodes_e csEvtOpcode;      
  uint16_t   connHandle;             
  uint8_t    csStatus;               
  uint8_t    numConfig;              
  uint16_t   maxProcedures;          
  uint8_t    numAntennas;            
  uint8_t    maxAntPath;             
  uint8_t    role;                   
  uint8_t    optionalModes;          
  uint8_t    rttCap;                 
  uint8_t    rttAAOnlyN;             
  uint8_t    rttSoundingN;           
  uint8_t    rttRandomPayloadN;      
  uint16_t   nadmSounding;           
  uint16_t   nadmRandomSeq;          
  uint8_t    optionalCsSyncPhy;      
  uint8_t    noFAE;                  
  uint8_t    chSel3c;                
  uint8_t    csBasedRanging;         
  uint16_t   tIp1Cap;                
  uint16_t   tIp2Cap;                
  uint16_t   tFcsCap;                
  uint16_t   tPmCsap;                
  uint8_t    tSwCap;                 
  uint8_t    snrTxCap;               
} CS_readRemoteCapabEvt_t;

typedef struct
{
  csEventOpcodes_e csEvtOpcode;        
  uint16_t         connHandle;         
  uint8_t          csStatus;           
  uint8_t          configId;           
  uint8_t          state;              
  uint8_t          mainMode;           
  uint8_t          subMode;            
  uint8_t          mainModeMinSteps;   
  uint8_t          mainModeMaxSteps;   
  uint8_t          mainModeRepetition; 
  uint8_t          modeZeroSteps;      
  uint8_t          role;               
  uint8_t          rttType;            
  uint8_t          csSyncPhy;          
  csChm_t          channelMap;         
  uint8_t          chMRepetition;      
  uint8_t          chSel;              
  uint8_t          ch3cShape;          
  uint8_t          ch3CJump;           
  uint8_t          rfu0;               
  uint8_t          tIP1;               
  uint8_t          tIP2;               
  uint8_t          tFCs;               
  uint8_t          tPM;                
  uint8_t          rfu1;               
} CS_configCompleteEvt_t;

typedef struct
{
  csEventOpcodes_e    csEvtOpcode;             
  uint16_t            connHandle;              
  uint8_t             csStatus;                
  csFaeTbl_t          faeTable;                
} CS_readRemFAECompleteEvt_t;

typedef struct
{
  csEventOpcodes_e    csEvtOpcode;            
  uint16_t            connHandle;             
  uint8_t             csStatus;               
} CS_securityEnableCompleteEvt_t;

typedef struct
{
  csEventOpcodes_e csEvtOpcode;        
  uint8_t          csStatus;           
  uint16_t         connHandle;         
  uint8_t          configId;           
  uint8_t          enable;             
  csACI_e          ACI;                
  uint8_t          pwrDelta;           
  uint32_t         subEventLen;        
  uint8_t          subEventsPerEvent;  
  uint16_t         subEventInterval;   
  uint16_t         eventInterval;      
  uint16_t         procedureInterval;  
  uint16_t         procedureCount;     
} CS_procEnableCompleteEvt_t;

typedef struct
{
  csEventOpcodes_e csEvtOpcode;                  
  uint16_t         connHandle;                   
  uint8_t          configID;                     
  uint16_t         startAclConnectionEvent;      
  uint16_t         procedureCounter;             
  int16_t          frequencyCompensation;        
  int8_t           referencePowerLevel;          
  uint8_t          procedureDoneStatus;          
  uint8_t          subeventDoneStatus;           
  uint8_t          abortReason;                  
  uint8_t          numAntennaPath;               
  uint8_t          numStepsReported;             
  uint16_t         dataLen;                      
  uint8_t          data[];                       
} CS_subeventResultsEvt_t;

typedef struct
{
  csEventOpcodes_e csEvtOpcode;         
  uint16_t         connHandle;          
  uint8_t          configID;            
  uint8_t          procedureDoneStatus; 
  uint8_t          subeventDoneStatus;  
  uint8_t          abortReason;         
  uint8_t          numAntennaPath;      
  uint8_t          numStepsReported;    
  uint16_t         dataLen;             
  uint8_t          data[];              
} CS_subeventResultsContinueEvt_t;

/*
 * Command Parameters Structures
 */
typedef struct
{
  uint16_t     connHandle;
} CS_readRemoteCapCmdParams_t;

typedef struct
{
  uint16_t    connHandle;              
  uint8_t     configID;                
  uint8_t     createContext;           
  uint8_t     mainMode;                
  uint8_t     subMode;                 
  uint8_t     mainModeMinSteps;        
  uint8_t     mainModeMaxSteps;        
  uint8_t     mainModeRepetition;      
  uint8_t     modeZeroSteps;           
  uint8_t     role;                    
  uint8_t     rttType;                 
  uint8_t     csSyncPhy;               
  csChm_t     channelMap;              
  uint8_t     chMRepetition;           
  uint8_t     chSel;                   
  uint8_t     ch3cShape;               
  uint8_t     ch3CJump;                
} CS_createConfigCmdParams_t;

typedef struct
{
  uint16_t connHandle;             
} CS_securityEnableCmdParams_t;

typedef struct
{
  uint16_t connHandle;              
  uint8_t  roleEnable;              
  uint8_t  csSyncAntennaSelection;  
  int8_t   maxTxPower;              
} CS_setDefaultSettingsCmdParams_t;

typedef struct
{
  uint16_t connHandle;             
} CS_readRemoteFAETableCmdParams_t;

typedef struct
{
  uint16_t    connHandle;          
  csFaeTbl_t  reflectorFaeTable;   
} CS_writeRemoteFAETableCmdParams_t;

typedef struct
{
  uint16_t connHandle;           
  uint8_t  configID;             
} CS_removeConfigCmdParams_t;

typedef struct
{
  csChm_t channelClassification; 
} CS_setChannelClassificationCmdParams_t;

typedef struct
{
  uint16_t   connHandle;           
  uint8_t    configID;             
  uint16_t   maxProcedureDur;      
  uint16_t   minProcedureInterval; 
  uint16_t   maxProcedureInterval; 
  uint16_t   maxProcedureCount;    
  uint32_t   minSubEventLen;       
  uint32_t   maxSubEventLen;       
  csACI_e    aci;                  
  uint8_t    phy;                  
  uint8_t    txPwrDelta;           
  uint8_t    preferredPeerAntenna; 
  uint8_t    snrCtrlI;             
  uint8_t    snrCtrlR;             
  uint8_t    enable;               
} CS_setProcedureParamsCmdParams_t;

typedef struct
{
  uint16_t connHandle;  
  uint8_t  configID;    
  uint8_t  enable;      
} CS_setProcedureEnableCmdParams_t;

typedef struct
{
  uint8_t defaultAntennaIndex;    
} CS_setDefaultAntennaCmdParams_t;

typedef struct
{
  uint16_t connHandle;  
  uint8_t  configID;    
  uint8_t* role;        
} CS_GetRoleCmdParams_t;

/*
 * The following structures are meant to help parsing the data from the subevent results
 */

typedef struct
{
    uint8_t stepMode;            
    uint8_t stepChnl;            
    uint8_t stepDataLen;         

    /* Step data is one of these types:
     * @ref CS_modeZeroInitStep_t
     * @ref CS_modeZeroReflStep_t
     * @ref CS_modeOneStep_t
     * @ref CS_modeTwoStep_t
     * @ref CS_modeThreeStep_t
     */
    uint8_t stepData;
} csSubeventResultsStep_t;

PACKED_TYPEDEF_STRUCT
{
  uint8_t  packetQuality;         
  uint8_t  packetRssi;            
  uint8_t  packetAntenna;         
  uint16_t measuredFreqOffset;    
} CS_modeZeroInitStep_t;

PACKED_TYPEDEF_STRUCT
{
  uint8_t packetQuality;        
  uint8_t packetRssi;           
  uint8_t packetAntenna;        
} CS_modeZeroReflStep_t;

PACKED_TYPEDEF_STRUCT
{
  uint8_t  packetQuality;       
  uint8_t  packetNadm;          
  uint8_t  packetRssi;          
  uint16_t ToDToA;              
  uint8_t  packetAntenna;       
} CS_modeOneStep_t;

PACKED_TYPEDEF_STRUCT
{
  uint32_t i:12;              
  uint32_t q:12;              
  uint32_t tqi:8;             
} modeTwoStepData_t;

PACKED_TYPEDEF_STRUCT
{
  uint8_t antennaPermutationIndex; 
  modeTwoStepData_t data[];        
} CS_modeTwoStep_t;

PACKED_TYPEDEF_STRUCT
{
  uint8_t  packetQuality;           
  uint8_t  packetNadm;              
  uint8_t  packetRssi;              
  uint16_t ToDToA;                  
  uint8_t  packetAntenna;           
  uint8_t  antennaPermutationIndex; 
  modeTwoStepData_t data[];         
} CS_modeThreeStep_t;

/*******************************************************************************
 * API FUNCTIONS
 */

csStatus_e CS_ReadLocalSupportedCapabilities(csCapabilities_t *localCapab);

csStatus_e CS_ReadRemoteSupportedCapabilities(CS_readRemoteCapCmdParams_t *params);

csStatus_e CS_SecurityEnable(CS_securityEnableCmdParams_t *params);

csStatus_e CS_SetDefaultSettings(CS_setDefaultSettingsCmdParams_t *params);

csStatus_e CS_ReadRemoteFAETable(CS_readRemoteFAETableCmdParams_t *params);

csStatus_e CS_WriteRemoteFAETable(CS_writeRemoteFAETableCmdParams_t *params);

csStatus_e CS_CreateConfig(CS_createConfigCmdParams_t *params);

csStatus_e CS_RemoveConfig(CS_removeConfigCmdParams_t *params);

csStatus_e CS_SetChannelClassification(CS_setChannelClassificationCmdParams_t *params);

csStatus_e CS_SetProcedureParameters(CS_setProcedureParamsCmdParams_t *params);

csStatus_e CS_ProcedureEnable(CS_setProcedureEnableCmdParams_t *params);

csStatus_e CS_SetDefaultAntenna(CS_setDefaultAntennaCmdParams_t *pParams);

csStatus_e CS_GetRole(CS_GetRoleCmdParams_t *pParams);

/*******************************************************************************
 * @fn          CS_GetStepLength
 *
 * @brief       This function calculates the length of a step data, depends on
 *              role, mode, and number of antenna paths.
 *
 * @param       mode - Step mode. Should be one of:
 *                     @ref CS_MODE_0
 *                     @ref CS_MODE_1
 *                     @ref CS_MODE_2
 *                     @ref CS_MODE_3
 *
 * @param       role - Role of the device measured the step of types:
 *                     @ref CS_ROLE_INITIATOR or @ref CS_ROLE_REFLECTOR
 *
 * @param       numAntennaPath - Number of antenna paths used in the step
 *
 * @return      Length of the relevant step data
 * @return      0 for one of the following cases:
 *              - Invalid mode has been given.
 *              - mode is 0 and role is invalid.
 */
uint8_t CS_GetStepLength(uint8_t mode, uint8_t role, uint8_t numAntennaPath);

/*******************************************************************************
 * @fn          CS_calcNumPaths
 *
 * @brief       This function returns number of antenna paths based on a given
 *              ACI (antenna permutation index).
 *
 * @param       aci - antenna permutation index
 *
 * @return      Number of antenna paths: 1 - 4
 * @return      0 If the given parameter is invalid
 */
uint8_t CS_calcNumPaths(csACI_e aci);

/*******************************************************************************
 * @fn          CS_calcNumPathsFromAntennaMask
 *
 * @brief       This function returns number of antenna paths based on a given
 *              antenna paths mask.
 *
 * @param       antPathMask - first 4 bits, each one represent an antenna path.
 *                            Lsb bit represent the first antenna path.
 *                            Valid values: 0x1, 0x3, 0x7, 0xF
 *
 * @return      Number of antenna paths: 1 - 4
 * @return      0 If the given parameter is invalid
 */
uint8_t CS_calcNumPathsFromAntennaMask(uint8_t antPathMask);

/*******************************************************************************
 * @fn          CS_calcAntPathsMask
 *
 * @brief       This function returns the antenna paths mask based on a given
 *              ACI (antenna permutation index).
 *
 * @param       aci - antenna permutation index
 *
 * @return      Antenna paths mask
 */
uint8_t CS_calcAntPathsMask(csACI_e aci);

uint8_t CS_RegisterCB(const csCBs_t *pCBs);

extern void CS_ProcessEvent(csEvtHdr_t *pData);

#endif // CS_H