Skip to content

README.zh-TW.md

Latest commit

 

History

History
164 lines (125 loc) · 6.41 KB

README.zh-TW.md

File metadata and controls

164 lines (125 loc) · 6.41 KB
Raw

Cardputer 鍵盤滑鼠

English | 简体中文 | 繁體中文 | Italiano | Français | Português

banner

把 M5Stack Cardputer Adv 變成口袋鍵盤 + 滑鼠,透過 藍牙 LE 或 USB-C 連接任何電腦、手機或平板。

  • ⌨️ 鍵盤 — 全部 56 個按鍵送出標準 HID 鍵碼(USB 模式下連 BIOS 都能用)
  • 🖱️ 傾斜滑鼠 — 利用內建加速度計,傾斜裝置即可移動游標(也可改用方向鍵游標)
  • 📶 3 個藍牙插槽 — 最多與 3 台裝置保持配對,隨時切換
  • ⚙️ 裝置端設定選單 — 設定儲存在 TF 卡上
  • 支援 Windows / macOS / Linux / Android / iPadOS / iOS

work1 work2

快速上手

  1. 燒錄韌體 — 參見燒錄。
  2. **藍牙(預設):**在裝置的藍牙設定中配對 Cardputer-Keyboard-Mouse, 無需 PIN 碼。
  3. **想用 USB?**長按 BtnA 約 0.7 秒開啟選單,選擇 Transport → USB (裝置會重新啟動),再接上 USB-C 資料線。
  4. 開始打字。按 Fn+Space 切換輸入模式: 鍵盤 → 滑鼠 → 鍵盤+滑鼠。

頂部狀態列顯示:連線狀態(OK / ADV)、輸入模式 ([KEY] / [MOUSE] / [K+M])、CAPS、傾斜靈敏度 S1–S5 以及電量。

輸入模式

模式 鍵盤 游標
鍵盤 所有按鍵正常輸入 關閉
滑鼠 按鍵變成滑鼠控制 傾斜移動 — 按住任一鍵才移動(離合)
鍵盤+滑鼠 (預設) 所有按鍵正常輸入 傾斜常開,打字時暫停

滑鼠模式按鍵

按照方向鍵的排列放在 ; , . / 上:

按鍵 動作
, / Enter / BtnA 左鍵
/ 右鍵
m 中鍵
; / . 滾輪向上 / 向下
其他任一鍵(按住) 離合 — 按住期間游標才會移動

鍵盤+滑鼠模式附加操作

按鍵 動作
BtnA 短按 左鍵點擊
Opt + , / / / m 左 / 右 / 中鍵
Opt + ; / . 滾輪向上 / 向下
Opt 快速輕點 送出一次 GUI/Win/Cmd 鍵

按住期間,Opt 作為本機滑鼠前綴鍵,不會送到主機。 需要 GUI 鍵組合(例如 Win+C)時,請使用鍵盤模式,此時 Opt 是一般的 GUI 修飾鍵。

方向鍵游標

在選單中設定 Cursor source = arrows 時使用,動作感測器故障時也會自動啟用。 僅限滑鼠模式:

按鍵 動作
; , . / 向上 / 左 / 下 / 右移動(按住會加速)
j / k 左鍵 / 右鍵
u / n 滾輪向上 / 向下
Enter / BtnA 左鍵

Fn 層

修飾鍵:Ctrl、Shift(Aa)、Alt、Opt = GUI/Win/Cmd。Fn 為本機按鍵, 永遠不會送到主機。

按鍵 Fn 層 按鍵 Fn 層
` Esc u PgUp
1 … 9、0 F1 … F9、F10 i Insert
- / = F11 / F12 p PrintScreen
Backspace Delete a CapsLock
e End d PgDn
h Home ; ↑
, / . / / ← / ↓ / → Space 切換輸入模式

其餘按鍵輸入其印刷符號(US 鍵盤配置;實際結果依主機的配置而定)。

設定選單

長按 BtnA 約 0.7 秒開啟/關閉(選單開啟時暫停對主機的輸入)。 以 ; 上移、. 下移、Enter 選擇、` / Backspace 返回。

項目 作用
Transport BLE / USB(儲存後重新啟動)
BLE host slot 1 / 2 / 3 — 每個插槽是獨立的藍牙身分
Clear pairing 清除全部 3 個插槽的配對 — 記得也要在主機端移除本裝置
Sensitivity 傾斜游標速度,1–5
Clutch mode 預設 / 按住才移動 / 按住即凍結 / 常開
Cursor source 傾斜 / 方向鍵
Recalibrate tilt 以偏好的持握姿勢靜置約 1 秒
Brightness 螢幕亮度,20%-100%,間距 20%(預設 80%)
Device name 循環切換預設名稱(自訂名稱:直接編輯設定檔)
About 版本 + 設定儲存後端

設定儲存在 TF 卡的 /kbmouse/settings.txt(純文字 key=value, 可放心手動編輯);未插卡時退回使用內部 flash。

燒錄

預先建置的映像

make release

會在 release/ 產生兩個發佈映像:

檔案 燒錄方式
Cardputer-Keyboard-Mouse-full.bin 以 esptool / M5Burner 寫入偏移 0x0
Cardputer-Keyboard-Mouse-app.bin 複製到 TF 卡,從 M5Launcher 安裝 
esptool.py --chip esp32s3 write_flash 0x0 release/Cardputer-Keyboard-Mouse-full.bin

從原始碼建置(PlatformIO)

pio run -e cardputer-adv            # build
pio run -e cardputer-adv -t upload  # flash over USB
pio test -e native                  # unit tests (no hardware needed)

如果 USB 連接埠沒有出現(首次燒錄 / 韌體損毀),請進入下載模式: 關機 → 按住 G0/BtnA → 接上 USB → 放開。

**M5Launcher 注意事項:**設定存在 TF 卡上,切換韌體後仍會保留; 切換韌體時 BLE 配對可能遺失 — 之後請重新配對。本韌體不會動到 G5, 也不會清除整個 NVS。

小技巧與疑難排解

  • 20 秒未操作後螢幕自動熄滅以節省電力——任何按鍵、點擊或傾斜移動都會立即喚醒螢幕。螢幕熄滅期間輸入照常運作。
  • 開機時保持裝置靜止約 1 秒 — 這時會擷取中立姿勢 (螢幕顯示 CALIBRATING)。每當游標移動啟動時,當下的姿勢會成為新的中心點, 因此游標不會自行漂移。
  • **iPhone/iPad 上的滑鼠指標:**啟用 設定 → 輔助使用 → 觸控 → 輔助觸控(AssistiveTouch)。鍵盤則開箱即用。
  • **重新配對後藍牙失效?**先在主機的藍牙清單中移除本裝置, 再於選單使用 Clear pairing,然後重新配對。
  • **偵測不到動作感測器?**韌體會自動切換到方向鍵游標,並在螢幕上提示。
  • **你的硬體傾斜方向相反?**調整 src/core/mouse_engine.h 中的 rollSign / pitchSign。
  • **重新燒錄永遠可行:**兩種傳輸模式下 USB 連接埠都保持為序列主控台 — 不需要按開機鍵的流程。USB 傳輸模式下,裝置是 CDC + HID keyboard + HID mouse 複合裝置,在 BIOS/UEFI 中也能輸入。