acc_rss_a121.h
Go to the documentation of this file.
1 // Copyright (c) Acconeer AB, 2021-2024
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"
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 */
38  /*! The application should toggle enable pin and then call test function again */
40  /*! The application should wait for interrupt and then call test function again */
42  /*! The test is complete */
45 
46 
47 /**
48  * @brief Integration status for rss tests
49  *
50  */
51 typedef enum
52 {
53  /*! The test status is OK */
55  /*! The test has timed out */
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. */
68  /*! Test SPI communication. */
70  /*! Test enable pin. */
72  /*! Test interrupt pin. */
74  /*! Test clock and supply stability. */
76  /*! Test sensor calibration. */
79 
80 
81 /**
82  * @brief The result struct of acc_rss_assembly_test
83  *
84  */
85 typedef struct
86 {
87  const char *test_name;
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  */
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  */
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  */
161 
162 
163 /**
164  * @brief Enable diagnostic logs for the assembly test,
165  */
167 
168 
169 /**
170  * @brief Enable all assembly tests
171  *
172  * @param[in] assembly_test The assembly_test instance
173  */
175 
176 
177 /**
178  * @brief Disable all assembly tests
179  *
180  * @param[in] assembly_test The assembly_test instance
181  */
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  */
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  */
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  */
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  */
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 diagnostic 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
hal
static const acc_hal_a121_t hal
Definition: acc_hal_integration_espidf_xe121.c:121
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.