acc_config.h
Go to the documentation of this file.
1 // Copyright (c) Acconeer AB, 2020-2023
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  * @param[in] config The configuration
112  * @param[in] step_length The step length
113  */
114 void acc_config_step_length_set(acc_config_t *config, uint16_t step_length);
115 
116 
117 /**
118  * @brief Get the step length in a sweep
119  *
120  * @see acc_config_step_length_set
121  *
122  * @param[in] config The configuration
123  * @return The step length
124  */
125 uint16_t acc_config_step_length_get(const acc_config_t *config);
126 
127 
128 /**
129  * @brief Set a profile
130  *
131  * Each profile consists of a number of settings for the sensor that configures
132  * the RX and TX paths. Lower profiles have higher depth resolution while
133  * higher profiles have higher SNR.
134  *
135  * @param[in] config The config to set a profile for
136  * @param[in] profile The profile to set
137  */
139  acc_config_profile_t profile);
140 
141 
142 /**
143  * @brief Get the currently used profile
144  *
145  * See @ref acc_config_profile_set
146  *
147  * @param[in] config The config to get a profile for
148  * @return The profile currently used
149  */
151 
152 
153 /**
154  * @brief Set the hardware accelerated average samples (HWAAS)
155  *
156  * Each data point can be sampled several times and the sensor hardware then
157  * produces an average value of those samples. The time needed to measure a sweep is roughly proportional
158  * to the number of averaged samples. Hence, if there is a need to obtain a higher update rate, HWAAS
159  * could be decreased but this leads to lower SNR.
160  *
161  * HWAAS must be between 1 and 511 inclusive
162  *
163  * @param[in] config The config to set HWAAS for
164  * @param[in] hwaas Hardware accelerated average samples
165  */
166 void acc_config_hwaas_set(acc_config_t *config, uint16_t hwaas);
167 
168 
169 /**
170  * @brief Get the hardware accelerated average samples (HWAAS)
171  *
172  * @see acc_config_hwaas_set
173  *
174  * @param[in] config The config to get HWAAS from
175  * @return Hardware accelerated average samples
176  */
177 uint16_t acc_config_hwaas_get(const acc_config_t *config);
178 
179 
180 /**
181  * @brief Set receiver gain setting
182  *
183  * Must be a value between 0 and 23 inclusive where 23 is the highest gain and 0 the lowest.
184  *
185  * Lower gain gives higher SNR. However, too low gain may result in quantization, lowering SNR.
186  * Too high gain may result in saturation, corrupting the data.
187  *
188  * @param[in] config The configuration
189  * @param[in] gain Receiver gain setting
190  */
191 void acc_config_receiver_gain_set(acc_config_t *config, uint8_t gain);
192 
193 
194 /**
195  * @brief Get receiver gain setting
196  *
197  * See @ref acc_config_receiver_gain_set
198  *
199  * @param[in] config The configuration
200  * @return Receiver gain setting
201  */
202 uint8_t acc_config_receiver_gain_get(const acc_config_t *config);
203 
204 
205 /**
206  * @brief Set sweeps per frame
207  *
208  * Sets the number of sweeps that will be captured in each frame (measurement).
209  * Can be set to 0 if e.g. only temperature measurement is wanted.
210  *
211  * @param[in] config The configuration
212  * @param[in] sweeps Sweeps per frame
213  */
214 void acc_config_sweeps_per_frame_set(acc_config_t *config, uint16_t sweeps);
215 
216 
217 /**
218  * @brief Get the number of sweeps per frame
219  *
220  * See @ref acc_config_sweeps_per_frame_set
221  *
222  * @param[in] config The configuration
223  * @return Sweeps per frame
224  */
225 uint16_t acc_config_sweeps_per_frame_get(const acc_config_t *config);
226 
227 
228 /**
229  * @brief Set the sweep rate
230  *
231  * Sets the sweep rate for sweeps in a frame (measurement).
232  *
233  * @param[in] config The configuration
234  * @param[in] sweep_rate Sweep rate in Hz. Must be >= 0, 0 is interpreted as max sweep rate
235  */
236 void acc_config_sweep_rate_set(acc_config_t *config, float sweep_rate);
237 
238 
239 /**
240  * @brief Get the sweep rate
241  *
242  * See @ref acc_config_sweep_rate_set
243  *
244  * @param[in] config The configuration
245  * @return Sweep rate in Hz
246  */
247 float acc_config_sweep_rate_get(const acc_config_t *config);
248 
249 
250 /**
251  * @brief Set continuous sweep mode
252  *
253  * In continuous sweep mode the timing will be identical over all sweeps, not
254  * just the sweeps in a frame.
255  *
256  * Constraints:
257  * - Frame rate must be set to unlimited (0.0)
258  * - Sweep rate must be set (> 0)
259  * - Inter frame idle state must be set equal to inter sweep idle state
260  *
261  * @param[in] config The configuration
262  * @param[in] enabled true if continuous sweep mode should be enabled, false otherwise
263  */
264 void acc_config_continuous_sweep_mode_set(acc_config_t *config, bool enabled);
265 
266 
267 /**
268  * @brief Get continuous sweep mode
269  *
270  * See @ref acc_config_continuous_sweep_mode_set
271  *
272  * @param[in] config The configuration
273  * @return true if continuous sweep mode is enabled, false otherwise
274  */
276 
277 
278 /**
279  * @brief Set the frame rate
280  *
281  * Sets the frame rate.
282  *
283  * Setting the frame rate to unlimited (0) means that the rate is not limited by the
284  * sensor but the rate that the host acknowledge and reads out the measurement data.
285  *
286  * @param[in] config The configuration
287  * @param[in] frame_rate Frame rate in Hz. Must be >= 0, 0 is interpreted as unlimited
288  */
289 void acc_config_frame_rate_set(acc_config_t *config, float frame_rate);
290 
291 
292 /**
293  * @brief Get the frame rate
294  *
295  * See @ref acc_config_frame_rate_set
296  *
297  * @param[in] config The configuration
298  * @return Frame rate
299  */
300 float acc_config_frame_rate_get(const acc_config_t *config);
301 
302 
303 /**
304  * @brief Enable or disable the transmitter
305  *
306  * If set to true, TX is enabled. This will enable the radio transmitter.
307  * By turning the transmitter off the RX noise floor can be measured.
308  *
309  * @param[in] config The configuration
310  * @param[in] enable true to enable the transmitter, false to disable it
311  */
312 void acc_config_enable_tx_set(acc_config_t *config, bool enable);
313 
314 
315 /**
316  * @brief Get transmitter enable configuration
317  *
318  * See @ref acc_config_enable_tx_set
319  *
320  * @param[in] config The configuration
321  * @return true if the transmitter is enabled, false if it is disabled
322  */
323 bool acc_config_enable_tx_get(const acc_config_t *config);
324 
325 
326 /**
327  * @brief Set inter frame idle state
328  *
329  * The 'inter-frame idle state' is the state the sensor idles in between each frame.
330  *
331  * See also @ref acc_config_idle_state_t.
332  *
333  * The inter frame idle state of the frame must be deeper or the same as the inter sweep idle state.
334  *
335  * @param[in] config The configuration
336  * @param[in] idle_state The idle state to use between frames
337  */
339 
340 
341 /**
342  * @brief Get inter frame idle state
343  *
344  * See @ref acc_config_inter_frame_idle_state_set
345  *
346  * @param[in] config The configuration
347  * @return The idle state to use between frames
348  */
350 
351 
352 /**
353  * @brief Set inter sweep idle state
354  *
355  * The 'inter-sweep idle state' is the state the sensor idles in between each sweep in a frame.
356  *
357  * See also @ref acc_config_idle_state_t.
358  *
359  * @param[in] config The configuration
360  * @param[in] idle_state The idle state to use between sweeps within a frame
361  */
363 
364 
365 /**
366  * @brief Get inter sweep idle state
367  *
368  * See @ref acc_config_inter_sweep_idle_state_set
369  *
370  * @param[in] config The configuration
371  * @return The idle state to use between sweeps within a frame
372  */
374 
375 
376 /**
377  * @brief Set Pulse Repetition Frequency
378  *
379  * See @ref acc_config_prf_t for details.
380  *
381  * @param[in] config The configuration
382  * @param[in] prf The Pulse Repetition Frequency to use
383  */
385 
386 
387 /**
388  * @brief Get Pulse Repetition Frequency
389  *
390  * See @ref acc_config_prf_t for details.
391  *
392  * @param[in] config The configuration
393  * @return Pulse Repetition Frequency
394  */
396 
397 
398 /**
399  * @brief Enable or disable phase enhancement
400  *
401  * If enabled, the data phase will be enhanced such that coherent distance filtering can be applied.
402  * Given a single reflection from an object, the phase will appear as "flat" around the amplitude peak.
403  *
404  * Enabling the phase enhancement increases the processing execution time.
405  *
406  * @param[in] config The configuration
407  * @param[in] enable true if phase enhancement should be enabled, false otherwise
408  */
409 void acc_config_phase_enhancement_set(acc_config_t *config, bool enable);
410 
411 
412 /**
413  * @brief Get the phase enhancement configuration
414  *
415  * See @ref acc_config_phase_enhancement_set
416  *
417  * @param[in] config The configuration
418  * @return true if phase enhancement is enabled, false otherwise
419  */
421 
422 
423 /**
424  * @brief Enable or disable loopback
425  *
426  * Constraints:
427  * - Loopback can't be enabled together with profile 2.
428  *
429  * @param[in] config The configuration
430  * @param[in] enable true if loopback should be enabled, false otherwise
431  */
432 void acc_config_enable_loopback_set(acc_config_t *config, bool enable);
433 
434 
435 /**
436  * @brief Get the enable loopback configuration
437  *
438  * See @ref acc_config_enable_loopback_set
439  *
440  * @param[in] config The configuration
441  * @return true if loopback is enabled, false otherwise
442  */
443 bool acc_config_enable_loopback_get(const acc_config_t *config);
444 
445 
446 /**
447  * @brief Enable or disable double buffering
448  *
449  * If enabled, the sensor buffer will be split in two halves reducing the
450  * maximum number of samples. A frame can be read using @ref acc_sensor_read while
451  * sampling is done into the other buffer. Switching of buffers is done automatically
452  * by @ref acc_sensor_measure.
453  *
454  * When using double buffering, measurements coinciding with SPI activity may have distorted phase.
455  * To mitigate this issue, applying a median filter is recommended.
456  *
457  * @param[in] config The configuration
458  * @param[in] enable true if double buffering should be enabled, false otherwise
459  */
460 void acc_config_double_buffering_set(acc_config_t *config, bool enable);
461 
462 
463 /**
464  * @brief Get the double buffering configuration
465  *
466  * See @ref acc_config_double_buffering_set
467  *
468  * @param[in] config The configuration
469  * @return true if double buffering is enabled, false otherwise
470  */
472 
473 
474 /**
475  * @}
476  */
477 
478 
479 #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_t
acc_config_profile_t
Profile.
Definition: acc_definitions_a121.h:39
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_prf_t
acc_config_prf_t
Pulse Repetition Frequency.
Definition: acc_definitions_a121.h:103
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_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_idle_state_t
acc_config_idle_state_t
Idle state.
Definition: acc_definitions_a121.h:61
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_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