firmware-flasher/README.md

DB720 펌웨어 적재 키트 (PowerShell)

ESP32-P4 기반 DB720 보드에 secure_release 서명 펌웨어를 PowerShell로 적재하는 독립 키트입니다. 이 폴더 하나만 있으면 빌드 환경 없이도 적재할 수 있습니다(esptool만 있으면 됨).

• 펌웨어: DIBD720Ue_08B_08R040C (8단40열 = 640×128, 256색/08B) — db250513 키로 V2 서명한 secure_release 빌드
• 빌드일: 2026-06-22 (버전 3.7.2)

DB720은 secure_release 단일입니다. 적재·빌드·OTA에 쓰는 펌웨어는 db250513 키로 서명한 바이너리뿐입니다. 서명이 없는 일반 빌드(예: V3.7.1 같은 공개 릴리즈 바이너리)는 secure_release 부트로더가 서명 검증에서 거부해 부팅되지 않습니다. 이 키트의 firmware\ 폴더에는 db250513 서명본만 두세요(비서명 bin 금지).

---

0. 두 경우 — 어느 스크립트를 쓰나

보드 상태	스크립트	무엇을 쓰나	위험
일상적 앱 교체 (서명 부트로더가 이미 정상)	flash_app.ps1	부트로더 제외 4종(파티션/ota_data/앱/www)	없음 — 부트로더 안 건드려 brick 불가
부트로더가 비었을 때 (flash 통째 지워짐 / 0x2000 빔 / 부팅 안 됨)	flash_full.ps1	부트로더+파티션+ota_data+앱+www 5종 전부	⚠ 부트로더(0x2000)에 손댐 — 아래 §1 경고

일상 적재는 flash_app.ps1(경우 B)만 쓰세요. 가능하면 -AppOnly로 앱만 올립니다. flash_full.ps1(경우 A)은 부트로더가 실제로 비어 부팅이 안 될 때만 쓰는 복구 전용입니다.

---

1. ★★★ full flash 경고 (경우 A 전용) ★★★

flash_full.ps1은 부트로더(0x2000)까지 다시 씁니다.

• 이미 secure_release로 구워진 보드 (예: 회사 .230) → 부트로더가 이미 영구 고정돼 있으므로 같은 서명 부트로더를 다시 쓸 이유가 없습니다. 일상 적재에 경우 A를 쓰지 마세요 — flash_app.ps1이면 충분합니다.
• eFuse가 아직 안 구워진 보드 → secure_release 서명본을 full flash하면 첫 부팅에 secure boot eFuse가 영구로 구워집니다(되돌릴 수 없음).
  • eFuse는 비가역입니다. 한 번 구워지면 그 보드는 영원히 이 서명 체계에만 묶입니다(DB400 V1에서 ABS_DONE_0 잠김으로 보드가 brick된 실증이 있습니다).
  • db250513 키를 분실하면 그 보드는 OTA로 더 이상 펌웨어를 못 올립니다(영구). 키 백업은 필수입니다.

flash_app.ps1(경우 B)은 부트로더를 안 건드리므로 이 위험이 없습니다.

---

2. 사전 준비

1. USB-JTAG 케이블로 PC ↔ DB720 연결 (보드의 USB-JTAG 포트).
2. esptool이 있는 파이썬. 두 스크립트는 기본으로 ESP-IDF 파이썬을 씁니다: C:\Users\jyheo\.espressif\python_env\idf5.5_py3.13_env\Scripts\python.exe
   • 환경이 다르면 flash_full.ps1 / flash_app.ps1 상단의 $Python 한 줄만 고치세요.
   • 또는 pip install esptool 한 파이썬이 PATH에 있으면 자동 폴백됩니다.
   • esptool은 v4.11 이상이어야 합니다(낮으면 적재 중 멈춤).
3. COM 포트 확인 — 적재 포트(USB-JTAG)는 번호가 바뀔 수 있습니다:

   .\list_ports.ps1
   

   • USB 직렬 장치(COMx) 또는 VID 303A:1001 = 적재 포트 (-Port COMx)
   • Silicon Labs CP210x (COMx) = COM2 자리(디버그·문구 전송, 적재 중 열지 말 것)

---

3. 적재 방법

PowerShell을 이 폴더에서 열고:

경우 B — 서명 부트로더 있음 (일상 적재, 권장)

# 앱만 최소로(앱 0x20000 + otadata erase) — 권장
.\flash_app.ps1 -Port COM4 -AppOnly

# 표준(파티션+ota_data+앱+www, 부트로더 제외)
.\flash_app.ps1 -Port COM4

경우 A — 부트로더 비었음 (전체 복구 전용, §1 경고 확인)

.\flash_full.ps1 -Port COM4

실행 정책 때문에 막히면(이 PC에 처음): Set-ExecutionPolicy -Scope CurrentUser RemoteSigned 한 번. -Port를 생략하면 기본 COM4로 시도합니다.

---

3a. 앱이 여러 개일 때 — 골라서 올리기

