General Description

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.

Radar System

A typical radar system consists of the following components:

A transmitter
A receiver
RF Generator
Amplifiers
Mixer
Analog to Digital Converter

This is represented by the following figure:

Radar system block diagram

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.

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:

Presence detection application

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.

Radar coverage for macro and micro movements

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

Presence detection algorithm

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

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

Quick Start

Code snippets

Snippet 1: Example usage.

The following snippet shows a task that allocates and initializes an instance of the radar presence detection algorithm using xensiv_radar_presence_alloc.

Next, the user event callback handler is configured using 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 xensiv_radar_presence_process_frame.

static __NO_RETURN void processing_task(void* pvParameters)
{
    (void)pvParameters;
    static const xensiv_radar_presence_config_t default_config =
    {
        .bandwidth                         = 460E6,
        .num_samples_per_chirp             = XENSIV_BGT60TRXX_CONF_NUM_SAMPLES_PER_CHIRP,
        .micro_fft_decimation_enabled      = false,
        .micro_fft_size                    = 128,
        .macro_threshold                   = 1.0f,
        .micro_threshold                   = 25.0f,
        .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,
        .mode                              = XENSIV_RADAR_PRESENCE_MODE_MICRO_IF_MACRO,
        .macro_fft_bandpass_filter_enabled = false
    };
    xensiv_radar_presence_handle_t handle;
    xensiv_radar_presence_set_malloc_free(pvPortMalloc,
                                          vPortFree);
    if (xensiv_radar_presence_alloc(&handle, &default_config) != 0)
    {
        CY_ASSERT(0);
    }
    xensiv_radar_presence_set_callback(handle, presence_detection_cb, NULL);
    for (;;)
    {
        /* Wait for frame data available to process */
        ulTaskNotifyTake(pdTRUE, portMAX_DELAY);
        xensiv_radar_presence_process_frame(handle, frame_f32,
                                            xTaskGetTickCount() * portTICK_PERIOD_MS);
    }
}
void presence_detection_cb(xensiv_radar_presence_handle_t handle,
                           const xensiv_radar_presence_event_t* event,
                           void* data)
{
    (void)handle;
    (void)data;
    switch (event->state)
    {
        case XENSIV_RADAR_PRESENCE_STATE_MACRO_PRESENCE:
            printf("[INFO] macro presence %" PRIi32 " %" PRIi32 "\n",
                   event->range_bin,
                   event->timestamp);
            break;
        case XENSIV_RADAR_PRESENCE_STATE_MICRO_PRESENCE:
            printf("[INFO] micro presence %" PRIi32 " %" PRIi32 "\n",
                   event->range_bin,
                   event->timestamp);
            break;
        case XENSIV_RADAR_PRESENCE_STATE_ABSENCE:
            printf("[INFO] absence %" PRIu32 "\n", event->timestamp);
            break;
        default:
            printf("[WARN]: Unknown reported state in event handling\n");
            break;
    }
}

Data Structures
struct	xensiv_radar_presence_event_t
	XENSIV(TM) Radar Presence detection algorithm event. More...

struct	xensiv_radar_presence_config_t
	XENSIV(TM) Radar Presence detection algorithm configuration. More...

Macros
#define	XENSIV_RADAR_PRESENCE_OK (0)
	Result code indicating successful operation. More...

#define	XENSIV_RADAR_PRESENCE_FFT_LEN_ERROR (1)
	Result code indicating a not supported configuration. More...

#define	XENSIV_RADAR_PRESENCE_MEM_ERROR (2)
	Result code indicating a memory allocation error. More...

#define	XENSIV_RADAR_PRESENCE_TIMESTAMP uint32_t
	Type definition for timestamp. More...

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

Enumerations
enum	xensiv_radar_presence_state_t { XENSIV_RADAR_PRESENCE_STATE_MACRO_PRESENCE, XENSIV_RADAR_PRESENCE_STATE_MICRO_PRESENCE, XENSIV_RADAR_PRESENCE_STATE_ABSENCE }
	XENSIV(TM) Radar Presence detection algorithm state. More...

