Si7020.h

00001 /*******************************************************************************
00002  * Copyright (C) 2015 Maxim Integrated Products, Inc., All Rights Reserved.
00003  *
00004  * Permission is hereby granted, free of charge, to any person obtaining a
00005  * copy of this software and associated documentation files (the "Software"),
00006  * to deal in the Software without restriction, including without limitation
00007  * the rights to use, copy, modify, merge, publish, distribute, sublicense,
00008  * and/or sell copies of the Software, and to permit persons to whom the
00009  * Software is furnished to do so, subject to the following conditions:
00010  *
00011  * The above copyright notice and this permission notice shall be included
00012  * in all copies or substantial portions of the Software.
00013  *
00014  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
00015  * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
00016  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
00017  * IN NO EVENT SHALL MAXIM INTEGRATED BE LIABLE FOR ANY CLAIM, DAMAGES
00018  * OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
00019  * ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
00020  * OTHER DEALINGS IN THE SOFTWARE.
00021  *
00022  * Except as contained in this notice, the name of Maxim Integrated
00023  * Products, Inc. shall not be used except as stated in the Maxim Integrated
00024  * Products, Inc. Branding Policy.
00025  *
00026  * The mere transfer of this software does not imply any licenses
00027  * of trade secrets, proprietary technology, copyrights, patents,
00028  * trademarks, maskwork rights, or any other form of intellectual
00029  * property whatsoever. Maxim Integrated Products, Inc. retains all
00030  * ownership rights.
00031  *******************************************************************************
00032  */
00033 
00034 #ifndef _SI7020_H_
00035 #define _SI7020_H_
00036 
00037 #include "mbed.h"
00038 
00039 /**
00040  * Silicon Labs Si7020 Humidity and Temperature Sensor
00041  *
00042  * @code
00043  * #include <stdio.h>
00044  * #include "mbed.h"
00045  * #include "Si7020.h"
00046  * 
00047  * I2C i2c(I2C_SDA, I2C_SCL);
00048  * Si7020 si(&i2c);
00049  * 
00050  * int main()
00051  * {
00052  *     while(1) {
00053  * 
00054  *         float humid;
00055  *         if(si.getHumidity(&humid) != 0) {
00056  *             printf("Error getting humidity\n");
00057  *             humid = -1;
00058  *         }
00059  * 
00060  *         float temp;
00061  *         if(si.getTemperature(&temp) != 0) {
00062  *             printf("Error getting temperature");
00063  *             temp = -1;
00064  *         } 
00065  *         printf("Humidity = %f%% Temperature = %fC\n", humid, temp);
00066  * 
00067  *         wait(1);
00068  *     }
00069  * }
00070  * @endcode
00071  */
00072 class Si7020
00073 {
00074 
00075 public:
00076 
00077     /**
00078      * @brief   Measurement resolution.
00079      * @details Controls the resolution of the humidity and temperarure readings.
00080      */
00081     typedef enum {
00082         RH_12b_TEMP_14b = 0x0, ///< 12 bits for RH, 14 bits for Temp
00083         RH_8b_TEMP_12b = 0x1,  ///< 8 bits for RH, 12 bits for Temp
00084         RH_10b_TEMP_13b = 0x2, ///< 10 bits for RH, 13 bits for Temp
00085         RH_11b_TEMP_11b = 0x3, ///< 11 bits for RH, 11 bits for Temp
00086     } resolution_t;
00087 
00088     /**
00089      * Si7020 constructor.
00090      *
00091      * @param sda mbed pin to use for SDA line of I2C interface.
00092      * @param scl mbed pin to use for SCL line of I2C interface.
00093      */
00094     Si7020(PinName sda, PinName scl);
00095 
00096     /**
00097      * Si7020 constructor.
00098      *
00099      * @param i2c I2C object to use
00100      */
00101     Si7020(I2C *i2c);
00102 
00103     /**
00104      * Si7020 destructor.
00105      */
00106     ~Si7020();
00107 
00108     /**
00109      * @brief   Reset.
00110      * @details Sends the rest command.
00111      * @returns 0 if no errors, -1 if error.
00112      */
00113     int reset(void);
00114 
00115     /**
00116      * @brief   Get Electronic ID.
00117      * @details Gets the Electronic ID of the connected device. Verifies the 
00118      *          ID with an 8-bit CRC.
00119      *
00120      * @param   Character buffer to store the id. Needs to be at least 8 bytes.
00121      * @returns 0 if no errors, -1 if error.
00122      */
00123     int getElectronicId(char *id);
00124 
00125     /**
00126      * @brief   Configure sample resolution.
00127      * @details Sets the number of bits used for humidity and temperature readings.
00128      * @param   resolution Enum for the resolution setting.
00129      * @returns 0 if no errors, -1 if error.
00130      */
00131     int configResolution(Si7020::resolution_t resolution);
00132 
00133     /**
00134      * @brief   Get temperature reading.
00135      * @details Initiates a temperature reading and blocks until reading has
00136      *          been calculated. 
00137      * 
00138      * @note    Will hold the I2C bus until reading is complete. Refer to datasheet
00139      *          for timing specifications.
00140      * 
00141      * @param   tempCx10 Pointer for temperature reading. Unit is 1/10th degree Celcius.
00142      * @returns 0 if no errors, -1 if error.
00143      */
00144     int getTemperature(int16_t *tempCx10);
00145 
00146     /**
00147      * @brief   Get temperature reading.
00148      * @details Initiates a temperature reading and blocks until reading has
00149      *          been calculated. 
00150      * 
00151      * @note    Will hold the I2C bus until reading is complete. Refer to datasheet
00152      *          for timing specifications.
00153      * 
00154      * @param   tempC Pointer for temperature reading. Unit is degree Celcius.
00155      * @returns 0 if no errors, -1 if error.
00156      */
00157     int getTemperature(float *tempC);
00158 
00159     /**
00160      * @brief   Start temperature reading.
00161      * @details Initiates a temperature reading. Will not hold the bus or block.
00162      * @returns 0 if no errors, -1 if error.
00163      */
00164     int startTemperature(void);
00165 
00166     /**
00167      * @brief   Check temperature reading.
00168      * @details Checks to see if the temperature reading has been completed.
00169                 Returns temperature if reading complete.
00170      * @note    Must call startTemperature() prior to calling this function. 
00171      * @param   tempCx10 Pointer for temperature reading. Unit is 1/10th degree Celcius.
00172      * @returns 0 if reading taken, -1 if reading pending.
00173      */
00174     int checkTemperature(int16_t *tempCx10);
00175 
00176     /**
00177      * @brief   Check temperature reading.
00178      * @details Checks to see if the temperature reading has been completed.
00179                 Returns temperature if reading complete.
00180      * @note    Must call startTemperature() prior to calling this function. 
00181      * @param   tempC Pointer for temperature reading. Unit is degree Celcius.
00182      * @returns 0 if reading taken, -1 if reading pending.
00183      */
00184     int checkTemperature(float *tempC);
00185 
00186     /**
00187      * @brief   Get humidity reading.
00188      * @details Initiates a humidity reading and blocks until reading has
00189      *          been calculated.
00190      *
00191      * @note    Will hold the I2C bus until reading is complete. Refer to datasheet
00192      *          for timing specifications.
00193      * 
00194      * @param   humidx10 Pointer for humidity reading. Unit is 1/10th percent.
00195      * @returns 0 if no errors, -1 if error.
00196      */
00197     int getHumidity(int16_t *humidx10);
00198 
00199     /**
00200      * @brief   Get humidity reading.
00201      * @details Initiates a humidity reading and blocks until reading has
00202      *          been calculated.
00203      *
00204      * @note    Will hold the I2C bus until reading is complete. Refer to datasheet
00205      *          for timing specifications.
00206      * 
00207      * @param   humid Pointer for humidity reading. Unit is percent.
00208      * @returns 0 if no errors, -1 if error.
00209      */
00210     int getHumidity(float *humid);
00211 
00212     /**
00213      * @brief   Start humidity reading.
00214      * @details Initiates a humidity reading. Will not hold the bus or block.
00215      * @returns 0 if no errors, -1 if error.
00216      */
00217     int startHumidity(void);
00218 
00219     /**
00220      * @brief   Check humidity reading.
00221      * @details Checks to see if the humidity reading has been completed.
00222                 Returns humidity if reading complete.
00223 
00224      * @note    Must call startHumidity() prior to calling this function. 
00225      * @param   humidCx10 Pointer for humidity reading. Unit is 1/10th percent.
00226      * @returns 0 if reading taken, -1 if reading pending.
00227      */
00228     int checkHumidity(int16_t *humidx10);
00229 
00230     /**
00231      * @brief   Check humidity reading.
00232      * @details Checks to see if the humidity reading has been completed.
00233                 Returns humidity if reading complete.
00234 
00235      * @note    Must call startHumidity() prior to calling this function. 
00236      * @param   humid Pointer for humidity reading. Unit is percent.
00237      * @returns 0 if reading taken, -1 if reading pending.
00238      */
00239     int checkHumidity(float *humid);
00240 
00241     /**
00242      * @brief   Get temperature from humidity reading.
00243      * @details Gets temperature reading from previous humidity reading.
00244      * @note    Must call startHumidity() prior to calling this function. 
00245      * @param   tempC Pointer for temperature reading. Unit is degree Celcius.
00246      * @returns 0 if reading taken, -1 if reading pending.
00247      */
00248     int getPrevTemperature(float* tempC);
00249 
00250     /**
00251      * @brief   Get temperature from humidity reading.
00252      * @details Gets temperature reading from previous humidity reading.
00253      * @note    Must call startHumidity() prior to calling this function. 
00254      * @param   tempCx10 Pointer for temperature reading. Unit is 1/10th degree Celcius.
00255      * @returns 0 if reading taken, -1 if reading pending.
00256      */
00257     int getPrevTemperature(int16_t *tempCx10);
00258 
00259     /**
00260      * @brief   Get firmware revision.
00261      * @details Reads the firmware revision, refer to datasheet for codes.
00262      * @param   rev Pointer to store firmware revision.
00263      * @returns 0 if no errors, -1 if error.
00264      */
00265     int getRev(char *rev);
00266 
00267     /**
00268      * @brief   Control heater.
00269      * @details Enable or disable the heater.
00270      * @param   enable True to enable heater, false to disable.
00271      * @returns 0 if no errors, -1 if error.
00272      */
00273     int heater(bool enable);
00274 
00275 private:
00276 
00277     char crc8(char value, char seed);
00278     I2C *i2c_;
00279     bool i2c_owner;
00280 };
00281 
00282 #endif /* _SI7020_H_ */