acc_processing.h
Go to the documentation of this file.
1 // Copyright (c) Acconeer AB, 2020-2024
2 // All rights reserved
3 
4 #ifndef ACC_PROCESSING_H_
5 #define ACC_PROCESSING_H_
6 
7 #include <stdbool.h>
8 #include <stdint.h>
9 
10 #include "acc_config_subsweep.h"
11 #include "acc_definitions_a121.h"
12 #include "acc_definitions_common.h"
13 
14 
15 /**
16  * @defgroup processing Processing
17  * @ingroup service
18  *
19  * @brief Module to interpret and process data read from sensor
20  *
21  * @{
22  */
23 
24 
25 /**
26  * @brief Generic processing handle
27  */
28 struct acc_processing_handle;
29 
30 typedef struct acc_processing_handle acc_processing_t;
31 
32 
33 /**
34  * @brief Metadata that will be populated by the processing module during creation
35  */
36 typedef struct
37 {
38  /** Number of elements in the frame */
40  /** Number of elements in the sweep */
42  /** Offset to the subsweeps data */
43  uint16_t subsweep_data_offset[ACC_MAX_NUM_SUBSWEEPS];
44  /** Number of elements in the subsweeps */
45  uint16_t subsweep_data_length[ACC_MAX_NUM_SUBSWEEPS];
46  /** Maximum sweep rate that the sensor can provide for the given configuration.
47  * Note that this is not the actual exact sweep rate. To obtain an exact rate,
48  * use the sweep rate parameter, @ref acc_config_sweep_rate_set.
49  *
50  * If no max sweep rate is applicable, it's set to 0.0f.
51  */
53  /** Flag indicating if high speed mode is used.
54  * If true, it means that the sensor has been configured in a way where it
55  * can optimize its measurements and obtain a high max_sweep_rate.
56  *
57  * Configuration limitations to enable high speed mode:
58  *
59  * continuous_sweep_mode false, see @ref acc_config_continuous_sweep_mode_set
60  * inter_sweep_idle_state READY, see @ref acc_config_inter_sweep_idle_state_set
61  * num_subsweeps 1, see @ref acc_config_num_subsweeps_set
62  * profile 3-5, see @ref acc_config_profile_set
63  */
66 
67 
68 /**
69  * @brief Result provided by the processing module
70  */
71 typedef struct
72 {
73  /** Indication of sensor data being saturated, can cause data corruption.
74  * Lower the receiver gain if this indication is set.
75  */
77  /** Indication of a delayed frame.
78  * The frame rate might need to be lowered if this indication is set.
79  */
81  /** Indication of calibration needed
82  * The sensor calibration needs to be redone if this indication is set.
83  */
85  /** Temperature in sensor during measurement (in degree Celsius).
86  * Note that it has poor absolute accuracy and should only be used
87  * for relative temperature measurements.
88  */
89  int16_t temperature;
90  /** Pointer to the frame data */
93 
94 
95 /**
96  * @brief Create a processing instance with the provided configuration
97  *
98  * @param[in] config The configuration to create a processing instance with
99  * @param[out] processing_metadata The metadata of the created processing instance
100  * @return Processing handle, NULL if processing instance was not possible to create
101  */
103 
104 
105 /**
106  * @brief Process the data according to the configuration used in create
107  *
108  * @param[in] handle A reference to the processing handle
109  * @param[in] buffer A reference to the buffer (populated by @ref acc_sensor_read) containing the
110  * data to be processed.
111  *
112  * @param[out] result Processing result
113  */
114 void acc_processing_execute(acc_processing_t *handle, void *buffer,
115  acc_processing_result_t *result);
116 
117 
118 /**
119  * @brief Destroy a processing instance identified with the provided processing handle
120  *
121  * @param[in] handle A reference to the processing handle to destroy, can be NULL
122  */
124 
125 
126 /**
127  * @brief Convert a distance or step length in points to meter
128  *
129  * Does not include any zero-point offset since it is highly integration dependant. In other words,
130  * calling this function with a 0 always returns 0.0.
131  *
132  * @param[in] points Number of points to convert to meter
133  * @return The corresponding length in meters
134  */
135 float acc_processing_points_to_meter(int32_t points);
136 
137 
138 /**
139  * @brief Convert a distance or step length in meter to points
140  *
141  * Does not include any zero-point offset since it is highly integration dependant. In other words,
142  * calling this function with a 0.0 always returns 0.
143  *
144  * @param[in] length Length in meter to convert to points
145  * @return The corresponding length in points
146  */
147 int32_t acc_processing_meter_to_points(float length);
148 
149 
150 /**
151  * @brief Calculate temperature compensation for mean sweep and background noise
152  * (tx off) standard deviation
153  *
154  * The signal adjustment models how the amplitude level fluctuates with temperature.
155  * If the same object is measured against while the temperature changes,
156  * the amplitude level should be multiplied with this factor.
157  *
158  * Example of usage:
159  * int16_t reference_temperature (recorded temperature during calibration)
160  * float reference_amplitude (recorded amplitude during calibration)
161  *
162  * int16_t current_temperature (temperature at current measurement time)
163  *
164  * float signal_adjust_factor
165  * float deviation_adjust_factor
166  *
167  * acc_processing_get_temperature_adjustment_factors(reference_temperature, current_temperature, profile,
168  * &signal_adjust_factor, &deviation_adjust_factor)
169  *
170  * reference_amplitude_new = reference_amplitude * signal_adjust_factor
171  *
172  * The reference_amplitude_new is an approximation of what the calibrated amplitude
173  * would be at the new temperature.
174  *
175  * Eg. When the temperature falls 60 degrees, the amplitude (roughly) doubles.
176  * This yields a signal_adjust_factor of (about) 2.
177  *
178  * The signal adjustment model follows 2 ^ -(temperature_diff / model_parameter), where
179  * model_parameter reflects the temperature difference relative the reference temperature,
180  * required for the amplitude to double/halve.
181  *
182  * The deviation_adjust_factor works the same way, but is applied to a measurement
183  * taken with the Tx off. So instead of a measurement of amplitude, we have a measurement of tx_off.
184  * The procedure for calculating this is to take the same configuration as
185  * the application will use, but turning off the Tx.
186  * This calibration value is multiplied with the deviation_adjust_factor.
187  *
188  * @param[in] reference_temperature The reference temperature, usually taken at calibration
189  * @param[in] current_temperature The current temperature
190  * @param[in] profile Configured profile
191  * @param[out] signal_adjust_factor The calculated signal adjustment factor
192  * @param[out] deviation_adjust_factor The calculated deviation adjustment factor
193  */
194 void acc_processing_get_temperature_adjustment_factors(int16_t reference_temperature, int16_t current_temperature, acc_config_profile_t profile,
195  float *signal_adjust_factor, float *deviation_adjust_factor);
196 
197 
198 /**
199  * @}
200  */
201 
202 
203 #endif
acc_processing_destroy
void acc_processing_destroy(acc_processing_t *handle)
Destroy a processing instance identified with the provided processing handle.
acc_processing_result_t
Result provided by the processing module.
Definition: acc_processing.h:71
acc_int16_complex_t
Data type for interger-based representation of complex numbers.
Definition: acc_definitions_common.h:43
acc_processing_execute
void acc_processing_execute(acc_processing_t *handle, void *buffer, acc_processing_result_t *result)
Process the data according to the configuration used in create.
acc_config_subsweep.h
acc_processing_get_temperature_adjustment_factors
void acc_processing_get_temperature_adjustment_factors(int16_t reference_temperature, int16_t current_temperature, acc_config_profile_t profile, float *signal_adjust_factor, float *deviation_adjust_factor)
Calculate temperature compensation for mean sweep and background noise (tx off) standard deviation.
acc_processing_metadata_t
Metadata that will be populated by the processing module during creation.
Definition: acc_processing.h:36
acc_processing_meter_to_points
int32_t acc_processing_meter_to_points(float length)
Convert a distance or step length in meter to points.
ACC_MAX_NUM_SUBSWEEPS
#define ACC_MAX_NUM_SUBSWEEPS
The maximum number of subsweeps in a configuration.
Definition: acc_definitions_a121.h:27
acc_processing_metadata_t::sweep_data_length
uint16_t sweep_data_length
Definition: acc_processing.h:41
acc_processing_metadata_t::high_speed_mode
bool high_speed_mode
Definition: acc_processing.h:64
acc_processing_metadata_t::frame_data_length
uint16_t frame_data_length
Definition: acc_processing.h:39
acc_config_t
struct acc_config acc_config_t
Definition: acc_config.h:26
acc_processing_points_to_meter
float acc_processing_points_to_meter(int32_t points)
Convert a distance or step length in points to meter.
acc_processing_result_t::frame_delayed
bool frame_delayed
Definition: acc_processing.h:80
acc_processing_result_t::frame
acc_int16_complex_t * frame
Definition: acc_processing.h:91
acc_processing_t
struct acc_processing_handle acc_processing_t
Definition: acc_processing.h:30
acc_config_profile_t
acc_config_profile_t
Profile.
Definition: acc_definitions_a121.h:52
acc_definitions_common.h
acc_processing_result_t::temperature
int16_t temperature
Definition: acc_processing.h:89
acc_processing_result_t::data_saturated
bool data_saturated
Definition: acc_processing.h:76
acc_processing_result_t::calibration_needed
bool calibration_needed
Definition: acc_processing.h:84
acc_processing_metadata_t::max_sweep_rate
float max_sweep_rate
Definition: acc_processing.h:52
acc_processing_create
acc_processing_t * acc_processing_create(const acc_config_t *config, acc_processing_metadata_t *processing_metadata)
Create a processing instance with the provided configuration.
acc_definitions_a121.h