- Rust 87.2%
- Python 11.1%
- Shell 1.7%
Ming Tsay
9bee5a24e7
- 右上角語言選單（自動／English／日本語／繁體中文／简体中文），選擇會記住 - 字型依語系調整後備順序：繁中蘋方 TC、簡中蘋方 SC、日文冬青黑體 - 字型檔改 mmap（蘋方 .ttc 78 MB），不整檔讀進記憶體 - 冬青黑體 ascent 較小，y_offset_factor 0.2 對齊基線（對照蘋方實測） - 下拉選單填滿欄寬並截斷、按鈕列可換行，日文長字串不再溢出 - 說明文字靠左，避免 columns 的 justify 撐開英文字距 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_019zAhkv92zMSevT618Ngvzu |
||
|---|---|---|
| assets | ||
| fixtures | ||
| locales | ||
| scripts | ||
| src | ||
| tests | ||
| tools/trace | ||
| .gitignore | ||
| Cargo.lock | ||
| Cargo.toml | ||
| CHANGELOG.md | ||
| LICENSE-APACHE | ||
| LICENSE-MIT | ||
| PROTOCOL.md | ||
| README.md | ||
keykey
KeyKey 兩鍵藍牙翻頁器（USB 5262:4B4B）的命令列配置工具，取代原廠只有 x86_64 版的配置軟體。
A command-line configurator for the KeyKey two-key Bluetooth page turner, replacing the vendor's abandoned x86_64-only app. Byte-for-byte compatible with the vendor tool.
為什麼
KeyKey 是一款常用於電子書、簡報翻頁的兩鍵藍牙小鍵盤（WCH CH57x），按鍵、巨集與燈光都要用原廠配置軟體設定。 原廠軟體作者佚名、已停止更新，macOS 版只有 x86_64，在 Apple Silicon 上得靠 Rosetta 2 執行， 而 macOS 28 會移除 Rosetta，屆時原廠軟體將無法開啟。
這個專案依原廠軟體反組譯整理出通訊協定，用 Rust 重新實作全部功能，並以原廠程式實際送出的 bytes 逐一比對驗證。
功能
- 單鍵：鍵盤鍵（含任意修飾鍵組合）、多媒體鍵、滑鼠按鍵／位移／滾輪
- 巨集：鍵盤巨集最多 14 步、滑鼠巨集最多 9 步，可設按下時間、延遲、重複次數、無限循環、按住循環
- 原廠 10 組翻頁預設（Android 音量鍵、iOS 方向鍵、Kobo、Page Up/Down、滑鼠點螢幕兩側……）
- 燈光：8 種模式，每顆燈分開設定，顏色用
#rrggbb或 HSL - 恢復出廠設定、關燈、重新開機
- 韌體更新（CH57x IAP bootloader，純 Rust USB，不需要 libusb）
- Power-on 開機模組配對（另售配件）
- USB／藍牙模式切換（原廠程式有定義、但介面沒有提供）
安裝
到 Releases 下載 macOS universal 執行檔（Apple Silicon 與 Intel 皆可）。 執行檔以 Developer ID 簽章並經 Apple 公證，首次執行時 Gatekeeper 會連網查核：
tar xzf keykey-v0.1.0-macos-universal.tar.gz
mv keykey-v0.1.0-macos-universal/keykey ~/.local/bin/ # 或任何 PATH 內的目錄
或從原始碼安裝（Rust 1.89 以上）：
cargo install --git https://git.mingtsay.tw/mt/keykey.git
Linux／Windows 理論上可以編譯（hidapi 與 nusb 都跨平台），但尚未測試。
使用
先用 USB 線接上 KeyKey。鍵號、燈號是 1、2，與原廠介面相同。
keykey info # 韌體版本、電量、藍牙 MAC
keykey keys # 列出所有按鍵名稱
# 單鍵
keykey set 1 ctrl+c # 修飾鍵用 + 組合
keykey set 1 cmd+shift+4
keykey set 2 volume_up # 多媒體鍵
keykey set 1 mouse:left # 滑鼠左鍵
keykey set 2 mouse:wheel=-3 # 滾輪（上為正）
keykey set 1 mouse:x=-10,y=5 # 游標位移（左、上為負）
# 巨集：每步 動作/按下ms/延遲ms，時間為 10 的倍數、0～2500，省略為 0
keykey macro 1 ctrl+c/20/50 ctrl+v --times 2
keykey macro 2 mouse:x=127/0/0 mouse:left/0/1000 --while-held
keykey macro 1 down/10/100 --forever
# 預設與燈光
keykey preset # 列出 10 組原廠預設
keykey preset 2 # 左右方向鍵
keykey light # 列出燈光模式
keykey light all press-color --color '#39c5bb'
keykey light 2 night-breathing --color 175,141,64
keykey lights-off
keykey factory-reset # 音量加減 + 按下亮隨機色
# 維護
keykey firmware KeyKey_V102.bin # 韌體更新，約 4 秒
keykey restart # 重新開機
keykey exit-bootloader # 卡在 bootloader 時救回
keykey mode ble # 切換藍牙／USB 模式
任何指令加上 --dry-run，只會印出要送出的封包，不連接裝置。
注意事項
- 裝置只能寫入，無法讀回目前設定。 修改前請自己記下原本的設定。
- 原廠配置軟體開著時會獨佔連線，兩者不能同時使用。
- 燈光的 HSL 中，L 是亮度；即使是彩虹等不需指定顏色的模式，L=0 也會不亮。沒給
--color時預設用出廠值。 - 「幸運色」模式每按一次會換一個隨機顏色。
- 原廠的「復位重啟」只會讓裝置進入 bootloader 並停在那裡；本工具的
restart會再送出離開指令，真正重開機。
實作與驗證
| 檔案 | 內容 |
|---|---|
PROTOCOL.md |
由原廠程式反組譯整理的 HID／IAP 協定文件 |
fixtures/vendor.json |
原廠程式在假 HID／USB 裝置上執行時，實際送出的每一個 byte |
tests/vendor.rs |
逐 byte 比對本工具與原廠的輸出 |
tools/trace/trace.py |
產生 fixtures 的記錄器 |
scripts/release-macos.sh |
建置 universal 執行檔、簽章、公證、打包 |
cargo test 涵蓋 131 組按鍵碼、54 個操作情境（預設、單鍵、巨集、燈光、Power-on、韌體更新分包），
以及 4913 組 RGB→HSL 換算與 Qt 的結果比對。單鍵、巨集、燈光、韌體更新與重新開機也都在實機上驗證過。
重新產生 fixtures 需要 Python 3.11、PySide6，以及從原廠 PyInstaller 執行檔抽出的 .pyc
（原廠程式不包含在本 repo）：
python3.11 tools/trace/trace.py <原廠 pyc 目錄> fixtures/vendor.json
刻意與原廠不同之處
- 所有 HID 封包補 0 到 65 bytes（原廠有些只送 8～17 bytes，macOS 的 hidapi 不會自動補齊）。
- Power-on「配對後解除」的封包不帶殘留的 MAC（原廠改動全域變數造成的 bug）。
restart會真正重新開機（見上方注意事項）。- 原廠按鍵選擇視窗中的
Robit按鈕沒有對應代碼（原廠點了也不會有作用），不列入按鍵表。
授權
以 MIT 或 Apache-2.0 授權，任選其一。
本專案與 KeyKey 原廠無關。KeyKey 為其權利人之名稱。