enum	xensiv_radar_presence_mode_t { XENSIV_RADAR_PRESENCE_MODE_MACRO_ONLY, XENSIV_RADAR_PRESENCE_MODE_MICRO_ONLY, XENSIV_RADAR_PRESENCE_MODE_MICRO_IF_MACRO, XENSIV_RADAR_PRESENCE_MODE_MICRO_AND_MACRO }
	XENSIV(TM) Radar Presence detection algorithm mode. More...

Functions
void	xensiv_radar_presence_set_malloc_free (void (malloc_func)(size_t size), void(free_func)(void ptr))
	Assigns malloc and free functions for malloc_fptr and free_fptr variable. More...

void	xensiv_radar_presence_set_callback (xensiv_radar_presence_handle_t handle, xensiv_radar_presence_cb_t callback, void *data)
	Assigns callback function for presence context. More...

void	xensiv_radar_presence_init_config (xensiv_radar_presence_config_t *config)
	Initialize XENSIV(TM) Initializes Radar Presence detection algorithm configuration structure with defaults settings: More...

int32_t	xensiv_radar_presence_alloc (xensiv_radar_presence_handle_t handle, const xensiv_radar_presence_config_t config)
	Allocate XENSIV(TM) Radar Presence detection algorithm context. More...

int32_t	xensiv_radar_presence_get_config (const xensiv_radar_presence_handle_t handle, xensiv_radar_presence_config_t *config)
	Obtains current presence detection algorithm configuration. More...

int32_t	xensiv_radar_presence_set_config (xensiv_radar_presence_handle_t handle, const xensiv_radar_presence_config_t *config)
	Sets presence detection algorithm configuration. More...

int32_t	xensiv_radar_presence_process_frame (xensiv_radar_presence_handle_t handle, float32_t *frame, XENSIV_RADAR_PRESENCE_TIMESTAMP time_ms)
	Process one radar frame. More...

cfloat32_t *	xensiv_radar_presence_get_macro_fft_buffer (const xensiv_radar_presence_handle_t handle)
	Returns macro fft buffer from presence context. More...

bool	xensiv_radar_presence_get_max_macro (const xensiv_radar_presence_handle_t handle, float macro, int index)
	Return last maximum detected energy of macro movement against set threshold. More...

bool	xensiv_radar_presence_get_max_micro (const xensiv_radar_presence_handle_t handle, float micro, int index)
	Return last maximum detected energy of micro movement against set threshold. More...

float32_t	xensiv_radar_presence_get_bin_length (const xensiv_radar_presence_handle_t handle)
	Return bin length in meters. More...

void	xensiv_radar_presence_reset (xensiv_radar_presence_handle_t handle)
	Resets the presence algorithm. More...

void	xensiv_radar_presence_free (xensiv_radar_presence_handle_t handle)
	Frees up resources allocated during initialization. More...

Data Structure Documentation

◆ xensiv_radar_presence_event_t

struct xensiv_radar_presence_event_t

Data Fields
XENSIV_RADAR_PRESENCE_TIMESTAMP	timestamp	event time [ms]
int32_t	range_bin	range bin index
xensiv_radar_presence_state_t	state	event type xensiv_radar_presence_state_t

◆ xensiv_radar_presence_config_t

struct xensiv_radar_presence_config_t

Data Fields
int16_t	num_samples_per_chirp	Number of samples per chirp.
int16_t	micro_fft_size	slow time FFT, e.g. number of chirps accumulated before calculating micro movement FFT
float32_t	bandwidth	FMCW Radar signal bandwidth [Hz]
int32_t	min_range_bin	minimum detection range bin
int32_t	max_range_bin	maximum detection range bin
float32_t	macro_threshold	Threshold value used in macro movement detection
float32_t	micro_threshold	Threshold value used in micro movement detection
XENSIV_RADAR_PRESENCE_TIMESTAMP	macro_compare_interval_ms	macro compare interval
int32_t	macro_movement_confirmations	trigger delay for macro movement detection. Input value is multiple of 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_trigger_range	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.
XENSIV_RADAR_PRESENCE_TIMESTAMP	macro_movement_validity_ms	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	micro_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_mode_t	mode	Sets the presence detection detect mode xensiv_radar_presence_mode_t.
bool	macro_fft_bandpass_filter_enabled	Enable/disable vibration filter
bool	micro_fft_decimation_enabled	Enable/disable micro FFT low pass filter
int32_t	micro_movement_compare_idx

