更新 VibeKeys 固件

本指南介绍如何更新 VibeKeys 设备上的固件。根据你的情况，有两种更新方式。

固件已预装

你的 VibeKeys Max 设备出厂时已预装固件。首次设置无需刷写固件，请直接前往 快速入门 配置设备。

什么是固件？

固件是运行在 VibeKeys 设备硬件上的软件，负责蓝牙连接、WiFi 处理、按键响应和与电脑的通信。

如何选择正确的方式

情况	方式	耗时
设备已在 0.4.x 且工作正常	OTA 更新（见下方）	5-10 分钟
设备还在 0.3.x（任何状态）	ESP LaunchPad（见后续）	10-15 分钟
设备无法连接或出现故障	ESP LaunchPad（见后续）	10-15 分钟
设备需要恢复出厂设置	Setting → Clear config，或 ESP LaunchPad	1-15 分钟

从 0.3.x 升级到 0.4.0？请先读这里

v0.4.0 改变了分区布局，因此 0.3.x 设备无法通过 OTA 升级到 0.4.0。必须用下方的 ESP LaunchPad 方式通过 USB 完整刷写一次镜像。这会清空已保存的配置（WiFi / MQTT broker / ASR），请准备好之后在 setup 页面重新配置设备。之后的升级恢复正常的 OTA 方式。

方式一：OTA 更新（适用于已在 0.4.x 的设备）

设备工作正常、已连接 WiFi、且已在 0.4.x 时使用此方式。 OTA（空中下载）更新允许你通过无线方式安装新固件——无需 USB 线，也无需重启到特殊模式。

第一步：在设备上打开 OTA Update

1. 开启 VibeKeys Max
2. 在启动菜单中选择 Setting（NEXT 移动，ACCEPT 确认）
3. 选择 OTA Update

设备会连接你保存过的某个 WiFi 网络并启动更新服务，屏幕上会显示下一步操作。

第二步：安装新固件

在设备屏幕上选择任一选项：

• 浏览器上传：在浏览器中打开设备上显示的更新地址，下载下面对应的 OTA 镜像，上传并点击 Start。
• download-latest：在设备上选择 download-latest，设备会直接从 GitHub 拉取最新 release——不需要电脑。

OTA 镜像（仅适用于已在 0.4.x 的设备——不确定时参见识别你的版本）：

V1（宽屏）

下载：vibekeys_ota.bin

V2（高屏）

下载：vibekeys_max2_ota.bin

屏幕会显示更新进度。完成后设备自动重启进入新固件。

无需 USB 线

OTA 更新完全通过 WiFi 完成——无需 USB 连接。设备把新镜像写入备用分区后重启进入，更新失败或中断时可以重试。

---

方式二：ESP LaunchPad（USB 刷写——恢复、恢复出厂、0.3.x → 0.4.0 升级）

以下情况请使用此方式：从 0.3.x 升级、设备恢复、恢复出厂设置，或 OTA 更新不可用。它通过 USB 刷写完整镜像（bootloader + 分区表 + 固件）。

配置会被清空

USB 完整刷写会清除已保存的配置（WiFi / MQTT broker / ASR）。刷写完成后请在 setup 页面重新配置设备。

准备工作

你需要

• VibeKeys Max 设备
• 一根 USB 数据线（USB-A 转 USB-C 或 USB-C 转 USB-C，取决于你的电脑）
• 一台带浏览器的电脑（推荐 Chrome 或 Edge）
• 网络连接

第一步：连接设备

1. 找到 USB-C 接口：位于 VibeKeys Max 设备右侧
2. 将 USB 线一端插入设备
3. 另一端连接电脑

使用数据线

请确保使用支持数据传输的 USB 线，而不是只能充电的线。

第二步：打开 ESP Launch Pad

1. 打开浏览器（推荐 Chrome 或 Edge）

2. 访问：

   https://espressif.github.io/esp-launchpad/?flashConfigURL=https://vibekeys.dev/firmware/vibekeys.toml

第三步：连接你的设备

1. 点击界面顶部的 "Connect"
2. 浏览器请求 USB 设备权限时选择允许
   • 点击 "Allow" 授权
   • 这是网页工具与设备通信所必需的

第四步：更新固件

1. 在下拉菜单中选择你的版本——选择与设备匹配的 V1 或 V2（不确定时参见识别你的版本）
2. 点击 "Flash" 开始刷写
3. 等待完成——通常需要 2-5 分钟

过程会显示：

• 从 VibeKeys 服务器下载固件
• 擦除旧固件
• 写入新固件
• 校验安装

请勿断开连接

整个更新过程中请保持 USB 连接。中断更新可能导致设备无法使用。

刷写完成后，设备会启动新固件。打开 setup 页面配置 WiFi、MQTT broker 和语音输入。

相关文档

• 快速入门 - 新设备的首次设置
• 按键与旋钮 - 了解设备控制方式
• 键盘模式 - 把 VibeKeys Max 当作蓝牙键盘使用
• Claude Code 状态集成 - 在设备屏幕上实时显示 Claude Code 状态
• 故障排查 - 解决常见的设置和模式切换问题

需要帮助？

如果遇到本指南未涵盖的问题：

1. 查看 GitHub Issues - 类似问题可能已有解决方案
2. 联系支持：vibekeys-customer-support@secondstate.io
3. 加入社区：查看 GitHub 仓库的讨论和更新