1 /* 2 * Copyright (C) 2017 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 #ifndef ASH_H_ 18 #define ASH_H_ 19 20 /** 21 * @file 22 * Defines the interface for the Android Sensor Hub support. 23 * These APIs are only accessible to system nanoapps and allow them to interact 24 * with the underlying sensor framework. 25 * These APIs are not part of the CHRE API and their support is optional. 26 */ 27 28 #include <stdbool.h> 29 #include <stddef.h> 30 #include <stdint.h> 31 32 #ifdef __cplusplus 33 extern "C" { 34 #endif 35 36 /** 37 * The values returned by this sensor cannot be trusted, calibration is needed 38 * or the environment doesn't allow readings. 39 */ 40 #define ASH_CAL_ACCURACY_UNRELIABLE UINT8_C(0) 41 42 /** 43 * This sensor is reporting data with low accuracy, calibration with the 44 * environment is needed. 45 */ 46 #define ASH_CAL_ACCURACY_LOW UINT8_C(1) 47 48 /** 49 * This sensor is reporting data with an average level of accuracy, calibration 50 * with the environment may improve the readings. 51 */ 52 #define ASH_CAL_ACCURACY_MEDIUM UINT8_C(2) 53 54 /** 55 * This sensor is reporting data with maximum accuracy. 56 */ 57 #define ASH_CAL_ACCURACY_HIGH UINT8_C(3) 58 59 /** 60 * Calibration info for a sensor which reports on a maximum of three axes. 61 * 62 * Let Su be the uncalibrated sensor data and Sc the calibrated one, 63 * Sc = compMatrix * (Su - bias) 64 * 65 */ 66 struct ashCalInfo { 67 /** 68 * The zero-bias vector in the x, y, z order. If the sensor reports on N 69 * axes with N < 3, only the first N elements are considered valid. 70 */ 71 float bias[3]; 72 73 /** 74 * The compensation matrix in the row major order. If the sensor reports on N 75 * axes with N < 3, only the first N elements of each row are considered 76 * valid. 77 */ 78 float compMatrix[9]; 79 80 /** 81 * One of the ASH_CAL_ACCURACY_* constants. This corresponds to the 82 * definition in the Android SensorManager. See 83 * https://developer.android.com/reference/android/hardware/SensorEvent.html#accuracy 84 * for more details. 85 * Note that this accuracy field is simply a suggestion to the platform and 86 * the platform can ignore or over-write it. 87 */ 88 uint8_t accuracy; 89 }; 90 91 //! This is used to indicate the persistent storage of the ASH implementaion. 92 #define ASH_CAL_STORAGE_ASH UINT8_C(0) 93 94 //! This is used to indicate the persistent storage in the sensor registry. 95 #define ASH_CAL_STORAGE_SNS UINT8_C(1) 96 97 //! Interval between cal params storage when AP is up, in usec. 98 #define ASH_CAL_SAVE_INTERVAL_USEC UINT64_C(300000000) 99 100 //! This is used to indicate that the cal params are invalid. 101 #define ASH_CAL_PARAMS_SOURCE_NONE UINT8_C(0) 102 103 //! This is used to indicate that the cal params were set by factory 104 //! calibration. 105 #define ASH_CAL_PARAMS_SOURCE_FACTORY UINT8_C(1) 106 107 //! This is used to indicate that the cal params were set by runtime 108 //! calibration. 109 #define ASH_CAL_PARAMS_SOURCE_RUNTIME UINT8_C(2) 110 111 /** 112 * A struct for calibration parameters to be saved to and loaded from a 113 * persistent area. The source of each section is indicated by the 114 * corresponding *Source field, which is one of the ASH_CAL_PARAMS_SOURCE_* 115 * constants. 116 */ 117 struct ashCalParams { 118 //! The offset of the sensor in the x, y and z axis at temperature 119 //! offsetTempCelsius. 120 float offset[3]; 121 122 //! The temperature at which last offset was updated. 123 float offsetTempCelsius; 124 125 //! The temperature sensitivity of offset. 126 float tempSensitivity[3]; 127 128 //! The estimated offset at zero degree Celsius. 129 float tempIntercept[3]; 130 131 //! The scale factor of the x, y and z axis. 132 float scaleFactor[3]; 133 134 //! The cross-axis factor in the [yx, zx, zy] order. 135 float crossAxis[3]; 136 137 //! The source of offset[3] 138 uint8_t offsetSource; 139 140 //! The source of offsetTempCelsius 141 uint8_t offsetTempCelsiusSource; 142 143 //! The source of tempSensitivity[3] 144 uint8_t tempSensitivitySource; 145 146 //! The source of tempIntercept[3] 147 uint8_t tempInterceptSource; 148 149 uint8_t scaleFactorSource; 150 151 //! The source of crossAxis[3] 152 uint8_t crossAxisSource; 153 }; 154 155 /** 156 * Updates the runtime calibration info of a given sensor type for the platform 157 * to compensate for. The calibration will be applied on top of the sensor's 158 * factory calibration if present. 159 * 160 * @param sensorType One of the CHRE_SENSOR_TYPE_* constants. 161 * @param calInfo A non-null pointer to ashCalInfo to update the sensor's 162 calibration. 163 * @return true if the calibration info has been successfully updated. 164 */ 165 bool ashSetCalibration(uint8_t sensorType, const struct ashCalInfo *calInfo); 166 167 /** 168 * Loads the stored cal params from the specified storage area. 169 * 170 * If ASH_CAL_STORAGE_SNS is specified as the storage area, it reads from the 171 * sensor registry with factory cal params. This should only be used for 172 * debugging as it can wake up the AP. 173 * 174 * If ASH_CAL_STORAGE_ASH is specified as the storage area, the stored cal 175 * params in the ASH storage are provided if they exist. Otherwise, the sensor 176 * registry cal params are provided instead. 177 * 178 * @param sensorType One of the CHRE_SENSOR_TYPE_* constants. 179 * @param storage Either ASH_CAL_STORAGE_ASH or ASH_CAL_STORAGE_SNS. 180 * @param params A non-null pointer to a ashCalParams that the cal params will 181 * be populated to. 182 * 183 * @return true if the cal params have been successfully populated to the 184 * provided memory. 185 */ 186 bool ashLoadCalibrationParams(uint8_t sensorType, uint8_t storage, 187 struct ashCalParams *params); 188 189 /** 190 * Saves the cal params to a local cache, and saves to ASH's persistent storage 191 * area when the AP wakes up, or when the AP is up and it has been 192 * ASH_CAL_SAVE_INTERVAL_USEC since the cal params were last saved to the ASH 193 * storage. 194 * 195 * @param sensorType One of the CHRE_SENSOR_TYPE_* constants. 196 * @param params A non-null pointer to a ashCalParams to be saved to the local 197 * cache. 198 * 199 * @return true if the cal params have been successfully saved to the local 200 * cache. 201 */ 202 bool ashSaveCalibrationParams(uint8_t sensorType, 203 const struct ashCalParams *params); 204 205 #ifdef __cplusplus 206 } 207 #endif 208 209 #endif // ASH_H_ 210