/* * Copyright (C) 2017 The Android Open Source Project * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ #ifndef ASH_H_ #define ASH_H_ /** * @file * Defines the interface for the Android Sensor Hub support. * These APIs are only accessible to system nanoapps and allow them to interact * with the underlying sensor framework. * These APIs are not part of the CHRE API and their support is optional. */ #include #include #include #ifdef __cplusplus extern "C" { #endif /** * The values returned by this sensor cannot be trusted, calibration is needed * or the environment doesn't allow readings. */ #define ASH_CAL_ACCURACY_UNRELIABLE UINT8_C(0) /** * This sensor is reporting data with low accuracy, calibration with the * environment is needed. */ #define ASH_CAL_ACCURACY_LOW UINT8_C(1) /** * This sensor is reporting data with an average level of accuracy, calibration * with the environment may improve the readings. */ #define ASH_CAL_ACCURACY_MEDIUM UINT8_C(2) /** * This sensor is reporting data with maximum accuracy. */ #define ASH_CAL_ACCURACY_HIGH UINT8_C(3) /** * Calibration info for a sensor which reports on a maximum of three axes. * * Let Su be the uncalibrated sensor data and Sc the calibrated one, * Sc = compMatrix * (Su - bias) * */ struct ashCalInfo { /** * The zero-bias vector in the x, y, z order. If the sensor reports on N * axes with N < 3, only the first N elements are considered valid. */ float bias[3]; /** * The compensation matrix in the row major order. If the sensor reports on N * axes with N < 3, only the first N elements of each row are considered * valid. */ float compMatrix[9]; /** * One of the ASH_CAL_ACCURACY_* constants. This corresponds to the * definition in the Android SensorManager. See * https://developer.android.com/reference/android/hardware/SensorEvent.html#accuracy * for more details. * Note that this accuracy field is simply a suggestion to the platform and * the platform can ignore or over-write it. */ uint8_t accuracy; }; //! This is used to indicate the persistent storage of the ASH implementaion. #define ASH_CAL_STORAGE_ASH UINT8_C(0) //! This is used to indicate the persistent storage in the sensor registry. #define ASH_CAL_STORAGE_SNS UINT8_C(1) //! Interval between cal params storage when AP is up, in usec. #define ASH_CAL_SAVE_INTERVAL_USEC UINT64_C(300000000) //! This is used to indicate that the cal params are invalid. #define ASH_CAL_PARAMS_SOURCE_NONE UINT8_C(0) //! This is used to indicate that the cal params were set by factory //! calibration. #define ASH_CAL_PARAMS_SOURCE_FACTORY UINT8_C(1) //! This is used to indicate that the cal params were set by runtime //! calibration. #define ASH_CAL_PARAMS_SOURCE_RUNTIME UINT8_C(2) /** * A struct for calibration parameters to be saved to and loaded from a * persistent area. The source of each section is indicated by the * corresponding *Source field, which is one of the ASH_CAL_PARAMS_SOURCE_* * constants. */ struct ashCalParams { //! The offset of the sensor in the x, y and z axis at temperature //! offsetTempCelsius. float offset[3]; //! The temperature at which last offset was updated. float offsetTempCelsius; //! The temperature sensitivity of offset. float tempSensitivity[3]; //! The estimated offset at zero degree Celsius. float tempIntercept[3]; //! The scale factor of the x, y and z axis. float scaleFactor[3]; //! The cross-axis factor in the [yx, zx, zy] order. float crossAxis[3]; //! The source of offset[3] uint8_t offsetSource; //! The source of offsetTempCelsius uint8_t offsetTempCelsiusSource; //! The source of tempSensitivity[3] uint8_t tempSensitivitySource; //! The source of tempIntercept[3] uint8_t tempInterceptSource; uint8_t scaleFactorSource; //! The source of crossAxis[3] uint8_t crossAxisSource; }; /** * Updates the runtime calibration info of a given sensor type for the platform * to compensate for. The calibration will be applied on top of the sensor's * factory calibration if present. * * @param sensorType One of the CHRE_SENSOR_TYPE_* constants. * @param calInfo A non-null pointer to ashCalInfo to update the sensor's calibration. * @return true if the calibration info has been successfully updated. */ bool ashSetCalibration(uint8_t sensorType, const struct ashCalInfo *calInfo); /** * Loads the stored cal params from the specified storage area. * * If ASH_CAL_STORAGE_SNS is specified as the storage area, it reads from the * sensor registry with factory cal params. This should only be used for * debugging as it can wake up the AP. * * If ASH_CAL_STORAGE_ASH is specified as the storage area, the stored cal * params in the ASH storage are provided if they exist. Otherwise, the sensor * registry cal params are provided instead. * * @param sensorType One of the CHRE_SENSOR_TYPE_* constants. * @param storage Either ASH_CAL_STORAGE_ASH or ASH_CAL_STORAGE_SNS. * @param params A non-null pointer to a ashCalParams that the cal params will * be populated to. * * @return true if the cal params have been successfully populated to the * provided memory. */ bool ashLoadCalibrationParams(uint8_t sensorType, uint8_t storage, struct ashCalParams *params); /** * Saves the cal params to a local cache, and saves to ASH's persistent storage * area when the AP wakes up, or when the AP is up and it has been * ASH_CAL_SAVE_INTERVAL_USEC since the cal params were last saved to the ASH * storage. * * @param sensorType One of the CHRE_SENSOR_TYPE_* constants. * @param params A non-null pointer to a ashCalParams to be saved to the local * cache. * * @return true if the cal params have been successfully saved to the local * cache. */ bool ashSaveCalibrationParams(uint8_t sensorType, const struct ashCalParams *params); #ifdef __cplusplus } #endif #endif // ASH_H_