alex/GY-63_MS5611
1
0
Fork 0
mirror of https://github.com/RobTillaart/Arduino.git synced 2024-09-20 00:55:58 -04:00
Code Issues Actions Packages Projects Releases Wiki Activity
73cbab23d9
GY-63_MS5611/libraries/SHT31_SW/README.md

197 lines
8.7 KiB
Markdown
Raw Normal View History

0.1.0 SHT31_SW
2023-03-24 07:12:37 -04:00
[![Arduino CI](https://github.com/robtillaart/SHT31_SW/workflows/Arduino%20CI/badge.svg)](https://github.com/marketplace/actions/arduino_ci)
[![JSON check](https://github.com/RobTillaart/SHT31_SW/actions/workflows/jsoncheck.yml/badge.svg)](https://github.com/RobTillaart/SHT31_SW/actions/workflows/jsoncheck.yml)
[![Arduino-lint](https://github.com/RobTillaart/SHT31_SW/actions/workflows/arduino-lint.yml/badge.svg)](https://github.com/RobTillaart/SHT31_SW/actions/workflows/arduino-lint.yml)
[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](https://github.com/RobTillaart/SHT31_SW/blob/master/LICENSE)
[![GitHub release](https://img.shields.io/github/release/RobTillaart/SHT31_SW.svg?maxAge=3600)](https://github.com/RobTillaart/SHT31_SW/releases)
# SHT31_SW
Arduino library for the SHT31 temperature and humidity sensor - using **SoftWire**.
## Description
0.1.2 SHT31_SW
2023-07-23 08:02:17 -04:00
This **experimental** library features the class SHT31_SW derived from - https://github.com/RobTillaart/SHT31.
0.1.0 SHT31_SW
2023-03-24 07:12:37 -04:00
It has the same interface as the SHT31 class so please use that documentation
as it will be the "leading class".
0.1.2 SHT31_SW
2023-07-23 08:02:17 -04:00
The main difference is that the SHT31_SW class uses the **SoftWire** library
for communication instead of the **TwoWire** based **Wire** class.
0.1.1 SHT31_SW
2023-05-12 11:01:00 -04:00
See SHT31 PR #35.
0.1.0 SHT31_SW
2023-03-24 07:12:37 -04:00
**SoftWire** is a software I2C bus library to be able to select other pins
than the default (AVR) hardware I2C pins (SDA and SCL).
An important reason to use this version is when you want more than two
devices on one Arduino.
0.1.2 SHT31_SW
2023-07-23 08:02:17 -04:00
#### SoftWire vs SoftwareWire
0.1.0 SHT31_SW
2023-03-24 07:12:37 -04:00
0.1.2 SHT31_SW
2023-07-23 08:02:17 -04:00
The **SoftWire** library is portable, however it could not read (on AVR)
the SHT85 sensor which is command compatible with the SHT3x.
The cause is not found yet.
Therefore a separate repo is created based upon the AVR specific **SoftwareWire**
see links below.
If you know a solution to get softWire working on AVR, please let me know.
0.1.1 SHT31_SW
2023-05-12 11:01:00 -04:00
The **SoftwareWire** library is an AVR specific and worked for the SHT85.
See https://github.com/RobTillaart/SHT31_SW/issues/5
0.1.0 SHT31_SW
2023-03-24 07:12:37 -04:00
0.1.2 SHT31_SW
2023-07-23 08:02:17 -04:00
#### SHT3x SHT85 sensors
0.1.0 SHT31_SW
2023-03-24 07:12:37 -04:00
0.1.2 SHT31_SW
2023-07-23 08:02:17 -04:00
The SHT3x family of sensors should work up to 1 MHz I2C although not tested above 400 MHz.
0.1.0 SHT31_SW
2023-03-24 07:12:37 -04:00
This library should also work for SHT30/35/85 but these are not tested yet.
0.1.2 SHT31_SW
2023-07-23 08:02:17 -04:00
Test on UNO
0.1.0 SHT31_SW
2023-03-24 07:12:37 -04:00
0.1.2 SHT31_SW
2023-07-23 08:02:17 -04:00
| SENSOR | Temperature | Humidity | works |
0.1.1 SHT31_SW
2023-05-12 11:01:00 -04:00
|:--------:|:-------------:|:----------:|:---------------|
| SHT30 | ~0.3 | 2.0 | (not tested) |
0.1.2 SHT31_SW
2023-07-23 08:02:17 -04:00
| SHT31 | ~0.3 | 1.5 | yes |
0.1.1 SHT31_SW
2023-05-12 11:01:00 -04:00
| SHT35 | ~0.2 | 1.5 | (not tested) |
0.1.2 SHT31_SW
2023-07-23 08:02:17 -04:00
| SHT85 | ~0.2 | 1.5 | no | See SHT31_SWW
0.1.0 SHT31_SW
2023-03-24 07:12:37 -04:00
#### Links
These libraries need to be installed to get SHT31_SW working:
0.1.1 SHT31_SW
2023-05-12 11:01:00 -04:00
- https://github.com/RobTillaart/SHT31
0.1.0 SHT31_SW
2023-03-24 07:12:37 -04:00
- https://github.com/stevemarple/AsyncDelay
0.1.2 SHT31_SW
2023-07-23 08:02:17 -04:00
- https://github.com/stevemarple/SoftWire
Related
0.1.1 SHT31_SW
2023-05-12 11:01:00 -04:00
- https://github.com/Testato/SoftwareWire // AVR only
0.1.0 SHT31_SW
2023-03-24 07:12:37 -04:00
## Interface
```cpp
#include "SHT31_SW.h"
```
Note: The interface is mostly inherited from SHT31 but presented here for completeness.
#### Base interface
- **SHT31_SW()** constructor.
- **bool begin(uint8_t address, SoftWire \*wire = &Wire)** for platforms with multiple I2C buses.
- **bool begin(SoftWire \*wire = &Wire)** same as above. With default SHT_DEFAULT_ADDRESS.
- **bool read(bool fast = true)** blocks 4 (fast) or 15 (slow) milliseconds + actual read + math.
Does read both the temperature and humidity.
- **bool isConnected()** check sensor is reachable over I2C. Returns false if not connected.
- **uint16_t readStatus()** details see datasheet and **Status fields** below.
- **uint32_t lastRead()** in milliSeconds since start of program.
- **bool reset(bool hard = false)** resets the sensor, soft reset by default. Returns false if it fails.
- **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.
- **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.
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.
#### Error interface
- **int getError()** returns last set error flag and clear it.
0.1.2 SHT31_SW
2023-07-23 08:02:17 -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.
0.1.0 SHT31_SW
2023-03-24 07:12:37 -04:00
| Error | Symbolic | Description |
|:-------:|:----------------------------|:------------------------------|
| 0x00 | SHT31_OK | no error |
| 0x81 | SHT31_ERR_WRITECMD | I2C write failed |
| 0x82 | SHT31_ERR_READBYTES | I2C read failed |
| 0x83 | SHT31_ERR_HEATER_OFF | Could not switch off heater |
| 0x84 | SHT31_ERR_NOT_CONNECT | Could not connect |
| 0x85 | SHT31_ERR_CRC_TEMP | CRC error in temperature |
| 0x86 | SHT31_ERR_CRC_HUM | CRC error in humidity |
| 0x87 | SHT31_ERR_CRC_STATUS | CRC error in status field |
| 0x88 | SHT31_ERR_HEATER_COOLDOWN | Heater need to cool down |
| 0x88 | SHT31_ERR_HEATER_ON | Could not switch on heater |
#### Heater interface
**WARNING:** Do not use heater for long periods.
Use the heater for max **180** seconds, and let it cool down **180** seconds = 3 minutes.
SHT31 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.
**WARNING:** The user is responsible to switch the heater off manually!
The class does **NOT** do this automatically.
Switch off the heater by directly calling **heatOff()** or indirectly by calling **isHeaterOn()**.
- **void setHeatTimeout(uint8_t seconds)** Set the time out of the heat cycle.
This value is truncated to max 180 seconds.
- **uint8_t getHeatTimeout
- **bool heatOn()** switches heat cycle on if not already on.
Returns false if fails, setting error to **SHT31_ERR_HEATER_COOLDOWN**
or to **SHT31_ERR_HEATER_ON**.
- **bool heatOff()** switches heat cycle off.
Returns false if fails, setting error to **SHT31_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.
- **bool heatUp()** will be obsolete in the future. replaced by **isHeaterOn()**
#### Async interface
See async example for usage
- **bool requestData()** requests a new measurement. Returns false if this fails.
- **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.
## Status fields
| 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
## Future
0.1.1 SHT31_SW
2023-05-12 11:01:00 -04:00
#### Must
0.1.2 SHT31_SW
2023-07-23 08:02:17 -04:00
- keep in sync with (leading) SHT31 and SHT31_SWW library.
0.1.1 SHT31_SW
2023-05-12 11:01:00 -04:00
#### Should
0.1.2 SHT31_SW
2023-07-23 08:02:17 -04:00
- remove script for atomic if not needed any more.
- investigate why SHT85 does not work with SoftWire.
0.1.1 SHT31_SW
2023-05-12 11:01:00 -04:00
#### Could
0.1.0 SHT31_SW
2023-03-24 07:12:37 -04:00
0.1.1 SHT31_SW
2023-05-12 11:01:00 -04:00
#### Wont
0.1.0 SHT31_SW
2023-03-24 07:12:37 -04:00
Reference in New Issue Copy Permalink