Added LEDC basic PWM example

Changes on the ledc_init function
Review on the README, docs and example functions
Added how to set freq and duty on README
Fix on the ledc.rst docs in the App Example
Added new example reference in the Chinese docs

docs/en/api-reference/peripherals/ledc.rst

@@ -192,8 +192,9 @@ The duty resolution is normally set using :cpp:type:`ledc_timer_bit_t`. This enu
 Application Example
 -------------------
 
-The LEDC change duty cycle and fading control example: :example:`peripherals/ledc`.
+The LEDC change duty cycle and fading control example: :example:`peripherals/ledc/ledc_fade`.
 
+The LEDC basic example: :example:`peripherals/ledc/ledc_basic`.
 
 API Reference
 -------------

docs/zh_CN/api-reference/peripherals/ledc.rst

@@ -192,7 +192,9 @@ LED PWM 控制器 API 会在设定的频率和占空比分辨率超过 LED PWM
 应用实例
 -------------------
 
-LED PWM 改变占空比和渐变控制的实例请参照 :example:`peripherals/ledc`。
+使用 LEDC 改变占空比和渐变控制的实例请参照 :example:`peripherals/ledc/ledc_fade`。
+
+使用 LEDC 基本实例请参照 :example:`peripherals/ledc/ledc_basic`。
 
 
 API 参考

examples/peripherals/ledc/ledc_basic/Makefile

@@ -0,0 +1,8 @@
+#
+# This is a project Makefile. It is assumed the directory this Makefile resides in is a
+# project subdirectory.
+#
+
+PROJECT_NAME := ledc_basic
+
+include $(IDF_PATH)/make/project.mk

examples/peripherals/ledc/ledc_basic/README.md

