alex/esp-idf
1
0
Fork 0
mirror of https://github.com/espressif/esp-idf.git synced 2025-11-04 06:11:06 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs(ledc): add notes for ledc_set_fade_with_time API reference

Browse Source 
Closes https://github.com/espressif/esp-idf/issues/15085
This commit is contained in:
Song Ruo Jing
2025-02-07 20:41:17 +08:00
parent b2dbcd7804
commit bea4615d0c
2 changed files with 34 additions and 12 deletions
Download Patch File Download Diff File Expand all files Collapse all files

32
components/esp_driver_ledc/include/driver/ledc.h
View File

@@ -1,5 +1,5 @@
/*
* SPDX-FileCopyrightText: 2015-2024 Espressif Systems (Shanghai) CO LTD
* SPDX-FileCopyrightText: 2015-2025 Espressif Systems (Shanghai) CO LTD
*
* SPDX-License-Identifier: Apache-2.0
*/
@@ -452,7 +452,18 @@ esp_err_t ledc_set_fade_with_step(ledc_mode_t speed_mode, ledc_channel_t channel
* @param speed_mode Select the LEDC channel group with specified speed mode. Note that not all targets support high speed mode.
* @param channel LEDC channel index (0 - LEDC_CHANNEL_MAX-1), select from ledc_channel_t
* @param target_duty Target duty of fading [0, (2**duty_resolution)]
* @param max_fade_time_ms The maximum time of the fading ( ms ).
* @param desired_fade_time_ms The intended time of the fading ( ms ).
* Note that the actual time it takes to complete the fade could vary by a factor of up to 2x shorter
* or longer than the expected time due to internal rounding errors in calculations.
* Specifically:
* * The total number of cycles (total_cycle_num = desired_fade_time_ms * freq / 1000)
* * The difference in duty cycle (duty_delta = |target_duty - current_duty|)
* The fade may complete faster than expected if total_cycle_num larger than duty_delta. Conversely,
* it may take longer than expected if total_cycle_num is less than duty_delta.
* The closer the ratio of total_cycle_num/duty_delta (or its inverse) is to a whole number (the floor value),
* the more accurately the actual fade duration will match the intended time.
* If an exact fade time is expected, please consider to split the entire fade into several smaller linear fades.
* The split should make each fade step has a divisible total_cycle_num/duty_delta (or its inverse) ratio.
*
* @return
* - ESP_OK Success
@@ -460,7 +471,7 @@ esp_err_t ledc_set_fade_with_step(ledc_mode_t speed_mode, ledc_channel_t channel
* - ESP_ERR_INVALID_STATE Channel not initialized
* - ESP_FAIL Fade function init error
*/
esp_err_t ledc_set_fade_with_time(ledc_mode_t speed_mode, ledc_channel_t channel, uint32_t target_duty, int max_fade_time_ms);
esp_err_t ledc_set_fade_with_time(ledc_mode_t speed_mode, ledc_channel_t channel, uint32_t target_duty, int desired_fade_time_ms);
/**
* @brief Install LEDC fade function. This function will occupy interrupt of LEDC module.
@@ -551,7 +562,18 @@ esp_err_t ledc_set_duty_and_update(ledc_mode_t speed_mode, ledc_channel_t channe
* @param speed_mode Select the LEDC channel group with specified speed mode. Note that not all targets support high speed mode.
* @param channel LEDC channel index (0 - LEDC_CHANNEL_MAX-1), select from ledc_channel_t
* @param target_duty Target duty of fading [0, (2**duty_resolution)]
* @param max_fade_time_ms The maximum time of the fading ( ms ).
* @param desired_fade_time_ms The intended time of the fading ( ms ).
* Note that the actual time it takes to complete the fade could vary by a factor of up to 2x shorter
* or longer than the expected time due to internal rounding errors in calculations.
* Specifically:
* * The total number of cycles (total_cycle_num = desired_fade_time_ms * freq / 1000)
* * The difference in duty cycle (duty_delta = |target_duty - current_duty|)
* The fade may complete faster than expected if total_cycle_num larger than duty_delta. Conversely,
* it may take longer than expected if total_cycle_num is less than duty_delta.
* The closer the ratio of total_cycle_num/duty_delta (or its inverse) is to a whole number (the floor value),
* the more accurately the actual fade duration will match the intended time.
* If an exact fade time is expected, please consider to split the entire fade into several smaller linear fades.
* The split should make each fade step has a divisible total_cycle_num/duty_delta (or its inverse) ratio.
* @param fade_mode choose blocking or non-blocking mode
*
* @return
@@ -560,7 +582,7 @@ esp_err_t ledc_set_duty_and_update(ledc_mode_t speed_mode, ledc_channel_t channe
* - ESP_ERR_INVALID_STATE Channel not initialized
* - ESP_FAIL Fade function init error
*/
esp_err_t ledc_set_fade_time_and_start(ledc_mode_t speed_mode, ledc_channel_t channel, uint32_t target_duty, uint32_t max_fade_time_ms, ledc_fade_mode_t fade_mode);
esp_err_t ledc_set_fade_time_and_start(ledc_mode_t speed_mode, ledc_channel_t channel, uint32_t target_duty, uint32_t desired_fade_time_ms, ledc_fade_mode_t fade_mode);
/**
* @brief A thread-safe API to set and start LEDC fade function.

14
components/esp_driver_ledc/src/ledc.c
View File

@@ -1,5 +1,5 @@
/*
* SPDX-FileCopyrightText: 2015-2024 Espressif Systems (Shanghai) CO LTD
* SPDX-FileCopyrightText: 2015-2025 Espressif Systems (Shanghai) CO LTD
*
* SPDX-License-Identifier: Apache-2.0
*/
@@ -1377,7 +1377,7 @@ static esp_err_t _ledc_set_fade_with_step(ledc_mode_t speed_mode, ledc_channel_t
return ESP_OK;
}
static esp_err_t _ledc_set_fade_with_time(ledc_mode_t speed_mode, ledc_channel_t channel, uint32_t target_duty, int max_fade_time_ms)
static esp_err_t _ledc_set_fade_with_time(ledc_mode_t speed_mode, ledc_channel_t channel, uint32_t target_duty, int desired_fade_time_ms)
{
ledc_timer_t timer_sel;
uint32_t duty_cur = 0;
@@ -1389,7 +1389,7 @@ static esp_err_t _ledc_set_fade_with_time(ledc_mode_t speed_mode, ledc_channel_t
if (duty_delta == 0) {
return _ledc_set_fade_with_step(speed_mode, channel, target_duty, 0, 0);
}
uint32_t total_cycles = max_fade_time_ms * freq / 1000;
uint32_t total_cycles = desired_fade_time_ms * freq / 1000;
if (total_cycles == 0) {
ESP_LOGW(LEDC_TAG, LEDC_FADE_TOO_FAST_STR);
return _ledc_set_fade_with_step(speed_mode, channel, target_duty, 0, 0);
@@ -1436,7 +1436,7 @@ static void _ledc_fade_start(ledc_mode_t speed_mode, ledc_channel_t channel, led
}
}
esp_err_t ledc_set_fade_with_time(ledc_mode_t speed_mode, ledc_channel_t channel, uint32_t target_duty, int max_fade_time_ms)
esp_err_t ledc_set_fade_with_time(ledc_mode_t speed_mode, ledc_channel_t channel, uint32_t target_duty, int desired_fade_time_ms)
{
LEDC_ARG_CHECK(speed_mode < LEDC_SPEED_MODE_MAX, "speed_mode");
LEDC_ARG_CHECK(channel < LEDC_CHANNEL_MAX, "channel");
@@ -1445,7 +1445,7 @@ esp_err_t ledc_set_fade_with_time(ledc_mode_t speed_mode, ledc_channel_t channel
LEDC_CHECK(ledc_fade_channel_init_check(speed_mode, channel) == ESP_OK, LEDC_FADE_INIT_ERROR_STR, ESP_FAIL);
_ledc_fade_hw_acquire(speed_mode, channel);
_ledc_set_fade_with_time(speed_mode, channel, target_duty, max_fade_time_ms);
_ledc_set_fade_with_time(speed_mode, channel, target_duty, desired_fade_time_ms);
_ledc_fade_hw_release(speed_mode, channel);
return ESP_OK;
}
@@ -1589,7 +1589,7 @@ esp_err_t ledc_set_duty_and_update(ledc_mode_t speed_mode, ledc_channel_t channe
return ESP_OK;
}
esp_err_t ledc_set_fade_time_and_start(ledc_mode_t speed_mode, ledc_channel_t channel, uint32_t target_duty, uint32_t max_fade_time_ms, ledc_fade_mode_t fade_mode)
esp_err_t ledc_set_fade_time_and_start(ledc_mode_t speed_mode, ledc_channel_t channel, uint32_t target_duty, uint32_t desired_fade_time_ms, ledc_fade_mode_t fade_mode)
{
LEDC_ARG_CHECK(speed_mode < LEDC_SPEED_MODE_MAX, "speed_mode");
LEDC_ARG_CHECK(channel < LEDC_CHANNEL_MAX, "channel");
@@ -1599,7 +1599,7 @@ esp_err_t ledc_set_fade_time_and_start(ledc_mode_t speed_mode, ledc_channel_t ch
LEDC_ARG_CHECK(target_duty <= ledc_get_max_duty(speed_mode, channel), "target_duty");
_ledc_op_lock_acquire(speed_mode, channel);
_ledc_fade_hw_acquire(speed_mode, channel);
_ledc_set_fade_with_time(speed_mode, channel, target_duty, max_fade_time_ms);
_ledc_set_fade_with_time(speed_mode, channel, target_duty, desired_fade_time_ms);
_ledc_fade_start(speed_mode, channel, fade_mode);
_ledc_op_lock_release(speed_mode, channel);
return ESP_OK;