example_service_calibration_caching.c
Go to the documentation of this file.
1 // Copyright (c) Acconeer AB, 2020-2023
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 #include <stdbool.h>
8 #include <stdint.h>
9 #include <stdio.h>
10 #include <stdlib.h>
11 
12 
13 #include "acc_config.h"
14 #include "acc_definitions_a121.h"
15 #include "acc_definitions_common.h"
18 #include "acc_integration.h"
19 #include "acc_processing.h"
20 #include "acc_rss_a121.h"
21 #include "acc_sensor.h"
22 
23 #include "acc_version.h"
24 
25 
26 /** \example example_service_calibration_caching.c
27  * @brief This is an example on how the sensor calibration can be cached
28  * @n
29  * The example executes as follows:
30  * - Retrieve and register HAL stuct
31  * - Create config, processing, and sensor instances
32  * - Calibrate and prepare sensor
33  * - Measure, read and process radar data
34  * - Check 'calibration_needed' indication
35  * - If needed either use cached calibration or perform new calibration and store
36  * - Destroy sensor, processing, and config instances
37  */
38 
39 #define SENSOR_ID (1U)
40 #define SENSOR_TIMEOUT_MS (1000U)
41 #define MAX_DATA_ENTRY_LEN (15U) // "-32000+-32000i" + zero termination
42 
43 /**
44  * A sensor calibration is valid at the temperature it was done +- 15 degrees
45  *
46  * If the temperature isn't controlled during caching, which is the case in this example,
47  * the maximum amount of caches needs to be calculated from a temperature difference of 16.
48  *
49  * For example
50  * - A calibration is done at 25 degrees, which means it is valid between 10 and 40 degrees
51  * - The temperature changes to 41 degrees
52  * - A new calibration needs to be done at 41 degrees since it is above the valid range for the previous calibration
53  * - The new calibration is then valid between 26 and 56 degrees
54  *
55  * However, if the temperature is controlled, for example in a factory, the maximum amount
56  * of caches can be calculated from a temperature difference of 30.
57  *
58  * For example
59  * - A calibration is done at 25 degrees, which means it is valid between 10 and 40 degrees
60  * - The temperature is manually changed to 55 degrees
61  * - A new calibration can be done which is valid between 40 and 70 degrees
62  *
63  * The maximum temperature variation that the application will operate in is assumed to be
64  * -40 to 85 degrees in this example.
65  */
66 #define MAX_CAL_TEMP_DIFF (16)
67 #define MAX_TEMP_VARIATION (125)
68 #define MAX_CACHE_COUNT ((MAX_TEMP_VARIATION / MAX_CAL_TEMP_DIFF) + 1)
69 
70 // Note that each 'acc_cal_result_t' struct should be suitably aligned for any built-in type
72 static int16_t cal_temps[MAX_CACHE_COUNT];
73 static uint16_t curr_cache_count = 0;
74 
75 static void set_config(acc_config_t *config);
76 
77 
78 static bool find_cache_index(int16_t temp, uint16_t *cache_index);
79 
80 
81 static bool get_next_empty_cache_index(uint16_t *cache_index);
82 
83 
84 static bool add_cache(uint16_t cache_index, int16_t temp);
85 
86 
87 static bool calibration_caching_and_prepare(acc_sensor_t *sensor, acc_config_t *config,
88  void *buffer, uint32_t buffer_size,
89  bool temp_known, int16_t temp);
90 
91 
92 static void cleanup(acc_config_t *config, acc_processing_t *processing,
93  acc_sensor_t *sensor, void *buffer);
94 
95 
96 int app_main(int argc, char *argv[]);
97 
98 
99 int app_main(int argc, char *argv[])
100 {
101  (void)argc;
102  (void)argv;
103  acc_config_t *config = NULL;
104  acc_processing_t *processing = NULL;
105  acc_sensor_t *sensor = NULL;
106  void *buffer = NULL;
107  uint32_t buffer_size = 0;
108  acc_processing_metadata_t proc_meta;
109  acc_processing_result_t proc_result;
110 
111  printf("Acconeer software version %s\n", acc_version_get());
112 
114 
116  {
117  return EXIT_FAILURE;
118  }
119 
120  config = acc_config_create();
121  if (config == NULL)
122  {
123  printf("acc_config_create() failed\n");
124  cleanup(config, processing, sensor, buffer);
125  return EXIT_FAILURE;
126  }
127 
128  set_config(config);
129 
130  // Print the configuration
131  acc_config_log(config);
132 
133  processing = acc_processing_create(config, &proc_meta);
134  if (processing == NULL)
135  {
136  printf("acc_processing_create() failed\n");
137  cleanup(config, processing, sensor, buffer);
138  return EXIT_FAILURE;
139  }
140 
141  if (!acc_rss_get_buffer_size(config, &buffer_size))
142  {
143  printf("acc_rss_get_buffer_size() failed\n");
144  cleanup(config, processing, sensor, buffer);
145  return EXIT_FAILURE;
146  }
147 
148  buffer = acc_integration_mem_alloc(buffer_size);
149  if (buffer == NULL)
150  {
151  printf("buffer allocation failed\n");
152  cleanup(config, processing, sensor, buffer);
153  return EXIT_FAILURE;
154  }
155 
158 
159  sensor = acc_sensor_create(SENSOR_ID);
160  if (sensor == NULL)
161  {
162  printf("acc_sensor_create() failed\n");
163  cleanup(config, processing, sensor, buffer);
164  return EXIT_FAILURE;
165  }
166 
167  if (!calibration_caching_and_prepare(sensor, config, buffer, buffer_size, false, 0))
168  {
169  printf("calibration_caching_and_prepare() failed\n");
170  acc_sensor_status(sensor);
171  cleanup(config, processing, sensor, buffer);
172  return EXIT_FAILURE;
173  }
174 
175  uint32_t update_count = 5U;
176 
177  for (uint32_t i = 0U; i < update_count; i++)
178  {
179  if (!acc_sensor_measure(sensor))
180  {
181  printf("acc_sensor_measure failed\n");
182  acc_sensor_status(sensor);
183  cleanup(config, processing, sensor, buffer);
184  return EXIT_FAILURE;
185  }
186 
188  {
189  printf("Sensor interrupt timeout\n");
190  acc_sensor_status(sensor);
191  cleanup(config, processing, sensor, buffer);
192  return EXIT_FAILURE;
193  }
194 
195  if (!acc_sensor_read(sensor, buffer, buffer_size))
196  {
197  printf("acc_sensor_read failed\n");
198  acc_sensor_status(sensor);
199  cleanup(config, processing, sensor, buffer);
200  return EXIT_FAILURE;
201  }
202 
203  acc_processing_execute(processing, buffer, &proc_result);
204 
205  if (proc_result.calibration_needed)
206  {
207  printf("New calibration needed due to temperature change\n");
208 
209  if (!calibration_caching_and_prepare(sensor, config, buffer, buffer_size, true, proc_result.temperature))
210  {
211  printf("calibration_caching_and_prepare() failed\n");
212  acc_sensor_status(sensor);
213  cleanup(config, processing, sensor, buffer);
214  return EXIT_FAILURE;
215  }
216  }
217  else
218  {
219  printf("IQ data retrieved\n");
220  }
221  }
222 
223  cleanup(config, processing, sensor, buffer);
224 
225  printf("Application finished OK\n");
226 
227  return EXIT_SUCCESS;
228 }
229 
230 
231 static void set_config(acc_config_t *config)
232 {
233  // Add configuration of the sensor here
234 
235  acc_config_start_point_set(config, 80);
236  acc_config_num_points_set(config, 160);
237 }
238 
239 
240 static bool find_cache_index(int16_t temp, uint16_t *cache_index)
241 {
242  bool cache_found = false;
243  uint16_t min_temp_diff = UINT16_MAX;
244 
245  // If caches have overlapping temperature ranges, the cache
246  // with center temperature closest to 'temp' will be chosen
247  for (uint16_t index = 0; index < curr_cache_count; index++)
248  {
249  uint16_t temp_diff = abs(cal_temps[index] - temp);
250 
251  if (temp_diff < MAX_CAL_TEMP_DIFF && temp_diff < min_temp_diff)
252  {
253  min_temp_diff = temp_diff;
254  *cache_index = index;
255  cache_found = true;
256  }
257  }
258 
259  return cache_found;
260 }
261 
262 
263 static bool get_next_empty_cache_index(uint16_t *cache_index)
264 {
265  *cache_index = curr_cache_count;
266 
268 }
269 
270 
271 static bool add_cache(uint16_t cache_index, int16_t temp)
272 {
273  bool status = false;
274 
275  if ((cache_index == curr_cache_count) && (cache_index < MAX_CACHE_COUNT))
276  {
277  cal_temps[cache_index] = temp;
279  status = true;
280  }
281 
282  return status;
283 }
284 
285 
287  void *buffer, uint32_t buffer_size,
288  bool temp_known, int16_t temp)
289 {
290  bool status = true;
291  bool use_cache = false;
292  uint16_t cache_index = 0;
293 
294  // If temperature is known, there might be a cached calibration result that can be used
295  if (temp_known)
296  {
297  if (find_cache_index(temp, &cache_index))
298  {
299  use_cache = true;
300  }
301  }
302 
303  // If no cached calibration can be used, a new calibration should be made
304  // and the result stored at an empty cache_index
305  if (!use_cache)
306  {
307  printf("New calibration is performed\n");
308 
309  if (!get_next_empty_cache_index(&cache_index))
310  {
311  printf("No empty cache_index to store calibration result\n");
312  return false;
313  }
314 
315  status = false;
316  bool cal_complete = false;
317  const uint16_t calibration_retries = 1U;
318 
319  // Random disturbances may cause the calibration to fail. At failure, retry at least once.
320  for (uint16_t i = 0; !status && (i <= calibration_retries); i++)
321  {
322  // Reset sensor before calibration by disabling/enabling it
325 
326  do
327  {
328  status = acc_sensor_calibrate(sensor, &cal_complete, &cal_results[cache_index], buffer, buffer_size);
329 
330  if (status && !cal_complete)
331  {
333  }
334  } while (status && !cal_complete);
335  }
336 
337  if (status)
338  {
339  // Reset sensor after calibration by disabling/enabling it
342 
343  acc_cal_info_t cal_info;
344  acc_sensor_get_cal_info(&cal_results[cache_index], &cal_info);
345  add_cache(cache_index, cal_info.temperature);
346  }
347  }
348  else
349  {
350  printf("Using cached calibration for %u degrees Celsius\n", cal_temps[cache_index]);
351  }
352 
353  if (status)
354  {
355  status = acc_sensor_prepare(sensor, config, &cal_results[cache_index], buffer, buffer_size);
356  }
357 
358  return status;
359 }
360 
361 
362 static void cleanup(acc_config_t *config, acc_processing_t *processing,
363  acc_sensor_t *sensor, void *buffer)
364 {
367 
368  if (sensor != NULL)
369  {
370  acc_sensor_destroy(sensor);
371  }
372 
373  if (processing != NULL)
374  {
375  acc_processing_destroy(processing);
376  }
377 
378  if (config != NULL)
379  {
380  acc_config_destroy(config);
381  }
382 
383  if (buffer != NULL)
384  {
385  acc_integration_mem_free(buffer);
386  }
387 }
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.
app_main
int app_main(int argc, char *argv[])
Assembly test example.
Definition: example_service_calibration_caching.c:99
acc_hal_integration_sensor_supply_off
void acc_hal_integration_sensor_supply_off(acc_sensor_id_t sensor_id)
Power off sensor supply.
Definition: acc_hal_integration_espidf_xe121.c:192
acc_rss_a121.h
acc_processing_destroy
void acc_processing_destroy(acc_processing_t *handle)
Destroy a processing instance identified with the provided processing handle.
acc_hal_integration_sensor_supply_on
void acc_hal_integration_sensor_supply_on(acc_sensor_id_t sensor_id)
Power on sensor supply.
Definition: acc_hal_integration_espidf_xe121.c:185
acc_cal_info_t
Information about calibration.
Definition: acc_definitions_a121.h:40
acc_processing_result_t
Result provided by the processing module.
Definition: acc_processing.h:71
SENSOR_TIMEOUT_MS
#define SENSOR_TIMEOUT_MS
Definition: example_service_calibration_caching.c:40
acc_sensor_read
bool acc_sensor_read(const acc_sensor_t *sensor, void *buffer, uint32_t buffer_size)
Read out radar data.
acc_version.h
acc_rss_get_buffer_size
bool acc_rss_get_buffer_size(const acc_config_t *config, uint32_t *buffer_size)
Get the buffer size needed for the specified config.
acc_config_destroy
void acc_config_destroy(acc_config_t *config)
Destroy a configuration freeing any resources allocated.
acc_cal_result_t
The result from a completed calibration.
Definition: acc_definitions_a121.h:32
acc_processing_execute
void acc_processing_execute(acc_processing_t *handle, void *buffer, acc_processing_result_t *result)
Process the data according to the configuration used in create.
get_next_empty_cache_index
static bool get_next_empty_cache_index(uint16_t *cache_index)
Definition: example_service_calibration_caching.c:263
acc_config_create
acc_config_t * acc_config_create(void)
Create a configuration.
acc_integration.h
acc_hal_rss_integration_get_implementation
const acc_hal_a121_t * acc_hal_rss_integration_get_implementation(void)
Get hal implementation reference.
Definition: acc_hal_integration_espidf_xe121.c:135
acc_integration_mem_alloc
void * acc_integration_mem_alloc(size_t size)
Allocate dynamic memory.
Definition: acc_integration_esp32.c:38
acc_processing_metadata_t
Metadata that will be populated by the processing module during creation.
Definition: acc_processing.h:36
acc_hal_a121_t
Definition: acc_hal_definitions_a121.h:82
acc_rss_hal_register
bool acc_rss_hal_register(const acc_hal_a121_t *hal)
Register an integration.
acc_sensor.h
add_cache
static bool add_cache(uint16_t cache_index, int16_t temp)
Definition: example_service_calibration_caching.c:271
acc_hal_integration_wait_for_sensor_interrupt
bool acc_hal_integration_wait_for_sensor_interrupt(acc_sensor_id_t sensor_id, uint32_t timeout_ms)
Wait for a sensor interrupt.
Definition: acc_hal_integration_espidf_xe121.c:100
acc_hal_integration_a121.h
acc_version_get
const char * acc_version_get(void)
Get the version of the Acconeer software.
acc_config_t
struct acc_config acc_config_t
Definition: acc_config.h:26
MAX_CACHE_COUNT
#define MAX_CACHE_COUNT
Definition: example_service_calibration_caching.c:68
acc_sensor_get_cal_info
bool acc_sensor_get_cal_info(const acc_cal_result_t *cal_result, acc_cal_info_t *cal_info)
Gets calibration information from a calibration result.
acc_hal_integration_sensor_enable
void acc_hal_integration_sensor_enable(acc_sensor_id_t sensor_id)
Enable sensor.
Definition: acc_hal_integration_espidf_xe121.c:199
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_hal_definitions_a121.h
find_cache_index
static bool find_cache_index(int16_t temp, uint16_t *cache_index)
Definition: example_service_calibration_caching.c:240
cal_results
static acc_cal_result_t cal_results[(((125)/(16))+1)]
Definition: example_service_calibration_caching.c:71
cleanup
static void cleanup(acc_config_t *config, acc_processing_t *processing, acc_sensor_t *sensor, void *buffer)
Definition: example_service_calibration_caching.c:362
acc_hal_integration_sensor_disable
void acc_hal_integration_sensor_disable(acc_sensor_id_t sensor_id)
Disable sensor.
Definition: acc_hal_integration_espidf_xe121.c:214
acc_processing_t
struct acc_processing_handle acc_processing_t
Definition: acc_processing.h:30
acc_sensor_status
void acc_sensor_status(const acc_sensor_t *sensor)
Check the status of the sensor.
calibration_caching_and_prepare
static bool calibration_caching_and_prepare(acc_sensor_t *sensor, acc_config_t *config, void *buffer, uint32_t buffer_size, bool temp_known, int16_t temp)
Definition: example_service_calibration_caching.c:286
hal
static const acc_hal_a121_t hal
Definition: acc_hal_integration_espidf_xe121.c:121
SENSOR_ID
#define SENSOR_ID
Definition: example_service_calibration_caching.c:39
acc_sensor_prepare
bool acc_sensor_prepare(acc_sensor_t *sensor, const acc_config_t *config, const acc_cal_result_t *cal_result, void *buffer, uint32_t buffer_size)
Prepare a sensor to do a measurement.
acc_integration_mem_free
void acc_integration_mem_free(void *ptr)
Free dynamic memory.
Definition: acc_integration_esp32.c:57
acc_definitions_common.h
acc_processing_result_t::temperature
int16_t temperature
Definition: acc_processing.h:89
acc_config_log
void acc_config_log(const acc_config_t *config)
Print a configuration to the log.
acc_config.h
curr_cache_count
static uint16_t curr_cache_count
Definition: example_service_calibration_caching.c:73
acc_sensor_calibrate
bool acc_sensor_calibrate(acc_sensor_t *sensor, bool *cal_complete, acc_cal_result_t *cal_result, void *buffer, uint32_t buffer_size)
Calibrate a sensor.
cal_temps
static int16_t cal_temps[(((125)/(16))+1)]
Definition: example_service_calibration_caching.c:72
acc_processing_result_t::calibration_needed
bool calibration_needed
Definition: acc_processing.h:84
acc_cal_info_t::temperature
int16_t temperature
Definition: acc_definitions_a121.h:42
acc_sensor_measure
bool acc_sensor_measure(acc_sensor_t *sensor)
Start a radar measurement with previously prepared configuration.
acc_processing_create
acc_processing_t * acc_processing_create(const acc_config_t *config, acc_processing_metadata_t *processing_metadata)
Create a processing instance with the provided configuration.
set_config
static void set_config(acc_config_t *config)
Definition: example_service_calibration_caching.c:231
acc_processing.h
acc_sensor_t
struct acc_sensor acc_sensor_t
Definition: acc_sensor.h:31
acc_sensor_destroy
void acc_sensor_destroy(acc_sensor_t *sensor)
Destroy a sensor instance freeing any resources allocated.
acc_definitions_a121.h
MAX_CAL_TEMP_DIFF
#define MAX_CAL_TEMP_DIFF
Definition: example_service_calibration_caching.c:66
acc_sensor_create
acc_sensor_t * acc_sensor_create(acc_sensor_id_t sensor_id)
Create a sensor instance.