Merge pull request #23 from MeowKJ/dev

Author: MeowKJ

.gitignore

@@ -89,4 +89,27 @@ build/
 .cache/
 
 # Windows reserved name (accidental create)
-nul
+nul
+
+# Local temporary commit message files
+commit_msg*.txt
+
+# pnpm 本地缓存
+.pnpm-store/
+
+# 3D 模型与设计文件（另行存放，不纳入本仓库）
+Models/
+models/
+model/
+*.shapr
+*.blend
+*.blend1
+*.stl
+*.obj
+*.step
+*.stp
+*.3ds
+*.fbx
+*.dae
+*.glb
+*.gltf

.gitmodules

@@ -0,0 +1,3 @@
+[submodule "examples/openwch-ch592"]
+	path = examples/openwch-ch592
+	url = https://github.com/openwch/ch592.git

README.md

@@ -34,20 +34,24 @@
 
 # 概述
 
+**BinaryKeyboard** 为本项目名称（项目名），开源迷你键盘固件与改键工具。
+
 # 快速开始
 
 # 环境
 
 ## 有线款
 
-[有线款](./Firmware/CH552G/README.md)
+[有线款](./firmware/CH552G/README.md)
 
 ## 无线款
 
-[无线款](./Firmware/CH592F/README.md)
+[无线款](./firmware/CH592F/README.md)
 
 # 贡献
 
