Merge branch 'feature/docs_update_sigmadelta_api' into 'master'

Updated sigma delta API documenation and example

See merge request !1319

diff --git a/components/driver/include/driver/sigmadelta.h b/components/driver/include/driver/sigmadelta.h
index 61a35c21f9139d28a3408f83ad09db52b92408c3..76237c193d3574fabb56969a0c11784d13b6e37a 100644 (file)
--- a/components/driver/include/driver/sigmadelta.h
+++ b/components/driver/include/driver/sigmadelta.h
@@ -27,14 +27,14 @@ extern "C" {
  * @brief Sigma-delta channel list
  */
 typedef enum{
-    SIGMADELTA_CHANNEL_0 = 0,         /*!< Sigma-delta channel0 */
-    SIGMADELTA_CHANNEL_1 = 1,         /*!< Sigma-delta channel1 */
-    SIGMADELTA_CHANNEL_2 = 2,         /*!< Sigma-delta channel2 */
-    SIGMADELTA_CHANNEL_3 = 3,         /*!< Sigma-delta channel3 */
-    SIGMADELTA_CHANNEL_4 = 4,         /*!< Sigma-delta channel4 */
-    SIGMADELTA_CHANNEL_5 = 5,         /*!< Sigma-delta channel5 */
-    SIGMADELTA_CHANNEL_6 = 6,         /*!< Sigma-delta channel6 */
-    SIGMADELTA_CHANNEL_7 = 7,         /*!< Sigma-delta channel7 */
+    SIGMADELTA_CHANNEL_0 = 0,         /*!< Sigma-delta channel 0 */
+    SIGMADELTA_CHANNEL_1 = 1,         /*!< Sigma-delta channel 1 */
+    SIGMADELTA_CHANNEL_2 = 2,         /*!< Sigma-delta channel 2 */
+    SIGMADELTA_CHANNEL_3 = 3,         /*!< Sigma-delta channel 3 */
+    SIGMADELTA_CHANNEL_4 = 4,         /*!< Sigma-delta channel 4 */
+    SIGMADELTA_CHANNEL_5 = 5,         /*!< Sigma-delta channel 5 */
+    SIGMADELTA_CHANNEL_6 = 6,         /*!< Sigma-delta channel 6 */
+    SIGMADELTA_CHANNEL_7 = 7,         /*!< Sigma-delta channel 7 */
     SIGMADELTA_CHANNEL_MAX,
 } sigmadelta_channel_t;
 
@@ -64,7 +64,8 @@ esp_err_t sigmadelta_config(const sigmadelta_config_t *config);
  *
  *        This function is used to set Sigma-delta channel duty,
  *        If you add a capacitor between the output pin and ground,
- *        the average output voltage Vdc = VDDIO / 256 * duty + VDDIO/2, VDDIO is power supply voltage.
+ *        the average output voltage will be Vdc = VDDIO / 256 * duty + VDDIO/2,
+ *        where VDDIO is the power supply voltage.
  *
  * @param channel Sigma-delta channel number
  * @param duty Sigma-delta duty of one channel, the value ranges from -128 to 127, recommended range is -90 ~ 90.

diff --git a/docs/api-reference/peripherals/sigmadelta.rst b/docs/api-reference/peripherals/sigmadelta.rst
index a70decea60d8154eb17f86902e32b4d73235867c..34d7c7aeb198d515a6d1c63b26873b7ef3365428 100644 (file)
--- a/docs/api-reference/peripherals/sigmadelta.rst
+++ b/docs/api-reference/peripherals/sigmadelta.rst
@@ -1,11 +1,25 @@
 Sigma-delta Modulation
 ======================
 
-Overview
---------
+Introduction
+------------
 
-ESP32 has a second-order sigma-delta modulation module.
-This driver configures the channels of the sigma-delta module.
+ESP32 has a second-order sigma-delta modulation module. This driver configures the channels of the sigma-delta module.
+
+Functionality Overview 
+----------------------
+
+There are eight independent sigma-delta modulation channels identified with :cpp:type:`sigmadelta_channel_t`. Each channel is capable to output the binary, hardware generated signal with the sigma-delta modulation.
+
+Selected channel should be set up by providing configuration parameters in :cpp:type:`sigmadelta_config_t` and then applying this configuration with :cpp:func:`sigmadelta_config`.
+
+Another option is to call individual functions, that will configure all required parameters one by one:
+
+* **Prescaler** of the sigma-delta generator - :cpp:func:`sigmadelta_set_prescale`
+* **Duty** of the output signal - :cpp:func:`sigmadelta_set_duty`
+* **GPIO pin** to output modulated signal - :cpp:func:`sigmadelta_set_pin`
+
+The range of the 'duty' input parameter of :cpp:func:`sigmadelta_set_duty` is from -128 to 127 (eight bit signed integer). If zero value is set, then the output signal's duty will be about 50%, see description of :cpp:func:`sigmadelta_set_duty`.
 
 Application Example
 -------------------
@@ -16,4 +30,3 @@ API Reference
 -------------
 
 .. include:: /_build/inc/sigmadelta.inc
-

diff --git a/examples/peripherals/sigmadelta/README.md b/examples/peripherals/sigmadelta/README.md
index e8cac2c87b8f5c4891e374c11fbf90b9525e75aa..669e65a0e5d25135ad56132f388d25697f8c5cdf 100644 (file)
--- a/examples/peripherals/sigmadelta/README.md
+++ b/examples/peripherals/sigmadelta/README.md
@@ -1,7 +1,7 @@
 # Example: sigma_delta modulation
 
-This example uses the sigma_delta output modulation driver to generate modulated output on a GPIO.
+This example uses the sigma-delta driver to generate modulated output on a GPIO.
 
 By default the GPIO output is 4, however you can edit this in the `sigmadelta_init()` function inside `main/sigmadelta_test.c`.
 
-If you connect an LED to the output GPIO, you will see it blinking slowly.
+If you connect a LED to the output GPIO, you will see it blinking slowly.

diff --git a/examples/peripherals/sigmadelta/main/sigmadelta_example_main.c b/examples/peripherals/sigmadelta/main/sigmadelta_example_main.c
index 5249d2dea76270470384e72c153ba68957d2ad32..594dbdb0c40688d67883326c98a2d9466790cf30 100644 (file)
--- a/examples/peripherals/sigmadelta/main/sigmadelta_example_main.c
+++ b/examples/peripherals/sigmadelta/main/sigmadelta_example_main.c
@@ -11,44 +11,44 @@
 #include "freertos/task.h"
 #include "esp_system.h"
 #include "driver/sigmadelta.h"
-
 /*
- * This test code intended to configure sigma-delta and set GPIO4 as signal output pin.
- * If you connect this GPIO4 with an LED, you will see the LED blinking slowly.
+ * This test code will configure sigma-delta and set GPIO4 as a signal output pin.
+ * If you connect this GPIO4 with a LED, you will see the LED blinking slowly.
  */
 
-/**
- * @brief Sigma-delta initialization.
+/*
+ * Configure and initialize the sigma delta modulation
+ * on channel 0 to output signal on GPIO4
  */
 static void sigmadelta_example_init(void)
 {
-   sigmadelta_config_t sigmadelta_cfg = {
-       /* Sigma-delta channel0*/
-       .channel = SIGMADELTA_CHANNEL_0,
-       /* Sigma-delta set duty 10*/
-       .sigmadelta_duty = 10,
-       /* Set prescale 30 */
-       .sigmadelta_prescale = 80,
-       /*select GPIO4 as output_io */
-       .sigmadelta_gpio = 4,
-     };
-   sigmadelta_config(&sigmadelta_cfg);
+    sigmadelta_config_t sigmadelta_cfg = {
+        .channel = SIGMADELTA_CHANNEL_0,
+        .sigmadelta_prescale = 80,
+        .sigmadelta_duty = 0,
+        .sigmadelta_gpio = 4,
+    };
+    sigmadelta_config(&sigmadelta_cfg);
 }
 
-/**
- * @brief Sigma-delta test to change duty of output signal.
+/*
+ *  Perform the sigma-delta modulation test
+ *  by changing the duty of the output signal.
  */
 void app_main()
 {
     sigmadelta_example_init();
+
     int8_t duty = 0;
     int inc = 1;
-    while(1) {
+    while (1) {
         sigmadelta_set_duty(SIGMADELTA_CHANNEL_0, duty);
-        /*by changing delay time, you can change the blink frequency of LED. */
+        /* By changing delay time, you can change the blink frequency of LED */
         vTaskDelay(10 / portTICK_PERIOD_MS);
 
         duty += inc;
-        if(duty == 127 || duty == -127) inc = (-1) * inc;
+        if (duty == 127 || duty == -127) {
+            inc = (-1) * inc;
+        }
     }
 }