xensiv_radar_presence.h

/*******************************************************************************
* \file xensiv_radar_presence.h
*
* \brief
* Provides API declarations for the XENSIV(TM) RADAR presence detection library.
*
********************************************************************************
* \copyright
* (c) 2022 Infineon Technologies AG.
*
* SPDX-License-Identifier: Apache-2.0
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
*     http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*******************************************************************************/

/**
 * \addtogroup group_board_libs XENSIV(TM) Radar Presence
 * \{
 * This library provides an interface for human presence detection using radar.
 * There are a number of reasons behind the use of radar in the this application:
 *  - It can operate at any time of the day in all weather conditions.
 *  - It can have a broad coverage and can even penetrate through walls.
 *  - Furthermore, it can detect and track moving targets and can operate unmanned.
 *
 * \section subsection_xensiv_radar_presence_radar_system Radar System
 *
 * A typical radar system consists of the following components: \n
 * - A transmitter
 * - A receiver
 * - RF Generator
 * - Amplifiers
 * - Mixer
 * - Analog to Digital Converter
 *
 * This is represented by the following figure:
 *
 * \image html typical_radar_system.png "Radar system block diagram" width=600px
 * \image latex typical_radar_system.png
 *
 * An electromagnetic wave generated by the RF generator is amplified and then transmitted through
 * the transmitter. The wave travels at a constant speed, approximately at the speed of light and
 * gets reflected once it strikes a target. The reflected signal is collected by the receiver,
 * amplified and fed to a mixer where it gets mixed with the transmitted signal. The resulting
 * signal from the mixer is called as IF (Intermediate frequency) signal, whose instantaneous
 * frequency is equal to the difference of the instantaneous frequencies of the two input signals
 * and phase is equal to the phase difference of the two input signals.
 * The IF signal is digitized through an ADC, resulting in a time domain data which can then be
 * processed further for different use cases.
 *
 * \section subsection_xensiv_radar_presence_detection Presence Detection
 *
 * This application detects human presence within a configurable distance
 * and a certain field of view from the radar. The maximum range to detect
 * human presence can be configured using the library API. Presence detection
 * can be further utilized for applications such as keyword-less
 * authentication, automatic user interaction with smart devices
 * and many more. The following figure shows a high-level representation of
 * presence detection:
 *
 * \image html Presence.png "Presence detection application" width=600px
 * \image latex Presence.png
 *
 * \section subsection_xensiv_radar_presence__mounting_recommendations Mounting Recommendations
 *
 * The connected sensor kit with the Radar Wing Board can be mounted
 * anywhere on the wall in front facing orientation at 1-1.5 meters
 * height from the ground level. The following figure provides an
 * illustration of radar coverage for macro and micro movements.
 *
 * \image html radar_coverage.png "Radar coverage for macro and micro movements" width=700px
 * \image latex radar_coverage.png
 *
 * \section subsection_xensiv_radar_presence_algorithm_implementation Presence detection algorithm
 *
 * The presence detection library detects macro and micro movements.
 * The macro then micro detection mode could be illustrated using a state machine
 *
 * \image html algo.png "Presence detection algorithm" width=600px
 * \image latex algo.png
 *
 * When the detection is in absence state, it would check the macro level.
 * If macro level is higher than macro threshold, macro trigger confirmation
 * count will increase by
 * 1.
 * If confirmation count exceeds macro trigger delay, state would transit
 * from absence to presence.
 * For presence state, state remains in presence when micro level is higher
 * than the micro threshold.
 * When the micro level is lower than the micro threshold, absence count
 * will increase by 1.
 * If absence count exceeds micro valid, the state would go back to absence.
 *
 * The user can configure:
 * - operation mode (macro only, micro only, macro and micro or micro after macro)
 * - minimum and maximum range detection can be configured.
 * - sensitivity level of each mode can be adjusted by changing the thresholds levels.
 * - enable filtering
 *
 * \section subsection_xensiv_radar_presence_memory_requirements Memory Requirements
 * Code size (Bytes) : 10506
 *
 * RAM size (Bytes) : 86404
 *
 * \note All values are minimum requirements with default configuration, no application code and
 * Release build
 *
 * \section subsection_xensiv_radar_presence_quickstart Quick Start
 *
 * \section subsection_board_libs_snippets Code snippets
 * \subsection subsection_board_libs_snippet_1 Snippet 1: Example usage.
 * The following snippet shows a task that allocates and initializes an instance of the radar
 * presence detection algorithm using \ref xensiv_radar_presence_alloc.
 *
 * Next, the user event callback handler is configured using \ref
 * xensiv_radar_presence_set_callback.
 *
 * Finally, it waits in idle mode until new raw radar data is available
 * and feeds it to the algorithm using \ref xensiv_radar_presence_process_frame.
 * \snippet snippet/main.c snippet_xensiv_radar_presence
 */