Macro Definition Documentation

◆ XENSIV_RADAR_PRESENCE_OK

#define XENSIV_RADAR_PRESENCE_OK (0)

Result code indicating successful operation.

◆ XENSIV_RADAR_PRESENCE_FFT_LEN_ERROR

#define XENSIV_RADAR_PRESENCE_FFT_LEN_ERROR (1)

Result code indicating a not supported configuration.

◆ XENSIV_RADAR_PRESENCE_MEM_ERROR

#define XENSIV_RADAR_PRESENCE_MEM_ERROR (2)

Result code indicating a memory allocation error.

◆ XENSIV_RADAR_PRESENCE_TIMESTAMP

#define XENSIV_RADAR_PRESENCE_TIMESTAMP uint32_t

Type definition for timestamp.

Enumeration Type Documentation

◆ xensiv_radar_presence_state_t

enum xensiv_radar_presence_state_t

XENSIV(TM) Radar Presence detection algorithm state.

Enumerator
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_mode_t

enum xensiv_radar_presence_mode_t

XENSIV(TM) Radar Presence detection algorithm mode.

Enumerator
XENSIV_RADAR_PRESENCE_MODE_MACRO_ONLY	Only macro movement detection
XENSIV_RADAR_PRESENCE_MODE_MICRO_ONLY	Only micro movement detection
XENSIV_RADAR_PRESENCE_MODE_MICRO_IF_MACRO	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_AND_MACRO	The algorithm would always detect both macro and micro movement; either kind of motion exceeding the threshold would be treated as a presence

Function Documentation

◆ xensiv_radar_presence_set_malloc_free()

void xensiv_radar_presence_set_malloc_free	(	void ()(size_t size)	malloc_func,
		void()(void ptr)	free_func
	)

Assigns malloc and free functions for malloc_fptr and free_fptr variable.

Parameters

[in]	malloc_func	Pointer to a function that is used for allocating memory
[in]	free_func	Pointer to a function that is used for freeing memory

◆ xensiv_radar_presence_set_callback()

void xensiv_radar_presence_set_callback	(	xensiv_radar_presence_handle_t	handle,
		xensiv_radar_presence_cb_t	callback,
		void *	data
	)

Assigns callback function for presence context.

Parameters

[in]	handle	Pointer to a presence context
[in]	callback	Pointer to a function that will handle presence events
[in]	data	Data pointer that is passed to the callback

◆ xensiv_radar_presence_init_config()

void xensiv_radar_presence_init_config ( xensiv_radar_presence_config_t * config )

Initialize XENSIV(TM) Initializes Radar Presence detection algorithm configuration structure with defaults settings:

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

Parameters

[in] config Pointer to a variable that holds the configuration

◆ xensiv_radar_presence_alloc()

int32_t xensiv_radar_presence_alloc	(	xensiv_radar_presence_handle_t *	handle,
		const xensiv_radar_presence_config_t *	config
	)

Allocate XENSIV(TM) Radar Presence detection algorithm context.

Parameters

[out]	handle	Pointer to a handle that holds the computation context
[in]	config	Pointer to a variable that holds the configuration

Returns: XENSIV_RADAR_PRESENCE_OK if the initialization was successful; else an error indicating what went wrong.

◆ xensiv_radar_presence_get_config()

int32_t xensiv_radar_presence_get_config	(	const xensiv_radar_presence_handle_t	handle,
		xensiv_radar_presence_config_t *	config
	)

Obtains current presence detection algorithm configuration.

Parameters

[in]	handle	Handle that holds the computation context
[out]	config	Pointer to a variable where the configuration will be saved

Returns: XENSIV_RADAR_PRESENCE_OK if current configuration was read successful; else an error indicating what went wrong.

◆ xensiv_radar_presence_set_config()

int32_t xensiv_radar_presence_set_config	(	xensiv_radar_presence_handle_t	handle,
		const xensiv_radar_presence_config_t *	config
	)

Sets presence detection algorithm configuration.

Parameters

[out]	handle	Handle that holds the computation context
[in]	config	Pointer to a variable that holds new configuration

Returns: XENSIV_RADAR_PRESENCE_OK if configuration could be updated; else an error indicating what went wrong.

◆ xensiv_radar_presence_process_frame()

