Permalink
Cannot retrieve contributors at this time
Name already in use
A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?
xensiv-radar-sensing/mtb_radar_sensing.h
Go to fileThis commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
784 lines (745 sloc)
34.7 KB
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| /** | |
| * \file mtb_radar_sensing.h | |
| * \version 1.0 | |
| * | |
| * \brief | |
| * This file includes all the header files of the RadarSensing middleware. | |
| * | |
| ******************************************************************************** | |
| * \copyright | |
| * Copyright (C) 2021 Infineon Technologies AG. All rights reserved. | |
| * | |
| * Infineon Technologies AG (INFINEON) is supplying this file for use | |
| * exclusively with Infineon's sensor products. This file can be freely | |
| * distributed within development tools and software supporting such | |
| * products. | |
| * | |
| * THIS SOFTWARE IS PROVIDED "AS IS". NO WARRANTIES, WHETHER EXPRESS, IMPLIED | |
| * OR STATUTORY, INCLUDING, BUT NOT LIMITED TO, IMPLIED WARRANTIES OF | |
| * MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE APPLY TO THIS SOFTWARE. | |
| * INFINEON SHALL NOT, IN ANY CIRCUMSTANCES, BE LIABLE FOR DIRECT, INDIRECT, | |
| * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES, FOR ANY REASON | |
| * WHATSOEVER. | |
| *******************************************************************************/ | |
| /** | |
| ******************************************************************************** | |
| * \mainpage RadarSensing Library | |
| ******************************************************************************** | |
| * The RadarSensing Library provides a high-level interface for multiple radar use cases. | |
| * <b>RADAR</b> (Radio Detection and Ranging) is a device that uses electromagnetic waves to obtain | |
| * range, angle or velocity of targets. Radar systems are used in a number of areas covering a | |
| * variety of applications. Some of them include (but not limited to): \n | |
| * - Air traffic control: aircraft tracking and guidance in airports. | |
| * - Space: satellite tracking, observation of meteors and other planetory bodies. | |
| * - Remote Sensing: weather surveillance. | |
| * - Health: vital signs monitoring. | |
| * - Modern Smart Devices: \ref section_presence_detection, \ref section_entrance_counter, gesture recognition, target | |
| localization. | |
| * | |
| * There are a number of reasons behind the use of radar in the aforementioned applications: | |
| * - 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 section_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 section_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 RadarSensing libary 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 section_entrance_counter Entrance Counter | |
| * | |
| * This application counts the number of people entering and exiting a location | |
| * such as an office building, cafeteria, supermarket etc. This allows customers to determine the occupancy | |
| * of their premises, thus enabling various solutions such as maintaining social distancing, | |
| * evacuating in case of an emergency and saving energy based on occupancy. Furthermore, the entrance counter | |
| * data can be sent to a centralized server and remotely displayed on laptops or mobile devices to understand | |
| * the occupancy level. The following figure shows a high-level representation of entrance counter: | |
| * | |
| * \image html entrance_counter.png "Entrance counter application" width=900px | |
| * \image latex entrance_counter.png | |
| * The above use cases are implemented using Infineon's XENSIV™ 60GHz radar: | |
| * https://www.infineon.com/cms/en/product/sensor/radar-sensors/radar-sensors-for-iot/60ghz-radar/ | |
| * | |
| * \note Radar wingboard driver is embedded in the current release of RadarSensing library. Future releases | |
| * will have radar wingboard driver shipped separately. This will provide direct access to the time domain data | |
| * from radar, which users can feed to their own algorithms, thus enabling more use cases. | |
| * | |
| ********************************************************************************* | |
| * \page section_radar_sensing_configuration RadarSensing library API usage | |
| ******************************************************************************** | |
| * | |
| * \par | |
| * Following code snippet shows example usage of RadarSensing library APIs for | |
| * presence detection application. | |
| * | |
| * \code | |
| * #include "mtb_radar_sensing.h" | |
| * | |
| * //Declare a context of radar. | |
| * mtb_radar_sensing_context_t sensing_context; | |
| * | |
| * //Declare SPI object | |
| * cyhal_spi_t mSPI; | |
| * | |
| * //Initialize HW configurations for radar | |
| * mtb_radar_sensing_hw_cfg_t hw_cfg = | |
| * { | |
| * .spi_cs = CYBSP_SPI_CS, | |
| * .reset = CYBSP_GPIO11, | |
| * .ldo_en = CYBSP_GPIO5, | |
| * .irq = CYBSP_GPIO10, | |
| * .spi = &mSPI | |
| * }; | |
| * | |
| * //Activate radar reset pin | |
| * cyhal_gpio_init(hw_cfg.reset, CYHAL_GPIO_DIR_OUTPUT, CYHAL_GPIO_DRIVE_STRONG, true); | |
| * | |
| * //Enable LDO | |
| * cyhal_gpio_init(hw_cfg.ldo_en, CYHAL_GPIO_DIR_OUTPUT, CYHAL_GPIO_DRIVE_STRONG, true); | |
| * | |
| * //Enable IRQ pin | |
| * cyhal_gpio_init(hw_cfg.irq, CYHAL_GPIO_DIR_INPUT, CYHAL_GPIO_DRIVE_PULLDOWN, false); | |
| * | |
| * //CS handled manually | |
| * cyhal_gpio_init(hw_cfg.spi_cs, CYHAL_GPIO_DIR_OUTPUT, CYHAL_GPIO_DRIVE_STRONG, true); | |
| * | |
| * //Configure SPI interface | |
| * if (cyhal_spi_init(hw_cfg.spi, CYBSP_SPI_MOSI, CYBSP_SPI_MISO, CYBSP_SPI_CLK, NC, NULL, 8, | |
| * CYHAL_SPI_MODE_00_MSB, false) != CY_RSLT_SUCCESS ) | |
| * { | |
| * CY_ASSERT(0); | |
| * } | |
| * | |
| * //Set the data rate to 25 Mbps | |
| * if (cyhal_spi_set_frequency(hw_cfg.spi, SPI_FREQUENCY) != CY_RSLT_SUCCESS) | |
| * { | |
| * CY_ASSERT(0); | |
| * } | |
| * | |
| * //Initialize the context of radar and configure events for presence detection application. | |
| * if (mtb_radar_sensing_init(&sensing_context, &hw_cfg, MTB_RADAR_SENSING_MASK_PRESENCE_EVENTS) != MTB_RADAR_SENSING_SUCCESS) | |
| * { | |
| * printf("mtb_radar_sensing_init error - Radar Wingboard not connected?\n"); | |
| * CY_ASSERT(0); | |
| * return; | |
| * } | |
| * | |
| * //Configure parameters for presence detection. | |
| * if (mtb_radar_sensing_set_parameter(sensing_context, "radar_presence_range_max", "1.0") != | |
| * MTB_RADAR_SENSING_SUCCESS) | |
| * { | |
| * CY_ASSERT(0); | |
| * return; | |
| * } | |
| * if (mtb_radar_sensing_set_parameter(sensing_context, "radar_presence_sensitivity", "medium") != | |
| * MTB_RADAR_SENSING_SUCCESS) | |
| * { | |
| * CY_ASSERT(0); | |
| * return; | |
| * } | |
| * | |
| * //Declare the following function to prepare a callback that handles presence detection events. | |
| * void radar_sensing_callback(mtb_radar_sensing_context_t sensing_context, | |
| * mtb_radar_sensing_event_t event, | |
| * mtb_radar_sensing_event_info_t* event_info, | |
| * void* data) | |
| * { | |
| * switch (event) { | |
| * case MTB_RADAR_SENSING_EVENT_PRESENCE_IN: | |
| * printf("%.3f: Presence IN %.2f-%.2f\r\n", | |
| * (float) event_info->timestamp / 1000, | |
| * ((mtb_radar_sensing_presence_event_info_t*)event_info)->distance); | |
| * break; | |
| * case MTB_RADAR_SENSING_EVENT_PRESENCE_OUT: | |
| * printf("%.3f: Presence OUT\r\n", (float) event_info->timestamp / 1000); | |
| * break; | |
| * } | |
| * } | |
| * | |
| * //Register callback. | |
| * if (mtb_radar_sensing_register_callback(sensing_context, radar_sensing_callback, NULL) != | |
| * MTB_RADAR_SENSING_SUCCESS) | |
| * { | |
| * CY_ASSERT(0); | |
| * return; | |
| * } | |
| * | |
| * //Enable radar sensing and periodically call mtb_radar_sensing_process to process time domain | |
| * //data acquired from radar. | |
| * if (mtb_radar_sensing_enable(sensing_context) != MTB_RADAR_SENSING_SUCCESS) | |
| * { | |
| * CY_ASSERT(0); | |
| * return; | |
| * } | |
| * for (;;) | |
| * { | |
| * //Process data acquired from radar every 2ms | |
| * uint64_t currenttime = (uint64_t)xTaskGetTickCount() * 1000LL / configTICK_RATE_HZ; | |
| * if (mtb_radar_sensing_process(sensing_context, currenttime) != MTB_RADAR_SENSING_SUCCESS) | |
| * { | |
| * printf("mtb_radar_sensing_process error\n"); | |
| * CY_ASSERT(0); | |
| * } | |
| * vTaskDelay(MTB_RADAR_SENSING_PROCESS_DELAY); | |
| * } | |
| * | |
| * \endcode | |
| * | |
| * \note | |
| * - mtb_radar_sensing_process should be called every ~2ms (use \ref MTB_RADAR_SENSING_PROCESS_DELAY constant). \n | |
| * - Users should replace currenttime initialization with their own APIs that provide system time in ms. \n | |
| * - For a complete demonstration of the above code snippet using FreeRTOS, please refer to the Modus Toolbox Code | |
| Example | |
| * on presence detection and entrance counter. | |
| * - For a MCU other than PSoC, users will have to configure SPI, HW accordingly. \n | |
| * \par | |
| * A similar approach can be taken to demonstrate the use of RadarSensing library APIs for entrance counter. | |
| * However, there are a few changes that need to be made to the above code snippet: | |
| * | |
| * \code | |
| * | |
| * //Replace initialization such that events for entrance counter application is configured. | |
| * if (mtb_radar_sensing_init(&sensing_context, &hw_cfg, MTB_RADAR_SENSING_MASK_COUNTER_EVENTS) != MTB_RADAR_SENSING_SUCCESS) | |
| * { | |
| * printf("mtb_radar_sensing_init error - Radar Wingboard not connected?\n"); | |
| * CY_ASSERT(0); | |
| * return; | |
| * } | |
| * | |
| * //Configure parameters used for entrance counter, e.g. installation as side, orientation as landscape. | |
| * if (mtb_radar_sensing_set_parameter(sensing_context, "radar_counter_installation", "side") != | |
| * MTB_RADAR_SENSING_SUCCESS) | |
| * { | |
| * CY_ASSERT(0); | |
| * return; | |
| * } | |
| * if (mtb_radar_sensing_set_parameter(sensing_context, "radar_counter_orientation", "landscape") != | |
| * MTB_RADAR_SENSING_SUCCESS) | |
| * { | |
| * CY_ASSERT(0); | |
| * return; | |
| * } | |
| * | |
| * //Update the callback to handle entrance counter events. | |
| * void radar_sensing_callback(mtb_radar_sensing_context_t sensing_context, | |
| * mtb_radar_sensing_event_t event, | |
| * mtb_radar_sensing_event_info_t* event_info, | |
| * void* data) | |
| *{ | |
| * switch (event) | |
| * { | |
| * // people walking in detected | |
| * case MTB_RADAR_SENSING_EVENT_COUNTER_IN: | |
| * printf("%.2f: Counter IN detected, IN: %d, OUT: %d\r\n", | |
| * (float)event_info->timestamp / 1000, | |
| * ((mtb_radar_sensing_counter_event_info_t *)event_info)->in_count, | |
| * ((mtb_radar_sensing_counter_event_info_t *)event_info)->out_count); | |
| * break; | |
| * // people walking out detected | |
| * case MTB_RADAR_SENSING_EVENT_COUNTER_OUT: | |
| * printf("%.2f: Counter OUT detected, IN: %d, OUT: %d\r\n", | |
| * (float)event_info->timestamp / 1000, | |
| * ((mtb_radar_sensing_counter_event_info_t *)event_info)->in_count, | |
| * ((mtb_radar_sensing_counter_event_info_t *)event_info)->out_count); | |
| * break; | |
| * // object detected in traffic zone, reminder for social distancing | |
| * case MTB_RADAR_SENSING_EVENT_COUNTER_OCCUPIED: | |
| * printf("%.2f: Counter occupied detected, IN: %d, OUT: %d\r\n", | |
| * (float)event_info->timestamp / 1000, | |
| * ((mtb_radar_sensing_counter_event_info_t *)event_info)->in_count, | |
| * ((mtb_radar_sensing_counter_event_info_t *)event_info)->out_count); | |
| * break; | |
| * // no more object detected in traffic zone | |
| * case MTB_RADAR_SENSING_EVENT_COUNTER_FREE: | |
| * printf("%.2f: Counter free detected, IN: %d, OUT: %d\r\n", | |
| * (float)event_info->timestamp / 1000, | |
| * ((mtb_radar_sensing_counter_event_info_t *)event_info)->in_count, | |
| * ((mtb_radar_sensing_counter_event_info_t *)event_info)->out_count); | |
| * break; | |
| * default: | |
| * break; | |
| * } | |
| *} | |
| * | |
| * \endcode | |
| * | |
| * For details on high-level function, used data structures and callback definition, please refer to: | |
| * * \ref group_mtb_radar_sensing_high_level | |
| * * \ref group_mtb_radar_sensing_macros | |
| * * \ref group_mtb_radar_sensing_structures | |
| * * \ref group_mtb_radar_sensing_callbacks | |
| * | |
| ******************************************************************************** | |
| * \page page_mounting_recommendations Mounting recommendations | |
| ******************************************************************************** | |
| * \section section_mounting_recommendations_presence Presence detection application | |
| * | |
| * 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 section_mounting_recommendations_counter Entrance counter application | |
| * The connected sensor kit with the Radar Wing Board can be mounted on a side or a ceiling | |
| * of an entrance as shown in figure below. | |
| * | |
| * \image html mounting_location.png "Mounting locations for connected sensor kit" width=600px | |
| * \image latex mounting_location.png | |
| * | |
| * The following figure shows a ceiling installation of the kit. It should be noted that | |
| * moving objects or swinging door should be avoided in the radar field of view. Current release | |
| * of entrance counter application does not have a workaround to handle swinging doors. | |
| * For optimal performance, the configured ceiling height should be less than the actual ceiling height. | |
| * For example, if the ceiling or top of the door is 3m high, the configured ceiling height | |
| * should be less than or equal to 2m. | |
| * | |
| * \note It is recommended to mount the sensor kit on a ceiling for optimal performance. | |
| * | |
| * \image html ceiling_mount.png "Ceiling installation of connected sensor kit" width=500px | |
| * \image latex ceiling_mount.png | |
| * | |
| * The figure below illustrates a side installation. For optimal performance, the configured entrance width | |
| * should be less than the actual entrance width. It is recommended (but not required) to configure entrance width | |
| * ~30cm less than the actual width. This makes sure reflections do not interfere with counting. | |
| * | |
| * \image html side_mount.png "Side installation of connected sensor kit" width=500px | |
| * \image latex side_mount.png | |
| * | |
| * | |
| ******************************************************************************** | |
| * \page group_mtb_radar_sensing_quick_start Quick Start Guide | |
| ******************************************************************************** | |
| * | |
| * RadarSensing library is used in ModusToolbox, Refer to the \ref section_radar_sensing_toolchain. | |
| * The quickest way to get started is using the Code Examples. Infineon | |
| * Semiconductor continuously extends its portfolio of the code examples at the | |
| * <a href="http://www.cypress.com"><b>Cypress Semiconductor website</b></a> | |
| * and at the <a href="https://github.com/cypresssemiconductorco"> | |
| * <b>Cypress Semiconductor GitHub</b></a>. | |
| * | |
| * \section group_mtb_radar_sensing_quick_start_modus RadarSensing Quick Start Guide | |
| * | |
| * This quick start guide assumes that the environment is configured to use | |
| * PSoC 6 Peripheral Driver Library(psoc6pdl) for development and the | |
| * library is included in the project. | |
| * It also assumes the | |
| * <a href="https://www.cypress.com/ModusToolboxDeviceConfig"> | |
| * <b>ModusToolbox Device Configurator Tool</b></a> | |
| * | |
| * - Click on New Application option in Modus Toolbox to open Project Creator and select CYBSYSKIT-DEV-01. | |
| * \image html project_creator.png "Project Creator" width=800px | |
| * \image latex project_creator.png | |
| * | |
| * - Click on the application to be created: Radar Presence / Entrance Counter Application on FreeRTOS and click on Create. | |
| * Once done, the example project is visible on Project Explorer tab. Build and run. | |
| * \image html application_selection.png "Application selection" width=800px | |
| * \image latex application_selection.png | |
| * | |
| * \note Please make sure that the radar wingboard is connected to the FeatherKit. | |
| * | |
| ******************************************************************************** | |
| * \section section_radar_sensing_toolchain Supported Software and Tools | |
| ******************************************************************************** | |
| * | |
| * This version of library is compatible with the following Softwares and Tools: | |
| * <table class="doxtable"> | |
| * <tr> | |
| * <th>Software and Tools</th> | |
| * <th>Version</th> | |
| * </tr> | |
| * <tr> | |
| * <td>ModusToolbox Software Environment</td> | |
| * <td>2.2</td> | |
| * </tr> | |
| * <tr> | |
| * <td>ModusToolbox Project Creator</td> | |
| * <td>1.20</td> | |
| * </tr> | |
| * <tr> | |
| * <td>Peripheral Driver Library (PDL)</td> | |
| * <td>1.5.0</td> | |
| * </tr> | |
| * <tr> | |
| * <td>GCC Compiler</td> | |
| * <td>9.3.1</td> | |
| * </tr> | |
| * <tr> | |
| * <td>FreeRTOS</td> | |
| * <td>10.3.1</td> | |
| * </tr> | |
| * </table> | |
| * | |
| * | |
| ******************************************************************************** | |
| * \section section_radar_sensing_memory_usage Memory Usage | |
| ******************************************************************************** | |
| * | |
| * Flash size - 49228 bytes | |
| * Data size - 568 bytes | |
| * | |
| * The RadarSensing library runtime required stack and heap memory consumption | |
| * varies for different applications. | |
| * | |
| * Entrance counter: | |
| * | |
| * * Stack Size - 1792 bytes | |
| * * Heap Size - 25026 bytes | |
| * | |
| * Presence detection: | |
| * | |
| * * Stack Size - 1792 bytes | |
| * * Heap Size - 137837 bytes | |
| * | |
| ******************************************************************************** | |
| * \section section_radar_sensing_more_information More Information | |
| ******************************************************************************** | |
| * | |
| * Cypress highly recommends starting with these documents. They can be found on | |
| * the Cypress web site at www.cypress.com. | |
| * | |
| * For more information, refer to the following documents: | |
| * | |
| * * <a href="https://www.cypress.com/products/modustoolbox-software-environment"> | |
| * <b>ModusToolbox Software Environment, Quick Start Guide, Documentation, | |
| * and Videos</b></a> | |
| * | |
| * * <a href="https://github.com/cypresssemiconductorco"><b> | |
| * Cypress Semiconductor GitHub</b></a> | |
| * | |
| * | |
| * * <a href="https://www.cypress.com/ModusToolboxDeviceConfig"><b>ModusToolbox | |
| * Device Configurator Tool Guide</b></a> | |
| * | |
| * * <a href="https://cypresssemiconductorco.github.io/psoc6pdl/pdl_api_reference_manual/html/index.html"> | |
| * <b>PDL API Reference</b></a> | |
| * | |
| * * <a href="http://www.cypress.com"><b>Cypress Semiconductor</b></a> | |
| * | |
| * \note | |
| * The links to another software component's documentation (middleware and PDL) | |
| * point to GitHub to the latest available version of the software. | |
| * To get documentation of the specified version, download from GitHub and unzip | |
| * the component archive. The documentation is available in the <i>docs</i> folder. | |
| * | |
| * \defgroup group_mtb_radar_sensing_high_level High Level | |
| * \brief RadarSensing high level interface functions. | |
| * | |
| * \defgroup group_mtb_radar_sensing_macros Macros | |
| * \brief Macros for constants and error codes. | |
| * | |
| * \defgroup group_mtb_radar_sensing_structures Structures | |
| * \brief Typedefs and structures used in the library. | |
| * | |
| * \defgroup group_mtb_radar_sensing_callbacks Callbacks | |
| * \brief Callbacks used in the library. | |
| * | |
| **/ | |
| /** | |
| * @file | |
| * | |
| * @brief This file contains constants, structures and function prototypes | |
| * used in RadarSensing library. | |
| */ | |
| #pragma once | |
| #include <stdbool.h> | |
| #include <stdint.h> | |
| #include <stddef.h> | |
| #include "cyhal.h" | |
| #ifdef __cplusplus | |
| extern "C" { | |
| #endif | |
| /******************************************************************************* | |
| * Macros | |
| *******************************************************************************/ | |
| /******************************************************************************/ | |
| /** \addtogroup group_mtb_radar_sensing_macros */ /** \{ */ | |
| /******************************************************************************/ | |
| /** Recommended delay time (ms) after each call to mtb_radar_sensing_process **/ | |
| #define MTB_RADAR_SENSING_PROCESS_DELAY (2) | |
| #define MTB_RADAR_SENSING_SUCCESS CY_RSLT_SUCCESS /**< Result success */ | |
| #define MTB_RADAR_SENSING_INIT_ERROR (1) /**< Initialization error */ | |
| #define MTB_RADAR_SENSING_MEM_ERROR (2) /**< Memory allocation error */ | |
| #define MTB_RADAR_SENSING_PROCESS_ERROR (3) /**< Processing error */ | |
| #define MTB_RADAR_SENSING_CONFIGURATION_ERROR (4) /**< Configuration error */ | |
| #define MTB_RADAR_SENSING_BAD_PARAM (5) /**< The function input parameter is invalid */ | |
| /** RadarSensing module base */ | |
| #define CY_RSLT_MODULE_RADAR_SENSING CY_RSLT_MODULE_MIDDLEWARE_BASE + 20 // TODO align base | |
| #define MTB_RADAR_SENSING_RESULT_INIT_ERROR \ | |
| CY_RSLT_CREATE(CY_RSLT_TYPE_FATAL, \ | |
| CY_RSLT_MODULE_RADAR_SENSING, \ | |
| (MTB_RADAR_SENSING_INIT_ERROR)) /**< Create a result for initialization error */ | |
| #define MTB_RADAR_SENSING_RESULT_MEM_ERROR \ | |
| CY_RSLT_CREATE(CY_RSLT_TYPE_FATAL, \ | |
| CY_RSLT_MODULE_RADAR_SENSING, \ | |
| (MTB_RADAR_SENSING_MEM_ERROR)) /**< Create a result for memory allocation error */ | |
| #define MTB_RADAR_SENSING_RESULT_PROCESS_ERROR \ | |
| CY_RSLT_CREATE(CY_RSLT_TYPE_FATAL, \ | |
| CY_RSLT_MODULE_RADAR_SENSING, \ | |
| (MTB_RADAR_SENSING_PROCESS_ERROR)) /**< Create a result for processing error */ | |
| #define MTB_RADAR_SENSING_RESULT_CONFIGURATION_ERROR \ | |
| CY_RSLT_CREATE(CY_RSLT_TYPE_FATAL, \ | |
| CY_RSLT_MODULE_RADAR_SENSING, \ | |
| (MTB_RADAR_SENSING_CONFIGURATION_ERROR)) /**< Create a result for configuration error */ | |
| #define MTB_RADAR_SENSING_RESULT_BAD_PARAM \ | |
| CY_RSLT_CREATE(CY_RSLT_TYPE_FATAL, \ | |
| CY_RSLT_MODULE_RADAR_SENSING, \ | |
| (MTB_RADAR_SENSING_BAD_PARAM)) /**< Create a result for configuration error */ | |
| /******************************************************************************/ | |
| /** \} \endcond **/ | |
| /******************************************************************************/ | |
| /******************************************************************************/ | |
| /** \addtogroup group_mtb_radar_sensing_structures */ /** \{ */ | |
| /******************************************************************************/ | |
| /** | |
| * @brief timestamp in milliseconds | |
| */ | |
| typedef uint64_t mtb_radar_sensing_timestamp_t; | |
| /** | |
| * @brief time interval in milliseconds | |
| */ | |
| typedef uint32_t mtb_radar_sensing_timeinterval_t; | |
| /** | |
| * @brief Type of events that are detected. | |
| */ | |
| typedef enum | |
| { | |
| MTB_RADAR_SENSING_EVENT_PRESENCE_IN = 300, /*!< Presence event: one or more people were detected in radar field of view within maximum range */ | |
| MTB_RADAR_SENSING_EVENT_PRESENCE_OUT = 301, /*!< Absence event: no human presence was detected in radar field of view within maximum range */ | |
| MTB_RADAR_SENSING_EVENT_COUNTER_IN = 310, /*!< Counter in event: a person has entered through the counter */ | |
| MTB_RADAR_SENSING_EVENT_COUNTER_OUT = 311, /*!< Counter out event: a person has exited through the counter */ | |
| MTB_RADAR_SENSING_EVENT_COUNTER_OCCUPIED = 312, /*!< Counter occupied: a person is still present in the traffic light zone */ | |
| MTB_RADAR_SENSING_EVENT_COUNTER_FREE = 313, /*!< Counter free: no human presence in the traffic light zone */ | |
| } mtb_radar_sensing_event_t; | |
| /** | |
| * @brief Type of application events that needs to be configured with \ref mtb_radar_sensing_init | |
| * | |
| */ | |
| typedef enum | |
| { | |
| MTB_RADAR_SENSING_MASK_NONE = 0, /*!< No events */ | |
| MTB_RADAR_SENSING_MASK_PRESENCE_EVENTS = (1 << 8), /*!< Events for presence detection */ | |
| MTB_RADAR_SENSING_MASK_COUNTER_EVENTS = (2 << 8) /*!< Events for entrance counter */ | |
| } mtb_radar_sensing_mask_t; | |
| /** | |
| * @brief Structure to hold information of RadarSensing event. | |
| * Depending on the event type, it can be cast to \ref mtb_radar_sensing_presence_event_info_t | |
| * or \ref mtb_radar_sensing_counter_event_info_t. | |
| * | |
| */ | |
| typedef struct | |
| { | |
| mtb_radar_sensing_timestamp_t timestamp; /*!< Timestamp of event */ | |
| const char *description; /*!< Description about the event */ | |
| } mtb_radar_sensing_event_info_t; | |
| /** | |
| * @brief Structure to hold information of presence detection events. | |
| * | |
| */ | |
| typedef struct | |
| { | |
| mtb_radar_sensing_timestamp_t timestamp; /*!< Timestamp of event */ | |
| const char *description; /*!< Description about the event */ | |
| float distance; /*!< Distance of object in meters, -1.0f if not applicable (i.e.. for OUT event) */ | |
| float accuracy; /*!< Accuracy of distance of object +- meters, -1.0f if not applicable (i.e. for OUT event) */ | |
| } mtb_radar_sensing_presence_event_info_t; | |
| /** | |
| * @brief Structure to hold information of entrance counter events. | |
| * | |
| */ | |
| typedef struct | |
| { | |
| mtb_radar_sensing_timestamp_t timestamp; /*!< Timestamp of event */ | |
| const char *description; /*!< Description about the event */ | |
| int in_count; /*!< Current in count */ | |
| int out_count; /*!< Current out count */ | |
| } mtb_radar_sensing_counter_event_info_t; | |
| /** | |
| * @brief Structure to hold hw resources. | |
| * | |
| */ | |
| typedef struct | |
| { | |
| cyhal_gpio_t spi_cs; /*!< spi_cs */ | |
| cyhal_gpio_t reset; /*!< reset */ | |
| cyhal_gpio_t ldo_en; /*!< ldo_en */ | |
| cyhal_gpio_t irq; /*!< irq */ | |
| cyhal_spi_t *spi; /*!< spi */ | |
| } mtb_radar_sensing_hw_cfg_t; | |
| /** | |
| * @brief Context object of the radar. The structure must be initialized using \ref mtb_radar_sensing_init. | |
| * It is passed to all other functions in this library. | |
| * Don't modify the context from application code. | |
| */ | |
| typedef struct | |
| { | |
| void *internal; /*!< Internal variable initialized by \ref mtb_radar_sensing_init, do not touch or modify */ | |
| } mtb_radar_sensing_context_t; | |
| /******************************************************************************/ | |
| /** \} \endcond **/ | |
| /******************************************************************************/ | |
| /******************************************************************************/ | |
| /** \addtogroup group_mtb_radar_sensing_high_level */ /** \{ */ | |
| /******************************************************************************/ | |
| /** | |
| * @brief This function allocates a new context of radar. | |
| * | |
| * @param context Context of radar. | |
| * @param hw_cfg HW configuration of radar. | |
| * @param event_mask Type of application events: mtb_radar_sensing_presence_events or mtb_radar_sensing_counter_events. | |
| * @return cy_rslt_t A success or a failure status. | |
| */ | |
| cy_rslt_t mtb_radar_sensing_init(mtb_radar_sensing_context_t *context, | |
| const mtb_radar_sensing_hw_cfg_t *hw_cfg, | |
| mtb_radar_sensing_mask_t event_mask); | |
| /** | |
| * @brief This function sets the memory-managment functions used by the library. | |
| * If your environment provides an alternative to the libc allocator functions, you can set them with function | |
| * @note Must be called before \ref mtb_radar_sensing_init | |
| * @param malloc_func Function pointer to the malloc function implementation. | |
| * @param free_func Function pointer to the free function implementation. | |
| */ | |
| void mtb_radar_sensing_platform_set_malloc_free(void * (*malloc_func)( size_t ), | |
| void (*free_func)( void * ) ); | |
| /** | |
| * @brief This function sets the value for a configuration parameter. | |
| * | |
| * \note It is not thread-safe to make calls to mtb_radar_sensing_set_parameter() while mtb_radar_sensing_process() | |
| * is still active. A workaround in FreeRTOS would be to use each function in a different task and synchronize access | |
| * via a mutex. | |
| * | |
| * Supported keys and values for presence detection: | |
| * <table> | |
| * <tr><th>key <th>default value <th>valid values <th>description | |
| * <tr><td>"radar_presence_range_max"<td>"2.0"<td>0.66 - 10.2 m<td>Maximum detection range. It is the maximum distance | |
| * within which a target is detected. <tr><td>"radar_presence_sensitivity"<td>"medium"<td>"low", "medium", | |
| * "high"<td>Adjusts the threshold values used in macro and micro movement detection. \n High sensitivity would mean | |
| * higher responsiveness towards macro and micro movements. | |
| * </table> | |
| * | |
| * Supported keys and values for entrance counter: | |
| * <table> | |
| * <tr><th>key <th>default value <th>valid values/range <th>description | |
| * <tr><td>"radar_counter_installation"<td>"side"<td>"ceiling", "side"<td>The location of sensor installation. | |
| * <tr><td>"radar_counter_orientation"<td>"portrait"<td>"portrait", "landscape"<td>The orientation of sensor. | |
| * <tr><td>"radar_counter_ceiling_height"<td>"2.5"<td>0.0 - 3.0 m<td>The height at which the sensor is mounted. This | |
| * parameter is only effective for a "ceiling" installation. | |
| * <tr><td>"radar_counter_entrance_width"<td>"1.0"<td>0.0 - 3.0 m<td>The width of the passage or the entrance. | |
| * <tr><td>"radar_counter_sensitivity"<td>"0.5"<td>0.0 - 1.0<td>Sensitivity of counter. | |
| * <tr><td>"radar_counter_traffic_light_zone"<td>"1.0"<td>0.0 - 1.0 m<td>The width of radar field of view that | |
| * represents the detection zone. | |
| * <tr><td>"radar_counter_reverse"<td>"false"<td>"true", "false"<td>Option to reverse directionality of counter. | |
| * <tr><td>"radar_counter_min_person_height"<td>"1.0"<td>0.0 - 2.0 m<td>The minimum height of a person that is | |
| * considered for detection. This is used to filter out pets. | |
| * </table> | |
| * | |
| * @param context Context of radar. | |
| * @param key The type of configuration parameter that is to be set (e.g. "radar_presence_range_max"). | |
| * @param value The value of the configuration parameter that is to be set as character string (e.g. "1.0"). | |
| * @return cy_rslt_t A success or a failure status. | |
| */ | |
| cy_rslt_t mtb_radar_sensing_set_parameter(const mtb_radar_sensing_context_t *context, const char *key, const char *value); | |
| /** | |
| * @brief This function gets the value of a configuration parameter. | |
| * | |
| * @param context Context of radar. | |
| * @param key The type of configuration parameter that is to be read (e.g. "radar_presence_range_max"). | |
| * @param value String buffer where the read value will be written to. | |
| * @param size Size of the string buffer. If size of the string buffer is not large enough a failure status is returned. | |
| * @return cy_rslt_t A success or a failure status. | |
| */ | |
| cy_rslt_t mtb_radar_sensing_get_parameter(const mtb_radar_sensing_context_t *context, const char *key, char *value, size_t size); | |
| /** | |
| * @brief This function processes time domain data acquired from radar. \ref mtb_radar_sensing_enable must be called | |
| * prior to using this function. Must be called periodically from your main loop. | |
| * | |
| * @param context Context of radar. | |
| * @param timestamp System timestamp that will be used to approximate event timestamps in milliseconds. | |
| * @return cy_rslt_t A success or a failure status. | |
| */ | |
| cy_rslt_t mtb_radar_sensing_process(const mtb_radar_sensing_context_t *context, mtb_radar_sensing_timestamp_t timestamp); | |
| /** | |
| * @brief This function enables RadarSensing. | |
| * @param context Context of radar. | |
| * @return cy_rslt_t A success or a failure status. | |
| */ | |
| cy_rslt_t mtb_radar_sensing_enable(const mtb_radar_sensing_context_t *context); | |
| /** | |
| * @brief This function disables RadarSensing. | |
| * @param context Context of radar. | |
| * @return cy_rslt_t A success or a failure status. | |
| */ | |
| cy_rslt_t mtb_radar_sensing_disable(const mtb_radar_sensing_context_t *context); | |
| /** | |
| * @brief This functions frees up resources used by RadarSensing. | |
| * @param context Context of radar. | |
| * @return cy_rslt_t A success or a failure status. | |
| */ | |
| cy_rslt_t mtb_radar_sensing_free(mtb_radar_sensing_context_t *context); | |
| /******************************************************************************/ | |
| /** \} \endcond **/ | |
| /******************************************************************************/ | |
| /******************************************************************************/ | |
| /** \addtogroup group_mtb_radar_sensing_callbacks */ /** \{ */ | |
| /******************************************************************************/ | |
| /** | |
| * @brief Callback function prototype that can be used to handle | |
| * \ref mtb_radar_sensing_event_t events. The callback needs to be registered | |
| * to \ref mtb_radar_sensing_register_callback(). The timestamp indicates the | |
| * start of events and reflects current system time that is passed to | |
| * \ref mtb_radar_sensing_process() | |
| */ | |
| typedef void (*mtb_radar_sensing_callback_t)(mtb_radar_sensing_context_t *context, | |
| mtb_radar_sensing_event_t event, | |
| mtb_radar_sensing_event_info_t *event_info, | |
| void *data); | |
| /** | |
| * @brief This function registers callback for radar service. Callback is invoked | |
| * as soon as an event is detected. | |
| * | |
| * @param context Context of radar. | |
| * @param callback Callback function. | |
| * @param data Data pointer that is passed to the invoke of the event callback. | |
| * @return cy_rslt_t A success or a failure status. | |
| */ | |
| cy_rslt_t mtb_radar_sensing_register_callback(mtb_radar_sensing_context_t *context, | |
| mtb_radar_sensing_callback_t callback, | |
| void *data); | |
| /******************************************************************************/ | |
| /** \} \endcond **/ | |
| /******************************************************************************/ | |
| #ifdef __cplusplus | |
| } | |
| #endif |