@@ -0,0 +1,79 @@
+# _LEDC Basic Example_
+
+(See the README.md file in the upper level 'examples' directory for more information about examples.)
+
+This example shows how to use the LEDC to generate a PWM signal using the `LOW SPEED` mode.
+To use `HIGH SPEED` mode check if the selected SoC supports this mode.
+
+## How to use example
+
+### Hardware Required
+
+* A development board with ESP32, ESP32-S2, ESP32-C3 or ESP32-S3 SoC (e.g., ESP32-DevKitC, ESP-WROVER-KIT, etc.)
+* A USB cable for power supply and programming
+
+Connect the GPIO to an oscilloscope to see the generated signal:
+
+|ledc channel| GPIO  |
+|:----------:|:-----:|
+| Channel 0  | GPIO5 |
+
+### Configure the project
+
+The example uses fixed PWM frequency of 5 kHz, duty cycle in 50%, and output GPIO pin. To change them, adjust `LEDC_FREQUENCY`, `LEDC_DUTY`, `LEDC_OUTPUT_IO` macros at the top of ledc_basic_example_main.c.
+
+Depending on the selected `LEDC_FREQUENCY`, you will need to change the `LEDC_DUTY_RES`.
+
+To dinamicaly set the duty and frequency, you can use the following functions:
+
+To set the frequency to 2.5 kHZ i.e:
+
+```c
+ledc_set_freq(LEDC_MODE, LEDC_TIMER, 2500);
+```
+
+Now the duty to 100% i.e:
+
+```c
+ledc_set_duty(LEDC_MODE, LEDC_CHANNEL, 8191);
+ledc_update_duty(LEDC_MODE, LEDC_CHANNEL);
+```
+
+To change the duty cycle you need to calculate the duty range according to the duty resolution.
+
+If duty resolution is 13 bits:
+
+Duty range: `0 to (2 ** 13) - 1 = 8191` where 0 is 0% and 8191 is 100%.
+
+### Build and Flash
+
+* [ESP-IDF Getting Started Guide](https://idf.espressif.com/)
+
+Build the project and flash it to the board, then run monitor tool to view serial output:
+
+```bash
+idf.py -p PORT flash monitor
+```
+
+(To exit the serial monitor, type ``Ctrl-]``.)
+
+See the Getting Started Guide for full steps to configure and use ESP-IDF to build projects.
+
+## Example Output
+
+Running this example, you will see the PWM signal with a duty cycle of 50%.
+
+![PWM](image/ledc_pwm_signal.png)
+
+## Troubleshooting
+
+* Duty Resolution
+
+    * If you get the following error log `ledc: requested frequency and duty resolution can not be achieved, try reducing freq_hz or duty_resolution.` you need to change the `LEDC_DUTY_RES` to a lower resolution and change the range of the duty.
+
+* Programming fail
+
+    * Hardware connection is not correct: run `idf.py -p PORT monitor`, and reboot your board to see if there are any output logs.
+    * The baud rate for downloading is too high: lower your baud rate in the `menuconfig` menu, and try again.
+
+For any technical queries, please open an [issue](https://github.com/espressif/esp-idf/issues) on GitHub. We will get back to you soon.

examples/peripherals/ledc/ledc_basic/main/CMakeLists.txt

@@ -0,0 +1,2 @@
+idf_component_register(SRCS "ledc_basic_example_main.c"
+                    INCLUDE_DIRS ".")

examples/peripherals/ledc/ledc_basic/main/ledc_basic_example_main.c

@@ -0,0 +1,54 @@
+/* LEDC (LED Controller) basic example
+
+   This example code is in the Public Domain (or CC0 licensed, at your option.)
+
+   Unless required by applicable law or agreed to in writing, this
+   software is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
+   CONDITIONS OF ANY KIND, either express or implied.
+*/
+#include <stdio.h>
+#include "driver/ledc.h"
+#include "esp_err.h"
+
+#define LEDC_TIMER              LEDC_TIMER_0
+#define LEDC_MODE               LEDC_LOW_SPEED_MODE
+#define LEDC_OUTPUT_IO          (5) // Define the output GPIO
+#define LEDC_CHANNEL            LEDC_CHANNEL_0
+#define LEDC_DUTY_RES           LEDC_TIMER_13_BIT // Set duty resolution to 13 bits
+#define LEDC_DUTY               (4095) // Set duty to 50%. ((2 ** 13) - 1) * 50% = 4095
+#define LEDC_FREQUENCY          (5000) // Frequency in Hertz. Set frequency at 5 kHz
+
+static void example_ledc_init(void)
+{
+    // Prepare and then apply the LEDC PWM timer configuration
+    ledc_timer_config_t ledc_timer = {
+        .speed_mode       = LEDC_MODE,
+        .timer_num        = LEDC_TIMER,
+        .duty_resolution  = LEDC_DUTY_RES,
+        .freq_hz          = LEDC_FREQUENCY,  // Set output frequency at 5 kHz
+        .clk_cfg          = LEDC_AUTO_CLK
+    };
+    ESP_ERROR_CHECK(ledc_timer_config(&ledc_timer));
+
+    // Prepare and then apply the LEDC PWM channel configuration
+    ledc_channel_config_t ledc_channel = {
+        .speed_mode     = LEDC_MODE,
+        .channel        = LEDC_CHANNEL,
+        .timer_sel      = LEDC_TIMER,
+        .intr_type      = LEDC_INTR_DISABLE,
+        .gpio_num       = LEDC_OUTPUT_IO,
+        .duty           = 0, // Set duty to 0%
+        .hpoint         = 0
+    };
+    ESP_ERROR_CHECK(ledc_channel_config(&ledc_channel));
+}
+
+void app_main(void)
+{
+    // Set the LEDC peripheral configuration
+    example_ledc_init();
+    // Set duty to 50%
+    ESP_ERROR_CHECK(ledc_set_duty(LEDC_MODE, LEDC_CHANNEL, LEDC_DUTY));
+    // Update duty to apply the new value
+    ESP_ERROR_CHECK(ledc_update_duty(LEDC_MODE, LEDC_CHANNEL));
+}

examples/peripherals/ledc/ledc_fade/CMakeLists.txt

@@ -0,0 +1,6 @@
+# The following lines of boilerplate have to be in your project's CMakeLists
+# in this exact order for cmake to work correctly
+cmake_minimum_required(VERSION 3.5)
+
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+project(ledc_fade)

examples/peripherals/ledc/Makefile → examples/peripherals/ledc/ledc_fade/Makefile

@@ -3,6 +3,6 @@
 # project subdirectory.
 #
 
-PROJECT_NAME := ledc
+PROJECT_NAME := ledc_fade
 
 include $(IDF_PATH)/make/project.mk

examples/peripherals/ledc/README.md → examples/peripherals/ledc/ledc_fade/README.md

@@ -1,4 +1,4 @@
-# _LEDC Example_
+# _LEDC Fade Example_
 
 (See the README.md file in the upper level 'examples' directory for more information about examples.)
 
@@ -28,6 +28,10 @@ idf.py menuconfig
 
 ### Build and Flash
 
+* [ESP-IDF Getting Started Guide on ESP32](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/get-started/index.html)
+* [ESP-IDF Getting Started Guide on ESP32-S2](https://docs.espressif.com/projects/esp-idf/en/latest/esp32s2/get-started/index.html)
+* [ESP-IDF Getting Started Guide on ESP32-C3](https://docs.espressif.com/projects/esp-idf/en/latest/esp32c3/get-started/index.html)
+
 Build the project and flash it to the board, then run monitor tool to view serial output:
 
 ```
@@ -64,4 +68,4 @@ you can also see the following output log on the serial monitor:
     * Hardware connection is not correct: run `idf.py -p PORT monitor`, and reboot your board to see if there are any output logs.
     * The baud rate for downloading is too high: lower your baud rate in the `menuconfig` menu, and try again.
 
-For any technical queries, please open an [issue] (https://github.com/espressif/esp-idf/issues) on GitHub. We will get back to you soon.
+For any technical queries, please open an [issue](https://github.com/espressif/esp-idf/issues) on GitHub. We will get back to you soon.

examples/peripherals/ledc/ledc_fade/main/CMakeLists.txt

@@ -0,0 +1,2 @@
+idf_component_register(SRCS "ledc_fade_example_main.c"
+                    INCLUDE_DIRS ".")

examples/peripherals/ledc/ledc_fade/main/component.mk

@@ -0,0 +1,3 @@
+#
+# Main Makefile. This is basically the same as a component makefile.
+#

examples/peripherals/ledc/main/CMakeLists.txt

@@ -1,2 +0,0 @@
-idf_component_register(SRCS "ledc_example_main.c"
-                    INCLUDE_DIRS ".")