OPT3101frameData.h

00001 /*!
00002 * \file OPT3101frameData.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 the OPT3101::frameData class declaraction
00026 */
00027 
00028 #ifndef OPT3101FRAMEDATA_H_
00029 #define OPT3101FRAMEDATA_H_
00030 
00031 #include <stdint.h>
00032 #include "hostController.h "
00033 //#include "OPT3101device.h"
00034 
00035 #ifdef OPT3101_USE_STREAMLIB
00036 #include <fstream>
00037 #include <iostream>
00038 #include <istream>
00039 #include <string>
00040 #endif
00041 
00042 
00043 namespace OPT3101 {
00044     /** \brief OPT3101::device declaration
00045     This is declared here to avoid cyclic reference of classes
00046     */
00047     class device;
00048     
00049     /*! \class OPT3101::frameData
00050     \brief Class the data output from OPT3101 device 
00051 
00052     This is a class that holds output data from OPT3101 AFE. 
00053     Measurements by AFE OPT3101 device are stores in registers with address 0x08, x09 & 0x0A. Difference sections of these registers hold different measurements like OPT3101::frameData::phase, OPT3101::frameData::amplitude <br>
00054     This class provides an abstraction where the registers are read, relevant portions of the registers are extracted and assigned to members with meaningful names.
00055     This provides a functional abstraction to the user. 
00056     */
00057     class frameData {
00058         public:
00059             uint32_t phase; ///< phase value measured by the AFE. Actually 16 bit unsigned value upscaled to 17 bits with 1 bit of frameData::phaseovl flag added to the MSB. Same as OPT3101::registers::phase_out
00060             bool phaseovl; ///< phase overload flag, specifying if phase value detected exceeds 16 bits. (greater than 65535). OPT3101::registers::.phase_overflow
00061             bool phaseovlf2; ///< phase overload flag for frequency 2, specifying if phase value detected exceeds 16 bits. (greater than 65535). Same as OPT3101::registers::phase_overflow_f2
00062             bool ambovl; ///< ambient over load flag which flags if the AFE is saturated due to very high ambient condition. Same as OPT3101::registers::amb_ovl_flag
00063             bool illumDac; ///< flag that specifies which of the auto-hdr register config from where the measurement is made. Same as OPT3101::registers::hdr_mode 
00064             uint8_t ledChannel; ///< value that specifies from which channel the measurement is made. Same as OPT3101::registers::tx_channel
00065             bool frameStatus; ///< flag that specifies if the measurement is a valid data. Same as OPT3101::registers::frame_status
00066             bool dealiasFreq; ///< flag that specifies if the measurement is done with fundamental frequency of de-alias frequency. Same as OPT3101::registers::mod_freq
00067             uint8_t frameCounter; ///< Frame counter which counts every data ready. Same as combination of OPT3101::register::frame_count0 , OPT3101::registers::frame_count1 and OPT3101::registers::frame_count2
00068             uint16_t amplitude; ///< amplitude value measured by AFE. 15 bit representation of the signal. Same as OPT3101::registers::amp_out
00069             bool sigovl; ///< flag that specifies if the AFE is saturated due to signal. Same as OPT3101::registers::sig_ovl_flag
00070             uint8_t dealiasBin; ///< value that specifies the de-aliased bin number. Same as OPT3101::registers::dealias_bin
00071             uint16_t ambient; ///< value specifies the ambient light measured by the ambient cancellation block. Same as OPT3101::registers::amb_data
00072             uint16_t temp; ///< value of internal temp sensor read from register 0x0A. Same as OPT3101::registers::tmain . This is updated every data ready.
00073             uint16_t tmain; ///< value of internal temp sensor read from register OPT3101::registers::tmain
00074             uint16_t tillum; ///< value of external temp sensor read using the I2C Master. Same as OPT3101::registers::tillum
00075             /*!
00076             * \brief initializes the members to 0
00077             *
00078             * \returns Nothing;
00079             */
00080             frameData();
00081             /*!
00082             * \brief captures measurement data from the device 
00083             *  This method invokes I2C transactions to capture data from the OPT3101 device registers 0x08, 0x09 and 0x0A. Extracts and assigns members their respective values based on their positions in the registers. 
00084             * \param[in] host; Pointer to the class hostController used to directly invoke I2C transactions bypassing OPT3101::registers or OPT3101::device class
00085             * \param[in] dev; Pointer to the class OPT3101::device used to read register(s) from device
00086             * \param[in] readTIllulm; Flag which specifies if OPT3101::registers::tillum value needs to be read or not
00087             * \returns Nothing;
00088             */
00089             void capture(hostController *host, device *dev, bool readTIllulm = true);
00090             /*!
00091             * \brief reports members of the instance
00092             *  Print the members of the class instance on screen
00093             * \returns Nothing;
00094             */
00095             void report();
00096             /*!
00097             * \brief prints members of the instance
00098             *  Print the members of the class instance on screen
00099             * \returns Nothing;
00100             */
00101             void print();
00102             /*!
00103             * \brief prints header
00104             *  Print the members of the class instance on screen
00105             * \returns Nothing;
00106             */
00107             void printHeader();
00108             /*!
00109             * \brief calculates mean and assigns to self
00110             *  Given a set on input OPT3101::frameData the method calculates the mean frame and assigns to self
00111             * \param[in] inputData; Pointer to the class OPT3101::frameData instance with multiple frame data
00112             * \param[in] nFrames; Number of measurements to step though in the inputData to calculate mean 
00113             * \returns Nothing;
00114             */
00115             void populateWithMean(frameData *inputData, uint16_t nFrames);
00116 #ifdef OPT3101_USE_STDIOLIB         
00117             /*!
00118             * \brief saves phase temp coff values to file
00119             *  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
00120             * \param[in] fileName; Path and name of the file to store
00121             * \returns Nothing;
00122             */
00123             void storeToFile(char *fileName);
00124             /*!
00125             * \brief load phase temp coff values from file
00126             *  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
00127             * \param[in] fileName; Path and name of the file from where to load
00128             * \returns Nothing;
00129             */
00130             void loadFromFile(char *fileName);
00131 #endif
00132 #ifdef OPT3101_USE_STREAMLIB
00133             /*!
00134             * \brief Operator overload to store class contents to a file
00135             *  Casts all the class members for file storage
00136             * \param[out] os; os is data stream to serialize data
00137             * \param[in] data; data is pointer to the class to be serlialized and stored
00138             * \returns std::ostream; Serialized std::ostream to be written to a file
00139             */
00140             friend std::ostream& operator<<(std::ostream& os, const frameData *data);
00141             /*!
00142             * \brief Operator overload to load class contents to from a file
00143             *  Retreives all the class members from a stored file
00144             * \param[in] is; is input stream from where the data is loaded
00145             * \param[out] data; data is pointer to the class to be restored
00146             * \returns std::istream; Serialized Input stream loaded from file
00147             */
00148             friend std::istream& operator>>(std::istream& is, frameData *data);
00149 #endif
00150 
00151         };
00152 }
00153 #endif /* OPT3101FRAMEDATA_H_ */
00154