[鍵盤] RMK Rust鍵盤韌體分享

代友po，原作者：https://github.com/ziteh

各位板友好，我是 ZiTe，好久不見
今天不是要分享 ErgoSNM 鍵盤，而是想介紹最近在測試的鍵盤韌體 RMK
https://haobogu.github.io/rmk

受限於 PTT 大概不太適合寫太多 code block 和篇幅問題，本篇就僅以 nRF52840 做一個簡單的分享。完整的教學還請移步 Blog
https://blog.ziteh.dev/posts/rmk-fw-intro

在這個 Rust 滿天飛的現在，鍵盤韌體當然也要有 Rust 的參與，RMK 是一個以 Rust 寫成的機械鍵盤韌體，架構在 Embassy 非同步嵌入式應用框架上。

對我來說 RMK 對比 QMK 有以下好處：
- 原生支援 nRF MCU 和藍牙 BLE
- License 是寬鬆的 Apache2.0 和 MIT，而非具感染性的 GPL

RMK 對比 ZMK 有以下好處：
- 支援 Vial 即時編輯 Keymap 鍵位
- Rust 開發環境比 Zephyr 更容易建立
- Kconfig + Devicetree 有一定的複雜度
- 在我的測試中 RMK 的藍牙比 ZMK 更穩定

---

1. 建立開發環境

首先要安裝 Rust 環境，這部分就和一般開發 Rust 時要做的事情一樣。
對於 Windows 使用者來說就是下載並使用 rustup 這個工具安裝，此外還要下載
Visual Studio 並安裝「Desktop Development with C++」
請參考：https://rustup.rs

再來要添加編譯目標，因為開發韌體算是交叉編譯，因此要為 Rust 添加目標平臺的編譯功能。這部分的命令會因你所使用的不同開發板和 MCU 而有所不同。
以 nRF52840（Cortex-M4 with FPU）來說的話請打開終端機執行：

rustup target add thumbv7em-none-eabihf

然後要安裝一些工具（rmkit、flip-link、cargo-make）：

cargo install rmkit flip-link cargo-make

最後還要安裝文字編輯器，一般推薦使用 VS Code，就照一般的軟體下載安裝即可。VS
Code 安裝好後建議再安裝一些擴充套件：Even Better TOML 和 rust-analyzer。
VS Code：https://code.visualstudio.com

---

2. 建立韌體專案

開啓終端機，移動到目標路徑（這裡示範爲 D 槽下的 rmk 資料夾），使用 rmktit 開啓互動式專案建立：

cd D:/rmk
rmkit init

只要依序回答專案名稱、鍵盤類型和目標 MCU 即可

完成後會建立專案資料夾，例如 D:/rmk/my-rmk-kb/。使用 VS Code 開啓此資料夾。

---

3. 編輯 keyboard.toml

首先最重要的是 keyboard.toml 這個檔案，它包含了大多數的鍵盤設定。接下來會分各個部分大致簡介，如果想知道詳細說明的話請參考官方文件：
https://haobogu.github.io/rmk/keyboard_configuration.html

keybaord.toml 完整範例
https://i.imgur.com/88DuNiD.png

[keyboard]
包含了基本資訊，比較重要的是：

- product_name 是顯示名稱，也就是搜尋藍牙時會出現的裝置名。
- vendor_id 和 product_id 是 USB 的東西，你不知道這是什麼的話可以不用改。
- chip 是你要用的 MCU，這裡是 nrf52840。

[matrix]
定義鍵矩陣掃描的 IO 腳，要注意的是這裡的腳位名稱要使用 Embassy 裡的
Peripherals 名稱，對 nRF52840來說 也就是 P1_05 這種。

RMK 預設使用 col2row 方向

[layout]
定義 Keymap 按鍵佈局。rows 和 cols 的數量要和 matrix 的 IO 腳部分配合，layers用來定義分層數量。

keymap 就是定義按鍵佈局，可用的 KeyCode 請參考：
https://docs.rs/rmk/latest/rmk/keycode/enum.KeyCode.html

另外還有一些特殊的修飾鍵，如 MO(1) 代表暫時切換到 layer 1。這些修飾鍵和 QMK 的定義是相同的，可以參考：
https://docs.qmk.fm/feature_layers

[behavior]
定義一些不同的鍵盤行為。例如 One Shot、Combo 鍵等等。這部分屬於比較進階的功能就先跳過。

[light]
定義指示燈的 IO，包含 capslock、numslock、scrolllock。

[storage]
定義儲存設定，RMK 會將 Keymap 資料和 BLE 連線資訊儲存在 Flash 中的特定位置。
預設情況下它是啓用的，並且會使用最後 2 個 sector 儲存資料。

有些 Bootloader（例如 Adafruit nRF52 Bootloader）會和此預設位置衝突，這時就需要修改這邊的 start_addr 設定，例如將其設為 start_addr = 0x000A0000。