#ifndef XENSIV_RADAR_PRESENCE_H
#define XENSIV_RADAR_PRESENCE_H

#include <stdint.h>
#include <stddef.h>

#include "ifx_sensor_dsp.h"

/************************************** Macros *******************************************/

/** Result code indicating successful operation. */
#define XENSIV_RADAR_PRESENCE_OK        (0)
/** Result code indicating a not supported configuration. */
#define XENSIV_RADAR_PRESENCE_FFT_LEN_ERROR (1)
/** Result code indicating a memory allocation error. */
#define XENSIV_RADAR_PRESENCE_MEM_ERROR (2)

/********************************* Type definitions **************************************/

/** Type definition for timestamp. */
#ifndef XENSIV_RADAR_PRESENCE_TIMESTAMP
#define XENSIV_RADAR_PRESENCE_TIMESTAMP uint32_t
#endif

/**
 * @brief XENSIV(TM) Radar Presence detection algorithm state
 */
typedef enum
{
    XENSIV_RADAR_PRESENCE_STATE_MACRO_PRESENCE, /**< macro presence event */
    XENSIV_RADAR_PRESENCE_STATE_MICRO_PRESENCE, /**< micro presence event */
    XENSIV_RADAR_PRESENCE_STATE_ABSENCE /**< absence event */
} xensiv_radar_presence_state_t;

/**
 * @brief XENSIV(TM) Radar Presence detection algorithm mode
 */
typedef enum
{
    /*! Only macro movement detection */
    XENSIV_RADAR_PRESENCE_MODE_MACRO_ONLY,
    /*! Only micro movement detection */
    XENSIV_RADAR_PRESENCE_MODE_MICRO_ONLY,
    /*! The algorithm would first detect macro motion for presence,
        and enter micro motion detect mode when the object movement is smaller */
    XENSIV_RADAR_PRESENCE_MODE_MICRO_IF_MACRO,
    /*! The algorithm would always detect both macro and micro movement;
        either kind of motion exceeding the threshold would be treated as a presence */
    XENSIV_RADAR_PRESENCE_MODE_MICRO_AND_MACRO
} xensiv_radar_presence_mode_t;

/**
 * @brief XENSIV(TM) Radar Presence detection algorithm event
 */
typedef struct
{
    /*! event time [ms] */
    XENSIV_RADAR_PRESENCE_TIMESTAMP timestamp;
    /*! range bin index */
    int32_t range_bin;
    /*! event type \ref xensiv_radar_presence_state_t */
    xensiv_radar_presence_state_t state;
} xensiv_radar_presence_event_t;

/**
 * @brief XENSIV(TM) Radar Presence detection algorithm configuration
 */
