MojoScale Studio Docs
API Reference

ads1115

ADS1115 16-bit I2C analog-to-digital converter module.

All modules Open Studio
Studio Docs Sensors & I/O

import ads1115

The ads1115 module reads ADS1115-compatible 4-channel ADC boards over I2C. It supports single-ended reads, valid ADS1115 differential channel pairs, per-reading gain/data-rate overrides, continuous conversions, and the ADS1115 comparator.

Quick example

import ads1115

adc = ads1115.ADS1115(sda=21, scl=22, address=0x48)

reading = adc.read(0)
print(reading["raw"])
print(reading["voltage_v"])

battery = adc.voltage(channel=1, gain=6.144)

adc.configure(gain=4.096, data_rate=128, mode="single")
diff = adc.read_diff(positive=0, negative=1)
print(diff["voltage_v"])

importads1115

ADS1115 16-bit I2C analog-to-digital converter module.

The ads1115 module reads ADS1115-compatible 4-channel ADC boards over I2C. It supports single-ended reads, valid ADS1115 differential channel pairs, per-reading gain/data-rate overrides, continuous conversions, and the ADS1115 comparator.

API 30 available

ads1115.ADS1115(sda: int, scl: int, address: int = None, frequency: int = None, port: int = None) -> ads1115_adc

Create and initialize an independent ADS1115 ADC.

Use one ADS1115 object for each physical ADC board. Multiple ADS1115 devices can share one I2C bus when each board has a unique address.

Parameters
Name Type Pass as Required Description
sda int positional or keyword Yes GPIO pin used for I2C SDA.
scl int positional or keyword Yes GPIO pin used for I2C SCL.
address int positional or keyword No Optional I2C address. Defaults to 0x48.
frequency int positional or keyword No Optional I2C bus speed in hertz. Defaults to 100000.
port int positional or keyword No Optional ESP-IDF I2C port number. Defaults to 0.
Returns

ads1115_adc ads1115_adc object.

ads1115.ADS1115().configure(gain=None, data_rate=None, mode=None) -> bool

Set default conversion range, data rate, and mode for this ADC.

Parameters
Name Type Pass as Required Description
gain int positional or keyword No Optional value. Defaults to None.
data_rate int positional or keyword No Optional value. Defaults to None.
mode str positional or keyword No Optional value. Defaults to None.

ads1115.ADS1115().read(channel, gain=None, data_rate=None) -> dict

Read one single-ended channel and return raw and voltage values.

Parameters
Name Type Pass as Required Description
channel int positional or keyword Yes Required value.
gain int positional or keyword No Optional value. Defaults to None.
data_rate int positional or keyword No Optional value. Defaults to None.

ads1115.ADS1115().voltage(channel, gain=None, data_rate=None) -> float

Read one single-ended channel and return volts.

Parameters
Name Type Pass as Required Description
channel int positional or keyword Yes Required value.
gain int positional or keyword No Optional value. Defaults to None.
data_rate int positional or keyword No Optional value. Defaults to None.

ads1115.ADS1115().read_diff(positive, negative, gain=None, data_rate=None) -> dict

Read a valid differential input pair.

Parameters
Name Type Pass as Required Description
positive int positional or keyword Yes Required value.
negative int positional or keyword Yes Required value.
gain int positional or keyword No Optional value. Defaults to None.
data_rate int positional or keyword No Optional value. Defaults to None.

ads1115.ADS1115().voltage_diff(positive, negative, gain=None, data_rate=None) -> float

Read a valid differential pair and return volts.

Parameters
Name Type Pass as Required Description
positive int positional or keyword Yes Required value.
negative int positional or keyword Yes Required value.
gain int positional or keyword No Optional value. Defaults to None.
data_rate int positional or keyword No Optional value. Defaults to None.

ads1115.ADS1115().start(channel, continuous=None) -> bool

Start a single-ended conversion without waiting for the value.

Parameters
Name Type Pass as Required Description
channel int positional or keyword Yes Required value.
continuous bool positional or keyword No Optional value. Defaults to None.

ads1115.ADS1115().start_diff(positive, negative, continuous=None) -> bool

