hoboNICOLAアダプタのプログラムのビルド方法

※ 当ページには、初期のhoboNicola 用のビルド情報が記載されています。SAMD21やRP2040用についての情報は、hoboNicolaの情報ページ内にあるそれぞれのリンク先を参照してください。

hoboNicolaアダプタは、SparkFun社のPro Micro (またはそのコピー品）をそのまま使っているので、PCに必要なソフトウェアを導入し、最新版のライブラリおよびスケッチ（Arduinoの世界では、プログラムソースをスケッチブックと呼ぶ）をビルドすれば、キーボードとして動作しているアダプタの中身を、ケーブルの抜き差しをすることなく入れ替えることができます。そのための手順を以下に説明します。

• プログラム更新のために必要なソフトウェアの導入。
• Pro Micro用USBドライバの導入（Windows 7, 8では必須）^*1。
• ソースファイルや必須ライブラリのダウンロードと配置。
• Arduino IDEを使ったビルドと書き込み。
• 注意点。

*1   Windows10では、Pro Micro用のUSBドライバをOSが備えているので、接続するだけで認識され導入されます。しかしながら、Windows 7, 8 では別途ドライバを導入してやる必要があります。
ここでいうドライバとは、HIDキーボード用のドライバではなく、Arduino IDEでファームウェアの更新を行うときに必要となるものです。

※ 2021年7月時点でのArduino IDEの最新版(1.8.15)に基づく内容も適宜追加しました。

ソフトウェアの導入

Arduino IDE 1.8.7版（またはそれ以降）

ビルドや書き込みのためには、Arduino IDEが必要です。このページでは、現在（2018年11月）の最新版（1.8.7版）を使うことを前提としています。以下、Windows環境での導入方法を記載します。

arduino.cc から Windows Installer版をダウンロードして実行します。このリンクをクリックすると、donation を求める画面になると思いますが、寄付するかどうかは個人で判断しダウンロードを行ってそれを実行します（arduino-1.8.7-windows.exe がダウンロードされます）。

インストーラを開始したら、なるべくインストーラが提示する初期値のまま、Arduino用のUSBドライバなども導入するようにしてください。

結果として、C:\Program Files(x86)\Arduino\…. というフォルダにバイナリ一式や各種ツールが導入され、以下のようなアイコンをもつプログラムショートカットが作成されます。

さっそく実行すると、実行した日付を含んだスケッチが提示されると思います。Arduinoでのスケッチの書き方などについて知りたい方は、適当に検索してください。

ファイルメニューに環境設定があり、スケッチブックの保存場所や、ビルドオプションなどを設定することができます。保存場所の初期値は、おそらくマイドキュメントの下になっていると思いますが、都合のよいフォルダに変更しても大丈夫です。このフォルダの下にhoboNicolaライブラリやその他の必須ライブラリを格納することになります。

環境設定内のビルドオプションやビルド時の情報表示については、最後の方で説明します。

SparkFun社のボードマネージャの導入

Arduino IDEは、arduino.cc が発売しているマイコンボード（いわゆるArduino）用のプログラムをビルドするためのものですが、他社のマイコンボードの開発を行うための拡張が可能です。
この拡張機能を利用して、hoboNicolaアダプタで使っている Pro Micro用の構成情報( ボードマネージャ ) を追加します。

ボードマネージャURLの入力

そのためには、ファイル／環境設定 を開きます。

上図でハイライトしている 追加のボードマネージャのURL: フィールドに以下を入力（貼り付け）します。

https://raw.githubusercontent.com/sparkfun/Arduino_Boards/main/IDE_Board_Manager/package_sparkfun_index.json

入力したらOKをクリックして、ダイアログを閉じてください。

※ sparkfun社のArduino用ボードマネージャURLは、最初にこれを書いた時点(2018年11月)とは変わっており、最新(2021年7月時点)の内容に変更しました。

複数のボードマネージャURLを登録しておくことも可能です。その場合はURLリストをプルダウンし、他のURLを消さないように追加しておきます。

Arduino IDE 1.8.15の場合

1.8.15版の環境設定ウィンドウは若干レイアウトが変わってますが、中身や入力内容は同じです。

ボードマネージャでの導入操作(1.8.7版)

次に ツール／ボード: を選択します。メニュー項目に何かArduinoのボード名が付加されているかもしれませんが、気にしない。選択するとボード一覧メニューがカスケードして表示されます。その一番上にある、ボードマネージャ… を選択します。

※ 1.8.15版では若干変更があり次節にまとめました(2021年7月)。

ボードマネージャの中には、現時点でArduino IDEがサポートしているマイコンボードやインタフェースボードの一覧が表示されます。

その中にある”SparkFun AVR Boards by SparkFun Electronics“を選択します。ダイアログ上部にあるフィールドに、”spa” とか打つと表示が絞り込まれて選びやすくなります。

この図では、すでに導入済なので、インストールボタンを選択不能になってますが、導入前ならば選択可能です。最新バージョン（現時点では、1.1.12）を選択し、インストールボタンをクリックして導入します。

導入後にボードマネージャからSparkfun AVR … を選択すると、上図のように、INSTALLED になっているはずです。閉じる でダイアログを閉じ、Arduino IDEに戻ります。

ボードマネージャでの導入操作(1.8.15版)

次に ツール／ボード: を選択します。メニュー項目に何かArduinoのボード名が付加されているかもしれませんが、気にしない。選択するとボード一覧メニューがカスケードして表示されます。その一番上にある、ボードマネージャ… を選択します。

ボードマネージャでは、各ボードの開発や実行に必要なツールや定義ファイルのArduino IDEへの導入や更新、削除といった作業を行います。

以前に比べると選択しやすくなってました。ボードマネージャの中には、現時点でArduino IDEがサポートしているマイコンボードやインタフェースボードの一覧が表示されます。

この一覧の中から”SparkFun AVR Boards by SparkFun Electronics“を表示します。ダイアログ上部にあるフィールドに、”spa” とか打つと表示が絞り込まれて選びやすくなります。表示される領域にマウスカーソルを合わせると以下のようになります。

SparkFun AVR Boards を導入していない状態では上記のようになるので、ドロップダウンリストから最新版(1.1.13) を選択してインストールをクリックします。インストールが完了すると以下のようになります。

導入後にボードマネージャからSparkfun AVR … を選択すると、上図のように、INSTALLED になっているはずです。閉じる でダイアログを閉じ、Arduino IDEに戻ります。

マイコンボード（SparkFun Pro Micro）の選択 (1.8.7版)

ツール／ボード を選択して開くカスケードメニュー内から、SparkFun Pro Microを選択します。

マイコンボード（SparkFun Pro Micro）の選択 (1.8.15版)

ツール／ボード を選択すると、カスケードメニューの中に SparkFun AVR Boards が追加されています。この項目を選択すると、SparkFun Pro Micro が出てくるので、これを選択します。

プロセッサ(動作電圧、周波数)の選択)

