ブログ
esptool：コマンド・フラグ・修正
esptoolは、ESP32ユーザーならいつか必ず手で叩くことになるツールです。Arduino IDEはその存在を隠し、PlatformIOも隠し——そしてある日、書き込みが失敗して、あなたはターミナルでPythonのコマンドを打ち込んでいる。この記事では、コマンドとフラグ、そして一度見れば何のことはないエラーたちをまとめます。
esptoolとは何？
esptoolはEspressif公式のコマンドラインツールで、シリアル経由でESP32チップと通信します。書き込み、消去、メモリ読み出し、個体識別までこなします。そして、事実上すべての書き込み経路がここを通ります。Arduino IDEもPlatformIOもesptoolを同梱していますし、Webインストーラも内部でこれを動かしています。つまり、このツールを知っておくことは、二度と繰り返さないデバッグの1時間を節約することを意味します。一度覚えれば、書き込みまわりの謎はほぼ消えます。
esptoolがインストールされているか確認するには？
ターミナルで esptool.py version を実行します。5.xや4.7のようなバージョン番号が表示されれば準備完了です。’Command not found’ と出る場合は pip install esptool でインストールしてください。必要なのはPython 3.7以上だけで、ほかに依存はありません。インストールした直後は、ターミナルを開き直してから確認するのがポイントです。
最もよく使うesptoolコマンドは？
主要なコマンドは5つです。chip_id はチップの識別、flash_id はフラッシュの読み取り、read_mac は工場出荷時のMACアドレスを表示、erase_flash は全消去、write_flash は指定アドレスへのバイナリ書き込み——日常の90%はこの5つで足ります。あともう1つ、merge_bin は複数のバイナリを1つのイメージに結合するコマンドで、書き込み済みのイメージを人に渡したいときなどに使います。
esptoolでファームウェアを書き込むには？
基本は1行です。esptool.py write_flash 0x0 firmware.bin に、多くのマシンでは --port COM3 を付け加えます。ここで重要なのがオフセットの理解です。0x0 はファクトリーイメージ（起動できる完全なイメージ）の開始位置で、ESP-IDFアプリは 0x10000 に書き込みます。オフセットを間違えると、基板は何も表示せずに沈黙したままになります。「文鎮化した」と報告される基板の多くが、実はこの書き込み位置ミスというオチです。オフセットとパーティション構成の関係は書き込みFAQで詳しく説明しています。
ESP32のフラッシュを消去するには？
esptool.py erase_flash でチップ全体を数秒で消去できます。ただし、誰もが読み飛ばす重要な警告があります。このコマンドはブートローダも消します。つまり、ストックファームウェアで動いていた基板は、何かを書き戻すまで起動しません。消去の用途は、破損したパーティションテーブルの修復やブートループの解消です。リセットだと思って使い、修理だとは思わないこと。消したら必ず続けて何かを書き込みましょう。
触る前にフラッシュをバックアップできますか？
できます。esptool.py read_flash 0x0 0x400000 backup.bin で、最初の4 MBをファイルに保存します。アップグレード前の定番の保険で、復元は同じオフセットへの write_flash で行います。ただし1つだけ落とし穴が。フラッシュ暗号化が有効になっている基板には、素のバックアップをそのまま復元できません。この点は去年の春、私が実地で学びました。暗号化を使っている基板は、バックアップ手順も別物だと覚えておいてください。
–port や –baud などのフラグは何をする？
--port はシリアルポートの指定です。WindowsならCOM3、Linuxなら/dev/ttyUSB0、macOSなら/dev/cu.usbserial-XXXXという具合です。--baud は通信速度の設定で、460800 が安全な高速の定番です。921600 を超えるとカクつくUSBチップもあるので、速度は基板のブリッジチップ次第と割り切りましょう。--chip は自動検出が失敗したときに、ターゲットチップを明示的に指定するフラグです。それ以外のフラグは、エラーが名指しするまで無視して構いません。
「Failed to connect to ESP32: Timed out waiting for packet header」が出るのはなぜ？
チップがブートモードに入っていない、という意味です。esptoolはROMブートローダが応答を待っている状態を必要とするので、定番の原因は3つ。自動リセット回路が配線されていない（裸モジュールの場合）、ポートの指定を間違えている、シリアルラインを他の何かが握っている——のどれかです。ちなみに私もこのエラーを1時間追いかけたことがありますが、原因はシリアルモニタを開きっぱなしにしていたことでした。対処の手順は、BOOTを押しながらENをタップし、BOOTを離して再試行。裸モジュールなら起動時にGPIO0をGNDへ落とします。詳しい切り分けはデバッグFAQにあります。
書き込みが100%で止まるのはなぜ？
多くの場合、これは正常です。データは書き終わっていて、基板は新しいファームウェアでリセットされ、静かにしています。ファームウェアにシリアル出力がなければ、このまま沈黙するのが正しい挙動です。一方、書き込み後にブートループする場合は、イメージのフラッシュサイズかチップの種類が違う可能性があります。esptool.py chip_id でチップを確認し、flash_id でフラッシュの容量を確認してから、書き直しましょう。2つのコマンドで、原因はほぼ特定できます。
esptoolはWindows・Linux・Macで同じように動く？
同じように動きます。esptoolはすべてのプラットフォームでPythonスクリプトとして動作するので、コマンドもフラグもオフセットも完全に同じです。異なるのはポート名とUSBドライバだけ。たとえばWindowsではCOM番号、Linuxでは/dev/ttyUSB*、macOSでは/dev/cu.usbserial-*という違いがあります。OSごとのドライバメモは当サイトのKBにまとめました。チームでOSが違っても、コマンドを共有できるのがこのツールのいいところです。