// Copyright (c) Acconeer AB, 2019-2022
// All rights reserved
#ifndef ACC_DETECTOR_PRESENCE_H_
#define ACC_DETECTOR_PRESENCE_H_
#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
#include "acc_definitions_a111.h"
#include "acc_definitions_common.h"
/**
* @defgroup Presence Presence Detector
* @ingroup Detectors
*
* @brief Presence detector API description
*
* @{
*/
/**
* @brief Presence detector handle
*/
struct acc_detector_presence_handle;
typedef struct acc_detector_presence_handle *acc_detector_presence_handle_t;
/**
* @brief Presence detector configuration container
*/
struct acc_detector_presence_configuration;
typedef struct acc_detector_presence_configuration *acc_detector_presence_configuration_t;
/**
* @brief Parameter structure for data filtering settings
*/
typedef struct
{
/** Time constant in s for inter-frame signal smoothing after the bandpass filtering */
float inter_frame_deviation_time_const;
/** Low pass cutoff frequency in Hz for inter-frame signal bandpass filtering */
float inter_frame_fast_cutoff;
/** High pass cutoff frequency in Hz for inter-frame signal bandpass filtering */
float inter_frame_slow_cutoff;
/** Time constant in s for inter-frame signal smoothing */
float intra_frame_time_const;
/** Weight between 0 and 1 for presence score interpolation between the inter-frame and intra-frame signals */
float intra_frame_weight;
/** Time constant in s for smoothing of the presence score */
float output_time_const;
} acc_detector_presence_configuration_filter_parameters_t;
/**
* @brief Presence detector results container
*/
typedef struct
{
/** True if presence was detected, False otherwise */
bool presence_detected;
/** A measure of the amount of motion detected */
float presence_score;
/** The distance, in meters, to the detected object */
float presence_distance;
/** Indication of a sensor communication error, detector probably needs to be restarted */
bool sensor_communication_error;
/** Indication of sensor data being saturated, can cause result instability */
bool data_saturated;
} acc_detector_presence_result_t;
/**
* @brief A callback for retrieving the service data buffer that the detector is based on
*
* @param[in] data A pointer to the buffer with sparse data
* @param[in] data_size Size of the data buffer in bytes
* @param[in] client_reference Pointer to a client reference
*/
typedef void (*acc_detector_presence_service_data_callback_t)(const uint16_t *data, size_t data_size, void *client_reference);
/**
* @brief Create a configuration for a presence detector
*
* @return Presence detector configuration, NULL if creation was not possible
*/
acc_detector_presence_configuration_t acc_detector_presence_configuration_create(void);
/**
* @brief Destroy a presence detector configuration
*
* @param[in] presence_configuration The configuration to destroy, set to NULL
*/
void acc_detector_presence_configuration_destroy(acc_detector_presence_configuration_t *presence_configuration);
/**
* @brief Create a presence detector with the provided configuration
*
* Only one presence detector may exist for a specific sensor at any given time and
* invalid configurations will not allow for presence detector creation.
*
* @param[in] presence_configuration The presence detector configuration to create a presence detector with
* @return Presence detector handle, NULL if presence detector was not possible to create
*/
acc_detector_presence_handle_t acc_detector_presence_create(acc_detector_presence_configuration_t presence_configuration);
/**
* @brief Destroy a presence detector identified with the provided handle
*
* Destroy the context of a presence detector allowing another presence detector to be created using the
* same resources. The presence detector handle reference is set to NULL after destruction.
* If NULL is sent in, nothing happens.
*
* @param[in] presence_handle A reference to the presence detector handle to destroy
*/
void acc_detector_presence_destroy(acc_detector_presence_handle_t *presence_handle);
/**
* @brief Reconfigure a presence detector with the provided configuration
*
* Only one presence detector may exist for a specific sensor at any given time and
* invalid reconfigurations will not allow for presence detector creation.
*
* @param[in] presence_handle A reference to the presence detector handle to reconfigure
* @param[in] presence_configuration The presence detector configuration to reconfigure a presence detector with
* @return True if possible to reconfigure
*/
bool acc_detector_presence_reconfigure(acc_detector_presence_handle_t *presence_handle,
acc_detector_presence_configuration_t presence_configuration);
/**
* @brief Activate the presence detector associated with the provided handle
*
* @param[in] presence_handle The presence detector handle for the presence detector to activate
* @return True if successful, otherwise false
*/
bool acc_detector_presence_activate(acc_detector_presence_handle_t presence_handle);
/**
* @brief Deactivate the presence detector associated with the provided handle
*
* @param[in] presence_handle The presence detector handle for the presence detector to deactivate
* @return True if successful, otherwise false
*/
bool acc_detector_presence_deactivate(acc_detector_presence_handle_t presence_handle);
/**
* @brief Retrieve the next result from the presence detector
*
* May only be called after a presence detector has been activated, blocks
* the application until a result is ready. Can still be called after vector
* output mode has been selected.
*
* @param[in] presence_handle The presence detector handle for the presence detector to get the next result for
* @param[out] result Presence detector results, can be NULL if no result is wanted.
* @return True if successful, otherwise false
*/
bool acc_detector_presence_get_next(acc_detector_presence_handle_t presence_handle, acc_detector_presence_result_t *result);
/**
* @brief Retrieve the next distance point vector from the presence detector
*
* May only be called after a presence detector has been activated, blocks
* the application until a result is ready. Vector output mode has to be set
* to true with the function @ref acc_detector_presence_configuration_vector_output_mode_set,
* otherwise returns with an error. Memory is owned by the detector and the client receives a pointer.
*
* @param[in] presence_handle The presence detector handle for the presence detector to get the next result for
* @param[out] distance_point_vector_length The number of elements in the distance_point_vector, can be NULL if no result is wanted
* @param[out] distance_point_vector The distance point vector, can be NULL if no result is wanted
* @param[out] result Presence detector results, same as result from acc_detector_presence_get_next
* @return True if successful, otherwise false
*/
bool acc_detector_presence_distance_point_vector_get_next(acc_detector_presence_handle_t presence_handle,
uint16_t *distance_point_vector_length,
float **distance_point_vector,
acc_detector_presence_result_t *result);
/**
* @brief Get start of sweep in m
*
* @param[in] configuration The configuration to get the sweep start for
* @return requested sweep start in m
*/
float acc_detector_presence_configuration_start_get(acc_detector_presence_configuration_t configuration);
/**
* @brief Set start of sweep in m
*
* @param[in] configuration The configuration to set the sweep start for
* @param[in] start The requested sweep start in m
*/
void acc_detector_presence_configuration_start_set(acc_detector_presence_configuration_t configuration, float start);
/**
* @brief Get length of sweep in m
*
* @param[in] configuration The configuration to get the sweep length for
* @return requested sweep length in m
*/
float acc_detector_presence_configuration_length_get(acc_detector_presence_configuration_t configuration);
/**
* @brief Set length of sweep in m
*
* @param[in] configuration The configuration to set the requested sweep length for
* @param[in] length The requested sweep length in m
*/
void acc_detector_presence_configuration_length_set(acc_detector_presence_configuration_t configuration, float length);
/**
* @brief Get sensor ID
*
* @param[in] configuration The configuration to get the sensor ID for
* @return sensor ID
*/
acc_sensor_id_t acc_detector_presence_configuration_sensor_get(acc_detector_presence_configuration_t configuration);
/**
* @brief Set sensor ID
*
* @param[in] configuration The configuration to set the sensor ID for
* @param[in] sensor_id The sensor ID
*/
void acc_detector_presence_configuration_sensor_set(acc_detector_presence_configuration_t configuration, acc_sensor_id_t sensor_id);
/**
* @brief Get detection threshold
*
* @param[in] configuration The configuration to get the detection threshold for
* @return detection threshold
*/
float acc_detector_presence_configuration_detection_threshold_get(acc_detector_presence_configuration_t configuration);
/**
* @brief Set detection threshold
*
* @param[in] configuration The configuration to set the detection threshold for
* @param[in] detection_threshold The threshold
*/
void acc_detector_presence_configuration_detection_threshold_set(acc_detector_presence_configuration_t configuration,
float detection_threshold);
/**
* @brief Get detection update rate
*
* Set the update rate of which the client call the detector to produce data. It's the clients responsibility
* to keep the configured timing.
*
* @param[in] configuration The configuration to get the detection update rate for
* @return detection update rate
*/
float acc_detector_presence_configuration_update_rate_get(acc_detector_presence_configuration_t configuration);
/**
* @brief Set detection update rate
*
* Set the update rate of which the client call the detector to produce data. It's the clients responsibility
* to keep the configured timing.
*
* @param[in] configuration The configuration to set the detection update rate for
* @param[in] update_rate
*/
void acc_detector_presence_configuration_update_rate_set(acc_detector_presence_configuration_t configuration,
float update_rate);
/**
* @brief Get the number of sweeps per frame
*
* @param[in] configuration The configuration to get the number of sweeps per frame for
* @return The number of sweeps per frame
*/
uint16_t acc_detector_presence_configuration_sweeps_per_frame_get(acc_detector_presence_configuration_t configuration);
/**
* @brief Set the number of sweeps per frame
*
* @param[in] configuration The configuration to set the number of sweeps per frame for
* @param[in] sweeps_per_frame The requested number of sweeps per frame
*/
void acc_detector_presence_configuration_sweeps_per_frame_set(acc_detector_presence_configuration_t configuration,
uint16_t sweeps_per_frame);
/**
* @brief Get the sweep rate
*
* Gets the requested sweep rate. Values of zero of lower are treated as the maximum possible rate.
*
* @param[in] configuration The configuration to get the sweep rate from
* @return sweep_rate The sweep rate
*/
float acc_detector_presence_configuration_sweep_rate_get(acc_detector_presence_configuration_t configuration);
/**
* @brief Set sweep rate
*
* Sets the requested sweep rate. Values of zero of lower are treated as the maximum possible rate.
*
* @param[in] configuration The configuration to set the sweep rate in
* @param[in] sweep_rate The sweep rate
*/
void acc_detector_presence_configuration_sweep_rate_set(acc_detector_presence_configuration_t configuration, float sweep_rate);
/**
* @brief Get sensor data filtering parameters
*
* See @ref acc_detector_presence_configuration_filter_parameters_set
*
* @param[in] configuration The configuration to get the filter parameters for
* @return The filter parameters, see @ref acc_detector_presence_configuration_filter_parameters_t
*/
acc_detector_presence_configuration_filter_parameters_t acc_detector_presence_configuration_filter_parameters_get(
acc_detector_presence_configuration_t configuration);
/**
* @brief Set sensor data filtering parameters
*
* Set filter parameters for the sensor data filtering that is performed before presence detection thresholding.
*
* @param[in] configuration The configuration to set the filter parameters for
* @param[in] filter_parameters The filter parameter structure, see @ref acc_detector_presence_configuration_filter_parameters_t
*/
void acc_detector_presence_configuration_filter_parameters_set(acc_detector_presence_configuration_t configuration,
const acc_detector_presence_configuration_filter_parameters_t *filter_parameters);
/**
* @brief Get the number of principal components removed in the PCA based noise reduction
*
* @param[in] configuration The configuration to get the number of principal components of noise to remove for
* @return The number of principal components of noise to remove, between 0 and 2
*/
uint8_t acc_detector_presence_configuration_nbr_removed_pc_get(acc_detector_presence_configuration_t configuration);
/**
* @brief Set the number of principal components removed in the PCA based noise reduction
*
* Sets the number of principal components removed in the PCA based noise reduction.
* Filters out static reflections.
* Setting to 0 (default) disables the PCA based noise reduction completely.
* For more information on the PCA based noise reduction algorithm, see
* <a href="https://acconeer-python-exploration.readthedocs.io/en/latest/processing/
* presence_detection_sparse.html#pca-based-noise-reduction">Read-the-Docs</a>
*
* @param[in] configuration The configuration to set the number of principal components of noise to remove for
* @param[in] nbr_removed_pc The number of principal components of noise to remove, between 0 and 2
*/
void acc_detector_presence_configuration_nbr_removed_pc_set(acc_detector_presence_configuration_t configuration, uint8_t nbr_removed_pc);
/**
* @brief Get power save mode
*
* @param[in] configuration The configuration to get the power save mode for
* @return power save mode
*/
acc_power_save_mode_t acc_detector_presence_configuration_power_save_mode_get(
acc_detector_presence_configuration_t configuration);
/**
* @brief Set power save mode
*
* @param[in] configuration The configuration to set the power save mode for
* @param[in] power_save_mode The power save mode
*/
void acc_detector_presence_configuration_power_save_mode_set(acc_detector_presence_configuration_t configuration,
acc_power_save_mode_t power_save_mode);
/**
* @brief Get the current service profile used by the detector
*
* See @ref acc_service_profile_t for details
*
* @param[in] configuration The configuration to get a profile from
* @return The current profile, 0 if configuration is invalid
*/
acc_service_profile_t acc_detector_presence_configuration_service_profile_get(
acc_detector_presence_configuration_t configuration);
/**
* @brief Set a service profile to be used by the detector
*
* See @ref acc_service_profile_t for details
*
* @param[in] configuration The configuration to set a profile for
* @param[in] service_profile The profile to set
*/
void acc_detector_presence_configuration_service_profile_set(acc_detector_presence_configuration_t configuration,
acc_service_profile_t service_profile);
/**
* @brief Get the current receiver gain used by the detector
*
* @param[in] configuration The configuration to get gain from
* @return The current gain
*/
float acc_detector_presence_configuration_receiver_gain_get(acc_detector_presence_configuration_t configuration);
/**
* @brief Set a receiver gain to be used by the detector
*
* @param[in] configuration The configuration to set gain for
* @param[in] gain The gain to set
*/
void acc_detector_presence_configuration_receiver_gain_set(acc_detector_presence_configuration_t configuration,
float gain);
/**
* @brief Get the sensor downsampling factor
*
* Gets the downsampling factor - the number of steps taken between each data point. A downsampling factor of 1 samples
* every possible point in the range. A downsampling factor of 2 samples every other point, and so on.
*
* In the sparse service, the base step length is ~6cm. Thus, for example setting downsampling factor to 3 makes
* the distance between two points in the measured range ~18cm.
*
* @param[in] configuration The configuration to get downsampling factor from
* @return The downsampling factor
*/
uint16_t acc_detector_presence_configuration_downsampling_factor_get(acc_detector_presence_configuration_t configuration);
/**
* @brief Set the sensor downsampling factor
*
* Sets the downsampling factor - the number of steps taken between each data point. A downsampling factor of 1 samples
* every possible point in the range. A downsampling factor of 2 samples every other point, and so on.
*
* In the sparse service, the base step length is ~6cm. Thus, for example setting downsampling factor to 3 makes
* the distance between two points in the measured range ~18cm.
*
* The sparse service supports setting an arbitrary downsampling factor of at least 1.
*
* @param[in] configuration The configuration to set downsampling factor in
* @param[in] downsampling_factor The downsampling factor
*/
void acc_detector_presence_configuration_downsampling_factor_set(acc_detector_presence_configuration_t configuration, uint16_t downsampling_factor);
/**
* @brief Get the hardware accelerated average samples
*
* Each data point can be sampled between 1 and 63 times, inclusive, and the sensor hardware then
* produces an average value of those samples. The time needed to measure a sweep is roughly proportional
* to the number of averaged samples. Hence, if there is a need to obtain a higher update rate, HWAAS
* could be decreased but this leads to lower SNR.
*
* @param[in] configuration The configuration to get hardware accelerated average samples from
* @return Hardware accelerated average samples
*/
uint8_t acc_detector_presence_configuration_hw_accelerated_average_samples_get(acc_detector_presence_configuration_t configuration);
/**
* @brief Set the hardware accelerated average samples
*
* Each data point can be sampled between 1 and 63 times, inclusive, and the sensor hardware then
* produces an average value of those samples. The time needed to measure a sweep is roughly proportional
* to the number of averaged samples. Hence, if there is a need to obtain a higher update rate, HWAAS
* could be decreased but this leads to lower SNR.
*
* @param[in] configuration The configuration to set hardware accelerated average samples in
* @param[in] samples Hardware accelerated average samples
*/
void acc_detector_presence_configuration_hw_accelerated_average_samples_set(acc_detector_presence_configuration_t configuration, uint8_t samples);
/**
* @brief Get asynchronous measurement mode
*
* If set to true, asynchronous measurement is enabled.
* In synchronous mode the sensor will measure while the host is waiting.
* In asynchronous mode the sensor will measure while the host is working.
*
* This means that if in synchronous mode, the sensor will only measure during
* a get_next call, while in asynchronous mode the sensor can measure outside
* of the get_next call.
*
* @param[in] configuration The configuration to get asynchronous_measurement mode from
* @return Asynchronous measurement mode
*/
bool acc_detector_presence_configuration_asynchronous_measurement_get(acc_detector_presence_configuration_t configuration);
/**
* @brief Set asynchronous measurement mode
*
* If set to true, asynchronous measurement is enabled.
* In synchronous mode the sensor will measure while the host is waiting.
* In asynchronous mode the sensor will measure while the host is working.
*
* This means that if in synchronous mode, the sensor will only measure during
* a get_next call, while in asynchronous mode the sensor can measure outside
* of the get_next call.
*
* @param[in] configuration The configuration to set asynchronous_measurement mode in
* @param[in] asynchronous_measurement asynchronous measurement mode, true or false
*/
void acc_detector_presence_configuration_asynchronous_measurement_set(acc_detector_presence_configuration_t configuration,
bool asynchronous_measurement);
/**
* @brief Gets vector output mode
*
* vector_output_mode decides whether or not the presence detector should output a distance point vector
* from the function @ref acc_detector_presence_distance_point_vector_get_next.
*
* @param[in] configuration The configuration to get vector_output_mode from
* @return vector_output_mode
*/
bool acc_detector_presence_configuration_vector_output_mode_get(acc_detector_presence_configuration_t configuration);
/**
* @brief Sets vector output mode
*
* vector_output_mode decides whether or not the presence detector should output a distance point vector.
*
* @param[in] configuration The configuration to set vector_output_mode in
* @param[in] vector_output_mode The vector_output_mode
*/
void acc_detector_presence_configuration_vector_output_mode_set(acc_detector_presence_configuration_t configuration, bool vector_output_mode);
/**
* @brief Set a callback function to get the service data
*
* A callback can be used to get the sparse service buffer. The data is the sparse data that is fed into the presence algorithm
*
* @param[in] configuration The configuration to set vector_output_mode in
* @param[in] service_data_callback The callback to get service data
* @param[in] client_reference Pointer to a client reference
*/
void acc_detector_presence_configuration_set_service_data_callback(acc_detector_presence_configuration_t configuration,
acc_detector_presence_service_data_callback_t service_data_callback,
void *client_reference);
/**
* @}
*/
#endif