Skip to content

Commit

Permalink
update examples (#50)
Browse files Browse the repository at this point in the history
* update examples
  • Loading branch information
RobTillaart authored Mar 31, 2023
1 parent 8d76b90 commit 1d53197
Show file tree
Hide file tree
Showing 25 changed files with 251 additions and 60 deletions.
3 changes: 3 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,9 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/)
and this project adheres to [Semantic Versioning](http://semver.org/).


- update and add examples


## [0.3.9] - 2023-01-21
- update GitHub actions
- update license 2023
Expand Down
36 changes: 20 additions & 16 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -46,7 +46,11 @@ is connected to:

## Interface

### Initializing
```cpp
#include "ADS1X15.h"
```

#### Initializing

To initialize the library you must call constructor as described below.

Expand Down Expand Up @@ -87,7 +91,7 @@ void begin() {
```
### I2C clock speed
#### I2C clock speed
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.
Expand All @@ -104,7 +108,7 @@ See - https://github.com/arduino/Arduino/issues/11457
Question: should this functionality be in this library?
### Programmable Gain
#### Programmable Gain
- **void setGain(uint8_t gain)** set the gain value, indicating the maxVoltage that can be measured
Adjusting the gain allowing to make more precise measurements.
Expand Down Expand Up @@ -138,7 +142,7 @@ Check the [examples](https://github.com/RobTillaart/ADS1X15/blob/master/examples
```


### Operational mode
#### Operational mode

The ADS sensor can operate in single shot or continuous mode.
Depending on how often conversions needed you can tune the mode.
Expand All @@ -147,7 +151,7 @@ Note: the mode is not set in the device until an explicit read/request of the AD
- **uint8_t getMode()** returns current mode 0 or 1, or ADS1X15_INVALID_MODE = 0xFE.


### Data rate
#### Data rate

- **void setDataRate(uint8_t dataRate)** Data rate depends on type of device.
For all devices the index 0..7 can be used, see table below.
Expand All @@ -172,7 +176,7 @@ Data rate in samples per second, based on datasheet is described on table below.
| 7 | 3300 | 860 | fastest |


### ReadADC Single mode
#### ReadADC Single mode

Reading the ADC is very straightforward, the **readADC()** function handles all in one call.
Under the hood it uses the asynchronous calls.
Expand Down Expand Up @@ -221,7 +225,7 @@ in terms of code
See [examples](https://github.com/RobTillaart/ADS1X15/blob/master/examples/ADS_read_async/ADS_read_async.ino).
## ReadADC Differential
#### ReadADC Differential
For reading the ADC in a differential way there are 4 calls possible.
Expand Down Expand Up @@ -250,7 +254,7 @@ After one of these calls you need to call
See [examples](https://github.com/RobTillaart/ADS1X15/blob/master/examples/ADS_differential/ADS_differential.ino).


### ReadADC continuous mode
#### ReadADC continuous mode

To use the continuous mode you need call three functions:
- **void setMode(0)** 0 = CONTINUOUS, 1 = SINGLE (default).
Expand Down Expand Up @@ -283,7 +287,7 @@ Instead you can configure the threshold registers to allow the **ALERT/RDY**
pin to trigger an interrupt signal when conversion data ready.


### Threshold registers
#### Threshold registers

If the thresholdHigh is set to 0x0100 and the thresholdLow to 0x0000
the **ALERT/RDY** pin is triggered when a conversion is ready.
Expand All @@ -296,7 +300,7 @@ the **ALERT/RDY** pin is triggered when a conversion is ready.
See [examples](https://github.com/RobTillaart/ADS1X15/blob/master/examples/ADS_read_RDY/ADS_read_RDY.ino).


## Comparator
#### Comparator

Please read Page 15 of the datasheet as the behaviour of the
comparator is not trivial.
Expand All @@ -305,7 +309,7 @@ NOTE: all comparator settings are copied to the device only after calling
**readADC()** or **requestADC()** functions.


### Comparator Mode
#### Comparator Mode

When configured as a **TRADITIONAL** comparator, the **ALERT/RDY** pin asserts
(active low by default) when conversion data exceed the limit set in the
Expand All @@ -326,7 +330,7 @@ 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.


### Polarity
#### Polarity

Default state of the **ALERT/RDY** pin is **LOW**, can be to set **HIGH**.

Expand All @@ -335,7 +339,7 @@ Flag is only explicitly set after a **readADC()** or a **requestADC()**
- **uint8_t getComparatorPolarity()** returns value set.


### Latch
#### Latch

Holds the **ALERT/RDY** to **HIGH** (or **LOW** depending on polarity) after triggered
even if actual value has been 'restored to normal' value.
Expand All @@ -344,7 +348,7 @@ even if actual value has been 'restored to normal' value.
- **uint8_t getComparatorLatch()** returns value set.


### QueConvert
#### QueConvert

Set the number of conversions before trigger activates.
The **void setComparatorQueConvert(uint8_t mode)** is used to set the number of
Expand All @@ -362,7 +366,7 @@ A value of 3 (or above) effectively disables the comparator. See table below.
| 3 | Disable comparator | default |


### Threshold registers comparator mode
#### Threshold registers comparator mode

Depending on the comparator mode **TRADITIONAL** or **WINDOW** the thresholds registers
mean something different see - Comparator Mode above or datasheet.
Expand All @@ -373,7 +377,7 @@ mean something different see - Comparator Mode above or datasheet.
- **int16_t getComparatorThresholdHigh()** reads value from device.


### RP2040 specific
## RP2040 specific

- **bool begin(int sda, int scl)** begin communication with the ADC.
It has the parameter for selecting on which pins the communication should happen.
Expand Down
2 changes: 1 addition & 1 deletion examples/ADS_1114_four/ADS_1114_four.ino
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,7 @@ void setup()
Serial.print(" ");
Serial.println(ADS[i].begin() ? "connected" : "not connected");

ADS[i].setDataRate(4); // 7 is fastest, but more noise
ADS[i].setDataRate(4); // 0 = slow 4 = medium 7 = fast, but more noise
}
ADS_request_all();
}
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,7 @@ void setup()
// SETUP FIRST ADS1114
ADS_1.begin();
ADS_1.setGain(0); // 0 == 6.144 volt, default
ADS_1.setDataRate(7); // 7 == highest
ADS_1.setDataRate(7); // 0 = slow 4 = medium 7 = fast

// SET ALERT RDY PIN
ADS_1.setComparatorThresholdHigh(0x8000);
Expand Down
5 changes: 2 additions & 3 deletions examples/ADS_RP2040_WIRE1/ADS_RP2040_WIRE1.ino
Original file line number Diff line number Diff line change
@@ -1,9 +1,8 @@
//
// FILE: ADS_RP2040_WIRE1.ino
// AUTHOR: Rob.Tillaart / Intubun
// VERSION: 0.1.1
// PURPOSE: read analog input
//
// URL: https://github.com/RobTillaart/ADS1X15

// test
// connect 1 potmeter
Expand Down Expand Up @@ -35,7 +34,7 @@ void setup()

ADS.begin(26, 27); // SDA (Pin 26), SCL(Pin 27)
ADS.setGain(0); // 6.144 volt
ADS.setDataRate(7); // fast
ADS.setDataRate(7); // 0 = slow 4 = medium 7 = fast
ADS.setMode(0); // continuous mode
ADS.readADC(0); // first read to trigger
}
Expand Down
2 changes: 1 addition & 1 deletion examples/ADS_async_16_channel/ADS_async_16_channel.ino
Original file line number Diff line number Diff line change
Expand Up @@ -39,7 +39,7 @@ void setup()
Serial.print(" ");
Serial.println(ADS[i].begin() ? "connected" : "not connected");

ADS[i].setDataRate(4); // 7 is fastest, but more noise
ADS[i].setDataRate(4); // 0 = slow 4 = medium 7 = fast, but more noise
}
ADS_request_all();
}
Expand Down
2 changes: 1 addition & 1 deletion examples/ADS_async_8_channel/ADS_async_8_channel.ino
Original file line number Diff line number Diff line change
Expand Up @@ -46,7 +46,7 @@ void setup()
// Serial.println(ADS2.isConnected());
// Serial.println(ADS3.isConnected());