Start a differential conversion without waiting for the value.

Parameters
Name Type Pass as Required Description
positive int positional or keyword Yes Required value.
negative int positional or keyword Yes Required value.
continuous bool positional or keyword No Optional value. Defaults to None.

ads1115.ADS1115().ready() -> bool

Check whether the current conversion is ready.

ads1115.ADS1115().last() -> dict

Read the latest conversion register without starting a new conversion.

ads1115.ADS1115().set_comparator(channel, high_threshold, low_threshold=None, latching=None, active_high=None, window=None, queue=None) -> bool

Enable the comparator for one single-ended channel.

Parameters
Name Type Pass as Required Description
channel int positional or keyword Yes Required value.
high_threshold int positional or keyword Yes Required value.
low_threshold int positional or keyword No Optional value. Defaults to None.
latching bool positional or keyword No Optional value. Defaults to None.
active_high bool positional or keyword No Optional value. Defaults to None.
window bool positional or keyword No Optional value. Defaults to None.
queue int positional or keyword No Optional value. Defaults to None.

ads1115.ADS1115().disable_comparator() -> bool

Disable the comparator.

ads1115.ADS1115().reset() -> bool

Restore this ADC's defaults.

ads1115.ADS1115().info() -> dict

Return I2C, gain, mode, comparator, and last-channel state for this ADC.

ads1115.ADS1115().close() -> bool

Release this ADS1115 handle.

ads1115.ADS1115().Example

adc = ads1115.ADS1115(sda=21, scl=22) print(adc.voltage(0))

ads1115.begin(sda: int, scl: int, address: int = None, frequency: int = None, port: int = None) -> bool

Legacy: initialize the module-level default ADS1115 ADC.

Prefer ``adc = ads1115.ADS1115(...)`` for new projects. The legacy wrapper keeps older singleton-style scripts working.

Parameters
Name Type Pass as Required Description
sda int positional or keyword Yes GPIO pin used for I2C SDA.
scl int positional or keyword Yes GPIO pin used for I2C SCL.
address int positional or keyword No Optional I2C address. Defaults to 0x48.
frequency int positional or keyword No Optional I2C bus speed in hertz. Defaults to 100000.
port int positional or keyword No Optional ESP-IDF I2C port number. Defaults to 0.
Returns

bool True when the device acknowledges the initial ADS1115 register setup.

ads1115.configure(gain: float = None, data_rate: int = None, mode: str = None) -> bool

Set the default ADS1115 conversion settings.

Parameters
Name Type Pass as Required Description
gain float positional or keyword No Optional full-scale input range in volts. Use 6.144, 4.096, 2.048, 1.024, 0.512, or 0.256. Defaults to 4.096.
data_rate int positional or keyword No Optional samples per second. Use 8, 16, 32, 64, 128, 250, 475, or 860. Defaults to 128.
mode str positional or keyword No Optional conversion mode. Use "single" or "continuous". Defaults to "single".
Returns

bool True when the config register is written.

ads1115.read(channel: int, gain: float = None, data_rate: int = None) -> dict

Read one single-ended channel and return raw and voltage values.

This performs a blocking single conversion. Use a lower gain value, such as 0.256, for small signals and a larger range, such as 6.144, when the input can be higher.

Parameters
Name Type Pass as Required Description
channel int positional or keyword Yes Single-ended ADC input channel. Use 0, 1, 2, or 3.
gain float positional or keyword No Optional full-scale input range in volts for this read only.
data_rate int positional or keyword No Optional samples per second for this read only.
Returns

dict Dict with ``ok``, ``raw``, ``voltage``, ``voltage_v``, ``channel``, ``positive``, ``negative``, ``differential``, ``ready``, ``gain``, ``fsr_v``, ``data_rate``, ``mode``, and ``address`` fields.

ads1115.voltage(channel: int, gain: float = None, data_rate: int = None) -> float

Read one single-ended channel and return volts.

Parameters
Name Type Pass as Required Description
channel int positional or keyword Yes Single-ended ADC input channel. Use 0, 1, 2, or 3.
gain float positional or keyword No Optional full-scale input range in volts for this read only.
data_rate int positional or keyword No Optional samples per second for this read only.
Returns