そして、ボード: の下にある、プロセッサ: をビルドする対象に応じて選択します。1.8.15版も同様。

• USB版ならば、ATmega32u4 (3.3V, 8MHz) を選択します。
• PS/2版ならば、ATmega32u4 (5V, 16MHz) を選択します。

このプロセッサの選択はとても重要です。USBキーボード用のhoboNicola アダプタに 5V/16MHzでビルドしたバイナリを書き込むと、PCからUSBデバイスとして認識されなくなり、USB接続での復活は難しくなります。PS/2版に8MHzでビルドしたものを書き込んだ場合も同様です。
機能しなくなったマイコンを「文鎮化した」とか言うことがありますが、大きさから言ったら「一口羊羹化」といったところです。

開発時には複数のアダプタを接続しているので、選択を間違えて書き込むことがあります。一切れの羊羹になったマイコンは、ちょっと特殊な方法でスケッチを書き直して復活するか、別のマイコンボードを使ってフラッシュメモリを消去し、ブートローダから書き直すなどする必要があってとても厄介です。

別のマイコンボードを使わず、特殊なリセット操作によって復活させる方法は、USBデバイスとして認識されなくなったPro Microの修復 という投稿にまとめました。

Pro Micro用USBドライバの導入(Windows 7, 8)

Windows10 では、この導入作業は不要です。Windows10ならば、Arduino IDEを使った接続の確認 まで読み飛ばしてください。

