From b5e4c76bfe199d9048f0460c87174bbaf73b1689 Mon Sep 17 00:00:00 2001 From: krzychb Date: Mon, 25 Sep 2017 21:20:48 +0200 Subject: [PATCH] Updated sigma delta API documenation and example --- components/driver/include/driver/sigmadelta.h | 19 +++++---- docs/api-reference/peripherals/sigmadelta.rst | 23 +++++++--- examples/peripherals/sigmadelta/README.md | 4 +- .../sigmadelta/main/sigmadelta_example_main.c | 42 +++++++++---------- 4 files changed, 51 insertions(+), 37 deletions(-) diff --git a/components/driver/include/driver/sigmadelta.h b/components/driver/include/driver/sigmadelta.h index 61a35c21f9..76237c193d 100644 --- 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 a70decea60..34d7c7aeb1 100644 --- 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 e8cac2c87b..669e65a0e5 100644 --- 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 5249d2dea7..594dbdb0c4 100644 --- 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; + } } } -- 2.40.0