LM77.h

00001 /* mbed LM77 Library, for an I2C Temperature sensor
00002  * Copyright (c) 2015, v01: WH, Initial version
00003  * 
00004  * The LM77 is a digital temperature sensor and thermal window comparator with an I2C Serial Bus interface. 
00005  * The open-drain Interrupt (INT) output becomes active whenever temperature goes outside a programmable window,
00006  * while a separate Critical Temperature Alarm (T_CRIT_A) output becomes active when the temperature exceeds a 
00007  * programmable critical limit. The INT output can operate in either a comparator or event mode, while the T_CRIT_A 
00008  * output operates in comparator mode only. The host can program both the upper and lower limits of the window as 
00009  * well as the critical temperature limit. Programmable hysterisis as well as a fault queue are available to minimize 
00010  * false tripping. Two pins (A0, A1) are available for address selection. The sensor powers up with default thresholds 
00011  * of 2°C THYST, 10°C TLOW, 64°C THIGH, and 80°C T_CRIT.
00012  * 
00013  * Permission is hereby granted, free of charge, to any person obtaining a copy
00014  * of this software and associated documentation files (the "Software"), to deal
00015  * in the Software without restriction, including without limitation the rights
00016  * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
00017  * copies of the Software, and to permit persons to whom the Software is
00018  * furnished to do so, subject to the following conditions:
00019  *
00020  * The above copyright notice and this permission notice shall be included in
00021  * all copies or substantial portions of the Software.
00022  *
00023  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
00024  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
00025  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
00026  * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
00027  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
00028  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
00029  * THE SOFTWARE.
00030  */
00031 
00032 #ifndef MBED_LM77_H
00033 #define MBED_LM77_H
00034 
00035 #include "mbed.h"
00036 
00037 /** An interface for the LM77 I2C temperature sensor
00038  *
00039  * @code
00040  * #include "mbed.h"
00041  * #include "LM77.h"
00042  * 
00043  * // I2C Communication
00044  * I2C i2c(p28,p27); // SDA, SCL
00045  *
00046  * // Serial Communication*
00047  * Serial pc(USBTX,USBRX);
00048  *
00049  * //Create an LM77 object at the default address (LM77_SA0)
00050  * LM77 sensor(&i2c);
00051  *
00052  * int main() {
00053  *   pc.printf("Hello World!\n");
00054  *   if (lm77.getStatus()) {
00055  *     pc.printf("LM77 status = Ok\n\r");   
00056  *
00057  *     pc.printf("Critical Alert temperature from LM77 is %.1f [C]\r\n", lm77.getCritAlertTemp());     
00058  *     pc.printf("Low Alert temperature from LM77 is %.1f [C]\r\n", lm77.getLowAlertTemp());     
00059  *     pc.printf("High Alert temperature from LM77 is %.1f [C]\r\n", lm77.getHighAlertTemp());             
00060  *     pc.printf("Alert Hysteresis from LM77 is %.1f [C]\r\n", lm77.getAlertHyst());  
00061  *     wait(1.0);
00062  *
00063  *#define CA          95.0f     
00064  *#define LA           8.0f     
00065  *#define HA          15.0f     
00066  *#define HY           3.0f     
00067  *     lm77.setCritAlertTemp(CA);     
00068  *     lm77.setLowAlertTemp(LA);         
00069  *     lm77.setHighAlertTemp(HA);
00070  *     lm77.setAlertHyst(HY);             
00071  * 
00072  *     while(1) {
00073  *
00074  *       // Show Temperature LM77
00075  *       //pc.printf("Ambient temperature from LM77 is %.1f [C]\r\n", (float) lm77.getTemperatureInt() / 10.0f);       
00076  *       pc.printf("Ambient temperature from LM77 is %.1f [C]\r\n", lm77.getTemperature());     
00077  *       wait(1.0);
00078  *     } // while
00079  *   }
00080  *   else {
00081  *       pc.printf("LM77 status = not Ok\n\r");            
00082  *   } //if
00083  * }
00084  * @endcode
00085  */
00086 
00087 // Device I2C Slave addresses
00088 #define LM77_SA0    0x90
00089 #define LM77_SA1    0x92
00090 #define LM77_SA2    0x94
00091 #define LM77_SA3    0x96
00092 
00093 //I2C register addresses
00094 #define LM77_REG_TEMP    0x00
00095 #define LM77_REG_CONF    0x01
00096 #define LM77_REG_THYST   0x02
00097 #define LM77_REG_TCRIT   0x03
00098 #define LM77_REG_TLOW    0x04
00099 #define LM77_REG_THIGH   0x05
00100 
00101 //Temp Register
00102 #define LM77_FLAG_LOW    0x01
00103 #define LM77_FLAG_HIGH   0x02
00104 #define LM77_FLAG_CRIT   0x04
00105 
00106 #define LM77_FLAG_MSK    0x07
00107 
00108 //Config Register
00109 #define LM77_PWR_ON      0x00
00110 #define LM77_PWR_DWN     0x01
00111 #define LM77_INT_CMP     0x00
00112 #define LM77_INT_EVENT   0x02
00113 #define LM77_POL_TCRIT_L 0x00
00114 #define LM77_POL_TCRIT_H 0x04
00115 #define LM77_POL_INT_L   0x00
00116 #define LM77_POL_INT_H   0x08
00117 #define LM77_FQU_1       0x00
00118 #define LM77_FQU_4       0x10
00119 
00120 #define LM77_PWR_MSK       0x01
00121 #define LM77_INT_MSK       0x02
00122 #define LM77_POL_TCRIT_MSK 0x04
00123 #define LM77_POL_INT_MSK   0x08
00124 #define LM77_FQU_MSK       0x10
00125 
00126 /** Create an LM77 Class instance
00127  *
00128  */ 
00129 class LM77 {
00130 
00131 public:
00132    
00133     /** Represents the power mode of the LM77
00134      */
00135     enum PowerMode {
00136         POWER_NORMAL,   /**< Chip is enabled and samples every 100ms */
00137         POWER_SHUTDOWN  /**< Chip is in low-power shutdown mode */
00138     };
00139 
00140     /** Represents INT pin mode of the LM77
00141      */
00142     enum IntMode {
00143         INT_COMPARATOR,  /**< INT pin asserted when temp exceeds an alert threshold, and de-asserted when temp crosses alert hysteresis threshold or when LM77 is read. It will be re-asserted when condition is still true after reading. */
00144         INT_EVENT        /**< INT pin asserted when temp reaches an alert threshold or threshold +/- hysteris and only de-asserted when a register has been read. It will be re-asserted when next event occurs. */
00145     };
00146 
00147     /** Represents Pin polarity of the LM77
00148      */
00149     enum PinPolarity {
00150         ACTIVE_LOW,     /**< Pin is a logic low when asserted, and a logic high when de-asserted */
00151         ACTIVE_HIGH     /**< Pin is a logic high when asserted, and a logic low when de-asserted */
00152     };
00153 
00154     /** Represents OS pin fault queue length of the LM77
00155      */
00156     enum FaultQueue {
00157         FAULT_QUEUE_1,   /**< Pins and flags are asserted after 1 fault */
00158         FAULT_QUEUE_4,   /**< Pins and flags are asserted after 4 consecutive faults */
00159     };
00160 
00161 
00162    /** Create an LM77 device instance
00163      *
00164      * @param i2c    I2C Bus 
00165      * @param char deviceAddress I2C slaveaddress (defaults to LM77_SA0).
00166      */ 
00167     LM77(I2C *i2c, char deviceAddress = LM77_SA0);
00168 
00169 
00170    /** Get the current power mode of the LM77
00171      *
00172      * @returns The current power mode as a PowerMode enum.
00173      */
00174     LM77::PowerMode getPowerMode();
00175 
00176    /** Set the power mode of the LM77
00177      *
00178      * @param mode The new power mode as a PowerMode enum.
00179      */
00180     void setPowerMode(PowerMode mode);
00181 
00182    /** Get the current INT pin mode of the LM77
00183      * Reset value is INT_COMPARATOR            
00184      *
00185      * @returns The current INT pin mode as an IntMode enum.
00186      */
00187     LM77::IntMode getIntMode();
00188 
00189    /** Set the INT pin mode of the LM77
00190      *
00191      * @param mode The new INT pin mode as an IntMode enum.
00192      */
00193     void setIntMode(IntMode mode);
00194 
00195    /** Get the current INT pin polarity of the LM77
00196      * Reset value is ACTIVE_LOW            
00197      *
00198      * @returns The current INT pin polarity as an PinPolarity enum.
00199      */
00200     LM77::PinPolarity getIntPolarity();
00201 
00202    /** Set the INT pin polarity of the LM77
00203      *
00204      * @param polarity The new INT pin polarity as an PinPolarity enum.
00205      */
00206     void setIntPolarity(PinPolarity polarity);
00207 
00208    /** Get the current T_CRIT_A pin polarity of the LM77
00209      * Reset value is ACTIVE_LOW            
00210      *
00211      * @returns The current T_CRIT_A pin polarity as an PinPolarity enum.
00212      */
00213     LM77::PinPolarity getTCritPolarity();
00214 
00215    /** Set the T_CRIT_A pin polarity of the LM77
00216      *
00217      * @param polarity The new T_CRIT_A pin polarity as an PinPolarity enum.
00218      */
00219     void setTCritPolarity(PinPolarity polarity);
00220 
00221 
00222    /** Get the current pin and flag fault queue length of the LM77
00223      * Reset value is FAULT_QUEUE_1, Pins and flags are asserted after 1 fault
00224      *
00225      * @returns The current pin and flag fault queue length as an FaultQueue enum.
00226      */
00227     LM77::FaultQueue getFaultQueue();
00228 
00229    /** Set the pin and flag fault queue length of the LM77
00230      *
00231      * @param queue The new pin and flag fault queue length as an FaultQueue enum.
00232      */
00233     void setFaultQueue(FaultQueue queue);
00234 
00235    /** Get the current critical alert temperature threshold of the LM77
00236      * Reset value is 80.0 °C.      
00237      *
00238      * @returns The current crtitcal alert temperature threshold in °C.
00239      */
00240     float getCritAlertTemp();
00241 
00242    /** Set the Critical alert temperature threshold of the LM77
00243      * Reset value is 80.0 °C.   
00244      *
00245      * @param temp The new Critical alert temperature threshold in °C.
00246      */
00247     void setCritAlertTemp(float temp);
00248 
00249 
00250    /** Get the current Low temperature alert threshold of the LM77
00251      * Reset value is 10.0 °C.      
00252      *
00253      * @returns The current Low temperature alert threshold in °C.
00254      */
00255     float getLowAlertTemp();
00256 
00257    /** Set the current Low temperature alert threshold of the LM77
00258      * Reset value is 10.0 °C.      
00259      *
00260      * @param temp The new Low alert temperature threshold in °C.
00261      */
00262     void setLowAlertTemp(float temp);
00263 
00264     
00265    /** Get the current High temperature alert threshold of the LM77
00266      * Reset value is 64.0 °C.      
00267      *
00268      * @returns The current High temperature alert threshold in °C.
00269      */
00270     float getHighAlertTemp();
00271     
00272    /** Set the High temperature alert threshold of the LM77
00273      * Reset value is 64.0 °C.   
00274      *
00275      * @param temp The new High temperature alert threshold in °C.
00276      */
00277     void setHighAlertTemp(float temp);
00278 
00279 
00280    /** Get the current alert temperature hysteresis of the LM77
00281      * Reset value is 2.0 °C.   
00282      *
00283      * @returns The current alert temperature hysteresis in °C.
00284      */
00285     float getAlertHyst();
00286 
00287    /** Set the alert temperature hysteresis of the LM77
00288      * Reset value is 2.0 °C.
00289      *
00290      * @param temp The new alert temperature hysteris in °C.
00291      */
00292     void setAlertHyst(float temp);
00293 
00294    /** Get Temperature as Int in °Celsius x 10
00295      *
00296      * @return int Temperature in °Celsius x 10
00297      */ 
00298     int getTemperatureInt(void);
00299     
00300    /** Get Temperature as float in °Celsius
00301      *
00302      * @return float Temperature in °Celsius
00303      */ 
00304     float getTemperature(void);
00305 
00306    /** Get the Alert flags of the LM77
00307      *
00308      * @returns The current Alert flags as int.
00309      */
00310     int getAlertFlags(void);
00311 
00312 
00313 #ifdef MBED_OPERATORS
00314     /** A shorthand for Temperature()
00315      *
00316      * @returns The current temperature measurement in °C.
00317      */
00318     operator float();
00319 #endif
00320 
00321    /** Convert Temperature from °Celsius into °Fahrenheit
00322      *
00323      * @param  float celsius in °Celsius  
00324      * @return float temperature in °Fahrenheit
00325      */ 
00326     float celsiusToFahrenheit(float celsius);
00327 
00328 
00329    /** Get Status
00330      *
00331      * @return bool Sensor ready 
00332     */ 
00333     bool getStatus(void);
00334     
00335 private:
00336     //Member variables
00337     I2C* _i2c;
00338     char _slaveAddress;    
00339 
00340     //Member methods
00341    /** Read 8 bit value from register
00342      *
00343      * @param reg Index of register
00344      * @return data value from register
00345      */       
00346     char _readReg8(char reg);
00347 
00348    /** Write 8 bit value to register
00349      *
00350      * @param reg Index of register
00351      * @param data value to write
00352      */     
00353     void _writeReg8(char reg, char data);
00354 
00355    /** Read 16 bit value from register
00356      * Used for Critical temp threshold, Low and High temp threshold window and Hysteresis
00357      *
00358      * @param reg Index of register
00359      * @return data value from register  
00360      */     
00361     int16_t _readReg16(char reg);
00362     
00363    /** Write 16 bit value to register
00364      * Used for Critical temp threshold, Low and High temp threshold window and Hysteresis
00365      *
00366      * @param reg Index of register
00367      * @param data value to write
00368      */         
00369     void _writeReg16(char, int16_t data);
00370 
00371    /** Get Temperature as float in °Celsius
00372      * Used for Critical temp threshold, Low and High temp threshold window and Hysteresis 
00373      *
00374      * @param reg Index of register to read temp value
00375      * @return float Temperature in °Celsius
00376     */     
00377     float _readTempHelper(char reg);
00378 
00379    /** Set Temperature as float in °Celsius
00380      * Used for Critical temp threshold, Low and High temp threshold window and Hysteresis
00381      *
00382      * @param reg Index of register to write temp value
00383      * @param temp float Temperature value in °Celsius
00384      */        
00385     void _writeTempHelper(char reg, float temp);
00386 };
00387 
00388 #endif