Library for the humidity and temperature sensors SI70xx, especially SI7021 with two-wire (also known as I2C) bus interface usually on board GY-21.
- Sensor address is
0x40hardcoded and cannot be changed by any library method. - The library provides measured temperature in degrees of Celsius and relative humidity in percentage.
- For conversion among various temperature unit scales and for calculating dew point temperature use library
gbjAppHelpers. - At erroneous measurement of relative humidity or temperature the corresponding method returns erroneous value
255.0.
- 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().
- DeviceTypes::TYPE_SAMPLE1: Sensor type Engineering samples.
- DeviceTypes::TYPE_SAMPLE2: Sensor type Engineering samples.
- DeviceTypes::TYPE_7013: Sensor type
Si7013. - DeviceTypes::TYPE_7020: Sensor type
Si7020. - DeviceTypes::TYPE_7021: Sensor type
Si7021.
- FirmwareVersions::FW_VERSION_10: Firmware revision byte for sensors of the series
A10. - FirmwareVersions::FW_VERSION_20: Firmware revision byte for sensors of the series
A20.
In a sketch the constants can be referenced in following forms:
- Static constant in the form
gbj_si70::<enumeration>::<constant>or shortlygbj_si70::<constant>, e.g., gbj_si70::DeviceTypes::TYPE_7021 or gbj_si70::TYPE_7021. - Instance constant in the form
<object>.<constant>, e.g., sensor.TYPE_7021.
gbj_si70 sensor = gbj_si70(sensor.CLOCK_400KHZ);- setResolutionTemp14()
- setResolutionTemp13()
- setResolutionTemp12()
- setResolutionTemp11()
- setResolutionRhum12()
- setResolutionRhum11()
- setResolutionRhum10()
- setResolutionRhum8()
- setHeaterEnabled()
- setHeaterDisabled()
- setHeaterLevel()
- setHoldMasterMode()
- setUseValuesTyp()
- setUseValuesMax()
- getResolutionTemp()
- getResolutionRhum()
- getDeviceType()
- getFwRevision()
- getHeaterEnabled()
- getHeaterLevel()
- getHeaterCurrent()
- getSNA()
- getSNB()
- getSerialNumber()
- getVddStatus()
- getHoldMasterMode()
- getErrorRHT()
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_si70(ClockSpeeds clockSpeed, uint8_t pinSDA, uint8_t pinSCL)
-
clockSpeed: Two-wire bus clock frequency in Hertz. If the clock is not from enumeration, it fallbacks to 100 kHz.
- 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_si70 sensor = gbj_si70(); // It is equivalent to
gbj_si70 sensor = gbj_si70(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.
- All the method parameters can be changed dynamically with corresponding setters later in a sketch.
ResultCodes begin(bool holdMasterMode)
- holdMasterMode: Logical flag about blocking (holding) serial clock line during measurement. At no holding master mode other communication on the bus can be performed.
- Valid values: true, false
- Default value: true
Some of result or error codes.
The method resets the sensor and sets control registers to their reset settings values.
ResultCodes reset()
None
Some of result or error codes.
The method writes the lock byte to the non-volatile memory of a sensor. It is enough to do it just once for every sensor.
ResultCodes writeLockByte()
None
Some of result or error codes.
The method is overloaded and measures either relative humidity alongside with temperature at once or the humidity alone.
- The temperature is returned through referenced input parameter.
float measureHumidity()
float measureHumidity(float &temperature)
- temperature: Referenced variable for placing a temperature value in centigrade.
- Valid values: sensor specific
- Default value: none
Relative humidity truncated to range 0 - 100 °C or erroneous value returned by getErrorRHT().
gbj_si70 sensor = gbj_si70();
float tempValue, rhumValue;
setup()
{
if (sensor.isSuccess(sensor.begin()))
{
rhumValue = sensor.measureHumidity(tempValue);
rhumValue = sensor.measureHumidity();
}
}The method measures temperature only without measuring the relative humidity.
float measureTemperature()
None
Temperature in centigrade or erroneous value returned by getErrorRHT().
The particular method sets the bit resolution for temperature measurement to the value in its name.
- The method sets the corresponding bit resolution for the relative humidity measurement at the same time by this relation:
| Temperature | Relative Humidity |
|---|---|
| 11 | 11 |
| 12 | 8 |
| 13 | 10 |
| 14 | 12 |
ResultCodes setResolutionTemp11()
ResultCodes setResolutionTemp12()
ResultCodes setResolutionTemp13()
ResultCodes setResolutionTemp14()
None
Some of result or error codes.
The method returns the temperature measurement resolution in bits.
uint8_t getResolutionTemp()
None
Bit resolution (11, 12, 13, or 14) or some of error codes.
setResolutionTemp11(), setResolutionTemp12(), setResolutionTemp13(), setResolutionTemp14()
The particular method sets the bit resolution for relative humidity measurement to the value in its name.
- The method sets the corresponding bit resolution for the temperature measurement at the same time by this relation:
| Relative Humidity | Temperature |
|---|---|
| 11 | 11 |
| 8 | 12 |
| 10 | 13 |
| 12 | 14 |
ResultCodes setResolutionRhum8()
ResultCodes setResolutionRhum10()
ResultCodes setResolutionRhum11()
ResultCodes setResolutionRhum12()
None
Some of result or error codes.
The method returns the relative humidity measurement resolution in bits.
uint8_t getResolutionRhum()
None
Bit resolution (8, 10, 11, or 12) or some of error codes.
setResolutionRhum8(), setResolutionRhum10(), setResolutionRhum11(), setResolutionRhum12()
The particular method turns on or off a heater built-in in the sensor.
ResultCodes setHeaterEnabled()
ResultCodes setHeaterDisabled()
None
Some of result or error codes.
The method returns the status of the sensor's heater.
bool getHeaterEnabled()
None
Flag about the heater switched on or off.
- true: The heater is on.
- false: The heater is off.
The method sets the heater level if the heater is enabled and determines by that level the heating current. The heater level is determined by lower 4 bits in the heater control register.
- The sensors of the class
A10have no current selection. They use predefined current at heater enabled and ignore the input parameter.
ResultCodes setHeaterLevel(uint8_t heaterLevel)
- heaterLevel: Desired heater level.
- Valid values: non-negative integer 0 ~ 15
- Default value: 0
Some of result or error codes.
The method returns the heater level as an integer if the heater is enabled
- The sensors of the class A10 have no current selection, so that they return only zero heater level.
uint8_t getHeaterLevel()
None
Current heater level in range 0 ~ 15 or some of error codes.
The method returns the heater direct current in milliampers if the heater is enabled.
- The sensors of the class
A10have no current selection, so that they return constant heater current.
float getHeaterCurrent()
None
Heater current in milliampers corresponding to the heater level or zero value if some errors occurs.
The method returns the byte, which determines the type of a sensor.
DeviceTypes getDeviceType()
None
Device type defined by library constants DeviceTypes.
getSNA(), getSNB(), getSerialNumber()
The method returns the firmware revision byte of the sensor, which determines the series of sensors, either A10 or A20.
FirmwareVersions getFwRevision()
None
Firmware revision defined by library constants FirmwareVersions.
getSNA(), getSNB(), getSerialNumber()
The particular method returns the corresponding 32-bit part of the serial number as a double word and the entire 64-bit serial number of the sensor.
uint32_t getSNA()
uint32_t getSNB()
uint64_t getSerialNumber()
None
Upper (SNA), lower (SNB) serial double word, or entire serial number.
The method returns the status of the supply voltage, which the sensor is powered by.
bool getVddStatus()
None
Flag about the correctness of the operating voltage.
- true: The voltage is correct.
- false: The voltage is incorrect.
The method sets internal flag about particular measuring hold master mode.
void setHoldMasterMode(bool holdMasterMode)
- holdMasterMode: See the same parameter in the method begin().
None
The method sets internal flag about particular measuring hold master mode.
bool getHoldMasterMode()
None
Current flag about measuring hold master mode.
The particular method sets the internal flag whether typical or maximal values from the datasheet should be used regarding conversion and reset times.
void setUseValuesTyp()
void setUseValuesMax()
None
None
The method return virtually wrong relative humidity or temperature value at erroneous measurement usually at incorrect CRC from the sensor.
float getErrorRHT()
None
Erroneous relative humidity or temperature.