ESP32 藍牙程式升級為何失效？Arduino v4.0 BLE 權限、通知與遷移指南

ESP32 藍牙程式最難查的錯誤，往往出現在編譯成功以後：手機看得到裝置，卻讀不到感測值；連線看似正常，通知始終不更新；第一次測試能用，第二次連線就失敗。Arduino ESP32 v4.0 的藍牙重構，正好牽涉這幾個地方。

Espressif 在 2026 年 10 月 20 日說明新版設計，本文以 4.0.0-RC1 候選版為查核基準，對照官方遷移文件，整理既有 BLE 感測器與控制專案的升級路徑。這是版本遷移與設計檢查指南，並非宣稱所有開發板、手機與既有產品已完成實機相容性測試。

先確認你使用的是哪一套藍牙程式庫

Arduino 是開發環境與生態，Arduino core for ESP32 才是把程式接到 ESP32 底層的核心套件。這次的重大改動發生在 Espressif 核心套件隨附的 BLE 與 BluetoothSerial 程式庫，不代表所有名稱中有「BLE」的第三方套件都能照同一張對照表修改。

先查看專案的標頭檔、編譯輸出的程式庫路徑和套件版本。使用 BLEDevice.h 的舊核心範例、獨立安裝的 NimBLE-Arduino、以及 ArduinoBLE，各自有不同來源。若同一台電腦上有重複程式庫，先確認編譯器實際選中的版本，再處理 API 差異，否則可能改對程式卻編到另一份標頭。

4.0.0-RC1 的發布資料指出它以 ESP-IDF v6.1 為基礎。升級核心套件會同時改變底層依賴，驗證範圍因此不能只剩藍牙函式；Wi-Fi 共存、儲存設定與其他已使用的周邊也應納入回歸測試。正式專案先保留舊版可重建環境，在獨立分支測試候選版。4.0.0-RC1 官方版本頁。

把「看得到、連得上、讀得到」拆成不同檢查點

手機掃描到廣播，只證明它收到了廣播資料；連線成功，也不代表感測值已經可以讀取。BLE 的 GATT 資料模型由服務與特徵值組成，手機還要找到預期的 UUID，通過存取條件，才能讀寫或接收更新。把整條路徑拆開，錯誤就比較容易定位。

手機閱讀可左右滑動表格。

這張表是建議的排錯順序，並不表示每個症狀只有一個原因。實務上先用 BLE 檢查工具確認服務與存取行為，再回頭測自己的 App，能把韌體問題與 App 狀態問題分開。

Read／Write 是能力，Permission 決定誰能操作

新版把特徵值的屬性與存取權限分開。屬性描述它能否讀取、寫入或發送通知；權限描述在什麼連線安全條件下允許操作。只宣告 Read，不等於允許所有已連線手機讀取。這是升級後「裝置存在、資料卻讀不到」值得優先檢查的地方。

以一個溫度節點為例，可以把服務契約設計成：目前溫度提供讀取與通知，調整量測週期的設定值另設寫入權限，維護功能再安排更嚴格的操作流程。這是設計範例，實際是否公開讀值，取決於資料用途與隱私需求。不要為了排除一個權限錯誤，就把所有設定與控制指令一併開放。

配對、加密與身分驗證也要分清楚。Pairing 協商連線所需的安全資料，Bonding 則把金鑰保存供未來重連使用。裝置是否有螢幕、按鍵或輸入能力，影響可採用的配對方式；宣告了硬體做不到的確認方式，使用者可能根本無法完成配對。依官方安全文件設計流程時，要一起驗證首次配對與已綁定裝置重連。固定版本的 BLE 安全與配對說明。

一次遷移一個行為，不只逐字替換名稱

下面以原先使用核心內建 BLE 程式庫的 v3.x 專案為例。表中的識別字用來查找程式位置；它不是可以獨立編譯的完整草稿。每完成一項，就編譯並檢查對應行為，比一次套用大量文字取代容易追蹤問題。

手機閱讀可左右滑動表格。

完整的參數與移除項目請對照4.0.0-RC1 BLE 遷移文件。我們建議先移出原專案中的繼電器、顯示器與網路上傳，只保留一個簡單服務，驗證廣播、讀取與寫入，再把其餘功能逐項加回來。這能減少「藍牙改完，卻被另一個周邊問題干擾」的排錯成本。

通知自動建立描述元，不代表手機自動訂閱

CCCD 是用戶端設定通知／指示的描述元。新版在宣告 Notify 或 Indicate 時，會處理相應描述元的建立，省掉部分舊版手動管理工作；手機端仍需要進行訂閱。當讀取成功卻收不到更新，應先確認訂閱狀態，再檢查韌體是否更新了特徵值、是否發出了通知，以及通知送往哪個連線。