typedef struct
{
    /* initialization only parameters */

    /*! Number of samples per chirp. */
    int16_t num_samples_per_chirp;
    /*! slow time FFT, e.g. number of chirps accumulated
        before calculating micro movement FFT */
    int16_t micro_fft_size;
    /*! FMCW Radar signal bandwidth [Hz] */
    float32_t bandwidth;

    /* run-time parameters */

    /*! minimum detection range bin */
    int32_t min_range_bin;
    /*! maximum detection range bin */
    int32_t max_range_bin;
    /*! Threshold value used in macro movement detection */
    float32_t macro_threshold;
    /*! Threshold value used in micro movement detection */
    float32_t micro_threshold;

    /*! macro compare interval */
    XENSIV_RADAR_PRESENCE_TIMESTAMP macro_compare_interval_ms;

    /*! trigger delay for macro movement detection.
        Input value is multiple of \ref macro_compare_interval_ms.
        For example, if macro_compare_interval_ms is 250 and
        setting macro_movement_confirmations is 3, the algorithm will determine the motion as
        macro movement for a continuous 750ms of major motion */
    int32_t macro_movement_confirmations;

    /*! macro trigger range for macro movement detection.
        At least that many range bins need to be triggered, so that a presence is reported.
        Default is 1.  */
    int32_t macro_trigger_range;

    /*! Time-out value [ms] used to judge motion is no longer macro movement.
        For example, if the value is 1000, it means a detected value below the
        macro threshold for 1 second continuous would be treated as no macro movement */
    XENSIV_RADAR_PRESENCE_TIMESTAMP macro_movement_validity_ms;

    /*! Time-out value [ms] used to judge the motion is no longer micro movement.
        The judging criteria are the same as for a valid macro value. */
    XENSIV_RADAR_PRESENCE_TIMESTAMP micro_movement_validity_ms;

    /*! Sets the presence detection detect mode \ref xensiv_radar_presence_mode_t. */
    xensiv_radar_presence_mode_t mode;

    /*! Enable/disable vibration filter */
    bool macro_fft_bandpass_filter_enabled;

    /*! Enable/disable micro FFT low pass filter */
    bool micro_fft_decimation_enabled;

    /* number of micro doppler FFT ranges to accumulate */
    int32_t micro_movement_compare_idx;
} xensiv_radar_presence_config_t;

/** \cond INTERNAL */
struct xensiv_radar_presence_context;
typedef struct xensiv_radar_presence_context* xensiv_radar_presence_handle_t;
/** \endcond */

/**
 * @brief XENSIV(TM) Radar Presence detection callback to notify user about
 * presence events
 */
typedef void (* xensiv_radar_presence_cb_t)(xensiv_radar_presence_handle_t handle,
                                            const xensiv_radar_presence_event_t* event,
                                            void* data);

/******************************* Function prototypes *************************************/

