example(i2c): update example for configurability (#144)

* example(i2c): update example for configurability
* Remove unnecessary task
* Switch fmt::print to logger
* Allow menuconfig configuration of the device address, register address, and register size for the test

* readme: update

* doc: rebuild

* update to probe for all devices

* doc: rebuild

components/i2c/example/CMakeLists.txt

@@ -11,7 +11,7 @@ set(EXTRA_COMPONENT_DIRS
 
 set(
   COMPONENTS
-  "main esptool_py task i2c"
+  "main esptool_py i2c logger"
   CACHE STRING
   "List of components to include"
   )

components/i2c/example/README.md

@@ -3,12 +3,18 @@
 This example shows how to use the `I2C` component to communicate with
 peripherals on the I2C bus.
 
-It is currently designed to run on a QtPy ESP32, but (by changing the I2C pin
-definitions in the main file) can be reconfigured to run on any of the ESP32
-chips.
+It supports using `menuconfig` to configure
+* i2c pins (sda /scl), with configuration pre-selected for QtPy ESP32 PICO and QtPy ESP32s3
+* i2c device address
+* i2c device register address
+* Number of bytes to read from the i2c device register (register size)
 
 ## How to use example
 
+Configure the example via `menuconfig`:
+
+![CleanShot 2024-01-17 at 13 36 51](https://github.com/esp-cpp/espp/assets/213467/3ade0226-cf09-47cf-b601-22569a6da346)
+
 ### Hardware Required
 
 This example requires a connection (via I2C) to an I2C device.
@@ -29,3 +35,4 @@ See the Getting Started Guide for full steps to configure and use ESP-IDF to bui
 
 ## Example Output
 
+![CleanShot 2024-01-17 at 13 40 38](https://github.com/esp-cpp/espp/assets/213467/3865e661-eee4-4917-8460-25e7a0b87ae7)

components/i2c/example/main/Kconfig.projbuild

@@ -36,4 +36,25 @@ menu "Example Configuration"
         help
             GPIO number for I2C Master data line.
 
+    config EXAMPLE_I2C_DEVICE_ADDR
+        hex "I2C Device Address"
+        range 0x00 0x7F
+        default 0x3C
+        help
+            I2C device address of the device.
+
+    config EXAMPLE_I2C_DEVICE_REG_ADDR
+        hex "I2C Device Register Address"
+        range 0x00 0xFF
+        default 0x00
+        help
+            I2C device register address of the device.
+
+    config EXAMPLE_I2C_DEVICE_REG_SIZE
+        int "I2C Device Register Size"
+        range 1 100
+        default 1
+        help
+            I2C device register size of the device.
+
 endmenu

components/i2c/example/main/i2c_example.cpp

@@ -3,55 +3,48 @@
 #include <vector>
 
 #include "i2c.hpp"
-#include "task.hpp"
+#include "logger.hpp"
 
 using namespace std::chrono_literals;
 
 extern "C" void app_main(void) {
-  {
-    std::atomic<bool> quit_test = false;
-    fmt::print("Starting ft5x06 example, press select & start together to quit!\n");
-    //! [i2c example]
-    espp::I2c i2c({
-        .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,
+  espp::Logger logger({.tag = "I2C Example", .level = espp::Logger::Verbosity::INFO});
+  logger.info("Starting");
+  //! [i2c example]
+  espp::I2c i2c({
+      .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,
     });
-    // finally, make the task to periodically query the bus
-    auto task_fn = [&i2c](std::mutex &m, std::condition_variable &cv) {
-      static constexpr uint8_t device_address = 0x58;
-      static constexpr uint8_t register_address = 0x58;
-      bool device_found = i2c.probe_device(device_address);
-      if (device_found) {
-        fmt::print("Found device with address 0x{:#02x}\n", device_address);
-        uint8_t read_data[1];
-        bool success = i2c.read_at_register(device_address, register_address, read_data, 1);
-        if (success) {
-          fmt::print("read data: {:#04x}\n", read_data[0]);
-        } else {
-          fmt::print("read failed\n");
-        }
-      } else {
-        fmt::print("Could not find device with address 0x{:#02x}\n", device_address);
-      }
-      // NOTE: sleeping in this way allows the sleep to exit early when the
-      // task is being stopped / destroyed
-      {
-        std::unique_lock<std::mutex> lk(m);
-        cv.wait_for(lk, 500ms);
-      }
-      return false; // don't stop the task
-    };
-    auto task = espp::Task(
-        {.name = "I2c Task", .callback = task_fn, .log_level = espp::Logger::Verbosity::WARN});
-    task.start();
-    //! [i2c example]
-    while (!true) {
-      std::this_thread::sleep_for(100ms);
+
+  // probe the bus for all addresses and store the ones that were found /
+  // responded
+  std::vector<uint8_t> found_addresses;
+  for (uint8_t address = 0; address < 128; 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);
 
-  fmt::print("Ft5x06 example complete!\n");
+  static constexpr uint8_t device_address = CONFIG_EXAMPLE_I2C_DEVICE_ADDR;
+  static constexpr uint8_t register_address = CONFIG_EXAMPLE_I2C_DEVICE_REG_ADDR;
+  bool device_found = i2c.probe_device(device_address);
+  if (device_found) {
+    logger.info("Found device with address {:#02x}", device_address);
+    std::vector<uint8_t> read_data(CONFIG_EXAMPLE_I2C_DEVICE_REG_SIZE, 0);
+    bool success = i2c.read_at_register(device_address, register_address, read_data.data(), read_data.size());
+    if (success) {
+      logger.info("read data: {::#02x}", read_data);
+    } else {
+      logger.error("read failed");
+    }
+  } else {
+    logger.error("Could not find device with address {:#02x}", device_address);
+  }
+  //! [i2c example]
+  logger.info("I2C example complete!");
 
   while (true) {
     std::this_thread::sleep_for(1s);

docs/adc/adc_types.html

@@ -146,7 +146,7 @@
           <li><a href="index.html">ADC APIs</a> &raquo;</li>
       <li>ADC Types</li>
       <li class="wy-breadcrumbs-aside">
-              <a href="https://github.com/esp-cpp/espp/blob/289d326/docs/en/adc/adc_types.rst" class="fa fa-github"> Edit on GitHub</a>
+              <a href="https://github.com/esp-cpp/espp/blob/7cdf5bb/docs/en/adc/adc_types.rst" class="fa fa-github"> Edit on GitHub</a>
       </li>
   </ul>
   <hr/>
@@ -163,7 +163,7 @@ <h2>API Reference<a class="headerlink" href="#api-reference" title="Permalink to
 <section id="header-file">
 <h3>Header File<a class="headerlink" href="#header-file" title="Permalink to this headline"></a></h3>
 <ul class="simple">
-<li><p><a class="reference external" href="https://github.com/esp-cpp/espp/blob/57b5b0c/components/adc/include/adc_types.hpp">components/adc/include/adc_types.hpp</a></p></li>
+<li><p><a class="reference external" href="https://github.com/esp-cpp/espp/blob/56f7180/components/adc/include/adc_types.hpp">components/adc/include/adc_types.hpp</a></p></li>
 </ul>
 </section>
 </section>

docs/adc/ads1x15.html

@@ -147,7 +147,7 @@
           <li><a href="index.html">ADC APIs</a> &raquo;</li>
       <li>ADS1x15 I2C ADC</li>
       <li class="wy-breadcrumbs-aside">
-              <a href="https://github.com/esp-cpp/espp/blob/289d326/docs/en/adc/ads1x15.rst" class="fa fa-github"> Edit on GitHub</a>
+              <a href="https://github.com/esp-cpp/espp/blob/7cdf5bb/docs/en/adc/ads1x15.rst" class="fa fa-github"> Edit on GitHub</a>
       </li>
   </ul>
   <hr/>
@@ -164,7 +164,7 @@ <h2>API Reference<a class="headerlink" href="#api-reference" title="Permalink to
 <section id="header-file">
 <h3>Header File<a class="headerlink" href="#header-file" title="Permalink to this headline"></a></h3>
 <ul class="simple">
-<li><p><a class="reference external" href="https://github.com/esp-cpp/espp/blob/289d326/components/ads1x15/include/ads1x15.hpp">components/ads1x15/include/ads1x15.hpp</a></p></li>
+<li><p><a class="reference external" href="https://github.com/esp-cpp/espp/blob/7cdf5bb/components/ads1x15/include/ads1x15.hpp">components/ads1x15/include/ads1x15.hpp</a></p></li>
 </ul>
 </section>
 <section id="classes">

docs/adc/ads7138.html

@@ -147,7 +147,7 @@
           <li><a href="index.html">ADC APIs</a> &raquo;</li>
       <li>ADS7138 I2C ADC</li>
       <li class="wy-breadcrumbs-aside">
-              <a href="https://github.com/esp-cpp/espp/blob/289d326/docs/en/adc/ads7138.rst" class="fa fa-github"> Edit on GitHub</a>
+              <a href="https://github.com/esp-cpp/espp/blob/7cdf5bb/docs/en/adc/ads7138.rst" class="fa fa-github"> Edit on GitHub</a>
       </li>
   </ul>
   <hr/>
@@ -169,7 +169,7 @@ <h2>API Reference<a class="headerlink" href="#api-reference" title="Permalink to
 <section id="header-file">
 <h3>Header File<a class="headerlink" href="#header-file" title="Permalink to this headline"></a></h3>
 <ul class="simple">
-<li><p><a class="reference external" href="https://github.com/esp-cpp/espp/blob/289d326/components/ads7138/include/ads7138.hpp">components/ads7138/include/ads7138.hpp</a></p></li>
+<li><p><a class="reference external" href="https://github.com/esp-cpp/espp/blob/7cdf5bb/components/ads7138/include/ads7138.hpp">components/ads7138/include/ads7138.hpp</a></p></li>
 </ul>
 </section>
 <section id="classes">

docs/adc/continuous_adc.html

@@ -147,7 +147,7 @@
           <li><a href="index.html">ADC APIs</a> &raquo;</li>
       <li>Continuous ADC</li>
       <li class="wy-breadcrumbs-aside">
-              <a href="https://github.com/esp-cpp/espp/blob/289d326/docs/en/adc/continuous_adc.rst" class="fa fa-github"> Edit on GitHub</a>
+              <a href="https://github.com/esp-cpp/espp/blob/7cdf5bb/docs/en/adc/continuous_adc.rst" class="fa fa-github"> Edit on GitHub</a>
       </li>
   </ul>
   <hr/>
@@ -169,7 +169,7 @@ <h2>API Reference<a class="headerlink" href="#api-reference" title="Permalink to
 <section id="header-file">
 <h3>Header File<a class="headerlink" href="#header-file" title="Permalink to this headline"></a></h3>
 <ul class="simple">
-<li><p><a class="reference external" href="https://github.com/esp-cpp/espp/blob/289d326/components/adc/include/continuous_adc.hpp">components/adc/include/continuous_adc.hpp</a></p></li>
+<li><p><a class="reference external" href="https://github.com/esp-cpp/espp/blob/7cdf5bb/components/adc/include/continuous_adc.hpp">components/adc/include/continuous_adc.hpp</a></p></li>
 </ul>
 </section>
 <section id="classes">

docs/adc/index.html

@@ -139,7 +139,7 @@
       <li><a href="../index.html" class="icon icon-home"></a> &raquo;</li>
       <li>ADC APIs</li>
       <li class="wy-breadcrumbs-aside">
-              <a href="https://github.com/esp-cpp/espp/blob/289d326/docs/en/adc/index.rst" class="fa fa-github"> Edit on GitHub</a>
+              <a href="https://github.com/esp-cpp/espp/blob/7cdf5bb/docs/en/adc/index.rst" class="fa fa-github"> Edit on GitHub</a>
       </li>
   </ul>
   <hr/>

docs/adc/oneshot_adc.html

@@ -147,7 +147,7 @@
           <li><a href="index.html">ADC APIs</a> &raquo;</li>
       <li>Oneshot ADC</li>
       <li class="wy-breadcrumbs-aside">
-              <a href="https://github.com/esp-cpp/espp/blob/289d326/docs/en/adc/oneshot_adc.rst" class="fa fa-github"> Edit on GitHub</a>
+              <a href="https://github.com/esp-cpp/espp/blob/7cdf5bb/docs/en/adc/oneshot_adc.rst" class="fa fa-github"> Edit on GitHub</a>
       </li>
   </ul>
   <hr/>
@@ -168,7 +168,7 @@ <h2>API Reference<a class="headerlink" href="#api-reference" title="Permalink to
 <section id="header-file">
 <h3>Header File<a class="headerlink" href="#header-file" title="Permalink to this headline"></a></h3>
 <ul class="simple">
-<li><p><a class="reference external" href="https://github.com/esp-cpp/espp/blob/289d326/components/adc/include/oneshot_adc.hpp">components/adc/include/oneshot_adc.hpp</a></p></li>
+<li><p><a class="reference external" href="https://github.com/esp-cpp/espp/blob/7cdf5bb/components/adc/include/oneshot_adc.hpp">components/adc/include/oneshot_adc.hpp</a></p></li>
 </ul>
 </section>
 <section id="classes">

docs/adc/tla2528.html

@@ -147,7 +147,7 @@
           <li><a href="index.html">ADC APIs</a> &raquo;</li>
       <li>TLA2528 I2C ADC</li>
       <li class="wy-breadcrumbs-aside">
-              <a href="https://github.com/esp-cpp/espp/blob/289d326/docs/en/adc/tla2528.rst" class="fa fa-github"> Edit on GitHub</a>
+              <a href="https://github.com/esp-cpp/espp/blob/7cdf5bb/docs/en/adc/tla2528.rst" class="fa fa-github"> Edit on GitHub</a>
       </li>
   </ul>
   <hr/>
@@ -169,7 +169,7 @@ <h2>API Reference<a class="headerlink" href="#api-reference" title="Permalink to
 <section id="header-file">
 <h3>Header File<a class="headerlink" href="#header-file" title="Permalink to this headline"></a></h3>
 <ul class="simple">
-<li><p><a class="reference external" href="https://github.com/esp-cpp/espp/blob/289d326/components/tla2528/include/tla2528.hpp">components/tla2528/include/tla2528.hpp</a></p></li>
+<li><p><a class="reference external" href="https://github.com/esp-cpp/espp/blob/7cdf5bb/components/tla2528/include/tla2528.hpp">components/tla2528/include/tla2528.hpp</a></p></li>
 </ul>
 </section>
 <section id="classes">