ZMKキーボードにドングルとProspectorを追加する方法
この記事では、既存のZMKキーボードにドングルおよびProspectorのサポートを追加する方法を解説します。
例として HSHS52キーボード を使用しますが、他のZMK対応の一体型や分割型キーボードでも同様に適用できます。
Prospector は、carrefinho氏が開発した、ディスプレイ付きのZMKドングルです。(https://github.com/carrefinho).
参考リンク
- https://zmk.dev/docs/development/hardware-integration/dongle
- https://github.com/carrefinho/prospector-zmk-module
- https://github.com/beekeeb/zmk-config-hshs
ドングルサポートの追加
例として Prospector ドングルを使用しますが、ZMKが対応する任意のBLEボードでも構いません。
まず、 https://github.com/beekeeb/zmk-config-hshs をフォーク（コピー）し、ローカル環境にクローン（ダウンロード）します。
Kconfig.shield の編集
config/boards/shields/hshs52/Kconfig.shieldを開き、以下を追記します。
config SHIELD_HSHS52_DONGLE
def_bool $(shields_list_contains,hshs52_dongle)修正後の内容例
config SHIELD_HSHS52_LEFT
def_bool $(shields_list_contains,hshs52_left)
config SHIELD_HSHS52_RIGHT
def_bool $(shields_list_contains,hshs52_right)
config SHIELD_HSHS52_DONGLE
def_bool $(shields_list_contains,hshs52_dongle)Kconfig.defconfig の編集
config/boards/shields/hshs52/Kconfig.defconfigに以下を追加します。
if SHIELD_HSHS52_DONGLE
# Max 16 characters in keyboard name
config ZMK_KEYBOARD_NAME
default "HSHS52"
config ZMK_SPLIT_ROLE_CENTRAL
default y
config ZMK_SPLIT
default y
# Set this to the number of peripherals your dongle will have.
# For a unibody, this would be 1. If you have left and right halves, set it to 2, etc.
config ZMK_SPLIT_BLE_CENTRAL_PERIPHERALS
default 2
# Set this to ZMK_SPLIT_BLE_CENTRAL_PERIPHERALS + your desired number of BT profiles (default is 5)
config BT_MAX_CONN
default 7
# Set this to the same number as BT_MAX_CONN
config BT_MAX_PAIRED
default 7
endif※ if SHIELD_HSHS52_LEFT のセクションは削除して構いません。左側を中央デバイスとして使用しないためです。
hshs52_dongle.overlay の作成
次に、config/boards/shields/hshs52/hshs52_dongle.overlayを新規作成し、以下を記述します。
#include <dt-bindings/zmk/matrix_transform.h>
/ {
chosen {
zmk,kscan = &mock_kscan;
zmk,matrix_transform = &default_transform;
};
mock_kscan: mock_kscan_0 {
compatible = "zmk,kscan-mock";
columns = <0>;
rows = <0>;
events = <0>;
};
default_transform: keymap_transform_0 {
compatible = "zmk,matrix-transform";
columns = <12>;
rows = <5>;
// | SW1 | SW2 | SW3 | SW4 | SW5 | SW6 | | SW6 | SW5 | SW4 | SW3 | SW2 | SW1 |
// | SW7 | SW8 | SW9 | SW10 | SW11 | SW12 | | SW12 | SW11 | SW10 | SW9 | SW8 | SW7 |
// | SW13 | SW14 | SW15 | SW16 | SW17 | SW18 / SW19 / \ SW19 \ SW18 | SW17 | SW16 | SW15 | SW14 | SW13 |
// | SW20 | SW21 | SW22 | SW23 / SW24 / SW25 / SW26 / \ SW26 \ SW25 \ SW24 \ SW23 | SW22 | SW21 | SW20 |
map = <
RC(0,0) RC(0,1) RC(0,2) RC(0,3) RC(0,4) RC(0,5) RC(0,6) RC(0,7) RC(0,8) RC(0,9) RC(0,10) RC(0,11)
RC(1,0) RC(1,1) RC(1,2) RC(1,3) RC(1,4) RC(1,5) RC(1,6) RC(1,7) RC(1,8) RC(1,9) RC(1,10) RC(1,11)
RC(2,0) RC(2,1) RC(2,2) RC(2,3) RC(2,4) RC(2,5) RC(4,5) RC(4,6) RC(2,6) RC(2,7) RC(2,8) RC(2,9) RC(2,10) RC(2,11)
RC(3,0) RC(3,1) RC(3,2) RC(4,1) RC(4,2) RC(4,3) RC(4,4) RC(4,7) RC(4,8) RC(4,9) RC(4,10) RC(3,9) RC(3,10) RC(3,11)
>;
};
};
※公式ドキュメントでは physical_layout0 が使用されていますが、動作しなかったため、ここでは default_transform を直接使用します。
config/west.yml の編集
https://github.com/carrefinho/prospector-zmk-module に従い、以下のように追記します。
manifest:
remotes:
- name: zmkfirmware
url-base: https://github.com/zmkfirmware
- name: carrefinho # <--- add this
url-base: https://github.com/carrefinho # <--- and this
projects:
- name: zmk
remote: zmkfirmware
revision: main
import: app/west.yml
- name: prospector-zmk-module # <--- and these
remote: carrefinho # <---
revision: main # <---
self:
path: configbuild.yml の更新
build.yamlを以下のように編集します。
include:
- board: nice_nano_v2
shield: hshs52_left nice_view_adapter nice_view
cmake-args: -DCONFIG_ZMK_SPLIT=y -DCONFIG_ZMK_SPLIT_ROLE_CENTRAL=n
- board: nice_nano_v2
shield: hshs52_right nice_view_adapter nice_view
cmake-args: -DCONFIG_ZMK_SPLIT=y -DCONFIG_ZMK_SPLIT_ROLE_CENTRAL=n
- board: nice_nano_v2
shield: hshs46_left nice_view_adapter nice_view
cmake-args: -DCONFIG_ZMK_SPLIT=y -DCONFIG_ZMK_SPLIT_ROLE_CENTRAL=n
- board: nice_nano_v2
shield: hshs46_right nice_view_adapter nice_view
cmake-args: -DCONFIG_ZMK_SPLIT=y -DCONFIG_ZMK_SPLIT_ROLE_CENTRAL=n
- board: nice_nano_v2
shield: settings_reset
- board: seeeduino_xiao_ble
shield: settings_reset
- board: seeeduino_xiao_ble
shield: hshs52_dongle prospector_adapter⚠️ リセット用ファームウェアを書き込む際は、複数デバイスの電源を同時に入れないよう注意してください。
Prospectorの明るさ設定
Prospectorを光センサーなしで組み立てた場合は、config/hshs52.conf に以下を追記します。
CONFIG_PROSPECTOR_USE_AMBIENT_LIGHT_SENSOR=n
CONFIG_PROSPECTOR_FIXED_BRIGHTNESS=80レイヤー名の更新
デフォルトではレイヤー名が「0, 1, 2」と表示されます。
任意の名前に変更したい場合は、config/boards/shields/hshs52/hshs52.keymap を編集します。
詳細はhttps://github.com/carrefinho/prospector-zmk-module?tab=readme-ov-file#usageを参照してください。
コンパイル
編集内容をGitHubに反映（プッシュ）したら、リポジトリの “Actions” タブでビルド処理（ワークフロー）を実行します。
完成例は以下のリポジトリにあります。
http://github.com/beekeeb/zmk-config-hshs-with-prospector
よくある問題
ディスクの不正な取り出し
→無視して構いません。
書き込んだファームウェアがUSBドライブに表示されない
→UF2書き込み用のドライブなので、書き込んだ後に中身が見えないのは正常です。
ペアリングできない場合
→ZMKデバイスの電源をすべて切り、各デバイス（ドングル・左右分割）にリセットファームウェアを再度書き込みます。
本ガイドでは Dongle に Xiao nRF52840、分割側に nice!nano v2 を使用しています。
正しいリセットファームウェアが書き込まれているか確認してください。
キー入力が反応しない場合
→Prospectorドングルで使用しているUSBケーブルが「充電専用ケーブル」ではなく「データ通信対応ケーブル」であることを確認してください。