int32_t xensiv_radar_presence_process_frame	(	xensiv_radar_presence_handle_t	handle,
		float32_t *	frame,
		XENSIV_RADAR_PRESENCE_TIMESTAMP	time_ms
	)

Process one radar frame.

Parameters

[in]	handle	Handle that holds the computation context
[in]	frame	Pointer to radar raw frame data.

Note: frame data will be modified

Parameters

[in] time_ms Current time in milliseconds

Returns: XENSIV_RADAR_PRESENCE_OK if no problem found during frame processing; else an error indicating what went wrong.

◆ xensiv_radar_presence_get_macro_fft_buffer()

cfloat32_t* xensiv_radar_presence_get_macro_fft_buffer ( const xensiv_radar_presence_handle_t handle )

Returns macro fft buffer from presence context.

Parameters

[in] handle Handle that holds the computation context

Returns: Pointer to the macro_fft_buffer array of size num_samples_per_chirp.

◆ xensiv_radar_presence_get_max_macro()

bool xensiv_radar_presence_get_max_macro	(	const xensiv_radar_presence_handle_t	handle,
		float *	macro,
		int *	index
	)

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.

Parameters

[in]	handle	Handle that holds the computation context
[out]	macro	Value representing amplitude of energy of the macro movement
[out]	index	Value representing the distance of macro movement

Returns: XENSIV_RADAR_PRESENCE_OK macro could be read

Note: Call to this function will reset the values of the macro and its range.

◆ xensiv_radar_presence_get_max_micro()

bool xensiv_radar_presence_get_max_micro	(	const xensiv_radar_presence_handle_t	handle,
		float *	micro,
		int *	index
	)

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.

Parameters

[in]	handle	Handle that holds the computation context
[out]	micro	Value representing amplitude of energy of the micro movement
[out]	index	Value representing the distance of micro movement

Returns: XENSIV_RADAR_PRESENCE_OK macro could be read

Note: Call to this function will reset the values of the micro and its range.

◆ xensiv_radar_presence_get_bin_length()

float32_t xensiv_radar_presence_get_bin_length ( const xensiv_radar_presence_handle_t handle )

Return bin length in meters.

The length is calculated from the configured bandwidth of the radar.

Parameters

[in] handle Handle that holds the computation context

Returns: float32_t bin length in meters.

◆ xensiv_radar_presence_reset()

void xensiv_radar_presence_reset ( xensiv_radar_presence_handle_t handle )

Resets the presence algorithm.

Parameters

[in] handle Handle that holds the computation context

◆ xensiv_radar_presence_free()

void xensiv_radar_presence_free ( xensiv_radar_presence_handle_t handle )

Frees up resources allocated during initialization.

Parameters

[in] handle Handle that holds the computation context

General Description

Radar System

Presence Detection

Mounting Recommendations

Presence detection algorithm

Memory Requirements

Quick Start

Code snippets

Snippet 1: Example usage.

Data Structures

Macros

Typedefs

Enumerations

Functions

Data Structure Documentation

◆ xensiv_radar_presence_event_t

◆ xensiv_radar_presence_config_t

Macro Definition Documentation

◆ XENSIV_RADAR_PRESENCE_OK

◆ XENSIV_RADAR_PRESENCE_FFT_LEN_ERROR

◆ XENSIV_RADAR_PRESENCE_MEM_ERROR

◆ XENSIV_RADAR_PRESENCE_TIMESTAMP

Enumeration Type Documentation

◆ xensiv_radar_presence_state_t

◆ xensiv_radar_presence_mode_t

Function Documentation

◆ xensiv_radar_presence_set_malloc_free()

◆ xensiv_radar_presence_set_callback()

◆ xensiv_radar_presence_init_config()

◆ xensiv_radar_presence_alloc()

◆ xensiv_radar_presence_get_config()

◆ xensiv_radar_presence_set_config()

◆ xensiv_radar_presence_process_frame()

◆ xensiv_radar_presence_get_macro_fft_buffer()

◆ xensiv_radar_presence_get_max_macro()

◆ xensiv_radar_presence_get_max_micro()

◆ xensiv_radar_presence_get_bin_length()

◆ xensiv_radar_presence_reset()

◆ xensiv_radar_presence_free()