diff --git a/docs/en/api-reference/peripherals/ledc.rst b/docs/en/api-reference/peripherals/ledc.rst index f85d4f1ccf..dcda4b7719 100644 --- a/docs/en/api-reference/peripherals/ledc.rst +++ b/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 ------------- diff --git a/docs/zh_CN/api-reference/peripherals/ledc.rst b/docs/zh_CN/api-reference/peripherals/ledc.rst index 7695c59eca..fcf197218a 100644 --- a/docs/zh_CN/api-reference/peripherals/ledc.rst +++ b/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 参考 diff --git a/examples/peripherals/ledc/CMakeLists.txt b/examples/peripherals/ledc/ledc_basic/CMakeLists.txt similarity index 100% rename from examples/peripherals/ledc/CMakeLists.txt rename to examples/peripherals/ledc/ledc_basic/CMakeLists.txt diff --git a/examples/peripherals/ledc/ledc_basic/Makefile b/examples/peripherals/ledc/ledc_basic/Makefile new file mode 100644 index 0000000000..63e461d010 --- /dev/null +++ b/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 diff --git a/examples/peripherals/ledc/ledc_basic/README.md b/examples/peripherals/ledc/ledc_basic/README.md new file mode 100644 index 0000000000..6412eda2e1 --- /dev/null +++ b/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. diff --git a/examples/peripherals/ledc/ledc_basic/image/ledc_pwm_signal.png b/examples/peripherals/ledc/ledc_basic/image/ledc_pwm_signal.png new file mode 100644 index 0000000000..31a77974fa Binary files /dev/null and b/examples/peripherals/ledc/ledc_basic/image/ledc_pwm_signal.png differ diff --git a/examples/peripherals/ledc/ledc_basic/main/CMakeLists.txt b/examples/peripherals/ledc/ledc_basic/main/CMakeLists.txt new file mode 100644 index 0000000000..04207465b2 --- /dev/null +++ b/examples/peripherals/ledc/ledc_basic/main/CMakeLists.txt @@ -0,0 +1,2 @@ +idf_component_register(SRCS "ledc_basic_example_main.c" + INCLUDE_DIRS ".") diff --git a/examples/peripherals/ledc/main/component.mk b/examples/peripherals/ledc/ledc_basic/main/component.mk similarity index 100% rename from examples/peripherals/ledc/main/component.mk rename to examples/peripherals/ledc/ledc_basic/main/component.mk diff --git a/examples/peripherals/ledc/ledc_basic/main/ledc_basic_example_main.c b/examples/peripherals/ledc/ledc_basic/main/ledc_basic_example_main.c new file mode 100644 index 0000000000..f4f97b7200 --- /dev/null +++ b/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 +#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)); +} diff --git a/examples/peripherals/ledc/ledc_fade/CMakeLists.txt b/examples/peripherals/ledc/ledc_fade/CMakeLists.txt new file mode 100644 index 0000000000..be4cb22e48 --- /dev/null +++ b/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) diff --git a/examples/peripherals/ledc/Makefile b/examples/peripherals/ledc/ledc_fade/Makefile similarity index 85% rename from examples/peripherals/ledc/Makefile rename to examples/peripherals/ledc/ledc_fade/Makefile index b198310347..b4c762786d 100644 --- a/examples/peripherals/ledc/Makefile +++ b/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 diff --git a/examples/peripherals/ledc/README.md b/examples/peripherals/ledc/ledc_fade/README.md similarity index 74% rename from examples/peripherals/ledc/README.md rename to examples/peripherals/ledc/ledc_fade/README.md index 980361cc79..ccc010e0ad 100644 --- a/examples/peripherals/ledc/README.md +++ b/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. diff --git a/examples/peripherals/ledc/ledc_fade/main/CMakeLists.txt b/examples/peripherals/ledc/ledc_fade/main/CMakeLists.txt new file mode 100644 index 0000000000..7602af34bd --- /dev/null +++ b/examples/peripherals/ledc/ledc_fade/main/CMakeLists.txt @@ -0,0 +1,2 @@ +idf_component_register(SRCS "ledc_fade_example_main.c" + INCLUDE_DIRS ".") diff --git a/examples/peripherals/ledc/ledc_fade/main/component.mk b/examples/peripherals/ledc/ledc_fade/main/component.mk new file mode 100644 index 0000000000..44bd2b5273 --- /dev/null +++ b/examples/peripherals/ledc/ledc_fade/main/component.mk @@ -0,0 +1,3 @@ +# +# Main Makefile. This is basically the same as a component makefile. +# diff --git a/examples/peripherals/ledc/main/ledc_example_main.c b/examples/peripherals/ledc/ledc_fade/main/ledc_fade_example_main.c similarity index 100% rename from examples/peripherals/ledc/main/ledc_example_main.c rename to examples/peripherals/ledc/ledc_fade/main/ledc_fade_example_main.c diff --git a/examples/peripherals/ledc/main/CMakeLists.txt b/examples/peripherals/ledc/main/CMakeLists.txt deleted file mode 100644 index b3933e0d20..0000000000 --- a/examples/peripherals/ledc/main/CMakeLists.txt +++ /dev/null @@ -1,2 +0,0 @@ -idf_component_register(SRCS "ledc_example_main.c" - INCLUDE_DIRS ".")