Skip to content
BranchesTags

Repository files navigation

Caravelle BLE ZMK Firmware

自作キーボードキット「Caravelle-BLE」を ZMK Firmware で動作させるための設定リポジトリです。
QMK + nRF52 環境から、ハードウェア改造なしにワイヤレス (OTA) のまま ZMK に移行・運用できます。

特徴

  • Bluetooth (OTA) 経由でのファームウェアアップデート完全対応
    • Caravelle BLE 純正のブートローダ（Nordic SDK 12.3.0 Secure DFU）環境のまま、PC ブラウザやスマホアプリからワイヤレスで書き換え可能
  • キー入力による Nordic Secure DFU（DfuTarg）モード移行に対応 (&nordic_dfu)
    • ADJUST レイヤーのキー操作だけで、物理タクトスイッチ（SW3/SW4）を押すことなく左右それぞれ単体でブートローダ（DfuTarg）に突入可能
    • DFU 待機中にファームウェア更新をやめたくなった場合でも、電源を OFF ➡️ ON にするだけで通常キーボードに安全に復帰
  • マウスキー機能（Pointing）対応
    • CONFIG_ZMK_POINTING=y により、キーボード単体でマウスカーソル移動、左右中クリック、ホイールスクロールが可能
    • デフォルトレイヤーの .（ピリオド）長押しで即座にマウスレイヤーが発動
  • 一次電池向けバッテリー残量管理モジュール対応
    • 単4一次電池駆動に対応したカスタムバッテリー管理モジュールを搭載し、正確な残量表示に対応
  • ZMK Studio によるリアルタイムのキーマップ編集
    • Bluetooth 接続対応の ZMK Studio デスクトップ版から、GUI 上でキーマップを直感的にカスタマイズ可能
  • GitHub Actions & 高速ローカルビルド対応
    • GitHub Actions による自動パッケージングに加え、ローカル Docker 環境（scripts/build_local.sh）により約 15〜20 秒で左右のファームウェアと OTA zip のコンパイルが可能
  • 安定＆低遅延な使用感 / マルチペアリング (最大 6 台)
    • 複数台の PC やスマートフォンとペアリングし、ワンタッチでスムーズに切り替え可能

ファームウェアの更新方法 (OTAアップデート)

GitHub Actions のビルド成果物（Artifacts: caravelle_ble_firmware）またはローカルビルド（artifacts/）に含まれる以下のパッケージを使用して、ワイヤレスでアップデートできます。

  • 左手用: caravelle_left_central_ota.zip
  • 右手用: caravelle_right_peripheral_ota.zip

1. PC からの OTA アップデート (Web Bluetooth) 【自己責任】

Web Bluetooth API に対応したブラウザ（Google Chrome、Microsoft Edge など）を使用することで、PC から直接 OTA アップデートが可能です。

Warning

【重要・自己責任】
PC の Web ブラウザ経由での OTA アップデートは、Bluetooth アダプタや OS 環境・ブラウザの挙動によって通信が途切れるリスクがあります。転送失敗等により万が一文鎮化した場合は、ST-Link 等の SWD ライタを用いた有線復旧が必要となります。必ず自己責任であることをご了承の上でご利用ください。

手順:

  1. キーボード側で DFU (ブートローダ) モードに入ります（ADJUST レイヤーの &nordic_dfu キーを押すか、基板上のタクトスイッチを押しながら電源 ON）。デバイスが DFU 待機状態 (DfuTarg) になります。
  2. 上記サイトを Chrome 等で開き、画面の指示に従って Bluetooth デバイスをスキャン・接続します。
  3. ダウンロードした OTA パッケージ（左手なら caravelle_left_central_ota.zip、右手なら caravelle_right_peripheral_ota.zip）を選択します。
  4. アップデートを実行し、100% 完了するまでキーボードの電源を切らずにお待ちください。

2. スマートフォンからの OTA アップデート (公式アプリ推奨)

Nordic 公式アプリを使用すると、安定して OTA アップデートが行えます。

  • 対応アプリ:
    • nRF Connect for Mobile (iOS / Android)
    • nRF Device Firmware Update (iOS / Android)
  • 手順:
    1. スマホに OTA パッケージ (.zip) をダウンロード・保存します。
    2. キーボードを DFU モードにします。
    3. アプリを起動してスキャンし、DfuTarg に接続します。
    4. DFU 画面から zip ファイル（Distribution packet (ZIP)）を選択して転送します。

有線でのトラブル復旧 / リカバリ (ST-Link 使用)

OTA アップデートの失敗等でキーボードが起動しなくなった場合など、有線での緊急復旧が必要になったときの手順です。
※ 通常の使用や初回導入時には ST-Link は不要です（OTA で書き換え可能です）。

  • 想定環境 : Windows11 + WSL(Ubuntu) + Devcontainer
  • 必要なもの : ST-Link の互換機 (例: AliExpress や Amazon で入手可能な安価な ST-Link V2 クローン)

