feat(tla2528/ads7138): Add calibrate function to TLA2528 and ADS7138 (#413)

* feat(tla2528): Add `calibrate` function to `TLA2528`
* Add new calibrate function to TLA2528, with option to automatically calibrate on construction (default = false).
* Update example to better support hardware to test / show use of other TLA addresses - automatically finding the TLA on the I2C bus.
* Update example to test calibration function and print out the calibration time for reference.

Allows users to gain better precision in adc measurements by calibrating the sensor.

Build and run `tla2528/example` on ESP32-S3 with TLA2528 at address 0x16 on I2C pins 17,18.

* update example; apply change to ads7138 as well

Author: finger563

components/ads7138/example/main/ads7138_example.cpp

@@ -107,6 +107,14 @@ extern "C" void app_main(void) {
         .log_level = espp::Logger::Verbosity::WARN,
     });
 
+    // calibrate the ADC
+    std::error_code ec;
+    ads.calibrate(ec);
+    if (ec) {
+      logger.error("error calibrating: {}", ec.message());
+      return;
+    }
+
     // create the gpio event queue
     gpio_evt_queue = xQueueCreate(10, sizeof(uint32_t));
     // setup gpio interrupts for mute button
@@ -163,7 +171,6 @@ extern "C" void app_main(void) {
     });
     alert_task->start();
 
-    std::error_code ec;
     // configure the alert pin
     ads.configure_alert(espp::Ads7138::OutputMode::PUSH_PULL, espp::Ads7138::AlertLogic::ACTIVE_LOW,
                         ec);

components/ads7138/include/ads7138.hpp

@@ -153,6 +153,11 @@ class Ads7138 : public BasePeripheral<> {
     BasePeripheral::read_fn read;   ///< Function to read from the ADC
     bool auto_init = true;          ///< Automatically initialize the ADC on construction. If false,
                                     ///< initialize() must be called before any other functions.
+    bool auto_calibrate =
+        false; ///< Automatically calibrate the ADC on construction. If false, calibrate() should be
+               ///< called to increase the accuracy of the ADC.
+               ///< @note Can only be set to true if auto_init is also true, otherwise it will be
+               ///< ignored.
     espp::Logger::Verbosity log_level{espp::Logger::Verbosity::WARN}; ///< Verbosity for the logger.
   };
 
@@ -180,6 +185,13 @@ class Ads7138 : public BasePeripheral<> {
       initialize(ec);
       if (ec) {
         logger_.error("Error initializing ADC: {}", ec.message());
+        return;
+      }
+      if (config.auto_calibrate) {
+        calibrate(ec);
+        if (ec) {
+          logger_.error("Error calibrating ADC: {}", ec.message());
+        }
       }
     }
   }
