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 */
36 acc_config_t *acc_config_create(void);
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 */
138 void acc_config_profile_set(acc_config_t *config,
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 */
150 acc_config_profile_t acc_config_profile_get(const acc_config_t *config);
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 */
275 bool acc_config_continuous_sweep_mode_get(const acc_config_t *config);
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 */
338 void acc_config_inter_frame_idle_state_set(acc_config_t *config, acc_config_idle_state_t idle_state);
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 */
349 acc_config_idle_state_t acc_config_inter_frame_idle_state_get(const acc_config_t *config);
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 */
362 void acc_config_inter_sweep_idle_state_set(acc_config_t *config, acc_config_idle_state_t idle_state);
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 */
373 acc_config_idle_state_t acc_config_inter_sweep_idle_state_get(const acc_config_t *config);
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 */
384 void acc_config_prf_set(acc_config_t *config, acc_config_prf_t prf);
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 */
395 acc_config_prf_t acc_config_prf_get(const acc_config_t *config);
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 */
420 bool acc_config_phase_enhancement_get(const acc_config_t *config);
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 */
471 bool acc_config_double_buffering_get(const acc_config_t *config);
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