+**分支与流程**：日常开发在 **`dev`** 分支进行，完成后通过 **Pull Request** 合并到 **`main`**。
+
 [![Contributors](https://contrib.rocks/image?repo=MeowKJ/BinaryKeyboard)](https://github.com/MeowKJ/BinaryKeyboard/graphs/contributors)
 
 # 许可
@@ -62,7 +66,7 @@
 </p>
 
 - **代码（Code）**：遵循 [GNU General Public License v3.0](https://www.gnu.org/licenses/gpl-3.0.html)  
-  适用范围：`/Firmware/**`、`/Software/**`、脚本与示例代码等。
+  适用范围：`/firmware/**`、`/tools/studio/**`、脚本与示例代码等。
 
 - **文档与素材（Docs & Assets）**：遵循 [CC BY-NC-SA 4.0](https://creativecommons.org/licenses/by-nc-sa/4.0/deed.zh-Hans)  
   适用范围：`/Hardware/**`、`/Models/**`

commit_msg.txt

@@ -12,5 +12,46 @@
 
 ## 3) 改键网页连不上设备
 
-- 尽量用 Chrome / Edge
+- 尽量用 Chrome / Edge（需支持 WebHID）
 - 检查是否被浏览器权限拦截（HID/USB 权限）
+- 无线版：确认已用 USB 连接且键盘处于 USB 模式
+
+## 4) 无线版：Debug Terminal 没有数据
+
+- 在改键工具中打开底部 Debug Terminal，进入设置，开启「HID 日志」并点击保存
+- 保存后需在工具内执行一次「保存配置」到设备，日志开关才会持久化
+
+## 5) 无线版：BLE 连接后过一会儿显示未连接
+
+现象：USB 切到 BLE、电脑配对后显示「正在连接」，过几秒或十几秒又变成「未连接」。
+
+**先看断开原因**：用 USB 连接键盘，打开改键工具和 Debug Terminal，开启 HID 日志。再次用蓝牙连接，断开后看终端里**紧接着出现的一条 BLE 事件**，`opcode` 应为 `GAP_LINK_TERMINATED`，`reason` 即断开原因。常见含义：
+
+| reason (hex) | 含义 |
+| :----------- | :--- |
+| 0x08 | CONNECTION_TIMEOUT（连接/监督超时） |
+| 0x16 | LOCAL_HOST_TERMINATED（本机主动断开） |
+| 0x3B | UNACCEPTABLE_CONN_PARAMS（主机不接受连接参数更新） |
+| 0x13 | REMOTE_USER_TERMINATED（对端用户/系统断开） |
+| 0x22 | LMP_LL_RESPONSE_TIMEOUT（链路层无响应） |
+
+**可尝试**：
+
+- **0x08 / 超时**：在 `firmware/CH592F/MeowBLE/hid/include/kbd_mode_config.h` 中把 `KBD_BLE_CONN_TIMEOUT` 从 `500`（5 秒）改为 `600` 或 `800`，重新编译烧录。
+- **0x3B / 参数不被接受**：同一文件里可适当放大 `KBD_BLE_CONN_INT_MIN/MAX`（如改为 16～32，即 20ms～40ms），或联系维护者调整连接参数更新时机。
+- **0x16 / 本机断开**：多为系统/驱动或省电策略断开，可尝试关闭该设备的「允许关闭此设备以节约电源」、更新蓝牙驱动或换一台设备对比。
+
+## 6) 无线版：BLE 配对完成后键盘卡死（RGB 不更新、按键无反应）
+
+现象：FN 切到 BLE、长按进入广播，电脑连接/配对过程中键盘完全无响应（RGB、普通键、FN 均无反应），需重新上电或拔 USB 才能恢复。最后一条日志可能是 **连接建立后 STATE_CB_EXIT**、**SECURITY_REQUEST (0xB7)** 成功、或 **PAIR_CB_EXIT**（配对完成/保存绑定之后）。
+
+**可能原因**：在 BLE 栈上下文中执行应用层代码（状态回调、日志、RGB 等）可能引发卡死；或配对/SNV 写路径、WCH BLE 库内部流程存在问题。
+
+**可尝试**：
+
+1. **固件已做缓解**：① **状态回调延后**：BLE 状态变化不再在栈上下文中直接调用应用（`onStateChange`），而是写入待处理队列，由主循环 `KBD_Mode_Process` 中取出并执行，从而避免在 BLE 栈里执行 RGB/连接状态等逻辑导致卡死。② 以下路径内默认不再打 BLE 诊断日志：SNV 写、配对/密码回调、安全请求事件、状态回调内日志（宏 `BLE_SNV_LOG_IN_WRITE`、`BLE_PAIRING_DIAG_LOG`、`BLE_SECURITY_REQ_DIAG_LOG`、`BLE_STATE_CB_DIAG_LOG` 均为 0）。需要调试时可把对应宏设为 1 再编译。
+2. **关键验证：关闭绑定保存**：在 `firmware/CH592F/MeowBLE/core/include/ble_config.h` 中把 `BLE_SNV` 设为 `FALSE` 后重新编译烧录，再测试“连接但不保存绑定”（每次重连需重新配对）：**若此时不再卡死，则问题在 SNV 写入或栈在写完成后的流程**；若仍卡死，则更可能是栈在配对完成回调返回后的其它路径有问题。
+3. **更新 BLE 库 / 芯片固件**：查看 WCH 官方是否有 CH592 BLE ROM/SDK 更新或勘误说明，针对配对后死机有无修复或建议。
+4. **缩短配对期负载**：确保在配对阶段不要同时做大量配置保存或其它 Flash 写（例如改键工具里暂不点“保存配置”），减少与 SNV 写争用或阻塞主循环的可能。
+
+若你已确认最后一条日志的 opcode（如 0xBA = PAIR_CB_EXIT）和复现步骤，欢迎提 issue 附上终端日志片段，便于进一步排查。

docs/faq.md

@@ -11,7 +11,7 @@ hero:
   actions:
     - theme: brand
       text: ⚡ 经典版
-      link: /classic/
+      link: /wired/
     - theme: alt
       text: 📡 无线版
       link: /wireless/

docs/index.md

@@ -0,0 +1,76 @@
+# 经典版固件开发
+
+基于 **CH552G** 芯片的固件开发指南。
+
+## 开发环境
+
+### 推荐工具链
+
+| 工具        | 说明                 |
+| :---------- | :------------------- |
+| Arduino IDE | 借助 CH55xduino 编译 |
+
+### 配置开发环境
+
+1. 安装 Arduino IDE
+2. 安装 CH55xduino 库
+
+## 版本配置
+
+在 `src/config.h` 中选择外形版本：
+
+```c
+// 只启用一个
+#define USE_BASIC    // 基础款
+// #define USE_5KEYS // 五键款
+// #define USE_KNOB  // 旋钮款
+```
+
+## 编译与烧录
+
+### 使用 Arduino IDE
+
+1. 打开 `CH552G.ino` 文件
+2. 选择板子：**CH552**
+3. 在 USB Setting 中选择：**USER CODE w/148B USB ram**
+4. 点击编译并上传
+
+## 常见改动点
+
+### 1. 默认键位
+
+修改 `KeysDataHandler.c` 中的按键映射表。
+
+### 2. RGB 灯效
+
+修改 `rgb.c` 中的灯效逻辑，支持 WS2812。
+
+### 3. USB 描述符
+
+修改 `USBConstant.c` 中的设备描述符。
+
+### 4. 音乐节奏游戏延迟问题
+
+修改 `config.h` 中的 DEBOUNCE_THRESHOLD 阈值，默认值为 5，单位为毫秒。如果用于音乐节奏游戏，可将阈值减小或者设置为0。
+
+## HID 协议
+
+经典版使用 USB HID 协议通信：
+
+| Report ID | 功能        | 数据长度 |
+| :-------- | :---------- | :------- |
+| 1         | 键盘输入    | 8 字节   |
+| 2         | 控制器      | 8 字节   |
+| 3         | 鼠标输入    | 5 字节   |
+| 4         | 主机 → 键盘 | 31 字节  |
+| 5         | 键盘 → 主机 | 31 字节  |
+
+::: tip
+Report ID 4/5 用于改键工具与键盘通信，修改键位映射。
+:::
+
+## 参考资料
+
+- [CH552 数据手册](https://www.wch.cn/products/CH552.html)
+- [SDCC 文档](http://sdcc.sourceforge.net/)
+- [CH55xduino](https://github.com/DeqingSun/ch55xduino)

docs/wired/dev.md

@@ -0,0 +1,41 @@
+# 经典版固件刷写
+
+## 准备工作
+
+- **WCHISPStudio** - [下载地址](https://www.wch.cn/downloads/WCHISPTool_Setup_exe.html)
+- 对应版本的 `.hex` 固件文件 - [GitHub Releases](https://github.com/MeowKJ/BinaryKeyboard/releases)
+
+## 固件文件说明
+
+| 固件文件                 | 适用外形 |
+| :----------------------- | :------- |
+| `ch552_basic_xxx.hex`    | 基础款   |
+| `ch552_fivekeys_xxx.hex` | 五键款   |
+| `ch552_knob_xxx.hex`     | 旋钮款   |
+
+> 以 GitHub Releases 的发布文件为准。注意前缀为`ch552_`，不要下错成无线版的`ch592_`。
+
+## 刷写步骤
+
+### 软件配置
+
+1. 打开 **WCHISPStudio**
+2. 顶部工具栏选择 **MCU系列视图** → **E8051USB系列**
+3. 芯片选择：芯片系列 **CH55x**，芯片型号 **CH552**，下载接口 **USB**
+4. 下载文件：目标程序文件1 选择对应的 `.hex` 固件文件
+
+### 硬件操作
+
+5. **按住** PCB 上的 **BOOT** 按钮不松开
+6. 保持按住的同时，将 USB-C 插入电脑
+7. 松开 BOOT 按钮（此时软件应识别到设备）
+
+::: tip
+如果没有识别到设备，请检BOOT按钮是否按下，或者检查USB-C接口是否焊接良好。
+:::
+
+### 开始烧录
+
+8. 点击"下载"按钮
+9. 等待进度条完成，提示成功
+10. 重新拔插 USB，测试键盘

docs/wired/flash.md

@@ -0,0 +1,88 @@
+# ⚡ 经典版快速开始
+
+基于 **CH552G** 芯片的 USB 直连版本，即插即用。
+
+## 准备工作
+
+### 你需要
+
+| 工具/材料       | 说明                                 |
+| :-------------- | :----------------------------------- |
+| 🔧 电烙铁 + 焊锡 | 焊接 PCB                             |
+| 🖨️ 3D 打印机     | 或者使用 3D 打印服务                 |
+| 💻 电脑          | 推荐 Windows，没有测试过 macOS/Linux |
+| 🔌 USB-C 数据线  | 连接键盘                             |
+
+### 下载文件
+
+1. **固件** - 从 [GitHub Releases](https://github.com/MeowKJ/BinaryKeyboard/releases) 下载
+   - `ch552_basic_xxx.hex` - 基础款
+   - `ch552_fivekeys_xxx.hex` - 五键款
+   - `ch552_knob_xxx.hex` - 旋钮款
+
+2. **外壳 STL** - 从 Releases 或 [OSHWHub](https://oshwhub.com/kjpig/Binary-Keyboard) 下载。
+
+3. **烧录工具** - [WCHISPStudio](https://www.wch.cn/downloads/WCHISPTool_Setup_exe.html)
+
+## 复刻流程
+
+### Step 1：3D 打印外壳
+
+- 普通 FDM 打印即可，没有特殊要求。
+- 层高 0.2mm
+
+### Step 2：焊接 PCB
+
+1. 焊接 USB-C 接口
+2. 按照原理图焊接元器件
+3. 焊接按键
+
+::: warning 注意
+USB-C接口的焊接难度略大，需要小心。可以寻找相关教程视频学习。我个人推荐使用一些助焊剂帮助焊接。一般复刻失败的原因都是USB-C接口焊接失败。
+:::
+
+### Step 3：刷写固件
+
+#### 软件配置
+
+1. 打开 **WCHISPStudio**
+2. 顶部工具栏选择 **MCU系列视图** → **E8051USB系列**
+3. 芯片选择：芯片系列 **CH55x**，芯片型号 **CH552**，下载接口 **USB**
+4. 下载文件：目标程序文件1 选择对应的 `.hex` 固件文件
+
+#### 硬件操作
+
+5. **按住** PCB 上的 **BOOT** 按钮不松开
+6. 保持按住的同时，将 USB-C 插入电脑
+7. 松开 BOOT 按钮（此时软件应识别到设备）
+
+#### 开始烧录
+
+8. 点击"下载"按钮
+9. 等待进度条完成，提示成功
+
+详细步骤见 [刷写固件](./flash)
+
+### Step 4：组装
+
+1. 将 PCB 装入外壳
+2. 盖上盖板，拧紧螺丝
+3. 安装轴体
+
+### Step 5：配置键位
+
+1. 用 Chrome / Edge 打开改键工具
+2. 点击"连接设备"
+3. 选择你的键盘
+4. 配置想要的键位映射
+5. 点击"写入"
+
+详细步骤见 [改键软件使用](./remap)
+
+## 完成 🎉
+
+插上 USB，享受你的可爱二进制键盘吧！
+
+::: tip 遇到问题？
+查看 [常见问题](/faq) 或在 GitHub 提交 Issue。
+:::