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 /* 18 * This module provides a containing class (NanoSensorCal) for dynamic runtime 19 * calibration algorithms that affect the following sensors: 20 * - Accelerometer (offset) 21 * - Gyroscope (offset, with over-temperature compensation) 22 * - Magnetometer (offset) 23 * 24 * Sensor Units: 25 * - Accelerometer [meters/sec^2] 26 * - Gyroscope [radian/sec] 27 * - Magnetometer [micro Tesla, uT] 28 * - Temperature [Celsius]. 29 * 30 * NOTE1: Define NANO_SENSOR_CAL_DBG_ENABLED to enable debug messaging. 31 * 32 * NOTE2: This module uses pointers to runtime calibration algorithm objects. 33 * These must be constructed and initialized outside of this class. The owner 34 * bares the burden of managing the lifetime of these objects with respect to 35 * the NanoSensorCal class which depends on these objects and handles their 36 * interaction with the Android ASH/CHRE system. This arrangement makes it 37 * convenient to modify the specific algorithm implementations (i.e., choice of 38 * calibration algorithm, parameter tuning, etc.) at the nanoapp level without 39 * the need to specialize the standard functionality implemented here. 40 */ 41 42 #ifndef LOCATION_LBS_CONTEXTHUB_NANOAPPS_CALIBRATION_NANO_CALIBRATION_NANO_CALIBRATION_H_ 43 #define LOCATION_LBS_CONTEXTHUB_NANOAPPS_CALIBRATION_NANO_CALIBRATION_NANO_CALIBRATION_H_ 44 45 #include <stdbool.h> 46 #include <stdint.h> 47 48 #include <ash.h> 49 #include <chre.h> 50 51 #include "calibration/online_calibration/common_data/calibration_callback.h" 52 #include "calibration/online_calibration/common_data/calibration_data.h" 53 #include "calibration/online_calibration/common_data/online_calibration.h" 54 #include "calibration/online_calibration/common_data/sensor_data.h" 55 #include "common/math/macros.h" 56 57 namespace nano_calibration { 58 59 // Common log message sensor-specific identifiers. 60 constexpr char kAccelTag[] = {"[NanoSensorCal:ACCEL_MPS2]"}; 61 constexpr char kGyroTag[] = {"[NanoSensorCal:GYRO_RPS]"}; 62 constexpr char kMagTag[] = {"[NanoSensorCal:MAG_UT]"}; 63 64 // Limits NanoSensorCal notifications to once every minute. 65 constexpr uint64_t kNanoSensorCalMessageIntervalNanos = MIN_TO_NANOS(1); 66 67 /* 68 * NanoSensorCal is a container class for dynamic runtime calibration sensor 69 * algorithms used by the IMU_Cal CHRE nanoapp. The main purpose of this class 70 * is to transfer sensor data to the sensor calibration algorithms and provide 71 * calibration updates to CHRE using the ASH API. 72 */ 73 class NanoSensorCal { 74 public: 75 // Alias used to reference the three-axis OnlineCalibration baseclass used by 76 // the runtime calibration sensor wrappers. This is for convenience and to 77 // help with code readability. 78 using OnlineCalibrationThreeAxis = online_calibration::OnlineCalibration< 79 online_calibration::CalibrationDataThreeAxis>; 80 81 NanoSensorCal() = default; 82 83 // Sets the sensor calibration object pointers and initializes the algorithms 84 // using runtime values recalled using Android Sensor Hub (ASH). A nullptr may 85 // be passed in to disable a particular sensor calibration. 86 void Initialize(OnlineCalibrationThreeAxis *accel_cal, 87 OnlineCalibrationThreeAxis *gyro_cal, 88 OnlineCalibrationThreeAxis *mag_cal); 89 90 // Sends new sensor samples to the calibration algorithms. 91 void HandleSensorSamples(uint16_t event_type, 92 const chreSensorThreeAxisData *event_data); 93 94 // Provides temperature updates to the calibration algorithms. 95 void HandleTemperatureSamples(uint16_t event_type, 96 const chreSensorFloatData *event_data); 97 98 private: 99 // Passes sensor data to the runtime calibration algorithms. 100 void ProcessSample(const online_calibration::SensorData &sample); 101 102 // Loads runtime calibration data using the Android Sensor Hub API. Returns 103 // 'true' when runtime calibration values were successfully recalled and used 104 // for algorithm initialization. 'sensor_tag' is a string that identifies a 105 // sensor-specific identifier for log messages. Updates 'flags' to indicate 106 // which runtime calibration parameters were recalled. 107 bool LoadAshCalibration(uint8_t chreSensorType, 108 OnlineCalibrationThreeAxis *online_cal, 109 online_calibration::CalibrationTypeFlags* flags, 110 const char *sensor_tag); 111 112 // Provides sensor calibration updates using the ASH API for the specified 113 // sensor type. 'cal_data' contains the new calibration data. 'flags' is used 114 // to indicate all of the valid calibration values that should be provided 115 // with the update. Returns 'true' with a successful ASH update. 116 bool NotifyAshCalibration( 117 uint8_t chreSensorType, 118 const online_calibration::CalibrationDataThreeAxis &cal_data, 119 online_calibration::CalibrationTypeFlags flags, const char *sensor_tag); 120 121 // Checks whether 'ash_cal_parameters' is a valid set of runtime calibration 122 // data and can be used for algorithm initialization. Updates 'flags' to 123 // indicate which runtime calibration parameters were detected. 124 bool DetectRuntimeCalibration(uint8_t chreSensorType, const char *sensor_tag, 125 online_calibration::CalibrationTypeFlags *flags, 126 ashCalParams *ash_cal_parameters); 127 128 // Helper functions for logging calibration information. 129 void PrintAshCalParams(const ashCalParams &cal_params, 130 const char *sensor_tag); 131 132 void PrintCalibration( 133 const online_calibration::CalibrationDataThreeAxis &cal_data, 134 online_calibration::CalibrationTypeFlags flags, const char *sensor_tag); 135 136 // Pointer to the accelerometer runtime calibration object. 137 OnlineCalibrationThreeAxis *accel_cal_ = nullptr; 138 139 // Pointer to the gyroscope runtime calibration object. 140 OnlineCalibrationThreeAxis *gyro_cal_ = nullptr; 141 142 // Limits the log messaging update rate for the gyro calibrations since these 143 // can occur frequently with rapid temperature changes. 144 uint64_t gyro_notification_time_nanos_ = 0; 145 146 // Pointer to the magnetometer runtime calibration object. 147 OnlineCalibrationThreeAxis *mag_cal_ = nullptr; 148 149 // Flags that determine which calibration elements are updated with the ASH 150 // API. These are reset during initialization, and latched when a particular 151 // calibration update is detected upon a valid recall of parameters and/or 152 // during runtime. The latching behavior is used to start sending calibration 153 // values of a given type (e.g., bias, over-temp model, etc.) once they are 154 // detected and thereafter. 155 online_calibration::CalibrationTypeFlags accel_cal_update_flags_ = 156 online_calibration::CalibrationTypeFlags::NONE; 157 online_calibration::CalibrationTypeFlags gyro_cal_update_flags_ = 158 online_calibration::CalibrationTypeFlags::NONE; 159 online_calibration::CalibrationTypeFlags mag_cal_update_flags_ = 160 online_calibration::CalibrationTypeFlags::NONE; 161 }; 162 163 } // namespace nano_calibration 164 165 #endif // LOCATION_LBS_CONTEXTHUB_NANOAPPS_CALIBRATION_NANO_CALIBRATION_NANO_CALIBRATION_H_ 166