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

383 lines
14 KiB
Markdown
Raw Normal View History

2021-01-29 06:31:58 -05:00
[![Arduino CI](https://github.com/RobTillaart/ADS1X15/workflows/Arduino%20CI/badge.svg)](https://github.com/marketplace/actions/arduino_ci)
2021-10-08 03:28:06 -04:00
[![Arduino-lint](https://github.com/RobTillaart/ADS1X15/actions/workflows/arduino-lint.yml/badge.svg)](https://github.com/RobTillaart/ADS1X15/actions/workflows/arduino-lint.yml)
[![JSON check](https://github.com/RobTillaart/ADS1X15/actions/workflows/jsoncheck.yml/badge.svg)](https://github.com/RobTillaart/ADS1X15/actions/workflows/jsoncheck.yml)
2021-01-29 06:31:58 -05:00
[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](https://github.com/RobTillaart/ADS1X15/blob/master/LICENSE)
[![GitHub release](https://img.shields.io/github/release/RobTillaart/ADS1X15.svg?maxAge=3600)](https://github.com/RobTillaart/ADS1X15/releases)
2022-03-15 10:40:30 -04:00
2021-01-29 06:31:58 -05:00
# ADS1X15
2021-12-11 10:46:06 -05:00
Arduino library for I2C ADC ADS1015, ADS1115, and similar.
2021-01-29 06:31:58 -05:00
2022-01-31 13:03:19 -05:00
For using I2C ADC with Raspberry pi or other SBC with Linux OS, you can check similar library [here](https://github.com/chandrawi/ADS1x15-ADC).
2021-07-14 04:59:33 -04:00
2022-03-15 10:40:30 -04:00
2021-01-29 06:31:58 -05:00
## Description
This library should work for the devices mentioned below,
although not all sensors support all functionality.
2021-07-14 04:59:33 -04:00
| Device | Channels | Resolution | Max sps | Comparator | ProgGainAMP | Notes |
|:-------:|:--------:|:----------:|:-------:|:----------:|:-----------:|:-------|
| ADS1013 | 1 | 12 | 3300 | N | N | |
| ADS1014 | 1 | 12 | 3300 | Y | Y | |
| ADS1015 | 4 | 12 | 3300 | Y | Y | |
| ADS1113 | 1 | 16 | 860 | N | N | |
| ADS1114 | 1 | 16 | 860 | Y | Y | |
| ADS1115 | 4 | 16 | 860 | Y | Y | Tested |
2021-01-29 06:31:58 -05:00
As the 1015 and the 1115 are both 4 channels these are the most
interesting from functionality point of view as these can also do
differential measurement.
2021-12-11 10:46:06 -05:00
The address of the ADS1113/4/5 is determined by to which pin the **ADDR**
2021-01-29 06:31:58 -05:00
is connected to:
2021-07-14 04:59:33 -04:00
| ADDR pin connected to | Address | Notes |
|:---------------------:|:-------:|:-------:|
| GND | 0x48 | default |
| VDD | 0x49 | |
| SDA | 0x4A | |
| SCL | 0x4B | |
2021-01-29 06:31:58 -05:00
2022-01-31 13:03:19 -05:00
## Interface
### Initializing
To initialize the library you must call constructor as described below.
2021-12-11 10:46:06 -05:00
- **ADS1x15()** base constructor, should not be used.
2021-04-07 07:31:22 -04:00
- **ADS1013(address, TwoWire \*wire = &Wire)** Constructor with device address,
and optional the Wire interface as parameter.
- **ADS1014(address, TwoWire \*wire = &Wire)** Constructor with device address,
and optional the Wire interface as parameter.
- **ADS1015(address, TwoWire \*wire = &Wire)** Constructor with device address,
and optional the Wire interface as parameter.
- **ADS1113(address, TwoWire \*wire = &Wire)** Constructor with device address,
and optional the Wire interface as parameter.
- **ADS1114(address, TwoWire \*wire = &Wire)** Constructor with device address,
and optional the Wire interface as parameter.
- **ADS1115(address, TwoWire \*wire = &Wire)** Constructor with device address,
and optional the Wire interface as parameter.
2021-01-29 06:31:58 -05:00
2022-01-21 13:23:09 -05:00
After construction the **ADS.begin()** need to be called. This will return false
if an invalid address is used.
The function **bool isConnected()** can be used to verify the reading of the ADS.
The function **void reset()** is sets the parameters to their initial value as
in the constructor.
2022-01-31 13:03:19 -05:00
For example.
```cpp
#include "ADS1X15.h"
// initialize ADS1115 on I2C bus 1 with default address 0x48
ADS1115 ADS(0x48);
void begin() {
if (!ADS.isConnected()) {
// error ADS1115 not connected
}
}
```
2022-01-21 13:23:09 -05:00
2022-01-31 13:03:19 -05:00
### I2C clock speed
2022-01-21 13:23:09 -05:00
The function **void setWireClock(uint32_t speed = 100000)** is used to set the clock speed
in Hz of the used I2C interface. typical value is 100 KHz.
2021-04-25 13:56:44 -04:00
2021-08-10 16:16:36 -04:00
The function **uint32_t getWireClock()** is a prototype.
It returns the value set by setWireClock().
This is not necessary the actual value.
When no value is set **getWireClock()** returns 0.
Need to implement a read / calculate from low level I2C code (e.g. TWBR on AVR),
better the Arduino Wire lib should support this call (ESP32 does).
2021-04-25 13:56:44 -04:00
2022-01-21 13:23:09 -05:00
See - https://github.com/arduino/Arduino/issues/11457
Question: should this functionality be in this library?
2021-01-29 06:31:58 -05:00
2022-01-31 13:03:19 -05:00
### Programmable Gain
2021-01-29 06:31:58 -05:00
2021-10-08 03:28:06 -04:00
- **void setGain(uint8_t gain)** set the gain value, indicating the maxVoltage that can be measured
2022-01-31 13:03:19 -05:00
Adjusting the gain allowing to make more precise measurements.
2021-08-10 16:16:36 -04:00
Note: the gain is not set in the device until an explicit read/request of the ADC (any read call will do).
2021-01-29 06:31:58 -05:00
See table below.
2021-10-08 03:28:06 -04:00
- **uint8_t getGain()** returns the gain value (index).
2021-01-29 06:31:58 -05:00
2021-07-14 04:59:33 -04:00
| PGA value | Max Voltage | Notes |
|:---------:|:-----------:|:-------:|
| 0 | ±6.144V | default |
| 1 | ±4.096V | |
| 2 | ±2.048V | |
| 4 | ±1.024V | |
| 8 | ±0.512V | |
| 16 | ±0.256V | |
2021-01-29 06:31:58 -05:00
2021-08-10 16:16:36 -04:00
- **float getMaxVoltage()** returns the max voltage with the current gain.
- **float toVoltage(int16_t raw = 1)** converts a raw measurement to a voltage.
2021-01-29 06:31:58 -05:00
Can be used for normal and differential measurements.
The default value of 1 returns the conversion factor for any raw number.
The voltage factor can also be used to set HIGH and LOW threshold registers
with a voltage in the comparator mode.
2022-01-31 13:03:19 -05:00
Check the [examples](https://github.com/RobTillaart/ADS1X15/blob/master/examples/ADS_read_comparator_1/ADS_read_comparator_1.ino).
2021-01-29 06:31:58 -05:00
```cpp
float f = ADS.toVoltage();
ADS.setComparatorThresholdLow( 3.0 / f );
ADS.setComparatorThresholdLow( 4.3 / f );
```
2021-10-08 03:28:06 -04:00
2022-01-31 13:03:19 -05:00
### Operational mode
2021-01-29 06:31:58 -05:00
The ADS sensor can operate in single shot or continuous mode.
2022-01-31 13:03:19 -05:00
Depending on how often conversions needed you can tune the mode.
2021-08-10 16:16:36 -04:00
- **void setMode(uint8_t mode)** 0 = CONTINUOUS, 1 = SINGLE (default)
Note: the mode is not set in the device until an explicit read/request of the ADC (any read call will do).
- **uint8_t getMode()** returns current mode 0 or 1, or ADS1X15_INVALID_MODE = 0xFE.
2021-01-29 06:31:58 -05:00
2022-01-31 13:03:19 -05:00
### Data rate
2021-01-29 06:31:58 -05:00
2021-08-10 16:16:36 -04:00
- **void setDataRate(uint8_t dataRate)** Data rate depends on type of device.
2021-01-29 06:31:58 -05:00
For all devices the index 0..7 can be used, see table below.
Values above 7 ==> will be set to the default 4.
2021-08-10 16:16:36 -04:00
Note: the data rate is not set in the device until an explicit read/request of the ADC (any read call will do).
- **uint8_t getDataRate()** returns the current data rate (index).
2021-01-29 06:31:58 -05:00
The library has no means to convert this index to the actual numbers
as that would take 32 bytes.
2022-01-31 13:03:19 -05:00
Data rate in samples per second, based on datasheet is described on table below.
2021-01-29 06:31:58 -05:00
2021-07-14 04:59:33 -04:00
| data rate | ADS101x | ADS 111x | Notes |
|:---------:|--------:|---------:|:-------:|
| 0 | 128 | 8 | slowest |
| 1 | 250 | 16 | |
| 2 | 490 | 32 | |
| 3 | 920 | 64 | |
| 4 | 1600 | 128 | default |
| 5 | 2400 | 250 | |
| 6 | 3300 | 475 | |
| 7 | 3300 | 860 | fastest |
2021-01-29 06:31:58 -05:00
2022-01-31 13:03:19 -05:00
### ReadADC Single mode
2021-01-29 06:31:58 -05:00
2022-01-31 13:03:19 -05:00
Reading the ADC is very straightforward, the **readADC()** function handles all in one call.
Under the hood it uses the asynchronous calls.
2022-03-15 10:40:30 -04:00
- **int16_t readADC(uint8_t pin = 0)** normal ADC functionality, pin = 0..3.
2021-07-14 04:59:33 -04:00
If the pin number is out of range, this function will return 0.
2022-03-15 10:40:30 -04:00
Default pin = 0 as this is convenient for 1 channel devices.
2021-01-29 06:31:58 -05:00
2022-01-31 13:03:19 -05:00
```cpp
2022-03-15 10:40:30 -04:00
// read ADC in pin 2
ADS.readADC(2);
// read ADC in pin 0 - two ways
ADS.readADC();
2022-01-31 13:03:19 -05:00
ADS.readADC(0);
```
See [examples](https://github.com/RobTillaart/ADS1X15/blob/master/examples/ADS_minimum/ADS_minimum.ino).
To read the ADC in an asynchronous way (e.g. to minimize blocking) you need call three functions:
2022-03-15 10:40:30 -04:00
- **void requestADC(uint8_t pin = 0)** Start the conversion. pin = 0..3.
Default pin = 0 as this is convenient for 1 channel devices.
2021-10-08 03:28:06 -04:00
- **bool isBusy()** Is the conversion not ready yet? Works only in SINGLE mode!
- **bool isReady()** Is the conversion ready? Works only in SINGLE mode! (= wrapper around **isBusy()** )
2021-08-10 16:16:36 -04:00
- **int16_t getValue()** Read the result of the conversion.
2021-01-29 06:31:58 -05:00
in terms of code
```cpp
void setup()
{
// other setup things here
2021-10-08 03:28:06 -04:00
ADS.setMode(1); // SINGLE SHOT MODE
2021-01-29 06:31:58 -05:00
ADS.requestADC(pin);
}
void loop()
{
if (ADS.isReady())
{
2021-12-11 10:46:06 -05:00
value = ADS.getValue();
2021-01-29 06:31:58 -05:00
ADS.requestADC(pin); // request new conversion
}
// do other things here
}
```
2022-01-31 13:03:19 -05:00
See [examples](https://github.com/RobTillaart/ADS1X15/blob/master/examples/ADS_read_async/ADS_read_async.ino).
2021-01-29 06:31:58 -05:00
2021-10-08 03:28:06 -04:00
2021-01-29 06:31:58 -05:00
## ReadADC Differential
For reading the ADC in a differential way there are 4 calls possible.
2021-12-11 10:46:06 -05:00
2021-08-10 16:16:36 -04:00
- **int16_t readADC_Differential_0_1()** returns the difference between 2 ADC pins.
- **int16_t readADC_Differential_0_3()** ADS1x15 only
- **int16_t readADC_Differential_1_3()** ADS1x15 only
- **int16_t readADC_Differential_2_3()** ADS1x15 only
- **int16_t readADC_Differential_0_2()** ADS1x15 only - in software (no async equivalent)
- **int16_t readADC_Differential_1_2()** ADS1x15 only - in software (no async equivalent)
2021-01-29 06:31:58 -05:00
2022-01-31 13:03:19 -05:00
```cpp
// read differential ADC between pin 0 and 1
ADS.readADC_Differential_0_1(0);
```
2021-07-14 04:59:33 -04:00
The differential reading of the ADC can also be done with asynchronous calls.
2021-12-11 10:46:06 -05:00
2021-10-08 03:28:06 -04:00
- **void requestADC_Differential_0_1()** starts conversion for differential reading
- **void requestADC_Differential_0_3()** ADS1x15 only
- **void requestADC_Differential_1_3()** ADS1x15 only
- **void requestADC_Differential_2_3()** ADS1x15 only
2021-01-29 06:31:58 -05:00
2022-01-31 13:03:19 -05:00
After one of these calls you need to call
2021-08-10 16:16:36 -04:00
- **int16_t getValue()** Read the result of the last conversion.
2021-01-29 06:31:58 -05:00
2022-01-31 13:03:19 -05:00
See [examples](https://github.com/RobTillaart/ADS1X15/blob/master/examples/ADS_differential/ADS_differential.ino).
2021-10-08 03:28:06 -04:00
2021-01-29 06:31:58 -05:00
2022-01-31 13:03:19 -05:00
### ReadADC continuous mode
2021-01-29 06:31:58 -05:00
2022-01-31 13:03:19 -05:00
To use the continuous mode you need call three functions:
2021-08-10 16:16:36 -04:00
- **void setMode(0)** 0 = CONTINUOUS, 1 = SINGLE (default).
Note: the mode is not set in the device until an explicit read/request of the ADC (any read call will do).
- **int16_t readADC(uint8_t pin)** or **void requestADC(uint8_t pin)** to get the continuous mode started.
- **int16_t getValue()** to return the last value read by the device.
Note this can be a different pin, so be warned.
2021-01-29 06:31:58 -05:00
Calling this over and over again can give the same value multiple times.
2022-01-31 13:03:19 -05:00
```cpp
void setup() {
// configuration things here
ADS.setMode(ADS.MODE_CONTINUOUS);
ADS.requestADC(0); // request on pin 0
}
void loop() {
value = ADS.getValue()
sleep(1)
}
```
See [examples](https://github.com/RobTillaart/ADS1X15/blob/master/examples/ADS_continuous/ADS_continuous.ino)
.
2021-08-10 16:16:36 -04:00
By using **bool isBusy()** or **bool isReady()** one can wait until new data is available.
2021-10-17 06:48:59 -04:00
Note this only works in the SINGLE_SHOT modus.
2021-10-08 03:28:06 -04:00
2022-01-31 13:03:19 -05:00
In continuous mode, you can't use **isBusy()** or **isReady()** functions to wait until new data available.
Instead you can configure the threshold registers to allow the **ALERT/RDY** pin to trigger an interrupt signal when conversion data ready.
2021-01-29 06:31:58 -05:00
2021-04-25 13:56:44 -04:00
2022-01-31 13:03:19 -05:00
### Threshold registers
2021-01-29 06:31:58 -05:00
If the thresholdHigh is set to 0x0100 and the thresholdLow to 0x0000
the **ALERT/RDY** pin is triggered when a conversion is ready.
2021-12-11 10:46:06 -05:00
2021-08-10 16:16:36 -04:00
- **void setComparatorThresholdLow(int16_t lo)** writes value to device directly.
- **void setComparatorThresholdHigh(int16_t hi)** writes value to device directly.
- **int16_t getComparatorThresholdLow()** reads value from device.
- **int16_t getComparatorThresholdHigh()** reads value from device.
2021-01-29 06:31:58 -05:00
2022-01-31 13:03:19 -05:00
See [examples](https://github.com/RobTillaart/ADS1X15/blob/master/examples/ADS_read_RDY/ADS_read_RDY.ino).
2021-01-29 06:31:58 -05:00
2021-04-25 13:56:44 -04:00
2021-01-29 06:31:58 -05:00
## Comparator
2021-08-10 16:16:36 -04:00
Please read Page 15 of the datasheet as the behaviour of the
2021-01-29 06:31:58 -05:00
comparator is not trivial.
2022-01-31 13:03:19 -05:00
NOTE: all comparator settings are copied to the device only after calling
**readADC()** or **requestADC()** functions.
2021-08-10 16:16:36 -04:00
2021-04-25 13:56:44 -04:00
2022-01-31 13:03:19 -05:00
### Comparator Mode
2021-01-29 06:31:58 -05:00
When configured as a **TRADITIONAL** comparator, the **ALERT/RDY** pin asserts
(active low by default) when conversion data exceed the limit set in the
2021-07-14 04:59:33 -04:00
high threshold register. The comparator then de-asserts when the input
2021-01-29 06:31:58 -05:00
signal falls below the low threshold register value.
2021-08-10 16:16:36 -04:00
- **void setComparatorMode(uint8_t mode)** value 0 = TRADITIONAL 1 = WINDOW,
2021-10-08 03:28:06 -04:00
- **uint8_t getComparatorMode()** returns value set.
2021-08-10 16:16:36 -04:00
2021-01-29 06:31:58 -05:00
If the comparator **LATCH** is set, the **ALERT/RDY** pin asserts and it will be
reset after reading the sensor (conversion register) again.
*An SMB alert command (00011001) on the I2C bus will also reset the alert state.*
*Not implemented in the library (yet)*
In **WINDOW** comparator mode, the **ALERT/RDY** pin asserts if conversion data exceeds
the high threshold register or falls below the low threshold register.
In this mode the alert is held if the **LATCH** is set. This is similar as above.
2021-04-25 13:56:44 -04:00
2022-01-31 13:03:19 -05:00
### Polarity
2021-01-29 06:31:58 -05:00
Default state of the **ALERT/RDY** pin is **LOW**, can be to set **HIGH**.
2021-08-10 16:16:36 -04:00
- **void setComparatorPolarity(uint8_t pol)**
Flag is only explicitly set after a **readADC()** or a **requestADC()**
- **uint8_t getComparatorPolarity()** returns value set.
2021-04-25 13:56:44 -04:00
2022-01-31 13:03:19 -05:00
### Latch
2021-01-29 06:31:58 -05:00
Holds the **ALERT/RDY** to **HIGH** (or **LOW** depending on polarity) after triggered
even if actual value has been 'restored to normal' value.
2021-08-10 16:16:36 -04:00
- **void setComparatorLatch(uint8_t latch)** 0 = NO LATCH, not 0 = LATCH
- **uint8_t getComparatorLatch()** returns value set.
2021-04-25 13:56:44 -04:00
2022-01-31 13:03:19 -05:00
### QueConvert
2021-01-29 06:31:58 -05:00
Set the number of conversions before trigger activates.
2021-08-10 16:16:36 -04:00
The **void setComparatorQueConvert(uint8_t mode)** is used to set the number of
2021-01-29 06:31:58 -05:00
conversions that exceed the threshold before the **ALERT/RDY** pin is set **HIGH**.
A value of 3 (or above) effectively disables the comparator. See table below.
2021-08-10 16:16:36 -04:00
- **void setComparatorQueConvert(uint8_t mode)** See table below.
- **uint8_t getComparatorQueConvert()** returns value set.
2021-07-14 04:59:33 -04:00
| value | meaning | Notes |
|:-----:|:----------------------------------|:--------|
| 0 | trigger alert after 1 conversion | |
| 1 | trigger alert after 2 conversions | |
| 2 | trigger alert after 4 conversions | |
| 3 | Disable comparator | default |
2021-01-29 06:31:58 -05:00
2021-04-25 13:56:44 -04:00
2022-01-31 13:03:19 -05:00
### Threshold registers comparator mode
2021-01-29 06:31:58 -05:00
Depending on the comparator mode **TRADITIONAL** or **WINDOW** the thresholds registers
mean something different see - Comparator Mode above or datasheet.
2021-12-11 10:46:06 -05:00
2021-08-10 16:16:36 -04:00
- **void setComparatorThresholdLow(int16_t lo)** set the low threshold; take care the hi >= lo.
- **void setComparatorThresholdHigh(int16_t hi)** set the high threshold; take care the hi >= lo.
- **int16_t getComparatorThresholdLow()** reads value from device.
- **int16_t getComparatorThresholdHigh()** reads value from device.
2021-01-29 06:31:58 -05:00
## Future ideas & improvements
- Improve documentation
2021-08-10 16:16:36 -04:00
- More examples ?
2021-01-29 06:31:58 -05:00
- SMB alert command (00011001) on I2C bus?
2021-04-25 13:56:44 -04:00
2022-01-31 13:03:19 -05:00
## Examples
2022-01-21 13:23:09 -05:00
2022-01-31 13:03:19 -05:00
See [examples](https://github.com/RobTillaart/ADS1X15/tree/master/examples).