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 */
47 acc_sensor_t *acc_sensor_create(acc_sensor_id_t sensor_id);
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 */
188 bool acc_sensor_hibernate_on(acc_sensor_t *sensor);
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
Definition: acc_definitions_a121.h:27
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
Definition: acc_definitions_a121.h:19
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.