注意

  • ブートローダや SoftDevice を全消去（mass_erase）した場合は、OTA 機能が失われます。その場合は本ページ末尾の「ソフトデバイスとブートローダの復旧」手順を行ってください。

復旧手順 (ST-Link 使用時)

  1. ビルド環境の作成（GitHub Actionsでオンラインビルドする場合は不要）
    1. zmk-workspaceの手順で開発コンテナを使用して、zmkのローカルビルドを整える
    2. config/zmk-caravelle-ble として zmk-caravelle-ble リポジトリを git clone
    3. scripts/build_local.sh を実行してビルド
  2. ST-LinkをCaravelle BLEのPCBのシルク印刷（3.3V GND SWDIO SWDCLK）に従って接続
  3. WSLのUbuntuで以下のコマンドを実行して、PCBと接続できていることを確認 $ openocd -f interface/stlink.cfg -f target/nordic/nrf52.cfg
  4. 以下のコマンドで左手分を書き込み
    $ openocd -f interface/stlink.cfg -f target/nordic/nrf52.cfg -c "init; halt; nrf5 mass_erase; program ./artifacts/caravelle_left_central.bin 0x0 verify reset; exit"
  5. 同様に右手のPCBにST-Linkを接続して右手分を書き込み
    $ openocd -f interface/stlink.cfg -f target/nordic/nrf52.cfg -c "init; halt; nrf5 mass_erase; program ./artifacts/caravelle_right_peripheral.bin 0x0 verify reset; exit"
  6. ホスト側のBluetooth情報をリセットして、"Caravelle BLE" という名前で検出されるので接続する

キーマップ構成・レイアウト図

Caravelle BLE は左右合計 48 キー（各手 24 キー）の左右分割レイアウトです。
ベースレイヤー（Layer 0）は Qwerty配列 と Dvorak配列 の両方に対応しており、config/caravelle.keymap の先頭にある #define USE_DVORAK_AS_DEFAULT で切り替えが可能です。

  • main ブランチ: 一般公開用として Qwerty配列 がデフォルト（#define USE_DVORAK_AS_DEFAULT 0）
  • dev ブランチ: 常用・開発用として Dvorak配列 がデフォルト（#define USE_DVORAK_AS_DEFAULT 1）

Mod-Tap (&mt) は高速打鍵時の誤ホールドを防ぐ tap-preferred 設定になっています。

Layer 0: Default (Qwerty 配列)

