ADS1x15 I2C ADC

The ADS1x15 provides a class for communicating with the ADS1x15 (ADS1015 and ADS1115) family of I2C ADC chips with configurable gain and sampling rate.

Ads1x15 Example
- How to use example
  - Build and Flash
- Example Output

API Reference

Header File

components/ads1x15/include/ads1x15.hpp

Classes

class Ads1x15 : public espp::BasePeripheral<>

Class for reading values from the ADS1x15 family of ADC chips.

ADS1X15 Example

    // make the I2C that we'll use to communicate
    espp::I2c i2c({
        .port = I2C_NUM_1,
        .sda_io_num = (gpio_num_t)CONFIG_EXAMPLE_I2C_SDA_GPIO, // pin 3 on the joybonnet
        .scl_io_num = (gpio_num_t)CONFIG_EXAMPLE_I2C_SCL_GPIO, // pin 5 on the joybonnet
    });
    // make the actual ads class
    espp::Ads1x15 ads(espp::Ads1x15::Ads1015Config{
        .device_address = espp::Ads1x15::DEFAULT_ADDRESS,
        .write = [&i2c](uint8_t addr, const uint8_t *data,
                        size_t len) { return i2c.write(addr, data, len); },
        .read = [&i2c](uint8_t addr, uint8_t *data,
                       size_t len) { return i2c.read(addr, data, len); },
    });
    // make the task which will get the raw data from the I2C ADC
    auto ads_read_task_fn = [&ads](std::mutex &m, std::condition_variable &cv) {
      static auto start = std::chrono::high_resolution_clock::now();
      auto now = std::chrono::high_resolution_clock::now();
      auto elapsed = std::chrono::duration<float>(now - start).count();
      std::error_code ec;
      auto x_mv = ads.sample_mv(1, ec); // channel 1
      if (ec) {
        logger.error("error reading channel 1: {}", ec.message());
        return false;
      }
      auto y_mv = ads.sample_mv(0, ec); // channel 0
      if (ec) {
        logger.error("error reading channel 0: {}", ec.message());
        return false;
      }
      logger.info("{:.3f}, {:.3f}, {:.3f}", elapsed, x_mv, y_mv);
      // NOTE: sleeping in this way allows the sleep to exit early when the
      // task is being stopped / destroyed
      {
        using namespace std::chrono_literals;
        std::unique_lock<std::mutex> lk(m);
        cv.wait_for(lk, 200ms);
      }
      // we don't want to stop, so return false
      return false;
    };
    auto ads_task = espp::Task::make_unique({.callback = ads_read_task_fn,
                                             .task_config =
                                                 {
                                                     .name = "ADS",
                                                     .stack_size_bytes{4 * 1024},
                                                 },
                                             .log_level = espp::Logger::Verbosity::INFO});
    ads_task->start();

Public Types

enum class Gain

Gain values for the ADC conversion.

Values:

enumerator TWOTHIRDS: +/-6.144V range = Gain 2/3

enumerator ONE: +/-4.096V range = Gain 1

enumerator TWO: +/-2.048V range = Gain 2 (default)

enumerator FOUR: +/-1.024V range = Gain 4

enumerator EIGHT: +/-0.512V range = Gain 8

enumerator SIXTEEN: +/-0.256V range = Gain 16

enum class Ads1015Rate : uint16_t

Sampling rates for the ADS1015 chips.

Values:

enumerator SPS128: 128 samples per second

enumerator SPS250: 250 samples per second

enumerator SPS490: 490 samples per second

enumerator SPS920: 920 samples per second

enumerator SPS1600: 1600 samples per second (default)

enumerator SPS2400: 2400 samples per second

enumerator SPS3300: 3300 samples per second

enum class Ads1115Rate : uint16_t

Sampling rates for the ADS1115 chips.

Values:

enumerator SPS8: 8 samples per second

enumerator SPS16: 16 samples per second

enumerator SPS32: 32 samples per second

enumerator SPS64: 64 samples per second

enumerator SPS128: 128 samples per second (default)

enumerator SPS250: 250 samples per second

enumerator SPS475: 475 samples per second

enumerator SPS860: 860 samples per second

typedef std::function<bool(uint8_t)> probe_fn

Function to probe the peripheral

Param address: The address to probe
Return: True if the peripheral is found at the given address

Public Functions

inline explicit Ads1x15(const Ads1015Config &config)

Construct Ads1x15 specficially for ADS1015.

Parameters: config – Configuration structure.

inline explicit Ads1x15(const Ads1115Config &config)

Construct Ads1x15 specficially for ADS1115.

Parameters: config – Configuration structure.

inline float sample_mv(int channel, std::error_code &ec)

Communicate with the ADC to sample the channel and return the sampled value.

Parameters

channel – Which channel of the ADC to sample
ec – Error code to set if there is an error.

Returns

The voltage (in mV) sampled on the channel.

inline bool probe (std::error_code &ec) requires(UseAddress)

Probe the peripheral

Note

This function is thread safe

Note

If the probe function is not set, this function will return false and set the error code to operation_not_supported

Note

This function is only available if UseAddress is true

Parameters: ec – The error code to set if there is an error
Returns: True if the peripheral is found

inline void set_address (uint8_t address) requires(UseAddress)

