Xiaojie雷达之路---mmWave API详解

日期： 2020-11-22 分类：跨站数据测试 551次阅读

mmWave API是运行在mmWaveLink和LLD API(驱动程序API)之上的更高层控件。它被设计为以更简单和更少的API集合的形式提供一个抽象层，供应用程序执行mmWave雷达探测任务。在具有双核的mmWave设备中，它还通过IPC提供了一个抽象层来同步和传递MSS和DSS域之间的配置。

文章目录

init
sync
open
config
start
stop
execute

init

函数原型：

MMWave_Handle MMWave_init(
	MMWave_InitCfg * ptrCtrlInitCfg,
	int32_t * errCode 
	)

这个函数是用来初始化mmWave控制模块，在其他的控制API调用之前，这个API一定要被调用。

函数参数：
第一个参数是输入变量，第二个参数是输出变量，第二个参数用于调用这个API产生的错误代码。
接下来看第一个参数，它是MMWave_InitCfg类型的指针，追根溯源，会找到是下面一个类型的结构体

typedef struct MMWave_InitCfg_t
{
    /**
     * @brief   Execution domain on which the mmWave module is executing.
     */
    MMWave_Domain               domain;

    /**
     * @brief   Handle to the SOC Driver
     */
    SOC_Handle                  socHandle;

    /**
     * @brief   Application supplied asynchronous event handler. This is invoked
     * on the reception of an asynchronous event from the BSS
     */
    MMWave_eventFxn             eventFxn;

    /**
     * @brief   mmWave link messages exchanged with the BSS have a checksum. The
     * configuration specifies if the CRC hardware *or* software to be used for
     * checksum calculation and validation.
     */
    MMWave_LinkCRCCfg           linkCRCCfg;

    /**
     * @brief   Configuration Mode: Full or Minimal
     */
    MMWave_ConfigurationMode    cfgMode;

#if (defined(SOC_XWR16XX) || defined(SOC_XWR18XX) || defined(SOC_XWR68XX))
    /**
     * @brief   The execution mode of the mmWave module. On the XWR16xx/XWR18xx/XWR68xx the mmWave module
     * could execute in either of the following modes:-
     *  (a) [Isolation Mode]: Only on the DSS
     *  (b) [Isolation Mode]: Only on the MSS
     *  (c) [Cooperative Mode]: Control Path on DSS and Data Path on MSS
     *  (d) [Cooperative Mode]: Control Path on MSS and Data Path on DSS
     */
    MMWave_ExecutionMode        executionMode;

    /**
     * @brief   In cooperative mode: The mmWave module is executing on both the DSS
     * and MSS. The module is responsible for passing the configuration and async
     * events between the domains.
     */
    MMWave_CooperativeModeCfg   cooperativeModeCfg;
#endif
}MMWave_InitCfg;

下面来解释下这一个结构体：

domain：这个变量是说明mmWave模块的执行域是哪一个，这个是一个枚举类型的变量，它里面的值只有两个：MMWave_Domain_MSS和MMWave_Domain_DSS，指明了mWave模块是在MSS上执行还是在DSS上执行。
socHandle：这个变量是指向的是调用SOC_init()对SOC进行初始化后返回的SOC_Handle句柄。
eventFxn：这个变量是指应用程序提供的异步处理事件。在接收到来自BSS的异步事件后被调用。它是一个指针变量，由应用程序进行事件的注册，只有下面的函数类型才能对它进行赋值：int32_t MmwDemo_eventCallbackFxn(uint16_t msgId, uint16_t sbId, uint16_t sbLen, uint8_t *payload)
linkCRCCfg：与MSS交互的mmWave link消息有一个校验和。这个配置指定用CRC硬件还是软件来进行校验和的计算和验证。

cfgMode：这个变量是指对mmWave控制模块的配置模式，这个配置模式有两种，一种是Full，另一种是Minimal。这个变量的类型是枚举，里面分别是MMWave_ConfigurationMode_MINIMAL和MMWave_ConfigurationMode_FULL，下面分别对这两种模式进行介绍：

 MMWave_ConfigurationMode_MINIMAL 
 	在这种模式下，mmWave负责下列的任务：
 		1. 设置到BSS的mmWave Link传输
 		2. 如果设备支持的话，与BSS和DSS的启动/停止/同步功能
 		3. 如果设备支持的话，对对等域进行BSS的异步事件的通知
 		4. mmWave Link初始化
 		5. 没有动态内存的分配
 	应用程序要负责下列的任务：
 		1. 使用mmWave Link对BSS进行配置
 		2. 对Profile/Chirp和Frame进行配置管理
 		3. 如果设备支持的话，发送消息到对等域
 	这种模式适用于开发者用户
 MMWave_ConfigurationMode_FULL
 	在这种模式下，mmWave负责下列的任务：
 		1. 设置到BSS的mmWave Link传输
 		2. 如果设备支持的话，与BSS和DSS的启动/停止/同步功能
 		3. 如果设备支持的话，对对等域进行BSS的异步事件的通知
 		4. mmWave Link初始化
 		5. 使用mmWave Link对BSS进行配置
 		6. 对Profile/Chirp和Frame进行配置管理
 		7. 如果设备支持的话，发送消息到对等域
 		8. 有动态内存的分配
 	应用程序负责的任务就是跟踪mmWave句柄。
 	这种模式适用于基本用户