ダウンロード

SparkFun社のページ（実際はgithub）から、Pro Micro用のUSBドライバ等をダウンロードします。ダウンロード用のリンクはこちらです。

Arduino_Boards-master.zip が得られるので、中身のフォルダ（Arduino_Boards_master）を適当な場所にコピーしておきます。中身はこんな具合のはずです。

noboNicolaアダプタをPCに接続してもSparkfunドライバは導入されないが、キーボードとしては使えるはず

hoboNicolaアダプタのUSBケーブルをWindows7 PCに接続します。この時点ではキーボードを接続している必要はありません（接続していてもいい）。自動認識されドライバの導入が始まります。

ドライバが存在しないので終わりません。Windows Updateからの…スキップする をクリックして終わらせます。すると以下のようになるはずです。

つまり、USB Composite Deviceとして認識され、なおかつ、USB入力デバイスとして認識されたものの、Pro Micro独自のドライバは見つからなかった、ということです。

Windows 8.1の場合こういった表示は行われないようですが、Pro Micro専用ドライバが導入されていないことには変わりありません。

ここまでの段階では、上図のようになって大丈夫です。

ダウンロードしてきたPro Micro用ドライバの導入

上記の状態でWindowsのデバイスマネージャーを開いてみると、以下のようになっているはずです (Windows8.1の画面)。

ここで。SparkFun Pro Microという項目を右クリックしてメニューを開き、ドライバーソフトウェアの更新 を選びます。以下のようなダイアログが開きます。

コンピュータを参照して…　を選び、引き続いて開く以下のウィンドウで、先ほどドライバを展開したフォルダ名を参照してセットします。

そして、次へをクリックすると、すぐにドライバが見つかってインストールの問い合わせがあります。

「常に信頼する」必要はないので、チェックボックスは外しておき、インストールをクリック。最後に、更新が成功した旨の表示があるはずです。

成功しなかったならば、ドライバをアンインストールしてやり直すか、運が悪いと思ってあきらめる。

ここまでの手順は、SparkFun社の公式ページに出ている内容をなぞったものですが、公式ページの内容が若干古めなので現在のバージョンに即して記述しました。

Arduino IDEを使った接続の確認

Pro Micro用のドライバが必要な理由は、Arduino IDEからUSB経由でPro Microに接続し、各種情報のやり取りやファームウェアの書き込みを可能とするためです。前述のようにHIDキーボードとしてならば、Windowsが標準的に用意しているもので事足りています。
ここでは、Arduino IDEを使ってPro Microドライバが作成した仮想シリアルポートを確認します。PCにhoboNicolaアダプタを接続しておいてください。

シリアルポートの選択

Arduino IDEを開き、ツール／シリアルポートを選択します。

COMの番号は導入したPCごとに変わりますが、COM3かCOM4の場合が多いと思われます。COMポートが１つしか表示されていないならば、おそらくそれがPro Microドライバが作った仮想シリアルポートです。そのCOMxx を選択します。

上図のように複数のCOMポートが出てきた場合、どちらがhoboNicolaアダプタのものか判断する必要があるので、とりあえず番号の若い方を選択します（ここではCOM10）。

ボード情報の取得による確認

ツール／ボード情報を取得 を選択すると以下のようなウィンドウが開きます。

