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 */
39 uint16_t frame_data_length;
40 /** Number of elements in the sweep */
41 uint16_t sweep_data_length;
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 */
52 float max_sweep_rate;
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 */
64 bool high_speed_mode;
65 } acc_processing_metadata_t;
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 */
76 bool data_saturated;
77 /** Indication of a delayed frame.
78 * The frame rate might need to be lowered if this indication is set.
79 */
80 bool frame_delayed;
81 /** Indication of calibration needed
82 * The sensor calibration needs to be redone if this indication is set.
83 */
84 bool calibration_needed;
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 */
91 acc_int16_complex_t *frame;
92 } acc_processing_result_t;
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 */
102 acc_processing_t *acc_processing_create(const acc_config_t *config, acc_processing_metadata_t *processing_metadata);
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 */
123 void acc_processing_destroy(acc_processing_t *handle);
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
buffer
void * buffer
Definition: i2c_example_cargo.c:40
acc_int16_complex_t
Data type for interger-based representation of complex numbers.
Definition: acc_definitions_common.h:40
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.
config
cargo_config_t config
Definition: i2c_example_cargo.c:34
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:25
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
handle
cargo_handle_t * handle
Definition: i2c_example_cargo.c:35
acc_processing_metadata_t::frame_data_length
uint16_t frame_data_length
Definition: acc_processing.h:39
result
cargo_result_t result
Definition: i2c_example_cargo.c:43
acc_config_t
struct acc_config acc_config_t
Definition: acc_config.h:24
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:49
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