executionMode：mmWave module的执行模式，这个变量只在XWR16xx/XWR18xx/XWR68xx这几个设备上执行，可以有下列两种模式：

 1. MMWave_ExecutionMode_ISOLATION模式：
  	在这种模式下，mmWave仅仅可以执行在DSS或者MSS上
 2. MMWave_ExecutionMode_COOPERATIVE模式：
 	在这种模式下，mmWave在DSS和MSS上都执行，MMwave的配置和事件被共享在mmWave执行域中，有两种方式：Control Path on DSS and Data Path on MSS
 		1. 控制路径在DSS上，数据路径在MSS上
 		2. 数据路径在MSS上，控制路径在DSS上
 	在这种模式下需要注意的是，MSS和DSS之间的通信使用的是Mailbox驱动的虚拟通道7。要保证这个虚拟通道不能用来做其他事情。

cooperativeModeCfg：这个变量是在上一个变量设置了MMWave_ExecutionMode_COOPERATIVE这种模式的情况下，这个变量才会生效，如果设置了MMWave_ExecutionMode_ISOLATION这种模式的情况下，这个变量可以忽略，这个变量的作用就是负责在域之间传递配置和异步事件，这个变量类型是一个结构体，里面的变量都是函数指针，如下：
```
typedef struct MMWave_CooperativeModeCfg_t
{
    MMWave_cfgFxn       cfgFxn;

    MMWave_openFxn      openFxn;

    MMWave_closeFxn     closeFxn;

    MMWave_startFxn     startFxn;

    MMWave_stopFxn      stopFxn;

}MMWave_CooperativeModeCfg;
```

函数返回值：当函数调用成功后，返回值为控制模块的句柄，当函数调用错误后，返回值为NULL。

sync

函数原型：

int32_t MMWave_sync(
	MMWave_Handle mmWaveHandle,
	int32_t * errCode 
)

这个函数用于在执行域之间同步执行模块，应用程序应该一直调用它，直到实现“同步”。失败的话，会导致mmWave模块的错误行为。

函数参数：
第一个函数参数是输入参数，是mmWave控制模块的句柄，值是调用mmWave_init()之后返回的mmWave模块控制句柄，第二个参数是输出参数，是执行调用这个API执行错误后产生的错误代码。

函数返回值：
当同步成功后返回值为1，当同步失败后返回值为0，当发生错误后返回值为小于0

open

函数原型：

int32_t MMWave_open(
	MMWave_Handle mmWaveHandle,
	const MMWave_OpenCfg * ptrOpenCfg,
	MMWave_CalibrationData * ptrCalibrationData,
	int32_t * errCode 
)

这个函数是用来打开mmWave模块。

函数参数：
第一个输入参数是mmWave模块的句柄，第二个输入参数是打开配置的指针，第三个输入参数是指向校准数据的指针，需要将其传递给RadarSS，以绕过校准并将其恢复到先前保存的值。将其设置为空，mmWave模块将请求RadarSS执行校准，第四个输出参数是执行调用这个API执行错误后产生的错误代码

下面看第二个参数，结构体如下：