#ifdef __cplusplus
extern "C" {
#endif

/** Assigns malloc and free functions for malloc_fptr and free_fptr variable
 *
 * @param[in] malloc_func   Pointer to a function that is used for allocating memory
 * @param[in] free_func     Pointer to a function that is used for freeing memory
 */
void xensiv_radar_presence_set_malloc_free(void* (*malloc_func)(size_t size),
                                           void (* free_func)(void* ptr));

/** Assigns callback function for presence context
 *
 * @param[in] handle        Pointer to a presence context
 * @param[in] callback      Pointer to a function that will handle presence events
 * @param[in] data          Data pointer that is passed to the callback
 */
void xensiv_radar_presence_set_callback(xensiv_radar_presence_handle_t handle,
                                        xensiv_radar_presence_cb_t callback,
                                        void* data);

/** Initialize XENSIV(TM) Initializes Radar Presence detection algorithm configuration
 * structure with defaults settings:
 *  @code
 *  bandwidth                         = 460E6
 *  num_samples_per_chirp             = 128
 *  micro_fft_decimation_enabled      = false
 *  micro_fft_size                    = 128
 *  macro_threshold                   = 0.5f
 *  micro_threshold                   = 12.5f
 *  min_range_bin                     = 1
 *  max_range_bin                     = 5
 *  macro_compare_interval_ms         = 250
 *  macro_movement_validity_ms        = 1000
 *  micro_movement_validity_ms        = 4000
 *  macro_movement_confirmations      = 0
 *  macro_trigger_range               = 1
 *  mode                              = XENSIV_RADAR_PRESENCE_MODE_MICRO_IF_MACRO
 *  macro_fft_bandpass_filter_enabled = false
 *  micro_movement_compare_idx        = 5
 *  @endcode
 *
 * @param[in] config        Pointer to a variable that holds the configuration
 */
void xensiv_radar_presence_init_config(xensiv_radar_presence_config_t* config);

/** Allocate XENSIV(TM) Radar Presence detection algorithm context.
 *
 * @param[out] handle       Pointer to a handle that holds the computation context
 * @param[in] config        Pointer to a variable that holds the configuration
 * @return XENSIV_RADAR_PRESENCE_OK if the initialization was successful; else an error indicating
 * what went wrong.
 */
int32_t xensiv_radar_presence_alloc(xensiv_radar_presence_handle_t* handle,
                                    const xensiv_radar_presence_config_t* config);

/** Obtains current presence detection algorithm configuration.
 *
 * @param[in] handle         Handle that holds the computation context
 * @param[out] config        Pointer to a variable where the configuration will be saved
 * @return XENSIV_RADAR_PRESENCE_OK if current configuration was read successful; else an error
 * indicating
 * what went wrong.
 */
int32_t xensiv_radar_presence_get_config(const xensiv_radar_presence_handle_t handle,
                                         xensiv_radar_presence_config_t* config);

/** Sets presence detection algorithm configuration.
 *
 * @param[out] handle       Handle that holds the computation context
 * @param[in] config        Pointer to a variable that holds new configuration
 * @return XENSIV_RADAR_PRESENCE_OK if configuration could be updated; else an error indicating
 * what went wrong.
 */
int32_t xensiv_radar_presence_set_config(xensiv_radar_presence_handle_t handle,
                                         const xensiv_radar_presence_config_t* config);

/** Process one radar frame.
 *
 * @param[in] handle        Handle that holds the computation context
 * @param[in] frame         Pointer to radar raw frame data.
 * \note frame data will be modified
 * @param[in] time_ms       Current time in milliseconds
 * @return XENSIV_RADAR_PRESENCE_OK if no problem found during frame processing;
 * else an error indicating what went wrong.
 */
int32_t xensiv_radar_presence_process_frame(xensiv_radar_presence_handle_t handle,
                                            float32_t* frame,
                                            XENSIV_RADAR_PRESENCE_TIMESTAMP time_ms);

/** Returns macro fft buffer from presence context
 *
 * @param[in] handle        Handle that holds the computation context
 * @return Pointer to the macro_fft_buffer array of size num_samples_per_chirp.
 */
cfloat32_t* xensiv_radar_presence_get_macro_fft_buffer(const xensiv_radar_presence_handle_t handle);

/**
 * @brief Return last maximum detected energy of macro movement against set threshold.
 *        This function can be called after processing several frames for getting the estimates
 *        of the energy amplitude with which the macro movements are detected and compared against
 *        the last set threshold. This is useful in finding the right value of the threshold for
 *        given scenarios.
 *
 * @param[in] handle        Handle that holds the computation context
 * @param[out] macro        Value representing amplitude of energy of the macro movement
 * @param[out] index        Value representing the distance of macro movement
 * @return XENSIV_RADAR_PRESENCE_OK macro could be read
 * @note Call to this function will reset the values of the macro and its range.
 */
bool xensiv_radar_presence_get_max_macro(const xensiv_radar_presence_handle_t handle,
                                         float* macro, int* index);

/**
 * @brief Return last maximum detected energy of micro movement against set threshold.
 *        This function can be called after processing several frames for getting the estimates
 *        of the energy amplitude with which the micro movements are detected and compared against
 *        the last set threshold. This is useful in finding the right value of the threshold for
 *        given scenarios.
 *
 * @param[in] handle        Handle that holds the computation context
 * @param[out] micro        Value representing amplitude of energy of the micro movement
 * @param[out] index        Value representing the distance of micro movement
 * @return XENSIV_RADAR_PRESENCE_OK macro could be read
 * @note Call to this function will reset the values of the micro and its range.
 */
bool xensiv_radar_presence_get_max_micro(const xensiv_radar_presence_handle_t handle,
                                         float* micro, int* index);

/**
 * @brief Return bin length in meters.
 * The length is calculated from the configured bandwidth of the radar.
 *
 * @param[in] handle        Handle that holds the computation context
 * @return float32_t bin length in meters.
 */
float32_t xensiv_radar_presence_get_bin_length(const xensiv_radar_presence_handle_t handle);

/** Resets the presence algorithm
 *
 * @param[in] handle        Handle that holds the computation context
 */
void xensiv_radar_presence_reset(xensiv_radar_presence_handle_t handle);

/** Frees up resources allocated during initialization.
 *
 * @param[in] handle        Handle that holds the computation context
 */
void xensiv_radar_presence_free(xensiv_radar_presence_handle_t handle);

/** \} group_board_libs */

#ifdef __cplusplus
}
#endif

#endif /* XENSIV_RADAR_PRESENCE_H */