1 /*
2  * Copyright (C) 2018 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 LOCATION_LBS_CONTEXTHUB_NANOAPPS_CALIBRATION_ONLINE_CALIBRATION_COMMON_DATA_ONLINE_CALIBRATION_H_
18 #define LOCATION_LBS_CONTEXTHUB_NANOAPPS_CALIBRATION_ONLINE_CALIBRATION_COMMON_DATA_ONLINE_CALIBRATION_H_
19 
20 #include <string.h>
21 
22 #include "calibration/online_calibration/common_data/calibration_callback.h"
23 #include "calibration/online_calibration/common_data/calibration_data.h"
24 #include "calibration/online_calibration/common_data/sensor_data.h"
25 
26 namespace online_calibration {
27 
28 /*
29  * This abstract base class provides a set of general interface functions for
30  * calibration algorithms. The data structures used are intended to be lean and
31  * portable to a wide variety of software and hardware systems. Algorithm
32  * wrappers may use this as a basis for providing the following functionality:
33  *
34  *   SetMeasurement - Delivers new sensor data.
35  *   SetInitialCalibration - Initializes the algorithm's calibration data.
36  *   GetSensorCalibration - Retrieves the latest calibration data set.
37  *   new_calibration_ready - Used to poll for new calibration updates.
38  *   SetCalibrationCallback - User provides a pointer its own Callback object.
39  *   UpdateDynamicSystemSettings - Provides feedback to adjust system behavior.
40  *   get_sensor_type - Returns the sensor type which is being calibrated.
41  *
42  * NOTE 1: This class accomodates two methods of providing calibration updates.
43  * Either, or both, may be used depending on system requirements. 1) Polling can
44  * be achieved with new_calibration_ready/GetSensorCalibration functions. 2)
45  * Callback notification of new calibration updates can managed using the
46  * SetCalibrationCallback function.
47  *
48  * NOTE 2: This code implementation specifically avoids using standard template
49  * libraries (STL) and other external API’s since they may not be fully
50  * supported on embedded hardware targets. Only basic C/C++ support will be
51  * assumed.
52  */
53 
54 // CalibrationType: Sets the calibration type (e.g., CalibrationDataThreeAxis).
55 template <class CalibrationType>
56 class OnlineCalibration {
57  public:
58   // Virtual destructor.
~OnlineCalibration()59   virtual ~OnlineCalibration() {}
60 
61   // Sends new sensor data to the calibration algorithm, and returns the state
62   // of the calibration update flags, 'cal_update_polling_flags_'.
63   virtual CalibrationTypeFlags SetMeasurement(const SensorData& sample) = 0;
64 
65   // Sets the initial calibration data of the calibration algorithm. Returns
66   // "true" if set successfully.
67   virtual bool SetInitialCalibration(const CalibrationType& cal_data) = 0;
68 
69   // Polling Updates: New calibration updates are generated during
70   // SetMeasurement and the 'cal_update_polling_flags_' are set according to
71   // which calibration values have changed. To prevent missing updates in
72   // systems that use polling, this bitmask remains latched until the
73   // calibration data is retrieved with this function.
GetSensorCalibration()74   const CalibrationType& GetSensorCalibration() const {
75     cal_update_polling_flags_ = CalibrationTypeFlags::NONE;
76     return cal_data_;
77   }
78 
79   // Polling Updates: This function returns 'cal_update_polling_flags_' to
80   // indicate which calibration components have a pending update. The updated
81   // calibration data may be retrieved with GetSensorCalibration, and the
82   // 'cal_update_polling_flags_' will reset.
new_calibration_ready()83   CalibrationTypeFlags new_calibration_ready() const {
84     return cal_update_polling_flags_;
85   }
86 
87   // Sets the pointer to the CallbackInterface object used for notification of
88   // new calibration updates.
SetCalibrationCallback(CallbackInterface<CalibrationType> * calibration_callback)89   void SetCalibrationCallback(
90       CallbackInterface<CalibrationType>* calibration_callback) {
91     calibration_callback_ = calibration_callback;
92   }
93 
94   // Returns the sensor-type this calibration algorithm provides updates for.
95   virtual SensorType get_sensor_type() const = 0;
96 
97  protected:
98   // Helper function that activates the registered callback.
OnNotifyCalibrationUpdate(CalibrationTypeFlags cal_update_flags)99   void OnNotifyCalibrationUpdate(CalibrationTypeFlags cal_update_flags) const {
100     if (calibration_callback_ != nullptr) {
101       calibration_callback_->Call(cal_data_, cal_update_flags);
102     }
103   }
104 
105   // Helper function used to initialize the calibration data.
InitializeCalData()106   void InitializeCalData() {
107     cal_data_.reset();
108     cal_data_.type = get_sensor_type();
109     cal_update_polling_flags_ = CalibrationTypeFlags::NONE;
110   }
111 
112   // Stores the sensor calibration data.
113   CalibrationType cal_data_;
114 
115   // Tracks the most recent sensor temperature value.
116   float temperature_celsius_ = kInvalidTemperatureCelsius;
117 
118   // This bitmask indicates which subset of calibration parameters have changed
119   // and is used specifically for polling; the callback notification passes its
120   // own set of update flags which do not need this latching behavior. Marked
121   // mutable so that these flags may be reset when GetSensorCalibration is
122   // called.
123   mutable CalibrationTypeFlags cal_update_polling_flags_ =
124       CalibrationTypeFlags::NONE;
125 
126  private:
127   // Pointer to a callback object.
128   CallbackInterface<CalibrationType>* calibration_callback_ = nullptr;
129 };
130 
131 }  // namespace online_calibration
132 
133 #endif  // LOCATION_LBS_CONTEXTHUB_NANOAPPS_CALIBRATION_ONLINE_CALIBRATION_COMMON_DATA_ONLINE_CALIBRATION_H_
134