MicroDuck 第一次連線：先找機，再配 Wi-Fi 和開啟控制檯

繁體版於 2026 年 10 月 31 日上線。以下另列原資料修訂日，舊版紀錄不因本地化變成新發布。原資料修訂： 2026年10月16日

10 月 16 日複核：Beta 板升級後先重新認機器

官方 daemon 0.17.4 原於 10 月 15 日釋出。它只把 Beta 板預設名稱所依據的 SoC 序號，從 U-Boot 提供的 device-tree 值改為核心 /proc/cpuinfo 的 Serial。上游兩塊 Beta 板原先同名 duck-d041；固定原始碼測試裡其中一塊現在得到 duck-2b6d。這是作者報告與原始碼核查，本站未升級實體機。手動設定過的名稱會保留；Zero 3W 的序號仍從 device tree 讀取，不因這次改動換預設名。Beta 的聲音/合唱標識及遠端訪問硬體 ID 也可能隨序號源改變，別公開貼出序號或硬體 ID。

升級後若舊預設名無法選中機器，先在電腦重新執行 uvx duckctl scan，按實際顯示名更新 --name 或 DUCK_ROBOT，不要照抄舊 duck-d041 或本文的示例 duck-c51b。已有配對的機器可能改變廣播表現；一次掃描稀疏不等於離線，不能僅憑改名就刪除 Bluetooth bond。這次改的是身份序號來源，不是普通 BLE 配對或密碼傳輸安全修復；下文開發版明文設定網路限制繼續適用。名稱與選擇規則 · 聲音種子原始碼。

適用範圍與最短路線

這是本站 2026 年 10 月 15 日補上的官方實體機首次連線步驟，依據 0.17.2 固定版 duckctl 檔案和客戶端原始碼。官方正式版原於 10 月 13 日釋出；首次找機不是今天新增的上游功能。本站沒有連線實體機、改 Wi-Fi 或測試影片。kissqy 的 R1 復刻映象基於另一套舊軟體，不應假定有同樣的 BLE 與控制檯入口。

電腦安裝好 uv 後執行以下命令。第一行只讀周圍藍芽廣播，不連線、無需 PIN；第二行會連線讀取身份，首次可能配對並驗證本機 PIN。把示例名 duck-c51b 換成掃描所得的自己的那臺，別省略 --name：多臺同場時無名稱會選先發現的機器。uvx 可能複用本地快取，也可能解析新發布的客戶端；本文核查的是 0.17.2，行為不同時先對照客戶端和機器人實際版本。

uvx duckctl scan
uvx duckctl --name duck-c51b info

出現 no address 時怎麼走

下列 Wi-Fi 查詢會連線機器，走藍芽而不要求先有 SSH；它們需要機器 PIN（--pin、DUCK_PIN，未設定時檔案預設 000000）。前面的 scan 則只看廣播，不連機也不需 PIN。PIN 校驗不等於藍芽鏈路加密；固定 btd 服務原始碼寫明普通開發板預設關閉配對、PIN 可經無線鏈路明文傳輸。公開提問時遮去藍芽地址、SSID 和 PIN。

uvx duckctl --name duck-c51b wifi status
uvx duckctl --name duck-c51b wifi scan

確實要換網路時，才把下面的示例名、SSID 和密碼在本機改成真實值。官方 CLI 的 --psk 是命令列引數，沒有這裡可用的隱藏式密碼輸入；共享電腦的程序引數和 shell 歷史可能暴露它。更關鍵的是，這份 0.17.2 開發版 btd 預設不要求藍芽配對、鏈路不加密；附近的人可能讀到 PIN 與 Wi-Fi 密碼。請只把此流程用於可信近場、隔離的測試網路和臨時憑據；不要把家庭或工作網路密碼當成安全設定網路輸入，也別把填好密碼的命令貼到社群。服務與路由原始碼。此操作會改機器網路，舊 Wi-Fi 上的 SSH 斷開可能正是切網結果；伺服器端最長輪詢 45 秒，客戶端另設 60 秒截止，都不是入網成功保證。開放網路才省略 --psk。固定說明。

uvx duckctl --name duck-c51b wifi connect 'YOUR_SSID' --psk 'YOUR_WIFI_PASSWORD'

有 IP 後，網頁和信令分開查

再讀 Wi-Fi 狀態和 IP；open --print 只列印控制檯網址，不開啟瀏覽器。正常 open 才會開啟機器人內建網頁。沒有網路地址就不能用這個 WebRTC 控制檯。網頁在 8080 埠，頁面的影片/操作信令另走 8443；如果網頁能開啟卻提示信令沒有響應，先查到 8443 的區域網路徑或防火牆，不要為此重配藍芽，更不要直接向公網開放埠。

uvx duckctl --name duck-c51b wifi status
uvx duckctl --name duck-c51b ip
uvx duckctl --name duck-c51b open --print

控制檯裡有真實運動按鈕；Stop 只停止網頁發出的指令，不會切斷伺服馬達供電，不是實體急停。官方控制檯說明。若仍卡住，可在技術討論寫明客戶端/機器人版本、掃描是否見機器、是否顯示 no address、失敗在 8080 網頁還是 8443 信令；先刪藍芽地址、序列號、區域網 IP、SSID、PIN、Wi-Fi 密碼和帳號。控制器有連線卻不響應時，另看實體控制器分層排錯；UDP 停走時序見 0.17.2 說明。