R2P2ESP32
English 日本語

環境構築

ESP-IDFをローカルにセットアップするか、代わりにDockerを使います。お好みの方法をどうぞ。

どちらの方法でも、まずはサブモジュールを含めてリポジトリをクローンします。

$ git clone --recursive https://github.com/picoruby/R2P2-ESP32.git
$ cd R2P2-ESP32

ESP-IDFを使う場合

前提条件

Espressifのインストールガイド に従ってESP-IDFをセットアップしてください。ビルドはESP-IDF v5.5で確認されています。

ESP-IDFを有効化する

新しいシェルセッションを開始するたびに、ESP-IDFを有効化してツールをPATHに追加します。

$ source ~/.espressif/tools/activate_idf_v5.5.x.sh
$ export PATH="$IDF_PATH/tools:$PATH"

続いて、お使いのバージョン管理ツールで対応するRubyをPATHに通します。

# mise
$ mise use ruby@4.0.5
# asdf
$ asdf local ruby 4.0.5
# rbenv
$ rbenv local 4.0.5

Tip: direnvを使うと、これらの環境変数をプロジェクト ディレクトリ内に限定して自動的に適用できるため、毎回手動で有効化する必要がなくなります。

Note: ターゲットのセットアップは、一部の ホスト側ツールをネイティブ(クロスではない)ツールチェーンでビルドします。 ESP-IDFのクロスツールチェーンがPATHに含まれていても通常は自動検出されますが、 検出結果が正しくない場合はHOST_CC / HOST_AR環境変数で上書きしてください。

Dockerを使う場合

ESP-IDFやRuby、ホストツールチェーンをマシンに直接インストールする代わりに、 公式のespressif/idfイメージをベースにした コンテナ内で完結してビルドすることもできます。このイメージにはすでにESP-IDF、gcc、rubyが 含まれています。プロジェクトのdocker/Dockerfileは、そのイメージに不足しているパッケージ (ruby-dev、libssl-dev)を追加するだけのものです。rake docker:*タスクは、初回実行時に このイメージを自動的にビルドします。ホスト側に必要なのはDockerだけです。

macOS: virtiofsを有効にする

プロジェクトディレクトリはコンテナにバインドマウントされるため、Dockerのファイル共有 バックエンドがシンボリックリンクを正しく扱える必要があります。ビルドは components/picoruby-esp32/picoruby以下にベンダリングされたシンボリックリンクを通じて ファイルの読み書きを行います。

macOSではvirtiofsを有効にする必要があります。 それ以外のバックエンド (Docker DesktopのgRPC FUSE / osxfs、Rancher Desktopのreverse-sshfs / 9p)では Operation not permittedエラーが発生します。

ESP-IDFバージョンの指定

デフォルトで固定されているESP-IDFパッチバージョン(v5.5.4、rakelib/docker.rakeの DOCKER_IDF_TAGを参照)と異なるバージョンを使いたい場合は、 イメージのタグ一覧からESP_IDF_DOCKER_TAGを 設定します。

$ export ESP_IDF_DOCKER_TAG=v5.5.5
$ rake docker:build

.envによる設定

ネイティブビルドと異なり、docker:*タスクはシェル環境からSDKCONFIG_DEFAULTSや USE_WIFIなどを読み込みません。代わりに、プロジェクトルートに(gitignore済みの) .envファイルを置いてください。存在する場合はそのままコンテナに渡されます。 Dockerの--env-file形式はシェルのようにクォートを取り除かないため、 値をクォートしないでください。

# .env
SDKCONFIG_DEFAULTS=sdkconfig.defaults;sdkconfigs/usb_console

SDKCONFIG_DEFAULTSに何を指定するかは設定を参照してください。

Note: docker:flash / docker:monitorタスクは用意されていません。ほとんどの コンテナ環境(macOS/WindowsのDocker DesktopやRancher Desktop)では、デバイスの シリアルポートをコンテナに渡すことができないためです。これはDockerfileやCLIフラグの 問題ではなく、それらのLinux VM内からポートそのものが見えないことが原因です。 docker:buildでビルドしたイメージは、ホスト側からフラッシュとモニタリング してください。これらもフルのESP-IDFインストールは不要です。ネイティブLinuxでは、 docker run --device=/dev/ttyUSB0 ...でシリアルデバイスを渡せば、コンテナ内から 書き込むことも可能です。

必要なツールのインストール

ホスト側でのフラッシュ・モニタリングにも、フルのESP-IDFインストールは不要です。 rake flash / rake monitor(フラッシュとモニタリングを参照)は idf.pyではなくesptool / esp-idf-monitorを直接呼び出すため、Dockerでビルドした build/であっても、ホスト側は次の2つのPythonパッケージだけで動作します。

$ pip install esptool esp-idf-monitor

これだけです。フラッシュ・モニタリングだけであれば、ESP-IDFの有効化(activate)は 必要ありません。(ESP-IDFを直接使ってビルドした場合は、そのインストールの一部として すでに手元にあります。)

次のステップ

設定でハードウェア固有の設定を確認し、最初のビルドの前に ターゲットのセットアップを行ってください。

このページをGitHubで編集