ADS0.setDataRate(4); // 7 is fastest, but more noise
ADS0.setDataRate(4); // 0 = slow 4 = medium 7 = fast but more noise
ADS1.setDataRate(4);
// ADS2.setDataRate(4);
// ADS3.setDataRate(4);
Expand Down
4 changes: 2 additions & 2 deletions examples/ADS_async_differential/ADS_async_differential.ino
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
// AUTHOR: Rob.Tillaart
// VERSION: 0.1.0
// PURPOSE: read multiple differential continuously
//
// URL: https://github.com/RobTillaart/ADS1X15

// test
// connect 4 potmeters
Expand Down Expand Up @@ -42,7 +42,7 @@ void setup()

ADS.begin();
ADS.setGain(0); // 6.144 volt
ADS.setDataRate(4); // medium
ADS.setDataRate(4); // 0 = slow 4 = medium 7 = fast

// single shot mode
ADS.setMode(1);
Expand Down
5 changes: 2 additions & 3 deletions examples/ADS_continuous/ADS_continuous.ino
Original file line number Diff line number Diff line change
@@ -1,9 +1,8 @@
//
// FILE: ADS_continuous.ino
// AUTHOR: Rob.Tillaart
// VERSION: 0.1.1
// PURPOSE: read analog input
//
// URL: https://github.com/RobTillaart/ADS1X15