firmware\ 폴더에 앱 .bin이 여러 개 있을 수 있습니다. 예를 들어 지금은 두 개가 들어 있습니다.

앱 파일	화면 크기	상태
DIBD720Te_08C_04R020C.bin	320×64 (4단20열, 8색)	부팅 검증됨 — 안전, 일상·복구용 권장
DIBD720Ue_08B_08R040C.bin	640×128 (8단40열, 256색)	부팅 미검증 — 테스트용(SRAM 한도 의심)

부트로더·파티션·ota_data·www_fs는 앱이 아니라 보조 파일이라 선택 대상에서 빠집니다. 앱 후보는 그 4개를 뺀 나머지 .bin입니다.

1단계 — 어떤 앱이 있는지 본다

앱을 지정하지 않고 그냥 실행하면, 스크립트가 임의로 고르지 않고 앱 목록을 보여준 뒤 멈춥니다.

.\flash_app.ps1 -Port COM4

출력 예:

여러 앱이 있습니다 — -App 으로 하나를 지정하세요:
   DIBD720Te_08C_04R020C.bin
   DIBD720Ue_08B_08R040C.bin
예: .\flash_app.ps1 -Port COM4 -App DIBD720Te_08C_04R020C.bin

2단계 — 올릴 앱을 -App으로 지정한다

# 320×64(검증된 것)을 앱만 최소로 올리기 — 권장
.\flash_app.ps1 -Port COM4 -App DIBD720Te_08C_04R020C.bin -AppOnly

# 640×128(테스트)을 표준으로 올리기
.\flash_app.ps1 -Port COM4 -App DIBD720Ue_08B_08R040C.bin

• -App 값은 firmware\ 안의 파일명만 적습니다(경로 없이).
• 앱이 하나뿐이면 -App을 생략해도 그것이 자동 선택됩니다(여러 개일 때만 지정 필수).
• flash_full.ps1(경우 A)도 똑같이 -App으로 고릅니다.

---

3b. 전체 굽기 (full flash) — 5영역 전부

부트로더(0x2000)까지 포함해 5개 영역을 전부 쓰는 절차입니다. flash가 통째로 비었거나 부트로더가 깨져 부팅이 안 될 때 보드를 처음부터 살립니다.

⚠ 먼저 §1 경고를 읽으세요. 전체 굽기는 부트로더를 건드리므로, eFuse가 안 구워진 보드에서는 첫 부팅에 secure boot eFuse가 영구로 구워집니다(되돌릴 수 없음). 일상 적재에는 쓰지 말고 §3(앱 적재)을 쓰세요. 전체 굽기는 부트로더가 실제로 비어 부팅이 안 될 때만 씁니다.

무엇을 쓰나 (영역 5개)

offset	파일	크기	서명
0x2000	firmware\bootloader.bin	45KB	db250513 서명
0x10000	firmware\partition-table.bin	3KB	비서명(정상)
0x11000	firmware\ota_data_initial.bin	8KB	비서명(정상)
0x20000	선택한 앱 (-App)	1.2~1.7MB	db250513 서명
0x420000	firmware\www_fs.bin	512KB	비서명(정상)

방법 1 — 스크립트 (권장)

# 앱이 하나면 그대로
.\flash_full.ps1 -Port COM4

# 앱이 여러 개면 -App 으로 지정
.\flash_full.ps1 -Port COM4 -App DIBD720Te_08C_04R020C.bin

스크립트가 5영역을 하나씩 개별 호출로 쓴 뒤(SDM 다중영역 한 번에 쓰면 중간 실패) hard_reset 합니다.

방법 2 — 수동 esptool (스크립트가 안 될 때, 한 줄씩)

COM4는 적재 포트로 바꾸고(.\list_ports.ps1), --flash_size 16MB는 반드시 붙입니다(이게 빠지면 SDM에서 4MB로 오인해 0x420000(www_fs)을 못 써 부팅 루프가 납니다 — 2026-06-22 실증).

$P = "C:\Users\jyheo\.espressif\python_env\idf5.5_py3.13_env\Scripts\python.exe"
$C = "--chip","esp32p4","-p","COM4","-b","115200","--before","default_reset","--after","no_reset","--connect-attempts","30","--no-stub"
$W = "write_flash","--flash_mode","dio","--flash_size","16MB","--flash_freq","80m"
& $P -m esptool @C @W 0x2000   firmware\bootloader.bin
& $P -m esptool @C @W 0x10000  firmware\partition-table.bin
& $P -m esptool @C @W 0x11000  firmware\ota_data_initial.bin
& $P -m esptool @C @W 0x20000  firmware\DIBD720Te_08C_04R020C.bin   # 올릴 앱
& $P -m esptool @C @W 0x420000 firmware\www_fs.bin
# SDM 탈출(정상 부팅)
& $P -c "from esptool.targets.esp32p4 import ESP32P4ROM; r=ESP32P4ROM('COM4'); r.connect('default_reset'); r.hard_reset()"

