AtomVM: mix タスクなどで遭遇したトラブル

はじめに

ESP32-S3 上で AtomVM を使って Elixir アプリケーションを動かす際、
mix atomvm.esp32.flash などの mix タスクまわりで、いくつかつまずくポイントがありました。

エラーメッセージの原因が「環境変数の衝突」や「古いビルド成果物」などの場合、ぱっと見では気づきにくく厄介でした。

本投稿では、自分が実際に遭遇したのエラーと、それぞれの解決方法をいくつか簡潔にまとめてみます。

同じようにハマった方の参考になれば嬉しいです。

対象環境

• マイコン
  • ESP32-S3（例：/dev/ttyACM0）
• ホスト PC
  • Debian 系 Linux
• AtomVM / Elixir
  • mix atomvm.esp32.flash を使う構成

よく使うコマンド

自分が普段叩いているのはだいたいこれです。

mix atomvm.esp32.flash --port /dev/ttyACM0 --baud 115200

mix do clean + atomvm.esp32.flash --port /dev/ttyACM0 --baud 115200

:eacces（権限エラー）

症状

mix atomvm.esp32.flash を実行した際、esptool.py の起動で :eacces が発生。

$ mix atomvm.esp32.flash --port /dev/ttyACM0 --baud 115200
Compiling 5 files (.ex)

Generated sample_app app
No avm_deps directory found.
This message can be safely ignored when standard libraries are already flashed to lib partition.
...
Flashing using esptool..
** (ErlangError) Erlang error: :eacces
    :erlang.open_port({:spawn_executable, ~c"/home/mnishiguchi/esp/esp-idf/components/esptool_py/esptool/esptool.py"}, [...])

原因

ESP-IDF を ESP-IDF の環境を有効にした端末では IDF_PATH が設定されます。
その状態で mix atomvm.esp32.flash を実行すると、ESP-IDF 配下の esptool.py を使おうとして失敗することがあります。

解決策

方法① コマンド単位で IDF_PATH を無効化する

env -u IDF_PATH mix atomvm.esp32.flash --port /dev/ttyACM0 --baud 115200

方法② シェル上で IDF_PATH を外す

bash

unset IDF_PATH

fish

set -e IDF_PATH

ESP-IDF と AtomVM を同じ端末で切り替えて使う場合、
IDF_PATH が残っていないかを最初に疑うと切り分けが早くなります。

端末を分けると安心

環境の衝突を防ぐため、以下のように端末を分ける運用が便利でした。

用途	シェルの状態
AtomVM / Elixir 開発	IDF_PATH 未設定
ESP-IDF 開発	source export.sh 済み

compile-time env mismatch

症状

$ mix atomvm.esp32.flash --port /dev/ttyACM0 --baud 115200

** (Mix) the application :sample_app has a different value set for key :scene during runtime compared to compile time. Since this application environment entry was marked as compile time, this difference can lead to different behavior than expected:

  * Compile time value was set to: SampleApp.HinomaruScene
  * Runtime value was set to: SampleApp.TouchCalibrationScene

原因

Application.compile_env/3 など、コンパイル時に固定する設定を変えたのに、再コンパイルしていないと起きます。

対処

mix clean

いつもmix cleanするようにしていれば、この問題に遭遇することがないのかもしれません。

mix do clean + atomvm.esp32.flash --port /dev/ttyACM0 --baud 115200

ESP-IDF の Python 環境がバージョン不一致

症状

ESP-IDF v5.4 の install.sh を実行した際に、既存の Python 仮想環境が v5.5 用として扱われてエラーになりました。

ERROR: Python environment is set to /home/mnishiguchi/.espressif/python_env/idf5.5_py3.14_env which was generated for ESP-IDF 5.5 instead of the current 5.4. ...

$ ./install.sh esp32s3

Detecting the Python interpreter
Checking "python3" ...
Python 3.14.2
"python3" has been detected
Checking Python compatibility
Installing ESP-IDF tools
Selected targets are: esp32s3
Current system platform: linux-amd64
Installing tools: xtensa-esp-elf-gdb, xtensa-esp-elf, riscv32-esp-elf, esp32ulp-elf, openocd-esp32, esp-rom-elfs
Skipping xtensa-esp-elf-gdb@14.2_20240403 (already installed)
Skipping xtensa-esp-elf@esp-14.2.0_20241119 (already installed)
Skipping riscv32-esp-elf@esp-14.2.0_20241119 (already installed)
Skipping esp32ulp-elf@2.38_20240113 (already installed)
Skipping openocd-esp32@v0.12.0-esp32-20241016 (already installed)
Skipping esp-rom-elfs@20241011 (already installed)
Installing Python environment and packages
Python 3.14.2
pip 25.3 from /home/mnishiguchi/.espressif/python_env/idf5.5_py3.14_env/lib/python3.14/site-packages/pip (python 3.14)

ERROR: Python environment is set to /home/mnishiguchi/.espressif/python_env/idf5.5_py3.14_env which was generated for ESP-IDF 5.5 instead of the current 5.4. 

The issue can be solved by 
(1) removing the directory and re-running the install script, or 
(2) unsetting the IDF_PYTHON_ENV_PATH environment variable, or 
(3) re-runing the install script from a clean shell where an ESP-IDF environment is not active.

原因

ESP-IDF の環境が有効なシェルで作業していると、過去に生成された Python 仮想環境（IDF_PYTHON_ENV_PATH など）を拾ってしまい、
「今の ESP-IDF のバージョンと Python env が一致しない」状態になることがありました。

解決策

エラーメッセージ自体がかなり親切で解決方法が提示されています。

• 該当ディレクトリを削除して作り直す
• IDF_PYTHON_ENV_PATH を unset する
• ESP-IDF 環境が有効なシェルではなく、クリーンなシェルでやり直す

自分の場合は、新しい端末を開き直してクリーンな状態で install.sh を実行したら通りました。

新しい端末で

cd ~/esp/esp-idf
./install.sh esp32s3

おわりに

今回のトラブルを振り返ると、原因の多くは AtomVM 自体ではなく、

• ESP-IDF の環境変数が残っていた
• 設定変更後にビルド成果物が残っていた
• 以前作られた Python 仮想環境を拾っていた

といった 環境まわりのズレでした。

特に、

• IDF_PATH の有無
• 設定変更後の mix clean
• ESP-IDF install をクリーンな端末で行っているか

このあたりを最初に確認すると、切り分けがかなり楽になります。

同じところで何度もハマらないためのメモとして、誰かの参考になれば幸いです。