| blob | 4708dc7db31a6bf0d00a2e6b35f36f67eda914ea |
1 /**
2 * Copyright (c) 2020 Bosch Sensortec GmbH. All rights reserved.
3 *
4 * BSD-3-Clause
5 *
6 * Redistribution and use in source and binary forms, with or without
7 * modification, are permitted provided that the following conditions are met:
8 *
9 * 1. Redistributions of source code must retain the above copyright
10 * notice, this list of conditions and the following disclaimer.
11 *
12 * 2. Redistributions in binary form must reproduce the above copyright
13 * notice, this list of conditions and the following disclaimer in the
14 * documentation and/or other materials provided with the distribution.
15 *
16 * 3. Neither the name of the copyright holder nor the names of its
17 * contributors may be used to endorse or promote products derived from
18 * this software without specific prior written permission.
19 *
20 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
21 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
22 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
23 * FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
24 * COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
25 * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
26 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
27 * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
28 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
29 * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
30 * IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
31 * POSSIBILITY OF SUCH DAMAGE.
32 *
33 * @file bmi270_context.h
34 * @date 2020-11-04
35 * @version v2.63.1
36 *
37 */
39 /**
40 * \ingroup bmi2xy
41 * \defgroup bmi270_context BMI270_CONTEXT
42 * @brief Sensor driver for BMI270_CONTEXT sensor
43 */
45 #ifndef BMI270_CONTEXT_H_
46 #define BMI270_CONTEXT_H_
48 /*! CPP guard */
49 #ifdef __cplusplus
51 #endif
53 /***************************************************************************/
55 /*! Header files
56 ****************************************************************************/
59 /***************************************************************************/
61 /*! Macro definitions
62 ****************************************************************************/
64 /*! @name BMI270_CONTEXT Chip identifier */
65 #define BMI270_CONTEXT_CHIP_ID UINT8_C(0x24)
67 /*! @name BMI270_CONTEXT feature input start addresses */
68 #define BMI270_CONTEXT_CONFIG_ID_STRT_ADDR UINT8_C(0x06)
69 #define BMI270_CONTEXT_STEP_CNT_1_STRT_ADDR UINT8_C(0x00)
70 #define BMI270_CONTEXT_STEP_CNT_4_STRT_ADDR UINT8_C(0x02)
71 #define BMI270_CONTEXT_MAX_BURST_LEN_STRT_ADDR UINT8_C(0x08)
72 #define BMI270_CONTEXT_CRT_GYRO_SELF_TEST_STRT_ADDR UINT8_C(0x09)
73 #define BMI270_CONTEXT_ABORT_STRT_ADDR UINT8_C(0x09)
74 #define BMI270_CONTEXT_NVM_PROG_PREP_STRT_ADDR UINT8_C(0x0A)
75 #define BMI270_CONTEXT_ACT_RGN_SETT_STRT_ADDR UINT8_C(0x00)
76 #define BMI270_CONTEXT_ACT_RGN_STRT_ADDR UINT8_C(0x0A)
78 /*! @name BMI270_CONTEXT feature output start addresses */
79 #define BMI270_CONTEXT_STEP_CNT_OUT_STRT_ADDR UINT8_C(0x00)
80 #define BMI270_CONTEXT_GYR_USER_GAIN_OUT_STRT_ADDR UINT8_C(0x04)
81 #define BMI270_CONTEXT_GYRO_CROSS_SENSE_STRT_ADDR UINT8_C(0x0C)
82 #define BMI270_CONTEXT_NVM_VFRM_OUT_STRT_ADDR UINT8_C(0x0E)
84 /*! @name Defines maximum number of pages */
85 #define BMI270_CONTEXT_MAX_PAGE_NUM UINT8_C(8)
87 /*! @name Defines maximum number of feature input configurations */
88 #define BMI270_CONTEXT_MAX_FEAT_IN UINT8_C(10)
90 /*! @name Defines maximum number of feature outputs */
91 #define BMI270_CONTEXT_MAX_FEAT_OUT UINT8_C(5)
93 /*! @name Mask definitions for feature interrupt status bits */
94 #define BMI270_CONTEXT_STEP_CNT_STATUS_MASK UINT8_C(0x01)
96 /*! @name Mask definitions for feature interrupt mapping bits */
97 #define BMI270_C_INT_STEP_COUNTER_MASK UINT8_C(0x01)
98 #define BMI270_C_INT_STEP_DETECTOR_MASK UINT8_C(0x01)
100 /*! @name Defines maximum number of feature interrupts */
101 #define BMI270_C_MAX_INT_MAP UINT8_C(2)
103 /***************************************************************************/
105 /*! BMI270_CONTEXT User Interface function prototypes
106 ****************************************************************************/
108 /**
109 * \ingroup bmi270_context
110 * \defgroup bmi270_contextApiInit Initialization
111 * @brief Initialize the sensor and device structure
112 */
114 /*!
115 * \ingroup bmi270_contextApiInit
116 * \page bmi270_context_api_bmi270_context_init bmi270_context_init
117 * \code
118 * int8_t bmi270_context_init(struct bmi2_dev *dev);
119 * \endcode
120 * @details This API:
121 * 1) updates the device structure with address of the configuration file.
122 * 2) Initializes BMI270_CONTEXT sensor.
123 * 3) Writes the configuration file.
124 * 4) Updates the feature offset parameters in the device structure.
125 * 5) Updates the maximum number of pages, in the device structure.
126 *
127 * @param[in, out] dev : Structure instance of bmi2_dev.
128 *
129 * @return Result of API execution status
130 * @retval 0 -> Success
131 * @retval < 0 -> Fail
132 */
135 /**
136 * \ingroup bmi270_context
137 * \defgroup bmi270_contextApiSensor Feature Set
138 * @brief Enable / Disable features of the sensor
139 */
141 /*!
142 * \ingroup bmi270_contextApiSensor
143 * \page bmi270_context_api_bmi270_context_sensor_enable bmi270_context_sensor_enable
144 * \code
145 * int8_t bmi270_context_sensor_enable(const uint8_t *sens_list, uint8_t n_sens, struct bmi2_dev *dev);
146 * \endcode
147 * @details This API selects the sensors/features to be enabled.
148 *
149 * @param[in] sens_list : Pointer to select the sensor/feature.
150 * @param[in] n_sens : Number of sensors selected.
151 * @param[in, out] dev : Structure instance of bmi2_dev.
152 *
153 * @note Sensors/features that can be enabled.
154 *
155 *@verbatim
156 * sens_list | Values
157 * ----------------------------|-----------
158 * BMI2_ACCEL | 0
159 * BMI2_GYRO | 1
160 * BMI2_AUX | 2
161 * BMI2_STEP_DETECTOR | 6
162 * BMI2_STEP_COUNTER | 7
163 * BMI2_GYRO_GAIN_UPDATE | 9
164 * BMI2_ACTIVITY_RECOGNITION | 34
165 *@endverbatim
166 *
167 * @note :
168 * example uint8_t sens_list[2] = {BMI2_ACCEL, BMI2_GYRO};
169 * uint8_t n_sens = 2;
170 *
171 * @return Result of API execution status
172 * @retval 0 -> Success
173 * @retval < 0 -> Fail
174 */
175 int8_t bmi270_context_sensor_enable(const uint8_t *sens_list, uint8_t n_sens, struct bmi2_dev *dev);
177 /*!
178 * \ingroup bmi270_contextApiSensor
179 * \page bmi270_context_api_bmi270_context_sensor_disable bmi270_context_sensor_disable
180 * \code
181 * int8_t bmi270_context_sensor_disable(const uint8_t *sens_list, uint8_t n_sens, struct bmi2_dev *dev);
182 * \endcode
183 * @details This API selects the sensors/features to be disabled.
184 *
185 * @param[in] sens_list : Pointer to select the sensor/feature.
186 * @param[in] n_sens : Number of sensors selected.
187 * @param[in, out] dev : Structure instance of bmi2_dev.
188 *
189 * @note Sensors/features that can be disabled.
190 *
191 *@verbatim
192 * sens_list | Values
193 * ----------------------------|-----------
194 * BMI2_ACCEL | 0
195 * BMI2_GYRO | 1
196 * BMI2_AUX | 2
197 * BMI2_STEP_DETECTOR | 6
198 * BMI2_STEP_COUNTER | 7
199 * BMI2_GYRO_GAIN_UPDATE | 9
200 * BMI2_ACTIVITY_RECOGNITION | 34
201 *@endverbatim
202 *
203 * @note :
204 * example uint8_t sens_list[2] = {BMI2_ACCEL, BMI2_GYRO};
205 * uint8_t n_sens = 2;
206 *
207 * @return Result of API execution status
208 * @retval 0 -> Success
209 * @retval < 0 -> Fail
210 */
211 int8_t bmi270_context_sensor_disable(const uint8_t *sens_list, uint8_t n_sens, struct bmi2_dev *dev);
213 /**
214 * \ingroup bmi270_context
215 * \defgroup bmi270_contextApiSensorC Sensor Configuration
216 * @brief Enable / Disable feature configuration of the sensor
217 */
219 /*!
220 * \ingroup bmi270_contextApiSensorC
221 * \page bmi270_context_api_bmi270_context_set_sensor_config bmi270_context_set_sensor_config
222 * \code
223 * int8_t bmi270_context_set_sensor_config(struct bmi2_sens_config *sens_cfg, uint8_t n_sens, struct bmi2_dev *dev);
224 * \endcode
225 * @details This API sets the sensor/feature configuration.
226 *
227 * @param[in] sens_cfg : Structure instance of bmi2_sens_config.
228 * @param[in] n_sens : Number of sensors selected.
229 * @param[in, out] dev : Structure instance of bmi2_dev.
230 *
231 * @note Sensors/features that can be configured
232 *
233 *@verbatim
234 * sens_list | Values
235 * ----------------------------|-----------
236 * BMI2_STEP_DETECTOR | 6
237 * BMI2_STEP_COUNTER | 7
238 * BMI2_STEP_COUNTER_PARAMS | 28
239 *@endverbatim
240 *
241 * @return Result of API execution status
242 * @retval 0 -> Success
243 * @retval < 0 -> Fail
244 */
245 int8_t bmi270_context_set_sensor_config(struct bmi2_sens_config *sens_cfg, uint8_t n_sens, struct bmi2_dev *dev);
247 /*!
248 * \ingroup bmi270_contextApiSensorC
249 * \page bmi270_context_api_bmi270_context_get_sensor_config bmi270_context_get_sensor_config
250 * \code
251 * int8_t bmi270_context_get_sensor_config(struct bmi2_sens_config *sens_cfg, uint8_t n_sens, struct bmi2_dev *dev);
252 * \endcode
253 * @details This API gets the sensor/feature configuration.
254 *
255 * @param[in] sens_cfg : Structure instance of bmi2_sens_config.
256 * @param[in] n_sens : Number of sensors selected.
257 * @param[in, out] dev : Structure instance of bmi2_dev.
258 *
259 * @note Sensors/features whose configurations can be read.
260 *
261 *@verbatim
262 * sens_list | Values
263 * ----------------------------|-----------
264 * BMI2_STEP_DETECTOR | 6
265 * BMI2_STEP_COUNTER | 7
266 * BMI2_STEP_COUNTER_PARAMS | 28
267 *@endverbatim
268 *
269 * @return Result of API execution status
270 * @retval 0 -> Success
271 * @retval < 0 -> Fail
272 */
273 int8_t bmi270_context_get_sensor_config(struct bmi2_sens_config *sens_cfg, uint8_t n_sens, struct bmi2_dev *dev);
275 /**
276 * \ingroup bmi270_context
277 * \defgroup bmi270_contextApiSensorD Sensor Data
278 * @brief Get sensor data
279 */
281 /*!
282 * \ingroup bmi270_contextApiSensorD
283 * \page bmi270_context_api_bmi270_context_get_sensor_data bmi270_context_get_sensor_data
284 * \code
285 * int8_t bmi270_context_get_sensor_data(struct bmi2_sensor_data *sensor_data, uint8_t n_sens, struct bmi2_dev *dev);
286 * \endcode
287 * @details This API gets the sensor/feature data for accelerometer, gyroscope,
288 * auxiliary sensor, step counter, high-g, gyroscope user-gain update,
289 * orientation, gyroscope cross sensitivity and error status for NVM and VFRM.
290 *
291 * @param[out] sensor_data : Structure instance of bmi2_sensor_data.
292 * @param[in] n_sens : Number of sensors selected.
293 * @param[in] dev : Structure instance of bmi2_dev.
294 *
295 * @note Sensors/features whose data can be read
296 *
297 *@verbatim
298 * sens_list | Values
299 * ---------------------|-----------
300 * BMI2_STEP_COUNTER | 7
301 * BMI2_NVM_STATUS | 38
302 * BMI2_VFRM_STATUS | 39
303 *@endverbatim
304 *
305 * @return Result of API execution status
306 * @retval 0 -> Success
307 * @retval < 0 -> Fail
308 */
309 int8_t bmi270_context_get_sensor_data(struct bmi2_sensor_data *sensor_data, uint8_t n_sens, struct bmi2_dev *dev);
311 /**
312 * \ingroup bmi270_context
313 * \defgroup bmi270_contextApiARecog Activity recognition settings
314 * @brief Set / Get activity recognition settings of the sensor
315 */
317 /*!
318 * \ingroup bmi270_contextApiARecog
319 * \page bmi270_context_api_bmi270_context_get_act_recg_sett bmi270_context_get_act_recg_sett
320 * \code
321 * int8_t bmi270_context_get_act_recg_sett(struct bmi2_act_recg_sett *sett, struct bmi2_dev *dev);
322 * \endcode
323 * @details This api is used for retrieving the following activity recognition settings currently set.
324 * enable/disable post processing(0/1) by default -> 1(enable),
325 * Setting the min & max Gini's diversity index (GDI) threshold. min_GDI_tres(0-0XFFFF) by default ->(0x06e1)
326 * max_GDI_tres(0-0xFFFF) by default ->(0x0A66)
327 * buffer size for post processing. range (1-0x0A) default -> (0x0A)
328 * min segment confidence. range (1-0x0A) default -> (0x0A)
329 *
330 * @param[in] sett : Structure instance of bmi2_act_recg_sett.
331 * @param[in] dev : Structure instance of bmi2_dev.
332 *
333 * @return Result of API execution status
334 * @retval 0 -> Success
335 * @retval < 0 -> Fail
336 */
339 /*!
340 * \ingroup bmi270_contextApiARecog
341 * \page bmi270_context_api_bmi270_context_set_act_recg_sett bmi270_context_set_act_recg_sett
342 * \code
343 * int8_t bmi270_context_set_act_recg_sett(const struct bmi2_act_recg_sett *sett, struct bmi2_dev *dev);
344 * \endcode
345 * @details This api is used for setting the following activity recognition settings
346 * enable/disable post processing(0/1) by default -> 1(enable),
347 * Setting the min & max Gini's diversity index (GDI) threshold. min_GDI_tres(0-0XFFFF) by default ->(0x06e1)
348 * max_GDI_tres(0-0xFFFF) by default ->(0x0A66)
349 * buffer size for post processing. range (1-0x0A) default -> (0x0A)
350 * min segment confidence. range (1-0x0A) default -> (0x0A)
351 *
352 * @param[in] sett : Structure instance of bmi2_act_recg_sett.
353 * @param[in] dev : Structure instance of bmi2_dev.
354 *
355 * @return Result of API execution status
356 * @retval 0 -> Success
357 * @retval < 0 -> Fail
358 */
359 int8_t bmi270_context_set_act_recg_sett(const struct bmi2_act_recg_sett *sett, struct bmi2_dev *dev);
361 /**
362 * \ingroup bmi270_contex
363 * \defgroup bmi270_contextApiactOut Activity Output
364 * @brief Activity output operations of the sensor
365 */
367 /*!
368 * \ingroup bmi270_contextApiactOut
369 * \page bmi270_context_api_bmi270_context_get_act_recog_output bmi270_context_get_act_recog_output
370 * \code
371 * int8_t bmi270_context_get_act_recog_output(struct bmi2_act_recog_output *act_recog,
372 * uint16_t *act_frm_len,
373 * struct bmi2_fifo_frame *fifo,
374 * const struct bmi2_dev *dev);
375 *
376 * \endcode
377 * @details This internal API is used to parse the activity output from the
378 * FIFO in header mode.
379 *
380 * @param[out] act_recog : Pointer to buffer where the parsed activity data
381 * bytes are stored.
382 * @param[in] act_frm_len : Number of activity frames parsed.
383 * @param[in] fifo : Structure instance of bmi2_fifo_frame.
384 * @param[in] dev : Structure instance of bmi2_dev.
385 *
386 * @verbatim
387 * ----------------------------------------------------------------------------
388 * bmi2_act_rec_output |
389 * Structure parameters | Description
390 *--------------------------|--------------------------------------------------
391 * time_stamp | time-stamp (expressed in 50Hz ticks)
392 * -------------------------|---------------------------------------------------
393 * type | Type of activity
394 * -------------------------|---------------------------------------------------
395 * stat | Activity status
396 * -------------------------|---------------------------------------------------
397 * @endverbatim
398 *
399 *@verbatim
400 * type | Activities
401 *----------|---------------------
402 * 0 | UNKNOWN
403 * 1 | STILL
404 * 2 | WALK
405 * 3 | RUN
406 * 4 | BIKE
407 * 5 | VEHICLE
408 * 6 | TILTED
409 *@endverbatim
410 *
411 *
412 *@verbatim
413 * stat | Activity status
414 *----------|---------------------
415 * 1 | START
416 * 2 | END
417 *@endverbatim
418 *
419 * @return Result of API execution status
420 * @retval 0 -> Success
421 * @retval < 0 -> Fail
422 */
428 /**
429 * \ingroup bmi270_contex
430 * \defgroup bmi270_contextApiGyroUG Gyro User Gain
431 * @brief Set / Get Gyro User Gain of the sensor
432 */
434 /*!
435 * \ingroup bmi270_contextApiGyroUG
436 * \page bmi270_context_api_bmi270_context_update_gyro_user_gain bmi270_context_update_gyro_user_gain
437 * \code
438 * int8_t bmi270_context_update_gyro_user_gain(const struct bmi2_gyro_user_gain_config *user_gain, struct bmi2_dev *dev);
439 * \endcode
440 * @details This API updates the gyroscope user-gain.
441 *
442 * @param[in] user_gain : Structure that stores user-gain configurations.
443 * @param[in] dev : Structure instance of bmi2_dev.
444 *
445 * @return Result of API execution status
446 * @retval 0 -> Success
447 * @retval < 0 -> Fail
448 */
449 int8_t bmi270_context_update_gyro_user_gain(const struct bmi2_gyro_user_gain_config *user_gain, struct bmi2_dev *dev);
451 /*!
452 * \ingroup bmi270_contextApiGyroUG
453 * \page bmi270_context_api_bmi270_context_read_gyro_user_gain bmi270_context_read_gyro_user_gain
454 * \code
455 * int8_t bmi270_context_read_gyro_user_gain(struct bmi2_gyro_user_gain_data *gyr_usr_gain, const struct bmi2_dev *dev);
456 * \endcode
457 * @details This API reads the compensated gyroscope user-gain values.
458 *
459 * @param[out] gyr_usr_gain : Structure that stores gain values.
460 * @param[in] dev : Structure instance of bmi2_dev.
461 *
462 * @return Result of API execution status
463 * @retval 0 -> Success
464 * @retval < 0 -> Fail
465 */
466 int8_t bmi270_context_read_gyro_user_gain(struct bmi2_gyro_user_gain_data *gyr_usr_gain, struct bmi2_dev *dev);
468 /*!
469 * \ingroup bmi270_contextApiInt
470 * \page bmi270_context_api_bmi270_context_map_feat_int bmi270_context_map_feat_int
471 * \code
472 * int8_t bmi270_context_map_feat_int(const struct bmi2_sens_int_config *sens_int, uint8_t n_sens, struct bmi2_dev *dev)
473 * \endcode
474 * @details This API maps/unmaps feature interrupts to that of interrupt pins.
475 *
476 * @param[in] sens_int : Structure instance of bmi2_sens_int_config.
477 * @param[in] n_sens : Number of interrupts to be mapped.
478 * @param[in] dev : Structure instance of bmi2_dev.
479 *
480 * @return Result of API execution status
481 * @retval 0 -> Success
482 * @retval < 0 -> Fail
483 */
484 int8_t bmi270_context_map_feat_int(const struct bmi2_sens_int_config *sens_int, uint8_t n_sens, struct bmi2_dev *dev);
486 /******************************************************************************/
487 /*! @name C++ Guard Macros */
488 /******************************************************************************/
489 #ifdef __cplusplus
490 }