内部向けWikiに技術記事を書くモチベーションと意義,そして今の悩み
はじめに
これはあくあたん工房アドベントカレンダー2019,2日目の記事です.技術の欠片もないポエムです.
他の記事はこちらからご覧頂けます.
内部向けWikiとは?
例えばサークル・研究室・企業など,何らかの集団において,そのメンバーが様々な情報の共有に使用するドキュメンテーションツールを指しています.どういったツールを使っているかは,その集団の特性等に大きく左右されると思います.例えば
- オンプレ
- SaaS
などなど,色々なツールが開発・利用されています.僕自身はサークル・研究室共にesa.ioのお世話になっています.
まだ学生の身なので企業内部でのWikiの使われ方はよくわかりませんが,今回の記事の中には通ずる部分もあるだろうと思っています.
ありがちな問題
こういったツールの問題として,基本的に「よく書く人と全く書かない人に分かれる」というのがあると考えています.書かない人たちからは
- 書くことが無い(何を書いたら良いか分からない)
- ググれば出てくる
- 書かなくてもみんな知ってる
などの声を聞くことがあります.特に,「既にググれば出てくるであろう知識」を書くモチベーションは欠けてしまいがちになっているように感じます.
ググって出てくるから書かなくて良い?
そもそも,ググれば出てくる==書く必要が無いは本当に真なのでしょうか.
現代のインターネットは非常に便利で,どう考えてもマイナーな内容でもググれば数件はヒットするという世界です.しかし一方で,現代は情報が氾濫しており,情報の取捨選択が難しいという問題が起きています.ゆえに自分に代わって情報の取捨選択をしてくれるキュレーションメディアが流行し,乱立していると言えるでしょう.
また,Google検索にはノイズも多く,
- プログラミングスクールの薄っぺらい記事
- StackOverflowの機械翻訳サイト
- 既に使えなくなっている古代の知識で書かれたブログ
などなど,分かっている人にとってはただただ邪魔な,分かっていない人にとってはより混乱の原因となるノイズが多数紛れています*1.
まとめると,ググって出てくる情報は
- あまりにも数が多く,その価値の判断が難しい上に時間がかかる
- 多数のノイズを効率よく弾くだけの基礎知識が必要
ということです.内部向け技術記事ではこの逆を目指していきたいというのが今回の記事の主旨です.
みんなに書いてもらうために
身内だけで通じる価値観を理解する
一部のスーパープログラマを除いて,大抵の技術者は世の中からほとんど認知されていません.その実力がどれくらいなのか,何に詳しいのか,どういうことに興味があるのか,そういった情報は基本的に明らかではありません. そのため,インターネット上に溢れる大抵のまとめ記事は価値が非常に低く見積もられがちです*2.
一方で,特定の集団内においては互いのことをある程度知っています.そのため,その人の書く記事がたとえ同じようなまとめ記事だったとしても信頼度が大きく変わってきます.もちろんその信頼性は多くの場合身内だけに通じるものなので,外部に公開するかどうかはそれを書いた本人がその価値を見積もって考えれば良いと思います.少なくとも,内部に向けた情報を記述するに当たって,ググれば出てくる情報の焼き増しをすることを恐れる必要は無い,ということは言えると思います.
つまり「ググれば出てくるから書かない」と言われたら,
- インターネット上の赤の他人の記事よりは,身内の記事の方が信頼できる(質問もできる)
- 既存の記事をまとめただけのものであっても,自分で探す手間が省けるから助かる
と言いましょう.
気軽に書ける雰囲気を作る
僕は少し前にサークル内向けに以下の様なLTをしました.
そもそも書くハードルを低くしておかなければ誰も書いてくれません.そのためには使いやすいツールを用意することが不可欠です.僕は前述したようにesa.ioを活用させて頂いており,その利便性に日々感謝しています.おすすめです.
また,どういった内容を書くのかについて,小さいチームなので特にルールを定めていません.弊サークルではメンバーごとに自分のネームスペースを持っているため,ただのメモ書きのようなものも好きに書けるようにしています*3.大きいチームでの運用に当たってはこの辺りの「遊び(余裕)」の調整が必要かとは思います.
既にある記事の更新を躊躇わない
知識はどんどん古くなっていきます.記事として残した情報も,いつかは古くなってしまう物です.「これは自分より詳し い〜〜さんが書いた物だから」とか「自分が書いても間違ってるかも」とか思わずに,どんどん更新されていくべきです.
簡単なtypo,実行するコマンドの変更,一部APIの使用方法の変化,…etc,細かい変化は常に起こり続けています.気が付いたら「バージョンXXからはYYはZZになりました」程度で良いので更新していければ,記事が陳腐化していくことを避けれるのではないでしょうか.これは個人ブログではなかなかできないので,多数の人間が関わって管理しているからこそ得られるメリットであると考えています.
集団で知識を蓄えていくというのはそういうことであり,上で述べた「書くハードル」にも近いですが「更新するハードル」も低くあるべきです.そのためには個人間で変な縄張り意識を持たず,自分の書いた記事への他の人からの変更を歓迎することが大事かも知れません.GitHubでPull Request出してくれた人にThank youと言うのと同じような文化が技術記事にも根付くと嬉しいです*4.
書くメリットを意識する
「そうは言われても書いたからって給料が上がるわけじゃないが?」みたいなことを言われればそれはそうなのですが,そもそも書くメリットを認識できていない人が多いのかなという気がしています.個人的に思っているメリットについていくつか書きます.
- 自分自身の理解の向上に繋がる
- 書くことで集団内での自分のブランディングができる
- 〜〜に詳しい人,みたいな
- 他人に教えるときに「とりあえずこれ読んで」と言える
- 他人に理解してもらう文章を書くのは難しいので,普段からそれを意識して書いておくことは,対外発表の練習にもなる
これは内部Wikiではなく,公開するブログに書く場合も同様なので,そもそも他人に見てもらうものを書く習慣があるかどうかの違いが大きいと思います.不特定多数に対して公開するブログと違って,明確にその集団のレベルアップに貢献できるという意味で,内部Wikiの方がメリットはわかりやすいかも知れません.
これは別にメリットではないんですが,僕は普段色々なブログ等にお世話になっているので,何か貢献できたらいいなという気持ちでブログを書いています.「GitHubでコントリビュートするのは難しいけど」みたいな人は,感謝の気持ちを込めてブログを書きましょう.
あるべき内部Wikiの姿
何か調べたいときに,まず最初に調べる場所が内部Wikiになるのがベストだと個人的には思っています.
そこには既に見知った人間がまとめた情報があるはずで,自分でググりながら真偽を確かめていく過程を省くことが出来るからです.その上で,その内容では足りない・間違っているなど追加/修正の必要が生じれば記事を更新する,そもそも記事が無く今後も必要となると判断したなら記事を書く,そういうサイクルをうまく回していけると,ナレッジベースとしての内部Wikiがうまく機能するのではないでしょうか.
今の悩み
どのレベルから知識を共有するか
当然個人間のスキルセットには差があるため,全員がどこまで理解していて,どこから分かっていないかを決めることは難しいです.例えばDockerの使い方について記事を書くとして,僕は「仮想化」というもので何を実現したいのか,どういうことが起きるのかをなんとなく理解していますが,今までそういったやり方に触れてこなかった人にはまずそこの説明から必要になってきます.しかしそれを書くためにじゃあLinuxカーネルってなんだ,そもそもLinuxってなんだ,OSとは?コンピュータとは?みたいなことまで書くかと言われれば,(僕自身の知識不足ももちろんありますが),時間的にも,費用対効果的にもしないでしょう.
記事が増えすぎたときにどうなるのか
今はせいぜい数百程度の記事しかなく,一覧で見てもなんとかなります.しかしこれが数千,数万に膨れ上がったら?それはソフトウェアで解決するのだろうか?というのは気になっています.
もちろん検索はあるので,キーワード検索やタグ検索などの方法をとることは可能です.しかし,「検索したいワードが分かっていないと検索は出来ない」という問題があり,そもそもどう検索すれば良いのかわからないシチュエーションでは内部Wikiもうまく効果を発揮できません.そもそもそれ以上時間をとらずに済むからWikiに書いたのに,「Wikiに書いてある内容を検索するための質問」とかをされるようになったら本末転倒です.
結局当人以外が記事を更新しない
特に研究室などでは,数年ごとに人が入れ替わります.そのため,過去に誰かが書いた記事がそのまま放置され,閲覧も更新もされない死んだ情報になってしまう可能性があります.属人性を排除するために記事として残したのに,その情報の修正/更新が属人化してしまっては元も子もありません.
更新されない理由として
- どういう記事があるのか知らない
- それを更新して良い物なのか判断できない
などがあると思っていて,今どういう記事が存在するのかをなんとなくでいいので把握しておくことが重要だと思います.僕は新しく記事を書いたときにSlack等で「こういうのを書きました」みたいなことを一言言うようにはしていますし,後輩と話しながら「じゃあそれ追記しておいて」とかは気軽に言うようにしています.とはいえ,そもそもSlackすらまともに見てくれない人たちや,自分がいなくなった後に入ってくる人たちにまで知らせることは難しいです.僕は他の人がどういうものを書いたのか見るのが好きで,更新があれば軽く覗いたりコメントしたりしているのですが,全員がこれをやる必要があるとまでは絶対言えないので,何かうまい対策が必要だなと感じています.
また,内容を盲目的に信じ切ってしまう人が出てくるのも課題だと感じています.「書いてあるから」「そうらしいから」などと信じ切ってしまう人が出てくると,その情報は更新もされずただただやってみたが上手くいかなかった「使えない情報」として処理されたり,時代錯誤なやり方が残って負の遺産となってしまう可能性があります.個人のレベルはまちまちなので仕方ないと言えばそれまでなのかも知れません.
最後に
情報が氾濫している現代では,情報の価値はそれを書いた人を自分がどれくらい信頼できるかで決まっていると感じています.同じ内容を知らない学生が言うのと,親しい友人が言うのではその重みが違うように,インターネット上でも知っている人の書いた情報と,赤の他人が書いた情報の間には大きな隔たりがあるはずです.
内部Wikiは現代では貴重な「ある程度信頼できる人が集まって作ったナレッジベース」であり,そこに情報を蓄積することは,自分だけでなく組織全体にとって意味があることです.全員が発信していける場を作り,全員で高め合っていけると最高ですね.
分割HHKB配列が実現できる自作キーボードキットChoco60を買った
はじめに
素晴らしいキットを制作,販売しておられるrecompile keysさん,自作キーボード関連の製品を手広くてがけておられる遊舎工房さんに感謝します.
というわけで完成しました.Choco60です. pic.twitter.com/PUYkQRueme
— 院生 (@pudding_info) November 4, 2019
Choco60とは?
recompile keysさんが今年開発された自作キーボードキットで,特徴としては以下の点が上げられます.
- CherryMX互換キースイッチ対応の62キーの分割キーボード
- HHKBをそのまま分割したような配列
- アンダーグロー非対応
- アクリルプレートサンドイッチマウント
詳細は以下の記事をご覧ください.
最上段の配列を削った40%キーボードのCocoa40という姉妹モデルもあります.
どこで買える?
遊舎工房で委託販売されています.また,イベントへの出展時に少数頒布されている場合もあるようなので,公式のTwitterアカウント(@recomplie_keys)をフォローするのが良いと思います.
売り切れになっていることが多い人気のキーボードキットですので,欲しい人はTwitterアカウントをフォローしてツイートの通知をオンにしておくと良いと思います.
なぜChoco60?
以前まではMint60を使用していました.
これはこれで大変良いキーボードキットで,一番最初にこれを経験できたのは大変幸運だったと感じています.しかし,上の記事中でも言及しているように,バックスラッシュやチルダ,バックスペースの位置がデフォルトだと合わず,HHKBライクにキーマップを変更して使って居ました.物理的に右上のキー数が足りないため,
という様な使い方をしていたため,しばらくHHKBを触った後に戻ってくると,混乱してESCの代わりにチルダとか,チルダの代わりにバックスラッシュとかを乱発したりするようになってしまいました*1.
研究室ではMint60,バイト先と家ではHHKBを使って居るため,できればHHKBに合わせたいところです.
- 耐久性と信頼性の観点から,仕事で使う道具はHHKB ProfessionalのUS配列が良い(Type-Sだとなお良い)
- でも分割キーボードは身体が楽なのでプライベートではなんとかしたい
- HHKBを単に二つ並べても,Fnがもう片方には伝播しないので難しい
- じゃあ分割キーボードでHHKB配列だ!
となるのは当然の流れだと思います.地味にHHKB配列は通常のUSともそこまで大きく乖離しないので,MacBookを使っても,ESCやチルダなど一部のキーを除けばちゃんと打てるのも個人的にはポイントが高いです.
キースイッチやキーキャップなど
recompile keysさんが技術書典で頒布された冊子Learning Custom Mechanical Keyboardを参考に,個人的にはリニアよりもタクタイルの方が好みだったため,以下の様な選択になりました.全て遊舎工房で購入することが出来ます.
- キースイッチ:ZealPC Zilent V2 62g
- ハウジング等の潤滑:Tribosys 3203
- スプリングの潤滑:Krytox GPL 105
キーキャップは当初JTK HyperFuseを検討していたのですが,お金が無くて手が出ず,次点で検討していた以下のキーキャップと同等の物が遊舎工房の店舗にあったのでこれを購入しました.
キースイッチの潤滑
具体的な方法は下記の記事が大変参考になります.
キースイッチオープナーは下記の物を注文しました.
素材はMJFのPA12GBです.エクスプレスサービスを利用したので通常注文はわかりませんが,注文してから4日目に手元に届きました.
初めてDMM makeのお世話になったんだけど,綺麗なもんだなぁ.
— 院生 (@pudding_info) November 2, 2019
キースイッチオープナーです. pic.twitter.com/OsqWPMh0ml
後はAmazonでマイクロアプリケーターを買いました.ルブステーションは使用しませんでした.感想としては「これを1日でやりきるスケジュールにした自分をひっぱたきたい」です.
ホームポジションの目印を作る
このキーキャップはFキーとJキーの位置に触って分かる目印が付いていません,個人的にはかなりこれに頼っているところがあるため,自作することにしました.
作り方は道具さえあれば難しくなく,UVレジンとUV照射器を使い,FキーとJキーに少しだけレジンを垂らして固めるだけです.少なくとも頑張って剥がそうとしてもびくともしない,くらいには頑丈になります.耐久性はこれから評価します.
UVレジンを借りてホームポジション用の目印を作った.ちゃんと固まると爪でガリガリやっても取れないし良さそう. pic.twitter.com/1yLTIIUY7t
— 院生 (@pudding_info) October 31, 2019
遊舎工房の店舗では他に
- 瞬間接着剤とラインストーンを使う
- 虫ピンを熱して刺す
などを紹介していただけました.ありがとうございます.
作り方
基本的には以下のサイトの通りです.キットにも特に説明書等は付属しないので,これを見てさっぱりわからんという人には難しいと思います*2
1. ダイオードを基板に刺す
キットの中身からまずは基板とダイオードを取り出します.適当にニッパで切りながら,基板に刺していきます.僕は指で適当に曲げながら差し込んでいきましたが,汚いので出来ればリードベンダー*3とかを使った方が良いです.
また,基板から浮いてしまうとスイッチと干渉するため,足を折り曲げるだけでなく,マスキングテープを使って固定した方がやりやすいです*4.足を先に切る派,半田付け後に切る派がいるらしいですが,どちらの場合でもニッパは小さい方がやりやすいです*5.
2. TRRSジャックとリセットスイッチのはんだづけ
本家の説明が少しわかりにくいのですが,Choco60というロゴのある方が表面で,recompile keysというロゴのある方が裏面になります*6.ダイオードは表面から付けて,裏面からはんだ付けしたことになります.
3. スタビライザーを装着
これは絶対lubeした方が良いことが経験的に分かっているので,少し過剰なくらいlubeしました.高い潤滑剤を使うともったいないので,Super lubeで十分です.それ以外には特に工夫はしていません.
4. 表側アクリルプレートを装着
先に表になるアクリルプレートを装着するのですが,順番的に先に3mmのスペーサーと8mmのネジをアクリルプレートに固定すると楽です.
短い方のネジでは明らかに長さが足りないのですぐ気付くと思います.長い方のネジを使って固定します.
これを基板の表面側(ダイオードのある側)から,各ネジの位置を合わせてはめ込み,裏側から長い方のスペーサーで固定します.無理に硬く締めると割れる可能性があるので,対角線上から順に少しずつ締めましょう.
5. キースイッチをはめ込んではんだ付け
少し押し込んで固定することになるのですが,このときアクリルプレートを一緒に押し込まないように注意しましょう.割れます.
後は裏面からはんだ付けするのですが,このときキースイッチが浮き上がっていないか確認しましょう.キーキャップを付けたとき,仕上がりが凸凹になってしまいます.
6. ProMicroをはんだ付け
最近のChoco60にはコンスルーが付属しているのでこれに準拠します.
ProMicroを裏向けにしてかぶせます.スペーサーの高さから分かるとおり,かなりギリギリです.少し浮かせてしまうと,簡単に干渉します.気をつけてはんだ付けしましょう.
7. ボトムプレートを装着
裏面からボトムプレートを装着し,ゴム足を貼り付けます.僕はコンスルーのピンとボトムプレートが少し干渉してしまい,若干たわんでいます.締める際は対角線上から順に,少しずつ締めていき,大丈夫か確認しましょう.
8. キーキャップをはめる
裏返して全てのスイッチにキーキャップを装着します.今回のキーキャップセットには合うスペースキーがなかったため,Shiftで代用しています.「-」と「=」が入れ替わっているのはこれを書いている最中に気付いて直しました…
ファームウェアを書き込む
Mint60はデフォルトでファームウェアが焼かれたProMicroが同梱されていたのですが,こちらは自分で書き込んでからで無いと動作確認もできません,幸いビルド環境を持たない人のために,デフォルトのhexファイルが頒布されているので,こだわりのない人はこれを使いましょう.
https://qmk.fm/compiled/choco60_default.hex
Dockerでビルド
前回の記事から少し更新があり,QMKが公式のDockerコンテナを出しました.少し使い勝手が違うので,紹介します.
# 自分でキーマップを書く人向け $ git clone --recurse-submodules https://github.com/qmk/qmk_firmware # 適当にキーマップを書く $ KEYMAP_NAME=キーマップ名 $ cp -r qmk_firmware/keyboards/choco60/keymaps/default qmk_firmware/keyboards/choco60/keymaps/${KEYMAP_NAME} $ vim qmk_firmware/keyboards/choco60/keymaps/${KEYMAP_NAME}/keymap.c # Dockerコンテナにクローンしたリポジトリをマウントしてビルドする # qmk_firmwareディレクトリまでの絶対パスを自分の環境に置き換える $ docker run --rm \ -v $PWD/qmk_firmware:/qmk_firmware \ qmkfm/qmk_firmware \ make choco60:${KEYMAP_NAME} # .hexファイルができる # ls -l | grep hex -rw-r--r-- 1 pudding staff 45333 Nov 4 13:50 choco60_pudding.hex
avrdudeで書き込み
最初に,macOS Catalinaの人はこちらを読んでください.
それ以外の人は,普通にavrdudeで書き込みが出来ます.裏面のリセットスイッチを押し,以下のコマンドを実行します.
$ sudo avrdude -p atmega32u4 -c avr109 -U flash:w:choco60_${KEYMAP_NAME}.hex
使ってみた感想
やはり慣れている配列というのは素晴らしく,新しいキーボードなのにすぐに手に馴染みます.キースイッチをタクタイルにしたのも個人的にはかなり正解だったと感じていますし,リニア軸に馴染めなかった人は検討してみると良いのではないでしょうか.作る上でもそんなに難しい箇所はなく,作りやすいキットだったと感じています.lubeしたり,macOS Catalinaでファームウェア書き込みするために調べまくっていた時間の方が,はんだ付けしている時間よりはるかに長かったです.
本当は家用にもう一台欲しいのですが,これ一台を作るために(いくら諸々の初期投資費用がかかっているとは言え)既にHHKB Professionalを2台くらい買える金額になり始めているので,ちょっと難しそうです.
まとめ
- 写真はちゃんとミラーレス一眼で撮れば良かった…
- Choco60はHHKBをそのまま左右に分割したような自作キーボード
- 作る上で難しいところは特になく,初心者でもおすすめできる
- macOS Catalinaはまだちょっとやめておいた方がいい
この記事はChoco60 + Zilent V2 62gで書きました.もう少し軽いタッチでも良かったので,リーフもlubeして良かったかも.
macOS Catalinaでavrdudeを使ってProMicroに書き込もうとするとprogrammer is not respondingというエラーが出る
はじめに
これは2019/11/4現在の情報です.macOS10.15よりも新しいバージョンでは当てはまらない可能性があります.何か更新があれば,コメントを頂けると幸いです.
[2019/12/12 追記]
この問題はmacOS Catalina 10.15.2で解消されました.
以下の内容はmacOS Catalina 10.15~10.15.1までのみで起きる問題です.回避するためにはmacOS 10.15.2へのアップデートを行なってください.
何が起きた?
QMK Firmwareを知らない自作キーボード界隈は居ないと思いますが,ファームウェアを
- Docker環境でビルド→avrdudeを直接叩いて書き込み
make キーボード名:キーマップ名:avrdude
でビルド & 書き込み
のどちらの方法でも,ProMicroに大して書き込みが出来なくなってしまいました.具体的には下記の様なエラーが出ます(Docker環境でビルドしたhexファイルを書き込もうとしていました).
$ sudo avrdude -p atmega32u4 -c avr109 -P /dev/tty.usbmodem142101 -U flash:w:.build/choco60_pudding.hex Connecting to programmer: .avrdude: ser_recv(): read error: Device not configured avrdude: butterfly_recv(): programmer is not responding avrdude: ser_recv(): read error: Device not configured avrdude: butterfly_recv(): programmer is not responding avrdude: ser_drain(): read error: Device not configured avrdude: ser_send(): write error: Device not configured avrdude: ser_recv(): read error: Device not configured avrdude: butterfly_recv(): programmer is not responding avrdude: ser_send(): write error: Device not configured avrdude: ser_recv(): read error: Device not configured avrdude: butterfly_recv(): programmer is not responding avrdude: ser_recv(): read error: Device not configured avrdude: butterfly_recv(): programmer is not responding avrdude: ser_send(): write error: Device not configured avrdude: ser_recv(): read error: Device not configured avrdude: butterfly_recv(): programmer is not responding Found programmer: Id = ""; type = Software Version = .; Hardware Version = . avrdude: ser_send(): write error: Device not configured avrdude: ser_recv(): read error: Device not configured avrdude: butterfly_recv(): programmer is not responding avrdude: ser_send(): write error: Device not configured avrdude: ser_recv(): read error: Device not configured avrdude: butterfly_recv(): programmer is not responding avrdude: error: buffered memory access not supported. Maybe it isn't a butterfly/AVR109 but a AVR910 device? avrdude: initialization failed, rc=-1 Double check connections and try again, or use -F to override this check. avrdude: ser_send(): write error: Device not configured avrdude: ser_recv(): read error: Device not configured avrdude: butterfly_recv(): programmer is not responding avrdude: error: programmer did not respond to command: leave prog mode avrdude: ser_send(): write error: Device not configured avrdude: ser_recv(): read error: Device not configured avrdude: butterfly_recv(): programmer is not responding avrdude: error: programmer did not respond to command: exit bootloader avrdude: ser_close(): can't reset attributes for device: Device not configured avrdude done. Thank you.
最初はリセットスイッチの押し忘れ・タイミング外れなど色々と検討しましたが,最終的に下記のIssueにたどり着き,Catalinaの問題であることが分かりました.
純粋にOS側での問題があるらしく,QMK Firmwareやavrdude側でどうにかすることが難しい事が伝わってきます.が,コメントでVirtualBox経由だと上手くいったといった内容が見受けられるので,じゃあVagrantでビルド環境ごと隔離すれば良いじゃんと思い,試してみました.
環境
以下の様な環境で試しています.
- macOS Catalina 10.15
- Homebrew 2.1.15
- avrdude version 6.3
- Vagrant 2.2.5
- vagrant-vbguest 0.20.0
- VirtualBox 6.0.14r133895
- VirtualBox Extension Pack 6.0.14
手順
1. QMK Firmwareをクローン
forkして使っている人や,既にローカルに持っている人はそれぞれ自分の環境に置き換えてください.最終的にローカルにリポジトリがあり,そのパスが分かれば良いです.ここでは適当にユーザのホームディレクトリ以下にcloneしたとして以降の手順を行います.
$ pwd /Users/ユーザ名 $ git clone --recursive https://github.com/qmk/qmk_firmware
2. VagrantとVirtualBoxのインストール
Homebrew Caskでインストールします.Extension Packとバージョンを合わせる必要があります.もしVirtualBoxだけ先にインストールしており,Extension Packのインストールに失敗する場合,先にbrew cask upgrade virtualbox
する必要があるかも知れません.
$ brew cask install \ vagrant \ virtualbox \ virtualbox-extension-pack
Guest Additionsの自動更新プラグインをインストールします.
$ vagrant plugin install vagrant-vbguest
僕はこの辺りで一度再起動を挟みました.
3. ProMicroデバイスの情報を確認
USBケーブルでProMicro(を実装した自作キーボード)とMacを接続します.VirtualBoxではUSBデバイスを仮想環境から扱うために,パススルーを許可するデバイスをホワイトリスト方式で許可する必要があります.そのためにプロダクトIDやベンダーIDを控える必要があります.VboxManage
コマンドを使って確認します.
$ VBoxManage list usbhost Host USB Devices: UUID: b8bdff28-b707-43f1-8340-51e9943f74f7 VendorId: 0x2341 (2341) ProductId: 0x8037 (8037) Revision: 1.0 (0100) Port: 1 USB version/speed: 0/Full Manufacturer: Arduino LLC Product: Arduino Micro Address: p=0x8037;v=0x2341;s=0x000008828f96a793;l=0x14210000 Current State: Busy # 以下略
VendorIdとProductIdをメモります.次に,リセットスイッチを押して書き込み可能状態にします.このとき,ProductIdが変化するので,これもまたメモります.
$ VBoxManage list usbhost Host USB Devices: UUID: b8bdff28-b707-43f1-8340-51e9943f74f7 VendorId: 0x2341 (2341) ProductId: 0x0037 (0037) Revision: 0.1 (0001) Port: 1 USB version/speed: 0/Full Manufacturer: Arduino LLC Product: Arduino Micro Address: p=0x0037;v=0x2341;s=0x000008828f96a793;l=0x14210000 Current State: Busy # 以下略
これを次の手順でVagrantfileに記述します.
4. Vagrantfileを用意
適当なディレクトリ(ここでは$HOME/qmk_vagrant
とする)に,以下の内容をVagrantfile
として配置します.
# -*- mode: ruby -*- # vi: set ft=ruby : Vagrant.configure("2") do |config| config.vm.box = "hashicorp/bionic64" config.vm.provider "virtualbox" do |v| # USBデバイスのパススルーを許可 v.name = "VM to flash firmware into ProMicro" v.customize ["modifyvm", :id, "--usb", "on"] v.customize ["modifyvm", :id, "--usbehci", "on"] # 以下にパススルーを許可するデバイスの情報(vendoridとproductid)を書く # nameは単に識別のためなので特に気にしないで良い v.customize ["usbfilter", "add", "0", "--target", :id, "--name", "Arduino Micro (writable)", "--vendorid", "2341", "--productid", "0037", "--remote", "no"] v.customize ["usbfilter", "add", "1", "--target", :id, "--name", "Arduino Micro", "--vendorid", "2341", "--productid", "8037", "--remote", "no"] end # ここを環境に合わせて書き換える config.vm.synced_folder "/Users/ユーザ名/qmk_firmware", "/qmk_firmware" config.vbguest.auto_update = true # avrdudeとQMK Firmwareのビルドツール一式を揃える config.vm.provision "shell", privileged: false, inline: <<-SHELL sudo apt-get update sudo apt-get install -y python3-pip avrdude /qmk_firmware/util/qmk_install.sh SHELL end
5. ProMicroをMacから抜く
USBケーブルで繋いでいたProMicroを抜きます.その方が安定しました.
おそらくmacOS側でビジーだと,VirtualBoxのゲストOS内にうまくマウントできないのだと思います.
6. vagrant upで仮想環境を起動
前の手順で用意したVagrantfileのあるディレクトリで以下のコマンドを実行します.
$ vagrant up
これで無事仮想環境が起動するのを待ちます.色々なインストールを含むので,多少時間がかかります.起動したらsshして仮想環境へ接続します.
$ vagrant ssh # USBデバイスを確認 (guest) $ lsusb Bus 001 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub Bus 002 Device 001: ID 1d6b:0001 Linux Foundation 1.1 root hub
7. 再びUSBで接続し,書き込む
再びUSBケーブルでMacとProMicroを接続します.以降の手順ではリセットスイッチを押す度にゲストOSが一瞬止まったように感じます.操作は反映されるので,焦って適当にコマンドを打たないようにしましょう.
リセットスイッチを押して書き込み可能状態にしてlsusb
してみます.
(guest) $ lsusb Bus 001 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub Bus 002 Device 003: ID 2341:0037 Arduino SA Bus 002 Device 001: ID 1d6b:0001 Linux Foundation 1.1 root hub
/dev/ttyACM0
が見えれば成功です.割とすぐ消えてしまうので,見えなくても焦らず再びリセットスイッチを押しましょう.
(guest) $ ls -l /dev/ttyACM0 ls: cannot access '/dev/ttyACM0': No such file or directory # 1,2回見つからなくても何度か押せば見つかる (guest) $ ls -l /dev/ttyACM0 crw-rw-rw- 1 root dialout 166, 0 Nov 3 15:30 /dev/ttyACM0
ここまで見えていればほぼ勝利です.ここから先は自分でavrdudeで書き込むのも,make
に任せるのもなんとかなります.
# /qmk_firmwareに移動 (guest) $ cd /qmk_firmware # ファームウェアをビルドして書き込み (guest) $ sudo make choco60:default:avrdude QMK Firmware 0.7.54 Making choco60 with keymap default and target avrdude avr-gcc (GCC) 5.4.0 Copyright (C) 2015 Free Software Foundation, Inc. This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. Size before: text data bss dec hex filename 0 16012 0 16012 3e8c .build/choco60_default.hex Copying choco60_default.hex to qmk_firmware folder [OK] Checking file size of choco60_default.hex [OK] * The firmware size is fine - 16012/28672 (55%, 12660 bytes free) Detecting USB port, reset your controller now................... # ここでリセットスイッチを押してしばらく待つ Device /dev/ttyACM0 has appeared; assuming it is the controller. Waiting for /dev/ttyACM0 to become writable. Connecting to programmer: . Found programmer: Id = "CATERIN"; type = S Software Version = 1.0; No Hardware Version given. Programmer supports auto addr increment. Programmer supports buffered memory access with buffersize=128 bytes. Programmer supports the following devices: Device code: 0x44 avrdude: AVR device initialized and ready to accept instructions Reading | ################################################## | 100% 0.00s avrdude: Device signature = 0x1e9587 (probably m32u4) avrdude: NOTE: "flash" memory has been specified, an erase cycle will be performed To disable this feature, specify the -D option. avrdude: erasing chip avrdude: reading input file ".build/choco60_default.hex" avrdude: input file .build/choco60_default.hex auto detected as Intel Hex avrdude: writing flash (16012 bytes): Writing | ################################################## | 100% 1.97s avrdude: 16012 bytes of flash written avrdude: verifying flash memory against .build/choco60_default.hex: avrdude: load data flash data from input file .build/choco60_default.hex: avrdude: input file .build/choco60_default.hex auto detected as Intel Hex avrdude: input file .build/choco60_default.hex contains 16012 bytes avrdude: reading on-chip flash data: Reading | ################################################## | 100% 1.13s avrdude: verifying ... avrdude: 16012 bytes of flash verified avrdude: safemode: Fuses OK (E:FB, H:D8, L:FF) avrdude done. Thank you.
手動でavrdudeコマンドを使って書き込む場合,以下の様にします.
$ sudo avrdude -p atmega32u4 -c avr109 -P /dev/ttyACM0 -U flash:w:hexファイルへのパス
直接 /dev/ttyACM0
を指定するのですが,見つからない場合以下の様にエラーが出ます.
$ sudo avrdude -p atmega32u4 -c avr109 -P /dev/ttyACM0 -U flash:w:.build/choco60_pudding.hex avrdude: ser_open(): can't open device "/dev/ttyACM0": No such file or directory avrdude done. Thank you.
リセットスイッチを押してからこのデバイスファイルが出現するまでラグがあるので,落ち着いて数回実行してください.
うまくいかないとき
最初全くうまくいかなかったのですが,あるとき急に上手くいくようになったので正直これはかなり再現性の低い手順なのではないかと思っています.ただいくつかポイントはあるかなと思っています.
- macOS側でProMicroに触らない(ビジー状態にしない)
- vagrant upする前に一旦USB接続を切断し,ゲストOS起動後に接続し直す
- リセットスイッチを押してからは失敗しても2,3回やり直す
- とりあえず再起動する
正直macOS Catalinaにアップデートしない or Windows,Linux等の他のOSを使用する方が絶対良いと思います(真顔).
まとめ
- macOS Catalina 10.15では,avrdudeを使ったQMK Firmwareの書き込みが出来ない
- これはmacOSのせいなので,他のOSを使用することで解決する
- ワークアラウンドとしてVagrantとVirtualBoxを使用し,ホストのUSBデバイスをゲストOSから参照することで書き込むことが出来る
この記事の手順は丸1日の試行錯誤を圧縮・整理した内容になっています.足りていない手順や余計な手順を含む可能性があることに留意してください.
早く修正されることを祈っています.それでは良きキーボードライフを.