ypedef struct MMWave_OpenCfg_t
{
    /**
     * @brief   Low Frequency Limit for calibrations:
     */
    uint16_t                    freqLimitLow;

    /**
     * @brief   High Frequency Limit for calibrations
     */
    uint16_t                    freqLimitHigh;

    /**
     * @brief   Configuration which is used to setup channel
     */
    rlChanCfg_t                 chCfg;

    /**
     * @brief   Low power mode configuration
     */
    rlLowPowerModeCfg_t         lowPowerMode;

    /**
     * @brief   Configuration which is used to setup ADC
     */
    rlAdcOutCfg_t               adcOutCfg;

#if (defined(SOC_XWR16XX) || defined(SOC_XWR18XX) || defined(SOC_XWR68XX))
    /**
     * @brief   Designate the default asynchronous event handler. By default
     * the BSS assumes that the default asynchronous event handler is the MSS. \n
     * Field Not valid for xwr14xx.
     */
    MMWave_DefaultAsyncEventHandler     defaultAsyncEventHandler;
#endif

    /**
     * @brief   Flag that determines if frame start async event is disabled.
     * For more information refer to the mmWave Link documentation for:-
     * - RL_RF_AE_FRAME_TRIGGER_RDY_SB
     * - rlSensorStart
     */
    bool                disableFrameStartAsyncEvent;

    /**
     * @brief   Flag that determines if frame stop async event is disabled.
     * For more information refer to the mmWave Link documentation for:-
     * - RL_RF_AE_FRAME_END_SB
     * - rlSensorStop
     */
    bool                disableFrameStopAsyncEvent;

    /**
     * @brief   Set the flag to enable the application to specify the calibration
     * mask which is to be used. If the flag is set to false the MMWave module will
     * default and enable all the calibrations.
     */
    bool                useCustomCalibration;

    /**
     * @brief   This is the custom calibration enable mask which is to be used and
     * is applicable only if the application has enabled "Custom Calibration"
     */
    uint32_t            customCalibrationEnableMask;

    /**
     * @brief   Calibration Monitor time unit configuration in units of frame.
     *          Value of 1 here means Calibration Monitor time unit = 1 frame duration.
     *          See rlRfCalMonTimeUntConf_t for details on this configuration.
     */
    rlUInt16_t                  calibMonTimeUnit;
}MMWave_OpenCfg;

下面来解释一下这个结构体：

freqLimitLow：这个变量是说明对于校准频率的下限
freqLimitHigh：这个变量是说明对于校准频率的上限
chCfg：这个变量用来配置接收发射天线的通道，以及是否级联
lowPowerMode：设置是否是低功耗模式的配置，0是正常功耗，1是低功耗
adcOutCfg：设置ADC数据输出的格式，可以设置adc数据的位数(12、14、16)，设置ADC输出数据的格式，可选的变量有：Real、Complex、Complex with Image band、Pseudo Real，
defaultAsyncEventHandler：指定默认的异步事件的处理程序，在默认情况下，BSS假定默认异步事件处理程序是MSS
disableFrameStartAsyncEvent：确定是否禁用帧启动异步事件的标志
disableFrameStopAsyncEvent：确定是否禁用帧停止异步事件的标志
useCustomCalibration：设置标志以使应用程序能够指定要使用的校准码，如果标志位设置为false，MMwave模块将默认并使能全部的校准。
customCalibrationEnableMask：这是要使用的自定义校准启用掩码，并且只有应用程序已启用"useCustomCalibration"时才适用
calibMonTimeUnit：以帧为单位的校准监视器时间单位配置。这里的值1表示校准监视器时间单位=1帧持续时间

接下来，看第三个参数，结构体如下：

typedef struct MMWave_CalibrationData_t
{
    /**
     * @brief   Calibration data as received from RadarSS via rlRfCalibDataStore API
     */
    rlCalibrationData_t*            ptrCalibData;

#if (defined(SOC_XWR18XX) || defined(SOC_XWR68XX))
    /**
     * @brief   xwr18xx/xwr6xxx: Phase shifter calibration data as received from 
     *          RadarSS via rlRfPhShiftCalibDataStore API
     */
    rlPhShiftCalibrationData_t*     ptrPhaseShiftCalibData;
#endif
} MMWave_CalibrationData;

下面解释一下这个结构体：

ptrCalibData：通过rlRfCalibDataStore API从Radar SS接收到校准数据
ptrPhaseShiftCalibData：这个变量当设备是xwr1843或者是xwr6843的时候才被使用，通过rlRfPhShiftCalibDataStore API从Radar SS接收的移相器的校准数据

函数返回值：当函数执行成功时，返回值为0，当函数执行失败后，返回值小于0

config

函数原型：

int32_t MMWave_config(	
	MMWave_Handle mmWaveHandle,
	MMWave_CtrlCfg * ptrControlCfg,
	int32_t * errCode 
	)

这个函数是用于配置mmWave的导出API，这仅适用于完全配置模式

函数参数：
第一个输入参数是mmWave模块的句柄，第二个输入参数是控制配置的指针(配置和设置BSS所需的配置)，第三个输出参数是执行调用这个API执行错误后产生的错误代码

下面将介绍第二个参数，结构体如下：

typedef struct MMWave_CtrlCfg_t
{
    /**
     * @brief   DFE Data Output Mode:
     */
    MMWave_DFEDataOutputMode        dfeDataOutputMode;

    union
    {
        /**
         * @brief   Chirp configuration to be used: This is only applicable
         * if the data output mode is set to Chirp
         */
        MMWave_FrameCfg         frameCfg;

        /**
         * @brief   Continuous configuration to be used: This is only applicable
         * if the data output mode is set to Continuous
         */
        MMWave_ContModeCfg          continuousModeCfg;

        /**
         * @brief   Advanced Frame configuration: This is only applicable
         * if the data output mode is set to Advanced Frame
         */
        MMWave_AdvancedFrameCfg     advancedFrameCfg;
    }u;
}MMWave_CtrlCfg;

