ESP32でesptool.pyの使い方

現時点の情報です。最新情報はM5StickC非公式日本語リファレンスを確認してみてください。

概要

Windows環境でESP32のフラッシュツールであるesptool.pyの使い方を調べてみました。

esptool.pyとは？

• https://github.com/espressif/esptool

ESP32の販売元であるEspressifが公開しているツールであり、ESP8266とESP32用のブートローダーと通信するためのPythonプログラムです。

Python 2.7またはPython 3.4以降がインストールされている環境であれば、OSに依存せずに動かすことができます。

$ pip install esptool

Pythonが適切に設定されている場合には上記のコマンドで設定できると思います。Windowsの場合には動作に制限が多いMicrosoft Storeからではなく、直接ダウンロードしたほうがトラブルが少ないと思います。

esptool.pyコマンド一覧

コマンド	解説
load_ram	イメージをRAMにダウンロードして実行する
dump_mem	任意のメモリをディスクにダンプします
read_mem	任意のメモリ位置を読み取る
write_mem	任意のメモリ位置へ書き込み
write_flash	バイナリBLOBをフラッシュに書き込む
run	フラッシュでアプリケーションコードを実行する
image_info	アプリケーションイメージからヘッダーをダンプする
make_image	バイナリファイルからアプリケーションイメージを作成する
elf2image	ELFファイルからアプリケーションイメージを作成する
read_mac	OTP ROMからMACアドレスを読み取る
chip_id	OTP ROMからチップIDを読み取る
flash_id	SPIフラッシュの製造元とデバイスIDを読み取る
read_flash_status	SPIフラッシュステータスレジスタの読み取り
write_flash_status	SPIフラッシュステータスレジスタの書き込み
read_flash	SPIフラッシュコンテンツの読み取り
verify_flash	フラッシュに対してバイナリBLOBを検証する
erase_flash	SPIフラッシュでチップ消去を実行する
erase_region	フラッシュの領域を消去する
version	esptoolバージョンを印刷する

ざっくりと上記のコマンドがあります。

共通オプション

シリアルポート(-p)

シリアルポートを指定するオプションです。Windowsの場合-p COM1やLinuxやMacの場合-p /dev/ttyUSB0で指定します。指定しない場合、若い番号から自動検索して接続します。複数接続している場合には、間違った方に書き込む可能性があるので、なるべく指定しましょう。

転送速度(-b)

デフォルトの転送速度は115200bpsです。M5StickCだと-b 1500000, -b 750000, -b 500000, -b 250000, -b 115200の5種類が利用できます。高速の場合には転送が失敗する場合があるので、失敗したらもう少し遅い速度で試してください。ボードによっては-b 921600や-b 460800、-b 230400などが利用できます。

主要コマンド解説

チップの情報取得(flash_id)

C:\Temp>esptool.py flash_id
esptool.py v2.7
Found 2 serial ports
Serial port COM3
Connecting....
Detecting chip type... ESP32
Chip is ESP32-PICO-D4 (revision 1)
Features: WiFi, BT, Dual Core, 240MHz, Embedded Flash, VRef calibration in efuse, Coding Scheme None
Crystal is 40MHz
MAC: ??:??:??:??:??:??
Uploading stub...
Running stub...
Stub running...
Manufacturer: c8
Device: 4016
Detected flash size: 4MB
Hard resetting via RTS pin...

接続しているチップの情報を出力します。read_macやchip_idもほぼ同じ情報を出力しますが、このコマンドが一番情報が多いので、他のコマンドを使う必要はありません。

上記はM5StickCなのでESP32-PICO-D4で、4Mフラッシュが搭載されているのが確認できます。最近160MHzの物があるようですし、M5Stack Grayのように4M以上のフラッシュをついているモデルの容量を確認することができます。

フラッシュの読み出し(read_flash)

C:\Temp>esptool.py --port COM3 -b 1500000 read_flash 0x00000 0x400000 image4M.bin
esptool.py v2.7
Serial port COM3
Connecting....
Detecting chip type... ESP32
Chip is ESP32-PICO-D4 (revision 1)
Features: WiFi, BT, Dual Core, 240MHz, Embedded Flash, VRef calibration in efuse, Coding Scheme None
Crystal is 40MHz
MAC: ??:??:??:??:??:??
Uploading stub...
Running stub...
Stub running...
Changing baud rate to 1500000
Changed.
4194304 (100 %)
4194304 (100 %)
Read 4194304 bytes at 0x0 in 49.2 seconds (682.5 kbit/s)...
Hard resetting via RTS pin...

上記は開始アドレス0x00000から4M(0x400000)を読み出して、image4M.binに保存した場合のコマンド例です。

