## 🛠️ KMonad 使用指南
KMonad 的核心是其 **配置檔案**，通常是一個 `.kbd` 檔案。
### 步驟一：安裝 KMonad (Linux)
KMonad 需要從原始碼編譯或使用發行版套件管理器（如果有的話）。
1. **安裝必要套件：**
```bash
sudo apt update
sudo apt install ghc cabal-install git
```
2. **克隆 KMonad 儲存庫並編譯：**
```bash
git clone https://github.com/kmonad/kmonad
cd kmonad
cabal update
cabal install
```
*如果編譯成功，KMonad 可執行檔通常會被放在 `~/.cabal/bin/kmonad`。*
### 步驟二：確定鍵盤路徑
KMonad 需要知道它應該接管哪個鍵盤輸入。
1. **列出所有輸入裝置：**
```bash
ls /dev/input/by-id/
```
2. 找到您的鍵盤裝置，它可能看起來像這樣：`usb-KEYBOARD_NAME-event-kbd`。
3. 記下這個完整路徑，例如：`/dev/input/by-id/usb-My_Keyboard-event-kbd`。
### 步驟三：編寫 KMonad 配置檔案 (`config.kbd`)
我們將設定一個名為 `FUNCTION` 的新層級 (Layer)，並使用 **Scroll Lock** 作為切換到此層級的鍵。
建立一個檔案，例如 `~/.config/kmonad/basic.kbd`
**重要觀念：**
* **`defsrc`**: 定義鍵盤的物理配置。
* **`deflayer`**: 定義一個模式或層級。
### 步驟四：啟動 KMonad
在終端機中，以後台模式運行 KMonad，並使用您剛剛建立的配置檔。
```bash
sudo ~/.cabal/bin/kmonad ~/.config/kmonad/basic.kbd
```
**注意：** KMonad 通常需要 **`sudo` 權限**才能創建虛擬輸入裝置並接管 `/dev/input`。
## KMonad: ISO 100% template
```
#| --------------------------------------------------------------------------
KMonad: ISO 100% template
This file contains the `defsrc' configuration for a standard
ISO 100% keyboard, modelled on a standard European model.
Copy out the `defsrc' layer to start your own keyboard configuration. Copy
out the `deflayer' template to easily start a new layer with matching
`transparent' buttons. `102d', the key on the right of the left shift key,
which is named this way because it used to be the 102nd key on a 100% board,
is the so called "iso" key. `nubs', short for "Non-US backslash", can also be
used in place of `102d'. `lsgt', which stands for "less (<) / greater (>)",
is yet another valid name for that key.
(deflayer name
_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _
_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _
_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _
_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _
_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _
_ _ _ _ _ _ _ _ _ _ _ _ _
)
-------------------------------------------------------------------------- |#
(defsrc
esc f1 f2 f3 f4 f5 f6 f7 f8 f9 f10 f11 f12 ssrq slck pause
grv 1 2 3 4 5 6 7 8 9 0 - = bspc ins home pgup nlck kp/ kp* kp-
tab q w e r t y u i o p [ ] ret del end pgdn kp7 kp8 kp9 kp+
caps a s d f g h j k l ; ' \ kp4 kp5 kp6
lsft 102d z x c v b n m , . / rsft up kp1 kp2 kp3 kprt
lctl lmet lalt spc ralt rmet cmp rctl left down rght kp0 kp.
)
```
## 自訂鍵盤
```
(defcfg
;; 設定要讀取的鍵盤輸入裝置路徑：ls /dev/input/by-id/
;; 請將這裡替換成您找到的路徑！
input (device-file "/dev/input/by-id/usb-Ducky_Zero_3108T-event-kbd")
;; 2. 設定輸出裝置（讓 KMonad 建立一個虛擬鍵盤）
output (uinput-sink "KMonad Virtual Keyboard")
fallthrough true ;; 重要：未定義的按鍵會維持原功能，不會失效
allow-cmd true ;; 允許執行系統指令
)
;; 所有層級（Layer）的模板
(defsrc
esc f1 f2 f3 f4 f5 f6 f7 f8 f9 f10 f11 f12 ssrq slck pause calc mute vold volu
grv 1 2 3 4 5 6 7 8 9 0 - = bspc ins home pgup nlck kp/ kp* kp-
tab q w e r t y u i o p [ ] ret del end pgdn kp7 kp8 kp9 kp+
caps a s d f g h j k l ; ' \ kp4 kp5 kp6
lsft 102d z x c v b n m , . / rsft up kp1 kp2 kp3 kprt
lctl lmet lalt spc ralt rmet cmp rctl left down rght kp0 kp.
)
(defalias
;; 定義別名：按下 sl 時切換到 'func' 層，放開後回到 'base' 層
mFu (momentary-layer func) ;; momentary-layer(按住時有效) 放開失效 短促的功能觸發（如 Shift 邏輯）
tFu (layer-toggle func) ;; layer-toggle(切換開關) 這是最接近 Caps Lock 邏輯的動作。按一下切換到目標層級，再按一下回到原層級。
nFu (layer-next func) ;; layer-next(下一鍵切換) 按一下這個鍵後，只有下一個按下的鍵會屬於目標層級，之後自動跳回 base 層。
etl (tap-next esc lctl) ;; tap-next(點擊或按住) 點擊發 ESC，按住發 Left Ctrl，空間節省，將大鍵改造成多功能鍵
;; 使用 around：第一個參數是「外層動作」，第二個是「核心按鍵/動作」
;; 當你按下 pFu 時，它會執行 @sFu 並保持在 (layer-next func) 狀態
pFu (around @sFu (layer-next func))
;; 定義功能別名
qBw (cmd-button "/home/adam/etc/script/quit.sh")
qKm (cmd-button "killall kmonad") ;; 關閉 kmonad
uRt (cmd-button "/home/adam/etc/script/updateRoute.sh") ;; 更新路由表
loc (cmd-button "loginctl lock-session") ;; 鎖定螢幕
sFu (cmd-button "systemd-run --user --machine=adam@.host --quiet --collect notify-send -r 100 'KMonad' '層級已切換到 Func'")
)
;; === 鍵盤層級定義 ===
(deflayer base
esc f1 f2 f3 f4 f5 f6 f7 f8 f9 f10 f11 f12 ssrq @nFu pause calc mute vold volu
grv 1 2 3 4 5 6 7 8 9 0 - = bspc ins home pgup nlck kp/ kp* kp-
tab q w e r t y u i o p [ ] ret del end pgdn kp7 kp8 kp9 kp+
caps a s d f g h j k l ; ' \ kp4 kp5 kp6
lsft 102d z x c v b n m , . / rsft up kp1 kp2 kp3 kprt
lctl lmet lalt spc ralt rmet cmp rctl left down rght kp0 kp.
)
;; (_)下底線表示繼承（維持切換鍵狀態）
(deflayer func
esc f1 f2 f3 f4 f5 f6 f7 f8 f9 f10 f11 f12 ssrq @qBw pause calc mute vold volu
grv 1 2 3 4 5 6 7 8 9 0 - = bspc ins home pgup nlck kp/ kp* kp-
tab q w e r t y u i o p [ ] ret del end pgdn kp7 kp8 kp9 kp+
caps a s d f g h j k l ; ' \ kp4 kp5 kp6
lsft 102d z x c v b n m , . / rsft up kp1 kp2 kp3 kprt
lctl lmet lalt spc ralt rmet cmp rctl left down rght kp0 kp.
)
```
## 建立服務 Service
要讓 **KMonad** 在 Ubuntu 開機時自動執行，最穩定且推薦的方法是將其設定為 **Systemd 服務**。由於 KMonad 需要讀取硬體裝置（如 `/dev/input/`），以系統服務執行可以確保它擁有必要的 `root` 權限。
以下是完整的設定步驟：
-----
### 1. 建立服務定義檔
請開啟終端機，使用 `nano` 建立一個新的服務檔案：
```bash
sudo vi /etc/systemd/system/kmonad.service
```
### 2. 貼入以下內容
請根據您的實際路徑修改 `ExecStart` 中的路徑：
```ini
[Unit]
Description=KMonad keyboard daemon
# 確保在圖形介面準備好後才啟動
After=local-fs.target
[Service]
# 請將 /home/adam/ 替換為您的使用者目錄
# 第一個路徑是 kmonad 執行檔，第二個是您的 .kbd 設定檔
ExecStart=/home/adam/.cabal/bin/kmonad /home/adam/.config/kmonad/basic.kbd
# 如果程式崩潰，自動重啟
Restart=always
RestartSec=3
[Install]
WantedBy=multi-user.target
```
-----
### 3\. 啟動與啟用服務
執行以下指令來讓設定生效：
1. **重新載入系統服務列表：**
```bash
sudo systemctl daemon-reload
```
2. **設定開機自動啟動：**
```bash
sudo systemctl enable kmonad.service
3. **立即手動啟動（測試）：**
```bash
sudo systemctl start kmonad.service
```
---
### 🔍 故障排除與監控
如果啟動後發現按鍵沒反應，可以透過以下方式除錯：
* **檢查服務狀態：** ```bash
sudo systemctl status kmonad.service
```
如果您看到 `Parse error`，代表您的 `.kbd` 檔語法有誤。
* **查看實時錯誤訊息：**
```bash
journalctl -u kmonad.service -f
```
這能讓您看到 KMonad 在執行指令（如 `notify-send`）時是否因為 D-Bus 環境變數設定不當而報錯。
* **緊急停止：** 萬一開機後鍵盤完全卡死，請使用滑鼠開啟終端機執行 `sudo systemctl stop kmonad.service` 即可恢復原始鍵盤功能。