mirror of
https://github.com/RobTillaart/Arduino.git
synced 2024-10-03 18:09:02 -04:00
146 lines
6.0 KiB
Markdown
146 lines
6.0 KiB
Markdown
|
|
[](https://github.com/marketplace/actions/arduino_ci)
|
|
[](https://github.com/RobTillaart/AM2315/actions/workflows/arduino-lint.yml)
|
|
[](https://github.com/RobTillaart/AM2315/actions/workflows/jsoncheck.yml)
|
|
[](https://github.com/RobTillaart/AM2315/blob/master/LICENSE)
|
|
[](https://github.com/RobTillaart/AM2315/releases)
|
|
|
|
|
|
# AM2315
|
|
|
|
Arduino library for I2C AM2315 temperature and humidity sensor.
|
|
|
|
The AM2315 can also be read with the https://github.com/RobTillaart/AM232X library as it uses the same protocol. The AM232X library allows to read some internal registers.
|
|
|
|
|
|
## Description
|
|
|
|
The library must be initiated by calling the **begin()** function,
|
|
optionally **begin(dataPin, clockPin)** for **ESP32** and similar platforms.
|
|
|
|
Thereafter one has to call the **read()** function to do the actual reading,
|
|
and with **getTemperature()** and **getHumidity()** to get the read values.
|
|
Calling these latter again will return the same values until a new **read()** is called.
|
|
|
|
The I2C address is 0x5C and is hardcoded in the device.
|
|
If you need multiple AM2315 devices use a I2C multiplexer e.g. https://github.com/RobTillaart/TCA9548
|
|
|
|
|
|
### I2C clock speed
|
|
|
|
The datasheet states the AM2315 should be used on 100 KHz I2C only.
|
|
When overclocking I got good readings up to 190 KHz in a test with
|
|
- Arduino UNO
|
|
- very short wires (< 1 meter)
|
|
- not using pull ups.
|
|
- version 0.1.1 of this library
|
|
|
|
|
|
| I2C clock | timing us | Notes |
|
|
|:---------:|:---------:|:----------------------|
|
|
| 50 KHz | 4570 | under-clocking works (e.g. long wires)
|
|
| 100 KHz | 3276 | specs default, robust
|
|
| 150 KHz | 2836 |
|
|
| 160 KHz | 2792 |
|
|
| 170 KHz | 2750 | 0.5 ms off, interesting for performance.
|
|
| 180 KHz | 2700 | near critical. DO NOT USE.
|
|
| 190 KHz | 2672 | near critical. DO NOT USE.
|
|
| 200 KHz | crash | sensor needs a power cycle reboot. DO NOT USE.
|
|
|
|
|
|
If robustness is mandatory stick to the default of 100 KHz.
|
|
If performance is mandatory do not go beyond 170 KHz.
|
|
|
|
|
|
### Wake up
|
|
|
|
As the sensor goes to sleep after 3 seconds after last read, it needs to be woken up.
|
|
This is hard coded in the **readSensor()** function.
|
|
There is also a **wakeUp()** function so the wake up can be done some time before the
|
|
read is actual needed.
|
|
|
|
|
|
## Interface
|
|
|
|
|
|
### Constructor
|
|
|
|
- **AM2315(TwoWire \*wire = &Wire)** constructor, default using Wire (I2C bus), optionally set to Wire0 .. WireN.
|
|
- **bool begin(uint8_t dataPin, uint8_t clockPin)** begin for ESP32 et al, to set I2C bus pins, returns true if device is connected.
|
|
- **bool begin()** initializer for non ESP32. Returns true if connected.
|
|
- **bool isConnected(uint16_t timeout = 3000)** returns true if the address of the AM2315 can be seen on the I2C bus.
|
|
As the device can be in sleep modus it will retry for the defined timeout (in micros) with a minimum of 1 try.
|
|
minimum = 800 us and maximum = 3000 us according to datasheet.
|
|
|
|
|
|
### Core
|
|
|
|
- **int8_t read()** read the sensor and store the values internally.
|
|
It returns the status of the read which should be **AM2315_OK** == 0.
|
|
- **float getHumidity()** returns last Humidity read + optional offset, or **AM2315_INVALID_VALUE** == -999 in case of error. This error can be suppressed, see below.
|
|
- **float getTemperature()** returns last Temperature read + optional offset, or **AM2315_INVALID_VALUE** == -999 in case of error. This error can be suppressed, see below.
|
|
- **uint32_t lastRead()** returns the timestamp in milliseconds since startup of the last successful read.
|
|
|
|
|
|
### Offset
|
|
|
|
- **void setHumOffset(float offset = 0)** set an offset for humidity to calibrate (1st order) the sensor.
|
|
Default offset = 0, so no parameter will reset the offset.
|
|
- **float getHumOffset()** return current humidity offset, default 0.
|
|
- **void setTempOffset(float offset = 0)** set an offset for temperature to calibrate (1st order) the sensor.
|
|
Default offset = 0, so no parameter will reset the offset.
|
|
- **float getTempOffset()** return current temperature offset, default 0.
|
|
|
|
|
|
### Control
|
|
|
|
Functions to adjust the communication with the sensor.
|
|
|
|
- **void setWaitForReading(bool b )** flag to enforce a blocking wait (up to 2 seconds) when **read()** is called.
|
|
- **bool getWaitForReading()** returns the above setting.
|
|
- **void setSuppressError(bool b)** suppress error values of **AM2315_INVALID_VALUE** == -999 => you need to check the return value of read() instead.
|
|
This can be used to keep spikes out of your graphs / logs.
|
|
- **bool getSuppressError()** returns the above setting.
|
|
|
|
|
|
### Misc
|
|
|
|
- **bool wakeUp()** function that will try for 3 milliseconds to wake up the sensor.
|
|
This can be done before an actual read to minimize the **read()** call.
|
|
|
|
|
|
### error codes
|
|
|
|
|
|
| name | value | notes |
|
|
|:----------------------------------|------:|:------------|
|
|
| AM2315_OK | 0 |
|
|
| AM2315_ERROR_CHECKSUM | -10 | I2C problem.
|
|
| AM2315_ERROR_CONNECT | -11 | I2C problem.
|
|
| AM2315_MISSING_BYTES | -12 | I2C problem.
|
|
| AM2315_WAITING_FOR_READ | -50 | called **read()** too fast, within 2 seconds.
|
|
| AM2315_HUMIDITY_OUT_OF_RANGE | -100 | not used by default.
|
|
| AM2315_TEMPERATURE_OUT_OF_RANGE | -101 | not used by default.
|
|
| AM2315_INVALID_VALUE | -999 | can be suppressed.
|
|
|
|
|
|
## Operation
|
|
|
|
See examples
|
|
|
|
|
|
## Future
|
|
|
|
- documentation
|
|
- test
|
|
- update unit test
|
|
- add examples
|
|
- merge with the AM232X library in a far future.
|
|
|
|
**wont**
|
|
- add calls for meta information (no description yet)
|
|
- 0x07 status register
|
|
- 0x08-0x0B user register HIGH LOW HIGH2 LOW2
|
|
(use AM232x library to access those)
|
|
|