example_cargo.h
Go to the documentation of this file.
1 // Copyright (c) Acconeer AB, 2025
2 // All rights reserved
3 // This file is subject to the terms and conditions defined in the file
4 // 'LICENSES/license_acconeer.txt', (BSD 3-Clause License) which is part
5 // of this source code package.
6
7 #ifndef EXAMPLE_CARGO_H_
8 #define EXAMPLE_CARGO_H_
9
10 #include <stdbool.h>
11 #include <stdint.h>
12
13 #include "acc_config.h"
14 #include "acc_detector_distance.h"
15 #include "acc_detector_presence.h"
16 #include "acc_processing.h"
17 #include "acc_sensor.h"
18
19 /**
20 * @brief Cargo Example App Presets
21 */
22 typedef enum
23 {
24 CARGO_PRESET_CONTAINER_10_FEET,
25 CARGO_PRESET_CONTAINER_20_FEET,
26 CARGO_PRESET_CONTAINER_40_FEET,
27 CARGO_PRESET_NO_LENS,
28 } cargo_preset_t;
29
30 /**
31 * @brief Container size
32 */
33 typedef enum
34 {
35 CARGO_CONTAINER_SIZE_10_FT,
36 CARGO_CONTAINER_SIZE_20_FT,
37 CARGO_CONTAINER_SIZE_40_FT,
38 } cargo_container_size_t;
39
40 /**
41 * @brief Configuration struct for cargo
42 */
43 typedef struct
44 {
45 uint32_t magic;
46
47 cargo_container_size_t container_size;
48
49 bool activate_utilization_level;
50
51 struct
52 {
53 /**
54 * Signal quality (dB).
55 * High quality equals higher HWAAS and better SNR but increases power consumption.
56 */
57 float signal_quality;
58
59 /**
60 * Sensitivity of threshold.
61 *
62 * High sensitivity equals low detection threshold, low sensitivity equals high detection
63 * threshold.
64 */
65 float threshold_sensitivity;
66 } utilization;
67
68 bool activate_presence;
69
70 struct
71 {
72 /**
73 * Sets the presence detector update rate (Hz).
74 */
75 float update_rate;
76
77 /**
78 * Number of sweeps per frame.
79 */
80 uint16_t sweeps_per_frame;
81
82 /**
83 * Signal quality (dB).
84 * High quality equals higher HWAAS and better SNR but increases power consumption.
85 */
86 float signal_quality;
87
88 /**
89 * Detection threshold for the inter-frame presence detection
90 */
91 float inter_detection_threshold;
92
93 /**
94 * Detection threshold for the intra-frame presence detection.
95 */
96 float intra_detection_threshold;
97
98 /**
99 * Whether the Presence's frame rate should be app driven.
100 * See @ref acc_detector_presence_config_frame_rate_app_driven_set
101 */
102 bool rate_is_app_driven;
103 } presence;
104 } cargo_config_t;
105
106 /**
107 * @brief Result type
108 */
109 typedef struct
110 {
111 /** If true, the sensor needs to be recalibrated & the cargo calibration needs to be updated */
112 bool calibration_needed;
113
114 /** Whether fields distance, level_m & level_percent are valid */
115 bool utilization_valid;
116
117 /** The distance in meters to the measured object */
118 float distance;
119
120 /** The container fill level in meters.
121 * Ranges from 0m to the full container size (10, 20 or 40 ft)
122 */
123 float level_m;
124
125 /** The container fill level in percent.
126 * Ranges from 0% to 100%
127 */
128 float level_percent;
129
130 /** Whether fields presence_detected, inter_presence_score & intra_presence_score are valid */
131 bool presence_valid;
132
133 /** Whether presence was detected. */
134 bool presence_detected;
135
136 /** See @ref acc_detector_presence_result_t */
137 float inter_presence_score;
138
139 /** See @ref acc_detector_presence_result_t */
140 float intra_presence_score;
141 } cargo_result_t;
142
143 /**
144 * @brief Handle type (forward declared)
145 */
146 struct cargo_handle;
147
148 typedef struct cargo_handle cargo_handle_t;
149
150 /**
151 * @brief Cargo mode enumeration
152 */
153 typedef enum
154 {
155 CARGO_MODE_NONE = 0,
156 CARGO_MODE_UTILIZATION,
157 CARGO_MODE_PRESENCE,
158 } cargo_mode_t;
159
160 /**
161 * @brief Initialize cargo config struct with a preset
162 *
163 * @param[out] cargo_config The cargo config to initialize
164 * @param[in] preset A @ref cargo_preset_t to initialize the config to
165 */
166 void cargo_config_initialize(cargo_config_t *cargo_config, cargo_preset_t preset);
167
168 /**
169 * @brief Log cargo config to debug uart
170 *
171 * @param[in] cargo_config The cargo config to log
172 */
173 void cargo_config_log(const cargo_config_t *cargo_config);
174
175 /**
176 * @brief Create a cargo handle
177 *
178 * @param[in] cargo_config Cargo configuration
179 * @return A cargo handle, or NULL if creation failed
180 */
181 cargo_handle_t *cargo_handle_create(const cargo_config_t *cargo_config);
182
183 /**
184 * @brief Destroy a cargo handle
185 *
186 * @param[in] handle The cargo handle to destroy
187 */
188 void cargo_handle_destroy(cargo_handle_t *handle);
189
190 /**
191 * @brief Get the required buffer sensor data buffer size
192 *
193 * @param[in] handle The cargo handle
194 * @param[out] buffer_size The required buffer size
195 * @return True if successful, false otherwise
196 */
197 bool cargo_get_buffer_size(const cargo_handle_t *handle, uint32_t *buffer_size);
198
199 /**
200 * @brief Get the required buffer for static distance detector calibration
201 *
202 * @param[in] handle The cargo handle
203 * @param[out] distance_cal_result_static_size The required buffer size.
204 * Will be 0U if activate_utilization_level is false.
205 * @return True if successful, false otherwise
206 */
207 bool cargo_get_distance_cal_result_static_size(const cargo_handle_t *handle, uint32_t *distance_cal_result_static_size);
208
209 /**
210 * @brief Calibrate Cargo
211 *
212 * Calibrating Cargo's internal Detector is needed to ensure reliable Detector results.
213 *
214 * See the calibration sections in the Distance Detector User Guide for more information.
215 *
216 * @param[in] sensor The sensor instance to use for calibration
217 * @param[in] handle The Cargo handle
218 * @param[in] sensor_cal_result Sensor calibration result
219 * @param[in] buffer Working memory buffer needed by function
220 * @param[in] buffer_size The size of buffer. Needs to be at least
221 * the result of @ref cargo_get_buffer_size
222 * @param[out] distance_cal_result_static Static result of calibration
223 * @param[in] distance_cal_result_static_size The size of distance_cal_result_static.
224 * Needs to be at least the result of @ref cargo_get_distance_cal_result_static_size
225 * @param[out] distance_cal_result_dynamic Dynamic result of calibration
226 * @param[out] calibration_complete Will be set to true when the calibration is complete.
227 * If false; at least one more call to this function is needed.
228 * Note that it's necessary to wait for interrupt between calls.
229 * @return True if successful, false otherwise
230 */
231 bool cargo_calibrate(cargo_handle_t *handle,
232 acc_sensor_t *sensor,
233 const acc_cal_result_t *sensor_cal_result,
234 void *buffer,
235 uint32_t buffer_size,
236 uint8_t *distance_cal_result_static,
237 uint32_t distance_cal_result_static_size,
238 acc_detector_cal_result_dynamic_t *distance_cal_result_dynamic,
239 bool *calibration_complete);
240
241 /**
242 * @brief Update Cargo calibration
243 *
244 * Updates Cargo's internal calibration.
245 *
246 * If calibration_needed has been set to true, you should do the following:
247 * 1. Recalibrate sensor (see @ref acc_sensor_calibrate)
248 * 2. Call this function in a loop until calibration_complete=true (and while true is returned)
249 * 3. Redo the Utilization- or Presence measurement
250 *
251 * @param[in] sensor The sensor instance to use for calibration
252 * @param[in] handle The Cargo handle
253 * @param[in] sensor_cal_result Sensor calibration result
254 * @param[in] buffer Working memory buffer needed by function
255 * @param[in] buffer_size The size of buffer. Needs to be at least
256 * the result of @ref cargo_get_buffer_size
257 * @param[out] distance_cal_result_dynamic Dynamic result of calibration
258 * @param[out] calibration_complete Will be set to true when the calibration is complete.
259 * If false; at least one more call to this function is needed.
260 * Note that it's necessary to wait for interrupt between calls.
261 * @return True if successful, false otherwise
262 */
263 bool cargo_update_calibration(cargo_handle_t *handle,
264 acc_sensor_t *sensor,
265 const acc_cal_result_t *sensor_cal_result,
266 void *buffer,
267 uint32_t buffer_size,
268 acc_detector_cal_result_dynamic_t *distance_cal_result_dynamic,
269 bool *calibration_complete);
270
271 /**
272 * @brief Prepare Cargo utilization for measurements
273 *
274 * @param[in, out] handle The Cargo handle
275 * @param[in] sensor The sensor instance
276 * @param[in] sensor_cal_result The sensor calibration result
277 * @param[in] buffer Memory used by the detector. Should be at least buffer_size bytes
278 * @param[in] buffer_size The buffer size received by @ref acc_detector_distance_get_sizes
279 * @return True if successful, false otherwise
280 */
281 bool cargo_prepare_utilization(cargo_handle_t *handle,
282 acc_sensor_t *sensor,
283 const acc_cal_result_t *sensor_cal_result,
284 void *buffer,
285 uint32_t buffer_size);
286
287 /**
288 * @brief Prepare Cargo presence for measurements
289 *
290 * @param[in, out] handle The Cargo handle
291 * @param[in] sensor The sensor instance
292 * @param[in] sensor_cal_result The sensor calibration result
293 * @param[in] buffer Memory used by the detector. Should be at least buffer_size bytes
294 * @param[in] buffer_size The buffer size received by @ref acc_detector_distance_get_sizes
295 * @return True if successful, false otherwise
296 */
297 bool cargo_prepare_presence(cargo_handle_t *handle,
298 acc_sensor_t *sensor,
299 const acc_cal_result_t *sensor_cal_result,
300 void *buffer,
301 uint32_t buffer_size);
302
303 /**
304 * @brief Process Sparse IQ data into a Cargo result
305 *
306 * @param[in] handle The Cargo handle
307 * @param[in] distance_cal_result_static The result from @ref cargo_calibrate
308 * @param[in] distance_cal_result_dynamic The result from @ref cargo_calibrate
309 * @param[in] buffer A reference to the buffer (populated by @ref acc_sensor_read) containing the
310 * data to be processed.
311 * @param[out] cargo_result Cargo result
312 * @param[out] result_available True if the cargo_result is valid
313 * @param[out] nullable_distance_result Pointer to auxilliary @ref acc_detector_distance_result_t
314 * Can be NULL.
315 * @return True if successful, false otherwise
316 */
317 bool cargo_process_utilization(cargo_handle_t *handle,
318 uint8_t *distance_cal_result_static,
319 acc_detector_cal_result_dynamic_t *distance_cal_result_dynamic,
320 void *buffer,
321 cargo_result_t *cargo_result,
322 bool *result_available,
323 acc_detector_distance_result_t *nullable_distance_result);
324
325 /**
326 * @brief Process Sparse IQ data into a Cargo result
327 *
328 * @param[in] handle The Cargo handle
329 * @param[in] buffer A reference to the buffer (populated by @ref acc_sensor_read) containing the
330 * data to be processed.
331 * @param[out] cargo_result Cargo result
332 * @param[out] nullable_presence_result Pointer to auxilliary @ref acc_detector_presence_result_t
333 * Can be NULL.
334 * @return True if successful, false otherwise
335 */
336 bool cargo_process_presence(cargo_handle_t *handle,
337 void *buffer,
338 cargo_result_t *cargo_result,
339 acc_detector_presence_result_t *nullable_presence_result);
340
341 /**
342 * @brief Get current mode of the cargo handle
343 *
344 * Really only useful when doing both Presence- & Utilization level measurements.
345 *
346 * @param[in] handle The cargo handle
347 * @return The current cargo mode. See @ref cargo_mode_t
348 */
349 cargo_mode_t cargo_current_mode_get(const cargo_handle_t *handle);
350
351 /**
352 * @brief Get presence detector metadata
353 *
354 * @param[in] handle The cargo handle
355 * @param[out] presence_metadata The Presence Detector metadata
356 * @return True if handle is valid & configured with presence activated, false otherwise
357 */
358 bool cargo_presence_metadata_get(cargo_handle_t *handle, acc_detector_presence_metadata_t *presence_metadata);
359
360 #endif
cargo_preset_t
cargo_preset_t
Cargo Example App Presets.
Definition: example_cargo.h:22
cargo_config_t::update_rate
float update_rate
Definition: example_cargo.h:75
cargo_result_t::calibration_needed
bool calibration_needed
Definition: example_cargo.h:112
cargo_handle_create
cargo_handle_t * cargo_handle_create(const cargo_config_t *cargo_config)
Create a cargo handle.
Definition: example_cargo.c:164
distance_cal_result_static_size
uint32_t distance_cal_result_static_size
Definition: i2c_example_cargo.c:39
cargo_process_presence
bool cargo_process_presence(cargo_handle_t *handle, void *buffer, cargo_result_t *cargo_result, acc_detector_presence_result_t *nullable_presence_result)
Process Sparse IQ data into a Cargo result.
Definition: example_cargo.c:558
CARGO_MODE_UTILIZATION
@ CARGO_MODE_UTILIZATION
Definition: example_cargo.h:156
cargo_config_t::intra_detection_threshold
float intra_detection_threshold
Definition: example_cargo.h:96
cargo_prepare_presence
bool cargo_prepare_presence(cargo_handle_t *handle, acc_sensor_t *sensor, const acc_cal_result_t *sensor_cal_result, void *buffer, uint32_t buffer_size)
Prepare Cargo presence for measurements.
Definition: example_cargo.c:423
buffer
void * buffer
Definition: i2c_example_cargo.c:40
cargo_mode_t
cargo_mode_t
Cargo mode enumeration.
Definition: example_cargo.h:153
sensor_cal_result
acc_cal_result_t sensor_cal_result
Definition: i2c_example_cargo.c:36
cargo_config_t::signal_quality
float signal_quality
Definition: example_cargo.h:57
cargo_presence_metadata_get
bool cargo_presence_metadata_get(cargo_handle_t *handle, acc_detector_presence_metadata_t *presence_metadata)
Get presence detector metadata.
Definition: example_cargo.c:634
cargo_result_t::distance
float distance
Definition: example_cargo.h:118
acc_cal_result_t
The result from a completed calibration.
Definition: acc_definitions_a121.h:30
distance_cal_result_static
uint8_t * distance_cal_result_static
Definition: i2c_example_cargo.c:38
cargo_config_t::magic
uint32_t magic
Definition: example_cargo.h:45
cargo_result_t::level_m
float level_m
Definition: example_cargo.h:123
cargo_container_size_t
cargo_container_size_t
Container size.
Definition: example_cargo.h:33
cargo_config_initialize
void cargo_config_initialize(cargo_config_t *cargo_config, cargo_preset_t preset)
Initialize cargo config struct with a preset.
Definition: example_cargo.c:80
cargo_config_t
Configuration struct for cargo.
Definition: example_cargo.h:43
cargo_result_t::inter_presence_score
float inter_presence_score
Definition: example_cargo.h:137
cargo_result_t::level_percent
float level_percent
Definition: example_cargo.h:128
cargo_config_t::sweeps_per_frame
uint16_t sweeps_per_frame
Definition: example_cargo.h:80
CARGO_CONTAINER_SIZE_10_FT
@ CARGO_CONTAINER_SIZE_10_FT
Definition: example_cargo.h:35
acc_sensor.h
acc_detector_presence_result_t
Presence detector results container.
Definition: acc_detector_presence.h:46
buffer_size
uint32_t buffer_size
Definition: i2c_example_cargo.c:41
CARGO_MODE_NONE
@ CARGO_MODE_NONE
Definition: example_cargo.h:155
acc_detector_cal_result_dynamic_t
The result from a completed calibration update.
Definition: acc_detector_distance_definitions.h:23
cargo_config_t::rate_is_app_driven
bool rate_is_app_driven
Definition: example_cargo.h:102
sensor
acc_sensor_t * sensor
Definition: i2c_example_cargo.c:33
CARGO_CONTAINER_SIZE_40_FT
@ CARGO_CONTAINER_SIZE_40_FT
Definition: example_cargo.h:37
cargo_calibrate
bool cargo_calibrate(cargo_handle_t *handle, acc_sensor_t *sensor, const acc_cal_result_t *sensor_cal_result, void *buffer, uint32_t buffer_size, uint8_t *distance_cal_result_static, uint32_t distance_cal_result_static_size, acc_detector_cal_result_dynamic_t *distance_cal_result_dynamic, bool *calibration_complete)
Calibrate Cargo.
Definition: example_cargo.c:318
acc_detector_presence_metadata_t
Definition: acc_detector_presence.h:88
cargo_result_t::utilization_valid
bool utilization_valid
Definition: example_cargo.h:115
handle
cargo_handle_t * handle
Definition: i2c_example_cargo.c:35
cargo_result_t::presence_valid
bool presence_valid
Definition: example_cargo.h:131
CARGO_CONTAINER_SIZE_20_FT
@ CARGO_CONTAINER_SIZE_20_FT
Definition: example_cargo.h:36
cargo_get_buffer_size
bool cargo_get_buffer_size(const cargo_handle_t *handle, uint32_t *buffer_size)
Get the required buffer sensor data buffer size.
Definition: example_cargo.c:272
cargo_get_distance_cal_result_static_size
bool cargo_get_distance_cal_result_static_size(const cargo_handle_t *handle, uint32_t *distance_cal_result_static_size)
Get the required buffer for static distance detector calibration.
Definition: example_cargo.c:298
CARGO_PRESET_CONTAINER_40_FEET
@ CARGO_PRESET_CONTAINER_40_FEET
Definition: example_cargo.h:26
cargo_config_t::activate_utilization_level
bool activate_utilization_level
Definition: example_cargo.h:49
acc_detector_distance_result_t
Distance Detector result returned from acc_detector_distance_process.
Definition: acc_detector_distance.h:48
cargo_result_t::intra_presence_score
float intra_presence_score
Definition: example_cargo.h:140
CARGO_PRESET_CONTAINER_10_FEET
@ CARGO_PRESET_CONTAINER_10_FEET
Definition: example_cargo.h:24
cargo_handle::presence_metadata
acc_detector_presence_metadata_t presence_metadata
Definition: example_cargo.c:34
cargo_config_log
void cargo_config_log(const cargo_config_t *cargo_config)
Log cargo config to debug uart.
Definition: example_cargo.c:135
cargo_handle_destroy
void cargo_handle_destroy(cargo_handle_t *handle)
Destroy a cargo handle.
Definition: example_cargo.c:240
cargo_config_t::container_size
cargo_container_size_t container_size
Definition: example_cargo.h:47
CARGO_PRESET_CONTAINER_20_FEET
@ CARGO_PRESET_CONTAINER_20_FEET
Definition: example_cargo.h:25
cargo_process_utilization
bool cargo_process_utilization(cargo_handle_t *handle, uint8_t *distance_cal_result_static, acc_detector_cal_result_dynamic_t *distance_cal_result_dynamic, void *buffer, cargo_result_t *cargo_result, bool *result_available, acc_detector_distance_result_t *nullable_distance_result)
Process Sparse IQ data into a Cargo result.
Definition: example_cargo.c:462
acc_config.h
distance_cal_result_dynamic
acc_detector_cal_result_dynamic_t distance_cal_result_dynamic
Definition: i2c_example_cargo.c:37
cargo_current_mode_get
cargo_mode_t cargo_current_mode_get(const cargo_handle_t *handle)
Get current mode of the cargo handle.
Definition: example_cargo.c:622
acc_detector_distance.h
cargo_handle
Cargo handle.
Definition: example_cargo.c:27
cargo_result_t
Result type.
Definition: example_cargo.h:109
cargo_result_t::presence_detected
bool presence_detected
Definition: example_cargo.h:134
acc_detector_presence.h
CARGO_PRESET_NO_LENS
@ CARGO_PRESET_NO_LENS
Definition: example_cargo.h:27
cargo_update_calibration
bool cargo_update_calibration(cargo_handle_t *handle, acc_sensor_t *sensor, const acc_cal_result_t *sensor_cal_result, void *buffer, uint32_t buffer_size, acc_detector_cal_result_dynamic_t *distance_cal_result_dynamic, bool *calibration_complete)
Update Cargo calibration.
Definition: example_cargo.c:353
cargo_prepare_utilization
bool cargo_prepare_utilization(cargo_handle_t *handle, acc_sensor_t *sensor, const acc_cal_result_t *sensor_cal_result, void *buffer, uint32_t buffer_size)
Prepare Cargo utilization for measurements.
Definition: example_cargo.c:384
acc_processing.h
acc_sensor_t
struct acc_sensor acc_sensor_t
Definition: acc_sensor.h:31
cargo_config_t::inter_detection_threshold
float inter_detection_threshold
Definition: example_cargo.h:91
cargo_config_t::threshold_sensitivity
float threshold_sensitivity
Definition: example_cargo.h:65
cargo_config_t::activate_presence
bool activate_presence
Definition: example_cargo.h:68
CARGO_MODE_PRESENCE
@ CARGO_MODE_PRESENCE
Definition: example_cargo.h:157