Set the address of the peripheral

Note

This function is thread safe

Note

This function is only available if UseAddress is true

Parameters: address – The address of the peripheral

inline void set_probe (const probe_fn &probe) requires(UseAddress)

Set the probe function

Note

This function is thread safe

Note

This should rarely be used, as the probe function is usually set in the constructor. If you need to change the probe function, consider using the set_config function instead.

Note

This function is only available if UseAddress is true

Parameters: probe – The probe function

inline void set_write(const write_fn &write)

Set the write function

Note

This function is thread safe

Note

This should rarely be used, as the write function is usually set in the constructor. If you need to change the write function, consider using the set_config function instead.

Parameters: write – The write function

inline void set_read(const read_fn &read)

Set the read function

Note

This function is thread safe

Note

This should rarely be used, as the read function is usually set in the constructor. If you need to change the read function, consider using the set_config function instead.

Parameters: read – The read function

inline void set_read_register(const read_register_fn &read_register)

Set the read register function

Note

This function is thread safe

Note

This should rarely be used, as the read register function is usually set in the constructor. If you need to change the read register function, consider using the set_config function instead.

Parameters: read_register – The read register function

inline void set_write_then_read(const write_then_read_fn &write_then_read)

Set the write then read function

Note

This function is thread safe

Note

This should rarely be used, as the write then read function is usually set in the constructor. If you need to change the write then

Parameters: write_then_read – The write then read function

inline void set_separate_write_then_read_delay(const std::chrono::milliseconds &delay)

Set the delay between the write and read operations in write_then_read

Note

This function is thread safe

Note

This should rarely be used, as the delay is usually set in the constructor. If you need to change the delay, consider using the set_config function instead.

Note

This delay is only used if the write_then_read function is not set to a custom function and the write and read functions are separate functions.

Parameters: delay – The delay between the write and read operations in write_then_read

inline void set_config(const Config &config)

Set the configuration for the peripheral

Note

This function is thread safe

Note

The configuration should normally be set in the constructor, but this function can be used to change the configuration after the peripheral has been created - for instance if the peripheral could be found on different communications buses.

Parameters: config – The configuration for the peripheral

inline void set_config(Config &&config)

Set the configuration for the peripheral

Note

This function is thread safe

Note

The configuration should normally be set in the constructor, but this function can be used to change the configuration after the peripheral has been created - for instance if the peripheral could be found on different communications buses.

Parameters: config – The configuration for the peripheral

inline const std::string &get_name() const

Get the name of the component

Note

This is the tag of the logger

Returns: A const reference to the name of the component

inline void set_log_tag(const std::string_view &tag)

Set the tag for the logger

Parameters: tag – The tag to use for the logger

inline espp::Logger::Verbosity get_log_level() const

Get the log level for the logger

See also

Logger::Verbosity

See also

Logger::set_verbosity

Returns: The verbosity level of the logger

inline void set_log_level(espp::Logger::Verbosity level)

Set the log level for the logger

See also

Logger::Verbosity

See also

Logger::set_verbosity

Parameters: level – The verbosity level to use for the logger

inline void set_log_verbosity(espp::Logger::Verbosity level)

Set the log verbosity for the logger

See also

set_log_level

See also

Logger::Verbosity

See also

Logger::set_verbosity

Note

This is a convenience method that calls set_log_level

Parameters: level – The verbosity level to use for the logger

inline espp::Logger::Verbosity get_log_verbosity() const

Get the log verbosity for the logger

See also

get_log_level

See also

Logger::Verbosity

See also

Logger::get_verbosity

Note

This is a convenience method that calls get_log_level

Returns: The verbosity level of the logger

inline void set_log_rate_limit(std::chrono::duration<float> rate_limit)

Set the rate limit for the logger

See also

Logger::set_rate_limit

Note

Only calls to the logger that have _rate_limit suffix will be rate limited

Parameters: rate_limit – The rate limit to use for the logger

Public Static Attributes

static constexpr uint8_t DEFAULT_ADDRESS = (0x48): I2C address of the ADS1x15 chips.

struct Ads1015Config

Configuration for ADS1015 ADC.

Public Members

uint8_t device_address = DEFAULT_ADDRESS : I2C address of the device.

BasePeripheral::write_fn write: Function to write to the ADC.

BasePeripheral::read_fn read: Function to read from the ADC.

Gain gain = {Gain::TWOTHIRDS}: Gain for the ADC.

Ads1015Rate sample_rate = {Ads1015Rate::SPS1600}: Sample rate for the ADC.

espp::Logger::Verbosity log_level = {espp::Logger::Verbosity::WARN}: Verbosity for the logger.

struct Ads1115Config

Configuration for ADS1115 ADC.

Public Members

uint8_t device_address = DEFAULT_ADDRESS : I2C address of the device.

BasePeripheral::write_fn write: Function to write to the ADC.

BasePeripheral::read_fn read: Function to read from the ADC.

Gain gain = {Gain::TWOTHIRDS}: Gain for the ADC.

Ads1115Rate sample_rate = {Ads1115Rate::SPS128}: Sample rate for the ADC.

espp::Logger::Verbosity log_level = {espp::Logger::Verbosity::WARN}: Verbosity for the logger.