ESPHome  2024.10.2
ledc_output.cpp
Go to the documentation of this file.
1 #include "ledc_output.h"
2 #include "esphome/core/log.h"
3 
4 #ifdef USE_ESP32
5 
6 #ifdef USE_ARDUINO
7 #include <esp32-hal-ledc.h>
8 #endif
9 #include <driver/ledc.h>
10 
11 #include <cinttypes>
12 
13 #define CLOCK_FREQUENCY 80e6f
14 
15 #ifdef USE_ARDUINO
16 #ifdef SOC_LEDC_SUPPORT_XTAL_CLOCK
17 #undef CLOCK_FREQUENCY
18 // starting with ESP32 Arduino 2.0.2, the 40MHz crystal is used as clock by default if supported
19 #define CLOCK_FREQUENCY 40e6f
20 #endif
21 #else
22 #ifdef SOC_LEDC_SUPPORT_APB_CLOCK
23 #define DEFAULT_CLK LEDC_USE_APB_CLK
24 #else
25 #define DEFAULT_CLK LEDC_AUTO_CLK
26 #endif
27 #endif
28 
29 static const uint8_t SETUP_ATTEMPT_COUNT_MAX = 5;
30 
31 namespace esphome {
32 namespace ledc {
33 
34 static const char *const TAG = "ledc.output";
35 
36 static const int MAX_RES_BITS = LEDC_TIMER_BIT_MAX - 1;
37 #ifdef USE_ESP_IDF
38 #if SOC_LEDC_SUPPORT_HS_MODE
39 // Only ESP32 has LEDC_HIGH_SPEED_MODE
40 inline ledc_mode_t get_speed_mode(uint8_t channel) { return channel < 8 ? LEDC_HIGH_SPEED_MODE : LEDC_LOW_SPEED_MODE; }
41 #else
42 // S2, C3, S3 only support LEDC_LOW_SPEED_MODE
43 // See
44 // https://docs.espressif.com/projects/esp-idf/en/latest/esp32c3/api-reference/peripherals/ledc.html#functionality-overview
45 inline ledc_mode_t get_speed_mode(uint8_t) { return LEDC_LOW_SPEED_MODE; }
46 #endif
47 #endif
48 
49 float ledc_max_frequency_for_bit_depth(uint8_t bit_depth) { return CLOCK_FREQUENCY / float(1 << bit_depth); }
50 
51 float ledc_min_frequency_for_bit_depth(uint8_t bit_depth, bool low_frequency) {
52  const float max_div_num = ((1 << MAX_RES_BITS) - 1) / (low_frequency ? 32.0f : 256.0f);
53  return CLOCK_FREQUENCY / (max_div_num * float(1 << bit_depth));
54 }
55 
57  ESP_LOGV(TAG, "Calculating resolution bit-depth for frequency %f", frequency);
58  for (int i = MAX_RES_BITS; i >= 1; i--) {
59  const float min_frequency = ledc_min_frequency_for_bit_depth(i, (frequency < 100));
60  const float max_frequency = ledc_max_frequency_for_bit_depth(i);
61  if (min_frequency <= frequency && frequency <= max_frequency) {
62  ESP_LOGV(TAG, "Resolution calculated as %d", i);
63  return i;
64  }
65  }
66  return {};
67 }
68 
69 #ifdef USE_ESP_IDF
70 esp_err_t configure_timer_frequency(ledc_mode_t speed_mode, ledc_timer_t timer_num, ledc_channel_t chan_num,
71  uint8_t channel, uint8_t &bit_depth, float frequency) {
72  bit_depth = *ledc_bit_depth_for_frequency(frequency);
73  if (bit_depth < 1) {
74  ESP_LOGE(TAG, "Frequency %f can't be achieved with any bit depth", frequency);
75  }
76 
77  ledc_timer_config_t timer_conf{};
78  timer_conf.speed_mode = speed_mode;
79  timer_conf.duty_resolution = static_cast<ledc_timer_bit_t>(bit_depth);
80  timer_conf.timer_num = timer_num;
81  timer_conf.freq_hz = (uint32_t) frequency;
82  timer_conf.clk_cfg = DEFAULT_CLK;
83 
84  // Configure the time with fallback in case of error
85  int attempt_count_max = SETUP_ATTEMPT_COUNT_MAX;
86  esp_err_t init_result = ESP_FAIL;
87  while (attempt_count_max > 0 && init_result != ESP_OK) {
88  init_result = ledc_timer_config(&timer_conf);
89  if (init_result != ESP_OK) {
90  ESP_LOGW(TAG, "Unable to initialize timer with frequency %.1f and bit depth of %u", frequency, bit_depth);
91  // try again with a lower bit depth
92  timer_conf.duty_resolution = static_cast<ledc_timer_bit_t>(--bit_depth);
93  }
94  attempt_count_max--;
95  }
96 
97  return init_result;
98 }
99 #endif
100 
101 #ifdef USE_ESP_IDF
102 constexpr int ledc_angle_to_htop(float angle, uint8_t bit_depth) {
103  return static_cast<int>(angle * ((1U << bit_depth) - 1) / 360.);
104 }
105 #endif // USE_ESP_IDF
106 
108  if (!initialized_) {
109  ESP_LOGW(TAG, "LEDC output hasn't been initialized yet!");
110  return;
111  }
112 
113  if (this->pin_->is_inverted())
114  state = 1.0f - state;
115 
116  this->duty_ = state;
117  const uint32_t max_duty = (uint32_t(1) << this->bit_depth_) - 1;
118  const float duty_rounded = roundf(state * max_duty);
119  auto duty = static_cast<uint32_t>(duty_rounded);
120  ESP_LOGV(TAG, "Setting duty: %" PRIu32 " on channel %u", duty, this->channel_);
121 #ifdef USE_ARDUINO
122  ledcWrite(this->channel_, duty);
123 #endif
124 #ifdef USE_ESP_IDF
125  auto speed_mode = get_speed_mode(channel_);
126  auto chan_num = static_cast<ledc_channel_t>(channel_ % 8);
127  int hpoint = ledc_angle_to_htop(this->phase_angle_, this->bit_depth_);
128  if (duty == max_duty) {
129  ledc_stop(speed_mode, chan_num, 1);
130  } else if (duty == 0) {
131  ledc_stop(speed_mode, chan_num, 0);
132  } else {
133  ledc_set_duty_with_hpoint(speed_mode, chan_num, duty, hpoint);
134  ledc_update_duty(speed_mode, chan_num);
135  }
136 #endif
137 }
138 
140  ESP_LOGV(TAG, "Entering setup...");
141 #ifdef USE_ARDUINO
142  this->update_frequency(this->frequency_);
143  this->turn_off();
144  // Attach pin after setting default value
145  ledcAttachPin(this->pin_->get_pin(), this->channel_);
146 #endif
147 #ifdef USE_ESP_IDF
148  auto speed_mode = get_speed_mode(channel_);
149  auto timer_num = static_cast<ledc_timer_t>((channel_ % 8) / 2);
150  auto chan_num = static_cast<ledc_channel_t>(channel_ % 8);
151 
152  esp_err_t timer_init_result =
153  configure_timer_frequency(speed_mode, timer_num, chan_num, this->channel_, this->bit_depth_, this->frequency_);
154 
155  if (timer_init_result != ESP_OK) {
156  ESP_LOGE(TAG, "Frequency %f can't be achieved with computed bit depth %u", this->frequency_, this->bit_depth_);
157  this->status_set_error();
158  return;
159  }
160  int hpoint = ledc_angle_to_htop(this->phase_angle_, this->bit_depth_);
161 
162  ESP_LOGV(TAG, "Configured frequency %f with a bit depth of %u bits", this->frequency_, this->bit_depth_);
163  ESP_LOGV(TAG, "Angle of %.1f° results in hpoint %u", this->phase_angle_, hpoint);
164 
165  ledc_channel_config_t chan_conf{};
166  chan_conf.gpio_num = pin_->get_pin();
167  chan_conf.speed_mode = speed_mode;
168  chan_conf.channel = chan_num;
169  chan_conf.intr_type = LEDC_INTR_DISABLE;
170  chan_conf.timer_sel = timer_num;
171  chan_conf.duty = inverted_ == pin_->is_inverted() ? 0 : (1U << bit_depth_);
172  chan_conf.hpoint = hpoint;
173  ledc_channel_config(&chan_conf);
174  initialized_ = true;
175  this->status_clear_error();
176 #endif
177 }
178 
180  ESP_LOGCONFIG(TAG, "LEDC Output:");
181  LOG_PIN(" Pin ", this->pin_);
182  ESP_LOGCONFIG(TAG, " LEDC Channel: %u", this->channel_);
183  ESP_LOGCONFIG(TAG, " PWM Frequency: %.1f Hz", this->frequency_);
184  ESP_LOGCONFIG(TAG, " Phase angle: %.1f°", this->phase_angle_);
185  ESP_LOGCONFIG(TAG, " Bit depth: %u", this->bit_depth_);
186  ESP_LOGV(TAG, " Max frequency for bit depth: %f", ledc_max_frequency_for_bit_depth(this->bit_depth_));
187  ESP_LOGV(TAG, " Min frequency for bit depth: %f",
189  ESP_LOGV(TAG, " Max frequency for bit depth-1: %f", ledc_max_frequency_for_bit_depth(this->bit_depth_ - 1));
190  ESP_LOGV(TAG, " Min frequency for bit depth-1: %f",
191  ledc_min_frequency_for_bit_depth(this->bit_depth_ - 1, (this->frequency_ < 100)));
192  ESP_LOGV(TAG, " Max frequency for bit depth+1: %f", ledc_max_frequency_for_bit_depth(this->bit_depth_ + 1));
193  ESP_LOGV(TAG, " Min frequency for bit depth+1: %f",
194  ledc_min_frequency_for_bit_depth(this->bit_depth_ + 1, (this->frequency_ < 100)));
195  ESP_LOGV(TAG, " Max res bits: %d", MAX_RES_BITS);
196  ESP_LOGV(TAG, " Clock frequency: %f", CLOCK_FREQUENCY);
197 }
198 
200  auto bit_depth_opt = ledc_bit_depth_for_frequency(frequency);
201  if (!bit_depth_opt.has_value()) {
202  ESP_LOGE(TAG, "Frequency %f can't be achieved with any bit depth", this->frequency_);
203  this->status_set_error();
204  }
205  this->bit_depth_ = bit_depth_opt.value_or(8);
206  this->frequency_ = frequency;
207 #ifdef USE_ARDUINO
208  ESP_LOGV(TAG, "Using Arduino API - Trying to define channel, frequency and bit depth...");
209  u_int32_t configured_frequency = 0;
210 
211  // Configure LEDC channel, frequency and bit depth with fallback
212  int attempt_count_max = SETUP_ATTEMPT_COUNT_MAX;
213  while (attempt_count_max > 0 && configured_frequency == 0) {
214  ESP_LOGV(TAG, "Trying initialize channel %u with frequency %.1f and bit depth of %u...", this->channel_,
215  this->frequency_, this->bit_depth_);
216  configured_frequency = ledcSetup(this->channel_, frequency, this->bit_depth_);
217  if (configured_frequency != 0) {
218  initialized_ = true;
219  this->status_clear_error();
220  ESP_LOGV(TAG, "Configured frequency: %u with bit depth: %u", configured_frequency, this->bit_depth_);
221  } else {
222  ESP_LOGW(TAG, "Unable to initialize channel %u with frequency %.1f and bit depth of %u", this->channel_,
223  this->frequency_, this->bit_depth_);
224  // try again with a lower bit depth
225  this->bit_depth_--;
226  }
227  attempt_count_max--;
228  }
229 
230  if (configured_frequency == 0) {
231  ESP_LOGE(TAG, "Permanently failed to initialize channel %u with frequency %.1f and bit depth of %u", this->channel_,
232  this->frequency_, this->bit_depth_);
233  this->status_set_error();
234  return;
235  }
236 
237 #endif // USE_ARDUINO
238 #ifdef USE_ESP_IDF
239  if (!initialized_) {
240  ESP_LOGW(TAG, "LEDC output hasn't been initialized yet!");
241  return;
242  }
243 
244  auto speed_mode = get_speed_mode(channel_);
245  auto timer_num = static_cast<ledc_timer_t>((channel_ % 8) / 2);
246  auto chan_num = static_cast<ledc_channel_t>(channel_ % 8);
247 
248  esp_err_t timer_init_result =
249  configure_timer_frequency(speed_mode, timer_num, chan_num, this->channel_, this->bit_depth_, this->frequency_);
250 
251  if (timer_init_result != ESP_OK) {
252  ESP_LOGE(TAG, "Frequency %f can't be achieved with computed bit depth %u", this->frequency_, this->bit_depth_);
253  this->status_set_error();
254  return;
255  }
256 
257  this->status_clear_error();
258 #endif
259  // re-apply duty
260  this->write_state(this->duty_);
261 }
262 
263 uint8_t next_ledc_channel = 0; // NOLINT(cppcoreguidelines-avoid-non-const-global-variables)
264 
265 } // namespace ledc
266 } // namespace esphome
267 
268 #endif
virtual void turn_off()
Disable this binary output.
Definition: binary_output.h:51
uint8_t next_ledc_channel
void update_frequency(float frequency) override
Dynamically change frequency at runtime.
virtual uint8_t get_pin() const =0
void status_set_error(const char *message="unspecified")
Definition: component.cpp:159
ledc_mode_t get_speed_mode(uint8_t channel)
Definition: ledc_output.cpp:40
void write_state(float state) override
Override FloatOutput&#39;s write_state.
uint16_le_t frequency
Definition: bl0942.h:72
void status_clear_error()
Definition: component.cpp:172
constexpr int ledc_angle_to_htop(float angle, uint8_t bit_depth)
void setup() override
Setup LEDC.
void dump_config() override
float ledc_min_frequency_for_bit_depth(uint8_t bit_depth, bool low_frequency)
Definition: ledc_output.cpp:51
optional< uint8_t > ledc_bit_depth_for_frequency(float frequency)
Definition: ledc_output.cpp:56
InternalGPIOPin * pin_
Definition: ledc_output.h:36
Implementation of SPI Controller mode.
Definition: a01nyub.cpp:7
esp_err_t configure_timer_frequency(ledc_mode_t speed_mode, ledc_timer_t timer_num, ledc_channel_t chan_num, uint8_t channel, uint8_t &bit_depth, float frequency)
Definition: ledc_output.cpp:70
float ledc_max_frequency_for_bit_depth(uint8_t bit_depth)
Definition: ledc_output.cpp:49
virtual bool is_inverted() const =0
bool state
Definition: fan.h:34