@@ -194,6 +206,41 @@ class Ads7138 : public BasePeripheral<> {
    */
   void initialize(std::error_code &ec) { init(config_, ec); }
 
+  /// @brief Calibrate the ADC
+  ///        This function will set the calibration bit in the GENERAL_CFG register
+  ///        to start the calibration process and will wait for the calibration to
+  ///        complete (CAL bit in GENERAL_CFG register to be cleared).
+  /// @param ec Error code to set if an error occurs.
+  /// @param poll_interval The time to wait between polls for the calibration
+  ///        to complete.
+  /// @param timeout The time to wait for the calibration to complete before
+  ///        returning an error.
+  void calibrate(std::error_code &ec,
+                 std::chrono::milliseconds poll_interval = std::chrono::milliseconds(10),
+                 std::chrono::milliseconds timeout = std::chrono::milliseconds(100)) {
+    std::lock_guard<std::recursive_mutex> lock(base_mutex_);
+    logger_.info("Starting calibration");
+    set_bits_(Register::GENERAL_CFG, CAL, ec);
+    if (ec) {
+      return;
+    }
+    // wait for the calibration to complete
+    auto start_time = std::chrono::steady_clock::now();
+    while (read_one_(Register::GENERAL_CFG, ec) & CAL) {
+      std::this_thread::sleep_for(poll_interval);
+      if (ec) {
+        return;
+      }
+      auto now = std::chrono::steady_clock::now();
+      if (now - start_time > timeout) {
+        logger_.error("Calibration timed out");
+        ec = std::make_error_code(std::errc::timed_out);
+        return;
+      }
+    }
+    logger_.info("Calibration complete");
+  }
+
   /**
    * @brief Communicate with the ADC to get the analog value for the channel
    *        and return it.

components/tla2528/example/main/tla2528_example.cpp

@@ -1,3 +1,4 @@
+#include <algorithm>
 #include <chrono>
 #include <sdkconfig.h>
 #include <vector>
@@ -21,18 +22,53 @@ extern "C" void app_main(void) {
         .port = I2C_NUM_0,
         .sda_io_num = (gpio_num_t)CONFIG_EXAMPLE_I2C_SDA_GPIO,
         .scl_io_num = (gpio_num_t)CONFIG_EXAMPLE_I2C_SCL_GPIO,
+        .sda_pullup_en = GPIO_PULLUP_ENABLE,
+        .scl_pullup_en = GPIO_PULLUP_ENABLE,
     });
 
+    std::vector<uint8_t> found_addresses;
+    for (uint8_t address = 0; address < 128; address++) {
+      logger.debug("probing address {:#02x}", address);
+      if (i2c.probe_device(address)) {
+        found_addresses.push_back(address);
+      }
+    }
+    // print out the addresses that were found
+    logger.info("Found devices at addresses: {::#02x}", found_addresses);
+
+    if (found_addresses.size() == 0) {
+      logger.error("No devices found!");
+      return;
+    }
+
+    // make sure one of the TLA addresses is in the list, and use one if it was found
+    //
+    // NOTE: the TLA2528 has 8 addresses, so we need to check for them all
+    // 0x10, 0x11, 0x12, 0x13, 0x14, 0x15, 0x16, 0x17
+    //
+    // Example: Address pin is connected via 11k to ADC_DECAP, so the default
+    // address of 0x10 becomes 0x16: espp::Tla2528::DEFAULT_ADDRESS | 0x06
+    const std::vector<uint8_t> tla_addresses{0x10, 0x11, 0x12, 0x13, 0x14, 0x15, 0x16, 0x17};
+    uint8_t tla_address = 0;
+    auto it = std::find_first_of(tla_addresses.begin(), tla_addresses.end(),
+                                 found_addresses.begin(), found_addresses.end());
+    if (it != tla_addresses.end()) {
+      tla_address = *it;
+    } else {
+      logger.error("No TLA2528 found!");
+      return;
+    }
+
+    logger.info("Found TLA2528 at address {:#02x}", tla_address);
+
     static std::vector<espp::Tla2528::Channel> channels = {
         espp::Tla2528::Channel::CH0, espp::Tla2528::Channel::CH1, espp::Tla2528::Channel::CH2,
         espp::Tla2528::Channel::CH3, espp::Tla2528::Channel::CH4, espp::Tla2528::Channel::CH5,
         espp::Tla2528::Channel::CH6, espp::Tla2528::Channel::CH7};
 
     // make the actual tla class
     espp::Tla2528 tla(espp::Tla2528::Config{
-        // Address pin is connected via 11k to ADC_DECAP, so the default address
-        // of 0x10 becomes 0x16
-        .device_address = espp::Tla2528::DEFAULT_ADDRESS | 0x06,
+        .device_address = tla_address,
         .mode = espp::Tla2528::Mode::AUTO_SEQ,
         .analog_inputs = channels,
         .digital_inputs = {},
@@ -46,6 +82,20 @@ extern "C" void app_main(void) {
         .log_level = espp::Logger::Verbosity::WARN,
     });
 
+    // calibrate the ADC
+    //
+    // NOTE: this is not strictly necessary, but improves the accuracy of the
+    //       ADC.
+    auto cal_start_us = esp_timer_get_time();
+    std::error_code ec;
+    tla.calibrate(ec);
+    auto cal_end_us = esp_timer_get_time();
+    if (ec) {
+      logger.error("error calibrating TLA2528: {}", ec.message());
+      return;
+    }
+    logger.info("calibration took {} us", cal_end_us - cal_start_us);
+
     // make the task which will get the raw data from the I2C ADC
     fmt::print("%time (s), ntc (mV), x (mV), y (mV)\n");
     auto tla_read_task_fn = [&tla](std::mutex &m, std::condition_variable &cv) {

components/tla2528/include/tla2528.hpp

@@ -131,6 +131,11 @@ class Tla2528 : public BasePeripheral<> {
     BasePeripheral::read_fn read;   ///< Function to read from the ADC
     bool auto_init = true;          ///< Automatically initialize the ADC on construction. If false,
                                     ///< initialize() must be called before any other functions.
+    bool auto_calibrate =
+        false; ///< Automatically calibrate the ADC on construction. If false, calibrate() should be
+               ///< called to increase the accuracy of the ADC.
+               ///< @note Can only be set to true if auto_init is also true, otherwise it will be
+               ///< ignored.
     espp::Logger::Verbosity log_level{espp::Logger::Verbosity::WARN}; ///< Verbosity for the logger.
   };
 
@@ -162,6 +167,13 @@ class Tla2528 : public BasePeripheral<> {
       initialize(ec);
       if (ec) {
         logger_.error("Error initializing ADC: {}", ec.message());
+        return;
+      }
+      if (config.auto_calibrate) {
+        calibrate(ec);
+        if (ec) {
+          logger_.error("Error calibrating ADC: {}", ec.message());
+        }
       }
     }
   }
@@ -176,6 +188,41 @@ class Tla2528 : public BasePeripheral<> {
    */
   void initialize(std::error_code &ec) { init(config_, ec); }
 
+  /// @brief Calibrate the ADC
+  ///        This function will set the calibration bit in the GENERAL_CFG register
+  ///        to start the calibration process and will wait for the calibration to
+  ///        complete (CAL bit in GENERAL_CFG register to be cleared).
+  /// @param ec Error code to set if an error occurs.
+  /// @param poll_interval The time to wait between polls for the calibration
+  ///        to complete.
+  /// @param timeout The time to wait for the calibration to complete before
+  ///        returning an error.
+  void calibrate(std::error_code &ec,
+                 std::chrono::milliseconds poll_interval = std::chrono::milliseconds(10),
+                 std::chrono::milliseconds timeout = std::chrono::milliseconds(100)) {
+    std::lock_guard<std::recursive_mutex> lock(base_mutex_);
+    logger_.info("Starting calibration");
+    set_bits_(Register::GENERAL_CFG, CAL, ec);
+    if (ec) {
+      return;
+    }
+    // wait for the calibration to complete
+    auto start_time = std::chrono::steady_clock::now();
+    while (read_one_(Register::GENERAL_CFG, ec) & CAL) {
+      std::this_thread::sleep_for(poll_interval);
+      if (ec) {
+        return;
+      }
+      auto now = std::chrono::steady_clock::now();
+      if (now - start_time > timeout) {
+        logger_.error("Calibration timed out");
+        ec = std::make_error_code(std::errc::timed_out);
+        return;
+      }
+    }
+    logger_.info("Calibration complete");
+  }
+
   /**
    * @brief Communicate with the ADC to get the analog value for the channel
    *        and return it.