Microduck Robot●microduck-robot.com

ESP32 LEDC 3.x 迁移:引脚、通道与定时器

先替换已移除的初始化调用,再确认参数表示引脚还是通道,之后才调整硬件。本指南固定使用 Arduino-ESP32 3.3.8;通道不同不代表动态改频相互独立。

示例基线:Arduino-ESP32 3.3.8 / ESP-IDF 5.5.4、Arduino CLI 1.6.0。资料核对日:2026-11-15。

确认实际参与编译的 core

从2.x迁移到3.0时,ledcSetup和ledcAttachPin已被移除。旧教程里的程序可能在产生PWM之前就编译失败。这个错误不能判断舵机或供电是否正常。

查看编译日志中的开发板包和core版本。保留旧工程及其依赖,检查第三方库支持的core后再修改。这里提供的是固定迁移参考,不保证所有旧库兼容。

按用途迁移 API

ledcAttach自动选择通道;需要明确通道时使用ledcAttachChannel。两者都返回配置是否成功。重复使用已配置的通道时,新传入的频率和分辨率会被忽略。

按引脚调用ledcWrite时,0表示GPIO0,不是通道0。输出在GPIO18就传入18;需要按通道寻址则使用ledcWriteChannel。整数参数含义用错仍可能通过编译,因此还要检查返回值。

横向滚动以比较全部栏目。

用途Arduino-ESP32 2.xArduino-ESP32 3.3.8
连接,自动通道ledcSetup(channel, Hz, bits) + ledcAttachPin(pin, channel)ledcAttach(pin, Hz, bits)
连接,指定通道ledcSetup(channel, Hz, bits) + ledcAttachPin(pin, channel)ledcAttachChannel(pin, Hz, bits, channel)
写入占空比ledcWrite(channel, duty)ledcWrite(pin, duty) / ledcWriteChannel(channel, duty)

编译经典 ESP32 的固定示例

完整程序针对指定的经典ESP32配置:GPIO18、通道0、APB 80 MHz、50 Hz、14 bit和1500 µs目标脉宽。程序对占空比数值取整,并检查配置与写入结果;其他core或芯片目标会被拒绝。

经典ESP32完整程序 · 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() {}

保存为ledc_migration/ledc_migration.ino,用固定版本工具编译。这里的脉宽不是所有舵机经过校准的中位或行程限位。S3/C3工程应选择各自的配置并在外部编译;这份程序只用于经典ESP32。

外部编译 · 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

一起核对频率和分辨率

固定时钟下,频率和位数共同决定分频值。低频时减少位数会增大所需分频值,可能超出驱动范围,因此降低分辨率不一定能解决失败。表格使用本站配置固定的时钟。

在50 Hz、14 bit下,一个标称占空比步长约为1.2207 µs。1500 µs请求取整为1229步,约1500.2441 µs。这是固定分频模型的计算结果,不是示波器测量,也不保证实物舵机角度。

横向滚动以比较全部栏目。

固定配置时钟50 Hz · 8 bit50 Hz · 14 bit
ESP32 · APB 80 MHzD = 6250 · 超出范围D = 97.65625 · 可实现
ESP32-S3 / C3 · XTAL 40 MHzD = 3125 · 超出范围D = 48.828125 · 可实现

区分引脚、通道与共享定时器

通道保存占空比,定时器决定频率和分辨率。固定版本的实现会在设置相同时复用定时器,因此不同通道可以拥有不同占空比,却共用同一时间基准。

改变频率可能影响同一定时器的其他使用者。只换成不同通道号不能证明独立;应在配置器查看group/timer分配,并让本示例保持固定频率。这里不承诺动态改频的独立分配方案。

从症状选择下一步检查

从最早失败的阶段开始检查。在报告中保留时钟、频率、分辨率、引脚及通道,便于别人复现声明配置。

  1. 找不到ledcSetup/ledcAttachPin:先确认安装的core,再按对应表迁移。
  2. 配置返回false:核对真实引脚、外设保留及频率/分辨率组合。
  3. 编译成功但占空比不变:区分引脚与通道,并检查写入结果。
  4. 多个频率一起变化:检查共享定时器;不同通道不等于相互独立。

迁移常见问题

为什么提示ledcSetup未声明?

它属于从2.x到3.0迁移时移除的API。确认实际core后,把初始化与引脚连接改为对应的3.3.8 API;这个错误本身不能检查接线。

ledcWrite(0,duty)可以原样保留吗?

仅当你确实要操作已配置的GPIO0。3.3.8的ledcWrite按引脚寻址;通道0应使用ledcWriteChannel(0,duty),示例GPIO18使用ledcWrite(18,duty)。

不同通道为什么会一起改频?

它们可能共用定时器。占空比属于通道,频率和分辨率属于定时器;固定版本实现会复用相同设置。

S3或C3工程能在经典模拟器执行吗?

不能。配置器支持指定S3/C3板卡配置与工程导出,但固件模拟器只执行经典ESP32。其他目标需要在对应外部工具链编译。

项目资料来源

联系我们