acc_config.h
Go to the documentation of this file.
1 // Copyright (c) Acconeer AB, 2020-2024
2 // All rights reserved
3 
4 #ifndef ACC_CONFIG_H_
5 #define ACC_CONFIG_H_
6 
7 #include <stdbool.h>
8 #include <stdint.h>
9 
10 #include "acc_definitions_a121.h"
11 #include "acc_definitions_common.h"
12 
13 
14 /**
15  * @defgroup config Config
16  * @ingroup service
17  *
18  * @brief Module to configure sensor and processing
19  *
20  * @{
21  */
22 
23 
24 struct acc_config;
25 
26 typedef struct acc_config acc_config_t;
27 
28 
29 /**
30  * @brief Create a configuration
31  *
32  * A configuration is created and populated with default values.
33  *
34  * @return A configuration instance
35  */
37 
38 
39 /**
40  * @brief Destroy a configuration freeing any resources allocated
41  *
42  * Destroy a configuration that is no longer needed.
43  *
44  * @param[in] config The configuration to destroy, can be NULL
45  */
46 void acc_config_destroy(acc_config_t *config);
47 
48 
49 /**
50  * @brief Print a configuration to the log
51  *
52  * @param[in] config The configuration to log
53  */
54 void acc_config_log(const acc_config_t *config);
55 
56 
57 /**
58  * @brief Set the starting point of the sweep
59  *
60  * This sets the starting point of the sweep. The corresponding start
61  * in millimeter is approximately start_point * 2.5 mm. For the exact
62  * distance in meter, use the @ref acc_processing_points_to_meter function.
63  *
64  * @param[in] config The configuration
65  * @param[in] start_point The starting point of the sweep
66  */
67 void acc_config_start_point_set(acc_config_t *config, int32_t start_point);
68 
69 
70 /**
71  * @brief Get the starting point of the sweep
72  *
73  * @see acc_config_start_point_set
74  *
75  * @param[in] config The configuration
76  * @return The starting point of the sweep
77  */
78 int32_t acc_config_start_point_get(const acc_config_t *config);
79 
80 
81 /**
82  * @brief Set the number of data points to measure
83  *
84  * This sets the number of data points to measure in a sweep.
85  *
86  * @param[in] config The configuration
87  * @param[in] num_points Number of data points to measure
88  */
89 void acc_config_num_points_set(acc_config_t *config, uint16_t num_points);
90 
91 
92 /**
93  * @brief Get the number of data points to measure
94  *
95  * @see acc_config_num_points_set
96  *
97  * @param[in] config The configuration
98  * @return Number of data points to measure
99  */
100 uint16_t acc_config_num_points_get(const acc_config_t *config);
101 
102 
103 /**
104  * @brief Set the step length in a sweep
105  *
106  * This sets the number of steps to have between each data point.
107  *
108  * Sampling produces complex (IQ) data points with configurable distance spacing,
109  * starting from ~2.5mm.
110  *
111  * The step length has the following constraints:
112  * if step_length <= 24:
113  * 24 % step_length == 0
114  *
115  * if step_length > 24:
116  * step_length % 24 == 0
117  *
118  * This leads to the following valid values:
119  * 1, 2, 3, 4, 6, 8, 12, 24, 48, 72 ...
120  *
121  * @param[in] config The configuration
122  * @param[in] step_length The step length
123  */
124 void acc_config_step_length_set(acc_config_t *config, uint16_t step_length);
125 
126 
127 /**
128  * @brief Get the step length in a sweep
129  *
130  * @see acc_config_step_length_set
131  *
132  * @param[in] config The configuration
133  * @return The step length
134  */
135 uint16_t acc_config_step_length_get(const acc_config_t *config);
136 
137 
138 /**
139  * @brief Set a profile
140  *
141  * Each profile consists of a number of settings for the sensor that configures
142  * the RX and TX paths. Lower profiles have higher depth resolution while
143  * higher profiles have higher SNR.
144  *
145  * @param[in] config The config to set a profile for
146  * @param[in] profile The profile to set
147  */
149  acc_config_profile_t profile);
150 
151 
152 /**
153  * @brief Get the currently used profile
154  *
155  * See @ref acc_config_profile_set
156  *
157  * @param[in] config The config to get a profile for
158  * @return The profile currently used
159  */
161 
162 
163 /**
164  * @brief Set the hardware accelerated average samples (HWAAS)
165  *
166  * Each data point can be sampled several times and the sensor hardware then
167  * produces an average value of those samples. The time needed to measure a sweep is roughly proportional
168  * to the number of averaged samples. Hence, if there is a need to obtain a higher update rate, HWAAS
169  * could be decreased but this leads to lower SNR.
170  *
171  * HWAAS must be between 1 and 511 inclusive
172  *
173  * @param[in] config The config to set HWAAS for
174  * @param[in] hwaas Hardware accelerated average samples
175  */
176 void acc_config_hwaas_set(acc_config_t *config, uint16_t hwaas);
177 
178 
179 /**
180  * @brief Get the hardware accelerated average samples (HWAAS)
181  *
182  * @see acc_config_hwaas_set
183  *
184  * @param[in] config The config to get HWAAS from
185  * @return Hardware accelerated average samples
186  */
187 uint16_t acc_config_hwaas_get(const acc_config_t *config);
188 
189 
190 /**
191  * @brief Set receiver gain setting
192  *
193  * Must be a value between 0 and 23 inclusive where 23 is the highest gain and 0 the lowest.
194  *
195  * Lower gain gives higher SNR. However, too low gain may result in quantization, lowering SNR.
196  * Too high gain may result in saturation, corrupting the data.
197  *
198  * @param[in] config The configuration
199  * @param[in] gain Receiver gain setting
200  */
201 void acc_config_receiver_gain_set(acc_config_t *config, uint8_t gain);
202 
203 
204 /**
205  * @brief Get receiver gain setting
206  *
207  * See @ref acc_config_receiver_gain_set
208  *
209  * @param[in] config The configuration
210  * @return Receiver gain setting
211  */
212 uint8_t acc_config_receiver_gain_get(const acc_config_t *config);
213 
214 
215 /**
216  * @brief Set sweeps per frame
217  *
218  * Sets the number of sweeps that will be captured in each frame (measurement).
219  * Can be set to 0 if e.g. only temperature measurement is wanted.
220  *
221  * @param[in] config The configuration
222  * @param[in] sweeps Sweeps per frame
223  */
224 void acc_config_sweeps_per_frame_set(acc_config_t *config, uint16_t sweeps);
225 
226 
227 /**
228  * @brief Get the number of sweeps per frame
229  *
230  * See @ref acc_config_sweeps_per_frame_set
231  *
232  * @param[in] config The configuration
233  * @return Sweeps per frame
234  */
235 uint16_t acc_config_sweeps_per_frame_get(const acc_config_t *config);
236 
237 
238 /**
239  * @brief Set the sweep rate
240  *
241  * Sets the sweep rate for sweeps in a frame (measurement).
242  *
243  * @param[in] config The configuration
244  * @param[in] sweep_rate Sweep rate in Hz. Must be >= 0, 0 is interpreted as max sweep rate
245  */
246 void acc_config_sweep_rate_set(acc_config_t *config, float sweep_rate);
247 
248 
249 /**
250  * @brief Get the sweep rate
251  *
252  * See @ref acc_config_sweep_rate_set
253  *
254  * @param[in] config The configuration
255  * @return Sweep rate in Hz
256  */
257 float acc_config_sweep_rate_get(const acc_config_t *config);
258 
259 
260 /**
261  * @brief Set continuous sweep mode
262  *
263  * In continuous sweep mode the timing will be identical over all sweeps, not
264  * just the sweeps in a frame.
265  *
266  * Constraints:
267  * - Frame rate must be set to unlimited (0.0)
268  * - Sweep rate must be set (> 0)
269  * - Inter frame idle state must be set equal to inter sweep idle state
270  *
271  * @param[in] config The configuration
272  * @param[in] enabled true if continuous sweep mode should be enabled, false otherwise
273  */
274 void acc_config_continuous_sweep_mode_set(acc_config_t *config, bool enabled);
275 
276 
277 /**
278  * @brief Get continuous sweep mode
279  *
280  * See @ref acc_config_continuous_sweep_mode_set
281  *
282  * @param[in] config The configuration
283  * @return true if continuous sweep mode is enabled, false otherwise
284  */
286 
287 
288 /**
289  * @brief Set the frame rate
290  *
291  * Sets the frame rate.
292  *
293  * Setting the frame rate to unlimited (0) means that the rate is not limited by the
294  * sensor but the rate that the host acknowledge and reads out the measurement data.
295  *
296  * @param[in] config The configuration
297  * @param[in] frame_rate Frame rate in Hz. Must be >= 0, 0 is interpreted as unlimited
298  */
299 void acc_config_frame_rate_set(acc_config_t *config, float frame_rate);
300 
301 
302 /**
303  * @brief Get the frame rate
304  *
305  * See @ref acc_config_frame_rate_set
306  *
307  * @param[in] config The configuration
308  * @return Frame rate
309  */
310 float acc_config_frame_rate_get(const acc_config_t *config);
311 
312 
313 /**
314  * @brief Enable or disable the transmitter
315  *
316  * If set to true, TX is enabled. This will enable the radio transmitter.
317  * By turning the transmitter off the RX noise floor can be measured.
318  *
319  * @param[in] config The configuration
320  * @param[in] enable true to enable the transmitter, false to disable it
321  */
322 void acc_config_enable_tx_set(acc_config_t *config, bool enable);
323 
324 
325 /**
326  * @brief Get transmitter enable configuration
327  *
328  * See @ref acc_config_enable_tx_set
329  *
330  * @param[in] config The configuration
331  * @return true if the transmitter is enabled, false if it is disabled
332  */
333 bool acc_config_enable_tx_get(const acc_config_t *config);
334 
335 
336 /**
337  * @brief Set inter frame idle state
338  *
339  * The 'inter-frame idle state' is the state the sensor idles in between each frame.
340  *
341  * See also @ref acc_config_idle_state_t.
342  *
343  * The inter frame idle state of the frame must be deeper or the same as the inter sweep idle state.
344  *
345  * @param[in] config The configuration
346  * @param[in] idle_state The idle state to use between frames
347  */
349 
350 
351 /**
352  * @brief Get inter frame idle state
353  *
354  * See @ref acc_config_inter_frame_idle_state_set
355  *
356  * @param[in] config The configuration
357  * @return The idle state to use between frames
358  */
360 
361 
362 /**
363  * @brief Set inter sweep idle state
364  *
365  * The 'inter-sweep idle state' is the state the sensor idles in between each sweep in a frame.
366  *
367  * See also @ref acc_config_idle_state_t.
368  *
369  * @param[in] config The configuration
370  * @param[in] idle_state The idle state to use between sweeps within a frame
371  */
373 
374 
375 /**
376  * @brief Get inter sweep idle state
377  *
378  * See @ref acc_config_inter_sweep_idle_state_set
379  *
380  * @param[in] config The configuration
381  * @return The idle state to use between sweeps within a frame
382  */
384 
385 
386 /**
387  * @brief Set Pulse Repetition Frequency
388  *
389  * See @ref acc_config_prf_t for details.
390  *
391  * @param[in] config The configuration
392  * @param[in] prf The Pulse Repetition Frequency to use
393  */
395 
396 
397 /**
398  * @brief Get Pulse Repetition Frequency
399  *
400  * See @ref acc_config_prf_t for details.
401  *
402  * @param[in] config The configuration
403  * @return Pulse Repetition Frequency
404  */
406 
407 
408 /**
409  * @brief Enable or disable phase enhancement
410  *
411  * If enabled, the data phase will be enhanced such that coherent distance filtering can be applied.
412  * Given a single reflection from an object, the phase will appear as "flat" around the amplitude peak.
413  *
414  * Enabling the phase enhancement increases the processing execution time.
415  *
416  * @param[in] config The configuration
417  * @param[in] enable true if phase enhancement should be enabled, false otherwise
418  */
419 void acc_config_phase_enhancement_set(acc_config_t *config, bool enable);
420 
421 
422 /**
423  * @brief Get the phase enhancement configuration
424  *
425  * See @ref acc_config_phase_enhancement_set
426  *
427  * @param[in] config The configuration
428  * @return true if phase enhancement is enabled, false otherwise
429  */
431 
432 
433 /**
434  * @brief Enable or disable loopback
435  *
436  * Constraints:
437  * - Loopback can't be enabled together with profile 2.
438  *
439  * @param[in] config The configuration
440  * @param[in] enable true if loopback should be enabled, false otherwise
441  */
442 void acc_config_enable_loopback_set(acc_config_t *config, bool enable);
443 
444 
445 /**
446  * @brief Get the enable loopback configuration
447  *
448  * See @ref acc_config_enable_loopback_set
449  *
450  * @param[in] config The configuration
451  * @return true if loopback is enabled, false otherwise
452  */
453 bool acc_config_enable_loopback_get(const acc_config_t *config);
454 
455 
456 /**
457  * @brief Enable or disable double buffering
458  *
459  * If enabled, the sensor buffer will be split in two halves reducing the
460  * maximum number of samples. A frame can be read using @ref acc_sensor_read while
461  * sampling is done into the other buffer. Switching of buffers is done automatically
462  * by @ref acc_sensor_measure.
463  *
464  * When using double buffering, measurements coinciding with SPI activity may have distorted phase.
465  * To mitigate this issue, applying a median filter is recommended.
466  *
467  * @param[in] config The configuration
468  * @param[in] enable true if double buffering should be enabled, false otherwise
469  */
470 void acc_config_double_buffering_set(acc_config_t *config, bool enable);
471 
472 
473 /**
474  * @brief Get the double buffering configuration
475  *
476  * See @ref acc_config_double_buffering_set
477  *
478  * @param[in] config The configuration
479  * @return true if double buffering is enabled, false otherwise
480  */
482 
483 
484 /**
485  * @}
486  */
487 
488 
489 #endif
acc_config_start_point_set
void acc_config_start_point_set(acc_config_t *config, int32_t start_point)
Set the starting point of the sweep.
acc_config_inter_frame_idle_state_set
void acc_config_inter_frame_idle_state_set(acc_config_t *config, acc_config_idle_state_t idle_state)
Set inter frame idle state.
acc_config_inter_frame_idle_state_get
acc_config_idle_state_t acc_config_inter_frame_idle_state_get(const acc_config_t *config)
Get inter frame idle state.
acc_config_enable_tx_get
bool acc_config_enable_tx_get(const acc_config_t *config)
Get transmitter enable configuration.
acc_config_prf_get
acc_config_prf_t acc_config_prf_get(const acc_config_t *config)
Get Pulse Repetition Frequency.
acc_config_continuous_sweep_mode_get
bool acc_config_continuous_sweep_mode_get(const acc_config_t *config)
Get continuous sweep mode.
acc_config_profile_set
void acc_config_profile_set(acc_config_t *config, acc_config_profile_t profile)
Set a profile.
acc_config_sweeps_per_frame_set
void acc_config_sweeps_per_frame_set(acc_config_t *config, uint16_t sweeps)
Set sweeps per frame.
acc_config_destroy
void acc_config_destroy(acc_config_t *config)
Destroy a configuration freeing any resources allocated.
acc_config_inter_sweep_idle_state_set
void acc_config_inter_sweep_idle_state_set(acc_config_t *config, acc_config_idle_state_t idle_state)
Set inter sweep idle state.
acc_config_create
acc_config_t * acc_config_create(void)
Create a configuration.
acc_config_hwaas_get
uint16_t acc_config_hwaas_get(const acc_config_t *config)
Get the hardware accelerated average samples (HWAAS)
acc_config_frame_rate_set
void acc_config_frame_rate_set(acc_config_t *config, float frame_rate)
Set the frame rate.
acc_config_start_point_get
int32_t acc_config_start_point_get(const acc_config_t *config)
Get the starting point of the sweep.
acc_config_profile_get
acc_config_profile_t acc_config_profile_get(const acc_config_t *config)
Get the currently used profile.
acc_config_double_buffering_set
void acc_config_double_buffering_set(acc_config_t *config, bool enable)
Enable or disable double buffering.
acc_config_prf_t
acc_config_prf_t
Pulse Repetition Frequency.
Definition: acc_definitions_a121.h:116
acc_config_hwaas_set
void acc_config_hwaas_set(acc_config_t *config, uint16_t hwaas)
Set the hardware accelerated average samples (HWAAS)
acc_config_sweeps_per_frame_get
uint16_t acc_config_sweeps_per_frame_get(const acc_config_t *config)
Get the number of sweeps per frame.
acc_config_t
struct acc_config acc_config_t
Definition: acc_config.h:26
acc_config_frame_rate_get
float acc_config_frame_rate_get(const acc_config_t *config)
Get the frame rate.
acc_config_step_length_get
uint16_t acc_config_step_length_get(const acc_config_t *config)
Get the step length in a sweep.
acc_config_step_length_set
void acc_config_step_length_set(acc_config_t *config, uint16_t step_length)
Set the step length in a sweep.
acc_config_num_points_set
void acc_config_num_points_set(acc_config_t *config, uint16_t num_points)
Set the number of data points to measure.
acc_config_receiver_gain_get
uint8_t acc_config_receiver_gain_get(const acc_config_t *config)
Get receiver gain setting.
acc_config_sweep_rate_set
void acc_config_sweep_rate_set(acc_config_t *config, float sweep_rate)
Set the sweep rate.
acc_config_enable_loopback_get
bool acc_config_enable_loopback_get(const acc_config_t *config)
Get the enable loopback configuration.
acc_config_enable_tx_set
void acc_config_enable_tx_set(acc_config_t *config, bool enable)
Enable or disable the transmitter.
acc_config_phase_enhancement_set
void acc_config_phase_enhancement_set(acc_config_t *config, bool enable)
Enable or disable phase enhancement.
acc_config_continuous_sweep_mode_set
void acc_config_continuous_sweep_mode_set(acc_config_t *config, bool enabled)
Set continuous sweep mode.
acc_config_double_buffering_get
bool acc_config_double_buffering_get(const acc_config_t *config)
Get the double buffering configuration.
acc_config_profile_t
acc_config_profile_t
Profile.
Definition: acc_definitions_a121.h:52
acc_definitions_common.h
acc_config_prf_set
void acc_config_prf_set(acc_config_t *config, acc_config_prf_t prf)
Set Pulse Repetition Frequency.
acc_config_receiver_gain_set
void acc_config_receiver_gain_set(acc_config_t *config, uint8_t gain)
Set receiver gain setting.
acc_config_log
void acc_config_log(const acc_config_t *config)
Print a configuration to the log.
acc_config_phase_enhancement_get
bool acc_config_phase_enhancement_get(const acc_config_t *config)
Get the phase enhancement configuration.
acc_config_sweep_rate_get
float acc_config_sweep_rate_get(const acc_config_t *config)
Get the sweep rate.
acc_config_num_points_get
uint16_t acc_config_num_points_get(const acc_config_t *config)
Get the number of data points to measure.
acc_config_enable_loopback_set
void acc_config_enable_loopback_set(acc_config_t *config, bool enable)
Enable or disable loopback.
acc_config_inter_sweep_idle_state_get
acc_config_idle_state_t acc_config_inter_sweep_idle_state_get(const acc_config_t *config)
Get inter sweep idle state.
acc_definitions_a121.h
acc_config_idle_state_t
acc_config_idle_state_t
Idle state.
Definition: acc_definitions_a121.h:74