Merge branch 'example/ledc_pwm_basic' into 'master'

Example: Added LEDC basic PWM example

Closes DO-70

See merge request espressif/esp-idf!13114

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/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/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 ".")