{{tag>[python esp32 firmware serial flashing embedded]}}

====== esptool ======
Espressif 칩의 serial bootloader와 통신해 flash read/write, erase, image 변환을 수행하는 Python 기반 CLI 도구.
ESP32/ESP8266 계열 펌웨어 플래싱과 flash 점검에 자주 사용된다.

===== Summary =====
  * ''esptool''은 Python 패키지이면서 동시에 standalone CLI로 사용된다.
  * 이 페이지는 로컬 바이너리가 없는 상태에서 2026-06-28 기준 Espressif 공식 문서를 확인해 작성했다.
  * SDK/framework 안에 포함된 ''esptool''은 framework가 기대하는 major version을 따르는 편이 안전하다.

===== Install =====
<note tip>
공식 문서는 최신 ''esptool'' 사용 시 Python 3.10 이상을 요구한다. Python 3.7~3.9는 ''v4.x'', Python 2.7/3.4~3.6은 ''v3.3.*'' 계열을 사용하라고 안내한다.
</note>

<code bash>
# 기본 설치
pip install esptool

# pip 직접 실행이 안 될 때
python -m pip install esptool
pip3 install esptool

# 가상환경 사용
python -m venv esptoolenv
source esptoolenv/bin/activate
pip install esptool

# 업그레이드
pip install --upgrade esptool

# 모듈 형태 실행
python -m esptool version
</code>

  * 공식 문서는 system-wide install보다 virtual environment 사용을 권장한다.
  * Python 없이 쓰고 싶다면 GitHub Releases의 pre-built binary도 사용할 수 있지만, 지원 OS/아키텍처와 제약을 먼저 확인한다.
  * framework 내부 도구라면 framework 문서에 맞춰 업그레이드하고, 임의 upgrade가 필요하면 major version 호환성을 먼저 확인한다.

===== Usage =====
<code bash>
esptool [OPTIONS] COMMAND [ARGS]...
</code>

  * ''<color #c3c3c3>**esptool**</color> <color #22b14c>[OPTIONS]</color> <color #ff7f27>COMMAND</color> <color #7092be>[ARGS]...</color>''
  * ''<color #c3c3c3>**esptool**</color> <color #22b14c>**--chip**</color> <color #7092be>ESP32</color> <color #22b14c>**--port**</color> <color #7092be>/dev/ttyUSB0</color> <color #22b14c>**--baud**</color> <color #7092be>460800</color> <color #ff7f27>write-flash</color> <color #7092be>OFFSET FILE...</color>''
  * ''<color #c3c3c3>**esptool**</color> <color #ff7f27>flash-id</color>'': SPI flash ID 읽기
  * ''<color #c3c3c3>**esptool**</color> <color #ff7f27>read-mac</color>'': built-in MAC address 읽기
  * ''<color #c3c3c3>**esptool**</color> <color #ff7f27>write-flash</color> <color #7092be>OFFSET FILE...</color>'': flash에 binary 기록
  * ''<color #c3c3c3>**esptool**</color> <color #ff7f27>read-flash</color> <color #7092be>ADDRESS SIZE OUTFILE</color>'': flash 내용 덤프
  * ''<color #c3c3c3>**esptool**</color> <color #ff7f27>erase-flash</color>'': flash 전체 erase
  * ''<color #c3c3c3>**esptool**</color> <color #ff7f27>erase-region</color> <color #7092be>ADDRESS SIZE</color>'': flash 일부 영역 erase
  * ''<color #c3c3c3>**esptool**</color> <color #ff7f27>image-info</color> <color #7092be>FILE.bin</color>'': image header / segment 정보 확인
  * ''<color #c3c3c3>**esptool**</color> <color #ff7f27>merge-bin</color> <color #22b14c>**-o**</color> <color #7092be>OUTFILE</color> <color #7092be>OFFSET FILE...</color>'': 여러 image 병합
  * ''<color #c3c3c3>**esptool**</color> <color #ff7f27>elf2image</color> <color #7092be>APP.elf</color>'': ELF를 flashable binary로 변환