★ secure 보드는 부트로더(0x2000)·전체 erase write를 거부할 수 있습니다 — 0105 format invalid 같은 거부는 부트로더가 이미 같은 키로 구워져 있다는 뜻(정상)이라, 그 경우 0x2000은 건너뛰고 나머지 4영역만 쓰면 됩니다(= §3 앱 적재로 충분). ★ esptool/USB 리셋은 이 보드에서 다운로드 모드로 떨어지는 경향이 있어, 최종 부팅은 USB-JTAG 케이블을 뽑고 전원 사이클해야 확실합니다.

---

4. 적재 메커니즘 (왜 이렇게 하나)

• eco2 secure download mode(SDM) 레시피: --no-stub + 115200 baud + --before default_reset --after no_reset. secure 보드는 esptool stub를 못 올리므로 --no-stub, 다운로드 모드 안정 위해 115200을 씁니다.
• 영역은 하나씩 개별 esptool 호출로 씁니다. SDM에서 여러 영역을 한 번에 쓰면 중간에 "Failed to enter Flash download mode"로 실패합니다(2026-06-22 실증 — www_fs가 빈 채 남아 부팅 루프).
• 부트로더(0x2000)는 경우 A에서만 씁니다. secure 보드는 부트로더/전체 erase를 거부하는 게 정상입니다.
• 적재 후 --after no_reset로 남은 다운로드 모드를 hard_reset(esptool ROM 객체)으로 빠져나와 정상 부팅합니다.
• 오프셋 정본: 부트로더 0x2000 / 파티션 0x10000 / ota_data 0x11000 / 앱 0x20000 / www_fs 0x420000. flash: dio / keep / 80m.

---

5. 적재 후 확인

다음 중 하나로 새 펌웨어가 실제로 올라가 부팅됐는지 확인합니다.

• COM2(디버그 콘솔, CP210x)에서 ![0081!] 을 115200bps로 보내 버전 배너가 오면 정상(적재 포트 COM4 아님).
• 부트로그에 RSA-PSS verified(secure_release 서명 검증 통과)와 정상 부팅 메시지가 보이면 정상.
• LAN으로 받은 빌드 시각을 키트의 빌드일(이 README 상단)과 대조 — 날짜가 맞으면 새 펌웨어가 적용된 것입니다.

적재 포트(COM4/USB-JTAG)는 측정·표출 중 열지 마세요 — DTR/RTS가 보드를 리셋해 화면이 날아갑니다.

---

6. 안 될 때

증상	조치
포트 연결 실패 / could not open port	.\list_ports.ps1로 실제 USB-JTAG COM 번호 확인 후 -Port COMx. 다른 프로그램이 그 포트를 잡고 있으면 닫기
~0.72MB에서 멈춤(hang)	esptool 버전이 낮음(<4.11). pip install -U esptool (이 키트는 v4.11+ 전제)
적재는 됐는데 부팅 안 됨(검정/무응답)	먼저 flash_app.ps1 -AppOnly로 otadata를 지워 ota_0으로 폴백 시도. 그래도 안 되고 부트로더가 빈 것 같으면 경우 A flash_full.ps1
부트로그에 서명 검증 실패	비서명(서명 없는) bin을 올렸을 때 발생. firmware\에 db250513 서명본만 있는지 확인(V3.7.1 같은 일반 릴리즈 bin은 secure_release에서 부팅 거부)
secure download / 권한 오류 반복	USB 케이블 재연결 후 재시도(스크립트가 connect 30회 재시도)

---

7. 포함 파일

DB720_Flash\
├─ README.md                  ← 이 문서
├─ list_ports.ps1             ← COM 포트 확인
├─ flash_app.ps1              ← 경우 B: 서명 부트로더 있을 때(brick-safe, 권장)
├─ flash_full.ps1             ← 경우 A: 부트로더 비었을 때(full, §1 경고)
└─ firmware\
   ├─ bootloader.bin            (0x2000,  45KB)  ← 경우 A에서만 사용 (db250513 서명)
   ├─ partition-table.bin       (0x10000,  3KB)  ← 비서명(설계상 정상)
   ├─ ota_data_initial.bin      (0x11000,  8KB)  ← 비서명(설계상 정상)
   ├─ DIBD720Te_08C_04R020C.bin (0x20000, 1.2MB) ← 앱① 320×64, 8색 (db250513 서명, 부팅 검증됨·권장)
   ├─ DIBD720Ue_08B_08R040C.bin (0x20000, 1.7MB) ← 앱② 640×128, 256색 (db250513 서명, 테스트용·미검증)
   └─ www_fs.bin                (0x420000, 512KB) ← 비서명(설계상 정상)

앱이 둘 다 0x20000(ota_0)에 올라가는 같은 자리라, 한 번에 하나만 적재됩니다. 어느 것을 올릴지는 §3a의 -App으로 고릅니다. 서명 대상(앱·부트로더)은 모두 db250513 서명본이고, 파티션·ota_data·www_fs는 secure boot v2가 서명하지 않는 정상 파일입니다.