OPT3101DesignCoefficients.h

00001 /*!
00002 * \file OPT3101DesignCoefficients.h
00003 * \author  Karthik Rajagopal <krthik@ti.com>
00004 * \version 0.9.1
00005 *
00006 * \section COPYRIGHT
00007 * TEXAS INSTRUMENTS TEXT FILE LICENSE
00008 * Copyright (c) 2018 Texas Instruments Incorporated
00009 * All rights reserved not granted herein.
00010 * Limited License.
00011 * Texas Instruments Incorporated grants a world-wide, royalty-free, non-exclusive license under copyrights and patents it now or hereafter owns or controls to make, have made, use, import, offer to sell and sell ("Utilize") this software subject to the terms herein.  With respect to the foregoing patent license, such license is granted  solely to the extent that any such patent is necessary to Utilize the software alone.  The patent license shall not apply to any combinations which include this software, other than combinations with devices manufactured by or for TI ("TI Devices").  No hardware patent is licensed hereunder.
00012 * Redistributions must preserve existing copyright notices and reproduce this license (including the above copyright notice and the disclaimer and (if applicable) source code license limitations below) in the documentation and/or other materials provided with the distribution
00013 * Redistribution and use in binary form, without modification, are permitted provided that the following conditions are met:
00014 * * No reverse engineering, decompilation, or disassembly of this software is permitted with respect to any software provided in binary form.
00015 * * any redistribution and use are licensed by TI for use only with TI Devices.
00016 * * Nothing shall obligate TI to provide you with source code for the software licensed and provided to you in object code.
00017 * If software source code is provided to you, modification and redistribution of the source code are permitted provided that the following conditions are met:
00018 * * any redistribution and use of the source code, including any resulting derivative works, are licensed by TI for use only with TI Devices.
00019 * * any redistribution and use of any object code compiled from the source code and any resulting derivative works, are licensed by TI for use only with TI Devices.
00020 * Neither the name of Texas Instruments Incorporated nor the names of its suppliers may be used to endorse or promote products derived from this software without specific prior written permission.
00021 * DISCLAIMER.
00022 * THIS SOFTWARE IS PROVIDED BY TI AND TI'S LICENSORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL TI AND TI'S LICENSORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
00023 *
00024 * \section DESCRIPTION
00025 * This file contains class declarations OPT3101::crosstalkTempCoffC OPT3101::phaseTempCoffC OPT3101::phaseAmbientCoffC . These are design coefficients required for various calibration steps. 
00026 */
00027 
00028 #ifndef OPT3101DESIGNCOEFFICIENTS_H_
00029 #define OPT3101DESIGNCOEFFICIENTS_H_
00030 
00031 #include <stdint.h>
00032 //#include "OPT3101device.h"
00033 #include "OPT3101Crosstalk.h "
00034 #include "OPT3101PhaseOffset.h "
00035 
00036 #ifdef OPT3101_USE_STREAMLIB
00037 #include <fstream>
00038 #include <iostream>
00039 #include <istream>
00040 #include <string>
00041 #endif 
00042 
00043 /** \brief OPT3101::device declaration
00044 This is declared here to avoid cyclic reference of classes
00045 */
00046 //class OPT3101::;
00047 
00048 
00049 namespace OPT3101 {
00050     /** \brief Class that holds crosstalk temperature coefficient related registers and values.
00051 
00052     This is a class container that can hold crosstalk temperature coefficients and related register values.  OPT3101 device has different crosstalk phenomenon which needs to be calibrated and compensated<br>
00053     Refer to documentation for OPT3101::crosstalkC class documentation<br>
00054     Crosstalk varies with temperature which needs to be calibration and compensated to improve the system performance. 
00055     Illum crosstalk temperature variation needs to be evaluated and a compensation coefficients have to be calculated.
00056     OPT3101 device has internal registers to correct and compensate for illum crosstalk temperature variation. This class acts as a temporary storage of crosstalk temp coefficients and related registers.
00057     Calculations have to be made on the crosstalk values, coefficients to transform them to register settings. Instances of OPT3101::crosstalkC taken at different temperate will be used to calculate these coefficients and registers. 
00058     */
00059     class crosstalkTempCoffC {
00060         public:
00061             double coffI; ///< Coefficient for I Component with floating point precision.Units for this measurement is crosstalk OPT3101::crosstalkC::I (24 bit level) codes change per unit of temperature sensor codes (OPT3101::registers::tmain) per OPT3101::crosstalkC::magnitude() of crosstalk 
00062             double coffQ; ///< Coefficient for Q Component with floating point precision.Units for this measurement is crosstalk OPT3101::crosstalkC::Q (24 bit level) codes change per unit of temperature sensor codes (OPT3101::registers::tmain) per OPT3101::crosstalkC::magnitude() of crosstalk 
00063             uint8_t coffIReg; ///< Value of OPT3101::crosstalkTempCoffC::coffI represented as a 8 bit number to be written to illum crosstalk temp compensation registers 
00064             uint8_t coffQReg; ///< Value of OPT3101::crosstalkTempCoffC::coffQ represented as a 8 bit number to be written to illum crosstalk temp compensation registers 
00065             uint8_t commonScale; ///< Value of common scale for register coefficients achieved using different instances of OPT3101::crosstalkTempCoffC. Calculated by OPT3101::calibration::findCrosstalkTempRegisterValues during production calibration. Used while loading a set of TX and current configurations to the OPT3101 device during production calibration
00066             /*!
00067             * \brief initializes the members to 0
00068             *
00069             * \returns Nothing;
00070             */
00071             crosstalkTempCoffC();
00072             /*!
00073             * \brief calculates the crosstalk temp coff
00074             *  
00075             * \param[in] illumXtalk0; Pointer to illum crosstalk OPT3101::crosstalkC instance measured at a lower  temperature 
00076             * \param[in] illumXtalk1; Pointer to illum crosstalk OPT3101::crosstalkC instance measured at a higher temperature 
00077             * \returns Nothing;
00078             */
00079             void calculateCoff(crosstalkC *illumXtalk0,crosstalkC *illumXtalk1);
00080             /*!
00081             * \brief reports members of the instance
00082             *  Print the members of the class instance on screen
00083             * \returns Nothing;
00084             */
00085             void report();
00086 #ifdef OPT3101_USE_STDIOLIB
00087             /*!
00088             * \brief saves crosstalk temp coff values to file
00089             *  This methods saves the crosstalk temp coff values to a non-volatile memory. Storage/Restoration to/from non-volatile memory is important for factory calibration
00090             * \param[in] fileName; Path and name of the file to store
00091             * \returns Nothing;
00092             */
00093             void storeToFile(char *fileName);
00094             /*!
00095             * \brief load crosstalk temp coff values from file
00096             *  This methods loads the crosstalk temp coff values to a non-volatile memory. Storage/Restoration to/from non-volatile memory is important for factory calibration
00097             * \param[in] fileName; Path and name of the file from where to load
00098             * \returns Nothing;
00099             */
00100             void loadFromFile(char *fileName);
00101 #endif
00102 #ifdef OPT3101_USE_STREAMLIB
00103             /*!
00104             * \brief Operator overload to store class contents to a file
00105             *  Casts all the class members for file storage
00106             * \param[out] os; os is data stream to serialize data
00107             * \param[in] data; data is pointer to the class to be serialized and stored
00108             * \returns std::ostream; Serialized std::ostream to be written to a file
00109             */
00110             friend std::ostream& operator<<(std::ostream& os, const crosstalkTempCoffC *data);
00111             /*!
00112             * \brief Operator overload to load class contents to from a file
00113             *  Retrieves all the class members from a stored file
00114             * \param[in] is; is input stream from where the data is loaded
00115             * \param[out] data; data is pointer to the class to be restored
00116             * \returns std::istream; Serialized Input stream loaded from file
00117             */
00118             friend std::istream& operator>>(std::istream& is, crosstalkTempCoffC *data);
00119 #endif
00120     };
00121     /*! \class OPT3101::phaseTempCoffC
00122     \brief Class that holds phase temperature coefficient related registers and values.
00123 
00124     This is a class container that can hold phase/phase offset temperature coefficients and related register values.  OPT3101 AFE phase measurement drifts over temperature. This drift is primarily due to change in delay in the path of the TX channels.
00125     The drift will show up in OPT3101::frameData::phase measurement which will translate to error in measurement.<br>
00126     OPT3101 has mechanism to compensate the output for this drift, for which phase temperature coefficient is required. 
00127     Either internal temp sensor or external temperature sensor can be used to compensate for this. 
00128     This class acts as a temporary storage of phase temp coefficients and related registers.
00129     Calculations have to be made on the phase offsets and frame data, coefficients to transform them to register settings. Instances of OPT3101::frameData taken at different temperature will be used to calculate these coefficients and registers.
00130     */
00131     class phaseTempCoffC {
00132         public: 
00133             double coff; ///< Coefficient stores in floating point precision.Units for this measurement is  OPT3101::frameData::phase codes (16 bit level) codes change per unit of temperature sensor codes (OPT3101::registers::tmain or OPT3101::registers::tillum based on OPT3101::phaseTempCoffC::istMainCoff
00134             uint16_t coffReg; ///< Coefficient value of OPT3101::phaseTempCoffC::coff represented as 16bit register setting
00135             uint8_t commonScale; ///< Common scale of OPT3101::phaseTempCoffC::coffReg calculated based on various OPT3101::phaseTempCoffC class instances. This is calculated by OPT3101::calibrationC::findPhaseTempRegisterValues during production calibration
00136             bool istMainCoff; ///< Flag which determines if the coefficient was obtained using OPT3101::registers::tmain difference or OPT3101::registers::tillum 
00137             /*!
00138             * \brief initializes the members to 0
00139             *
00140             * \returns Nothing;
00141             */
00142             phaseTempCoffC();
00143             /*!
00144             * \brief calculates the phase temp coff
00145             *
00146             * \param[in] frameData0; Pointer to frame data OPT3101::frameData instance measured at a lower  temperature
00147             * \param[in] frameData1; Pointer to frame data OPT3101::frameData instance measured at a higher temperature
00148             * \param[in] istMainCoff; istMainCoff specifies if the calculation should be done with Tmain Coff 
00149             * \returns Nothing;
00150             */
00151             void calculateCoff(frameData *frameData0,frameData *frameData1,bool istMainCoff=true);
00152             /*!
00153             * \brief reports members of the instance
00154             *  Print the members of the class instance on screen
00155             * \returns Nothing;
00156             */
00157             void report();
00158 #ifdef OPT3101_USE_STDIOLIB
00159             /*!
00160             * \brief saves phase temp coff values to file
00161             *  This methods saves the phase temp coff values to a non-volatile memory. Storage/Restoration to/from non-volatile memory is important for factory calibration
00162             * \param[in] fileName; Path and name of the file to store
00163             * \returns Nothing;
00164             */
00165             void storeToFile(char *fileName);
00166             /*!
00167             * \brief load phase temp coff values from file
00168             *  This methods loads the phase temp coff values to a non-volatile memory. Storage/Restoration to/from non-volatile memory is important for factory calibration
00169             * \param[in] fileName; Path and name of the file from where to load
00170             * \returns Nothing;
00171             */
00172             void loadFromFile(char *fileName);
00173             /*!
00174             * \brief Operator overload to store class contents to a file
00175             *  Casts all the class members for file storage
00176             * \param[out] os; os is data stream to serialize data
00177             * \param[in] data; data is pointer to the class to be serialized and stored
00178             * \returns std::ostream; Serialized std::ostream to be written to a file
00179             */
00180 #endif
00181 #ifdef OPT3101_USE_STREAMLIB
00182             friend std::ostream& operator<<(std::ostream& os, const phaseTempCoffC *data);
00183             /*!
00184             * \brief Operator overload to load class contents to from a file
00185             *  Retrieves all the class members from a stored file
00186             * \param[in] is; is input stream from where the data is loaded
00187             * \param[out] data; data is pointer to the class to be restored
00188             * \returns std::istream; Serialized Input stream loaded from file
00189             */
00190             friend std::istream& operator>>(std::istream& is, phaseTempCoffC *data);
00191 #endif
00192     };
00193     /*! \class OPT3101::phaseAmbientCoffC
00194     \brief Class that holds ambient phase  coefficient related registers and values.
00195 
00196     This is a class container that can hold phase offset ambient coefficients and related registers. 
00197     Photo diodes has a phenomenon where the phase delay of modulated current generated by photo diode is dependent on the amount of ambient light falling on the photo diode. 
00198     The effect observed on the system is that the phase reported by the system will be dependent on the amount of ambient light of the environment. <br>
00199     OPT3101 has compensation block for the same, which needs coefficients to be  programmed. OPT3101 has a look up table based correction since the phenomenon in non-linear. 
00200     The look-up table is a 4 way split PWL correction with 4 independent coefficients. The PWL correlation is between ambient ADC output and phase measured<br>
00201     This class has members to contain the coefficients and the split points. 
00202     */
00203     class phaseAmbientCoffC {
00204         public:
00205             double coff[4]; ///< Coefficients stored in floating point precision. Since there are 4 sections the OPT3101::phaseAmbientCoffC::coff is array of 4 elements. Units for this is OPT3101::frameData::phase codes per unit OPT3101::frameData::ambient codes 
00206             uint8_t coffReg[4]; ///< Coefficients value of  OPT3101::phaseAmbientCoffC::coff represented as 8 bit register values calculated by  OPT3101::phaseAmbientCoffC::calculateCoff
00207             uint16_t splitsReg[3]; ///< Register entries for the split point for the PWL. Since there are 4 sections where are 3 split points to be set. Units for this is OPT3101::frameData::ambient codes
00208             uint8_t commonScale; ///< Since there are 4 OPT3101::phaseAmbientCoffC::coff to represent them as 8 bit register values a common scaling factor is required. This is calculated by method  OPT3101::phaseAmbientCoffC::calculateCoff
00209             /*!
00210             * \brief initializes the members to 0
00211             *
00212             * \returns Nothing;
00213             */
00214             phaseAmbientCoffC();
00215             /*!
00216             * \brief Calculates the register settings for the phase ambient coefficient
00217             * Calculates OPT3101::phaseAmbientCoffC::coffReg and OPT3101::phaseAmbientCoffC::commonScale based on OPT3101::phaseAmbientCoffC::coff 
00218             * \param[in] freqCounter; freqCounter is the count which represents the frequency from the Frequency correction block. This is read from register OPT3101::registers::freq_count_read_reg
00219             * \returns Nothing;
00220             */
00221             void calculateCoff(uint16_t freqCounter);
00222             /*!
00223             * \brief reports members of the instance
00224             *  Print the members of the class instance on screen
00225             * \returns Nothing;
00226             */
00227             void report();
00228 #ifdef OPT3101_USE_STDIOLIB
00229             /*!
00230             * \brief saves phase ambient coff values to file
00231             *  This methods saves the phase ambient coff values to a non-volatile memory. Storage/Restoration to/from non-volatile memory is important for factory calibration
00232             * \param[in] fileName; Path and name of the file to store
00233             * \returns Nothing;
00234             */
00235             void storeToFile(char *fileName);
00236             /*!
00237             * \brief load phase ambient coff values from file
00238             *  This methods loads the phase ambient coff values to a non-volatile memory. Storage/Restoration to/from non-volatile memory is important for factory calibration
00239             * \param[in] fileName; Path and name of the file from where to load
00240             * \returns Nothing;
00241             */
00242             void loadFromFile(char *fileName);
00243             /*!
00244             * \brief Operator overload to store class contents to a file
00245             *  Casts all the class members for file storage
00246             * \param[out] os; os is data stream to serialize data
00247             * \param[in] data; data is pointer to the class to be serialized and stored
00248             * \returns std::ostream; Serialized std::ostream to be written to a file
00249             */
00250 #endif
00251 #ifdef OPT3101_USE_STREAMLIB
00252             friend std::ostream& operator<<(std::ostream& os, const phaseAmbientCoffC *data);
00253             /*!
00254             * \brief Operator overload to load class contents to from a file
00255             *  Retrieves all the class members from a stored file
00256             * \param[in] is; is input stream from where the data is loaded
00257             * \param[out] data; data is pointer to the class to be restored
00258             * \returns std::istream; Serialized Input stream loaded from file
00259             */
00260             friend std::istream& operator>>(std::istream& is, phaseAmbientCoffC *data);
00261 #endif
00262     };
00263 }
00264 
00265 #endif /* OPT3101DESIGNCOEFFICIENTS_H_ */
00266