acc_sensor.h
Go to the documentation of this file.
1 // Copyright (c) Acconeer AB, 2020-2022
2 // All rights reserved
3 
4 #ifndef ACC_SENSOR_H_
5 #define ACC_SENSOR_H_
6 
7 #include <stdbool.h>
8 #include <stdint.h>
9 
10 #include "acc_config.h"
11 #include "acc_definitions_a121.h"
12 #include "acc_definitions_common.h"
13 
14 
15 /**
16  * @defgroup service Service
17  *
18  * @brief Service API
19  *
20  * @defgroup sensor Sensor
21  * @ingroup service
22  *
23  * @brief Module to control the sensor
24  *
25  * @{
26  */
27 
28 
29 struct acc_sensor;
30 
31 typedef struct acc_sensor acc_sensor_t;
32 
33 
34 /**
35  * @brief Create a sensor instance
36  *
37  * A sensor instance represents a physical radar sensor and handles the communication
38  * with it.
39  *
40  * Before this function is called the sensor must be powered on and not used
41  * in another sensor instance without a power or reset cycle between.
42  *
43  * @param[in] sensor_id The sensor id to be used to communicate with
44  *
45  * @return Sensor instance, NULL if sensor instance was not possible to create
46  */
48 
49 
50 /**
51  * @brief Destroy a sensor instance freeing any resources allocated.
52  *
53  * @param[in] sensor The sensor instance to destroy, can be NULL
54  */
55 void acc_sensor_destroy(acc_sensor_t *sensor);
56 
57 
58 /**
59  * @brief Calibrate a sensor
60  *
61  * Note that the sensor must be powered on before calling this function.
62  * To calibrate the sensor, call this function and wait for sensor interrupt,
63  * repeat until calibration is complete (or fails).
64  *
65  * @param[in] sensor The sensor instance to calibrate
66  * @param[out] cal_complete True if calibration is complete
67  False if caller should wait for interrupt and
68  then call again
69  * @param[out] cal_result The result after a completed calibration
70  * @param[in] buffer Memory used during calibration.
71  * A larger buffer might mean fewer transactions between host and sensor.
72  * The buffer will only be used during the calibration.
73  * The client has to make sure this buffer is suitably aligned for
74  * any built-in type.
75  * @param[in] buffer_size The size in bytes of the buffer, should be at least buffer_size
76  from @ref acc_rss_get_buffer_size
77  * @return true if successful, false otherwise
78  */
79 bool acc_sensor_calibrate(acc_sensor_t *sensor, bool *cal_complete, acc_cal_result_t *cal_result,
80  void *buffer, uint32_t buffer_size);
81 
82 
83 /**
84  * @brief Gets calibration information from a calibration result
85  *
86  * @param[in] cal_result The calibration result
87  * @param[out] cal_info The calibration information
88  * @return true if successful, false otherwise
89  */
90 bool acc_sensor_get_cal_info(const acc_cal_result_t *cal_result, acc_cal_info_t *cal_info);
91 
92 
93 /**
94  * @brief Prepare a sensor to do a measurement
95  *
96  * It's possible to reconfigure the sensor by calling the function multiple times.
97  *
98  * Note:
99  * - The sensor must be powered on when calling this function.
100  * - The sensor must not be measuring when calling this function, if previous call was
101  * @ref acc_sensor_measure use @ref acc_hal_integration_wait_for_sensor_interrupt to
102  * wait for measurement to complete.
103  * - Reconfiguring is not supported when double buffering is active, however enabling
104  * double buffering through reconfiguration is.
105  *
106  * @param[in] sensor The sensor instance to prepare
107  * @param[in] config The configuration to prepare for
108  * @param[in] cal_result The calibration result to prepare for
109  * @param[in] buffer Memory used during preparation.
110  * A larger buffer might mean fewer transactions between host and sensor.
111  * The buffer will only be used during the duration of this call.
112  * The client has to make sure this buffer is suitably aligned for
113  * any built-in type.
114  * @param[in] buffer_size The size in bytes of the buffer, should be at least buffer_size
115  * from @ref acc_rss_get_buffer_size
116  * @return true if successful, false otherwise
117  */
118 bool acc_sensor_prepare(acc_sensor_t *sensor, const acc_config_t *config, const acc_cal_result_t *cal_result,
119  void *buffer, uint32_t buffer_size);
120 
121 
122 /**
123  * @brief Start a radar measurement with previously prepared configuration
124  *
125  * Note that the following preconditions apply
126  * - The sensor must be powered on
127  * - @ref acc_sensor_calibrate must have been called
128  * - @ref acc_sensor_prepare must have been called
129  *
130  * @param[in] sensor The sensor instance to measure with
131  * @return true if successful, false otherwise
132  */
133 bool acc_sensor_measure(acc_sensor_t *sensor);
134 
135 
136 /**
137  * @brief Read out radar data
138  *
139  * Note that the following preconditions apply
140  * - The sensor must be powered on
141  * - @ref acc_sensor_measure must be called before each call to this function
142  * - The sensor interrupt must be active
143  *
144  * @param[in] sensor The sensor to read the radar data from
145  * @param[in] buffer The buffer to read radar data into.
146  * The buffer will only be used during the duration of this call.
147  * The client has to make sure this buffer is suitably aligned for
148  * any built-in type.
149  * @param[in] buffer_size The size in bytes of the buffer, should be at least buffer_size
150  * from @ref acc_rss_get_buffer_size
151  * @return true if successful, false otherwise
152  */
153 bool acc_sensor_read(const acc_sensor_t *sensor, void *buffer, uint32_t buffer_size);
154 
155 
156 /**
157  * @brief Check if a sensor is connected and responsive
158  *
159  * Note that the sensor must be powered on before calling this function.
160  *
161  * @param[in] sensor_id The sensor id to be used to communicate with
162  * @return true if it is possible to communicate with the sensor
163  */
164 bool acc_sensor_connected(acc_sensor_id_t sensor_id);
165 
166 
167 /**
168  * @brief Check the status of the sensor
169  *
170  * This function reads out the internal status from the sensor and prints it for debugging purposes.
171  * It can for example be called when the function @ref acc_hal_integration_wait_for_sensor_interrupt()
172  * fails. Note that the sensor must be powered on before calling this function.
173  *
174  * @param[in] sensor The sensor instance to get status from
175  */
176 void acc_sensor_status(const acc_sensor_t *sensor);
177 
178 
179 /**
180  * @brief Prepare sensor for entering hibernation
181  *
182  * Prepare sensor for entering hibernation.
183  * Should be invoked prior to calling @ref acc_hal_integration_sensor_disable()
184  *
185  * @param[in] sensor The sensor to prepare for hibernation
186  * @return True if prepare was successful
187  */
189 
190 
191 /**
192  * @brief Restore sensor after exiting hibernation
193  *
194  * Restore sensor after exiting hibernation.
195  * Should be invoked after calling @ref acc_hal_integration_sensor_enable()
196  *
197  * @param[in] sensor The sensor to unprepare for hibernation
198  * @return True if unprepare was successful
199  */
200 bool acc_sensor_hibernate_off(const acc_sensor_t *sensor);
201 
202 
203 /**
204  * @brief Validate calibration result
205  *
206  * @param[in] cal_result Result of a calibration
207  *
208  * @return True if calibration is valid
209  */
210 bool acc_sensor_validate_calibration(const acc_cal_result_t *cal_result);
211 
212 
213 /**
214  * @}
215  */
216 
217 
218 #endif
acc_cal_info_t
Information about calibration.
Definition: acc_definitions_a121.h:40
acc_sensor_read
bool acc_sensor_read(const acc_sensor_t *sensor, void *buffer, uint32_t buffer_size)
Read out radar data.
acc_cal_result_t
The result from a completed calibration.
Definition: acc_definitions_a121.h:32
acc_sensor_validate_calibration
bool acc_sensor_validate_calibration(const acc_cal_result_t *cal_result)
Validate calibration result.
acc_sensor_hibernate_off
bool acc_sensor_hibernate_off(const acc_sensor_t *sensor)
Restore sensor after exiting hibernation.
acc_config_t
struct acc_config acc_config_t
Definition: acc_config.h:26
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_sensor_connected
bool acc_sensor_connected(acc_sensor_id_t sensor_id)
Check if a sensor is connected and responsive.
acc_sensor_id_t
uint32_t acc_sensor_id_t
Type representing a sensor ID.
Definition: acc_definitions_common.h:14
acc_sensor_hibernate_on
bool acc_sensor_hibernate_on(acc_sensor_t *sensor)
Prepare sensor for entering hibernation.
acc_sensor_status
void acc_sensor_status(const acc_sensor_t *sensor)
Check the status of the sensor.
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_definitions_common.h
acc_config.h
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.
acc_sensor_measure
bool acc_sensor_measure(acc_sensor_t *sensor)
Start a radar measurement with previously prepared configuration.
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
acc_sensor_create
acc_sensor_t * acc_sensor_create(acc_sensor_id_t sensor_id)
Create a sensor instance.