BLE micro proの動作確認をする
この記事は古いバージョンの記事です。
やった手順書いておかないともう一回同じ失敗をするのでメモ書き。
目標はnamecard2x4 rev2 for LPのBLE micro pro対応。
前提
Windows10で行います。
WSL上のubuntuでうまくいかなかったのでmsys2 64bitでやります。
参考URL
リポジトリの取得
qmk/qmk_firmwareにはマージされていないのでsekigon-gonnoc/qmk_firmwareを引っ張ってくる必要があります。
git remote add sekigon https://github.com/sekigon-gonnoc/qmk_firmware.git git checkout -b nrf52 sekigon/nrf52
個人的にはリポジトリの切り替えに時間がかかるので、別名クローンしたほうがよいような気がします。 本家と競合してるっぽいし。 URLだけだとプロジェクト名でフォルダを作成しますが、第二引数にパスを追加することで別のフォルダ名でクローンできます。
git clone --depth 1 -b nrf52 https://github.com/sekigon-gonnoc/qmk_firmware.git ble_micro_pro
開発環境の用意
arm開発環境
とりあえず以下のコマンドを実行してarm環境をいれます。
make git-submodule
次にnRF5_SDK v15.0.0をいれます。v15.2.0じゃだめっぽいです。
~/nRF_SDK_v15.0.0な感じにするとたぶん楽です。
パスを通す
以下を実行します。 ~/.bashrcあたりに書いておくと楽かも？
export NRFSDK15_ROOT=~/nRF_SDK_v15.0.0
nrf52への書き込みツール
以下からnrfutil.exeをダウンロードして~/qmk_utilsにいれます。qmk_firmware/utilではないです。
書き込みテスト
とりあえず以下を実行してビルド成功～書き込みまでできるか試しましょう。 BLEmicroproはこの時点では抜いておいてください。
make ble_micro_test:default:nrfutil
以下が表示されたらResetを押しながらケーブルを接続してください。
Detecting USB port, put your controller into dfu-mode now.
デバイスが検出されたら以下のメッセージが表示されて完了です。
Detected controller on USB port at /dev/ttyS32 Remapped MSYS2 USB port to COM33 Programming Started Device programmed.
BLE対応デバイスと接続する
〆
今回はここまで。次はキーボード定義。
QMK configuratorを使ってキーマップを作成する
namecard2x4のキーマップ作成支援のための記事です。
Windows10環境で動作確認をしています。
バージョン情報などは2019/02/13時点での情報です。
- 書き込み用ソフトウェアをダウンロードする（QMK toolbox）
- QMK toolboxの動作確認をする
- WEBファームウェアビルダーを開く（QMK configurator）
- キーボードを選ぶ
- キーマップを作成する
- 設定ファイルをダウンロードする
- ファームウェアをコンパイルする
- ファームウェアをダウンロードする
- ファームウェアを書き込む
- 動作確認をする
- 〆
書き込み用ソフトウェアをダウンロードする（QMK toolbox）
以下のリンクからダウンロードしてください。記事執筆時の最新版は0.0.9です。
Windowsの場合はexe, MacOSの場合はapp.zipです。
QMK toolboxの動作確認をする
ファームウェア作成で手間取ったあとに書き込みがうまくいかなくて泣くのは辛いので、先に泣きましょう。
現在、qmk.fmから全てのQMK対応キーボードのdefault keymapがダウンロードできます。
以下のリンクからダウンロードしてください。
- 黒基板の人はnamecard2x4/rev1
- 白、緑の基板の人はnamecard2x4/rev2
QMK toolboxを起動します。
local fileに先ほどダウンロードしたhexファイルを選択してください。
次にその右のMicrocontrollerの下のFlashボタンの下のautoflashにチェックを入れてください。
最後に、promicro/デカマイクロをUSB接続し、promicro/デカマイクロをリセットしてください。
すでに組み立て済みの場合は、リセットボタンを押して離せば大丈夫です。
組み立てをしていない場合は、ピンセットなど金属でGNDとRSTを触って繋いで離してください。
promicroのLEDが何も光っていない場合はケーブルがPCにつながっていないか、断線しています。
リセットがかかると、黒い部分に何かしら表示されると思います。具体的には黄色い文字で「今から書き込みするから抜くんじゃねぇぞ」と表示された後、avrdudeなんとかかんとかというコマンドが発行され、しばらくまつと書き込みが実行されます。
以下のように表示されたら書き込み完了です。
avrdude.exe done. Thank you.
正常に終わった場合、書き込みが正常にできることが確認できました。次へ進めます。
書き込みがうまくいかなかった場合
段階を踏んで確認してください。
段階的に確認していってなお動かなかった場合は、OSとどこまで確認していて、どこから動かないかをDiscordのSMKJサーバーに投稿してください。24時間以内に誰かしらから助言を得ることができるはずです。
promicroをUSBケーブルで接続したとき、promicroのLED（黄色と赤）は点灯しているか
何にも差し込んでいないpromicroのLEDが光らない場合電源供給がされていません。ケーブルを交換して確認してください。
PCはpromicroをどのように認識しているか
promicroはArduino LeonardoもしくはArduino Microとして認識されます。
ドライバーがはいっていないと不明なデバイスなどと出てくることがあります。
ドライバーは以下のURLの実行ファイルを使ってインストールするとよいでしょう。ArduinoIDEをインストールしている人はArduinoIDEのフォルダ内にもドライバーがあります。
promicroのLEDが光っているにも関わらず、不明なデバイスすら表示されない場合はケーブルが充電専用の可能性があります。ケーブルを交換して動作確認をしてください。それでもダメであれば不良promicroの可能性があるので新しいpromicroを手に入れてみてください。
リセットをかけたとき、promicroの赤LEDは消灯するか
単純にリセットを掛けたつもりが実はかかってなかった、というのを防ぐための確認項目です。
消えるはずです（たぶん）。
リセットをかけたとき、PCはどのように認識しているか
リセットがかかったあと数秒間書き込み用ポートで接続がされます。そのため、リセットを押した直後にデバイスの切断と新しいデバイスの検出が行われるはずです。数秒後、再度切断と、元のデバイスが検出されるようになります。QMK toolboxが起動していてautoflashにチェックをいれた状態であればnamecard2x4のファームウェアが書き込まれるはずなので、デバイス名がnamecard2x4に代わっているかもしれません。
原則リセットは1回かければ問題ないはずですが、何故か2回かけないといけない個体があるといううわさがあります。
QMK toolboxのログにはどのような表示がされているか
QMK toolboxは何か動作をするたびにどういう状態なのかが常に書きだされています。問題がある場合は「こういう状態なのでだめだった」と表示されます。最も多いのはFlashをしようとしたときに「書き込み可能なデバイスが検出されない（なので書き込みできない）」でしょうか。
英語ですが、とても短い英語なのでこの文章くらいはちゃんと読んでください。
WEBファームウェアビルダーを開く（QMK configurator）
QMK configuratorを開いてください。
rev1
rev2
それ以外
キーボードを選ぶ
KEYBOARDを正しく選択してください。黒い基板の人はnamecard2x4/rev1, それ以外の基板の人はnamecard2x4/rev2を選択してください。
どちらを選んでも場合、N/Aと書かれた四角の数が2x4に変更されます。rev1とrev2で中身がちょっと変わったので、間違えると書き込んでも入力できないキーが発生したり、違う場所にキーがアサインされたりします。
キーマップを作成する
四角形をクリックしてアサインしたい1つのキーを押すか、下から四角形にドラッグアンドドロップすることで入力内容を設定できます。multimedia keyはwindowsとmacで異なるので注意してください。
2019/5/12現在、コンビネーションは一発では入力できないので気を付けてください。例えばCtrl+Vを押した場合は最初に押したCtrlが配置されます。Ctrlとの同時押しはQuantum タブ内「LCtl」もしくは「RCtl」を使うことで実現できます。LRの区別があるのは、内部的に区別されているからです。アプリケーションによっては右が指定されることがあります。
多層化したい場合は、Quantum>Layer functionsを使います。特定のキーを押している間だけ状態が切り替わるようにするには、MOまたはLTを使います。
MOをD&Dしたのちに、移動したいレイヤー番号を入力してください。0-15の範囲で、初期レイヤーは0番です。その後の、左側の0から15の数字をクリックすると、他のレイヤーを編集できます。
設定ファイルをダウンロードする
KEYMAP.JSONと書かれている場所の左側のexportボタンを押すと、現在設定したキーマップを外部ファイルに保存できます。このファイルをKEYMAP.JSONと書かれている場所の右側にあるimportボタンを押すと、keymap.jsonを読み込むことができ、読み込むことで過去に設定したキーマップを使いまわせます。
exportをしなかった場合、編集内容はいつ失われるかわかりません。
ファームウェアをコンパイルする
COMPILEボタンを押して芋が焼けるまで待ってください。
ファームウェアをダウンロードする
右下のFIRMWAREと書かれたボタンを押してhexファイルをダウンロードしてください。
ファームウェアを書き込む
QMK toolboxでダウンロードしたhexファイルを書き込んでください。
動作確認をする
キーをたたいて、期待通りの動作か確認してください。
〆
以上です。
これよりも複雑なレイアウトを実現しようとした場合、開発環境を構築してソースコードを書き換えてコンパイルする必要があります。
説明するのも大変なので省略します。
QMK configuratorを手元で動かす
環境
手順
git clone https://github.com/qmk/qmk_configurator
cd qmk_configurator
bash
sudo apt-get update sudo apt-get upgrade
sudo apt-get install ruby sudo apt-get install ruby-dev
bundle install
bundle exec jekyll serve
最後に、ブラウザーで http://127.0.0.1:4000 を開く。
参考文献
コンスルーまとめ
本記事はキーボードに関する記事です。
コンスルーは便利なのですが、取り扱いに関して正しく理解している人間が少なく、都市伝説的に語り継がれています。
毎度説明するのが非常にめんどくさいのでまとめます。
取り扱いの話は2019/6/7に追記しました。もともとはデータシートを毎度探すのがめんどいので最低限の数字と資料への参照をまとめた記事でした。
コンスルーとキーボード
スプリングピンヘッダことコンスルーという部品があります。
Helixで遊舎工房のないん氏が使い始めた部品で、microUSBが弱いpromicroの交換を容易にするために用いられています。オプション部品です*1。
そのため、12ピンのもののみが小ロットで入手可能でした。BLE micro proに対応するため、13ピンのコンスルーが遊舎工房で取り扱いが始まりました。店頭だけでなく通販でも選択可能です。どちらもプラ高2.5mmのようです。
コンスルーの調達先と種類
さて、このコンスルーですが、各小売りページにおいて2019/01/31現在 型番が明記されていません。また、カタログページへのリンクが切れています。
そのため人づてにしか情報を得られないような情報が続いていて基板設計のときにとてもめんどくさいのでまとめます。
追記
Switch Scienceは2mm高で確定とのこと。遊舎工房は2.5mmと予想されています。0.5mmはpromicroを裏向きで取り付ける際の、実装部品の高さの兼ね合いです。
裏返しでpromicroを取り付ける場合は遊舎工房のほうを、表向きでつける場合やもげにくいマイクロを使う場合はSwitch Scienceのものがよさそうです。
コンスルーと基板設計
コンスルーはどんな基板でも利用可能なわけではありません。コンスルーは2枚の基板を繋ぐ部品です。それぞれの基板がコンスルーに対応しているかしていないかで4通りの組み合わせがあります。このときの利用条件は以下のようになります。
| 対応 | 非対応 | |
|---|---|---|
| 対応 | 利用可能 | 条件付き |
| 非対応 | 条件付き | 利用不可 |
| 利用条件 | 説明 |
|---|---|
| 利用可能 | 刺すだけで利用可能 |
| 条件付き | 非対応基板にはんだ付けをすることで利用可能 |
| 利用不可 | コンスルーでは接点を作れない・刺さらない |
コンスルーのデータシートによると、0.8mmφ～0.9mmφが対応径で、0.85mmφが推奨穴径です。特に実験はしていませんが、この径より小さい場合は穴に入らず、この径より大きい場合はガバガバで通常のピンヘッダを使うのと変わらなくなる、と予想されます。
promicroのスルーホールは2.54mm間隔です。2.54mm間隔用のピンヘッダの対角は約0.8～0.9mmです。この"棒"を抜き差しするために穴径は余裕が必要なので、通常は1mmφ程度で設計をします。そのため、promicroや多くのpromicro対応のキーボード基板はコンスルー非対応です。両側が非対応の場合ただの高いピンヘッダとなってしまいます。ブレッドボードを使った「仮留め」ができなくなる分いいことは何もないかもしれません。
Helixをはじめとしたビルドガイドにコンスルーの利用に関して書かれているキーボードキットの基板は穴径をコンスルー対応にしているため、promicroにはんだ付けをすることで利用可能です。主に国内の一部キーボードが該当します。国外ではコンスルーの入手が困難なため、今後も対応がされることはないでしょう*2。
また、国内の開発者がキーボード向けに作成したpromicroとピン配置を同様にしたマイコンボードの基板はコンスルーに対応しています。SwitchScience版promicroとBLE micro proです。これらのマイコンボードとコンスルー対応キーボード基板を利用する場合は、どちらにもはんだづけをすることなく利用ができます。また、これらの基板を使うことでコンスルー非対応キーボード基板であってもキーボード基板側にコンスルーをはんだ付けをすることで交換可能な状態を維持したまま利用することができます。
向き
実は向きがあります。上下だけでなく、左右もあるそうです。詳しくないので、データシート見てください。
左右の向きは「窓を同じ方向に向いた状態にする」です。
コンスルーと寿命
コンスルーには寿命があります。正確には、コンスルーを抜き差しされる基板側に寿命があります。コンスルーはピンヘッダのピン部分をばね構造にしてスルーホール内に押し付けることによって接点を作っています。そのため、抜き差し時には摩耗するので挿抜回数に制限があります。
国内キットではpromicroを利用することからpromicroにはんだづけをしてキーボードから抜き差しをしていますが、この場合はキーボード側のスルーホールが摩耗し、最終的にはんだづけをしないと利用できなくなります。promicroが壊れたときに交換するためのコンスルーですが、あまり気軽に抜き差しをし過ぎるとキーボード基板側が原因で接触不良を起こしてしまうという、実は望ましい利用方法ではないのです。
だいじそうなとこ
以下マルツのカタログページから参照されていたデータシートよりコピーした内容です。
とりあえずpromicroのフットプリントは推奨値に従ってランド1.5mmφ、TH0.85mmφにしましょう。
資料
ググったら何故かマルツからカタログを参照することができました。マックエイトのカタログシステム刷新のため、検索エンジンから到達できないためです。
https://www.marutsu.co.jp/contents/shop/marutsu/datasheet/XB.pdf
現在では遊舎工房カタログページから参照されているURLから、公式のものが調達できます。
https://www.mac8sdk.co.jp/uploads/entry_meta/file_value/1117/mac8_2018a_jp-xb2.pdf
分割キーボードを定義する
通常のキーボード定義の話は本稿では省略します。
環境
この記事を書いているとき、QMKバージョンは 0.6.242 でした。
新しい分割キーボードの定義
分割キーボードを新しく定義する際にやるべきことは3つです。
rule.mk
以下を追加して分割キーボードに関するライブラリの読み込みを有効にします。
SPLIT_KEYBOARD=yes
config.h
TRSを用いた単線通信の場合は以下を定義します。使えるピンは D0, D1, D2, D3, E6 の5ピンです。
#define SOFT_SERIAL_PIN DX
TRRSを用いたI2Cを使う場合は以下を定義します。
#define USE_I2C
キーマップの定義
キーマップを定義する前にレイアウトマクロを定義します。この際に、そのまま行を2倍にします。
前半行が左手、後半行が左手になります。
分かりやすさのため、前半はprefixをKでなくL、後半のprefixをRとする人もいます。
キーマップはレイアウトマクロを使って過不足なく定義してください。
ファームウェアのビルドと書き込み
ファームウェアのビルド方法は変わりません。
オプション
マスタデバイスの向きを切り替える
ここでいうマスタデバイス(マスタ)とは、分割キーボードのうちUSBケーブルでPCと接続された側のデバイスのことをいいます。 逆に、マスタデバイスとオーディオ4極ケーブル等で接続されたデバイスをスレーブデバイス（スレーブ）とします。
デフォルトではマスタは左手です。そのため、USBが接続されたデバイスは必ず左手として認識されます。
ハードウェアの変更なしにUSBを右手に接続したい場合は以下を定義します。
#define MASTER_RIGHT
それぞれのデバイスが内部に両方のキーマップを持っていますので、キーコードで一時的に左右の手を切り替えることもできます。
ハードウェアに変更を加えて
ハードウェアに変更を加えることが可能な場合は、空いているGPIOを一つ用意します。
#define SPLIT_HAND_PIN your_choose_pin
そして、左手になるデバイスのこのピンをVCCに接続してください。右手になるデバイスはこのピンをGNDに接続してください。
これで、左右の役割が固定されるのでどちらのUSBに接続しても役割が変わらず利用できます。
左右の手で異なるマトリクスを使う
追加で接続されるデバイスは右手扱いになります。以下の定義をすることで異なるピンアサインを定義できます。
#define MATRIX_ROW_PINS_RIGHT {X,X,X.,..,X}
#define MATRIX_COL_PINS_RIGHT {X,X,X,...,X}
注意事項として、現在は MATRIX_ROW_PINS とMATRIX_ROW_PINS_RIGHT は同じ長さにしなくてはならない、とあります。
ピン数さえ揃えれば動作します。
確かオタクスプリットで使いました。
RGBLED
QMK用語でとても分かりにくいものにLEDがあります。
- BACKLIGHT(普通のLED)
- RGBLED(neopixel系)
- RGBMATRIX（普通のLED+LEDドライバだったけど最近neopixel系も盛り込まれた）
これらはすべて別個です。 ここではRGBLEDもしくはLEDという語句を使ったとき、ws2812やsk6812といったneopixel系の単線通信マイコン内蔵のフルカラーLEDのことを指します。
まずLEDの信号を吐き出すピンを定義します。左右とも同じピンを使います。
define RGB_DI_PIN YOUR_LED_PIN
次に、左右それぞれのLEDの数を指定してください。
define RGBLED_SPLIT {LEFT_NUM, RIGHT_NUM}
以上です。RGBLIGHT_SPLIT という定数もありますが、これはRGBLED_SPLITを定義したときに暗黙に定義されるので設計者が定義する必要はありません。定義するとコードレビュー時に「意味ないから消せ」っていわれます。
参考ページ
@mtei 氏の連続ツイートを主に参考にしました。
qmk_firmware で、自分の作ったキーボード基板向けのファームウェアを作る最初の一歩。
— m.tei / ishii (@mtei) 2018年12月25日
shell script で、雛形を作る。
$ sh util/new_project.sh my_endgame
また、Discordでまとまっているという情報があったので以下のドキュメントを参照しました。
おまけ
QMKの標準スプリットキーボードは、スレーブデバイスのLEDはサポートしてないそうです。
どうやら、TRRSで片方を単線通信用、片方をLED信号用にすることで実現できるようです。品質の良くないケーブルを使うと動かなくなりそうですね。
光らせたい＆OLEDを点灯させたいというのはよくわからないので、Helix回路/コードを流用するのがよいのではないでしょうか。
正確な日付は覚えていませんが、現在は単線通信でもRGBLEDがサポートされています。
分割キーボードで右手用デバイスにUSBを刺す（左右のデバイスの役割を交換する）
QMKでは分割キーボード（スプリットキーボード）をサポートしています。現在のキットで一般的な構成は以下の通りです。
この際、両方ともにpromicroがあるのでどちらでもマスターにできるように見えますが、デフォルトでは左がマスターです。
左手にUSBケーブルを指せば使えますが、右手にUSBケーブルを指したいこともあると思います。その場合どうすればいいかを調査しました。
一時的に交換する
SH_から始まるkeycodeを使うことで一時的に左右の手の切り替えができます。トグルや交換の有効無効、長押し中のみ切り替えなどがあります。「キーを押し続けている場合は手を交換」は片手キーボードを実現するための機能かもしれません。
この交換は電源を切った場合交換しない状態に戻ります。
詳細は以下URLを参照ください。
恒久的に交換する
デフォルトではUSBを差したデバイスが左手扱いされます。これを右手扱いに変更したい場合はkeymapフォルダ内の your_keyboard_name.c に以下の定数宣言を追加します。
#define MASTER_RIGHT
