Vico Keyboard
使用说明书

产品概览

Vico Keyboard 是一款面向效率操作、开发工作流和 Vibe Coding 场景的 8 键可编程小键盘。它集成 128 × 64 OLED、8 颗 RGB 灯、EC11 旋钮、麦克风，以及 USB / Bluetooth LE 双模连接。

部件布局

连接方式

USB 模式

1. 将模式拨片拨到 3.3 V 一侧。
2. 使用支持数据传输的 USB Type-C 线连接电脑。仅充电线无法用于配置或固件升级。
3. 系统会识别“Vico Keyboard”；打开 VicoDeck 后点击顶部“USB 连接设备”。

• 支持键盘、多媒体按键、配置同步、OLED、RGB、状态转发与语音数据传输。
• 由外部供电，不执行自动休眠。
• 未检测到 USB 数据连接时，OLED 会显示“PLUG IN USB”。

蓝牙模式

1. 将模式拨片拨到接地（GND）一侧。
2. 在 Windows“设置 → 蓝牙和设备”中搜索并配对“Vico Keyboard”。
3. 配对成功后即可使用基础键盘与多媒体按键。需要配置功能时，再在 VicoDeck 中连接蓝牙 GATT。

提示：模式拨片支持热切换。切换时固件会先释放旧模式的按键状态，避免出现按键卡住。若切换后电脑未重新识别 USB 端口，请关闭小键盘再重新打开。

两类蓝牙连接的区别

默认按键与五套预设

默认导航预设 P1

Ctrl + Win 是组合键本身，是否出现可见结果取决于当前操作系统和应用；KEY8 建议保留为 Fn，以便使用机身组合操作。

内置预设

在键盘上切换预设

按住 KEY8（Fn），再按 KEY1–KEY5，可分别切换到 P1–P5。切换组合键本身不会向电脑发送普通按键。当前预设会保存到小键盘，并与已连接的 VicoDeck 同步。

机身操作

Fn 组合键

设置菜单操作

菜单包含 PROFILE、OLED、RGB LIGHT、CONNECTION、KEY TEST、DEVICE INFO、FACTORY RESET 与 EXIT。设置菜单中不会向电脑发送 HID 按键，修改会立即保存。

旋钮

录音期间会暂停普通按键、旋钮转动及其他非必要数据传输，以保证音频传输稳定。

安装与认识 VicoDeck

安装

1. 从 VicoDeck 官方 GitHub Release 或更新服务器下载安装程序。
2. 运行安装程序并完成安装。Windows SmartScreen 可能因应用尚未使用商业代码签名而显示“未知发布者”，请确认安装包来自官方发布地址。
3. 启动 VicoDeck。软件可最小化到系统托盘，并可在设置中开启“开机自启动”。

主要页面

顶部状态区

• “USB 连接设备”只用于 WebHID 配置通道，并会校验 Vico 产品名称与 VID/PID，避免误连其他键盘。
• 连接状态显示当前配置通道；蓝牙 HID 已配对不等于蓝牙 GATT 已连接。
• 当前预设显示正在使用的 P1–P5；从软件或小键盘切换时会同步更新。

在 VicoDeck 中连接设备

USB 配置连接

1. 确认小键盘位于 USB 模式，并使用数据线连接电脑。
2. 点击顶部“USB 连接设备”。
3. 在浏览器式设备选择窗口中选择 Vico Keyboard；软件会读取设备状态并启用配置功能。
4. 完成设置后可点击断开；基础 USB 键盘功能不受配置窗口影响。

蓝牙 GATT 配置连接

1. 先在 Windows 蓝牙设置中完成“Vico Keyboard”的 HID 配对。
2. 进入 OLED、RGB、Claude Code 或语音页面，点击“连接蓝牙 GATT”。
3. 在系统弹出的蓝牙设备窗口中选择 Vico Keyboard。连接后，软件会发现 Vico 状态服务并同步配置。
4. 手动断开后再次连接时，流程与首次连接相同：重新弹出系统选择窗口并重新发现服务。

首次授权：Windows 会记住浏览器蓝牙设备授权。若设备断电、深度睡眠或超出范围，VicoDeck 会显示断开；唤醒后可重新连接。

连接优先级

按键配置与预设

编辑并同步

1. 连接 USB 或蓝牙 GATT。
2. 进入“按键配置”，在当前预设下拉框中选择 P1–P5。选择后，小键盘会同步切换到该预设，不会立即跳回原预设。
3. 点击需要修改的按键卡片，选择普通按键、组合快捷键、多媒体控制或系统操作。
4. 保存设置；需要时使用“同步当前预设”或“同步全部预设”写入小键盘。

