Library for the temperature sensors TMP102 with two-wire (also known as I2C) bus interface.
- Sensor can have following addresses, which allow up to 4 sensors present on the same two-wire bus:
0x48for ADD0 pin connected to GND (ground)0x49for ADD0 pin connected to V+ (power supply positive rail)0x4Afor ADD0 pin connected to SDA (serial data rail of the two-wire bus)0x4Bfor ADD0 pin connected to SCL (serial clock rail of the two-wire bus)
- The library provides measured temperature in degrees of Celsius.
- For conversion among various temperature unit scales and for calculating dew point temperature use library
gbjAppHelpers. - The sensor in normal mode has 12-bit resolution with sensitivity
0.0625 °C/bitwithin the measurement range-55 °C ~ +128 °C. - The extended mode has 13-bit resolution, but the same sensitivity and it just extends the upper temperature measurement range up to
+150 °C.- Switching (reconfiguration) to extended mode from normal mode or vice-versa needs a time delay cca
350 millisecondsafter it in order to settle the sensor and stabilize the temperature conversion. - Without the delay after switching to extended mode the reading is doubled to real temperature at first reading after switching mode.
- Without the delay after switching to normal mode the reading is halved to real temperature at first reading after switching mode.
- Library does not have implemented such specific delay after mode switching due to small usefulness of the extended mode.
- Library caches pointer and configuration register.
- Switching (reconfiguration) to extended mode from normal mode or vice-versa needs a time delay cca
- Connect microcontroller's pin
D0to sensor's pin SDA (Serial Data). - Connect microcontroller's pin
D1to sensor's pin SCL (Serial Clock).
- Connect microcontroller's pin
A4to sensor's pin SDA (Serial Data). - Connect microcontroller's pin
A5to sensor's pin SCL (Serial Clock).
- Connect microcontroller's pin
D2to sensor's pin SDA (Serial Data). - Connect microcontroller's pin
D1to sensor's pin SCL (Serial Clock).
- Particle.h: Includes alternative (C++) data type definitions.
- Arduino.h: Main include file for the Arduino SDK version greater or equal to 100.
- inttypes.h: Integer type conversions. This header file includes the exact-width integer definitions and extends them with additional facilities provided by the implementation.
- TwoWire: I2C system library loaded from the file
Wire.h.
- gbjTwoWire: I2C custom library loaded from the file
gbj_twowire.h, which provides common bus functionality.
The library does not have specific error codes. Error codes as well as result code are inherited from the parent library gbjTwoWire only. The result code and error codes can be tested in the operational code with its method getLastResult(), isError() or isSuccess().
- Addresses::ADDRESS_GND: ADD0 pin connected to GND pin (default).
- Addresses::ADDRESS_VCC: ADD0 pin connected to positive power supply rail.
- Addresses::ADDRESS_SDA: ADD0 pin connected to serial data rail of two-wire bus.
- Addresses::ADDRESS_SCL: ADD0 pin connected to serial clock rail of two-wire bus.
In a sketch the constants can be referenced in following forms:
- Static constant in the form
gbj_tmp102::<enumeration>::<constant>or shortlygbj_tmp102::<constant>, e.g., gbj_tmp102::Addresses::ADDRESS_GND or gbj_tmp102::ADDRESS_GND. - Instance constant in the form
<object>.<constant>, e.g., sensor.ADDRESS_GND.
gbj_tmp102 sensor = gbj_tmp102(sensor.CLOCK_400KHZ)The configuration of the sensor is realized by the configuration register, which consists of several configuration bits determining its behavior. The library stores (caches) the value of the configuration register in its instance object.
The sensor configuration implemented in the library is based on updating cached configuration value in advanced and finally to send that value to the sensor and write all configuration bits to configuration register at once in order to reduce communication on the two-wire bus in contrast to sending configuration bits to the sensor individually.
It is good practice or sometimes necessary to read the configuration register right before using getters, especially those related to particular configuration bits in order to get its current value.
- setConfiguration()
- setAlertLow()
- setAlertHigh()
- setUseValuesTyp()
- setUseValuesMax()
- configAlertActiveLow()
- configAlertActiveHigh()
- configExtendedMode()
- configNormalMode()
- configShutdownMode()
- configContinuousMode()
- configInterruptMode()
- configThermostatMode()
- configOneshotMode()
- configConversionRate_025hz()
- configConversionRate_1hz()
- configConversionRate_4hz()
- configConversionRate_8hz()
- configConversionPeriod_4000ms()
- configConversionPeriod_1000ms()
- configConversionPeriod_250ms()
- configConversionPeriod_125ms()
- configFaults1()
- configFaults2()
- configFaults4()
- configFaults6()
- getConfiguration()
- getAlertLow()
- getAlertHigh()
- getAlertActiveLow()
- getAlertActiveHigh()
- getAlert()
- getNormalMode()
- getExtendedMode()
- getContinuousMode()
- getShutdownMode()
- getInterruptMode()
- getThermostatMode()
- getOneshotMode()
- getConversionRate()
- getConversionPeriod()
- getFaults()
- getErrorValue()
Other possible setters and getters are inherited from the parent library gbjTwoWire and described there.
The library does not need special constructor and destructor, so that the inherited ones are good enough and there is no need to define them in the library, just use it with default or specific parameters as defined at constructor of parent library gbjTwoWire.
- Constructor sets parameters specific to the two-wire bus in general.
- All the constructor parameters can be changed dynamically with corresponding setters later in a sketch.
gbj_tmp102(uint32_t clockSpeed, uint8_t pinSDA, uint8_t pinSCL)
-
clockSpeed: Two-wire bus clock frequency in Hertz.
- Valid values:ClockSpeeds::CLOCK_100KHZ, ClockSpeeds::CLOCK_400KHZ
- Default value: ClockSpeeds::CLOCK_100KHZ
-
pinSDA: Microcontroller's pin for serial data. It is not a board pin but GPIO number. For hardware two-wire bus platforms it is irrelevant and none of methods utilizes this parameter for such as platforms for communication on the bus. On the other hand, for those platforms the parameters might be utilized for storing some specific attribute in the class instance object.
- Valid values: positive integer
- Default value: 4 (GPIO4, D2)
-
pinSCL: Microcontroller's pin for serial clock. It is not a board pin but GPIO number. For hardware two-wire bus platforms it is irrelevant and none of methods utilizes this parameter for such as platforms. On the other hand, for those platforms the parameters might be utilized for storing some specific attribute in the class instance object.
- Valid values: positive integer
- Default value: 5 (GPIO5, D1)
Object performing the sensor management. The constructor cannot return a result or error code directly, however, it stores them in the instance object.
The method has all arguments defaulted and calling without any parameters is equivalent to the calling with all arguments set by corresponding constant with default value:
gbj_tmp102 sensor = gbj_tmp102(); // It is equivalent to
gbj_tmp102 sensor = gbj_tmp102(sensor.CLOCK_100KHZ, D2, D1)The method takes, sanitizes, and stores sensor parameters to a class instance object and initiates two-wire bus.
- The method sets parameters specific to the sensor itself.
- The method resets the sensor to its power-up state.
- The method resets the sensor by the general call software reset sending the code
0x06to the two-wire bus at address0x00and reads the content of the configuration register to the library instance object. - All the method parameters can be changed dynamically with corresponding setters later in a sketch.
- The method enables to set the sensor's address according to the ADDR pin, if it is wired to a microcontroller's pin.
ResultCodes begin(Addresses address)
- address: One of two possible 7 bit addresses of the sensor corresponding to the ADDR pin connection.
- Valid values: Addresses::ADDRESS_GND, Addresses::ADDRESS_VCC,, Addresses::ADDRESS_SDA Addresses::ADDRESS_SCL
- Default value: gbj_tmp102::ADDRESS_GND
- The default values is set to address corresponding to grounded ADD0 pin.
- If input value is none of expected ones, the method fallbacks it to default address.
- Implementing addressing allows up to 4 sensors present on the same two-wire bus.
- Module boards with the sensor have usually ADD0 grounded and are equipped with soldering pad for reconnecting that pin to V+ rail.
Some of result or error codes.
The method has all arguments defaulted and calling without any parameters is equivalent to the calling with all arguments set by corresponding constant with default value:
gbj_tmp102 sensor = gbj_tmp102();
setup()
{
sensor.begin(); // It is equivalent to
sensor.begin(sensor.ADDRESS_GND);
}The method resets the sensor by writing power-up value to the configuration register and its cache in the instance object. It causes resetting all internal registers to their power-up values, which determine following configuration and values:
- Upper alert temperature limit 80 °C.
- Lower alert temperature limit 75 °C.
- Normal mode (12 bit).
- Conversion rate 4 Hz.
- Continuous power mode (shutdown mode off).
- Thermostat (comparator) mode.
- Alert pin active low.
- Alert active.
- One fault for fault queue.
- One-shot conversion off.
ResultCodes reset()
None
Some of result or error codes.
The method measures temperature.
- The method reads the temperature register with value from recent conversion.
- The continuous mode should be configured before the measurement, if in meanwhile the one-shot mode has been set, but just once.
- Right after power-up or resetting of the sensor the continuous mode is set by default.
float measureTemperature()
None
Temperature in centigrade or erroneous value returned by getErrorValue(). The error code can be tested in the operational code with the method getLastResult(), isError(), or isSuccess().
The method configures shutdown mode and one-shot conversion of the sensor. It waits until conversion finishes and returns ambient temperature in centigrade.
- The method is useful at very long periods (couple of minutes and hours) between measurements in order to save power consumption.
float measureTemperatureOneshot()
None
Temperature in centigrade or erroneous value returned by getErrorValue(). The error code can be tested in the operational code with the method getLastResult(), isError(), or isSuccess().
The method writes the new content of the configuration register stored in the instance object (configuration cache) to the sensor. This content should has been prepared by methods of type configXXX right before.
ResultCodes setConfiguration()
None
Some of result or error codes.
The method reads configuration register and its value stores in the instance object, so that it caches it and enables it for corresponding getters.
ResultCodes getConfiguration()
None
Some of result or error codes.
The particular method writes either lower or upper temperature limit.
- A method for particular temperature limit does not check its relation to the related limit. It should be done in a sketch. So that, those methods allows to set high limit less than low limit.
ResultCodes setAlertLow(float temperatureLow)
ResultCodes setAlertHigh(float temperatureHigh)
-
temperatureLow: Low temperature limit in centigrade.
- Valid values: -55.0 ~ 150.0
- Default value: 75.0
-
temperatureHigh: Hight temperature limit in centigrade.
- Valid values: -55.0 ~ 150.0
- Default value: 80.0
Some of result or error codes.
The particular method reads upper or lower temperature limit from the sensor.
float getAlertLow()
float getAlertHigh()
None
Lower or upper temperature limit in centigrade or erroneous value returned by getErrorValue(). The error code can be tested in the operational code with the method getLastResult(), isError(), or isSuccess().
The particular method sets the internal flag whether typical or maximal values from the datasheet should be used regarding conversion time.
void setUseValuesTyp()
void setUseValuesMax()
None
None
The particular method updates alert activity bit state in the cached configuration value before its sending to the sensor by the method setConfiguration().
void configAlertActiveLow()
void configAlertActiveHigh()
None
None
getAlertActiveLow(), getAlertActiveHigh()
The particular method determines flag about alert activity mode from the cached configuration value.
bool getAlertActiveLow()
bool getAlertActiveHigh()
None
Flag about set particular alert activity mode.
configAlertActiveLow(), configAlertActiveHigh()
The method provides flag about state of alert pin from cached configuration value.
- It is suitable for detecting the alert by software without need of hardware sensing the ALERT pin of the sensor.
bool getAlert()
None
Flag about ALERT pin state.
The particular method turns on corresponding resolution mode in the cached configuration value before its sending to the sensor by the method setConfiguration().
- At normal mode the resolution is the 12-bit resolution.
- At extended mode the resolution is the 13-bit resolution.
- Extended mode does not increase sensitivity, just extents the upper temperature measurement range from +128 to +150 centigrades. So that in normal working conditions it is not very useful.
- After changing resolution mode and writing it to the sensor it is needed to wait cca 350 milliseconds in order to settle the sensor and provide conversion. Otherwise the first conversion after changing resolution to extended mode from normal one doubles the measured temperature and after changing to normal mode from extended one halves the temperature, which might confuse follow-up logic or controlling mechanizm.
- The library does not have extra delay after resolution change implemented, so that it must be enforced in a sketch.
void configExtendedMode()
void configNormalMode()
None
None
getExtendedMode(), getNormalMode()
The particular method determines flag about resolution mode state from the cached configuration value.
bool getExtendedMode()
bool getNormalMode()
None
Flag about set particular resolution mode.
configExtendedMode(), configNormalMode()
The particular method turns on corresponding power mode in the cached configuration value before its sending to the sensor by the method setConfiguration().
- At shutdown mode the sensor turns on all its system except the serial interface and reduces power consumption. This mode is utilized by the method measurementTemperatureOneshot() for one-shot temperature measurement.
- At continuous mode the sensor performs continuous temperature conversion according to its current conversion rate.
void configShutdownMode()
void configContinuousMode()
None
None
getShutdownMode(), getContinuousMode()
The particular method determines flag about power mode state from the cached configuration value.
bool getShutdownMode()
bool getContinuousMode()
None
Flag about set particular power mode.
configShutdownMode(), configContinuousMode()
The particular method turns on corresponding action mode in the cached configuration value before its sending to the sensor by the method setConfiguration().
- At interruption mode the sensor generates a short impulse on ALERT pin at reaching particular temperature limit with particular polarity according to the alert activity mode. The impulse is active until next reading a sensor's register, usually the temperature one.
- At termostat mode the sensor changes state of ALERT pin at reaching a temperature limit with particular polarity according to the alert activity mode and keeps it until reaching another temperature limit.
void configInterruptMode()
void configThermostatMode()
None
None
getInterruptMode(), getThermostatMode()
The particular method determines flag about action mode state from the cached configuration value.
bool getInterruptMode()
bool getThermostatMode()
None
Flag about set particular action mode.
configInterruptMode(), configThermostatMode()
The method turns on one-shot temperature measurement mode in the cached configuration value before its sending to the sensor by the method setConfiguration().
- This mode is utilized by the method measurementTemperatureOneshot() for one-shot temperature measurement.
void configOneshotMode()
None
None
The method provides current consecutive faults in form of value of pair of fault queue bits from the cached configuration value. That value can be compared to corresponding library class constants in order to determine number of consecutive faults.
bool getOneshotMode()
None
Flag about set one-shot measurement mode.
configConversionRate_025hz(), configConversionRate_1hz(), configConversionRate_4hz(), configConversionRate_8hz()
The particular method sets conversion rate bits in the cached configuration value before its sending to the sensor by the method setConfiguration().
- The rate is determined by desired conversion frequency in Hertz denoted in the method's name.
void configConversionRate_025hz()
void configConversionRate_1hz()
void configConversionRate_4hz()
void configConversionRate_8hz()
None
None
The method provides current conversion rate as a frequency in Hertz based on conversion rate bits from the cached configuration value.
float getConversionRate()
None
Conversion frequency in Hertz.
configConversionPeriod_4000ms(), configConversionPeriod_1000ms(), configConversionPeriod_250ms(), configConversionPeriod_125ms()
The particular method sets conversion rate bits in the cached configuration value before its sending to the sensor by the method setConfiguration().
- The rate is determined by desired conversion time period in milliseconds denoted in the method's name.
- The particular method set the corresponding conversion frequency as a reciprocal value.
void configConversionPeriod_4000ms()
void configConversionPeriod_1000ms()
void configConversionPeriod_250ms()
void configConversionPeriod_125ms()
None
None
The method provides current conversion rate as a time period in milliseconds based on conversion rate bits from the cached configuration value.
uint16_t getConversionPeriod()
None
Conversion time period in milliseconds.
The method sets fault queue bits in the cached configuration value before its sending to the sensor by the method setConfiguration().
- The number of faults is determined by a digit in the method's name.
- The number determines a number of consecutive faults (breaking a particular temperature limit) to activate particular alert. That number eliminate a environmental noise.
void configFaults1()
void configFaults2()
void configFaults4()
void configFaults6()
None
None
The method provides current number of consecutive faults based on fault queue bits from the cached configuration value.
uint8_t getFaults()
None
Number of conscutive faults for a temperature alert activation.
configFaults1(), configFaults2(), configFaults4(), configFaults6()
The method returns virtually wrong temperature value at erroneous measurement usually at failure of two-wire bus.
float getErrorValue()
None
Erroneous temperature value. The error code can be tested in the operational code with the method getLastResult(), isError(), or isSuccess().