GY-63_MS5611/libraries/SHT85/README.md

214 lines
8.8 KiB
Markdown
Raw Normal View History

2021-05-26 06:06:51 -04:00
[![Arduino CI](https://github.com/robtillaart/SHT85/workflows/Arduino%20CI/badge.svg)](https://github.com/marketplace/actions/arduino_ci)
2021-08-24 12:45:23 -04:00
[![Arduino-lint](https://github.com/RobTillaart/SHT85/actions/workflows/arduino-lint.yml/badge.svg)](https://github.com/RobTillaart/SHT85/actions/workflows/arduino-lint.yml)
2021-10-20 02:32:56 -04:00
[![JSON check](https://github.com/RobTillaart/SHT85/actions/workflows/jsoncheck.yml/badge.svg)](https://github.com/RobTillaart/SHT85/actions/workflows/jsoncheck.yml)
2021-05-26 06:06:51 -04:00
[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](https://github.com/RobTillaart/SHT85/blob/master/LICENSE)
2021-08-24 12:45:23 -04:00
[![GitHub release](https://img.shields.io/github/release/RobTillaart/SHT85.svg?maxAge=3600)](https://github.com/RobTillaart/SHT85/releases)
2021-05-26 06:06:51 -04:00
# SHT85
2021-12-28 08:21:26 -05:00
Arduino library for the SHT85 temperature and humidity sensor.
2021-05-26 06:06:51 -04:00
Based upon the SHT31 library - https://github.com/RobTillaart/SHT31
**Warning:** to keep self-heating below 0.1<EFBFBD>C, the SHT85 sensor should
not be used for more than 10% of the time.
## Description
```
2021-10-20 02:32:56 -04:00
// TOPVIEW SHT85
2021-05-26 06:06:51 -04:00
// +-------+
// +-----\ | SDA 4 -----
2021-10-20 02:32:56 -04:00
// | /-+ ----+ GND 3 -----
// | +-+ ----+ +5V 2 -----
2021-05-26 06:06:51 -04:00
// +-----/ | SCL 1 -----
// +-------+
```
2021-10-20 02:32:56 -04:00
2021-05-26 06:06:51 -04:00
The SHT85 sensors should work up to 1000 KHz, however during tests
2021-08-07 06:34:52 -04:00
with an Arduino UNO it stopped between 500 - 550 KHz so to be safe I recommend
not to use it above 400 KHz. Also the differences in read time becomes
2021-05-26 06:06:51 -04:00
quite small. (max 15% gain). See output example sketch.
| I2C speed | read ms | notes |
|:---------:|:-------:|:------|
| 100 KHz | 5.11 | |
| 150 KHz | 4.79 | |
| 200 KHz | 4.64 | |
| 250 KHz | 4.56 | |
| 300 KHz | 4.50 | |
| 350 KHz | 4.47 | |
| 400 KHz | 4.45 | |
| 450 KHz | 4.43 | |
| 500 KHz | 4.42 | |
| 550 KHz | ---- | fail |
### Compatibility
This library should also work for SHT30, SHT31 and SHT35 but
this is not verified yet.
2021-12-28 08:21:26 -05:00
Accuracy table
| SENSOR | Temperature | Humidity |
|:------:|:-----------:|:--------:|
| SHT30 | ~0.3<EFBFBD> | 2.0% |
| SHT31 | ~0.3<EFBFBD> | 1.5% |
| SHT35 | ~0.2<EFBFBD> | 1.5% |
| SHT85 | ~0.2<EFBFBD> | 1.5% |
2021-05-26 06:06:51 -04:00
Need to investigate if the interface is identical?
2021-12-28 08:21:26 -05:00
If so the libraries might be merged.
2021-05-26 06:06:51 -04:00
2021-08-24 12:45:23 -04:00
An elaborated library for the SHT31 sensor can be found here
https://github.com/hawesg/SHT31D_Particle_Photon_ClosedCube
2021-05-26 06:06:51 -04:00
## Interface
#### Base interface
2021-08-24 13:59:51 -04:00
- **SHT()** constructor of the base class. **getType()** will return 0.
- **SHT30()** constructor.
- **SHT31()** constructor.
- **SHT35()** constructor.
2021-08-24 12:45:23 -04:00
- **SHT85()** constructor.
2021-08-24 13:59:51 -04:00
- **uint8_t getType()** returns numeric part of sensor type.
2022-01-17 15:15:55 -05:00
- **bool begin(uint8_t address, uint8_t dataPin, uint8_t clockPin)** begin function for ESP8266 & ESP32; **WARNING: not verified yet**
2021-05-26 06:06:51 -04:00
returns false if device address is incorrect or device cannot be reset.
2022-01-17 15:15:55 -05:00
- **bool begin(uint8_t dataPin, uint8_t clockPin)** same as above.
Uses SHT_DEFAULT_ADDRESS as address.
- **bool begin(uint8_t address, TwoWire \*wire = &Wire)** for platforms with multiple I2C buses. Default Wire as I2C bus.
- **bool begin(TwoWire \*wire = &Wire)** same as above.
Uses SHT_DEFAULT_ADDRESS as address.
2021-08-24 12:45:23 -04:00
- **bool read(bool fast = true)** blocks 4 (fast) or 15 (slow) milliseconds + actual read + math.
2021-05-26 06:06:51 -04:00
Does read both the temperature and humidity.
2021-08-24 12:45:23 -04:00
- **bool isConnected()** check sensor is reachable over I2C. Returns false if not connected.
- **uint16_t readStatus()** details see datasheet and **Status fields** below.
2021-05-26 06:06:51 -04:00
- **uint32_t lastRead()** in milliSeconds since start of program.
2021-08-24 12:45:23 -04:00
- **bool reset(bool hard = false)** resets the sensor, soft reset by default. Returns false if fails.
2021-08-24 13:59:51 -04:00
- **float getHumidity()** computes the relative humidity in % based on the latest raw reading, and returns it.
- **float getTemperature()** computes the temperature in <20>C based on the latest raw reading, and returns it.
- **float getFahrenheit()** computes the temperature in <20>F based on the latest raw reading, and returns it.
2021-08-24 12:45:23 -04:00
- **uint16_t getRawHumidity()** returns the raw two-byte representation of humidity directly from the sensor.
- **uint16_t getRawTemperature()** returns the raw two-byte representation of temperature directly from the sensor.
2021-08-07 06:34:52 -04:00
2021-12-28 08:21:26 -05:00
Note that the temperature and humidity values are recalculated on every call to getHumidity() and getTemperature().
If you're worried about the extra cycles, you should make sure to cache these values or only request them after
you've performed a new reading.
2021-05-26 06:06:51 -04:00
#### Error interface
2021-08-24 13:59:51 -04:00
- **int getError()** returns last set error flag and clear it.
2021-08-07 06:34:52 -04:00
Be sure to clear the error flag by calling **getError()** before calling any command as the error flag could be from a previous command.
2021-05-26 06:06:51 -04:00
2021-12-28 08:21:26 -05:00
| Error | Symbolic | Description |
2021-08-24 12:45:23 -04:00
|:-----:|:--------------------------|:----------------------------|
| 0x00 | SHT_OK | no error |
| 0x81 | SHT_ERR_WRITECMD | I2C write failed |
| 0x82 | SHT_ERR_READBYTES | I2C read failed |
| 0x83 | SHT_ERR_HEATER_OFF | Could not switch off heater |
| 0x84 | SHT_ERR_NOT_CONNECT | Could not connect |
| 0x85 | SHT_ERR_CRC_TEMP | CRC error in temperature |
| 0x86 | SHT_ERR_CRC_HUM | CRC error in humidity |
2021-12-28 08:21:26 -05:00
| 0x87 | SHT_ERR_CRC_STATUS | CRC error in status field |
2021-08-24 12:45:23 -04:00
| 0x88 | SHT_ERR_HEATER_COOLDOWN | Heater need to cool down |
2021-08-24 13:59:51 -04:00
| 0x89 | SHT_ERR_HEATER_ON | Could not switch on heater |
2021-05-26 06:06:51 -04:00
#### Heater interface
2021-08-24 12:45:23 -04:00
**WARNING:** Do not use heater for long periods.
Use the heater for max **180** seconds, and let it cool down **180** seconds = 3 minutes.
Version 0.3.3 and up guards the cool down time by preventing switching the heater on
within **180** seconds of the last switch off. Note: this guarding is not reboot persistent.
2021-05-26 06:06:51 -04:00
2021-08-24 12:45:23 -04:00
**WARNING:** The user is responsible to switch the heater off manually!
2021-05-26 06:06:51 -04:00
The class does **NOT** do this automatically.
2021-08-24 12:45:23 -04:00
Switch off the heater by directly calling **heatOff()** or indirectly by calling **isHeaterOn()**.
2021-05-26 06:06:51 -04:00
2021-08-24 12:45:23 -04:00
- **void setHeatTimeout(uint8_t seconds)** Set the time out of the heat cycle.
2021-05-26 06:06:51 -04:00
This value is truncated to max 180 seconds.
2021-08-24 12:45:23 -04:00
- **uint8_t getHeatTimeout
- **bool heatOn()** switches heat cycle on if not already on.
Returns false if fails, setting error to **SHT_ERR_HEATER_COOLDOWN**
or to **SHT_ERR_HEATER_ON**.
- **bool heatOff()** switches heat cycle off.
Returns false if fails, setting error to **SHT_ERR_HEATER_OFF**.
- **bool isHeaterOn()** is the sensor still in heating cycle? replaces **heatUp()**.
Will switch the heater off if max heating time has passed.
2021-05-26 06:06:51 -04:00
#### Async interface
See async example for usage
2021-08-24 13:59:51 -04:00
- **bool requestData()** requests a new measurement. Returns false if the request fails.
2021-08-24 12:45:23 -04:00
- **bool dataReady()** checks if enough time has passed to read the data. (15 milliseconds)
- **bool readData(bool fast = true)** fast = true skips the CRC check.
Returns false if reading fails or in case of a CRC failure.
2021-05-26 06:06:51 -04:00
## Status fields
2021-08-24 12:45:23 -04:00
| BIT | Description | value | notes |
|:-----|:---------------------------|:--------|:------|
| 15 | Alert pending status | 0 | no pending alerts
| | | 1 | at least one pending alert - default
| 14 | Reserved | 0 |
| 13 | Heater status | 0 | Heater OFF - default
| | | 1 | Heater ON
| 12 | Reserved | 0 |
| 11 | Humidity tracking alert | 0 | no alert - default
| | | 1 | alert
| 10 | Temperature tracking alert | 0 | no alert - default
| | | 1 | alert
| 9-5 | Reserved | 00000 |
| 4 | System reset detected | 0 | no reset since last <20>clear status register<65> command
| | | 1 | reset detected (hard or soft reset command or supply fail) - default
| 3-2 | Reserved | 00 |
| 1 | Command status | 0 | last command executed successfully
| | | 1 | last command not processed. Invalid or failed checksum
| 0 | Write data checksum status | 0 | checksum of last write correct
| | | 1 | checksum of last write transfer failed
2021-05-26 06:06:51 -04:00
2021-12-28 08:21:26 -05:00
## Operation
See examples.
2021-05-26 06:06:51 -04:00
## Future
2022-01-17 15:15:55 -05:00
#### should
- testing
- verify working with ESP32
- software I2C experiments
2021-12-28 08:21:26 -05:00
- improve error handling / status. (all code paths)
2022-01-17 15:15:55 -05:00
- add offsets for temperature and humidity.
- like other sensors
#### could
2021-05-26 06:06:51 -04:00
- investigate command ART (auto sampling at 4 Hz)
- investigate command BREAK (stop auto sampling)
2022-01-17 15:15:55 -05:00
- merge with other SHT sensors if possible
#### won't
- create a SHT85 simulator
- I2C slave sketch with e.g. a DHT22 sensor/
- not within this library.
2021-05-26 06:06:51 -04:00