配置建议

• 把常用操作按场景分组，例如导航、办公、媒体、开发和系统控制。
• KEY8 默认作为 Fn。若将其改为其他按键，机身预设切换和 OLED 页面组合操作将受到影响。
• 组合快捷键是否生效取决于当前窗口、操作系统快捷键占用和目标应用。
• 修改前先确认正在编辑的预设；软件选择预设后，键盘会切换到同一预设。

同步与保存位置

OLED 显示

显示内容

切换页面

• 小键盘：KEY8 + KEY6 向前切换，KEY8 + KEY7 向后切换。
• VicoDeck：在“OLED 显示”的显示内容下拉框中选择页面。
• Claude Code 状态到来时，可自动临时切换到 Coding 页面；状态结束后返回用户页面。

数字孪生预览

VicoDeck 的 128 × 64 像素预览使用与 SSD1306 相同的单色帧缓冲格式。固件会把实际 1024 字节画面回传给软件，因此预览反映的是小键盘 OLED 正在显示的内容，而不是另行绘制的近似界面。

自定义像素画

1. 选择“自定义像素画”，使用画笔、橡皮擦、反相、清空或导入图片完成绘制。
2. 点击发送或预览可临时显示到 OLED。
3. 点击“保存到键盘”把图像写入小键盘缓存与 NVS；完成后即使软件断开或键盘重启，图像仍可显示。

RGB 灯光

进入“RGB 灯光”并连接设备后，可设置灯光模式、亮度、速度与可选颜色。VicoDeck 的实时预览会按每颗灯的相位与亮度模拟效果；旋钮不带灯光。

灯光模式

设置方法

1. 选择灯光模式。常亮与呼吸模式可使用颜色选择器。
2. 调节亮度；动态模式可继续调节速度。
3. 观察实时预览并同步到小键盘。设置会保存，重启后继续使用。

低功耗：蓝牙电池模式进入连接空闲态时，RGB 会熄灭；任意按键或旋钮动作唤醒后恢复原设置。若用户选择“关闭”，唤醒后仍保持关闭。

Claude Code 状态显示

VicoDeck 通过 Claude Code Hooks 接收本机编码会话事件，再通过 USB Vendor HID 或蓝牙 GATT 转发到小键盘 OLED。固件不直接访问 Claude Code，也不读取云端账号。

启用步骤

1. 打开 VicoDeck 的“Claude Code”页面。
2. 点击安装或更新 Hooks。软件会把 Vico Hooks 合并到 %USERPROFILE%\.claude\settings.json，并保留已有 Hook 配置。
3. 关闭旧的 Claude Code 会话并新建会话，使 Hook 生效。
4. 连接 USB 或蓝牙 GATT，选择 OLED 的 Coding 页面；可先点击“发送测试状态”验证整条链路。

可显示的状态

本地服务：Hook 状态发送到 VicoDeck 在 127.0.0.1:38471 监听的本地接口，仅供本机使用。关闭主窗口后，如已启用托盘运行，状态转发仍可继续。

语音输入

VicoDeck 提供两套互相独立的语音输入：小键盘内置麦克风和电脑麦克风。语音识别由用户配置的豆包 Seed-ASR 2.0 云端接口完成，ESP32 本身不运行本地语音模型。

A 小键盘麦克风

1. 在 VicoDeck 中填写并保存语音 API 配置。API 密钥由 Electron safeStorage 使用 Windows DPAPI 加密保存。
   获取豆包语音 API Key

   1. 注册并登录火山引擎账号，按控制台要求完成实名认证，然后进入豆包语音开通管理。
   2. 选择要使用的项目，在“开通管理”中找到并开通“豆包录音文件识别模型 2.0 标准版”（资源 ID：volc.seedasr.auc）。实际额度与费用以控制台显示为准。
   3. 进入API Key 管理，新建或复制一个可用的 API Key。
   4. 返回 VicoDeck 的“语音识别 → 豆包云端设置”，将 API Key 粘贴到输入框并点击“保存”。请勿把密钥发送给他人或放入截图、代码和公开文档。

   新用户免费额度：新用户可获得 20 小时的免费语音识别额度。开通服务后可在火山引擎控制台查看剩余额度和有效期；免费额度政策可能调整，请以控制台当前显示为准。

2. 确保 USB 配置通道或蓝牙 GATT 已连接。
3. 按住旋钮开始录音，松开结束。VicoDeck 接收音频、调用云端识别，并把文本输入到当前获得焦点的聊天框或文本框。

