260 lines
7.5 KiB
Markdown
260 lines
7.5 KiB
Markdown
# ADS1115 Module
|
||
| Since | Origin / Contributor | Maintainer | Source |
|
||
| :----- | :-------------------- | :---------- | :------ |
|
||
| 2017-04-24 | [fetchbot](https://github.com/fetchbot) | [fetchbot](https://github.com/fetchbot) | [ads1115.c](../../app/modules/ads1115.c)|
|
||
|
||
This module provides access to the ADS1115 (16-Bit) and ADS1015 (12-Bit) analog-to-digital converters.
|
||
Other chips from the same family (ADS1113, ADS1114, ADS1013 and ADS1014) are likely to work. Missing hardware features will be silently ignored.
|
||
|
||
This module supports multiple devices connected to I²C bus. The devices of different types can be mixed.
|
||
The addressing of ADS family allows for maximum of 4 devices connected to the same I²C bus.
|
||
|
||
!!! caution
|
||
|
||
The **ABSOLUTE MAXIMUM RATINGS** for all analog inputs are `–0.3V to VDD+0.3V` referred to GND.
|
||
|
||
|
||
|
||
## ads1115.ads1115()
|
||
Registers ADS1115 (ADS1113, ADS1114) device.
|
||
|
||
#### Syntax
|
||
`ads1115.ADS1115(I2C_ID, I2C_ADDR)`
|
||
|
||
#### Parameters
|
||
- `I2C_ID` - always 0
|
||
- `ADDRESS` - I²C address of a device
|
||
* `ads1115.ADDR_GND`
|
||
* `ads1115.ADDR_VDD`
|
||
* `ads1115.ADDR_SDA`
|
||
* `ads1115.ADDR_SCL`
|
||
|
||
#### Returns
|
||
Registered `device` object
|
||
|
||
#### Example
|
||
```lua
|
||
local id, sda, scl = 0, 6, 5
|
||
i2c.setup(id, sda, scl, i2c.SLOW)
|
||
ads1115.reset()
|
||
adc1 = ads1115.ads1115(id, ads1115.ADDR_GND)
|
||
```
|
||
|
||
|
||
## ads1115.ads1015()
|
||
Registers ADS1015 (ADS1013, ADS1014) device.
|
||
|
||
#### Syntax
|
||
`ads1115.ads1015(I2C_ID, I2C_ADDR)`
|
||
|
||
#### Parameters
|
||
- `I2C_ID` - always 0
|
||
- `ADDRESS` - I²C address of a device
|
||
* `ads1115.ADDR_GND`
|
||
* `ads1115.ADDR_VDD`
|
||
* `ads1115.ADDR_SDA`
|
||
* `ads1115.ADDR_SCL`
|
||
|
||
#### Returns
|
||
Registered `device` object
|
||
|
||
#### Example
|
||
```lua
|
||
local id, sda, scl = 0, 6, 5
|
||
i2c.setup(id, sda, scl, i2c.SLOW)
|
||
ads1115.reset()
|
||
adc1 = ads1115.ads1015(id, ads1115.ADDR_VDD)
|
||
adc2 = ads1115.ads1115(id, ads1115.ADDR_SDA)
|
||
```
|
||
## ads1115.reset()
|
||
Reset all devices connected to I²C interface.
|
||
|
||
### Syntax
|
||
ads1115.reset()
|
||
|
||
#### Parameters
|
||
none
|
||
|
||
#### Returns
|
||
`nil`
|
||
|
||
#### Example
|
||
```lua
|
||
local id, alert_pin, sda, scl = 0, 7, 6, 5
|
||
i2c.setup(id, sda, scl, i2c.SLOW)
|
||
ads1115.reset()
|
||
```
|
||
|
||
|
||
# ADS Device
|
||
|
||
## ads1115.device:read()
|
||
Gets the result stored in the register of a previously issued conversion, e.g. in continuous mode or with a conversion ready interrupt.
|
||
|
||
#### Syntax
|
||
`volt, volt_dec, raw, sign = device:read()`
|
||
|
||
#### Parameters
|
||
none
|
||
|
||
#### Returns
|
||
- `volt` voltage in mV (see note below)
|
||
- `volt_dec` voltage decimal in uV (see note below)
|
||
- `adc` raw adc register value
|
||
- `sign` sign of the result (see note below)
|
||
|
||
!!! note
|
||
|
||
If using float firmware then `volt` is a floating point number, `volt_dec` and `sign` are nil. On an integer firmware, the final value has to be concatenated from `volt`, `volt_dec` and `sign`. On integer firmware `volt` and `volt_dec` are always positive, sign can be `-1`, `0`, `1`.
|
||
|
||
#### Example
|
||
```lua
|
||
local id, alert_pin, sda, scl = 0, 7, 6, 5
|
||
i2c.setup(id, sda, scl, i2c.SLOW)
|
||
ads1115.reset()
|
||
adc1 = ads1115.ads1115(id, ads1115.ADDR_GND)
|
||
|
||
-- continuous mode
|
||
adc1:setting(ads1115.GAIN_6_144V, ads1115.DR_128SPS, ads1115.SINGLE_0, ads1115.CONTINUOUS)
|
||
-- read adc result with read()
|
||
volt, volt_dec, adc, sign = ads1:read()
|
||
print(volt, volt_dec, adc, sign)
|
||
|
||
-- comparator
|
||
adc1:setting(ads1115.GAIN_6_144V, ads1115.DR_128SPS, ads1115.SINGLE_0, ads1115.CONTINUOUS, ads1115.COMP_1CONV, 1000, 2000)
|
||
local function comparator(level, when)
|
||
-- read adc result with read() when threshold reached
|
||
gpio.trig(alert_pin)
|
||
volt, volt_dec, adc, sign = adc1:read()
|
||
print(volt, volt_dec, adc, sign)
|
||
end
|
||
gpio.mode(alert_pin, gpio.INT)
|
||
gpio.trig(alert_pin, "both", comparator)
|
||
|
||
-- read adc result with read()
|
||
volt, volt_dec, adc, sign = ads1115:read()
|
||
print(volt, volt_dec, adc, sing)
|
||
|
||
-- format value in int build
|
||
if sign then
|
||
-- int build
|
||
print(string.format("%s%d.%03d mV", sign >= 0 and "+" or "-", volt, volt_dec))
|
||
else
|
||
-- float build
|
||
-- just use V as it is
|
||
end
|
||
```
|
||
|
||
|
||
## ads1115.device:setting()
|
||
Configuration settings for the ADC.
|
||
|
||
#### Syntax
|
||
`device:setting(GAIN, SAMPLES, CHANNEL, MODE[, CONVERSION_RDY][, COMPARATOR, THRESHOLD_LOW, THRESHOLD_HI[,COMP_MODE]])`
|
||
|
||
#### Parameters
|
||
- `GAIN` Programmable gain amplifier
|
||
* `ads1115.GAIN_6_144V` 2/3x Gain
|
||
* `ads1115.GAIN_4_096V` 1x Gain
|
||
* `ads1115.GAIN_2_048V` 2x Gain
|
||
* `ads1115.GAIN_1_024V` 4x Gain
|
||
* `ads1115.GAIN_0_512V` 8x Gain
|
||
* `ads1115.GAIN_0_256V` 16x Gain
|
||
- `SAMPLES` Data rate in samples per second
|
||
* `ads1115.DR_8SPS` ADS1115 only
|
||
* `ads1115.DR_16SPS` ADS1115 only
|
||
* `ads1115.DR_32SPS` ADS1115 only
|
||
* `ads1115.DR_64SPS` ADS1115 only
|
||
* `ads1115.DR_128SPS`
|
||
* `ads1115.DR_250SPS`
|
||
* `ads1115.DR_475SPS` ADS1115 only
|
||
* `ads1115.DR_490SPS` ADS1015 only
|
||
* `ads1115.DR_860SPS` ADS1115 only
|
||
* `ads1115.DR_920SPS` ADS1015 only
|
||
* `ads1115.DR_1600SPS` ADS1015 only
|
||
* `ads1115.DR_2400SPS` ADS1015 only
|
||
* `ads1115.DR_3300SPS` ADS1015 only
|
||
- `CHANNEL` Input multiplexer for single-ended or differential measurement
|
||
* `ads1115.SINGLE_0` channel 0 to GND
|
||
* `ads1115.SINGLE_1` channel 1 to GND
|
||
* `ads1115.SINGLE_2` channel 2 to GND
|
||
* `ads1115.SINGLE_3` channel 3 to GND
|
||
* `ads1115.DIFF_0_1` channel 0 to 1
|
||
* `ads1115.DIFF_0_3` channel 0 to 3
|
||
* `ads1115.DIFF_1_3` channel 1 to 3
|
||
* `ads1115.DIFF_2_3` channel 2 to 3
|
||
- `MODE` Device operating mode
|
||
* `ads1115.SINGLE_SHOT` single-shot mode
|
||
* `ads1115.CONTINUOUS` continuous mode
|
||
- `CONVERSION_RDY` Number of conversions after conversion ready asserts (optional)
|
||
* `ads1115.CONV_RDY_1`
|
||
* `ads1115.CONV_RDY_2`
|
||
* `ads1115.CONV_RDY_4`
|
||
- `COMPARATOR` Number of conversions after comparator asserts (optional)
|
||
* `ads1115.COMP_1CONV`
|
||
* `ads1115.COMP_2CONV`
|
||
* `ads1115.COMP_4CONV`
|
||
- `THRESHOLD_LOW`
|
||
* `0` - `+ GAIN_MAX` in mV for single-ended inputs
|
||
* `- GAIN_MAX` - `+ GAIN_MAX` in mV for differential inputs
|
||
- `THRESHOLD_HI`
|
||
* `0` - `+ GAIN_MAX` in mV for single-ended inputs
|
||
* `- GAIN_MAX` - `+ GAIN_MAX` in mV for differential inputs
|
||
- `COMP_MODE` Comparator mode
|
||
* `ads1115.CMODE_TRAD` traditional comparator mode (with hysteresis)
|
||
* `ads1115.CMODE_WINDOW` window comparator mode
|
||
|
||
note: Comparator and conversion ready are always configured to non-latching, active low.
|
||
|
||
#### Returns
|
||
`nil`
|
||
|
||
#### Example
|
||
```lua
|
||
local id, sda, scl = 0, 6, 5
|
||
i2c.setup(id, sda, scl, i2c.SLOW)
|
||
ads1115.reset()
|
||
adc1 = ads1115.ads1015(id, ads1115.ADDR_GND)
|
||
|
||
adc1:setting(ads1115.GAIN_6_144V, ads1115.DR_3300SPS, ads1115.SINGLE_0, ads1115.SINGLE_SHOT)
|
||
```
|
||
|
||
|
||
## ads1115.device:startread()
|
||
Starts the ADC reading for single-shot mode and after the conversion is done it will invoke an optional callback function in which the ADC conversion result can be obtained.
|
||
|
||
#### Syntax
|
||
`device:startread([CALLBACK])`
|
||
|
||
#### Parameters
|
||
- `CALLBACK` callback function which will be invoked after the adc conversion is done
|
||
* `function(volt, volt_dec, adc, sign) end`
|
||
|
||
#### Returns
|
||
- `nil`
|
||
|
||
#### Example
|
||
```lua
|
||
local id, alert_pin, sda, scl = 0, 7, 6, 5
|
||
i2c.setup(id, sda, scl, i2c.SLOW)
|
||
ads1115.reset()
|
||
adc1 = ads1115.ads1115(id, ads1115.ADDR_VDD)
|
||
|
||
-- single shot
|
||
adc1:setting(ads1115.GAIN_6_144V, ads1115.DR_128SPS, ads1115.SINGLE_0, ads1115.SINGLE_SHOT)
|
||
-- start adc conversion and get result in callback after conversion is ready
|
||
adc1:startread(function(volt, volt_dec, adc, sign) print(volt, volt_dec, adc, sign) end)
|
||
|
||
-- conversion ready
|
||
adc1:setting(ads1115.GAIN_6_144V, ads1115.DR_128SPS, ads1115.SINGLE_0, ads1115.SINGLE_SHOT, ads1115.CONV_RDY_1)
|
||
local function conversion_ready(level, when)
|
||
gpio.trig(alert_pin)
|
||
volt, volt_dec, adc, sign = adc1:read()
|
||
print(volt, volt_dec, adc, sign)
|
||
end
|
||
gpio.mode(alert_pin, gpio.INT)
|
||
gpio.trig(alert_pin, "down", conversion_ready)
|
||
-- start conversion and get result with read() after conversion ready pin asserts
|
||
adc1:startread()
|
||
```
|