acc_rss_a121.h
Go to the documentation of this file.
1 // Copyright (c) Acconeer AB, 2021-2023
2 // All rights reserved
3
4 #ifndef ACC_RSS_A121_H_
5 #define ACC_RSS_A121_H_
6
7 #include <stdbool.h>
8
9 #include "acc_config.h"
10 #include "acc_definitions_common.h"
11 #include "acc_hal_definitions_a121.h"
12
13
14 /**
15 * @defgroup rss RSS
16 *
17 * @brief RSS API description
18 *
19 * @{
20 */
21
22
23 /**
24 * @brief The minimum buffer size needed for the assembly test
25 *
26 */
27 #define ACC_RSS_ASSEMBLY_TEST_MIN_BUFFER_SIZE 4096U
28
29
30 /**
31 * @brief Return code for rss tests
32 *
33 */
34 typedef enum
35 {
36 /*! The test is ongoing, the application should call test function again */
37 ACC_RSS_TEST_STATE_ONGOING = 0,
38 /*! The application should toggle enable pin and then call test function again */
39 ACC_RSS_TEST_STATE_TOGGLE_ENABLE_PIN,
40 /*! The application should wait for interrupt and then call test function again */
41 ACC_RSS_TEST_STATE_WAIT_FOR_INTERRUPT,
42 /*! The test is complete */
43 ACC_RSS_TEST_STATE_COMPLETE,
44 } acc_rss_test_state_t;
45
46
47 /**
48 * @brief Integration status for rss tests
49 *
50 */
51 typedef enum
52 {
53 /*! The test status is OK */
54 ACC_RSS_TEST_INTEGRATION_STATUS_OK = 0,
55 /*! The test has timed out */
56 ACC_RSS_TEST_INTEGRATION_STATUS_TIMEOUT,
57 } acc_rss_test_integration_status_t;
58
59
60 /**
61 * @brief Test identity enum for acc_rss_assembly_test
62 *
63 */
64 typedef enum
65 {
66 /*! Test SPI basic read functionality. */
67 ACC_RSS_ASSEMBLY_TEST_ID_BASIC_READ,
68 /*! Test SPI communication. */
69 ACC_RSS_ASSEMBLY_TEST_ID_COMMUNICATION,
70 /*! Test enable pin. */
71 ACC_RSS_ASSEMBLY_TEST_ID_ENABLE_PIN,
72 /*! Test interrupt pin. */
73 ACC_RSS_ASSEMBLY_TEST_ID_INTERRUPT,
74 /*! Test clock and supply stability. */
75 ACC_RSS_ASSEMBLY_TEST_ID_CLOCK_AND_SUPPLY,
76 /*! Test sensor calibration. */
77 ACC_RSS_ASSEMBLY_TEST_ID_SENSOR_CALIBRATION,
78 } acc_rss_assembly_test_test_id_t;
79
80
81 /**
82 * @brief The result struct of acc_rss_assembly_test
83 *
84 */
85 typedef struct
86 {
87 const char *test_name;
88 bool test_result;
89 } acc_rss_assembly_test_result_t;
90
91
92 /**
93 * @brief The acc_rss_assembly_test instance
94 *
95 */
96 struct acc_rss_assembly_test;
97
98 typedef struct acc_rss_assembly_test acc_rss_assembly_test_t;
99
100
101 /**
102 * @brief Register an integration
103 *
104 * @param[in] hal A reference to the hal to register
105 * @return True if a valid integration is registered, false otherwise
106 */
107 bool acc_rss_hal_register(const acc_hal_a121_t *hal);
108
109
110 /**
111 * @brief Get the buffer size needed for the specified config
112 *
113 * This buffer size can be used to allocate a memory buffer in the
114 * application, which is needed for several functions in the RSS library.
115 *
116 * @param[in] config The config to get the buffer size for
117 * @param[out] buffer_size The buffer size
118 * @return True if successful, false otherwise
119 */
120 bool acc_rss_get_buffer_size(const acc_config_t *config, uint32_t *buffer_size);
121
122
123 /**
124 * @brief Set the log level that determines when the integration HAL logger function is called
125 *
126 * Shall be called when there is a hal registered in RSS as it has no effect otherwise.
127 *
128 * @param[in] level The severity level for log output.
129 */
130 void acc_rss_set_log_level(acc_log_level_t level);
131
132
133 /**
134 * @brief Create a sensor assembly test instance
135 *
136 * The assembly test instance is used to keep track of internal state and
137 * results of the assembly test.
138 *
139 * The provided buffer start address should be 32-bit aligned.
140 * The size of the provided buffer must be at least ACC_RSS_ASSEMBLY_TEST_MIN_BUFFER_SIZE bytes.
141 * The size of the provided buffer should be a multiple of 8 bytes.
142 * The test will not behave differently if a larger buffer is provided.
143 *
144 * All assembly tests are enabled by default after creation.
145 *
146 * @param[in] sensor_id The sensor id to be used to communicate with
147 * @param[in] buffer A buffer used for assembly test
148 * @param[in] buffer_size The size of the buffer
149 *
150 * @return Assembly test instance, NULL if the creation of the instance failed
151 */
152 acc_rss_assembly_test_t *acc_rss_assembly_test_create(acc_sensor_id_t sensor_id, void *buffer, uint32_t buffer_size);
153
154
155 /**
156 * @brief Destroy a sensor assembly test instance freeing any resources allocated.
157 *
158 * @param[in] assembly_test The assembly_test instance to destroy, can be NULL
159 */
160 void acc_rss_assembly_test_destroy(acc_rss_assembly_test_t *assembly_test);
161
162
163 /**
164 * @brief Enable disagnostic logs for the assembly test,
165 */
166 void acc_rss_assembly_test_enable_diagnostic_logs(void);
167
168
169 /**
170 * @brief Enable all assembly tests
171 *
172 * @param[in] assembly_test The assembly_test instance
173 */
174 void acc_rss_assembly_test_enable_all_tests(acc_rss_assembly_test_t *assembly_test);
175
176
177 /**
178 * @brief Disable all assembly tests
179 *
180 * @param[in] assembly_test The assembly_test instance
181 */
182 void acc_rss_assembly_test_disable_all_tests(acc_rss_assembly_test_t *assembly_test);
183
184
185 /**
186 * @brief Enable a test in assembly test
187 *
188 * @param[in] assembly_test The assembly_test instance
189 * @param[in] test_id The id of the test to be enabled
190 */
191 void acc_rss_assembly_test_enable(acc_rss_assembly_test_t *assembly_test, acc_rss_assembly_test_test_id_t test_id);
192
193
194 /**
195 * @brief Disable a test in assembly test
196 *
197 * @param[in] assembly_test The assembly_test instance
198 * @param[in] test_id The id of the test to be enabled
199 */
200 void acc_rss_assembly_test_disable(acc_rss_assembly_test_t *assembly_test, acc_rss_assembly_test_test_id_t test_id);
201
202
203 /**
204 * @brief Execute the assembly test
205 *
206 * The sensor must be powered on and enabled before this function is called.
207 *
208 * The function should be called repeatedly until it returns ACC_RSS_TEST_STATE_COMPLETE.
209 * If the function returns ACC_RSS_TEST_STATE_TOGGLE_ENABLE_PIN the caller should toggle the
210 * enable pin to reset the sensor and then call @ref acc_rss_assembly_test_execute() again.
211 * If the function returns ACC_RSS_TEST_STATE_WAIT_FOR_INTERRUPT the caller have to wait for
212 * the interrupt pin before calling @ref acc_rss_assembly_test_execute() again.
213 *
214 * After assembly test has been run the sensor enable pin should be toggled to reset the sensor.
215 *
216 * @param[in, out] assembly_test The sensor assembly test instance
217 * @param[in] integration_status Report back to assembly test if 'wait for interrupt' timed out
218 * @return ACC_RSS_TEST_STATE_ONGOING if caller should call this function again.
219 * ACC_RSS_TEST_STATE_TOGGLE_ENABLE_PIN if caller should toggle the enable pin.
220 * ACC_RSS_TEST_STATE_WAIT_FOR_INTERRUPT if caller should wait for interrupt pin.
221 * or ACC_RSS_TEST_STATE_COMPLETE if the assembly test is complete.
222 */
223 acc_rss_test_state_t acc_rss_assembly_test_execute(acc_rss_assembly_test_t *assembly_test,
224 acc_rss_test_integration_status_t integration_status);
225
226
227 /**
228 * @brief A function to get the results from the sensor assembly test
229 *
230 * @param[in] assembly_test The sensor assembly test instance
231 * @param[out] nbr_of_test_results The number of test results returned
232 * @return The assembly test result array
233 */
234 const acc_rss_assembly_test_result_t *acc_rss_assembly_test_get_results(const acc_rss_assembly_test_t *assembly_test,
235 uint16_t *nbr_of_test_results);
236
237
238 /**
239 * @}
240 */
241
242
243 #endif
ACC_RSS_TEST_STATE_WAIT_FOR_INTERRUPT
@ ACC_RSS_TEST_STATE_WAIT_FOR_INTERRUPT
Definition: acc_rss_a121.h:41
acc_rss_assembly_test_result_t
The result struct of acc_rss_assembly_test.
Definition: acc_rss_a121.h:85
acc_rss_assembly_test_execute
acc_rss_test_state_t acc_rss_assembly_test_execute(acc_rss_assembly_test_t *assembly_test, acc_rss_test_integration_status_t integration_status)
Execute the assembly test.
acc_rss_assembly_test_get_results
const acc_rss_assembly_test_result_t * acc_rss_assembly_test_get_results(const acc_rss_assembly_test_t *assembly_test, uint16_t *nbr_of_test_results)
A function to get the results from the sensor assembly test.
ACC_RSS_ASSEMBLY_TEST_ID_ENABLE_PIN
@ ACC_RSS_ASSEMBLY_TEST_ID_ENABLE_PIN
Definition: acc_rss_a121.h:71
ACC_RSS_ASSEMBLY_TEST_ID_CLOCK_AND_SUPPLY
@ ACC_RSS_ASSEMBLY_TEST_ID_CLOCK_AND_SUPPLY
Definition: acc_rss_a121.h:75
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_RSS_ASSEMBLY_TEST_ID_BASIC_READ
@ ACC_RSS_ASSEMBLY_TEST_ID_BASIC_READ
Definition: acc_rss_a121.h:67
ACC_RSS_TEST_INTEGRATION_STATUS_TIMEOUT
@ ACC_RSS_TEST_INTEGRATION_STATUS_TIMEOUT
Definition: acc_rss_a121.h:56
acc_rss_assembly_test_enable_diagnostic_logs
void acc_rss_assembly_test_enable_diagnostic_logs(void)
Enable disagnostic logs for the assembly test,.
ACC_RSS_ASSEMBLY_TEST_ID_SENSOR_CALIBRATION
@ ACC_RSS_ASSEMBLY_TEST_ID_SENSOR_CALIBRATION
Definition: acc_rss_a121.h:77
acc_rss_assembly_test_destroy
void acc_rss_assembly_test_destroy(acc_rss_assembly_test_t *assembly_test)
Destroy a sensor assembly test instance freeing any resources allocated.
acc_hal_a121_t
Definition: acc_hal_definitions_a121.h:82
acc_log_level_t
acc_log_level_t
This enum represents the different log levels for RSS.
Definition: acc_definitions_common.h:25
acc_rss_hal_register
bool acc_rss_hal_register(const acc_hal_a121_t *hal)
Register an integration.
ACC_RSS_TEST_INTEGRATION_STATUS_OK
@ ACC_RSS_TEST_INTEGRATION_STATUS_OK
Definition: acc_rss_a121.h:54
acc_rss_assembly_test_create
acc_rss_assembly_test_t * acc_rss_assembly_test_create(acc_sensor_id_t sensor_id, void *buffer, uint32_t buffer_size)
Create a sensor assembly test instance.
ACC_RSS_TEST_STATE_ONGOING
@ ACC_RSS_TEST_STATE_ONGOING
Definition: acc_rss_a121.h:37
acc_rss_assembly_test_enable_all_tests
void acc_rss_assembly_test_enable_all_tests(acc_rss_assembly_test_t *assembly_test)
Enable all assembly tests.
acc_rss_set_log_level
void acc_rss_set_log_level(acc_log_level_t level)
Set the log level that determines when the integration HAL logger function is called.
acc_config_t
struct acc_config acc_config_t
Definition: acc_config.h:26
acc_rss_assembly_test_result_t::test_result
bool test_result
Definition: acc_rss_a121.h:88
acc_hal_definitions_a121.h
ACC_RSS_TEST_STATE_COMPLETE
@ ACC_RSS_TEST_STATE_COMPLETE
Definition: acc_rss_a121.h:43
ACC_RSS_ASSEMBLY_TEST_ID_COMMUNICATION
@ ACC_RSS_ASSEMBLY_TEST_ID_COMMUNICATION
Definition: acc_rss_a121.h:69
acc_rss_assembly_test_result_t::test_name
const char * test_name
Definition: acc_rss_a121.h:87
acc_rss_test_state_t
acc_rss_test_state_t
Return code for rss tests.
Definition: acc_rss_a121.h:34
acc_rss_assembly_test_disable
void acc_rss_assembly_test_disable(acc_rss_assembly_test_t *assembly_test, acc_rss_assembly_test_test_id_t test_id)
Disable a test in assembly test.
acc_sensor_id_t
uint32_t acc_sensor_id_t
Type representing a sensor ID.
Definition: acc_definitions_common.h:14
acc_rss_test_integration_status_t
acc_rss_test_integration_status_t
Integration status for rss tests.
Definition: acc_rss_a121.h:51
acc_rss_assembly_test_t
struct acc_rss_assembly_test acc_rss_assembly_test_t
Definition: acc_rss_a121.h:98
acc_rss_assembly_test_test_id_t
acc_rss_assembly_test_test_id_t
Test identity enum for acc_rss_assembly_test.
Definition: acc_rss_a121.h:64
acc_rss_assembly_test_disable_all_tests
void acc_rss_assembly_test_disable_all_tests(acc_rss_assembly_test_t *assembly_test)
Disable all assembly tests.
ACC_RSS_TEST_STATE_TOGGLE_ENABLE_PIN
@ ACC_RSS_TEST_STATE_TOGGLE_ENABLE_PIN
Definition: acc_rss_a121.h:39
acc_definitions_common.h
ACC_RSS_ASSEMBLY_TEST_ID_INTERRUPT
@ ACC_RSS_ASSEMBLY_TEST_ID_INTERRUPT
Definition: acc_rss_a121.h:73
acc_config.h
acc_rss_assembly_test_enable
void acc_rss_assembly_test_enable(acc_rss_assembly_test_t *assembly_test, acc_rss_assembly_test_test_id_t test_id)
Enable a test in assembly test.