From: krzychb Date: Mon, 23 Oct 2017 03:32:47 +0000 (+0200) Subject: Provided more meaningful parameter names by renaming 'bit_num' to 'duty_resolution... X-Git-Tag: v3.1-dev~5^2 X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=d488bb7bacca80e6089bdf070bb1e10324d31dbb;p=esp-idf Provided more meaningful parameter names by renaming 'bit_num' to 'duty_resolution' and 'div_num' to 'clock_divider' --- diff --git a/components/driver/include/driver/ledc.h b/components/driver/include/driver/ledc.h index 55c0c8d2ac..f004ae64a9 100644 --- a/components/driver/include/driver/ledc.h +++ b/components/driver/include/driver/ledc.h @@ -30,7 +30,7 @@ extern "C" { typedef enum { LEDC_HIGH_SPEED_MODE = 0, /*!< LEDC high speed speed_mode */ - LEDC_LOW_SPEED_MODE, /*!< LEDC low speed speed_mode */ + LEDC_LOW_SPEED_MODE, /*!< LEDC low speed speed_mode */ LEDC_SPEED_MODE_MAX, /*!< LEDC speed limit */ } ledc_mode_t; @@ -45,15 +45,15 @@ typedef enum { } ledc_duty_direction_t; typedef enum { - LEDC_REF_TICK = 0, /*!< LEDC timer clock divided from reference tick(1Mhz) */ - LEDC_APB_CLK, /*!< LEDC timer clock divided from APB clock(80Mhz)*/ + LEDC_REF_TICK = 0, /*!< LEDC timer clock divided from reference tick (1Mhz) */ + LEDC_APB_CLK, /*!< LEDC timer clock divided from APB clock (80Mhz) */ } ledc_clk_src_t; typedef enum { - LEDC_TIMER_0 = 0, /*!< LEDC source timer TIMER0 */ - LEDC_TIMER_1, /*!< LEDC source timer TIMER1 */ - LEDC_TIMER_2, /*!< LEDC source timer TIMER2 */ - LEDC_TIMER_3, /*!< LEDC source timer TIMER3 */ + LEDC_TIMER_0 = 0, /*!< LEDC timer 0 */ + LEDC_TIMER_1, /*!< LEDC timer 1 */ + LEDC_TIMER_2, /*!< LEDC timer 2 */ + LEDC_TIMER_3, /*!< LEDC timer 3 */ } ledc_timer_t; typedef enum { @@ -69,46 +69,47 @@ typedef enum { } ledc_channel_t; typedef enum { - LEDC_TIMER_10_BIT = 10, /*!< LEDC PWM depth 10Bit */ - LEDC_TIMER_11_BIT = 11, /*!< LEDC PWM depth 11Bit */ - LEDC_TIMER_12_BIT = 12, /*!< LEDC PWM depth 12Bit */ - LEDC_TIMER_13_BIT = 13, /*!< LEDC PWM depth 13Bit */ - LEDC_TIMER_14_BIT = 14, /*!< LEDC PWM depth 14Bit */ - LEDC_TIMER_15_BIT = 15, /*!< LEDC PWM depth 15Bit */ + LEDC_TIMER_10_BIT = 10, /*!< LEDC PWM duty resolution of 10 bits */ + LEDC_TIMER_11_BIT = 11, /*!< LEDC PWM duty resolution of 11 bits */ + LEDC_TIMER_12_BIT = 12, /*!< LEDC PWM duty resolution of 12 bits */ + LEDC_TIMER_13_BIT = 13, /*!< LEDC PWM duty resolution of 13 bits */ + LEDC_TIMER_14_BIT = 14, /*!< LEDC PWM duty resolution of 14 bits */ + LEDC_TIMER_15_BIT = 15, /*!< LEDC PWM duty resolution of 15 bits */ } ledc_timer_bit_t; typedef enum { LEDC_FADE_NO_WAIT = 0, /*!< LEDC fade function will return immediately */ - LEDC_FADE_WAIT_DONE, /*!< LEDC fade function will block until fading to the target duty*/ + LEDC_FADE_WAIT_DONE, /*!< LEDC fade function will block until fading to the target duty */ LEDC_FADE_MAX, } ledc_fade_mode_t; + /** * @brief Configuration parameters of LEDC channel for ledc_channel_config function */ typedef struct { - int gpio_num; /*!< the LEDC output gpio_num, if you want to use gpio16, gpio_num = 16*/ - ledc_mode_t speed_mode; /*!< LEDC speed speed_mode, high-speed mode or low-speed mode*/ - ledc_channel_t channel; /*!< LEDC channel(0 - 7)*/ - ledc_intr_type_t intr_type; /*!< configure interrupt, Fade interrupt enable or Fade interrupt disable*/ - ledc_timer_t timer_sel; /*!< Select the timer source of channel (0 - 3)*/ - uint32_t duty; /*!< LEDC channel duty, the duty range is [0, (2**bit_num) - 1], */ + int gpio_num; /*!< the LEDC output gpio_num, if you want to use gpio16, gpio_num = 16 */ + ledc_mode_t speed_mode; /*!< LEDC speed speed_mode, high-speed mode or low-speed mode */ + ledc_channel_t channel; /*!< LEDC channel (0 - 7) */ + ledc_intr_type_t intr_type; /*!< configure interrupt, Fade interrupt enable or Fade interrupt disable */ + ledc_timer_t timer_sel; /*!< Select the timer source of channel (0 - 3) */ + uint32_t duty; /*!< LEDC channel duty, the range of duty setting is [0, (2**duty_resolution) - 1] */ } ledc_channel_config_t; /** * @brief Configuration parameters of LEDC Timer timer for ledc_timer_config function */ typedef struct { - ledc_mode_t speed_mode; /*!< LEDC speed speed_mode, high-speed mode or low-speed mode*/ - ledc_timer_bit_t bit_num; /*!< LEDC channel duty depth*/ - ledc_timer_t timer_num; /*!< The timer source of channel (0 - 3)*/ - uint32_t freq_hz; /*!< LEDC timer frequency(Hz)*/ + ledc_mode_t speed_mode; /*!< LEDC speed speed_mode, high-speed mode or low-speed mode */ + ledc_timer_bit_t duty_resolution; /*!< LEDC channel duty resolution */ + ledc_timer_t timer_num; /*!< The timer source of channel (0 - 3) */ + uint32_t freq_hz; /*!< LEDC timer frequency (Hz) */ } ledc_timer_config_t; typedef intr_handle_t ledc_isr_handle_t; /** * @brief LEDC channel configuration - * Configure LEDC channel with the given channel/output gpio_num/interrupt/source timer/frequency(Hz)/LEDC depth + * Configure LEDC channel with the given channel/output gpio_num/interrupt/source timer/frequency(Hz)/LEDC duty resolution * * @param ledc_conf Pointer of LEDC channel configure struct * @@ -120,14 +121,14 @@ esp_err_t ledc_channel_config(const ledc_channel_config_t* ledc_conf); /** * @brief LEDC timer configuration - * Configure LEDC timer with the given source timer/frequency(Hz)/bit_num + * Configure LEDC timer with the given source timer/frequency(Hz)/duty_resolution * * @param timer_conf Pointer of LEDC timer configure struct * * @return * - ESP_OK Success * - ESP_ERR_INVALID_ARG Parameter error - * - ESP_FAIL Can not find a proper pre-divider number base on the given frequency and the current bit_num. + * - ESP_FAIL Can not find a proper pre-divider number base on the given frequency and the current duty_resolution. */ esp_err_t ledc_timer_config(const ledc_timer_config_t* timer_conf); @@ -137,7 +138,7 @@ esp_err_t ledc_timer_config(const ledc_timer_config_t* timer_conf); * After ledc_set_duty, ledc_set_fade, we need to call this function to update the settings. * * @param speed_mode Select the LEDC speed_mode, high-speed mode and low-speed mode, - * @param channel LEDC channel(0-7), select from ledc_channel_t + * @param channel LEDC channel (0-7), select from ledc_channel_t * * @return * - ESP_OK Success @@ -151,7 +152,7 @@ esp_err_t ledc_update_duty(ledc_mode_t speed_mode, ledc_channel_t channel); * Disable LEDC output, and set idle level * * @param speed_mode Select the LEDC speed_mode, high-speed mode and low-speed mode - * @param channel LEDC channel(0-7), select from ledc_channel_t + * @param channel LEDC channel (0-7), select from ledc_channel_t * @param idle_level Set output idle level after LEDC stops. * * @return @@ -161,24 +162,24 @@ esp_err_t ledc_update_duty(ledc_mode_t speed_mode, ledc_channel_t channel); esp_err_t ledc_stop(ledc_mode_t speed_mode, ledc_channel_t channel, uint32_t idle_level); /** - * @brief LEDC set channel frequency(Hz) + * @brief LEDC set channel frequency (Hz) * * @param speed_mode Select the LEDC speed_mode, high-speed mode and low-speed mode - * @param timer_num LEDC timer index(0-3), select from ledc_timer_t + * @param timer_num LEDC timer index (0-3), select from ledc_timer_t * @param freq_hz Set the LEDC frequency * * @return * - ESP_OK Success * - ESP_ERR_INVALID_ARG Parameter error - * - ESP_FAIL Can not find a proper pre-divider number base on the given frequency and the current bit_num. + * - ESP_FAIL Can not find a proper pre-divider number base on the given frequency and the current duty_resolution. */ esp_err_t ledc_set_freq(ledc_mode_t speed_mode, ledc_timer_t timer_num, uint32_t freq_hz); /** - * @brief LEDC get channel frequency(Hz) + * @brief LEDC get channel frequency (Hz) * * @param speed_mode Select the LEDC speed_mode, high-speed mode and low-speed mode - * @param timer_num LEDC timer index(0-3), select from ledc_timer_t + * @param timer_num LEDC timer index (0-3), select from ledc_timer_t * * @return * - 0 error @@ -191,8 +192,8 @@ uint32_t ledc_get_freq(ledc_mode_t speed_mode, ledc_timer_t timer_num); * Only after calling ledc_update_duty will the duty update. * * @param speed_mode Select the LEDC speed_mode, high-speed mode and low-speed mode - * @param channel LEDC channel(0-7), select from ledc_channel_t - * @param duty Set the LEDC duty, the duty range is [0, (2**bit_num) - 1] + * @param channel LEDC channel (0-7), select from ledc_channel_t + * @param duty Set the LEDC duty, the range of duty setting is [0, (2**duty_resolution) - 1] * * @return * - ESP_OK Success @@ -204,7 +205,7 @@ esp_err_t ledc_set_duty(ledc_mode_t speed_mode, ledc_channel_t channel, uint32_t * @brief LEDC get duty * * @param speed_mode Select the LEDC speed_mode, high-speed mode and low-speed mode - * @param channel LEDC channel(0-7), select from ledc_channel_t + * @param channel LEDC channel (0-7), select from ledc_channel_t * * @return * - LEDC_ERR_DUTY if parameter error @@ -217,8 +218,8 @@ uint32_t ledc_get_duty(ledc_mode_t speed_mode, ledc_channel_t channel); * Set LEDC gradient, After the function calls the ledc_update_duty function, the function can take effect. * * @param speed_mode Select the LEDC speed_mode, high-speed mode and low-speed mode - * @param channel LEDC channel(0-7), select from ledc_channel_t - * @param duty Set the start of the gradient duty, the duty range is [0, (2**bit_num) - 1] + * @param channel LEDC channel (0-7), select from ledc_channel_t + * @param duty Set the start of the gradient duty, the range of duty setting is [0, (2**duty_resolution) - 1] * @param gradule_direction Set the direction of the gradient * @param step_num Set the number of the gradient * @param duty_cyle_num Set how many LEDC tick each time the gradient lasts @@ -253,22 +254,22 @@ esp_err_t ledc_isr_register(void (*fn)(void*), void * arg, int intr_alloc_flags, * @brief Configure LEDC settings * * @param speed_mode Select the LEDC speed_mode, high-speed mode and low-speed mode - * @param timer_sel Timer index(0-3), there are 4 timers in LEDC module - * @param div_num Timer clock divide number, the timer clock is divided from the selected clock source - * @param bit_num The count number of one period, counter range is 0 ~ ((2 ** bit_num) - 1) + * @param timer_sel Timer index (0-3), there are 4 timers in LEDC module + * @param clock_divider Timer clock divide value, the timer clock is divided from the selected clock source + * @param duty_resolution Resolution of duty setting in number of bits. The range of duty values is [0, (2**duty_resolution) - 1] * @param clk_src Select LEDC source clock. * * @return * - (-1) Parameter error * - Other Current LEDC duty */ -esp_err_t ledc_timer_set(ledc_mode_t speed_mode, ledc_timer_t timer_sel, uint32_t div_num, uint32_t bit_num, ledc_clk_src_t clk_src); +esp_err_t ledc_timer_set(ledc_mode_t speed_mode, ledc_timer_t timer_sel, uint32_t clock_divider, uint32_t duty_resolution, ledc_clk_src_t clk_src); /** * @brief Reset LEDC timer * * @param speed_mode Select the LEDC speed_mode, high-speed mode and low-speed mode - * @param timer_sel LEDC timer index(0-3), select from ledc_timer_t + * @param timer_sel LEDC timer index (0-3), select from ledc_timer_t * * @return * - ESP_ERR_INVALID_ARG Parameter error @@ -280,7 +281,7 @@ esp_err_t ledc_timer_rst(ledc_mode_t speed_mode, uint32_t timer_sel); * @brief Pause LEDC timer counter * * @param speed_mode Select the LEDC speed_mode, high-speed mode and low-speed mode - * @param timer_sel LEDC timer index(0-3), select from ledc_timer_t + * @param timer_sel LEDC timer index (0-3), select from ledc_timer_t * * @return * - ESP_ERR_INVALID_ARG Parameter error @@ -293,7 +294,7 @@ esp_err_t ledc_timer_pause(ledc_mode_t speed_mode, uint32_t timer_sel); * @brief Resume LEDC timer * * @param speed_mode Select the LEDC speed_mode, high-speed mode and low-speed mode - * @param timer_sel LEDC timer index(0-3), select from ledc_timer_t + * @param timer_sel LEDC timer index (0-3), select from ledc_timer_t * * @return * - ESP_ERR_INVALID_ARG Parameter error @@ -305,8 +306,8 @@ esp_err_t ledc_timer_resume(ledc_mode_t speed_mode, uint32_t timer_sel); * @brief Bind LEDC channel with the selected timer * * @param speed_mode Select the LEDC speed_mode, high-speed mode and low-speed mode - * @param channel LEDC channel index(0-7), select from ledc_channel_t - * @param timer_idx LEDC timer index(0-3), select from ledc_timer_t + * @param channel LEDC channel index (0-7), select from ledc_channel_t + * @param timer_idx LEDC timer index (0-3), select from ledc_timer_t * * @return * - ESP_ERR_INVALID_ARG Parameter error @@ -319,8 +320,8 @@ esp_err_t ledc_bind_channel_timer(ledc_mode_t speed_mode, uint32_t channel, uint * Call ledc_fade_start() after this to start fading. * * @param speed_mode Select the LEDC speed_mode, high-speed mode and low-speed mode, - * @param channel LEDC channel index(0-7), select from ledc_channel_t - * @param target_duty Target duty of fading.( 0 - (2 ** bit_num - 1))) + * @param channel LEDC channel index (0-7), select from ledc_channel_t + * @param target_duty Target duty of fading [0, (2**duty_resolution) - 1] * @param scale Controls the increase or decrease step scale. * @param cycle_num increase or decrease the duty every cycle_num cycles * @@ -337,8 +338,8 @@ esp_err_t ledc_set_fade_with_step(ledc_mode_t speed_mode, ledc_channel_t channel * Call ledc_fade_start() after this to start fading. * * @param speed_mode Select the LEDC speed_mode, high-speed mode and low-speed mode, - * @param channel LEDC channel index(0-7), select from ledc_channel_t - * @param target_duty Target duty of fading.( 0 - (2 ** bit_num - 1))) + * @param channel LEDC channel index (0-7), select from ledc_channel_t + * @param target_duty Target duty of fading.( 0 - (2 ** duty_resolution - 1))) * @param max_fade_time_ms The maximum time of the fading ( ms ). * * @return diff --git a/components/driver/ledc.c b/components/driver/ledc.c index 309ea63c7c..49b9e1ecf6 100644 --- a/components/driver/ledc.c +++ b/components/driver/ledc.c @@ -74,15 +74,15 @@ static IRAM_ATTR void ledc_ls_channel_update(ledc_mode_t speed_mode, ledc_channe } } -esp_err_t ledc_timer_set(ledc_mode_t speed_mode, ledc_timer_t timer_sel, uint32_t div_num, uint32_t bit_num, +esp_err_t ledc_timer_set(ledc_mode_t speed_mode, ledc_timer_t timer_sel, uint32_t clock_divider, uint32_t duty_resolution, ledc_clk_src_t clk_src) { LEDC_CHECK(speed_mode < LEDC_SPEED_MODE_MAX, LEDC_MODE_ERR_STR, ESP_ERR_INVALID_ARG); LEDC_CHECK(timer_sel <= LEDC_TIMER_3, LEDC_TIMER_ERR_STR, ESP_ERR_INVALID_ARG); portENTER_CRITICAL(&ledc_spinlock); - LEDC.timer_group[speed_mode].timer[timer_sel].conf.div_num = div_num; + LEDC.timer_group[speed_mode].timer[timer_sel].conf.clock_divider = clock_divider; LEDC.timer_group[speed_mode].timer[timer_sel].conf.tick_sel = clk_src; - LEDC.timer_group[speed_mode].timer[timer_sel].conf.bit_num = bit_num; + LEDC.timer_group[speed_mode].timer[timer_sel].conf.duty_resolution = duty_resolution; ledc_ls_timer_update(speed_mode, timer_sel); portEXIT_CRITICAL(&ledc_spinlock); return ESP_OK; @@ -183,13 +183,13 @@ esp_err_t ledc_isr_register(void (*fn)(void*), void * arg, int intr_alloc_flags, esp_err_t ledc_timer_config(const ledc_timer_config_t* timer_conf) { int freq_hz = timer_conf->freq_hz; - int bit_num = timer_conf->bit_num; + int duty_resolution = timer_conf->duty_resolution; int timer_num = timer_conf->timer_num; int speed_mode = timer_conf->speed_mode; LEDC_CHECK(speed_mode < LEDC_SPEED_MODE_MAX, LEDC_MODE_ERR_STR, ESP_ERR_INVALID_ARG); periph_module_enable(PERIPH_LEDC_MODULE); - if (freq_hz == 0 || bit_num == 0 || bit_num > LEDC_TIMER_15_BIT) { - ESP_LOGE(LEDC_TAG, "freq_hz=%u bit_num=%u", freq_hz, bit_num); + if (freq_hz == 0 || duty_resolution == 0 || duty_resolution > LEDC_TIMER_15_BIT) { + ESP_LOGE(LEDC_TAG, "freq_hz=%u duty_resolution=%u", freq_hz, duty_resolution); return ESP_ERR_INVALID_ARG; } if (timer_num > LEDC_TIMER_3) { @@ -197,14 +197,14 @@ esp_err_t ledc_timer_config(const ledc_timer_config_t* timer_conf) return ESP_ERR_INVALID_ARG; } esp_err_t ret = ESP_OK; - uint32_t precision = ( 0x1 << bit_num ); // 2**depth + uint32_t precision = ( 0x1 << duty_resolution ); // 2**depth // Try calculating divisor based on LEDC_APB_CLK ledc_clk_src_t timer_clk_src = LEDC_APB_CLK; // div_param is a Q10.8 fixed point value uint64_t div_param = ( (uint64_t) LEDC_APB_CLK_HZ << 8 ) / freq_hz / precision; if (div_param < 256) { // divisor is too low - ESP_LOGE(LEDC_TAG, "requested frequency and bit depth can not be achieved, try reducing freq_hz or bit_num. div_param=%d", + ESP_LOGE(LEDC_TAG, "requested frequency and duty resolution can not be achieved, try reducing freq_hz or duty_resolution. div_param=%d", (uint32_t ) div_param); ret = ESP_FAIL; } @@ -213,7 +213,7 @@ esp_err_t ledc_timer_config(const ledc_timer_config_t* timer_conf) timer_clk_src = LEDC_REF_TICK; div_param = ((uint64_t) LEDC_REF_CLK_HZ << 8) / freq_hz / precision; if (div_param < 256 || div_param > LEDC_DIV_NUM_HSTIMER0_V) { - ESP_LOGE(LEDC_TAG, "requested frequency and bit depth can not be achieved, try increasing freq_hz or bit_num. div_param=%d", + ESP_LOGE(LEDC_TAG, "requested frequency and duty resolution can not be achieved, try increasing freq_hz or duty_resolution. div_param=%d", (uint32_t ) div_param); ret = ESP_FAIL; } @@ -224,7 +224,7 @@ esp_err_t ledc_timer_config(const ledc_timer_config_t* timer_conf) } } // set timer parameters - ledc_timer_set(speed_mode, timer_num, div_param, bit_num, timer_clk_src); + ledc_timer_set(speed_mode, timer_num, div_param, duty_resolution, timer_clk_src); // reset timer ledc_timer_rst(speed_mode, timer_num); return ret; @@ -261,7 +261,7 @@ esp_err_t ledc_channel_config(const ledc_channel_config_t* ledc_conf) esp_err_t ret = ESP_OK; /*set channel parameters*/ /* channel parameters decide how the waveform looks like in one period*/ - /* set channel duty, duty range is (0 ~ ((2 ** bit_num) - 1))*/ + /* set channel duty, duty range is (0 ~ ((2 ** duty_resolution) - 1))*/ ledc_set_duty(speed_mode, ledc_channel, duty); /*update duty settings*/ ledc_update_duty(speed_mode, ledc_channel); @@ -364,20 +364,20 @@ esp_err_t ledc_set_freq(ledc_mode_t speed_mode, ledc_timer_t timer_num, uint32_t LEDC_CHECK(speed_mode < LEDC_SPEED_MODE_MAX, LEDC_MODE_ERR_STR, ESP_ERR_INVALID_ARG); portENTER_CRITICAL(&ledc_spinlock); esp_err_t ret = ESP_OK; - uint32_t div_num = 0; - uint32_t bit_num = LEDC.timer_group[speed_mode].timer[timer_num].conf.bit_num; + uint32_t clock_divider = 0; + uint32_t duty_resolution = LEDC.timer_group[speed_mode].timer[timer_num].conf.duty_resolution; uint32_t timer_source_clk = LEDC.timer_group[speed_mode].timer[timer_num].conf.tick_sel; - uint32_t precision = (0x1 << bit_num); + uint32_t precision = (0x1 << duty_resolution); if (timer_source_clk == LEDC_APB_CLK) { - div_num = ((uint64_t) LEDC_APB_CLK_HZ << 8) / freq_hz / precision; + clock_divider = ((uint64_t) LEDC_APB_CLK_HZ << 8) / freq_hz / precision; } else { - div_num = ((uint64_t) LEDC_REF_CLK_HZ << 8) / freq_hz / precision; + clock_divider = ((uint64_t) LEDC_REF_CLK_HZ << 8) / freq_hz / precision; } - if (div_num <= 256 || div_num > LEDC_DIV_NUM_HSTIMER0) { - ESP_LOGE(LEDC_TAG, "div param err,div_param=%u", div_num); + if (clock_divider <= 256 || clock_divider > LEDC_DIV_NUM_HSTIMER0) { + ESP_LOGE(LEDC_TAG, "div param err,div_param=%u", clock_divider); ret = ESP_FAIL; } - LEDC.timer_group[speed_mode].timer[timer_num].conf.div_num = div_num; + LEDC.timer_group[speed_mode].timer[timer_num].conf.clock_divider = clock_divider; portEXIT_CRITICAL(&ledc_spinlock); return ret; } @@ -388,13 +388,13 @@ uint32_t ledc_get_freq(ledc_mode_t speed_mode, ledc_timer_t timer_num) portENTER_CRITICAL(&ledc_spinlock); uint32_t freq = 0; uint32_t timer_source_clk = LEDC.timer_group[speed_mode].timer[timer_num].conf.tick_sel; - uint32_t bit_num = LEDC.timer_group[speed_mode].timer[timer_num].conf.bit_num; - uint32_t div_num = LEDC.timer_group[speed_mode].timer[timer_num].conf.div_num; - uint32_t precision = (0x1 << bit_num); + uint32_t duty_resolution = LEDC.timer_group[speed_mode].timer[timer_num].conf.duty_resolution; + uint32_t clock_divider = LEDC.timer_group[speed_mode].timer[timer_num].conf.clock_divider; + uint32_t precision = (0x1 << duty_resolution); if (timer_source_clk == LEDC_APB_CLK) { - freq = ((uint64_t) LEDC_APB_CLK_HZ << 8) / precision / div_num; + freq = ((uint64_t) LEDC_APB_CLK_HZ << 8) / precision / clock_divider; } else { - freq = ((uint64_t) LEDC_REF_CLK_HZ << 8) / precision / div_num; + freq = ((uint64_t) LEDC_REF_CLK_HZ << 8) / precision / clock_divider; } portEXIT_CRITICAL(&ledc_spinlock); return freq; @@ -504,7 +504,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); int timer_sel = LEDC.channel_group[speed_mode].channel[channel].conf0.timer_sel; - uint32_t max_duty = (1 << (LEDC.timer_group[speed_mode].timer[timer_sel].conf.bit_num)) - 1; + uint32_t max_duty = (1 << (LEDC.timer_group[speed_mode].timer[timer_sel].conf.duty_resolution)) - 1; LEDC_CHECK(target_duty <= max_duty, LEDC_FADE_TARGET_ERR_STR, ESP_ERR_INVALID_ARG); uint32_t freq = ledc_get_freq(speed_mode, timer_sel); uint32_t duty_cur = LEDC.channel_group[speed_mode].channel[channel].duty_rd.duty_read >> LEDC_DUTY_DECIMAL_BIT_NUM; @@ -535,7 +535,7 @@ esp_err_t ledc_set_fade_with_step(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); int timer_sel = LEDC.channel_group[speed_mode].channel[channel].conf0.timer_sel; - uint32_t max_duty = (1 << (LEDC.timer_group[speed_mode].timer[timer_sel].conf.bit_num)) - 1; + uint32_t max_duty = (1 << (LEDC.timer_group[speed_mode].timer[timer_sel].conf.duty_resolution)) - 1; LEDC_CHECK(target_duty <= max_duty, LEDC_FADE_TARGET_ERR_STR, ESP_ERR_INVALID_ARG); //disable the interrupt, so the operation will not mess up ledc_enable_intr_type(speed_mode, channel, LEDC_INTR_DISABLE); @@ -579,8 +579,8 @@ esp_err_t ledc_set_fade_with_step(ledc_mode_t speed_mode, ledc_channel_t channel s_ledc_fade_rec[speed_mode][channel]->cycle_num, s_ledc_fade_rec[speed_mode][channel]->scale ); - int bit_num_ch0 = (speed_mode == LEDC_HIGH_SPEED_MODE) ? LEDC_DUTY_CHNG_END_HSCH0_INT_ENA_S : LEDC_DUTY_CHNG_END_LSCH0_INT_ENA_S; - LEDC.int_clr.val |= BIT(bit_num_ch0 + channel); + int duty_resolution_ch0 = (speed_mode == LEDC_HIGH_SPEED_MODE) ? LEDC_DUTY_CHNG_END_HSCH0_INT_ENA_S : LEDC_DUTY_CHNG_END_LSCH0_INT_ENA_S; + LEDC.int_clr.val |= BIT(duty_resolution_ch0 + channel); ledc_enable_intr_type(speed_mode, channel, LEDC_INTR_FADE_END); return ESP_OK; } diff --git a/components/soc/esp32/include/soc/ledc_struct.h b/components/soc/esp32/include/soc/ledc_struct.h index dd3c364bd4..f90c3cb9d9 100644 --- a/components/soc/esp32/include/soc/ledc_struct.h +++ b/components/soc/esp32/include/soc/ledc_struct.h @@ -69,13 +69,13 @@ typedef volatile struct { struct { union { struct { - uint32_t bit_num: 5; /*This register controls the range of the counter in high speed timer. the counter range is [0 2**reg_hstimer0_lim] the max bit width for counter is 20.*/ - uint32_t div_num: 18; /*This register is used to configure parameter for divider in high speed timer the least significant eight bits represent the decimal part.*/ - uint32_t pause: 1; /*This bit is used to pause the counter in high speed timer*/ - uint32_t rst: 1; /*This bit is used to reset high speed timer the counter will be 0 after reset.*/ - uint32_t tick_sel: 1; /*This bit is used to choose apb_clk or ref_tick for high speed timer. 1'b1:apb_clk 0:ref_tick*/ + uint32_t duty_resolution: 5; /*This register controls resolution of PWN duty by defining the bith width of timer's counter. The max bit width of the counter is 20.*/ + uint32_t clock_divider: 18; /*This register is used to configure the divider of clock at the entry of timer. The least significant eight bits represent the decimal part.*/ + uint32_t pause: 1; /*This bit is used to pause the counter in high speed timer*/ + uint32_t rst: 1; /*This bit is used to reset high speed timer the counter will be 0 after reset.*/ + uint32_t tick_sel: 1; /*This bit is used to choose apb_clk or ref_tick for high speed timer. 1'b1:apb_clk 0:ref_tick*/ uint32_t low_speed_update: 1; /*This bit is only useful for low speed timer channels, reserved for high speed timers*/ - uint32_t reserved26: 5; + uint32_t reserved26: 5; }; uint32_t val; } conf; diff --git a/docs/_static/ledc-api-settings.jpg b/docs/_static/ledc-api-settings.jpg index 06c0b10ad9..92f0545ab1 100644 Binary files a/docs/_static/ledc-api-settings.jpg and b/docs/_static/ledc-api-settings.jpg differ diff --git a/docs/api-reference/peripherals/ledc.rst b/docs/api-reference/peripherals/ledc.rst index a92b07af73..9b22f1b5d3 100644 --- a/docs/api-reference/peripherals/ledc.rst +++ b/docs/api-reference/peripherals/ledc.rst @@ -38,9 +38,9 @@ Configure Timer Setting of the timer is done by calling function :cpp:func:`ledc_timer_config`. This function should be provided with a data structure :cpp:type:`ledc_timer_config_t` that contains the following configuration settings: * The timer number :cpp:type:`ledc_timer_t` and a speed mode :cpp:type:`ledc_mode_t`. - * The PWM signal's frequency and a "bit number". The later represents a resolution of PWM's duty value changes. + * The PWM signal's frequency and resolution of PWM's duty value changes. -The frequency and the bit values are interdependent. The higher the PWM frequency, the lower bit number is available and vice versa. This relationship may became important, if you are planning to use this API for purposes other that changing intensity of LEDs. Check section :ref:`ledc-api-supported-range-frequency-bit-number` for more details. +The frequency and the duty resolution are interdependent. The higher the PWM frequency, the lower duty resolution is available and vice versa. This relationship may became important, if you are planning to use this API for purposes other that changing intensity of LEDs. Check section :ref:`ledc-api-supported-range-frequency-duty-resolution` for more details. .. _ledc-api-configure-channel: @@ -70,7 +70,7 @@ Setting of the duty is done by first calling dedicated function :cpp:func:`ledc_ Another way to set the duty, and some other channel parameters as well, is by calling :cpp:func:`ledc_channel_config` discussed in the previous section. -The range of the duty value entered into functions depends on selected bit number (`` bit_num``) and should be from 0 to (2 ** bit_num) - 1. For example, if selected bit number is 10, then the duty range is from 0 to 1023. This provides the duty resolution of ~0.1%. +The range of the duty value entered into functions depends on selected ``duty_resolution`` and should be from 0 to (2 ** duty_resolution) - 1. For example, if selected duty resolution is 10, then the duty range is from 0 to 1023. This provides the resolution of ~0.1%. Change PWM Duty with Hardware Fading @@ -96,7 +96,7 @@ The LEDC API provides several means to change the PWM frequency "on the fly". * One of options is to call :cpp:func:`ledc_set_freq`. There is a corresponding function :cpp:func:`ledc_get_freq` to check what frequency is currently set. - * Another option to change the frequency, and the bit number as well, is by calling :cpp:func:`ledc_bind_channel_timer` to bind other timer to the channel. + * Another option to change the frequency, and the duty resolution as well, is by calling :cpp:func:`ledc_bind_channel_timer` to bind other timer to the channel. * Finally the channel's timer may be changed by calling :cpp:func:`ledc_channel_config`. @@ -134,32 +134,32 @@ The advantage of the high speed mode is h/w supported, glitch-free changeover of For additional details regarding speed modes please refer to `ESP32 Technical Reference Manual `_ (PDF). Note that support for ``SLOW_CLOCK`` mentioned in this manual is not implemented in the LEDC API. -.. _ledc-api-supported-range-frequency-bit-number: +.. _ledc-api-supported-range-frequency-duty-resolution: -Supported Range of Frequency and Bit Number -------------------------------------------- +Supported Range of Frequency and Duty Resolution +------------------------------------------------ -The LED PWM Controller is designed primarily to drive LEDs and provides wide resolution of PWM duty settings. The resolution (or granularity) of the PWM duty is determined by the "bit number". For instance for the PWM frequency at 5 kHz, the maximum bit number is 13 bits. It means that the duty may be set anywhere from 0 to 100% with resolution of ~0.012% (13 ** 2 = 8192 discrete levels of the LED intensity). +The LED PWM Controller is designed primarily to drive LEDs and provides wide resolution of PWM duty settings. For instance for the PWM frequency at 5 kHz, the maximum duty resolution is 13 bits. It means that the duty may be set anywhere from 0 to 100% with resolution of ~0.012% (13 ** 2 = 8192 discrete levels of the LED intensity). The LEDC may be used for providing signals at much higher frequencies to clock other devices, e.g. a digital camera module. In such a case the maximum available frequency is 40 MHz with duty resolution of 1 bit. This means that duty is fixed at 50% and cannot be adjusted. -The API is designed to report an error when trying to set a frequency and a bit number that is out of the range of LEDC's hardware. For example, an attempt to set the frequency at 20 MHz and the bit number of 3 bits will result in the following error reported on a serial monitor: +The API is designed to report an error when trying to set a frequency and a duty resolution that is out of the range of LEDC's hardware. For example, an attempt to set the frequency at 20 MHz and the duty resolution of 3 bits will result in the following error reported on a serial monitor: .. highlight:: none :: - E (196) ledc: requested frequency and bit number can not be achieved, try reducing freq_hz or bit_num. div_param=128 + E (196) ledc: requested frequency and duty resolution can not be achieved, try reducing freq_hz or duty_resolution. div_param=128 -In such a case either the bit number or the frequency should be reduced. For example setting the bit number at 2 will resolve this issue and provide possibility to set the duty with 25% steps, i.e. at 25%, 50% or 75%. +In such a case either the duty resolution or the frequency should be reduced. For example setting the duty resolution at 2 will resolve this issue and provide possibility to set the duty with 25% steps, i.e. at 25%, 50% or 75%. -The LEDC API will also capture and report an attempt to configure frequency / bit number combination that is below the supported minimum, e.g.: +The LEDC API will also capture and report an attempt to configure frequency / duty resolution combination that is below the supported minimum, e.g.: :: - E (196) ledc: requested frequency and bit depth can not be achieved, try increasing freq_hz or bit_num. div_param=128000000 + E (196) ledc: requested frequency and duty resolution can not be achieved, try increasing freq_hz or duty_resolution. div_param=128000000 -Setting of the bit number is normally done using :cpp:type:`ledc_timer_bit_t`. This enumeration covers the range from 10 to 15 bits. If a smaller bit number is required (below 10 down to 1), enter the equivalent numeric values directly. +Setting of the duty resolution is normally done using :cpp:type:`ledc_timer_bit_t`. This enumeration covers the range from 10 to 15 bits. If a smaller duty resolution is required (below 10 down to 1), enter the equivalent numeric values directly. Application Example diff --git a/examples/peripherals/ledc/main/ledc_example_main.c b/examples/peripherals/ledc/main/ledc_example_main.c index 9f5def1fd1..05547fb202 100644 --- a/examples/peripherals/ledc/main/ledc_example_main.c +++ b/examples/peripherals/ledc/main/ledc_example_main.c @@ -60,10 +60,10 @@ void app_main() * that will be used by LED Controller */ ledc_timer_config_t ledc_timer = { - .bit_num = LEDC_TIMER_13_BIT, // resolution of PWM duty - .freq_hz = 5000, // frequency of PWM signal - .speed_mode = LEDC_HS_MODE, // timer mode - .timer_num = LEDC_HS_TIMER // timer index + .duty_resolution = LEDC_TIMER_13_BIT, // resolution of PWM duty + .freq_hz = 5000, // frequency of PWM signal + .speed_mode = LEDC_HS_MODE, // timer mode + .timer_num = LEDC_HS_TIMER // timer index }; // Set configuration of timer0 for high speed channels ledc_timer_config(&ledc_timer); diff --git a/examples/peripherals/pcnt/main/pcnt_example_main.c b/examples/peripherals/pcnt/main/pcnt_example_main.c index 68b36e45fa..2a4b3695c7 100644 --- a/examples/peripherals/pcnt/main/pcnt_example_main.c +++ b/examples/peripherals/pcnt/main/pcnt_example_main.c @@ -96,10 +96,10 @@ static void ledc_init(void) { // Prepare and then apply the LEDC PWM timer configuration ledc_timer_config_t ledc_timer; - ledc_timer.speed_mode = LEDC_HIGH_SPEED_MODE; - ledc_timer.timer_num = LEDC_TIMER_1; - ledc_timer.bit_num = LEDC_TIMER_10_BIT; - ledc_timer.freq_hz = 1; // set output frequency at 1 Hz + ledc_timer.speed_mode = LEDC_HIGH_SPEED_MODE; + ledc_timer.timer_num = LEDC_TIMER_1; + ledc_timer.duty_resolution = LEDC_TIMER_10_BIT; + ledc_timer.freq_hz = 1; // set output frequency at 1 Hz ledc_timer_config(&ledc_timer); // Prepare and then apply the LEDC PWM channel configuration