# Key Frequency Logger

自從 ErgodoxTW 開賣以後,有成功的讓新的使用者開始體會到自己定義鍵位,來符合自己的使用習慣後,就有人開始想要透過真實的數據分析,來協助他決定什麼功能的按鍵應該擺放在越前面的 layer,或者甚至是擺放在手更加自然可以伸展到的地方後,於是就有能夠紀錄按鍵過程的需求了。

這個需求乍聽之下好像並不困難,有人可能會想說應該 Karabiner 等等的程式就可以做到了。但其實仔細思考後,這件事卻並不如想像中的那麼簡單。首先是 TMK,QMK 等等的韌體,因為你可以自由 mapping 按鍵,所以你可能會有多顆按鍵都是同一個功能 (例如我有設定很多顆按鍵都是 ctrl,方便我在按不同組合鍵時使用),所以這些跑在電腦端的程式只能知道你按下了 ctrl,但他不知道你按的是哪一個 ctrl,他更不會知道你現在在哪一個 layer。簡單來說,有太多的資訊都隱藏在鍵盤中,是無法被電腦得知的。

也因此,在經過一番研究後,我就寫出了這個 key frequency logger。他是一隻簡單的程式,當你跑起來的時候,他會開始偵測是否有會輸出訊息的 TMK 或 QMK 鍵盤,在抓到這樣的鍵盤後,他就會開始接收鍵盤送來更詳細的資訊,最後把整個完整的按鍵紀錄儲存成一個 csv 檔案。有了 csv 檔案以後,你就可以打開你的 excel 開始分析,或者你如果是一名軟體工程師,很自然的就可以用 python 等等的 programming language 開始做更進一步的分析了。

# 程式下載


檔案可以在 releases 這裡下載。

# 設定

要使用 key frequency logger,有兩個先決條件:

  1. 要在電腦上運行這隻程式
  2. TMK 或 QMK 鍵盤要設定並輸出一個定義好的 debug message

第一點相對來說比較簡單,我已經把編譯好,直接下載下來就可以運行的程式跑起來就可以了。

第二點相較來說則比較困難一點,必須要能夠自己編譯鍵盤的韌體。如果需要協助的朋友,歡迎直接訊息聯絡我,在我能力所及範圍內盡量幫你生出韌體。如果已經能夠編譯 QMK 韌體的朋友,則可以參考以下的教學,把 debug message 加到鍵盤中,並編譯完成就可以燒錄上去開始使用。

# debug message

這隻程式會接收所有鍵盤輸出的 debug message,但只會對一些特定格式的訊息有反應。這個特定格式訊息如下

ErgoKB:COL,ROW,PRESSED,LAYER,KEYCODE\n

,當中 COL, ROW, PRESSED, LAYER, KEYCODE 都是數字,從名字上也可以看出代表的意義:

  • COL: 按鍵所在的 column
  • ROW: 按鍵所在的 row
  • PRESSED: 代表按鍵是否按下,這邊以數字表示的話,0 表示放開,1 表示按下
  • LAYER: 當前鍵盤所採用的 layer
  • KEYCODE: 按鍵按下/放開時送出的按鍵功能代號

以下是一個範例

ErgoKB:4,6,0,1,40\n

這行訊息代表的意義是位在 column 4,row 6 的按鍵放開了 (0),當時鍵盤所用的 layer 是 1,然後放開的按鍵送出了按鍵功能代號 40

只要送出的訊息符合這樣的格式,程式就會去解讀他,並且把它轉換成 csv 的格式存起來。

如果你不清楚要怎麼把這個訊息加到鍵盤韌體之中,可以參考以下的簡易範本。你可以把下面這段 code 加到你的 keymap.c 檔案中:

#include <debug.h>

uint8_t current_layer = 0;

layer_state_t layer_state_set_user(layer_state_t state) {
	current_layer = get_highest_layer(state);
	return state;
}

bool process_record_user(uint16_t keycode, keyrecord_t *record) {
	uprintf("ErgoKB:%u,%u,%u,%u,%u\n", record->event.key.col, record->event.key.row, record->event.pressed, current_layer, keycode);
	return true;
}

當然,如果你本來的 keymap.c 當中已經有定義這些 function 了,你需要做相應的修改,可以直接把他整合進 function 中即可。

# 使用

這是一個只有 terminal 介面黑黑的程式,在 macOS 上面你也可以直接點兩下程式,他會自己開始運作

程式會顯示一些資訊給你看,像是輸出的 csv 檔案會存在哪裡,你可以透過 terminal,加上不同的 flag ,可以修改這些參數。他會有一個動畫,顯示正在等待你插入可以輸出訊息的鍵盤

鍵盤被偵測到後,就會開始進行紀錄。

接著按下鍵盤上的按鍵,他就會輸出一些訊息提示你已經在收資料了。而要離開這隻程式,你可以直接關掉 terminal 視窗,或者按下 ctrl + c 強制關閉即可。由於受限於 QMK 的實作,所以輸出的 keycode 我只能盡可能的把他 mapping 回去,對於無法 mapping 的 keycode,則暫時維持原樣。

如果你喜歡我的 work,歡迎你幫我分享,或者也可以對這個專案發 PR,來讓他變得更棒,讓我們一起來做一把能讓你用得開心的鍵盤和設定吧!