MicroDuck 第一次连接：先找机，再配 Wi-Fi 和打开控制台

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 说明。