raspi-kit-ads1x15
v1.0.0
Published
Analog to Digital converter library for ADS1015 and ADS1115
Downloads
38
Maintainers
Readme
ADS1x15 Interface over I2C
This module provides an interface to working with the ADS1015 and ADS1115 analog to digital converter chips over I2C.
The primary focus of this module is code quality and maintainability. There's nothing worse than half-written, untested modules that can barely be used for projects. Every feature has been unit tested and hardware tested. If you find a bug, please file an issue and a pull request.
We utilize the Raspi.js suite for underlying hardware communication. If you want to
use something other than raspi-i2c
underlying swapping it out isn't much hassle.
This module was written from scratch with inspiration from Adafruit's Python library and the (not-production-ready, abandoned port of the Adafruit library) node-ads1x15 module.
Requirements
To use this module, you'll need:
- System Requirements – See Raspi-I2C for specific hardware and operating system requirements.
- Peer Dependencies – This module assumes that you have
raspi
andraspi-i2c
installed in your package. - Node.js – Supports current LTS versions, such as v6 and v8.
Installation
Your project must have raspi
and raspi-i2c
installed, as this module assumes they are installed as peers.
If you have not done so already, then using npm or yarn:
npm install raspi raspi-i2c
yarn add raspi raspi-i2c
Then install this module using npm or yarn:
npm install raspi-kit-ads1x15
yarn add raspi-kit-ads1x15
Quick Start
Here's a simple example on using the ADS1x15 class.
"use strict";
const Raspi = require('raspi');
const I2C = require('raspi-i2c').I2C;
const ADS1x15 = require('raspi-kit-ads1x15');
// Init Raspi
Raspi.init(() => {
// Init Raspi-I2c
const i2c = new I2C();
// Init the ADC
const adc = new ADS1x15({
i2c, // i2c interface
chip: ADS1x15.chips.IC_ADS1015, // chip model
address: ADS1x15.address.ADDRESS_0x48, // i2c address on the bus
// Defaults for future readings
pga: ADS1x15.pga.PGA_4_096V, // power-gain-amplifier range
sps: ADS1x15.spsADS1015.SPS_250 // data rate (samples per second)
});
// Get a single-ended reading from channel-0 and display the results
adc.readChannel(ADS1x15.channel.CHANNEL_0, (err, value, volts) => {
if (err) {
console.error('Failed to fetch value from ADC', err);
process.exit(1);
} else {
console.log('Channel 0');
console.log(' * Value:', value); // will be a 11 or 15 bit integer depending on chip
console.log(' * Volts:', volts); // voltage reading factoring in the PGA
process.exit(0);
}
});
});
The example might produce output that looks like this:
Channel 0
* Value: 652
* Volts: 1.304637029799707
Simple!
ADS1x15 Enumerations
The ADS1x15 class exposes static enumeration properties. Please use these enumerations when working with the class.
Most enumerations map to their respective configuration register bits.
ADS1x15.chips
Enumeration containing the supported series integrated circuit chips.
ADS1x15.chips.IC_ADS1015
– ADS1015 chipADS1x15.chips.IC_ADS1115
– ADS1115 chip (default)
ADS1x15.address
Enumeration containing the supported I2C addresses of the chip series.
ADS1x15.address.ADDRESS_0x48
–0x48
I2C address (default)ADS1x15.address.ADDRESS_0x49
–0x49
I2C addressADS1x15.address.ADDRESS_0x4A
–0x4A
I2C addressADS1x15.address.ADDRESS_0x4B
–0x4B
I2C address
ADS1x15.channel
Enumeration containing the single-ended channel list.
ADS1x15.channel.CHANNEL_0
– AIN1ADS1x15.channel.CHANNEL_1
– AIN2ADS1x15.channel.CHANNEL_2
– AIN3ADS1x15.channel.CHANNEL_3
– AIN4
ADS1x15.differential
Enumeration containing the channel comparator options.
ADS1x15.differential.DIFF_0_1
– P=AIN0, N=AIN1, e.g. 1 minus 0 (default)ADS1x15.differential.DIFF_0_3
– P=AIN0, N=AIN3, e.g. 3 minus 0ADS1x15.differential.DIFF_1_3
– P=AIN1, N=AIN3, e.g. 3 minus 1ADS1x15.differential.DIFF_2_3
– P=AIN2, N=AIN3, e.g. 3 minus 2
ADS1x15.pga
Enumeration containing the power gain amplifier options.
ADS1x15.pga.PGA_6_144V
– +/- 6.144VADS1x15.pga.PGA_4_096V
– +/- 4.096VADS1x15.pga.PGA_2_048V
– +/- 2.048VADS1x15.pga.PGA_1_024V
– +/- 1.024VADS1x15.pga.PGA_0_512V
– +/- 0.512VADS1x15.pga.PGA_0_256V
– +/- 0.256V
ADS1x15.pgaToVolts
Lookup map converting ADS1x15.pga.*
values into volts.
For example:
const pgaRangeVolts = ADS1x15.pgaToVolts[ADS1x15.pga.PGA_4_096V]; // === 4.096
ADS1x15.spsADS1015
Enumeration containing the data rate options for the ADS1015 chip.
ADS1x15.spsADS1015.SPS_128
– 128 samples per secondADS1x15.spsADS1015.SPS_250
– 250 samples per secondADS1x15.spsADS1015.SPS_490
– 490 samples per secondADS1x15.spsADS1015.SPS_920
– 920 samples per secondADS1x15.spsADS1015.SPS_1600
– 1600 samples per secondADS1x15.spsADS1015.SPS_2400
– 2400 samples per secondADS1x15.spsADS1015.SPS_3300
– 3300 samples per second
ADS1x15.spsADS1115
Enumeration containing the data rate options for the ADS1115 chip.
ADS1x15.spsADS1115.SPS_8
– 8 samples per secondADS1x15.spsADS1115.SPS_16
– 16 samples per secondADS1x15.spsADS1115.SPS_32
– 32 samples per secondADS1x15.spsADS1115.SPS_64
– 64 samples per secondADS1x15.spsADS1115.SPS_128
– 128 samples per secondADS1x15.spsADS1115.SPS_250
– 250 samples per secondADS1x15.spsADS1115.SPS_475
– 475 samples per secondADS1x15.spsADS1115.SPS_860
– 860 samples per second
ADS1x15.spsToMilliseconds
Lookup map converting ADS1x15.spsADS1x15.*
values into sample time length in milliseconds.
For example:
const sampleLength = ADS1x15.spsToMilliseconds.ADS1015[ADS1x15.spsADS1015.SPS_250]; // === 4 (milliseconds)
ADS1x15.comparatorMode
Enumeration containing the comparator modes.
ADS1x15.comparatorMode.TRADITIONAL
– Traditional mode (asserts when HIGH exceeded, de-asserts when drops below LOW, default)ADS1x15.comparatorMode.WINDOW
– Window mode (asserts when HIGH exceeded OR drops below LOW)
ADS1x15.comparatorActiveMode
Enumeration containing the alert pin active modes.
ADS1x15.comparatorActiveMode.ACTIVE_LOW
– Alert pin goes LOW when threshold met (default)ADS1x15.comparatorActiveMode.ACTIVE_HIGH
– Alert pin goes HIGH when threshold met
ADS1x15.comparatorLatchingMode
Enumeration containing the latching modes.
ADS1x15.comparatorLatchingMode.LATCHING
– Hold until value is read, alert clearedADS1x15.comparatorLatchingMode.NON_LATCHING
– Do not hold (default)
ADS1x15.comparatorReadings
Enumeration containing the comparator reading count options.
ADS1x15.comparatorReadings.DISABLED
– Comparator disabledADS1x15.comparatorReadings.READINGS_1
– Trigger alert pin after 1 reading (default for comparator mode)ADS1x15.comparatorReadings.READINGS_2
– Trigger alert pin after 2 readingsADS1x15.comparatorReadings.READINGS_4
– Trigger alert pin after 4 readings
ADS1x15.thresholdMaxValues
Enumeration containing the maximum value range for each chip.
ADS1x15.thresholdMaxValues.ADS1015_MAX_RANGE
– 2048 === 2^(12-1), 12bit (1 bit for sign), -2048 to 2047 reading rangeADS1x15.thresholdMaxValues.ADS1115_MAX_RANGE
– 32768 === 2^(16-1), 16bit (1bit for sign), -32768 to 32767 reading range
Remember that positive readings range from zero to MAX_RANGE minus one. Negative readings range from -MAX_RANGE to 0.
new ADS1x15([options])
Constructs a new instance of the ADS1x15 class with given optional parameters.
options
– Optional configuration parametersi2c
- (I2C) Raspi-I2C instance or compatible interface. See swapping it out for details. Defaults to new instance of raspi-i2c.chip
– (Enumeration) See ADS1x15.chips. Defaults toIC_ADS1015
with a warning message to the console.address
– (Enumeration) See ADS1x15.address. Defaults toADDRESS_0x48
.pga
– (Enumeration) See ADS1x15.pga. Defaults toPGA_2_048V
.sps
– (Enumeration) See ADS1x15.spsADS1015 or ADS1x15.spsADS1115. Defaults toSPS_250
on ADS1015 andSPS_1600
on ADS1115.spsExtraDelay
– (Number) Additional number of milliseconds to delay in addition to the reading time (based on sps). Defaults to1
millisecond.
Examples
Minimum usage, using class defaults:
const adc = new ADS1x15();
Typical usage:
const Raspi = require('raspi');
const I2C = require('raspi-i2c').I2C;
const ADS1x15 = require('raspi-kit-ads1x15');
// Init Raspi
Raspi.init(() => {
// Init Raspi-I2c
const i2c = new I2C();
// Init the ADC
const adc = new ADS1x15({
i2c, // i2c interface
chip: ADS1x15.chips.IC_ADS1015, // chip model
address: ADS1x15.address.ADDRESS_0x48, // i2c address on the bus
// Defaults for future readings
pga: ADS1x15.pga.PGA_4_096V, // power-gain-amplifier range
sps: ADS1x15.spsADS1015.SPS_250 // data rate (samples per second)
});
// ...
});
readChannel(channel, [options,] callback)
Reads the value for given single-ended channel in single-shot mode.
channel
– (Enumeration) The single-ended channel to read from. See ADS1x15.channel for options.options
– (Object) Optional reading parameters. Can be omitted.pga
– (Enumeration) See ADS1x15.pga. Defaults to the value set in the constructor.sps
– (Enumeration) See ADS1x15.spsADS1015 or ADS1x15.spsADS1115. Defaults to the value set in the constructor.
callback(err, value, volts)
– Callback fired when read operation completed.err
– (Error) If the operation failed, this value will be truthy.value
– (Number) The numeric value returned from the chip.volts
– (Number) The converted value in volts.
For example:
// Get a single-ended reading from channel-0 and display the results
adc.readChannel(ADS1x15.channel.CHANNEL_0, (err, value, volts) => {
if (err) {
console.error('Failed to fetch value from ADC', err);
} else {
console.log('Channel 0');
console.log(' * Value:', value); // will be a 11 or 15 bit integer depending on chip
console.log(' * Volts:', volts); // voltage reading factoring in the PGA
}
});
Check out the example applications for a more thorough demonstration.
readDifferential(differential, [options,] callback)
Reads the voltage differential for given channel set in single-shot mode.
differential
– (Enumeration) The channel differential to read from. See ADS1x15.differential for options.options
– (Object) Optional reading parameters. Can be omitted.pga
– (Enumeration) See ADS1x15.pga. Defaults to the value set in the constructor.sps
– (Enumeration) See ADS1x15.spsADS1015 or ADS1x15.spsADS1115. Defaults to the value set in the constructor.
callback(err, value, volts)
– Callback fired when read operation completed.err
– (Error) If the operation failed, this value will be truthy.value
– (Number) The numeric value returned from the chip.volts
– (Number) The converted value in volts.
For example:
// Get a differential reading and displays the results
adc.readDifferential(ADS1x15.differential.DIFF_0_1, (err, value, volts) => {
if (err) {
console.error('Failed to fetch value from ADC', err);
} else {
console.log('Channel 1 minus Channel 0');
console.log(' * Value:', value); // will be a 11 or 15 bit integer depending on chip
console.log(' * Volts:', volts); // voltage reading factoring in the PGA
}
});
Check out the example applications for a more thorough demonstration.
startContinuousChannel(channel, [options,] callback)
Starts continuous readings on the ADS chip. Use getLastReading to retrieve future values.
channel
– (Enumeration) The single-ended channel to read from. See ADS1x15.channel for options.options
– (Object) Optional reading parameters. Can be omitted.pga
– (Enumeration) See ADS1x15.pga. Defaults to the value set in the constructor.sps
– (Enumeration) See ADS1x15.spsADS1015 or ADS1x15.spsADS1115. Defaults to the value set in the constructor.
callback(err, value, volts)
– Callback fired when read operation completed. Contains the first reading from the chip.err
– (Error) If the operation failed, this value will be truthy.value
– (Number) The numeric value returned from the chip.volts
– (Number) The converted value in volts.
For example:
// Starts continuous readings from channel-0 and displays the initial results
adc.startContinuousChannel(ADS1x15.channel.CHANNEL_0, (err, value, volts) => {
if (err) {
console.error('Failed to fetch value from ADC', err);
} else {
console.log('Channel 0');
console.log(' * Value:', value); // will be a 11 or 15 bit integer depending on chip
console.log(' * Volts:', volts); // voltage reading factoring in the PGA
}
// From here on, call adc.getLastReading(...) for future readings
// When done, call adc.stopContinuousReadings(...) to stop the chip readings
});
Check out the example applications for a more thorough demonstration.
startContinuousDifferential(differential, [options,] callback)
Starts continuous differential readings on the ADS chip. Use getLastReading to retrieve future values.
differential
– (Enumeration) The channel differential to read from. See ADS1x15.differential for options.options
– (Object) Optional reading parameters. Can be omitted.pga
– (Enumeration) See ADS1x15.pga. Defaults to the value set in the constructor.sps
– (Enumeration) See ADS1x15.spsADS1015 or ADS1x15.spsADS1115. Defaults to the value set in the constructor.
callback(err, value, volts)
– Callback fired when read operation completed. Contains the first reading from the chip.err
– (Error) If the operation failed, this value will be truthy.value
– (Number) The numeric value returned from the chip.volts
– (Number) The converted value in volts.
For example:
// Starts continuous differential readings and displays the initial results
adc.startContinuousDifferential(ADS1x15.differential.DIFF_0_1, (err, value, volts) => {
if (err) {
console.error('Failed to fetch value from ADC', err);
} else {
console.log('Channel 1 minus Channel 0');
console.log(' * Value:', value); // will be a 11 or 15 bit integer depending on chip
console.log(' * Volts:', volts); // voltage reading factoring in the PGA
}
// From here on, call adc.getLastReading(...) for future readings
// When done, call adc.stopContinuousReadings(...) to stop the chip readings
});
Check out the example applications for a more thorough demonstration.
startComparatorChannel(channel, high, low, [options,] callback)
Starts the continuous comparator mode on the ADS chip, triggering the ALERT pin HIGH or LOW when the threshold criteria is met. Use getLastReading to retrieve values and clear alerts.
channel
– (Enumeration) The single-ended channel to read from. See ADS1x15.channel for options.high
– (Number) The high threshold value, not Volts. If you want to use Volts, use the getThresholdFromVolts helper function.low
– (Number) The low threshold value, not Volts. If you want to use Volts, use the getThresholdFromVolts helper function.options
– (Object) Optional reading parameters. Can be omitted.pga
– (Enumeration) See ADS1x15.pga. Defaults to the value set in the constructor.sps
– (Enumeration) See ADS1x15.spsADS1015 or ADS1x15.spsADS1115. Defaults to the value set in the constructor.comparatorMode
- (Enumeration) See ADS1x15.comparatorMode. Defaults toTRADITIONAL
.comparatorActiveMode
- (Enumeration) See ADS1x15.comparatorActiveMode. Defaults toACTIVE_LOW
.comparatorLatchingMode
- (Enumeration) See ADS1x15.comparatorLatchingMode. Defaults toNON_LATCHING
.comparatorReadings
- (Enumeration) See ADS1x15.comparatorReadings. Defaults toREADINGS_1
.
callback(err, value, volts)
– Callback fired when read operation completed. Contains the first reading from the chip.err
– (Error) If the operation failed, this value will be truthy.value
– (Number) The numeric value returned from the chip.volts
– (Number) The converted value in volts.
For example:
// Starts continuous comparator mode from channel-0 and displays the initial results
adc.startComparatorChannel(ADS1x15.channel.CHANNEL_0, 2000, 1000, (err, value, volts) => {
if (err) {
console.error('Failed to fetch value from ADC', err);
} else {
console.log('Channel 0');
console.log(' * Value:', value); // will be a 11 or 15 bit integer depending on chip
console.log(' * Volts:', volts); // voltage reading factoring in the PGA
}
// From here on, call adc.getLastReading(...) for future readings and to clear latched alerts
// When done, call adc.stopContinuousReadings(...) to stop the chip readings
});
Check out the example applications for a more thorough demonstration.
startComparatorDifferential(differential, high, low, [options,] callback)
Starts the continuous differential comparator mode on the ADS chip, triggering the ALERT pin HIGH or LOW when the threshold criteria is met. Use getLastReading to retrieve values and clear alerts.
differential
– (Enumeration) The channel differential to read from. See ADS1x15.differential for options.high
– (Number) The high threshold value, not Volts. If you want to use Volts, use the getThresholdFromVolts helper function.low
– (Number) The low threshold value, not Volts. If you want to use Volts, use the getThresholdFromVolts helper function.options
– (Object) Optional reading parameters. Can be omitted.pga
– (Enumeration) See ADS1x15.pga. Defaults to the value set in the constructor.sps
– (Enumeration) See ADS1x15.spsADS1015 or ADS1x15.spsADS1115. Defaults to the value set in the constructor.comparatorMode
- (Enumeration) See ADS1x15.comparatorMode. Defaults toTRADITIONAL
.comparatorActiveMode
- (Enumeration) See ADS1x15.comparatorActiveMode. Defaults toACTIVE_LOW
.comparatorLatchingMode
- (Enumeration) See ADS1x15.comparatorLatchingMode. Defaults toNON_LATCHING
.comparatorReadings
- (Enumeration) See ADS1x15.comparatorReadings. Defaults toREADINGS_1
.
callback(err, value, volts)
– Callback fired when read operation completed. Contains the first reading from the chip.err
– (Error) If the operation failed, this value will be truthy.value
– (Number) The numeric value returned from the chip.volts
– (Number) The converted value in volts.
For example:
// Starts continuous differential readings and displays the initial results
adc.startComparatorDifferential(ADS1x15.differential.DIFF_0_1, -100, -500, (err, value, volts) => {
if (err) {
console.error('Failed to fetch value from ADC', err);
} else {
console.log('Channel 1 minus Channel 0');
console.log(' * Value:', value); // will be a 11 or 15 bit integer depending on chip
console.log(' * Volts:', volts); // voltage reading factoring in the PGA
}
// From here on, call adc.getLastReading(...) for future readings and to clear latched alerts
// When done, call adc.stopContinuousReadings(...) to stop the chip readings
});
Check out the example applications for a more thorough demonstration.
getLastReading(callback)
Gets the latest reading value stored on the chip. Used when continuous readings are active.
callback(err, value, volts)
– Callback fired when read operation completed.err
– (Error) If the operation failed, this value will be truthy.value
– (Number) The numeric value returned from the chip.volts
– (Number) The converted value in volts.
For example:
adc.getLastReading((err, value, volts) => {
if (err) {
console.error('Failed to fetch value from ADC', err);
} else {
console.log(' * Value:', value); // will be a 11 or 15 bit integer depending on chip
console.log(' * Volts:', volts); // voltage reading factoring in the PGA
}
});
stopContinuousReadings(callback)
Stops continuous conversions on the chip. Call this when done making continuous readings to give the chip a break.
callback(err)
– Callback fired when read operation completed.err
– (Error) If the operation failed, this value will be truthy.
For example:
adc.stopContinuousReadings((err) => {
if (err) {
console.error('Failed to reset config register');
} else {
// good to go
}
});
getThresholdFromVolts(volts[, pga])
Helper function to convert Volts to a 12/16-bit adc value.
volts
– (Number) Known Voltage to convertpga
– (Enumeration) Optional power-gain-amplifier range. See ADS1x15.pga. Defaults to the value set in the constructor.
Returns the 12/16-bit adc value.
For example:
adc.startComparatorChannel(
ADS1x15.channel.CHANNEL_0, // channel
adc.getThresholdFromVolts(3.14), // high
adc.getThresholdFromVolts(1.50), // low
(err, value, volts) => { // callback
// ...
}
);
getVoltageFromValue(value, pga)
Helper function to convert a 12/16-bit adc value to volts.
value
– (Number) Known 12/16-bit adc value to convertpga
– (Enumeration) Power-gain-amplifier range. See ADS1x15.pga
Returns the corresponding value in Volts.
For example:
const volts = adc.getVoltageFromValue(2047, ADS1x15.pga.PGA_4_096V) // returns 4.096
Swapping Out Raspi-I2C
If you are using a different hardware I/O interface other than the Raspi.js suite, you can provide the ADS1x15 class with your own.
In the constructor, pass the i2c
option with an object that has the following interface:
i2c.read(address, register, numberOfBytes, callback(err, buffer))
This method should read bytes from the I2C interface and return them as a buffer.
address
– (integer) I2C address of the device.register
– (integer) Register pointer to read.numberOfBytes
(integer) Number of bytes to read from the register.callback(err, buffer)
(function) Callback to fire when read failed or completed.err
– Error object set if the read operation failed, ornull
if successful.buffer
Buffer object containing the bytes read.
i2c.write(address, register, buffer, callback(err))
This method should write bytes to an I2C device register.
address
– (integer) I2C address of the device.register
– (integer) Register pointer to read.buffer
– (Buffer) Data to write to the register.callback(err)
(function) Callback to fire when write failed or completed.err
– Error object set if the write operation failed, ornull
if successful.
The interface is simple enough that you should be able to provide your own shim if using another I/O library.
Additionally, you could extend the ADS1x15 class and override the _getI2CInterface
function:
class MyADS1x15 extends ADS1x15 {
constructor(options) {
super(options);
}
/**
* Gets the default interface class to I2C
*/
_getI2CInterface() {
const myI2CInterface = {
read: (address, register, byteCount, callback) => {
callback(null, Buffer.from((new Array(byteCount)).fill(0x00)));
},
write: (address, register, buffer, callback) => {
callback(null);
}
};
return myI2CInterface;
}
}
// Usage
const ads = new MyADS1x15();
ads.readChannel(...);
Contributing
If you find a bug or have suggestions, please open a pull request. Contributions are greatly appreciated.
To maintain standards, please ensure that contributions pass unit tests and has complete code coverage.
To run the tests:
npm run report
This script will run the unit tests, code quality and show code coverage. If you are lacking coverage, please
see coverage/index.html
to narrow down where your coverage is lacking.
License
TL;DR? see: http://www.tldrlegal.com/license/mit-license
The MIT License (MIT)
Copyright (c) 2018 Kevin M. Fitzgerald
Permission is hereby granted, free of charge, to any person obtaining a copy of
this software and associated documentation files (the "Software"), to deal in
the Software without restriction, including without limitation the rights to
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
of the Software, and to permit persons to whom the Software is furnished to do
so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.