1 /*
2  * Copyright (C) 2016 The Android Open Source Project
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  *      http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 
17 ///////////////////////////////////////////////////////////////
18 /*
19  * This module implements a sensor stillness detector with a
20  * look-ahead feature that allows the sensor's mean to be
21  * computed for an extended stillness period (one-pass, online
22  * method) sample by sample without a memory buffer. Stillness
23  * is computed using non-overlapping windows of signal variance
24  * and thresholding logic. The look-ahead feature ensures that
25  * the mean computation is not corrupted by the onset of sensor
26  * activity.
27  *
28  * NOTE - Time units are agnostic (i.e., determined by the
29  * user's application and usage). However, typical time units
30  * are nanoseconds.
31  */
32 ///////////////////////////////////////////////////////////////
33 #ifndef LOCATION_LBS_CONTEXTHUB_NANOAPPS_CALIBRATION_GYROSCOPE_GYRO_STILLNESS_DETECT_H_
34 #define LOCATION_LBS_CONTEXTHUB_NANOAPPS_CALIBRATION_GYROSCOPE_GYRO_STILLNESS_DETECT_H_
35 
36 #include <math.h>
37 #include <stdbool.h>
38 #include <stdint.h>
39 #include <stdio.h>
40 #include <string.h>
41 #include <sys/types.h>
42 
43 #ifdef __cplusplus
44 extern "C" {
45 #endif
46 
47 struct GyroStillDet {
48   // Variance threshold for the stillness confidence score.
49   float var_threshold;  // [sensor units]^2
50 
51   // Delta about the variance threshold for calculation of the
52   // stillness confidence score [0,1].
53   float confidence_delta;  // [sensor units]^2
54 
55   // Flag to indicate when enough samples have been collected for
56   // a complete stillness calculation.
57   bool stillness_window_ready;
58 
59   // Flag to signal the beginning of a new stillness detection window. This
60   // is used to keep track of the window start time.
61   bool start_new_window;
62 
63   // Starting time stamp for the current window.
64   uint64_t window_start_time;
65 
66   // Accumulator variables for tracking the sample mean during
67   // the stillness period.
68   uint32_t num_acc_samples;
69   float mean_x, mean_y, mean_z;
70 
71   // Accumulator variables for computing the window sample mean and
72   // variance for the current window (used for stillness detection).
73   uint32_t num_acc_win_samples;
74   float win_mean_x, win_mean_y, win_mean_z;
75   float assumed_mean_x, assumed_mean_y, assumed_mean_z;
76   float acc_var_x, acc_var_y, acc_var_z;
77 
78   // Stillness period mean (used for look-ahead).
79   float prev_mean_x, prev_mean_y, prev_mean_z;
80 
81   // Latest computed variance.
82   float win_var_x, win_var_y, win_var_z;
83 
84   // Stillness confidence score for current and previous sample
85   // windows [0,1] (used for look-ahead).
86   float stillness_confidence;
87   float prev_stillness_confidence;
88 
89   // Timestamp of last sample recorded.
90   uint64_t last_sample_time;
91 };
92 
93 /////// FUNCTION PROTOTYPES //////////////////////////////////////////
94 
95 // Initialize the gyro_still_det_t structure.
96 void gyroStillDetInit(struct GyroStillDet* gyro_still_det, float var_threshold,
97                       float confidence_delta);
98 
99 // Update the stillness detector with a new sample.
100 void gyroStillDetUpdate(struct GyroStillDet* gyro_still_det,
101                         uint64_t stillness_win_endtime, uint64_t sample_time,
102                         float x, float y, float z);
103 
104 // Calculates and returns the stillness confidence score [0,1].
105 float gyroStillDetCompute(struct GyroStillDet* gyro_still_det);
106 
107 // Resets the stillness detector and initiates a new detection window.
108 // 'reset_stats' determines whether the stillness statistics are reset.
109 void gyroStillDetReset(struct GyroStillDet* gyro_still_det, bool reset_stats);
110 
111 #ifdef __cplusplus
112 }
113 #endif
114 
115 #endif  // LOCATION_LBS_CONTEXTHUB_NANOAPPS_CALIBRATION_GYROSCOPE_GYRO_STILLNESS_DETECT_H_
116