ブログ
ESP32ライブラリ：インストール・使い方・修正
ライブラリのインストールは楽なほうです。面倒なのは、次のコンパイルを壊すバージョン不一致。ライブラリがどこに置かれるのか、動くものをどう選ぶのか、サンプルがビルドできないときの対処までを順に解説します。
ArduinoにESP32ライブラリをインストールするには？
いちばん簡単なのはライブラリマネージャです。スケッチ → ライブラリをインクルード → ライブラリを管理 から検索してインストールするだけで、ESP32用ライブラリの大半はここにあります。手動で入れる場合は、ZIPをダウンロードして、スケッチ → ライブラリをインクルード → ZIP形式のライブラリを追加 を選びます。1つだけ注意点が。ライブラリマネージャはすべてのボード向けライブラリをまとめて列挙するので、ESP32タグで絞り込むか、リポジトリがarduino-esp32対応と明記しているか確認しましょう。フォルダの構成ルールはArduino IDE FAQで説明しています。
ESP32でアニメーションGIFライブラリを使うには？
定番はLarry Bank作のAnimatedGIFです。TFT_eSPIと組み合わせれば、一般的なSPI接続のディスプレイでGIFを再生できます。ここで重要なのがRAMの話。GIFは生のフレームにデコードされるため、320×240の1フレームでおよそ150 KBを消費します。だから2 MBフラッシュのチップではアニメーションが苦しくなり、PSRAM搭載基板なら快調に動きます。私の240×320のILI9341では約15 FPSが出て、ループアニメーションには十分滑らかでした。動作する構成例はサンプルプロジェクトのページにあります。
ESP32にハードウェアシリアルライブラリはある？
あります。HardwareSerialはコアに組み込まれていて、インストールは不要です。従来のESP32ではSerial、Serial1、Serial2が使えます。C3やS3では、Serial1とSerial2が使えるかどうかがチップのUART次数に依存します。ちなみに「harware serial」という検索はタイポなのですが、どちらで検索しても同じ内蔵ライブラリにたどり着きます。追加のインストールが不要なので、はじめてのシリアル通信にはうってつけのライブラリです。
ある基板ではコンパイルできるのに別の基板でできないのはなぜ？
原因のほとんどは基板固有の設定です。#define に直書きされたピン番号、PSRAMの有無、想定されているフラッシュサイズ——このあたりの前提が違うと、コンパイルエラーになります。ESP32ライブラリの多くはWROOM-32の4 MBフラッシュを前提に設計されていて、S3基板では配線が違うピンをハードコードしています。対処の第一歩は、ライブラリのREADMEに書かれた対応基板表を読むこと。表に基板名が列挙されているなら、あなたの基板が載っているかを確認してください。載っていないものは最初から諦めるのが無難です。
インストールしたのにライブラリが見つからない？
まずIDEを再起動してから、スケッチブックフォルダを確認します。場所は File → Preferences で確認でき、ユーザーライブラリは <sketchbook>/libraries に置かれます。よくある失敗は2つ。1つ目は、ZIPが二重のフォルダ構造で展開されたケース——Arduinoは .h ファイルが1階層下にあることを期待します。2つ目は、IDEが壊れたコピーをキャッシュしたケースで、この場合はライブラリを削除して入れ直せば直ります。手順をスクリーンショット付きで知りたいなら、ナレッジベースをどうぞ。
コア更新でライブラリが壊れた。どうすれば？
arduino-esp32の2.xから3.xへの更新でAPIが改名され、古い名前に固定されたライブラリは、意味不明なエラーを出して失敗します。直す順番は決まっています。まずライブラリを最新版に更新。それでダメならライブラリのチェンジログを読む。それでもダメなら、ボードマネージャでコアをライブラリが要求するバージョンに固定します。この順番を飛ばしてコアをあちこち切り替えると、かえって状況が複雑になります。落ち着いて、1つずつ。
内蔵ライブラリとサードパーティライブラリの違いは？
「内蔵」はコアに同梱されているライブラリです。WiFi.h、HardwareSerial、SPI、Wireなどが代表例で、インストール不要で、コアの更新に合わせて一緒に更新されます。「サードパーティ」は外部リポジトリから配布されるライブラリで、センサー、ディスプレイ、サービスの類です。こちらは独自の更新ペースで動くため、コアの更新と噛み合わずに壊れることがあります。だからこそ、バージョン固定が重要なのです。内蔵はその心配がありません。
2つのライブラリが同じ関数を定義している。衝突する？
衝突します。そして厄介なことに、リンカーが黙ってどちらか一方を選ぶか、エラーになります。C++はこれを止めてくれないので、結果は「どちらが呼ばれるか」のコイントスのようなものです。エラーメッセージから重複を見つけたら、使わないほうのライブラリをアンインストールするか、名前空間が用意されていればそちらを使いましょう。私もかつて2つのDHTライブラリを同時に入れて当たりました。解決策は、使っていなかったほうを消すだけでした。
スケッチが必要なライブラリを見分けるには？
スケッチ冒頭の #include の行を読むのが第一歩です。そこに書かれた名前を、ライブラリマネージャで1つずつ検索します。Adafruit BMP280、U8g2など、検索すればたいてい見つかります。次のステップとして、READMEかサンプルのヘッダに「作者が推奨するフォーク」が書かれていることが多く、改名されたライブラリではこれが重要になります。そして最終的な判断基準は1つ。Issueが実際に解決され続けているライブラリこそ、動くライブラリです。
自分でESP32ライブラリを作れますか？
作れます。<sketchbook>/libraries の配下に、.h ファイルと .cpp ファイル、それに library.properties を入れたフォルダを作るだけで、それは立派なライブラリです。設計のコツは2つ。使うAPIを外に公開することと、ハードウェア固有の設定はヘッダの設定項目にまとめること。突き詰めると、ESP32ライブラリとは「ESP32用ヘッダを #ifdef で切り替えるArduinoライブラリ」のことです。作り始めれば、思ったより敷居が低いと感じるはずです。
この記事のテーマのプロジェクトは、sensbench の無料シミュレーターでそのまま実行できます。回路は配線済み、ファームウェア同梱、アカウントもインストールも不要です。