假設一個節點讓兩支手機連線，第一支訂閱、第二支只讀取，預期行為就應分開記錄。當第一支手機斷線後重連，要重新驗證服務探索和訂閱；不能僅因第一次連線成功，就假設後續狀態一定相同。新版提供廣播給已訂閱連線及指定連線的通知操作，應按產品需求明確選擇。BLE 架構與連線設計。

若用途是「控制成功後回覆結果」，還要定義應用層確認。收到一個按鈕寫入，不等於馬達已轉到指定位置；韌體應以真正的執行結果更新狀態，必要時帶上命令編號，讓 App 能區分舊通知與本次操作。這是控制協定設計，無法只靠升級 BLE 程式庫取得。

物件還在，不代表連線仍有效

新版以共用控制代碼管理物件，有助於減少手動配置與釋放資源的負擔。但這不會延長無線連線的生命：遠端裝置離線、藍牙堆疊停止或資源已釋放時，程式仍要檢查操作結果。尤其是事件函式裡保存的連線資訊，不應被當成永遠有效的目標。

對需要長時間運作的感測節點，建議明確寫出初始化、廣播、已連線、斷線後恢復等狀態。每個狀態只允許合適的操作；連線數變動時也要決定是否重新廣播，以及是否仍接受新裝置。這比在主迴圈中反覆嘗試一個已失效的操作更容易維護。

新版的 BTStatus 提供結構化錯誤，例如逾時、未連線、驗證失敗、權限不足或不支援。把「不支援」當成需要無限重試的暫時錯誤，並不會讓功能出現；逾時則可以安排有限次重試，並留下間隔與失敗原因。這些分類在Espressif 藍牙重構說明中有完整介紹。

統一 API 之後，晶片差異仍然存在

同一套介面能降低不同底層堆疊的程式差異，但不會替晶片增加不存在的無線能力。原始 ESP32 的 Bluetooth Classic 與 BLE 能力，不能直接套到 S3、C3、C6 等型號；S2 更不能因為名稱屬於 ESP32 家族，就被當成具有原生藍牙無線電的板子。選板時請查完整型號與官方支援表。Espressif 藍牙能力與協定堆疊說明。

BluetoothSerial 的 SPP 應用屬於 Classic Bluetooth；BLE 中提供類似串列傳輸的資料通道，並不因此變成相同協定。若舊設備是以 Classic SPP 配對通訊，換板前先確認該晶片與用戶端是否支援原協定，再決定保留或重做通訊層。新版 BluetoothSerial 的多對端改動也有獨立遷移說明。BluetoothSerial 遷移文件。

同樣地，「支援 Bluetooth 5」不足以代表任意距離、吞吐量或手機相容性。協商的連線參數、封包量、天線、供電與 Wi-Fi 共存都會影響結果。先把應用要傳的資料量和容許延遲寫清楚，才有辦法判斷升級是否帶來實際改善。

用一張回歸清單決定是否值得正式切換

建議至少覆蓋首次配對、已綁定重連、取消綁定、超出範圍後返回、節點重啟、手機重啟，以及預期用戶端數量下的操作。若同時使用 Wi-Fi，加入實際上傳流量；若控制實體設備，先接測試負載驗證命令和回報一致。這些是測試建議，應依產品用途調整。

紀錄不只寫「成功」。保留板子完整型號、核心版本、程式庫來源、手機型號與系統版本，再附上每種情境的連線結果和錯誤日誌。對有配對資料的既有裝置，先測保留金鑰的升級路徑；只有在明確的測試案例裡才清除綁定，避免用恢復原廠設定掩蓋真正的升級相容問題。

若現有量產專案穩定運作，目前較合理的做法是另開測試分支，逐步累積 v4.0 的相容性證據。新專案則可以提早依新版的權限與生命週期模型設計，但發布前仍應固定版本並完成自己的測試矩陣。RC1 是適合開始驗證的時間點，切換決策要由專案測試結果決定。

開發板與整合選型

台灣智能感測科技有限公司（TaiwanSensor）提供 ESP32 開發板、感測器與物聯網相關產品資訊。詢問藍牙應用時，請提供開發板完整型號、目前核心版本、使用 BLE 或 Classic SPP，以及連線對象是手機、電腦還是既有設備。若尚未決定板型，可先閱讀ESP32 C3、S3 選購指南，再由TaiwanSensor 官網查詢產品與聯絡資訊。