下面解释一下这个结构体：

dfeDataOutputMode：这个变量可以被设置为三种类型：MMWave_DFEDataOutputMode_FRAME 、MMWave_DFEDataOutputMode_CONTINUOUS 、MMWave_DFEDataOutputMode_ADVANCED_FRAME，设置为不同的类型后，DFE被操作在不同的模式下，分别为：Frame mode、continuous mode、advanced frame mode
u是一个共用体，共用体的概念就是每次只可以使用其中的一个类型变量，共用体中的变量共享同一块内存，dfeDataOutputMode的三种类型分别对应着三个变量。

函数返回值：当函数执行成功时，返回值为0，当函数执行失败后，返回值小于0

start

函数原型：

int32_t MMWave_start(	
	MMWave_Handle mmWaveHandle,
	const MMWave_CalibrationCfg * ptrCalibrationCfg,
	int32_t * errCode 
	)

这个函数用于在配置被应用后打开mmWave控制模块。

函数参数：
第一个输入参数是mmWave模块的句柄，第二个输入参数是校准配置的指针(保存设置射频校准所需的信息)，第三个输出参数是执行调用这个API执行错误后产生的错误代码

下面将介绍第二个参数，结构体如下：

typedef struct MMWave_CalibrationCfg_t
{
    /**
     * @brief   DFE Data Output Mode: Chirp or Continuous
     *
     * NOTE: Please ensure that the DFE Data output mode passed during
     * control configuration and calibration configuration should be
     * the same. Failure to do so will result in unpredictable behavior
     */
    MMWave_DFEDataOutputMode        dfeDataOutputMode;

    union
    {
        /**
         * @brief   This should be configured if the DFE Data output mode
         * is configured to operate in frame or advanced frame mode
         */
        MMWave_ChirpCalibrationCfg  chirpCalibrationCfg;

        /**
         * @brief   This should be configured if the DFE Data output mode
         * is configured to operate in continuous mode
         */
        MMWave_ContCalibrationCfg   contCalibrationCfg;
    }u;
}MMWave_CalibrationCfg;

dfeDataOutputMode：这个变量可以被设置为三种类型：MMWave_DFEDataOutputMode_FRAME 、MMWave_DFEDataOutputMode_CONTINUOUS 、MMWave_DFEDataOutputMode_ADVANCED_FRAME，设置为不同的类型后，DFE被操作在不同的模式下，分别为：Frame mode、continuous mode、advanced frame mode
u是一个共用体，在这个共用体里面有两个变量，当DFE数据输出模式被设置为MMWave_DFEDataOutputMode_FRAME 或者是MMWave_DFEDataOutputMode_ADVANCED_FRAME时，chirpCalibrationCfg变量将被进行配置，当DFE数据输出模式被设置为MMWave_DFEDataOutputMode_CONTINUOUS 时，contCalibrationCfg变量将被进行配置。

函数返回值：当函数执行成功时，返回值为0，当函数执行失败后，返回值小于0

stop

函数原型：

int32_t MMWave_stop(	
	MMWave_Handle 	mmWaveHandle,
	int32_t * 	errCode 
	)

这个函数用于停止mmWave控制模块。

函数参数：
第一个输入参数是mmWave模块的句柄，第二个输出参数是执行调用这个API执行错误后产生的错误代码

函数返回值：当函数执行成功时，返回值为0，当函数执行失败后，返回值小于0

execute

函数原型：

int32_t MMWave_execute(	
	MMWave_Handle 	mmWaveHandle,
	int32_t * 	errCode 
)

函数描述：
该函数用于执行mmWave控制模块，它只应在执行任务的上下文中调用函数块和处理mmWave link消息

函数参数：
第一个输入参数是mmWave模块的句柄，第二个输出参数是执行调用这个API执行错误后产生的错误代码

函数返回值：当函数执行成功时，返回值为0，当函数执行失败后，返回值小于0

参考文献：

《mmWave SDK Module Documentation》

除特别声明，本站所有文章均为原创，如需转载请以超级链接形式注明出处：SmartCat's Blog

标签：# TI实战笔记 # TI学习笔记 mmWave API AWR1843 BSS MSS MMWave_start

上一篇： SRS、EasyDarwin、ZLMediaKit、Monibuca对比分析

下一篇：绘制stm23最小系统PCB图

Young87

So happy to code my life!

Xiaojie雷达之路---mmWave API详解

文章目录

init

sync

open

config

start

stop

execute