手元環境の場合最高速の-b 1500000だとたまにエラーになるので、-b 750000や安全のために-b 115200で動かしてもよいと思います。

ESP32のメモリマップを参考にすると、先頭アドレスは0x1000以降だけ読み込めばいいのですが、読み込むサイズ計算が面倒になるので先頭から4Mみたいな指定をしたほうが安全だと思います。

C:\Temp>esptool.py --port COM3 -b 115200 read_flash 0 4194304 image4M.bin

上記のように16進数ではなく、10進数でも指定可能です。

フラッシュのベリファイチェック(verify_flash)

C:\Temp>esptool.py --port COM3 -b 1500000 verify_flash --diff yes 0x00000 image4M.bin
esptool.py v2.7
Serial port COM3
Connecting......
Detecting chip type... ESP32
Chip is ESP32-PICO-D4 (revision 1)
Features: WiFi, BT, Dual Core, 240MHz, Embedded Flash, VRef calibration in efuse, Coding Scheme None
Crystal is 40MHz
MAC: ??:??:??:??:??:??
Uploading stub...
Running stub...
Stub running...
Changing baud rate to 1500000
Changed.
Configuring flash size...
Auto-detected Flash size: 4MB
Verifying 0x400000 (4194304) bytes @ 0x00000000 in flash against image4M.bin...
-- verify OK (digest matched)
Hard resetting via RTS pin...

読み込んだファイルが正しいか、ベリファイチェックします。書き込みの場合には自動的にベリファイチェックしているので、利用することは少ないと思います。

ただ、起動するたびにデータを書き換えているプログラムが存在しており、その場合にはベリファイチェックがNGになり、差分が画面に表示されます。何度か実行して同じような結果になる場合には、念の為差分を保存してからあきらめてください。

フラッシュの書き込み(write_flash)

C:\Temp>esptool.py --port COM3 -b 1500000 write_flash 0x00000 image4M.bin
esptool.py v2.7
Serial port COM3
Connecting....
Detecting chip type... ESP32
Chip is ESP32-PICO-D4 (revision 1)
Features: WiFi, BT, Dual Core, 240MHz, Embedded Flash, VRef calibration in efuse, Coding Scheme None
Crystal is 40MHz
MAC: ??:??:??:??:??:??
Uploading stub...
Running stub...
Stub running...
Changing baud rate to 1500000
Changed.
Configuring flash size...
Auto-detected Flash size: 4MB
Compressed 4194304 bytes to 149336...
Wrote 4194304 bytes (149336 compressed) at 0x00000000 in 8.7 seconds (effective 3869.2 kbit/s)...
Hash of data verified.
Leaving...
Hard resetting via RTS pin...

read_flashで保存したファイルを書き込むときのコマンドです。読み込みは速度が115200のときには6分以上かかりますが、書き込みは1分ぐらいで完了しています。

指定したアドレスから、ファイルサイズ分書き込む操作となります。読み出しで利用したアドレスと同じアドレスでないと、おかしなことになるので注意しましょう。

書き込みでは、自動的にベリファイをしていますので、個別にベリファイを実行する必要はありません。

フラッシュの削除(erase_flash)

C:\Temp>esptool.py --port COM3 -b 1500000 erase_flash
esptool.py v2.7
Serial port COM3
Connecting....
Detecting chip type... ESP32
Chip is ESP32-PICO-D4 (revision 1)
Features: WiFi, BT, Dual Core, 240MHz, Embedded Flash, VRef calibration in efuse, Coding Scheme None
Crystal is 40MHz
MAC: ??:??:??:??:??:??
Uploading stub...
Running stub...
Stub running...
Changing baud rate to 1500000
Changed.
Erasing flash (this may take a while)...
Chip erase completed successfully in 1.7s
Hard resetting via RTS pin...

フラッシュの中身を消します。利用していない領域も含めて0xFFで上書きをします。NVSが壊れた場合など、動作が不安定な場合には一度クリアしてからプログラムの転送をしなおすとなおる場合もあると思います。

また、利用していないESP32や、人に譲るESP32などはクリアしておかないと、中身のデータや、NVS領域などのWi-Fiアクセスポイント情報などをかんたんに抜き出すことができるので、注意してください。

まとめ

ESP32はかんたんにプログラムの書き込みや、読み込みが可能です。反面フラッシュの中身をUSB接続で抜き出すことが可能ですので、気をつけて扱いましょう。

暗号化することで、抜き出しにくくすることも可能ですが、暗号化はヒューズ操作になるので、3回までしか実施できないのとNVS領域が保護されていないので注意が必要です。