另外還有一個 clear_storage，如果將其設爲 true 那每次鍵盤開機都會清空這些資訊，通常用於開發測試。

[ble]
設定無線藍牙的相關功能。對我們來說就是將 enabled = true 啓用 BLE 就行了。

---

4. 編輯 memory.x

這個是用來定義 MCU 的 RAM 和 Flash 佈局。使用 nRF52840 的話，會牽扯到你使用的SoftDevice 要修改韌體起始位置，也就是 FLASH : ORIGIN = ???。

使用 S140 v6.1.1 的話可以使用 0x00026000，如果是 7.3.0 的話可以用
0x0027000。

這裡以 S140 v6.1.1 爲例：
https://i.imgur.com/6tRQNGv.png

注意這裡的 1K 是 1KiB 也就是 1024 bytes

---

5. 編輯 vial.json

再來是 vial.json 檔案，要設定好才能使用 Vial 編輯 Keymap，這個是 Vial 要用的，其格式請參考文件說明：
https://get.vial.today/docs/porting-to-via.html

或
https://blog.ziteh.dev/posts/diyqmkkeyboard-vial

---

6. 編譯設定

這邊只要再次確認 .carbo/config.toml 裡的 build.target 是不是
thumbv7em-none-eabihf 即可。

---

7. 編譯

接下來就可以進行編譯了，在 VS Code 開啓終端機（上方選單列 > Terminal > New
Terminal）並執行：

cargo build --release

如果成功的話會產生在 target/thumbv7em-none-eabihf/release/my-rmk-kb
編譯完成的韌體沒有副檔名，但它其實是 ELF 檔案。

但我們可能更喜歡 .uf2 和 .hex，所以要改用 cargo-make，執行：

cargo make uf2 --release

成功後會在專案資料夾下產生 my-rmk-kb.uf2 和 my-rmk-kb.hex

---

8. 燒錄

主要有兩種燒錄方式。

如果你的 MCU 有 UF2 Bootloader 的話，只要用 USB 將其接上電腦並進入 DFU 模式，此時它會變成一個隨身碟，再將剛剛編譯完的 .uf2 檔複製貼上進去即可。

進入 DFU 模式的方法不同的 Bootloader 都不同，但通常是快速按 RESET 按鈕兩次。

如果你的 MCU 沒有 UF2 Bootloader 的話，要使用專門的燒錄器如 J-Link 或 DAP
Link 等，將 MCU 或開發板接上燒錄工具，再使用燒錄程式（如 nrfjprog、probe-rs、OpenOCD）。

如果你喜歡 GUI 工具的話，可以用 Nordic 官方的 nRF Connect for Desktop，裡面有個 Programmer 可以燒錄。

完成燒錄後就可以用 USB 或藍牙連接到電腦，它應該已經可以正常運作了

注意！
nRF MCU 要使用藍牙功能的話會需要 SoftDevice，以 nRF52840 來說的話要使用藍牙通常是選擇 S140，然後 RMK 目前支援 v6.x 和 v7.x。

如果你的 nRF52840 已經有燒錄好 UF2 Bootloader 的話，要查看其使用的 SoftDevice版本。
方法爲進入 DFU 後，開啓其中的 INFO_UF2.TXT 檔案，內部會標註版本如 SoftDevice:S140 version 6.1.1。

如果你的 nRF52840 是完全空的，那除了燒錄 RMK 韌體外，你還要先為其燒錄
SoftDevice。
先到 Nordic 官網下載對應的 SoftDevice，然後用燒錄器將 .hex 檔案（如
s140_nrf52_7.3.0_softdevice.hex）燒進 MCU 內。

https://i.imgur.com/EPTsdgz.png
以上圖為例，我加入了兩個檔案：
- SoftDevice：s140_nrf52_7.3.0_softdevice.hex
- RMK 韌體：my-rmk-kb.hex

其中綠色的部分是我們的 RMK 韌體，可以確認其起始位置是 0x00027000，沒有和
SoftDevice 重疊。而藍色的區域就是 SoftDevice，我燒錄的是 S140 v7.3.0。最下面的橘色是 MBR 開機區域。

---

我有建立一個範例 repo 可以參考，也有預編譯的 .hex 和 .uf2 可以測試
https://github.com/siderakb/rmk-example

前陣子我還在處理 ErgoSNM v3 鍵盤，突然看到 RMK 且用起來很不錯，所以未來我開發鍵盤可能都會更傾向使用它取代 QMK 和 ZMK

尤其不知道爲什麼 ZMK 不管我用其它人編譯好的還是自己編譯，BLE 連線都很不穩定，用得有點頭痛

但是它目前最大的問題是缺乏對遊標裝置的支援，所以我的 ErgoSNM 還沒辦法使用它

至於 ErgoSNM 的後續進度的話，因爲我最近在準備換工作，比較忙，遙遙無期呀~

--