確認實際參與編譯的核心
從2.x遷移到3.0時,ledcSetup與ledcAttachPin已被移除。舊教學的程式可能在產生PWM之前就編譯失敗;這個錯誤無法判斷伺服馬達或供電是否正常。
查看編譯紀錄中的開發板套件與核心版本。保留原專案及相依套件,確認第三方程式庫支援的核心後再修改。這是固定版本的遷移參考,不保證所有舊程式庫相容。
依用途遷移 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目標脈寬。程式會將占空比數值取整,並檢查設定及寫入結果;其他核心或晶片目標會被拒絕。
#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:先確認安裝的核心,再依對照表遷移。
- 設定回傳false:核對實際腳位、周邊保留與頻率/解析度組合。
- 編譯成功但占空比不變:區分腳位與通道,並檢查寫入結果。
- 多個頻率一起改變:檢查共用計時器;不同通道不等於互不影響。
遷移常見問題
為什麼顯示ledcSetup未宣告?
它屬於從2.x到3.0遷移時移除的API。確認實際核心後,把初始化與腳位連接改為對應的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。其他目標需在對應的外部工具鏈編譯。