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