确认实际参与编译的 core
从2.x迁移到3.0时,ledcSetup和ledcAttachPin已被移除。旧教程里的程序可能在产生PWM之前就编译失败。这个错误不能判断舵机或供电是否正常。
查看编译日志中的开发板包和core版本。保留旧工程及其依赖,检查第三方库支持的core后再修改。这里提供的是固定迁移参考,不保证所有旧库兼容。
按用途迁移 API
ledcAttach自动选择通道;需要明确通道时使用ledcAttachChannel。两者都返回配置是否成功。重复使用已配置的通道时,新传入的频率和分辨率会被忽略。
按引脚调用ledcWrite时,0表示GPIO0,不是通道0。输出在GPIO18就传入18;需要按通道寻址则使用ledcWriteChannel。整数参数含义用错仍可能通过编译,因此还要检查返回值。
横向滚动以比较全部栏目。
| 用途 | Arduino-ESP32 2.x | Arduino-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或芯片目标会被拒绝。
#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 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 bit | 50 Hz · 14 bit |
|---|---|---|
| ESP32 · APB 80 MHz | D = 6250 · 超出范围 | D = 97.65625 · 可实现 |
| ESP32-S3 / C3 · XTAL 40 MHz | D = 3125 · 超出范围 | D = 48.828125 · 可实现 |
从症状选择下一步检查
从最早失败的阶段开始检查。在报告中保留时钟、频率、分辨率、引脚及通道,便于别人复现声明配置。
- 找不到ledcSetup/ledcAttachPin:先确认安装的core,再按对应表迁移。
- 配置返回false:核对真实引脚、外设保留及频率/分辨率组合。
- 编译成功但占空比不变:区分引脚与通道,并检查写入结果。
- 多个频率一起变化:检查共享定时器;不同通道不等于相互独立。
迁移常见问题
为什么提示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。其他目标需要在对应外部工具链编译。