【左手 (Left)】                                                     【右手 (Right)】
+----------+------+------+----------+------+------+                +------+------+----------+------+------+------+
| GUI / ESC|  Q   |  W   |    E     |  R   |  T   |                |  Y   |  U   |    I     |  O   |  P   |  [   |
+----------+------+------+----------+------+------+------+  +------+------+------+----------+------+------+------+
| CTL / TAB|  A   |  S   | CTL / D  |  F   |  G   |  (   |  |  )   |  H   |  J   | CTL / K  |  L   |  ;   |  '   |
+----------+------+------+----------+------+------+------+  +------+------+------+----------+------+------+------+
|  SHIFT   |  Z   |  X   |    C     |  V   |  B   |  {   |  |  }   |  N   |  M   |    ,     |LT 4 / .|  /  |SHIFT |
+----------+------+------+----------+------+------+------+  +------+------+------+----------+------+------+------+
                  |ADJ(3)| ALT / BSP|LWR(1)|SFT / SPC|      |CTL / ENT|RSE(2)|ALT / TAB|ADJ(3)|
                  +------+----------+------+---------+      +---------+------+---------+------+
  • Mod-Tap & Layer-Tap キー (単押し / 長押し):
    • LT 4 / .: タップで .（ピリオド）、ホールドで マウスレイヤー (Layer 4) が発動
    • GUI / ESC: タップで Escape、ホールドで GUI (Win / Cmd)
    • CTL / TAB: タップで Tab、ホールドで Left Control
    • CTL / D: タップで D、ホールドで Left Control
    • CTL / K: タップで K、ホールドで Right Control
    • ALT / BSP: タップで Backspace、ホールドで Left Alt
    • SFT / SPC: タップで Space、ホールドで Left Shift
    • CTL / ENT: タップで Enter、ホールドで Right Control
    • ALT / TAB: タップで Tab、ホールドで Left Alt

Layer 0: Default (Dvorak 配列)

【左手 (Left)】                                                     【右手 (Right)】
+----------+------+------+----------+------+------+                +------+------+----------+------+------+------+
| GUI / ESC|  '   |  ,   |LT 4 / .  |  P   |  Y   |                |  F   |  G   |    C     |  R   |  L   |  /   |
+----------+------+------+----------+------+------+------+  +------+------+------+----------+------+------+------+
| CTL / TAB|  A   |  O   | CTL / E  |  U   |  I   |  (   |  |  )   |  D   |  H   | CTL / T  |  N   |  S   |  -   |
+----------+------+------+----------+------+------+------+  +------+------+------+----------+------+------+------+
|  SHIFT   |  ;   |  Q   |    J     |  K   |  X   |  {   |  |  }   |  B   |  M   |    W     |  V   |  Z   |SHIFT |
+----------+------+------+----------+------+------+------+  +------+------+------+----------+------+------+------+
                  |ADJ(3)| ALT / BSP|LWR(1)|SFT / SPC|      |CTL / ENT|RSE(2)|ALT / TAB|ADJ(3)|
                  +------+----------+------+---------+      +---------+------+---------+------+
  • Mod-Tap & Layer-Tap キー (単押し / 長押し):
    • LT 4 / .: タップで .（ピリオド）、ホールドで マウスレイヤー (Layer 4) が発動
    • GUI / ESC: タップで Escape、ホールドで GUI (Win / Cmd)
    • CTL / TAB: タップで Tab、ホールドで Left Control
    • CTL / E: タップで E、ホールドで Left Control
    • CTL / T: タップで T、ホールドで Right Control
    • ALT / BSP: タップで Backspace、ホールドで Left Alt
    • SFT / SPC: タップで Space、ホールドで Left Shift
    • CTL / ENT: タップで Enter、ホールドで Right Control
    • ALT / TAB: タップで Tab、ホールドで Left Alt

Layer 1: LOWER (ファンクション・カーソル移動・IME切替)

最下段の LWR(1) を押している間アクティブになります。

【左手 (Left)】                                                     【右手 (Right)】
+----------+------+------+----------+------+------+                +------+------+----------+------+------+------+
|          |  F1  |  F2  |    F3    |  F4  |  F5  |                |      | HOME |  PG_DN   |PG_UP | END  |      |
+----------+------+------+----------+------+------+------+  +------+------+------+----------+------+------+------+
|          |  F6  |  F7  | CTL / F8 |  F9  | F10  |ADJ(3)|  |      |Alt+` | LEFT |   DOWN   |  UP  |RIGHT |      |
+----------+------+------+----------+------+------+------+  +------+------+------+----------+------+------+------+
|          | F11  | F12  |  PSCRN   | SLCK | INS  |      |  |      |      |      |          |      |      |      |
+----------+------+------+----------+------+------+------+  +------+------+------+----------+------+------+------+
                  |      | ALT / DEL|      |         |      |         |      |         |      |
                  +------+----------+------+---------+      +---------+------+---------+------+
  • `Alt+``: 日本語入力 IME 切り替えマクロ（Alt 単押しの誤動作を防ぐカスタムマクロ）
  • PSCRN / SLCK / INS: PrintScreen / ScrollLock / Insert

Layer 2: RAISE (数字・記号)

最下段の RSE(2) を押している間アクティブになります。

【左手 (Left)】                                                     【右手 (Right)】
+----------+------+------+----------+------+------+                +------+------+----------+------+------+------+
|          |  1   |  2   |    3     |  4   |  5   |                |  6   |  7   |    8     |  9   |  0   |      |
+----------+------+------+----------+------+------+------+  +------+------+------+----------+------+------+------+
|          |      |      |   ESC    |      | TAB  |      |  |      |  [   |  ]   |    /     |  =   |  -   |      |
+----------+------+------+----------+------+------+------+  +------+------+------+----------+------+------+------+
|          |      |      |          |      |      |      |  |      |  `   |  \   |          |      |      |      |
+----------+------+------+----------+------+------+------+  +------+------+------+----------+------+------+------+
                  |      |          |      |         |      |         |      |         |      |
                  +------+----------+------+---------+      +---------+------+---------+------+

Layer 3: ADJUST (システム設定・Bluetooth切替・ワイヤレスDFU突入)

親指の ADJ(3) を押すことでアクティブになります。左右対称に配置されています。

【左手 (Left)】                                                     【右手 (Right)】
+----------+------+------+----------+------+------+                +------+------+----------+------+------+------+
|   BT 0   | BT 1 | BT 2 |   BT 3   | BT 4 | BT 5 |                | BT 0 | BT 1 |   BT 2   | BT 3 | BT 4 | BT 5 |
+----------+------+------+----------+------+------+------+  +------+------+------+----------+------+------+------+
|  STUDIO  |RESET | DFU  | CLR_ALL  | CLR  |      | DFU  |  | DFU  |      | CLR  | CLR_ALL  | DFU  |RESET |STUDIO|
+----------+------+------+----------+------+------+------+  +------+------+------+----------+------+------+------+
|          |      |      |          |      |      |      |  |      |      |      |          |      |      |      |
+----------+------+------+----------+------+------+------+  +------+------+------+----------+------+------+------+
                  |      |          |      |         |      |         |      |         |      |
                  +------+----------+------+---------+      +---------+------+---------+------+
  • DFU (&nordic_dfu): Nordic Secure DFU ブートローダを起動し、OTA アップデート待機状態に入ります
    • 左手側の DFU を押すと 左手（セントラル）だけが DfuTarg に突入
    • 右手側の DFU を押すと 右手（ペリフェラル）だけが DfuTarg に突入
    • 分割キーボードの物理タクトスイッチ（SW3/SW4）を押す必要がなく、完全ワイヤレスでアップデート可能
    • アップデートをやめたくなった場合でも、電源を OFF ➡️ ON にするだけで通常モードに安全復帰
  • BT 0 〜 BT 5: Bluetooth 接続先（プロファイル 0〜5）を切り替え（最大 6 台）
  • CLR (bt BT_CLR): 現在選択中の Bluetooth プロファイルのペアリング情報を削除
  • CLR_ALL (bt BT_CLR_ALL): すべての Bluetooth 接続先ペアリング情報を一括全消去
  • RESET (&sys_reset): キーボードの再起動
  • STUDIO (&studio_unlock): ZMK Studio の編集ロック解除

Layer 4: MOUSE (マウス操作)

デフォルトレイヤーの .（ピリオド）キーを長押ししている間アクティブになります。

【左手 (Left)】                                                     【右手 (Right)】
+----------+------+------+----------+------+------+                +------+------+----------+------+------+------+
|          |      | RCLK |          | LCLK |      |                |      |      | SCRL_DN  |SCRL_UP|     |      |
+----------+------+------+----------+------+------+------+  +------+------+------+----------+------+------+------+
|          |      | RCLK |          | LCLK | MCLK |      |  |      |      | LEFT |   DOWN   |  UP  |RIGHT |      |
+----------+------+------+----------+------+------+------+  +------+------+------+----------+------+------+------+
|          |      |      |          |      |      |      |  |      |      | LCLK |   MCLK   | RCLK |      |      |
+----------+------+------+----------+------+------+------+  +------+------+------+----------+------+------+------+
                  |      |          |      | LCLK | RCLK |  |      |      |      |          |
                  +------+----------+------+---------+      +---------+------+---------+------+
  • カーソル移動: 右手の LEFT / DOWN / UP / RIGHT（H/J/K/L 周辺）でマウスカーソルを操作
  • クリック: LCLK（左クリック）、MCLK（中クリック / ホイールクリック）、RCLK（右クリック）
  • スクロール: SCRL_UP / SCRL_DN（ホイール上下スクロール）

キーマップ定義ファイル: config/caravelle.keymap

補足

  • ST-Linkの種類によっては付属ケーブルがメス-メスになっているようです。その時は自キーを作ってるとよく余るピンヘッダを使うとPCBに接続しやすいです

TODO

  • 純正のソフトデバイス+ブートローダーを使用したOTAによるファームウェア書き込み (対応完了)
  • キー入力による左右両方のワイヤレスDFU突入（物理タクトスイッチ押下不要化） (対応完了)
  • マウスキー機能（CONFIG_ZMK_POINTING）の追加 (対応完了)
  • デフォルトレイヤに Qwerty を追加 (済)
  • ZMK の Keymap Editor に対応 (済)
  • バッテリーの残量表示に対応する (現状は常に 100% になってるみたいです) (対応完了)
  • 安定性の確認 (確認完了)
  • Readmeの導入手順の加筆 (対応完了)
  • OpenOCDではなくもっと簡単な nRF Connect for Desktop での導入 (ST-Linkは必要ですが) (対応完了)
  • 不要な設定の削除や、動作改善に関するチューニング

ソフトデバイスとブートローダの復旧

  • openocd -f interface/stlink.cfg -f target/nordic/nrf52.cfg -c init -c "reset init" -c halt -c "nrf5 mass_erase" -c "program ./zmk-workspace/bootloader/s132_nrf52_3.0.0_softdevice.hex verify" -c reset -c exit
  • openocd -f interface/stlink.cfg -f target/nordic/nrf52.cfg -c "init; halt; program ./zmk-workspace/caravelle_bootloader/caravelle_ble-bootloader.hex verify reset; exit"
  • ソフトデバイスとブートローダーは本家のCaravelle BLEのビルドガイドに入手先が記載されています

About

Caravelle BLE用のZMKファームウェア

Resources

Readme
GPL-3.0 license
Activity

Stars

1 star

Watchers

0 watching

Forks

1 fork
Report repository

Releases

Packages

Contributors

Languages