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
"
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 diagnostic 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 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.