はじめに
RustyKeys のビルドガイドにようこそ！
この RustyKeys のビルドガイド（以下、本ガイド）では RustyKeys の組み立て手順やファームウェアの開発方法などについて説明します。
RustyKeys とは
RustyKeys は、組込み Rust 入門に最適な1台を目指して開発された自作キーボードのキットです。
次のような特徴があります:
- フットプリントが名刺サイズ(91mm x 55mm)
- 公式のビルドガイド（本ガイド）が組込み Rust をサポートしている
- キーボードを「使いたい人」向けではなく「作りたい人」向け
- 組み立てが簡単で、はんだ付け入門としてもおすすめ
※本商品は QMK Firmware 等の既存のファームウェアには対応していません。キーボードとして動作させるためにはビルドガイドに従ってファームウェアを組込み Rust で開発しなければなりません。
作者: KOBA789
- Twitter: @KOBA789
- YouTube: KOBA789 / Channel 78.9
- Website: koba789.com
RustyKeys の紹介とプロトタイプ開発の様子
RustyKeys を手に入れる
RustyKeys を組み立てるには RustyKeys キット以外にもいくらか必要なものがあります。
RustyKeys キットを注文する前によく確認し、キットは手元に届いたのに必要な工具や部品が足らなくて組み立てを始められない、ということがないようにしましょう。
RustyKeys キット内容
- RustyKeys 基板（オリジナル） x1
- Raspberry Pi Pico x2
- 1N4148(ダイオード) x6
- L字ピンヘッダ(3P) x1
- ジャンパ線(ソケット-ソケット 3P) x1
- ピンヘッダ(40P) x1
- ゴム足 x4
※2つの Raspberry Pi Pico のうち1つはキーボード用、もう1つはデバッグアダプタ用です。
※ジャンパ線の色は異なる場合があります
別途用意が必要な部品
以下のものは RustyKeys キットに含まれません。お好きなものを別途ご用意ください。
- Cherry MX（互換）スイッチ x6
- キーキャップ（上記スイッチに対応するもの） x6
- microUSB ケーブル x2
※2本のmicroUSB ケーブルのうち1本はパソコンとキーボードとの接続用、もう1本はパソコンとデバッグアダプタとの接続用です。ファームウェア開発時は2本とも同時に使います。
組み立てに必要な工具
RustyKeys キットの組み立てにははんだ付けが必要です。 はんだづけのための工具をご用意ください。
本キットの部品はすべて足のピッチが2.54mm以上であり、高度なはんだづけ技術・工具は不要です。 有鉛ハンダであればフラックスなしで簡単に組み立てられます。
注意事項
購入前に必ずお読みください。
- 本商品は、組み立て・プログラミング自体を楽しむことを目的としたキットです
- キーボードとして動作させるためには組込み Rust によるファームウェアの開発が必要です
- ファームウェアの開発についてはビルドガイド（近日公開）で解説していますので購入前にご確認ください
- 組み立て・プログラミングの失敗による部品・パソコン本体の破損はお客様ご自身の責任となります
購入はこちらから
必要なツールをインストールする
サポートする開発環境
本ビルドガイドでは次の3つの環境をサポートします。
- macOS
- Windows
- Ubuntu(Linux)
Windows Subsystem for Linux はサポート対象外
本ビルドガイドでは Windows Subsystem for Linux(WSL) をサポートしません。
WSL の最新版である WSL2 は仮想マシン内の環境であり、ハードウェアを扱わねばならないファームウェア開発には不向きだからです。
Windows でファームウェアを開発する場合は WSL 内ではなく、Windows 上に開発環境を構築してください。
Rust をインストールする
Rust 公式のインストール手順(日本語版)に従ってインストールしてください。
もし既にインストール済みの場合は、以下のコマンドで最新版にアップデートしておきましょう。
$ rustup update
thumbv6m-none-eabi ターゲットをインストールする
開発環境のコンピュータと、ファームウェアの実行環境の Raspberry Pi Pico には実行できるバイナリに違いがあります。 たとえば、開発環境のコンピュータには OS がありますが、Raspberry Pi Pico にはありません。また、CPU アーキテクチャも異なるでしょう。
Rust のツールチェーンをデフォルトの設定でインストールしただけの状態では、開発環境と同じ環境向けのバイナリしかビルドできません。
Raspberry Pi Pico 向けのバイナリをビルドできるようにするには次のコマンドを実行します。
$ rustup target add thumbv6m-none-eabi
probe-run をインストールする
ビルドしたバイナリを Raspberry Pi Pico 上で実行するためには、後述のデバッグアダプタを通じて Raspberry Pi Pico にバイナリを転送しなければなりません。
probe-run はこのバイナリの転送と実行をするためのツールです。Raspberry Pi Pico のデバッグ出力を開発環境のコンピュータに表示する機能もあります。
probe-run 公式のインストール手順に従ってインストールしてください。
flip-link をインストールする
Raspberry Pi Pico のようなマイコンにはメモリ管理ユニット(MMU)がないため、無限再帰などでスタックオーバーフローを起こしてもそれになかなか気づけません。
flip-link はメモリ上のスタックの位置を工夫することでスタックオーバーフローに気づきやすくできるリンカーです。
flip-link 公式のインストール手順に従ってインストールしてください。
elf2uf2-rs をインストールする
elf2uf2-rs は ELF 形式のバイナリを UF2 形式に変換したり、UF2 形式のバイナリを Raspberry Pi Pico に書き込んだりできるツールです。
自作キーボードのファームウェア開発では使いませんが、後述のデバッグアダプタを作成する際に使います。
以下のコマンドを実行してインストールしてください。
$ cargo install elf2uf2-rs
RustyKeys キットを組み立てる
この章では、RustyKeys キットを組み立てる手順を説明します。
手順通りに組み立てると、RustyKeys キーボード本体とデバッグアダプタが組み上がります。
組み立てに必要なパーツを確認する
組み立てを始めるまえに、必要なパーツが揃っているか確認しましょう。
RustyKeys キット内容
※ジャンパ線の色は異なる場合があります
別途用意が必要な部品
組み立てに必要なパーツは揃っていましたか？ それでは組み立てを始めましょう！
下ごしらえをする
キーボード本体やデバッグアダプタを組み立てる前に、材料の下ごしらえをしましょう。
40ピンのピンヘッダを半分に折る
キットに含まれる40ピンのピンヘッダを半分に折ります。折ったあとの20ピンのピンヘッダ2つはあとの組み立て工程で使います。
下ごしらえは以上です。次はお待ちかねのキーボード本体の組み立てです！
キーボード本体を組み立てる
ではいよいよキーボード本体を組み立てていきます！
手順通りに進めれば難しいことはありません。落ち着いて進めましょう。
1N4148(ダイオード)をはんだ付けする
はんだ付けの順番は、背の低いパーツから始めるのが原則です。さもなくば背の高いパーツがはんだ付けされたあとの不安定な基板に背の低いパーツをはんだ付けしようとして苦労することになります。
RustyKeys で最も背が低いパーツは 1N4148(ダイオード)なので、まずはこのはんだ付けから始めましょう。
ダイオードには極性があり、向きを間違えて取り付けると回路が正しく機能しなくなります。正しい向きの目印は基板の表面に白いインク(シルク)で印刷されていますから、それを確認して間違いのないように取り付けてください。
シルクで描かれた白い帯と 1N4148 に印刷された黒い帯が合う向きで取り付けてください。
1N4148 は6つあります。すべてはんだ付けしてください。
L字ピンヘッダ(3ピン)をはんだ付けする
次にL字ピンヘッダ(3ピン)をはんだ付けします。このピンヘッダはデバッグアダプタと接続するために使います。
中央のピンは GND に接続されており熱容量が大きいため、はんだが乗りづらいことがあります。焦らずによく温めてはんだ付けしてください。
ピンヘッダ(20ピン)を使って Raspberry Pi Pico の位置を合わせる
RustyKeys では、Raspberry Pi Pico を端面スルーホールのみではんだ付けします。
しかし端面スルーホールだけでは位置合わせが難しいため、位置合わせのためだけにピンヘッダを一時的に差し込みます。
基板を重ねてピンヘッダ(20ピン)を差し込む
まず、以下の写真のように RustyKeys 本体の基板と Raspberry Pi Pico を重ね、基板裏面からピンヘッダ(20ピン)を1番ピンから20番ピンの列に差し込んでください。
このとき、Raspberry Pi Pico の上下の向きを間違えないようにしてください。
40番ピンをはんだ付けして仮止め
次に、Raspberry Pi Pico の40番ピンだけをはんだ付けします。40番ピン以外はまだはんだ付けしないでください。1ヶ所のみをはんだ付けするのは、方向や位置を修正しやすくするためです。
本体の基板と Raspberry Pi Pico の基板の間に隙間が開いていたり、向きが曲がっていたりしていないことを確認してください。
ピンヘッダを抜いて20番ピンをはんだ付けして仮止め
差し込まれているピンヘッダを引き抜きます。このとき、本体の基板と Raspberry Pi Pico は1ヶ所のはんだ付けのみで支えられています。無理な力をかけないように気をつけてください。
ピンヘッダを引き抜いたら、先ほどとは対角にある20番ピンをはんだ付けします。ここでも、基板の間に隙間が開いていたり、向きが曲がっていたりしていないことを確認してください。
Raspberry Pi Pico の残りのピンをすべてはんだ付けする
対角2ヶ所(40番ピン・20番ピン)の仮止めができたら、残りすべてのピンをはんだ付けしましょう。
すべてのピンをはんだ付けすると、次の写真のようになります。下側にある3つのピンも忘れずにはんだ付けしましょう。
キースイッチをはんだ付けする
最後のはんだ付けはキースイッチです。キースイッチは RustyKeys キットに含まれていませんから、お好きな Cherry MX(互換) スイッチを6個用意してください。
なお、キースイッチによっては差し込みに多少の力が必要かもしれません。向きが合ってることを確認し、自分を信じてまっすぐに力を込めて差し込んでください。その際、基板の角などでケガをしないように十分ご注意ください。
キーキャップを取り付ける
キースイッチをはんだ付けしたら、キースイッチにキーキャップを取り付けましょう。キーキャップも RustyKeys キットに含まれていませんから、お好きなキーキャップを6個用意してください。
ゴム足を貼り付ける
最後に裏面にゴム足を取り付けましょう。基板の四隅に白い円が印刷されているのがゴム足の取り付け位置の目印です。
RustyKeys のできあがり……？
組み立てお疲れ様でした！ RustyKeys の完成です！
……と言いたいところですが、このままではキーボードとしては使えません。そう、ファームウェアが書き込まれていないのです。さらには、ファームウェアを書き込むためのデバッグアダプタの組み立ても残っています。
とはいえ本体の組み立ては完了です。ぜひ記念写真を撮って Twitter にアップロードしてくださいね。
デバッグアダプタを組み立てる
キーボード本体の次はデバッグアダプタを組み立てていきましょう。
「デバッグアダプタ」という仰々しい名前が付いていますが、はんだ付けはキーボード本体よりも簡単です。
ピンヘッダをはんだ付けする
20ピンのピンヘッダを、Raspberry Pi Pico の1番ピンから20番ピン側の列にはんだ付けします。
以上ですべてのはんだ付けが完了しました。はんだ付けのための工具は片付けて構いません。くれぐれもはんだごての電源を切るのを忘れずに！
デバッグアダプタのファームウェアを書き込む
続いて、デバッグアダプタにファームウェアを書き込んでいきましょう。
rust-dap のソースコードを用意する
デバッグアダプタのファームウェアには rust-dap を利用します。
次のコマンドを実行して git リポジトリを clone してください。
$ git clone https://github.com/ciniml/rust-dap.git
clone したローカルリポジトリ内に作業ディレクトリを移動しておきます。
$ cd rust-dap
rust-dap をデバッグアダプタに書き込む
Raspberry Pi Pico 用のファームウェアを書き込むため、作業ディレクトリを boards/xiao_rp2040 に移動します。
$ cd boards/xiao_rp2040
次に、デバッグアダプタ用の Raspberry Pi Pico と開発用のコンピュータを USB ケーブルで接続します。Raspberry Pi Pico が USB ストレージとして認識されるはずです。
※Linux では、手動でファイルシステムをマウントしなければならないかもしれません。
USB ストレージが認識されたら、次のコマンドを実行してファームウェアを書き込みます。書き込み前にビルドが実行されるため少々時間がかかります。
$ cargo run --release
コマンドの実行が完了し、デバッグアダプタ用の Raspberry Pi Pico の緑色の LED が光っていれば成功です。
ファームウェアを書き込む
開発環境のセットアップやハードウェアの組み立てが終わり、デバッグアダプタの準備もできました。いよいよキーボードのファームウェア開発を始めましょう！
本体とデバッグアダプタを接続する
ファームウェアを書き込むには、ジャンパ線で本体とデバッグアダプタを接続し、また両方の Raspberry Pi Pico を USB ケーブルで開発用のコンピュータに接続します。
※図中のジャンパ線の色とキット付属のジャンパ線の色は異なる場合があります。
ジャンパ線で本体とデバッグアダプタを接続する
まず、付属のジャンパ線で本体とデバッグアダプタを接続します。
ピンの対応は以下の通りです。
| 本体側ピン | デバッグアダプタ側ピン |
|---|---|
| SWDIO | GP4(GPIO4) |
| GND | GND |
| SWCLK | GP2(GPIO2) |
デバッグアダプタを開発用のコンピュータに接続する
次に、USB ケーブルでデバッグアダプタを開発用のコンピュータに接続します。USB ケーブルはキットに付属していないため、適当な長さのものを用意してください。
キーボード本体を開発用のコンピュータに接続する
最後に、USB ケーブルでデバッグアダプタを開発用のコンピュータに接続します。
このように、ファームウェア開発時にはデバッグアダプタとキーボード本体の両方を開発用のコンピュータに接続します。USB ケーブルは2本用意してください。
Hello, World!
キーボード本体とデバッグアダプタの接続はできましたか？
なにはともあれ、まずは Hello, World! の実行からはじめましょう。
rusty-keys のリポジトリを clone する
Hello, World! のためのコードは rusty-keys のリポジトリにあります。
$ git clone https://github.com/KOBA789/rusty-keys.git
clone したローカルリポジトリ内に作業ディレクトリを移動しておきます。
$ cd rusty-keys
Hello, World! を実行する
実行は驚くほど簡単です。
まずは Hello, World! のあるディレクトリまで移動します。
$ cd firmware/hello
あとは cargo run するだけです！
$ cargo run
ビルドが始まるのでちょっと待ちましょう。最終的に以下のような表示が得られたら成功です！
これであなたも組込み Rust に入門しました！ おめでとうございます！！🎉
Finished dev [unoptimized + debuginfo] target(s) in 14.81s
Running `probe-run --chip RP2040 target/thumbv6m-none-eabi/debug/rusty-keys-hello`
(HOST) INFO flashing program (6 pages / 24.00 KiB)
(HOST) INFO success!
────────────────────────────────────────────────────────────────────────────────
Hello, world!
└─ rusty_keys_hello::__cortex_m_rt_main @ src/main.rs:25
────────────────────────────────────────────────────────────────────────────────
(HOST) INFO device halted without error
初めてのキーボード
Hello, World! を確認したら、さっそく USB キーボードとして動かしてみましょう！
手順に飛躍があるように感じるかもしれませんが、この文書は自作キーボードキットのビルドガイドであって、組込みプログラミング入門でも USB デバイス開発入門でもないのです。
とりあえずキーボードが動くところをご覧に入れましょう。あとの話はそれからです！
rusty-keys のリポジトリを開く
リポジトリは Hello, World! したときに clone してあるはずです。 ここでは、ローカルリポジトリのルートディレクトリが作業ディレクトリになっていると仮定します。
$ pwd
/path/to/rusty-keys
キーボードのファームウェアを実行する
実行の手順は Hello, World! と何ら変わりありません。
コードの複雑さの違いはともかくとして、実行するだけなら同じくらい簡単です。
$ cd firmware/keyboard
$ cargo run --release --bin simple
cargo run になにやらオプションが付いています。一応解説しておきましょう。
--release: リリースビルドをする。ざっくり言うと、付けないときよりも強めの最適化がかかる。--bin simple: 複数ある実行可能バイナリのうち、simpleを実行する。
不正確な説明では満足できない勤勉な方のために cargo の公式マニュアルのリンクを紹介しておきます。
キーを押して文字を入力してみる
cargo run の実行に成功していれば、あなたの手元の RustyKeys は既にキーボードになっています！
試しにいくつかのキーを押してみてどんな文字が入力されるか確認しましょう。
| キー | レイヤー1 | レイヤー2 |
|---|---|---|
| SW1 | K キー | 7 キー |
| SW2 | O キー | 8 キー |
| SW3 | シフトキー | 9 キー |
| SW4 | B キー | バックスペースキー |
| SW5 | A キー | エンターキー |
| SW6 | レイヤー切り替えキー |
作者の名前 KOBA789 を入力できるだけのキーマップになっていることに気づきましたか？
オリジナルのファームウェアを作る
作者の名前しか入力できないキーボードほど要らないキーボードもないでしょう。
サンプルコードを実行できたら、次は自分だけのキーボードを作るための改造を始めましょう！
キーマップを改造する
🚧 工事中
LED を光らせる
🚧 工事中
マクロ入力を作る
🚧 工事中
MIDI キーボードを作る
🚧 工事中