float Float measured input voltage in volts.

ads1115.read_diff(positive: int, negative: int, gain: float = None, data_rate: int = None) -> dict

Read a valid ADS1115 differential input pair.

Parameters
Name Type Pass as Required Description
positive int positional or keyword Yes Positive differential input channel.
negative int positional or keyword Yes Negative differential input channel. Valid pairs are 0-1, 0-3, 1-3, and 2-3.
gain float positional or keyword No Optional full-scale input range in volts for this read only.
data_rate int positional or keyword No Optional samples per second for this read only.
Returns

dict Dict with the same fields as ``read()``, with ``differential`` set to True and ``positive``/``negative`` set to the selected pair.

ads1115.voltage_diff(positive: int, negative: int, gain: float = None, data_rate: int = None) -> float

Read a valid ADS1115 differential pair and return volts.

Parameters
Name Type Pass as Required Description
positive int positional or keyword Yes Positive differential input channel.
negative int positional or keyword Yes Negative differential input channel. Valid pairs are 0-1, 0-3, 1-3, and 2-3.
gain float positional or keyword No Optional full-scale input range in volts for this read only.
data_rate int positional or keyword No Optional samples per second for this read only.
Returns

float Float differential voltage in volts.

ads1115.start(channel: int, continuous: bool = None) -> bool

Start a single-ended conversion without waiting for the value.

Parameters
Name Type Pass as Required Description
channel int positional or keyword Yes Single-ended ADC input channel. Use 0, 1, 2, or 3.
continuous bool positional or keyword No Optional mode flag. True starts continuous conversion, False starts one single-shot conversion. Defaults to False.
Returns

bool True when the conversion command is written.

ads1115.start_diff(positive: int, negative: int, continuous: bool = None) -> bool

Start a differential conversion without waiting for the value.

Parameters
Name Type Pass as Required Description
positive int positional or keyword Yes Positive differential input channel.
negative int positional or keyword Yes Negative differential input channel. Valid pairs are 0-1, 0-3, 1-3, and 2-3.
continuous bool positional or keyword No Optional mode flag. True starts continuous conversion, False starts one single-shot conversion. Defaults to False.
Returns

bool True when the conversion command is written.

ads1115.ready() -> bool

Check whether the current ADS1115 conversion is ready.

Returns

bool True when the ADS1115 ready bit says the conversion is complete.

ads1115.last() -> dict

Read the latest conversion register without starting a new conversion.

Returns

dict Dict with the same fields as ``read()`` for the last started channel or differential pair.

ads1115.set_comparator(channel: int, high_threshold: int, low_threshold: int = None, latching: bool = None, active_high: bool = None, window: bool = None, queue: int = None) -> bool

Enable the ADS1115 comparator for one single-ended channel.

Threshold values are raw ADC counts, not volts. The comparator runs in continuous conversion mode after this call.

Parameters
Name Type Pass as Required Description
channel int positional or keyword Yes Single-ended ADC input channel. Use 0, 1, 2, or 3.
high_threshold int positional or keyword Yes Raw high threshold value from -32768 through 32767.
low_threshold int positional or keyword No Optional raw low threshold value. Defaults to 0.
latching bool positional or keyword No Optional latch mode. True keeps alert asserted until read.
active_high bool positional or keyword No Optional alert polarity. True makes ALERT/RDY active high.
window bool positional or keyword No Optional comparator mode. True uses window comparison, False uses traditional high-threshold comparison.
queue int positional or keyword No Optional comparator queue count. Use 1, 2, or 4.
Returns

bool True when threshold and config registers are written.

ads1115.disable_comparator() -> bool

Disable the ADS1115 comparator.

Returns

bool True when the comparator queue-disable bits are written.

ads1115.reset() -> bool

Restore the ADS1115 module defaults.

Returns

bool True when thresholds and the default config register are written.

ads1115.info() -> dict

Return ADS1115 module state.

Returns

dict Dict with initialization state, I2C settings, gain, full-scale range, data rate, mode, comparator state, and last selected channel or differential pair.