Back to Playground

ファームウェア取り扱いガイド

このガイドについて

このページでは、キーボードにファームウェアを書き込むときの基本的な考え方を説明します。

対象は、UF2 ファイルを書き込むタイプのキーボードです。ZMK系の無線キーボードでよく使う手順です。

「どのファイルを書けばいいのか分からない」「左右で別のファイルがある」「モジュールを変えたらどれを選ぶのか分からない」という人向けに、なるべく順番に確認できるようにしています。

まず覚えること

ファームウェアは、キーボードを動かすための中身です。

キーボード本体に入れることで、キー入力、トラックボール、ロータリーエンコーダ、OLED、BLE接続などの動きが決まります。

書き込みに使うファイルは、多くの場合 .uf2 という拡張子です。

例:

Polaris_L_MODULE_ENC.uf2
Polaris_R_MODULE_TB.uf2
settings_reset-seeeduino_xiao_ble.uf2

UF2 は、特別な書き込みソフトを使わずに、USBメモリへファイルをコピーするような感覚で書き込める形式です。

UF2を書き込む流れ

基本の流れは次の通りです。

  1. キーボードをUSBケーブルでPCに接続する
  2. キーボードをブートローダーモードにする
  3. PCに表示されたドライブを開く
  4. 対応する .uf2 ファイルをコピーする
  5. コピーが終わると自動で再起動する

ブートローダーモードに入ると、PC上に新しいドライブが表示されます。

ドライブ名は使用しているマイコンによって異なります。たとえば XIAO-SENSE, Seeed XIAO のような名前で表示されることがあります。

このガイドで想定しているマイコンでは、リセットボタンを2回押すことでファームウェア書き込みモードに入ります。

ブートローダーモードに入る方法

キーボードによって方法は少し違いますが、よく使う方法は次のどれかです。

リセットボタンを2回押す

多くのマイコンでは、リセットボタンを素早く2回押すとブートローダーモードに入ります。

押す間隔が遅すぎると通常の再起動になることがあります。うまくいかない場合は、少し速めに2回押してください。

ファームウェア書き込みモードに入ると、PCにドライブが表示されます。そのドライブを開いて、書き込みたい .uf2 ファイルをドラッグアンドドロップでコピーします。

キー操作でリセットする

すでにファームウェアが入っている場合、キーマップに Reset や Bootloader が設定されていれば、キー操作でブートローダーモードに入れることがあります。

ただし初回書き込みや、ファームウェアが壊れている場合は、この方法は使えません。

UF2を書き込む

ブートローダーモードに入ると、PCにドライブが表示されます。

そのドライブへ .uf2 ファイルをコピーします。

コピー中にドライブが消えることがありますが、これは正常です。コピーが完了するとマイコンが自動で再起動します。

OSから見ると、ドライブが勝手に切断されたように見えるため、エラーダイアログや警告が出ることがあります。

これは書き込み完了後にマイコンが自動で切断・再起動しているためです。UF2をコピーした直後にドライブが消えた場合は、基本的には正常な動作です。

書き込み後にドライブが消えて、キーボードとして動き始めれば成功です。

書き込みに成功すると、マイコンのランプが青や赤に光るはずです。ランプが光るかどうかも、書き込み後の確認ポイントになります。

ファームウェアファイルの選び方

ここが一番間違いやすいところです。

ファームウェアは「キーボード本体の種類」「左右」「取り付けているモジュール」に合わせて選びます。

ファイル名だけで判断しにくい場合は、次の順番で確認してください。

1. キーボード名を見る

まず、自分のキーボード名が入っているファイルを選びます。

たとえば SparAkasha 用のキーボードに、Geacon 用のファイルを書き込まないでください。

違うキーボード用のファームウェアを書き込むと、キーの位置、配線、センサー設定が合わず、正しく動かないことがあります。

2. 左右を確認する

分割キーボードでは、左手側と右手側で別々のファイルを使うことがあります。

よくある名前:

Polaris_L_MODULE_ENC.uf2
Polaris_R_MODULE_TB.uf2

Polaris_L〜 は左手側、Polaris_R〜 は右手側です。

ZMKでは、片方が親機、もう片方が子機として動く構成があります。ファイル名に central や peripheral が入っている場合は、ビルド元の説明に従ってください。

迷った場合は、配布ページやREADMEで「左に書くファイル」「右に書くファイル」を確認してください。

3. モジュールの種類を確認する

モジュール式キーボードでは、取り付けているモジュールによって使うファームウェアが変わることがあります。

モジュールが違うファームウェアを書き込むと、キー入力はできても、ポインターやエンコーダが動かないことがあります。

たとえば Polaris_R_MODULE_TB.uf2 は、Polarisの右手側で、トラックボールモジュールを使うためのファームウェアです。

このファイル名は次のように読みます。

右手側にトラックボールモジュールを取り付けている場合は、このような R と TB が入ったファイルを選びます。

左右とモジュールの略称は、次のように読むと判断しやすいです。

表記意味選ぶ場面
L左手用左手側の基板に書き込む
R右手用右手側の基板に書き込む
ENCエンコーダーモジュール用ロータリーエンコーダーモジュールを使う
TBトラボ用トラックボールモジュールを使う
JOYアナログスティック&エンコーダーモジュール用アナログスティックとエンコーダーのモジュールを使う
TPDトラパ用トラックパッドモジュールを使う