===== Options =====
  * ''<color #22b14c>**--chip**</color> <color #7092be>CHIP</color>'': 대상 칩 지정. 예: ''ESP32'', ''ESP32-S3''
  * ''<color #22b14c>**--port**</color> <color #7092be>PORT</color>'': serial port 지정. 예: ''/dev/ttyUSB0'', ''COM5''
  * ''<color #22b14c>**--baud**</color> <color #7092be>RATE</color>'': serial baudrate 지정
  * ''<color #22b14c>**--before**</color> <color #7092be>default-reset|no-reset|no-reset-no-sync</color>'': 작업 전 reset / sync 동작 제어
  * ''<color #22b14c>**--after**</color> <color #7092be>hard-reset|no-reset|no-reset-stub</color>'': 작업 후 reset 동작 제어
  * ''<color #22b14c>**--no-stub**</color>'': stub loader 업로드 비활성화
  * ''<color #22b14c>**--port-filter**</color> <color #7092be>TYPE=VALUE</color>'': VID/PID/name/serial 기준 포트 autodetection 필터링

===== Examples =====
<code bash>
# 설치 확인
esptool version
python -m esptool version

# flash ID 확인
esptool --port /dev/ttyUSB0 flash-id

# MAC 주소 읽기
esptool --chip ESP32 --port /dev/ttyUSB0 read-mac

# 앱/부트로더/파티션 테이블 플래시
esptool --chip ESP32 --port /dev/ttyUSB0 --baud 460800 \
  write-flash 0x1000 bootloader.bin 0x8000 partition-table.bin 0x10000 app.bin

# flash 전체 덤프
esptool --port /dev/ttyUSB0 read-flash 0 0x200000 flash.bin

# flash 전체 erase
esptool --port /dev/ttyUSB0 erase-flash

# 이미지 정보 확인
esptool image-info app.bin

# 여러 바이너리 병합
esptool --chip ESP32 merge-bin -o merged-flash.bin \
  0x1000 bootloader.bin 0x8000 partition-table.bin 0x10000 app.bin
</code>

===== Troubleshooting =====
  * ''esptool: command not found'': virtual environment 활성화 여부 또는 ''python -m esptool'' 형태 실행을 먼저 확인
  * 포트를 못 찾으면 ''--port'' 지정, ''lsusb'', ''dmesg''로 USB-serial 장치 이름 확인
  * auto reset이 실패하면 ''--before no-reset'' 또는 boot 버튼을 사용한 수동 bootloader 진입이 필요할 수 있다
  * framework 번들 버전을 무시하고 최신판으로 올리면 toolchain 호환성이 깨질 수 있다
  * ''erase-flash'' 는 NVS/설정/앱을 모두 지울 수 있으므로 destructive 작업으로 취급한다

===== Compatibility =====
  * 이 작업 환경에는 ''esptool'' 바이너리가 없어 로컬 ''--help'' 원문은 캡처하지 못했다.
  * 공식 문서 기준 최신판은 Python 3.10+를 요구하며, 구형 Python은 별도 major/minor 계열 사용이 필요하다.
  * pre-built binary는 편하지만 Python module import 용도로는 쓸 수 없다.

===== Help =====
++++ esptool --help |
<code text>
Local `esptool` binary was not available in this workspace on 2026-06-28.

Verified from official Espressif docs:
  * installation via `pip install esptool`
  * `python -m esptool` module execution
  * commands: flash-id, read-mac, write-flash, read-flash, erase-flash, erase-region,
    image-info, merge-bin, elf2image
  * global options: --chip, --port, --baud, --before, --after, --no-stub, --port-filter
</code>
++++

===== See Also =====
  * [[python:pip]]
  * [[python:venv]]
  * [[python:uv]]
  * [[lsusb]]
  * [[dmesg]]

===== History =====
  * codex:: 2026-06-28 Created esptool page with official installation guidance, flashing examples, and version compatibility notes.