Skip to content

Commit 156407e

Browse files
KongJingKongJing
KongJing
authored and
KongJing
committed
docs: complete keyboard usage and development guides
1 parent e0df72f commit 156407e

12 files changed

Lines changed: 490 additions & 45 deletions

File tree

‎docs/.vitepress/config.ts‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,7 @@ export default defineConfig({
3232

3333
nav: [
3434
{ text: "🏠 首页", link: "/" },
35+
{ text: "🎹 使用指南", link: "/usage" },
3536
{
3637
text: "⚡ 经典版",
3738
link: "/wired/",
@@ -45,6 +46,7 @@ export default defineConfig({
4546
{
4647
text: "🔧 开发",
4748
items: [
49+
{ text: "开发总览", link: "/development" },
4850
{ text: "⚡ 经典版开发", link: "/wired/dev" },
4951
{ text: "📡 无线版开发", link: "/wireless/dev" },
5052
],
@@ -54,11 +56,20 @@ export default defineConfig({
5456
],
5557

5658
sidebar: [
59+
{
60+
text: "🎹 开始使用",
61+
collapsed: false,
62+
items: [
63+
{ text: "总览与型号选择", link: "/usage" },
64+
{ text: "常见问题", link: "/faq" },
65+
],
66+
},
5767
{
5868
text: "⚡ 经典版",
5969
collapsed: false,
6070
items: [
6171
{ text: "快速开始", link: "/wired/" },
72+
{ text: "使用方式", link: "/usage#经典版-basic" },
6273
{ text: "硬件复刻", link: "/wired/make" },
6374
{ text: "刷写固件", link: "/wired/flash" },
6475
{ text: "改键软件", link: "/wired/remap" },
@@ -70,6 +81,7 @@ export default defineConfig({
7081
collapsed: false,
7182
items: [
7283
{ text: "快速开始", link: "/wireless/" },
84+
{ text: "使用方式", link: "/usage#无线版-5key" },
7385
{ text: "硬件复刻", link: "/wireless/make" },
7486
{ text: "刷写固件", link: "/wireless/flash" },
7587
{ text: "改键软件", link: "/wireless/remap" },
@@ -86,6 +98,7 @@ export default defineConfig({
8698
text: "📚 其他",
8799
collapsed: true,
88100
items: [
101+
{ text: "开发总览", link: "/development" },
89102
{ text: "MeowFS 宏存储", link: "/meowfs" },
90103
{ text: "MeowMacro 宏语言", link: "/meowmacro" },
91104
{ text: "常见问题", link: "/faq" },

‎docs/development.md‎

Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
# 开发总览
2+
3+
开发文档放在使用文档之后。建议先确认目标芯片和键盘型号，再进入对应固件目录。
4+
5+
## 开发入口
6+
7+
| 目标 | 文档 | 主要内容 |
8+
| :--- | :--- | :--- |
9+
| 经典版 CH552G | [经典版固件开发](./wired/dev.md) | SDCC / CMake、USB HID、EEPROM、FUNC、RGB、旋钮 |
10+
| 无线版 CH592F | [无线版固件开发](./wireless/dev.md) | RISC-V 工具链、USB/BLE 双模、DataFlash、FN、宏、IAP |
11+
| 统一控制台 | [无线版便捷开发工具](./wireless/dev-tools.md) | `console.py`、工具链缓存、构建与烧录菜单 |
12+
| Studio / 协议 | [无线版 HID 通讯协议](./wireless/hid.md) | WebHID 帧格式、命令、状态与配置同步 |
13+
| 宏存储 | [MeowFS](./meowfs.md) | 有线 / 无线共用宏存储格式 |
14+
| 宏语言 | [MeowMacro](./meowmacro.md) | Studio 宏编辑语言与示例 |
15+
16+
## 推荐工作流
17+
18+
1. 从仓库根目录运行统一控制台：
19+
20+
```bash
21+
./run.sh
22+
```
23+
24+
2. 在控制台中选择 target：
25+
26+
- `CH552G`：经典版 BASIC / 5KEY / KNOB。
27+
- `CH592F`：无线版 5KEY / KNOB。
28+
29+
3. 选择 keyboard 和 profile。
30+
4. 执行 build。
31+
5. 使用对应刷写流程验证。
32+
6. 用 Studio 连接设备，确认设备信息、键位读写、层切换、RGB 和宏功能。
33+
34+
## 目标与产物
35+
36+
### CH552G
37+
38+
| keyboard | 产物示例 | 用途 |
39+
| :--- | :--- | :--- |
40+
| BASIC | `CH552G-BASIC-<version>.hex` | 经典基础款 |
41+
| 5KEY | `CH552G-5KEY-<version>.hex` | 经典五键款 |
42+
| KNOB | `CH552G-KNOB-<version>.hex` | 经典旋钮款 |
43+
44+
### CH592F
45+
46+
| 文件 | 用途 |
47+
| :--- | :--- |
48+
| `CH592F-<MODEL>-<version>-full.hex` | 首刷 / 救砖恢复 |
49+
| `CH592F-<MODEL>-<version>-app.bin` | Studio 在线更新 |
50+
| `CH592F-<MODEL>-<version>-iap.hex` | 高地址 IAP 单独产物 |
51+
52+
## 关键目录
53+
54+
```text
55+
firmware/
56+
├── CH552G/ # 经典版固件
57+
├── CH592F/ # 无线版固件
58+
└── cmake/ # 两个固件共用的 CMake helper
59+
60+
tools/
61+
├── scripts/ # console.py、构建脚本、刷写脚本
62+
├── meowisp/ # wchisp 封装与分发
63+
└── studio/ # BinaryKeyboard Studio 前端
64+
```
65+
66+
## 改动建议
67+
68+
- 默认键位：先看 `kbd_storage.c` 或 `KeysDataHandler.c`。
69+
- 键位布局：先看固件型号宏，再看 Studio 的 `layouts.ts`。
70+
- 通讯协议：先改固件命令处理，再同步 Studio codec。
71+
- 宏：优先保持 MeowFS / MeowMacro 兼容，不要为单个芯片单独造格式。
72+
- 发布产物：保持 `config/versions.json`、Release asset 命名和 Studio 更新逻辑一致。
73+
74+
## 验证清单
75+
76+
每次改固件至少验证：
77+
78+
- 目标型号能成功编译。
79+
- 首刷或普通刷写能完成。
80+
- Studio 能连接并读到正确型号。
81+
- 默认层与键位数量正确。
82+
- 键位写入后断电重启仍保留。
83+
- 如果改到无线版，USB / BLE 两种模式都能输入。
84+
- 如果改到宏或存储，旧配置异常时能恢复默认配置。

‎docs/index.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,9 @@ hero:
1010
alt: BinaryKeyboard Logo
1111
actions:
1212
- theme: brand
13+
text: 🎹 开始使用
14+
link: /usage
15+
- theme: alt
1316
text: ⚡ 经典版
1417
link: /wired/
1518
- theme: alt

‎docs/usage.md‎

Lines changed: 245 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,245 @@
1+
# 使用指南
2+
3+
这页按实际使用顺序整理 BinaryKeyboard：先选对型号和固件，再连接、改键、切层、使用 RGB / 宏，最后再进入开发文档。
4+
5+
## 型号速查
6+
7+
| 系列 | 芯片 | 发布型号 | 连接方式 | 适合场景 |
8+
| :--- | :--- | :--- | :--- | :--- |
9+
| 经典版 | CH552G | BASIC / 5KEY / KNOB | USB 有线 | 简单、稳定、即插即用 |
10+
| 无线版 | CH592F | 5KEY / KNOB | USB / BLE | 需要无线、宏、FN、状态指示 |
11+
12+
::: warning 先确认型号
13+
固件按型号区分，BASIC、5KEY、KNOB 不能混刷。刷错后最常见的现象是按键位置不对、旋钮无反应或 Studio 显示布局异常。
14+
:::
15+
16+
## 第一次使用
17+
18+
1. 从 [GitHub Releases](https://github.com/MeowKJ/BinaryKeyboard/releases) 下载对应型号固件。
19+
2. 按 [经典版刷写](./wired/flash.md) 或 [无线版刷写](./wireless/flash.md) 完成首次烧录。
20+
3. 用 Chrome / Edge 打开 BinaryKeyboard Studio。
21+
4. USB 连接键盘，点击“连接设备”，授权 WebHID。
22+
5. 按需要修改键位、层、RGB、宏，然后写入设备。
23+
24+
::: tip 浏览器
25+
Studio 使用 WebHID，只支持 Chrome、Edge、Opera 等 Chromium 内核浏览器。Firefox 和 Safari 当前不可用。
26+
:::
27+
28+
## 通用概念
29+
30+
### 键位编号
31+
32+
Studio 里的键位编号与固件中的索引一致，从 1 开始显示。文档里写的 K1、K2、K3 等，对应 Studio 中从左到右、从上到下看到的可点击键位。
33+
34+
### 层
35+
36+
层可以理解成多套键位配置。当前层切换后，同一个实体按键会执行当前层里的动作。
37+
38+
- 经典版：BASIC / KNOB 默认 4 层，5KEY 默认 5 层。
39+
- 无线版：KNOB 默认 4 层，5KEY 默认 5 层。
40+
- Studio 中可逐层编辑，每层写入后保存在设备内。
41+
42+
### 可配置动作
43+
44+
| 动作 | 经典版 CH552G | 无线版 CH592F |
45+
| :--- | :--- | :--- |
46+
| 键盘按键 | 支持 | 支持 |
47+
| 修饰键组合 | 支持 | 支持 |
48+
| 鼠标按键 / 滚轮 | 支持 | 支持 |
49+
| 多媒体键 | 支持 | 支持 |
50+
| 层动作 | 部分支持，以 Studio 当前可见项为准 | 支持 |
51+
| 宏 | 支持 MeowFS 宏存储 | 支持 MeowFS 宏存储 |
52+
| RGB 配置 | 支持按键 RGB | 支持按键 RGB / 状态指示 |
53+
| 电池状态 | 不适用 | 支持 |
54+
| HID 日志 | 不适用 | 支持 |
55+
56+
## 经典版 BASIC
57+
58+
BASIC 是 4 键 USB 直连版本，默认布局为 3 列 2 行，其中右侧是一个竖向 2u 键，左下是一个横向 2u 键。
59+
60+
默认键位：
61+
62+
| 键位 | 默认动作 |
63+
| :--- | :--- |
64+
| K1 | `0` |
65+
| K2 | `1` |
66+
| K3 | `Enter` |
67+
| K4 | `Space` |
68+
69+
使用方式：
70+
71+
- 插入 USB 后即可作为标准键盘使用。
72+
- 短按 `FUNC`：切换下一个 RGB 灯效。
73+
- 按住 `FUNC` 再按 K1~K4：切换到第 1~4 层。
74+
- 按住 `FUNC` 时普通按键不会向电脑发送，避免切层时误触发。
75+
- 在 Studio 中选择不同层后，可以分别配置 K1~K4 的动作。
76+
77+
## 经典版 5KEY
78+
79+
5KEY 是 5 键 USB 直连版本，比 BASIC 多一个普通按键，默认 5 层。
80+
81+
默认键位：
82+
83+
| 键位 | 默认动作 |
84+
| :--- | :--- |
85+
| K1 | `1` |
86+
| K2 | `2` |
87+
| K3 | `3` |
88+
| K4 | `4` |
89+
| K5 | `5` |
90+
91+
使用方式：
92+
93+
- 插入 USB 后即可使用。
94+
- 短按 `FUNC`：切换下一个 RGB 灯效。
95+
- 按住 `FUNC` 再按 K1~K5：切换到第 1~5 层。
96+
- 适合把五个键设置成快捷键、媒体控制、应用启动宏或游戏快捷操作。
97+
98+
## 经典版 KNOB
99+
100+
KNOB 是 4 个普通键加 1 个旋钮的 USB 版本。旋钮在 Studio 中会显示为 3 个虚拟动作：按下、左转、右转。
101+
102+
默认键位：
103+
104+
| 键位 | 默认动作 |
105+
| :--- | :--- |
106+
| K1 | `A` |
107+
| K2 | `B` |
108+
| K3 | `C` |
109+
| K4 | `D` |
110+
| 旋钮按下 | 鼠标左键 |
111+
| 旋钮左转 | 音量减 |
112+
| 旋钮右转 | 音量加 |
113+
114+
使用方式：
115+
116+
- K1~K4 像普通键盘按键一样使用。
117+
- 旋钮旋转会触发一次离散动作，适合音量、滚轮、上一首/下一首等。
118+
- 短按 `FUNC`：切换下一个 RGB 灯效。
119+
- 按住 `FUNC` 再按 K1~K4：切换到第 1~4 层；旋钮不参与层选择。
120+
- Studio 中可分别配置 K1~K4、旋钮按下、旋钮左转、旋钮右转。
121+
122+
## 无线版 5KEY
123+
124+
无线 5KEY 是 5 键 USB / BLE 双模版本，默认 5 层。
125+
126+
默认键位：
127+
128+
| 键位 | 默认动作 |
129+
| :--- | :--- |
130+
| K1 | `1` |
131+
| K2 | `2` |
132+
| K3 | `3` |
133+
| K4 | `4` |
134+
| K5 | `5` |
135+
136+
使用方式：
137+
138+
- USB 模式下，连接 USB-C 后作为有线键盘使用，并可打开 Studio 配置。
139+
- BLE 模式下，键盘作为蓝牙 HID 键盘使用。
140+
- `FN1` 短按 / 长按：在 USB 与 BLE 模式之间切换，设备会保存模式并重启进入目标模式。
141+
- `FN2` 短按：切换到下一层。
142+
- `FN2` 长按：在 BLE 模式下清除蓝牙配对信息并重启。
143+
- 按住任意 FN 键再按 K1~K5：直接切换到第 1~5 层。
144+
145+
## 无线版 KNOB
146+
147+
无线 KNOB 是 4 个普通键加 1 个旋钮的 USB / BLE 双模版本。旋钮动作在 Studio 中同样作为虚拟键位配置。
148+
149+
默认键位：
150+
151+
| 键位 | 默认动作 |
152+
| :--- | :--- |
153+
| K1 | `1` |
154+
| K2 | `2` |
155+
| K3 | `3` |
156+
| K4 | `4` |
157+
| 旋钮右转 | 音量加 |
158+
| 旋钮左转 | 音量减 |
159+
| 旋钮按下 | 静音 |
160+
161+
使用方式：
162+
163+
- USB 模式下可直接作为有线键盘使用，也用于 Studio 改键和固件更新。
164+
- BLE 模式下用于无线输入。
165+
- `FN1` 短按 / 长按：切换 USB / BLE 模式。
166+
- `FN2` 短按：切换到下一层。
167+
- `FN2` 长按：在 BLE 模式下清除蓝牙配对信息。
168+
- 按住任意 FN 键再按 K1~K4：切换到第 1~4 层；旋钮不参与层选择。
169+
- 旋钮适合配置为音量、滚轮、媒体键、层切换或宏触发。
170+
171+
## 无线版蓝牙配对
172+
173+
1. 确保电池已连接且电量足够。
174+
2. 短按 `FN1` 切换到 BLE 模式，键盘会重启并进入蓝牙路径。
175+
3. 等待指示灯进入广播状态。
176+
4. 在电脑或手机蓝牙设置中搜索 `BinaryKeyboard5KEY` 或 `BinaryKeyboardKNOB`。
177+
5. 点击连接，按系统提示完成配对。
178+
179+
如果系统一直连不上：
180+
181+
- 在 BLE 模式下长按 `FN2` 清除配对，再重新搜索。
182+
- 在电脑 / 手机蓝牙列表中删除旧的 BinaryKeyboard 设备后重试。
183+
- 用 USB 连接 Studio，打开 Debug Terminal 查看 BLE 日志。
184+
185+
## Studio 改键
186+
187+
### 连接
188+
189+
1. 用 USB-C 连接键盘。
190+
2. 打开 Studio。
191+
3. 点击“连接设备”。
192+
4. 在浏览器弹窗中选择 BinaryKeyboard。
193+
194+
::: warning 无线版也要接 USB
195+
无线版改键、宏编辑和固件更新都通过 USB HID 配置通道完成。BLE 模式只负责日常输入，暂不用于配置。
196+
:::
197+
198+
### 写入配置
199+
200+
1. 选择要编辑的层。
201+
2. 点击键位，选择键盘、鼠标、媒体、宏或层动作。
202+
3. 无线版可继续调整 FN、RGB、电池和日志相关配置。
203+
4. 点击保存 / 写入，等待提示成功。
204+
205+
### 宏
206+
207+
宏适合把一串输入绑定到单个键位，例如固定短语、快捷键序列或鼠标点击序列。
208+
209+
- 详细语法见 [MeowMacro](./meowmacro.md)。
210+
- 存储结构见 [MeowFS](./meowfs.md)。
211+
- 无线版宏编辑器说明见 [无线版改键软件](./wireless/remap.md#宏编辑器使用指南)。
212+
213+
## RGB 与状态灯
214+
215+
经典版：
216+
217+
- 短按 `FUNC` 切换灯效。
218+
- Studio 中可配置开关、模式、亮度、速度、颜色和按键反馈效果。
219+
220+
无线版：
221+
222+
- 默认使用状态指示模式。
223+
- USB 已连接、BLE 广播、BLE 已连接、低电量、充电和睡眠都有不同状态提示。
224+
- Studio 中可调整 RGB 和指示灯亮度。
225+
226+
## 进入刷写 / 恢复
227+
228+
经典版：
229+
230+
- 拔下 USB。
231+
- 按住 `BOOT`。
232+
- 插入 USB。
233+
- 松开 `BOOT` 后刷写对应 `CH552G-<MODEL>-<version>.hex`。
234+
235+
无线版：
236+
237+
- 首刷或救砖使用 `CH592F-<MODEL>-<version>-full.hex`。
238+
- 正常在线更新使用 Studio 下载并写入 `CH592F-<MODEL>-<version>-app.bin`。
239+
- 设备正常运行时，单击 `BOOT` 会进入 IAP / Bootloader 路径。
240+
241+
## 接下来
242+
243+
- 想复刻硬件：看 [经典版硬件复刻](./wired/make.md) 或 [无线版硬件复刻](./wireless/make.md)。
244+
- 想刷写固件：看 [经典版刷写](./wired/flash.md) 或 [无线版刷写](./wireless/flash.md)。
245+
- 想开发固件：从 [经典版开发](./wired/dev.md) 或 [无线版开发](./wireless/dev.md) 开始。

0 commit comments

Comments
 (0)