Feature/oneshot adc read all (#162)

* feat(adc): Add new read_all_mv API to OneshotAdc

* Update how docs are built

* update metadoc

* doc: rebuild

Author: finger563

.gitignore

@@ -44,3 +44,5 @@ dependencies.lock
 # weird mac folders...
 .DS_Store
 lib/pc
+_build/
+__pycache__/

README.md

@@ -2,7 +2,7 @@
 
 This is the repository for some c++ components developed for the [ESP-IDF](https://github.com/espressif/esp-idf) farmework.
 
- * [Documentation](https://esp-cpp.github.io/espp/) - github hosted version of the documentation found in [./docs](./docs), which is built by running [./doc/build_docs.sh](./doc/build_docs.sh).
+ * [Documentation](https://esp-cpp.github.io/espp/) - github hosted version of the documentation found in [./docs](./docs), which is built by running [./build_docs.sh](./build_docs.sh). NOTE: to ensure proper build environments, the documentation build now relies on docker, so you'll need to run `docker build -t esp-docs doc` once before running `build_docs.sh`.
 
 Many components in this repo contain example code (referenced in the documentation above) that shows some basic usage. This example code can be found in that component's `example` directory. NOTE: many component examples also make use of other components (esp. some of the foundational components such as `format`, `logger`, and `task`.
 

build_docs.sh

@@ -0,0 +1,4 @@
+#!/bin/sh
+# NOTE: ensure you've built the docker image first by running
+#   `docker build -t esp-docs doc`
+docker run --rm -v $PWD:/project -w /project -u $UID -e HOME=/tmp esp-docs ./docker_build_docs.sh

components/adc/example/main/adc_example.cpp

@@ -22,14 +22,26 @@ extern "C" void app_main(void) {
         .channels = channels,
     });
     auto task_fn = [&adc, &channels](std::mutex &m, std::condition_variable &cv) {
-      for (auto &conf : channels) {
-        auto maybe_mv = adc.read_mv(conf);
-        if (maybe_mv.has_value()) {
-          fmt::print("{}: {} mV\n", conf, maybe_mv.value());
-        } else {
-          fmt::print("{}: no value!\n", conf);
+      static bool use_individual_functions = false;
+      if (use_individual_functions) {
+        // this iteration, we'll use the read_mv function for each channel
+        for (auto &conf : channels) {
+          auto maybe_mv = adc.read_mv(conf);
+          if (maybe_mv.has_value()) {
+            fmt::print("{}: {} mV\n", conf, maybe_mv.value());
+          } else {
+            fmt::print("{}: no value!\n", conf);
+          }
+        }
+      } else {
+        // this iteration, we'll use the read_all_mv function to read all
+        // configured channels
+        auto voltages = adc.read_all_mv();
+        for (const auto &mv : voltages) {
+          fmt::print("{} mV\n", mv);
         }
       }
+      use_individual_functions = !use_individual_functions;
       // NOTE: sleeping in this way allows the sleep to exit early when the
       // task is being stopped / destroyed
       {

components/adc/include/oneshot_adc.hpp

@@ -65,6 +65,30 @@ class OneshotAdc : public BaseComponent {
     }
   }
 
+  /**
+   * @brief Take a new ADC reading for all configured channels and convert it to
+   *        voltage (mV) if the unit was properly calibrated. If it was not
+   *        properly calibrated, then it will return the same value as \c
+   *        read_raw().
+   * @return std::vector<float> Voltage in mV for all configured channels (if
+   *         they were configured).
+   */
+  std::vector<int> read_all_mv() {
+    std::vector<int> values;
+    values.reserve(configs_.size());
+    for (const auto &config : configs_) {
+      int raw = 0;
+      auto err = adc_oneshot_read(adc_handle_, config.channel, &raw);
+      if (err != ESP_OK) {
+        logger_.error("Couldn't read oneshot: {} - '{}'", err, esp_err_to_name(err));
+        values.push_back(0);
+      } else {
+        values.push_back(raw_to_mv(raw));
+      }
+    }
+    return values;
+  }
+
   /**
    * @brief Take a new ADC reading for the provided \p config.
    * @param config The channel configuration to take a reading from.

components/adc/src/continuous_adc.cpp

@@ -0,0 +1,14 @@
+# esp-docs doesn't currently support 3.12 (see https://github.com/espressif/esp-docs/issues/9)
+FROM python:3.11
+
+WORKDIR /usr/src/app
+
+# update apt-get
+RUN apt-get update
+
+# install doxygen
+RUN apt-get install -y doxygen
+
+COPY requirements.txt ./
+
+RUN pip install --no-cache-dir -r requirements.txt

doc/Dockerfile

@@ -9,4 +9,7 @@ For more information please see [ESP Docs](https://github.com/espressif/esp-docs
  - [API Documentation Template](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/template.html)
  - [ESP-DOCS Add-Ons and Extensions Reference](https://github.com/espressif/esp-docs/blob/master/docs/add-ons-reference.md) 
 
-to build the documentation, simply run `./build_docs.sh`.
+
+1. To ensure you can build the documentation, create a docker image for building the documentation  `docker build -t esp-docs .` (from within this directory) or `docker build -t esp-docs doc` from within the top-level project / espp directory.
+
+2. To build the documentation, simply run `./build_docs.sh` from within the top-level project / espp directory.

doc/README.md

@@ -0,0 +1,14 @@
+# This is a list of python packages used to generate documentation. This file is used with pip:
+# pip install --user -r requirements.txt
+#
+cairosvg
+
+# we have to pin these versions or we get a "this project needs sphinx v5.0" error
+# see https://github.com/sphinx-doc/sphinx/issues/11890
+sphinxcontrib-applehelp==1.0.4
+sphinxcontrib-devhelp==1.0.2
+sphinxcontrib-htmlhelp==2.0.1
+sphinxcontrib-qthelp==1.0.3
+sphinxcontrib-serializinghtml==1.1.5
+
+esp-docs==1.4.0

doc/build_docs.sh

@@ -0,0 +1,9 @@
+#!/bin/sh
+# add doc to the python path
+export PYTHONPATH=$PYTHONPATH:/project/doc
+# ensure we can run git commands
+git config --global --add safe.directory /project
+# build the docs
+build-docs -t esp32 -l en --project-path /project/ --source-dir /project/doc/ --doxyfile_dir /project/doc/
+# copy the docs to the docs folder
+cp -rf /project/_build/en/esp32/html/* /project/docs/.

doc/requirements.txt

@@ -150,7 +150,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/fb7442bb/docs/en/adc/adc_types.rst" class="fa fa-github"> Edit on GitHub</a>
+              <a href="https://github.com/esp-cpp/espp/blob/a3878d6f/docs/en/adc/adc_types.rst" class="fa fa-github"> Edit on GitHub</a>
       </li>
   </ul>
   <hr/>
@@ -167,7 +167,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/e14a4b5/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/f6a9c216/components/adc/include/adc_types.hpp">components/adc/include/adc_types.hpp</a></p></li>
 </ul>
 </section>
 </section>