ここには、現在選択中のボードのUSBのVID (Vendor ID) とPID (Product ID)  が表示されており、上記の値（0x1BF4と0x9204）が、SparkFun Pro Micro +3.3V/8MHz 版を表しています。これにより、選択中の仮想COMポートには、USB版のhoboNicolaアダプタが接続されていることが確認できます。

たとえば+5V/16MHz版ならば、0x1BF4と0x9206 となり識別できます。

同じPCに複数のhoboNicolaアダプタが接続されている場合、ボード情報だけでは識別できませんので、一方のUSBケーブルを抜くなどして、プログラムの更新対象を確認する必要があります。

必須ライブラリの導入

miniUHS用ライブラリの導入

USBアダプタのキーボード側は、mini USB Host Shield （以下、miniUHS ）という製品を利用しています。miniUHSをコントロールするためのライブラリの USB Host Shield Library 2.0 を、Arduino IDEに追加します。

※ PS/2アダプタや自作キーボード用しかビルドしない場合、UHS2.0ライブラリの導入は不要です。

Arduino IDEで、ツール／ライブラリを管理… を選択すると、以下のような ライブラリマネージャ が開きます。

検索をフィルタ と表示されているフィールドに、USB HOST と入力すると、おそらく以下のような表示になります。

上図でハイライトしている、USB Host Shield Library 2.0 が導入の対象ですのでクリックして選択します。選択すると、バージョン選択のリストとインストールボタンが表示されるので、バージョン1.3.2以降(1.6.0を推奨)を選択してインストールをクリック。導入されると、USB Host Shield Library 2.0 by … の後ろに青字で INSTALLED と表示されます。

この操作で導入されたライブラリの一式は、スケッチブックの保存場所 フォルダの下に、libraries\USB_Host_Shield_Library_2.0 という名前のフォルダ名で格納されているはずです。一応確認しておいてください。

hoboNicolaライブラリのダウンロードと導入

hoboNicolaアダプタ用にビルドが必要なファイルは、すべてこのライブラリ内に入っています。当初はArduino標準のHIDライブラリの変更などが必要でしたが、1.2.0版以降はライブラリ内に含めることにしました。

ダウンロード

hiboNicolaのページから、hoboNicolaライブラリの最新版をダウンロードしてArduino IDEに導入します。
最新版のzipファイルをダウンロードしPCに保存してください。Arduino IDEへの導入はzipファイルのまま行うのでunzipは不要です。

今後ライブラリの更新があった場合、都度ごとにダウンロード、導入、ビルドを繰り返すことになります。

導入と確認

Arduino IDEの スケッチ／ライブラリをインクルード を選択すると、ライブラリ一覧がカスケードして表示されます。一覧の上の方にある、.ZIP形式のライブラリをインストール… を選択します。するとインストール対象のファイルの選択を求められるので、先にダウンロードした hoboNicola121.zip を選び 開く をクリックすると導入処理が行われ、すぐに終わります。

再び スケッチ／ライブラリをインクルード を選択し、今度はライブラリ一覧の下の方までスクロールしてください。提供されたライブラリ というキャプションの下に、導入したライブラリが見えていることを確認します。

存在を確認したら、ライブラリの選択を行わずに、メニューを閉じます。

※ 同じ名前のライブラリを複数回導入することはできません。その必要が生じたときには、Windows Explorer などで [スケッチの保存フォルダ]\libraries\[対象のライブラリ] をフォルダごと削除してから導入作業を行います。hoboNicola120.zipは、…\libraries\hoboNicolaLibrary120 という名前で格納されています。

hoboNicola 1.2.0 以降のライブラリを導入するときも同じ作業となりますが、ライブラリ名に付加する番号で識別できるようにしています。今のところ、古いライブラリと共存させておいても、ビルドが正常に完了する場合には問題ありません。

ビルドと書き込み

各部名称について

以降、Arduino IDEの各部の名称を以下のように表記します。

