firmware/os/algos/calibration/online_calibration/common_data/calibration_data.h - device/google/contexthub - Git at Google

 /*
  * Copyright (C) 2018 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.
  */

 /*
  * This module provides the component definitions used to represent sensor
  * calibration data, labeled flags/enumerators, and the callback functionality
  * employed by the online sensor calibration algorithms.
  */

 #ifndef LOCATION_LBS_CONTEXTHUB_NANOAPPS_CALIBRATION_ONLINE_CALIBRATION_COMMON_DATA_CALIBRATION_DATA_H_
 #define LOCATION_LBS_CONTEXTHUB_NANOAPPS_CALIBRATION_ONLINE_CALIBRATION_COMMON_DATA_CALIBRATION_DATA_H_

 #include <stdint.h>
 #include <string.h>
 #include <sys/types.h>

 #include "calibration/online_calibration/common_data/calibration_quality.h"
 #include "calibration/online_calibration/common_data/sensor_data.h"
 #include "calibration/over_temp/over_temp_model.h"

 namespace online_calibration {

 /*
  * Bitmask used to indicate which calibration values have changed for a given
  * calibration update.
  *
  * [Bit Flag]   | [Affected Sensor Calibration Value]
  * BIAS             - Quasi-static non-zero sensor output (offset), given
  *                    conditions where the sensor should ideally output zero.
  *                    Includes corrections for over-temperature compensation.
  * SCALE_FACTOR     - Sensor axis scaling (ideally unity).
  * CROSS_AXIS       - Output sensitivity due to variations of perpendicular
  *                    sensing axes (ideally zero).
  * OVER_TEMP        - Model parameters that capture variations in sensor
  *                    behavior with temperature (e.g., linear bias sensitivity
  *                    model).
  * QUALITY_DEGRADED - Indicates a degradation in calibration quality.
  */
 enum class CalibrationTypeFlags : uint8_t {
   NONE = 0x00,
   BIAS = 0x01,
   SCALE_FACTOR = 0x02,
   CROSS_AXIS = 0x04,
   OVER_TEMP = 0x08,
   QUALITY_DEGRADED = 0x10,
   ALL = 0xFF
 };

 // Logic operators to assist with common bitmask setting/checking.
 CalibrationTypeFlags operator|(CalibrationTypeFlags lhs,
                                CalibrationTypeFlags rhs);

 bool operator&(CalibrationTypeFlags lhs, CalibrationTypeFlags rhs);

 CalibrationTypeFlags& operator|=(CalibrationTypeFlags& lhs,
                                  CalibrationTypeFlags rhs);

 /*
  * Defines the calibration data specific to a prototypical three-axis sensing
  * device (e.g., accelerometer, gyroscope, magnetometer).
  *
  * Calibration correction may be applied as:
  *   corrected_data = scale_skew_matrix * (input_data - offset);
  *
  * 'offset' is the sensor bias estimate (with temperature compensation applied
  * when supported by the underlying calibration algorithm).
  *
  * The 'scale_skew_matrix' is assumed to be in lower diagonal form where the
  * sensor frame reference definition is such that cross-axis sensitivities
  * cross_axis_xy, cross_axis_xz, and cross_axis_yz are set to zero.
  *
  *   scale_skew_matrix = [scale_factor_x    0                 0
  *                        cross_axis_yx     scale_factor_y    0
  *                        cross_axis_zx     cross_axis_zy     scale_factor_z]
  *
  * NOTE1: If over-temperature compensation is provided, then temperature
  * compensation is already applied to the 'offset'. Coefficients representative
  * of the sensor's temperature dependency model are provided, and may be used
  * for model initialization after a system restart.
  *
  *   temp_sensitivity - Modeled temperature sensitivity (i.e., linear slope).
  *   temp_intercept   - Linear model intercept.
  *
  * The model equation for the over-temperature compensated offset:
  *   compensated_offset = temp_sensitivity * current_temp + temp_intercept
  *
  * NOTE2: Unless otherwise stated, 3-dimensional array indices: 0=x, 1=y, 2=z.
  */
 struct CalibrationDataThreeAxis {
   // Timestamp for the most recent calibration update.
   uint64_t cal_update_time_nanos = 0;

   // The sensor's offset (i.e., bias) in the x-, y-, z-axes at
   // 'offset_temp_celsius'.
   float offset[3];

   // The temperature associated with the sensor offset.
   float offset_temp_celsius;

   // The temperature sensitivity of the offset.
   float temp_sensitivity[3];  // [sensor_units/Celsius]

   // The sensor's offset at zero degrees Celsius.
   float temp_intercept[3];  // [sensor_units]

   // The sensor's scale factor for each axis.
   float scale_factor[3];

   // The cross-axis factors in order: [0=yx, 1=zx, 2=zy].
   float cross_axis[3];

   // Metrics used for the reported calibration accuracy. The behavior and
   // definition depends on the sensor calibration type. See the calibration
   // algorithm documentation for details.
   CalibrationQuality calibration_quality;

   // Indicates the type of sensing device being calibrated.
   SensorType type = SensorType::kUndefined;

   // Optional pointer to an array of over-temperature model data (null when not
   // used). For initialization, populating a model dataset will take precedence
   // over the linear model parameters provided in the calibration data.
   OverTempModelThreeAxis* otc_model_data = nullptr;
   int16_t num_model_pts = 0;

   // Helper function that resets the calibration data to a set of neutral
   // reference values where no calibration correction would be applied if used.
   void reset() {
     otc_model_data = nullptr;
     calibration_quality.reset();
     offset_temp_celsius = 0.0f;
     scale_factor[0] = 1.0f;
     scale_factor[1] = 1.0f;
     scale_factor[2] = 1.0f;
     memset(offset, 0, sizeof(offset));
     memset(temp_sensitivity, 0, sizeof(temp_sensitivity));
     memset(temp_intercept, 0, sizeof(temp_intercept));
     memset(cross_axis, 0, sizeof(cross_axis));
   }

   CalibrationDataThreeAxis() { reset(); }
 };

 /*
  * Defines the calibration data for single dimensional sensing device (e.g.,
  * thermometer, barometer).
  *
  * Calibration correction may be applied as:
  *   corrected_data = scale_factor * (input_data - offset);
  *
  * 'offset' is the sensor bias estimate (with temperature compensation applied,
  * if supported by the underlying calibration algorithm).
  *
  * NOTE: If over-temperature compensation is provided, then temperature
  * compensation is already applied to the 'offset'. Coefficients representative
  * of the sensor's temperature dependency model are provided, and may be used
  * for model initialization after a system restart.
  *
  *   temp_sensitivity - Modeled temperature sensitivity (i.e., linear slope).
  *   temp_intercept   - Linear model intercept.
  *
  * The model equation for the over-temperature compensated offset:
  *   compensated_offset = temp_sensitivity * current_temp + temp_intercept
  */
 struct CalibrationDataSingleAxis {
   // Timestamp for the most recent calibration update.
   uint64_t cal_update_time_nanos = 0;

   // The sensor's offset (i.e., bias) at temperature, 'offset_temp_celsius'.
   float offset;

   // The temperature associated with the sensor offset.
   float offset_temp_celsius;

   // The temperature sensitivity of the offset.
   float temp_sensitivity;  // [sensor_units/Celsius]

   // The sensor's offset at zero degrees Celsius.
   float temp_intercept;  // [sensor_units]

   // The sensor's scale factor.
   float scale_factor;

   // Metrics used for the reported calibration accuracy. The behavior and
   // definition depends on the sensor calibration type. See the calibration
   // algorithm documentation for details.
   CalibrationQuality calibration_quality;

   // Indicates the type of sensing device being calibrated.
   SensorType type = SensorType::kUndefined;

   // Optional pointer to an array of over-temperature model data (null when not
   // used). For initialization, populating a model dataset will take precedence
   // over the linear model parameters provided in the calibration data.
   OverTempModelSingleAxis* otc_model_data = nullptr;
   int16_t num_model_pts = 0;

   // Helper function that resets the calibration data to a set of neutral
   // reference values where no calibration correction would be applied if used.
   void reset() {
     otc_model_data = nullptr;
     calibration_quality.reset();
     scale_factor = 1.0f;
     offset_temp_celsius = 0.0f;
     offset = 0.0f;
     temp_sensitivity = 0.0f;
     temp_intercept = 0.0f;
   }

   CalibrationDataSingleAxis() { reset(); }
 };

 }  // namespace online_calibration

 #endif  // LOCATION_LBS_CONTEXTHUB_NANOAPPS_CALIBRATION_ONLINE_CALIBRATION_COMMON_DATA_CALIBRATION_DATA_H_
	/*
	* Copyright (C) 2018 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.
	*/

	/*
	* This module provides the component definitions used to represent sensor
	* calibration data, labeled flags/enumerators, and the callback functionality
	* employed by the online sensor calibration algorithms.
	*/

	#ifndef LOCATION_LBS_CONTEXTHUB_NANOAPPS_CALIBRATION_ONLINE_CALIBRATION_COMMON_DATA_CALIBRATION_DATA_H_
	#define LOCATION_LBS_CONTEXTHUB_NANOAPPS_CALIBRATION_ONLINE_CALIBRATION_COMMON_DATA_CALIBRATION_DATA_H_

	#include <stdint.h>
	#include <string.h>
	#include <sys/types.h>

	#include "calibration/online_calibration/common_data/calibration_quality.h"
	#include "calibration/online_calibration/common_data/sensor_data.h"
	#include "calibration/over_temp/over_temp_model.h"

	namespace online_calibration {

	/*
	* Bitmask used to indicate which calibration values have changed for a given
	* calibration update.
	*
	* [Bit Flag] \| [Affected Sensor Calibration Value]
	* BIAS - Quasi-static non-zero sensor output (offset), given
	* conditions where the sensor should ideally output zero.
	* Includes corrections for over-temperature compensation.
	* SCALE_FACTOR - Sensor axis scaling (ideally unity).
	* CROSS_AXIS - Output sensitivity due to variations of perpendicular
	* sensing axes (ideally zero).
	* OVER_TEMP - Model parameters that capture variations in sensor
	* behavior with temperature (e.g., linear bias sensitivity
	* model).
	* QUALITY_DEGRADED - Indicates a degradation in calibration quality.
	*/
	enum class CalibrationTypeFlags : uint8_t {
	NONE = 0x00,
	BIAS = 0x01,
	SCALE_FACTOR = 0x02,
	CROSS_AXIS = 0x04,
	OVER_TEMP = 0x08,
	QUALITY_DEGRADED = 0x10,
	ALL = 0xFF
	};

	// Logic operators to assist with common bitmask setting/checking.
	CalibrationTypeFlags operator\|(CalibrationTypeFlags lhs,
	CalibrationTypeFlags rhs);

	bool operator&(CalibrationTypeFlags lhs, CalibrationTypeFlags rhs);

	CalibrationTypeFlags& operator\|=(CalibrationTypeFlags& lhs,
	CalibrationTypeFlags rhs);

	/*
	* Defines the calibration data specific to a prototypical three-axis sensing
	* device (e.g., accelerometer, gyroscope, magnetometer).
	*
	* Calibration correction may be applied as:
	* corrected_data = scale_skew_matrix * (input_data - offset);
	*
	* 'offset' is the sensor bias estimate (with temperature compensation applied
	* when supported by the underlying calibration algorithm).
	*
	* The 'scale_skew_matrix' is assumed to be in lower diagonal form where the
	* sensor frame reference definition is such that cross-axis sensitivities
	* cross_axis_xy, cross_axis_xz, and cross_axis_yz are set to zero.
	*
	* scale_skew_matrix = [scale_factor_x 0 0
	* cross_axis_yx scale_factor_y 0
	* cross_axis_zx cross_axis_zy scale_factor_z]
	*
	* NOTE1: If over-temperature compensation is provided, then temperature
	* compensation is already applied to the 'offset'. Coefficients representative
	* of the sensor's temperature dependency model are provided, and may be used
	* for model initialization after a system restart.
	*
	* temp_sensitivity - Modeled temperature sensitivity (i.e., linear slope).
	* temp_intercept - Linear model intercept.
	*
	* The model equation for the over-temperature compensated offset:
	* compensated_offset = temp_sensitivity * current_temp + temp_intercept
	*
	* NOTE2: Unless otherwise stated, 3-dimensional array indices: 0=x, 1=y, 2=z.
	*/
	struct CalibrationDataThreeAxis {
	// Timestamp for the most recent calibration update.
	uint64_t cal_update_time_nanos = 0;

	// The sensor's offset (i.e., bias) in the x-, y-, z-axes at
	// 'offset_temp_celsius'.
	float offset[3];

	// The temperature associated with the sensor offset.
	float offset_temp_celsius;

	// The temperature sensitivity of the offset.
	float temp_sensitivity[3]; // [sensor_units/Celsius]

	// The sensor's offset at zero degrees Celsius.
	float temp_intercept[3]; // [sensor_units]

	// The sensor's scale factor for each axis.
	float scale_factor[3];

	// The cross-axis factors in order: [0=yx, 1=zx, 2=zy].
	float cross_axis[3];

	// Metrics used for the reported calibration accuracy. The behavior and
	// definition depends on the sensor calibration type. See the calibration
	// algorithm documentation for details.
	CalibrationQuality calibration_quality;

	// Indicates the type of sensing device being calibrated.
	SensorType type = SensorType::kUndefined;

	// Optional pointer to an array of over-temperature model data (null when not
	// used). For initialization, populating a model dataset will take precedence
	// over the linear model parameters provided in the calibration data.
	OverTempModelThreeAxis* otc_model_data = nullptr;
	int16_t num_model_pts = 0;

	// Helper function that resets the calibration data to a set of neutral
	// reference values where no calibration correction would be applied if used.
	void reset() {
	otc_model_data = nullptr;
	calibration_quality.reset();
	offset_temp_celsius = 0.0f;
	scale_factor[0] = 1.0f;
	scale_factor[1] = 1.0f;
	scale_factor[2] = 1.0f;
	memset(offset, 0, sizeof(offset));
	memset(temp_sensitivity, 0, sizeof(temp_sensitivity));
	memset(temp_intercept, 0, sizeof(temp_intercept));
	memset(cross_axis, 0, sizeof(cross_axis));
	}

	CalibrationDataThreeAxis() { reset(); }
	};

	/*
	* Defines the calibration data for single dimensional sensing device (e.g.,
	* thermometer, barometer).
	*
	* Calibration correction may be applied as:
	* corrected_data = scale_factor * (input_data - offset);
	*
	* 'offset' is the sensor bias estimate (with temperature compensation applied,
	* if supported by the underlying calibration algorithm).
	*
	* NOTE: If over-temperature compensation is provided, then temperature
	* compensation is already applied to the 'offset'. Coefficients representative
	* of the sensor's temperature dependency model are provided, and may be used
	* for model initialization after a system restart.
	*
	* temp_sensitivity - Modeled temperature sensitivity (i.e., linear slope).
	* temp_intercept - Linear model intercept.
	*
	* The model equation for the over-temperature compensated offset:
	* compensated_offset = temp_sensitivity * current_temp + temp_intercept
	*/
	struct CalibrationDataSingleAxis {
	// Timestamp for the most recent calibration update.
	uint64_t cal_update_time_nanos = 0;

	// The sensor's offset (i.e., bias) at temperature, 'offset_temp_celsius'.
	float offset;

	// The temperature associated with the sensor offset.
	float offset_temp_celsius;

	// The temperature sensitivity of the offset.
	float temp_sensitivity; // [sensor_units/Celsius]

	// The sensor's offset at zero degrees Celsius.
	float temp_intercept; // [sensor_units]

	// The sensor's scale factor.
	float scale_factor;

	// Metrics used for the reported calibration accuracy. The behavior and
	// definition depends on the sensor calibration type. See the calibration
	// algorithm documentation for details.
	CalibrationQuality calibration_quality;

	// Indicates the type of sensing device being calibrated.
	SensorType type = SensorType::kUndefined;

	// Optional pointer to an array of over-temperature model data (null when not
	// used). For initialization, populating a model dataset will take precedence
	// over the linear model parameters provided in the calibration data.
	OverTempModelSingleAxis* otc_model_data = nullptr;
	int16_t num_model_pts = 0;

	// Helper function that resets the calibration data to a set of neutral
	// reference values where no calibration correction would be applied if used.
	void reset() {
	otc_model_data = nullptr;
	calibration_quality.reset();
	scale_factor = 1.0f;
	offset_temp_celsius = 0.0f;
	offset = 0.0f;
	temp_sensitivity = 0.0f;
	temp_intercept = 0.0f;
	}

	CalibrationDataSingleAxis() { reset(); }
	};

	} // namespace online_calibration

	#endif // LOCATION_LBS_CONTEXTHUB_NANOAPPS_CALIBRATION_ONLINE_CALIBRATION_COMMON_DATA_CALIBRATION_DATA_H_