e37a03c7ad
clone 시 firmware/ 엔 flash.json 만 있고 서명 .bin 은 제외돼 있어, 어디에 어떤 파일을 넣는지(자동 탐색 firmware/ 또는 [폴더…]) 명확히 안내. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
134 lines
6.6 KiB
Markdown
134 lines
6.6 KiB
Markdown
# firmware-flasher
|
|
|
|
ESP32 계열 컨트롤러(DB720·DB402S·DB400S 등)에 펌웨어를 굽는 **Windows GUI 도구**.
|
|
설치·파이썬 없이 도는 단일 실행본으로 배포되고, 모델별 설정은 `flash.json` 하나로 갈아끼운다.
|
|
|
|
> 시작은 DB720(ESP32-P4) 전용 PowerShell 키트였고, 지금은 여러 모델을 GUI로 다룬다.
|
|
> 기존 `.ps1` 스크립트도 그대로 남아 있다([아래](#powershell-키트-기존)).
|
|
|
|
## 특징
|
|
|
|
- **멀티모델** — 칩·offset·baud·쓰기방식이 다른 모델을 프로파일로 분리. 드롭다운에서 고르거나 폴더의 `flash.json`으로 자동.
|
|
- **포트 자동 감지** — USB-JTAG(`303A:1001`)를 꽂는 즉시 잡아 자동 선택. 리셋으로 COM 번호가 바뀌어 생기는 **유령 포트**를 열기-probe로 걸러 살아있는 포트로 자동 전환.
|
|
- **esptool 동봉** — esptool v5 단독 실행본을 같이 묶어, 받는 PC에 파이썬이 없어도 동작.
|
|
- **안전장치** — "앱만"이 기본(부트로더 안 건드림). "전체"(부트로더 재작성)는 eFuse 영구 굽힘 경고 + 확인 체크.
|
|
|
|
## 빠른 시작 (사용자)
|
|
|
|
1. 배포 zip을 풀고 `FirmwareFlasher.exe` 실행.
|
|
2. **펌웨어 폴더** 선택 → **앱**·**모델** 확인(폴더에 `flash.json` 있으면 자동).
|
|
3. **포트**는 자동으로 잡힘(안 잡히면 `↻ 새로고침`).
|
|
4. **모드** 고르고 **플래시 시작**.
|
|
- 평소: **앱만**(가장 안전)
|
|
- 새 보드 첫 굽기/복구: **전체** (eFuse 주의)
|
|
5. 끝나면 보드 전원 재인가.
|
|
|
|
## 펌웨어 파일 넣는 곳
|
|
|
|
서명된 펌웨어 `.bin`은 보안상 repo·배포본에 **들어 있지 않다**(`.gitignore`로 제외). **직접 넣어야 한다.**
|
|
|
|
모델 폴더 하나에 아래 파일을 모아 둔다:
|
|
|
|
```
|
|
<펌웨어 폴더>/
|
|
├─ flash.json ← 모델 설정 (없으면 앱 "모델" 드롭다운에서 선택)
|
|
├─ bootloader.bin
|
|
├─ partition-table.bin
|
|
├─ ota_data_initial.bin
|
|
├─ DIBD*.bin ← 앱 (예: DIBD720Te_…, DIBD402S_…)
|
|
└─ www_fs.bin ← DB720 만
|
|
```
|
|
|
|
- 앱은 **exe 옆 `firmware/` 폴더를 자동으로** 찾는다 — 거기에 넣으면 바로 잡힌다.
|
|
- 다른 위치에 두려면 앱에서 **[폴더…]** 로 그 폴더를 고른다.
|
|
- **"앱만" 모드**는 앱 `DIBD*.bin` 하나만 있으면 된다(부트로더·파티션 등 불필요).
|
|
|
|
## 지원 모델
|
|
|
|
| 모델 | 칩 | 부트로더 offset | 포트·방식 |
|
|
|---|---|---|---|
|
|
| DB720 | `esp32p4` | `0x2000` | USB-JTAG · no-stub · 115200 · 영역별 |
|
|
| DB402S | `esp32s3` | `0x0000` | UART(TTL) · stub · 921600 · 한 번에 |
|
|
| DB400S / DB400Q / DB300eM | `esp32` | `0x1000` | UART(TTL) · stub · 921600 · 한 번에 |
|
|
|
|
공통 offset: 파티션 `0x10000` · ota_data `0x11000` · 앱 `0x20000` · (DB720만) www_fs `0x420000`.
|
|
|
|
## 모델 추가 — `flash.json`
|
|
|
|
펌웨어 폴더에 `flash.json`을 넣으면 앱이 **그 폴더만 보고** 그대로 굽는다. `profiles/`에 모델별 템플릿이 있다.
|
|
|
|
```json
|
|
{
|
|
"name": "DB402S (ESP32-S3)",
|
|
"chip": "esp32s3",
|
|
"baud": 921600,
|
|
"noStub": false,
|
|
"perRegion": false,
|
|
"regions": [
|
|
{ "file": "bootloader.bin", "offset": "0x0000", "kind": "bootloader" },
|
|
{ "file": "partition-table.bin", "offset": "0x10000", "kind": "support" },
|
|
{ "file": "ota_data_initial.bin", "offset": "0x11000", "kind": "support" },
|
|
{ "app": true, "offset": "0x20000" }
|
|
],
|
|
"consolePortHint": "10C4:EA60",
|
|
"downloadModeHint": "TTL(COM2) 연결, SW1 누른 채 SW2 눌렀다 떼고 SW1 떼면 다운로드 모드"
|
|
}
|
|
```
|
|
|
|
주요 키: `chip` / `baud` / `noStub`(스텁 여부) / `perRegion`(영역별 vs 한 번에) / `flashSize`·`flashMode`·`flashFreq`(생략 시 자동) / `flashPortHint`(자동선택 우선 VID:PID) / `consolePortHint` / `appOnlyErasesOtadata`.
|
|
|
|
> `flash.json`이 없어도 됨 — DB720·DB402S·DB400S·DB400Q·DB300eM 설정은 앱에 내장돼 있어 "모델" 드롭다운에서 골라도 동작.
|
|
|
|
## 포트 — 유령 COM 주의
|
|
|
|
ESP32 USB-JTAG는 보드가 리셋될 때마다 USB를 다시 잡아 **COM 번호가 올라간다**(예: COM17→COM18). 옛 번호는 목록엔 "정상"으로 남지만 열 수 없다(유령 포트). 앱은 **최신 번호 우선 + 열기-probe**로 살아있는 포트를 자동으로 쓴다. 그래도 안 되면 케이블을 다시 꽂고 `↻ 새로고침`.
|
|
|
|
> 적재 포트는 측정/표출 중에는 열지 말 것 — DTR/RTS가 보드를 리셋한다.
|
|
|
|
## secure 보드 / eFuse
|
|
|
|
서명(secure boot) 보드는 부트로더(`0x8000` 아래) 쓰기를 거부하는 게 **정상**이다. 그땐 **표준/앱만**으로(부트로더 건너뜀). 꼭 부트로더를 다시 써야 하면 `--force`. eFuse는 한 번 구워지면 **되돌릴 수 없으니** 서명 키 백업 필수.
|
|
|
|
## 빌드 (개발)
|
|
|
|
요구: **.NET 9 SDK** (Windows), WPF(`net9.0-windows`).
|
|
|
|
```powershell
|
|
dotnet build FirmwareFlasher\FirmwareFlasher.csproj
|
|
dotnet run --project FirmwareFlasher\FirmwareFlasher.csproj
|
|
```
|
|
|
|
## 배포 (단일 실행본)
|
|
|
|
```powershell
|
|
dotnet publish FirmwareFlasher\FirmwareFlasher.csproj -c Release -r win-x64 `
|
|
--self-contained true -p:PublishSingleFile=true -p:IncludeNativeLibrariesForSelfExtract=true
|
|
```
|
|
|
|
> ⚠ 단일 파일 publish는 동봉 `esptool.exe`를 exe 안으로 삼킨다. publish 후 `tools\esptool\`와 `firmware\`를 **exe 옆에 따로 복사**해 배포 폴더를 만든다(그래야 앱이 esptool을 찾음). 받는 사람은 폴더 통째로 받아 `FirmwareFlasher.exe` 실행 — 설치 불필요.
|
|
|
|
## 폴더 구조
|
|
|
|
```
|
|
firmware-flasher/
|
|
├─ FirmwareFlasher/ WPF 앱 소스 (+ tools/esptool/ 동봉 엔진)
|
|
├─ firmware/ 펌웨어 폴더 (flash.json 포함; 서명 .bin 은 git 제외)
|
|
├─ profiles/ 모델별 flash.json 템플릿 (DB720·DB402S·DB400S)
|
|
├─ flash_app.ps1 / flash_full.ps1 / list_ports.ps1 기존 PowerShell 키트
|
|
└─ README.md
|
|
```
|
|
|
|
> `firmware/*.bin`(서명 실펌웨어)와 `dist/`(배포본), 빌드 출력은 git에 올리지 않는다(`.gitignore`). 배포본 zip은 Gitea **Releases**로.
|
|
|
|
## PowerShell 키트 (기존)
|
|
|
|
GUI 없이 명령으로 굽는 원래 방식(여전히 사용 가능). DB720 기준:
|
|
|
|
```powershell
|
|
.\list_ports.ps1 # 적재 포트(303A:1001) 확인
|
|
.\flash_app.ps1 -Port COM4 -AppOnly # 앱만 (brick-safe, 권장)
|
|
.\flash_full.ps1 -Port COM4 # 전체 (부트로더 포함, eFuse 주의)
|
|
```
|
|
|
|
> 일상 적재는 `flash_app.ps1`(앱만)으로 충분하다. `flash_full.ps1`은 부트로더가 비어 부팅이 안 될 때만 쓰는 복구 전용. GUI 앱은 동봉 esptool(v5)로 같은 일을 더 안전하게 한다.
|