たとえば、右手側にトラックボールを付ける場合は R と TB が入ったファイルを選びます。

左手側にエンコーダーモジュールを付ける場合は L と ENC が入ったファイルを選びます。

左手側にアナログスティック&エンコーダーモジュールを付ける場合は L と JOY が入ったファイルを選びます。

右手側にトラックパッドモジュールを付ける場合は R と TPD が入ったファイルを選びます。

4. 書き込み前のチェックリスト

書き込む前に、次の項目を確認してください。

ひとつでも不安がある場合は、無理に書き込まず、ファイル名や配布元の説明を確認してください。

よくある失敗

ドライブが表示されない

USBケーブルが充電専用の可能性があります。

データ通信に対応したUSBケーブルを使ってください。

また、USBハブ経由だとうまく認識しないことがあります。PC本体のUSBポートに直接接続して試してください。

UF2をコピーしても動かない

ファイルの種類が違っている可能性があります。

キーボード名、左右、モジュール、マイコンの種類をもう一度確認してください。

まず、ランプが青や赤に光っているか確認してください。

ランプが光っていれば、少なくとも書き込み自体は進んでいる可能性があります。

左右の片方だけ動かない

分割キーボードでは、左右それぞれに正しいファームウェアが必要です。

左用を右に、右用を左に書き込んでいないか確認してください。

無線キーボードの場合は、左右のペアリング情報が残っていて動かないこともあります。配布元にリセット用UF2やペアリング削除手順がある場合は、それに従ってください。

無線接続がうまくいかない

無線接続がうまくいかない場合は、PC側とキーボード側の接続情報がずれている可能性があります。

この場合は、PC側の接続情報と、キーボード側に残っている設定を一度消してから、ファームウェアを書き直して再ペアリングします。

基本の流れは次の通りです。

  1. PC側のBluetooth設定から、対象キーボードの接続情報を削除する
  2. 左手側に settings_reset のUF2を書き込む
  3. 右手側に settings_reset のUF2を書き込む
  4. 左手側に左手用ファームウェアを書き込む
  5. 右手側に右手用ファームウェアを書き込む
  6. PCとキーボードをもう一度ペアリングする

settings_reset は、キーボード側に残っている接続情報や設定を消すためのファームウェアです。

左右の両方に settings_reset を書き込むのが重要です。片側だけリセットすると、もう片方に古い接続情報が残って、うまくつながらないことがあります。

settings_reset を書き込んだあとは、そのままではキーボードとして使えません。必ず通常のファームウェアを書き直してください。

右手側には、Polaris_R_MODULE_TB.uf2 のように R が付いた右手用ファイルを書き込みます。

左手側には、使用している構成に合った左手用ファイルを書き込みます。ファイル名に L が入っている場合は左手用です。

最後にPC側でBluetoothペアリングをやり直します。PC側に古い接続情報が残っていると再接続に失敗しやすいため、最初に削除してからやり直してください。

モジュールだけ動かない

キー入力はできるのに、トラックボールやエンコーダだけ動かない場合は、モジュール非対応のファームウェアを書いている可能性があります。

取り付けたモジュール名が入っているファイルを探してください。

「動かない」と言うときは、どこが動かないのかを分けて確認すると原因を見つけやすいです。

キー入力もできない場合と、モジュールだけ動かない場合では、疑う場所が変わります。

キー入力もできない場合は、左右やキーボード名、マイコンの種類が違っている可能性があります。

キー入力はできるがモジュールだけ動かない場合は、モジュール対応ファームウェアではない、またはモジュールの接続が正しくない可能性があります。

書き込みをやり直すとき

ファームウェアは、何度でも書き込み直せます。

間違えたファイルを書いてしまっても、もう一度ブートローダーモードに入れて、正しい .uf2 をコピーすれば大丈夫です。

ただし、書き込み中にUSBケーブルを抜かないでください。

コピー中に中断すると、再度ブートローダーモードに入れる必要があります。

初心者向けの安全な進め方

初めて書き込む場合は、次の順番で進めるのがおすすめです。

  1. まず標準構成のファームウェアを書き込む
  2. キーボードとして入力できるか確認する
  3. 左右がある場合は両方確認する
  4. モジュール対応ファームウェアを書き込む
  5. トラックボール、エンコーダ、OLEDなどを確認する

いきなり複雑な構成のファームウェアを書き込むより、まず標準構成で動作確認した方が原因を切り分けやすくなります。

困ったときに確認する情報

質問や問い合わせをするときは、次の情報があると状況を伝えやすくなります。

「動きません」だけだと原因を絞りにくいです。ファイル名と構成を一緒に確認すると、かなり解決しやすくなります。

まとめ

UF2の書き込み自体は、ドライブにファイルをコピーするだけです。

難しいのは、正しいファイルを選ぶことです。

ファイルを選ぶときは、次の順番で確認してください。

  1. キーボード名
  2. 左右
  3. マイコン
  4. モジュール

この順番で確認すれば、間違ったファームウェアを書き込む可能性をかなり減らせます。