スケッチエディタでは、Arduino用のスケッチの作成や編集ができます。ほぼC++で記述すると思って間違いありません。
ただ、ここで記述したスケッチは、main() を含んだライブラリに取り込まれてからビルドされるため、若干の制限事項もあります（詳細は、arduino.cc を参照のこと）。

メッセージ領域には、コンパイル結果（成功、失敗）、マイコンボードへの書き込み結果 などが表示されます。

情報出力領域には、ビルド時やマイコンボードへの書き込み時のメッセージが表示されます。初期設定では、ビルドエラーの有無や、コードサイズ、データサイズ等が表示されるだけですが、オプションの変更により情報量を増やすことができます。
情報量を増やすことで、Arduino IDEが呼び出すコンパイラ（avr-g++）や、マイコンボードへの書き込みを行うツール（avrdude）が出力する内容をそのまま表示させることもできます。

ステータスバーには、選択中のシリアルポート、対象のマイコンボード名およびプロセッサの種類が表示されます。

ビルドオプションや情報表示量の変更

ビルドオプションや情報出力領域への表示量を増やしたからといって、出来上がるものが変わるわけではありません。ただ、ビルドエラーが生じた場合など、詳細な情報が必要になることがあるので、以下のように設定しておくのがよいでしょう。

ファイル／環境設定 を開きます。

上図でハイライトしている部分について。

より詳細な情報を表示する:

コンパイルをチェックしておくことで、g++がビルドしている内容が情報出力領域に表示されます。これにより、ビルド対象としているライブラリや、ビルド時のインクルードディレクトリを確認できます。チェック有を推奨。

書き込みをチェックしておくことで、avrdudeがマイコンボードに書き込んでいる状況が逐次表示されるようになります。こちらは、チェック有としておくのがよいでしょう。

コンパイラの警告:

コンパイル時のWARNINGレベルを調整するためのものです。初期値、より多く、すべての三段階から選択できます。コンパイルエラーについてはレベルによらずエラーですから表示されます。

推奨設定は「より多く」です。

• 初期値 にしておくと、変なことを書いてなければ警告されません。
• より多く にすると、signedとunsigned の比較など、とりあえずいいんじゃないと思って書いたものが警告対象になります。このレベルでのWARNINGは出ない方がいいでしょう。
• すべて にすると、利用しているライブラリ内のビルド時にも数多くのWARNINGが表示されるようになります。勝手に手を入れるわけにもいかないので放置することになりますが、ビルド環境が変わった際（Arduino IDEのバージョンアップなど）には注意しておくべき部分。

行番号の表示

エラー発生行を確認するためにも、チェック有がよいでしょう（初期値もチェック有かもしれない）。

メインモジュールのビルドと書き込み

Arduino IDEを使ってビルドと書き込みを行います。hoboNicolaライブラリのメインモジュールは、ライブラリ内にスケッチ例という形態で格納してあります。

usb_hobo_nicolaを開く（またはps2_hobo_nicolaを開く）

