Microduck Robot●microduck-robot.com

ESP32 LEDC 3.x Migration: Pins, Channels and Timers

Replace the removed setup/attach calls and check every pin-versus-channel argument before changing hardware. This guide uses Arduino-ESP32 3.3.8; separate channels do not guarantee independent frequency changes.

Examples: Arduino-ESP32 3.3.8 / ESP-IDF 5.5.4, Arduino CLI 1.6.0. Sources checked 2026-11-15.

Identify the core that is actually compiling

The 2.x-to-3.0 migration removed ledcSetup and ledcAttachPin. A sketch copied from an older tutorial can therefore fail before any PWM is produced. That compiler error does not diagnose the servo or its supply.

Read the selected board package and core version in the build output. Keep the old project and its dependencies; check a third-party library’s supported core before replacing calls. This example is a fixed migration reference, not a promise that every old library works.

Translate the API by intent

ledcAttach chooses a channel automatically. Use ledcAttachChannel when the channel must be explicit. Both report whether setup succeeded. Reusing an already configured channel ignores the newly supplied frequency and resolution.

In the pin-based ledcWrite call, 0 means GPIO0, not channel 0. For an output on GPIO18, pass 18; if channel addressing is intentional, use ledcWriteChannel. An integer in the wrong role can compile, so check the return value as well as the argument.

Scroll sideways to compare all columns.

IntentArduino-ESP32 2.xArduino-ESP32 3.3.8
Attach, automatic channelledcSetup(channel, Hz, bits) + ledcAttachPin(pin, channel)ledcAttach(pin, Hz, bits)
Attach, explicit channelledcSetup(channel, Hz, bits) + ledcAttachPin(pin, channel)ledcAttachChannel(pin, Hz, bits, channel)
Write dutyledcWrite(channel, duty)ledcWrite(pin, duty) / ledcWriteChannel(channel, duty)

Compile a fixed classic ESP32 example

This complete sketch targets the named classic ESP32 profile: GPIO18, channel 0, APB 80 MHz, 50 Hz, 14 bits and a 1500 µs pulse request. It rounds the duty calculation and checks every setup/write result. The code rejects a different core or chip target.

Complete classic ESP32 sketch · Arduino-ESP32 3.3.8
#include <Arduino.h>
#include <esp_arduino_version.h>

#if ESP_ARDUINO_VERSION != ESP_ARDUINO_VERSION_VAL(3, 3, 8)
#error "Use Arduino-ESP32 3.3.8 for this example"
#endif
#if !CONFIG_IDF_TARGET_ESP32
#error "This example targets the classic ESP32 profile"
#endif

constexpr uint8_t SERVO_PIN = 18;
constexpr uint8_t SERVO_CHANNEL = 0;
constexpr uint32_t FREQ_HZ = 50;
constexpr uint8_t RES_BITS = 14;
constexpr uint32_t PULSE_US = 1500;
constexpr uint32_t DUTY =
    (uint64_t(PULSE_US) * FREQ_HZ * (1UL << RES_BITS) + 500000ULL)
    / 1000000ULL;

void setup() {
  Serial.begin(115200);
  bool ok = ledcSetClockSource(LEDC_USE_APB_CLK);
  if (ok) {
    ok = ledcAttachChannel(SERVO_PIN, FREQ_HZ, RES_BITS, SERVO_CHANNEL);
  }
  if (ok) {
    ok = ledcWrite(SERVO_PIN, DUTY);  // pin, not channel
  }
  Serial.println(ok ? "LEDC configured" : "LEDC setup failed");
}

void loop() {}

Save it as ledc_migration/ledc_migration.ino and compile with the matching pinned tools. The pulse request is an example, not a calibrated neutral or travel limit for every servo. S3/C3 projects must use their own planner profile and compile externally; this sketch is classic-only.

External compile · Arduino CLI 1.6.0
arduino-cli version
arduino-cli core list
arduino-cli compile --fqbn "esp32:esp32:esp32:FlashMode=dio,FlashSize=4M,PartitionScheme=default" --export-binaries ./ledc_migration

Check frequency and resolution together

For a fixed clock, frequency and bit depth together determine the divider. At low frequency, reducing bit depth increases the required divider and can exceed the driver range. A failed setup is not always cured by choosing fewer bits. The table uses this site’s fixed profile clocks.

At 50 Hz and 14 bits, one nominal duty step is about 1.2207 µs. A 1500 µs request rounds to 1229 ticks, about 1500.2441 µs. These are calculated values under the pinned divider model, not an oscilloscope measurement or a physical servo-angle guarantee.

Scroll sideways to compare all columns.

Pinned profile clock50 Hz · 8 bit50 Hz · 14 bit
ESP32 · APB 80 MHzD = 6250 · outside rangeD = 97.65625 · feasible
ESP32-S3 / C3 · XTAL 40 MHzD = 3125 · outside rangeD = 48.828125 · feasible

Separate pins, channels and shared timers

A channel owns its duty setting; a timer supplies frequency and resolution. The pinned implementation can reuse a timer when those settings match. Different channels can therefore have different duty values while sharing timing.

Changing the frequency of one timer user can affect its other users. Selecting different channel numbers alone is not an isolation strategy. Inspect group/timer assignments in the planner and keep this example fixed-frequency; no dynamic-retuning workaround is promised.

Diagnose the symptom before changing code

Use the first failing stage to choose the next check. Keep the requested clock, frequency, resolution, pin and channel in the report so another person can reproduce the configuration.

  1. Missing ledcSetup/ledcAttachPin: verify the installed core, then use the matching migration row.
  2. Setup returns false: check the exact board pin, peripheral reservations and frequency/resolution combination in the planner.
  3. Code compiles but duty does not change: distinguish pin from channel and check the write result.
  4. Two outputs change frequency together: inspect shared timers; do not assume channel separation proves independence.

Migration questions

Why is ledcSetup not declared?

It belongs to the removed API in the historical 2.x-to-3.0 migration. Check the actual core version, then replace the setup/attach pair with the appropriate 3.3.8 API; this error alone says nothing about wiring.

Can I keep ledcWrite(0,duty)?

Only if GPIO0 is the intended configured pin. In 3.3.8 ledcWrite addresses a pin. For channel 0 use ledcWriteChannel(0,duty); for the example’s GPIO18 use ledcWrite(18,duty).

Why do different channels change frequency together?

They may share a timer. Duty belongs to the channel, while frequency and resolution belong to its timer. The pinned implementation can reuse matching timers.

Will an S3 or C3 project run in the classic simulator?

No. The planner supports the named S3/C3 configurations and project export, but the current firmware emulator executes classic ESP32 only. Compile those projects in the matching external toolchain.

Project sources

Contact us