Getting Started With Esp32 on Macos

by Werner Vogels

macOSにおけるESP32開発ガイド (uv + esptool)

このドキュメントは、macOS上でuvとesptoolを使用してESP32のMicroPython開発を安定して行うための手順と、遭遇しやすいトラブルの解決策をまとめたものです。

1. 仮想環境の構築

システムのPython環境を汚さず、プロジェクトごとに依存関係を管理するため、uvによる仮想環境の利用を推奨します。

  1. プロジェクトディレクトリの作成
mkdir my_esp32_project
cd my_esp32_project
  1. 仮想環境の作成と有効化
# 仮想環境を作成
uv venv
# 仮想環境を有効化 (プロンプトの先頭に (.venv) と表示される)
source .venv/bin/activate
  1. esptoolのインストール
uv pip install esptool

2. ESP32との基本操作

2.1. 接続ポートの特定

ESP32がどのシリアルポートに接続されているかを確認します。

  1. ポートのリスト表示
ls /dev/tty.*
# /dev/tty.usbserial-XXXXのような名前がESP32のポートである可能性が高いです。
  1. 確実な特定方法 ESP32をMacから抜き、再度ls /dev/tty.*を実行して消えたポート名を確認します。もう一度接続し、現れたポート名が対象のポートです。

2.2. ファームウェアの書き込み (クリーンインストール)

ブートループなどの問題を回避するため、**「一度完全に消去してから書き込む」**という手順が最も確実です。

  1. フラッシュメモリの完全消去 esptoolを使い、ESP32のメモリを初期化します。
esptool --port [あなたのポート名] erase_flash

例: esptool --port /dev/tty.usbserial-0001 erase-flash

  1. MicroPythonファームウェアの書き込み 公式のファームウェアをダウンロードし、ESP32に書き込みます。
  • ダウンロード: MicroPython公式サイトから、お使いのボード用の最新安定版（Stable）.binファイルをダウンロードします。
  • 書き込みコマンド:esptool --chip esp32 --port [あなたのポート名] write_flash -z 0x1000 [ダウンロードした.binファイル名]

3. REPLへの接続とトラブルシューティング

3.1. REPLへの接続方法

screenコマンドを使い、ESP32上のPython対話環境（REPL）に接続します。接続コマンドボーレートは115200を指定します。

screen [あなたのポート名] 115200

プロンプトの表示 接続直後、文字化けや起動ログが表示されることがあります。画面が落ち着いたらCtrl+Cを押してください。これにより実行中のプロセスが中断され、»>というREPLプロンプトが表示されます。

3.2. よくあるトラブルと解決策

問題原因解決策
Resource busyエラーscreenがポートを掴んだままになっている。1. screen -lsでセッションを確認。
2. killall screenまたはkill -9 [PID]でプロセスを終了。
3. screen -wipeでデッドセッションを掃除する。
ブートループ
（同じログが延々と表示される）		ファームウェアが破損しているか、起動スクリプト(boot.py)に問題がある。上記2.2. ファームウェアの書き込みの手順に従い、フラッシュを完全消去してから再書
文字化け
(REPLが起動しない)		1. ボーレートの不一致。
2. 正常な起動ログ。		1. ボーレートが115200であることを確認する。
2. Ctrl+Cを押してREPLプロンプトを呼び出す。
  1. 作業の終了screenセッションを正しく終了させないと、次回接続時にResource busyエラーの原因となります。正しい終了方法: Ctrl+Aを押した後にKを押し、確認メッセージにyと入力