ファイル／スケッチ例 を選択すると、Arduino IDEに付属しているものや、ライブラリの導入に合わせて追加されたものなど、いろいろスケッチ例の一覧がカスケード表示されます。
下の方に、カスタムライブラリのスケッチ例 というキャプションがあり、その下にhoboNicola Library 1.2.0 という項目 (またはそれ以降の番号をもつ項目）があるはずなので、src > をクリックすると以下のようになります。

hoboNicola Library 1.2.0は上図のように４つのスケッチ例を含んでいます（以降のバージョンでは、追加または削除されている場合があります）。スケッチ例としていますが、これらがメインモジュールです。USB版ならば usb_hobo_nicola を、PS/2版ならば ps2_hobo_nicola を選択します。
なお、ble_hobo_nicolaのビルドのためには、Arduino core for the ESP32 という構成セットを導入し、ESP32開発ボードを用意しておく必要があります。askeyboard用のスケッチについても本稿では触れません。

Arduino IDEのウィンドウが新たに開き、選択したスケッチがスケッチエディタに表示されます。

ビルド

※ ビルドを実行する前に、前述のようにボードとプロセッサを確認してください。ステータスバーにも表示されています。

スケッチ／検証・コンパイル を選択することでビルド（コンパイル、リンクなど）が開始します。成功すると、メッセージ領域に コンパイルが完了しましたと表示されます。

情報出力領域の最後には、ビルドして得られたプログラムのメモリ情報が表示されます。

これはusb_hobo_nicolaをビルドした際のものです。ビルド環境によって、スケッチサイズ（占有するフラッシュ領域のサイズ）とデータサイズ（RAMサイズ）が異なることはないと思うんですが、この数字と大きく異なるようならば何か問題があるのかもしれません。
これらの数字からは、コード、データ共にもうちょっと余裕があることが分かりますが、「ローカル変数」の領域にはスタック領域も含まれているので、あまり拡張はできません。

マイコンボードに書き込む

xd87 PCBやxd64 PCB(ver3) への書き込みは、Arduino IDEではできません。Atmel FlipなどAtmel DFUブートローダに対応したソフトウェアを用いる必要があります。Atmel Flipの使い方については、こちらを参照してください。

スケッチ／マイコンボードに書き込む を選択します。再度コンパイルとリンクなどが行われ、マイコンボードへの書き込みが開始します。

アダプタのPro Microに載っているLEDが数回点滅し、転送が行われていることを示します。点滅が完了した一瞬後にはキーボードとして動作しているはずです。

書き込みが成功すると、メッセージ領域には ボードへの書き込みが完了しました と表示されます。

書き込み時の情報

情報出力領域にはビルド時とほぼ同じ内容の後、以下のように表示されます。

Pro Micro特有の動作として、通常はキーボードとして見えているUSBポートを、プログラム転送用のシリアルポートに一時的に変更してから書き込みが行われています。

完了

書き込みが完了した一瞬後にはキーボードとして動作しているはずです。この時点でアダプタにキーボードが接続されていればすぐに使えるでしょう。

USB版では、アダプタへのキーボードの接続は任意の時点で行うことができます。稼働後（PCへのUSBケーブルの接続後）にキーボードをつないだ場合、認識まで1,2秒かかることがあります。その場合も、適当にキーを叩けばキーボード入力がPCに反映されること分かるので、認識されたと確認できます。一応、ホットプラグ対応ということになっています。

PS/2版の場合、まずキーボードをアダプタに接続してから、アダプタとPC間のUSBケーブルを接続する必要があります。キーボード未接続でアダプタを稼働させた場合、Pro MicroのLEDが点滅を繰り返し、キーボードが認識できなかったことを知らせます。PS/2接続はホットプラグ対応ではありません。

注意点

1. PCがブートした直後のパーティション選択やBIOS操作など、一応対応していることになっています。しかしながら、不安がないわけではないので、BIOS操作が必須ならば、別のUSBキーボードを接続できるようにしておいたほうがいいでしょう。
2. ハードウェアとしての注意点ですが、アダプタをUSBハブに接続して使うとき、ハブ自体が電源をもたないバスパワードHUBに接続していると、キーボードとしての挙動が不安定になり、PCの起動時にBIOSエラーとなったり、入力中に突然機能しなくなるようなこともあるようです。セルフパワードHUBやPCに直結することを推奨します。
3. Pro MicroのUSBマイクロBコネクタは、ちょっとの力でもげ取れます。基板から持ち上げる方向に力がかからないようにしてください。

コネクタがもげるとき、基板上のパターンの銅箔も剥がしていくので修復は不可能で、Pro Microを取り換えることになります。
このため、PC-アダプタ間のUSBケーブルはPro Microから抜かないようにした方がいいでしょう。抜く必要がある場合はPC側を抜きます。ケーブルごと接着剤で固めてしまってもいいかもしれません。

以上）