跳到主要内容
版本：0.4.x

故障排查

本页用于解决 VibeKeys 设置和连接中的常见问题。

遥控模式里看不到任何会话​

会话选择器为空，通常是设备和 vibetty 没有连到同一个 MQTT broker。

  1. 检查电脑上的 vibetty 是否在运行，且其 MQTT 按钮显示 conn。如果只显示 brkr，说明内置 broker 已启动但 vibetty 本身没有连上——请重新运行 vibetty setup。
  2. 检查设备上保存的 MQTT broker 地址（通过 setup 页面）是否指向 vibetty 使用的同一个 broker。使用电脑上的内置 broker 时，设备需要填 mqtt://你电脑的局域网IP:1883。
  3. 检查两端是否都在 0.4.x——固件 v0.4.0+ 和 vibetty 0.4.x。MQTT 协议在 0.4.0 有变更，旧固件无法连接或正常显示。请按需升级固件或 vibetty。
  4. 检查设备是否在线：如果你当前使用的 WiFi 不在已保存的网络列表中（或只有 5GHz），设备就无法访问 broker。请在 setup 页面添加该网络。

完整设置流程请参考 遥控模式。

setup 页面里找不到设备​

setup 页面通过 Web Bluetooth（BLE）与设备通信。

  1. 请使用 Chrome 或 Edge，且必须是 HTTPS——其他浏览器不支持 Web Bluetooth。
  2. 设备必须处于键盘模式（在启动菜单中选择 Keyboard）——配置服务只在该模式下广播。
  3. 如果设备已经作为蓝牙键盘连上了某台电脑或手机，它会停止广播。在设备上按 ACCEPT 键重新开始广播，然后再点击 Connect。

语音输入没有出文字​

  1. 在 setup 页面核对 ASR 字段：URI、API key、model 必须与你的 Whisper 兼容服务匹配。遥控模式下，未配置 ASR 服务时 MIC 键完全没有反应。
  2. 键盘模式下，确认 setup 页面上的 "prefer built-in ASR" 已勾选——否则 MIC 会把按键发给电脑，而不是自己录音。（该开关对遥控模式无效，遥控模式始终用设备录音。）
  3. 检查 MIC 模式：PTT 需要按住按键说话；Toggle 点一下开始、再点一下停止。

详见遥控模式下的语音输入或键盘模式下的语音输入。

无法通过 OTA 更新固件​

  • 0.3.x 设备无法 OTA 升级到 0.4.0——分区布局已变更。请一次性使用 ESP LaunchPad USB 方式（见更新固件），之后的更新恢复 OTA。
  • 已在 0.4.x 的设备通过 Setting → OTA Update 更新。请确保设备能连上已保存的某个 WiFi 网络，并使用与硬件版本匹配的 OTA 镜像。

设备连不上 WiFi​

  • VibeKeys Max 只能连接 2.4GHz 网络——纯 5GHz 网络永远连不上。
  • 列表顺序就是优先级顺序：开机时设备会连接范围内排第一的已保存网络。请在 Setting → WiFi networks 或 setup 页面调整列表顺序、清理不用的网络。