蓝牙连接录音提示：当 VicoDeck 与小键盘通过蓝牙 GATT 连接时，受蓝牙传输速率及硬件缓冲区限制，单次语音录制请控制在约 4 秒以内；录音过长可能造成音频不完整或识别失败。使用 USB 连接时没有此时长限制，可进行更长时间的录音。

音频规格：小键盘麦克风采用 16 kHz、16-bit、单声道 PCM。蓝牙模式下固件使用 128 KB 环形缓冲区传输音频。

B 电脑麦克风

1. 默认全局快捷键为 Ctrl + Alt + I，可在 VicoDeck 设置中修改。
2. 按住快捷键开始录音，松开后停止并识别。桌面浮层会显示麦克风图标与流动光圈，但不会抢走当前输入焦点。
3. 识别结果自动输入到原来的聊天框或文本框。语音页面中的“测试”按钮主要用于验证 API 与电脑麦克风是否可用。

隐私：两种方式都会把录音发送到所配置的云端语音服务。请确保网络可用，并根据使用场景、组织政策和服务条款决定是否启用。

低功耗与电池

蓝牙电池模式的休眠逻辑

唤醒方式

• 连接空闲态：按任意按键、旋转或按下旋钮、切换模式或由软件发送设置。
• 深度睡眠：按 KEY1–KEY8 中任意一个，或按下旋钮。唤醒后蓝牙会重新广播。
• GPIO38 模式拨片不是 RTC 唤醒源；深度睡眠时仅拨动模式开关不会唤醒，请再按任意按键。
• USB 模式不进入自动休眠。

电量显示

固件通过 GPIO14 读取电池分压电压，经过平滑与电压—百分比曲线估算剩余电量。结果可显示在 OLED、VicoDeck 和 Windows 蓝牙电池信息中。

电池电压会随负载、温度和电芯特性变化，因此百分比仅供参考。当前硬件没有独立充电状态信号，固件不能仅凭 ADC 可靠判断“正在充电”。

USB 固件升级

VicoDeck 内置基于 Web Serial 与 esptool-js 的 ESP32-S3 烧录工具。普通用户不需要安装 Python、PlatformIO 或额外烧录软件。

云端固件 推荐

1. 把模式拨片切换到蓝牙（GND）一侧，避免 USB HID 占用升级端口。
2. 使用数据线连接电脑，打开“固件升级”，保持“云端固件”为首选来源。
3. 从下拉框选择版本或功能固件，核对说明后点击“开始 USB 升级”。
4. 在端口窗口中选择 ESP32-S3 或 Vico 对应端口。软件会下载、校验并写入完整固件包。
5. 等待校验成功和设备重启。整个过程不要拔线、关闭软件或切断电源。

本地 BIN

找不到升级端口

• 确认使用数据线，并把拨片切换到蓝牙侧。
• 关闭小键盘再重新打开，然后重新点击端口选择。
• 仍无法出现端口时：按住 BOOT，短按 RST，再松开 BOOT，手动进入下载模式。

保存 恢复与维护

会长期保存的设置

恢复出厂设置

1. 按 KEY4 + KEY8 进入设置菜单。
2. 用 KEY6 / KEY2 选择 FACTORY RESET，按 KEY4 确认。
3. 确认后恢复默认五套预设、OLED/RGB 设置，并清除键盘内保存的自定义像素画。

注意：恢复出厂设置不可撤销。VicoDeck 电脑端已有的配置文件不会自动删除，可在之后重新同步。

日常维护

• 清洁前断开 USB 并关闭设备；使用柔软干布，避免液体进入按键、旋钮、麦克风或接口。
• 避免在高温、高湿、强静电或金属粉尘环境中使用。
• 不要在固件升级、配置写入或自定义像素画保存期间断电。
• 长期不用时关闭设备并定期检查电池状态。

故障排查

排查顺序：先确认模式拨片和物理连接，再确认 Windows HID，最后检查 VicoDeck 的 USB/GATT 配置通道。这样可以快速区分“键盘输入问题”和“配套软件配置问题”。

技术规格与支持

下载与项目地址

更新建议

• 在 VicoDeck“设置 → 设备与更新”中检查软件更新。下载完成后可重启并安装。
• 升级固件前阅读版本说明，确认目标硬件与固件类型。云端固件为普通用户首选。
• 提交问题时请附上 VicoDeck 版本、固件版本、连接模式、Windows 版本和复现步骤。