// test
// connect 1 potmeter
Expand Down Expand Up @@ -35,7 +34,7 @@ void setup()

ADS.begin();
ADS.setGain(0); // 6.144 volt
ADS.setDataRate(7); // fast
ADS.setDataRate(7); // 0 = slow 4 = medium 7 = fast
ADS.setMode(0); // continuous mode
ADS.readADC(0); // first read to trigger
}
Expand Down
121 changes: 121 additions & 0 deletions examples/ADS_continuous_3_channel/ADS_continuous_3_channel.ino
Original file line number Diff line number Diff line change
@@ -0,0 +1,121 @@
//
// FILE: ADS_continuous_3_channel.ino
// AUTHOR: Rob.Tillaart
// PURPOSE: read multiple analog inputs continuously
// interrupt driven to catch all conversions.
// URL: https://github.com/RobTillaart/ADS1X15
// https://github.com/RobTillaart/ADS1X15/issues/49
//
// experimental, not tested extensively

// test
// connect multiple potmeters
//
// RDY ----------------- pin 2 (for IRQ)
//
// GND ---[ x ]------ 5V
// |
// |
// ADS(n)
//
// measure at x - connect to AIN0..3.
//
// for the test it is an option to have AIN3 connected to 5V and AIN4 to GND
// so one can see these as references in the output.
//
// has an issue with the index of the channels. not not investigated yet.


#include "ADS1X15.h"


// choose your sensor
// ADS1013 ADS(0x48);
// ADS1014 ADS(0x48);
// ADS1015 ADS(0x48);
// ADS1113 ADS(0x48);
// ADS1114 ADS(0x48);
ADS1115 ADS(0x48);

volatile bool RDY = false;
uint8_t channel = 0;
int16_t val[4] = { 0, 0, 0, 0 };

int SPS = 0;
uint32_t lastTime = 0;


void setup()
{
Serial.begin(230400); // <<<<<<<<< fast!
Serial.println(__FILE__);
Serial.print("ADS1X15_LIB_VERSION: ");
Serial.println(ADS1X15_LIB_VERSION);

Wire.setClock(400000);

ADS.begin();
ADS.setGain(0); // 6.144 volt
ADS.setDataRate(7); // 0 = slow 4 = medium 7 = fast

// SET ALERT RDY PIN
ADS.setComparatorThresholdHigh(0x8000);
ADS.setComparatorThresholdLow(0x0000);
ADS.setComparatorQueConvert(0);

// SET INTERRUPT HANDLER TO CATCH CONVERSION READY
pinMode(2, INPUT_PULLUP);
attachInterrupt(digitalPinToInterrupt(2), adsReady, RISING);

ADS.setMode(0); // continuous mode
channel = 0;
ADS.requestADC(channel); // start at 0
}


void loop()
{
// if conversion ready
// request a new one and print the last one.
if (RDY)
{
SPS++;
val[channel] = ADS.getValue();
// request next channel asap
channel++;
if (channel >= 3) channel = 0;
ADS.requestADC(channel);
RDY = false;

// to see it works
if (SPS % 200 == 0)
{
for (int i = 0; i < 4; i++)
{
Serial.print('\t');
Serial.print(val[i]);
}
Serial.println();
}
}


// print the SPS
if (millis() - lastTime >= 1000)
{
lastTime = millis();
Serial.print("SPS: ");
Serial.println(SPS);
SPS = 0;
}
}


// interrupt service routine
// kept as minimal as possible
void adsReady()
{
RDY = true;
}

// -- END OF FILE --
Original file line number Diff line number Diff line change
@@ -1,10 +1,9 @@
//
// FILE: ADS_continuous_4_channel.ino
// AUTHOR: Rob.Tillaart
// VERSION: 0.1.2
// PURPOSE: read multiple analog inputs continuously
// interrupt driven to catch all conversions.
//
// URL: https://github.com/RobTillaart/ADS1X15

// test
// connect multiple potmeters
Expand Down Expand Up @@ -47,7 +46,7 @@ void setup()

ADS.begin();
ADS.setGain(0); // 6.144 volt
ADS.setDataRate(7); // slow
ADS.setDataRate(7); // 0 = slow 4 = medium 7 = fast

// SET ALERT RDY PIN
ADS.setComparatorThresholdHigh(0x8000);
Expand Down
Loading

0 comments on commit 1d53197

Please sign in to comment.