From 3a662affb615d493bd6155499664292fdd0ba1ab Mon Sep 17 00:00:00 2001 From: root Date: Tue, 19 May 2026 05:26:53 +0900 Subject: [PATCH] feat: support merged.bin, boot_app0, upload mode toggle + flash guide MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - server.js: add boot_app0 field at 0xe000, raise file limit 8→32 MB - index.html: add 병합/분리 mode toggle, boot_app0 drop zone, numbered split zones - app.js: dynamic mode logic, remove hardcoded flashAddress 0x10000, server now auto-selects 0x0 (merged) or 0x10000 (split) - flash-guide.html: step-by-step Korean flash guide with file table, method A/B walkthrough, flash_args explanation, troubleshooting Co-Authored-By: Claude Sonnet 4.6 --- backend/server.js | 21 +- flash-guide.html | 717 ++++++++++++++++++++++++++++++++++++++++++++ frontend/index.html | 83 +++-- frontend/js/app.js | 68 ++++- 4 files changed, 842 insertions(+), 47 deletions(-) create mode 100644 flash-guide.html diff --git a/backend/server.js b/backend/server.js index 885def1..fec45ca 100644 --- a/backend/server.js +++ b/backend/server.js @@ -52,7 +52,7 @@ const upload = multer({ cb(new Error('.bin 파일만 업로드 가능합니다')); } }, - limits: { fileSize: 8 * 1024 * 1024 }, // 8 MB + limits: { fileSize: 32 * 1024 * 1024 }, // 32 MB }); // ── 라우트 ────────────────────────────────────────────────────────────────── @@ -68,13 +68,14 @@ app.get('/api/firmware', (_req, res) => { }); // 펌웨어 업로드 -// 지원 필드: firmware(필수), bootloader(선택), partitions(선택) +// 지원 필드: firmware(필수), bootloader(선택), partitions(선택), boot_app0(선택) app.post( '/api/firmware/upload', upload.fields([ - { name: 'firmware', maxCount: 1 }, - { name: 'bootloader', maxCount: 1 }, - { name: 'partitions', maxCount: 1 }, + { name: 'firmware', maxCount: 1 }, + { name: 'bootloader', maxCount: 1 }, + { name: 'partitions', maxCount: 1 }, + { name: 'boot_app0', maxCount: 1 }, ]), (req, res) => { try { @@ -105,7 +106,15 @@ app.post( }); } - // 부트로더가 따로 없으면 0x0, 있으면 0x10000 + if (files.boot_app0) { + parts.push({ + file: files.boot_app0[0].filename, + offset: '0xe000', + label: 'Boot App0', + }); + } + + // 부트로더가 따로 없으면(병합 바이너리) 0x0, 있으면 0x10000 const appOffset = flashAddress || (files.bootloader ? '0x10000' : '0x0000'); diff --git a/flash-guide.html b/flash-guide.html new file mode 100644 index 0000000..4f66755 --- /dev/null +++ b/flash-guide.html @@ -0,0 +1,717 @@ + + + + + + ESP32 Web Flasher — 플래시 사용 설명서 + + + + +
+

⚡ ESP32 Web Flasher 사용 설명서

+

Arduino IDE 빌드 파일을 웹 브라우저에서 ESP32에 플래시하는 방법

+
+ +
+ + +
+

1 Arduino IDE 빌드 파일 설명

+ +

+ Sketch → Export Compiled Binary 클릭 후 빌드 폴더 + (build/esp32.esp32.esp32s3/ 등)에 생성되는 파일들입니다. +

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
파일명크기 (예시)플래시 주소용도사용 여부
*.ino.merged.bin~16 MB0x0000전체 병합 바이너리 (모든 파일 합본)✓ 권장
*.ino.bootloader.bin~20 KB0x0000부트로더분리 방식 시
*.ino.partitions.bin~3 KB0x8000파티션 테이블분리 방식 시
boot_app0.bin~8 KB0xe000OTA 부트 선택자분리 방식 시
*.ino.bin~1 MB0x10000애플리케이션 (실제 코드)분리 방식 시
*.ino.elf~15 MB—디버그 심볼 (GDB용)불필요
*.ino.map~17 MB—메모리 맵 (분석용)불필요
flash_args~200 B—esptool 플래시 인수 (참고용)참고용
+ +
+ 💡 +
+ flash_args 파일을 열면 어떤 파일이 어느 주소에 들어가는지 정확히 기록되어 있습니다. + 
--flash-mode dio --flash-freq 80m --flash-size 16MB
+0x0     bootloader.bin
+0x8000  partitions.bin
+0xe000  boot_app0.bin
+0x10000 app.bin
+
+
+
+ + +
+

2 업로드 방식 선택

+ +
+
+
방법 A — 병합 바이너리 (권장)
+

+ 모든 파티션이 하나로 합쳐진 *.merged.bin 파일 하나만 업로드합니다. + 가장 간단하고 오류 가능성이 낮습니다. +

+
+
✓ 장점
+
    +
  • 파일 하나로 완전한 플래시
    • +
  • 주소 설정 불필요
    • +
  • 파일 누락 실수 없음
    • +
+
+
+
⚠ 주의
+
    +
  • 파일 크기가 클 수 있음 (Flash 크기 = 파일 크기)
    • +
+
+
+ +
+
방법 B — 분리 파일
+

+ bootloader, partitions, boot_app0, app을 각각 업로드합니다. + 파일 크기가 작고 부분 업데이트가 가능합니다. +

+
+
✓ 장점
+
    +
  • 앱만 따로 업데이트 가능
    • +
  • 파일 크기 작음 (앱만 ~1 MB)
    • +
+
+
+
⚠ 주의
+
    +
  • 4개 파일을 정확히 맞춰야 함
    • +
  • 파일 누락 시 부팅 실패
    • +
+
+
+
+
+ + +
+

3 방법 A — 병합 바이너리 플래시 (권장)

+ +
+ 병합 바이너리 모드 +
+
+ +
+
1
+
+
브라우저 준비
+
+ Chrome 89+ 또는 Edge 89+를 사용하세요. +
Web Flasher 주소: http://localhost:3100 (Docker와 같은 PC인 경우) +
Firefox / Safari는 Web Serial API 미지원으로 플래시 불가 +
+
+
+ +
+
2
+
+
ESP32 보드 USB 연결
+
+ ESP32-S3는 내장 USB 포트를 사용하면 별도 드라이버가 필요 없습니다. +
USB-UART 변환기(CP2102, CH340)를 사용하는 경우 칩 드라이버를 미리 설치하세요. +
+
+
+ +
+
3
+
+
시리얼 연결 확인 (STEP 1)
+
+ 웹 플래셔의 포트 연결 버튼을 클릭하고 브라우저 포트 선택창에서 ESP32 포트를 선택합니다. +
아래와 같이 Espressif 확인 메시지가 나오면 정상입니다. +
+ ✓ 포트 연결 성공
+   VID: 0x303A PID: 0x1001
+   Espressif 장치 감지됨 (ESP32S3 가능성 높음)
+   포트를 닫았습니다 (플래시 시 자동 재연결) +
+
+
+
+ +
+
4
+
+
업로드 방식 선택 — "병합 바이너리" 선택
+
+ 펌웨어 업로드 탭에서 병합 바이너리 버튼이 선택되어 있는지 확인합니다. +
+
+
+ +
+
5
+
+
merged.bin 파일 선택
+
+ 빌드 폴더에서 CANFD_Logger.ino.merged.bin (또는 프로젝트명.ino.merged.bin)을 드래그하거나 클릭하여 선택합니다. +
+ 📦 +
+
CANFD_Logger.ino.merged.bin
+
전체 병합 바이너리 — 이 파일 하나만 필요
+
+
offset 0x0
+
+
+
+
+ +
+
6
+
+
메타데이터 입력 후 업로드
+
+ 이름, 버전, 칩 패밀리(ESP32-S3)를 입력하고 서버에 업로드를 클릭합니다. +
업로드 완료 후 자동으로 플래시 탭으로 이동합니다. +
+
+
+ +
+
7
+
+
플래시 실행
+
+ 플래시 탭에서 방금 업로드한 펌웨어를 클릭하여 선택한 뒤, + ⚡ 플래시 실행 버튼을 누릅니다. +
esp-web-tools 창에서 포트를 선택하면 자동으로 플래싱이 진행됩니다. +
+ ⚠ +
플래시 중 USB 케이블 분리 금지. 일부 보드는 BOOT 버튼을 누른 채로 연결해야 합니다.
+
+
+
+
+ +
+
+ + +
+

4 방법 B — 분리 파일 플래시

+ +
+ 분리 파일 모드 +
+
+ +

+ 단계 1~3(브라우저 준비 → USB 연결 → 시리얼 연결 확인)은 방법 A와 동일합니다. + 4단계부터 차이가 있습니다. +

+ +
+
4
+
+
업로드 방식 — "분리 파일" 선택
+
+ 업로드 탭 상단에서 분리 파일을 선택합니다. + bootloader, partitions, boot_app0, app 4개 드롭존이 표시됩니다. +
+
+
+ +
+
5
+
+
파일 4개 각각 선택
+
+ 빌드 폴더에서 아래 파일들을 각 드롭존에 넣습니다. + +
+ 🔧 +
+
CANFD_Logger.ino.bootloader.bin
+
① 부트로더 드롭존에 넣기
+
+
0x0000
+
+
+ 📋 +
+
CANFD_Logger.ino.partitions.bin
+
② 파티션 테이블 드롭존에 넣기
+
+
0x8000
+
+
+ 🔁 +
+
boot_app0.bin
+
③ Boot App0 드롭존에 넣기 (OTA 미사용 시 생략 가능)
+
+
0xe000
+
+
+ 📦 +
+
CANFD_Logger.ino.bin
+
④ 애플리케이션 드롭존에 넣기
+
+
0x10000
+
+ +
+ ⚠ +
+ boot_app0.bin은 빌드 폴더가 아닌 Arduino ESP32 코어 폴더에 있을 수 있습니다.
+ %LOCALAPPDATA%\Arduino15\packages\esp32\hardware\esp32\버전\tools\partitions\boot_app0.bin +
+
+
+
+
+ +
+
6
+
+
메타데이터 입력 후 업로드 → 플래시
+
+ 방법 A의 6~7단계와 동일하게 진행합니다. +
+
+
+ +
+
+ + +
+

5 자주 발생하는 문제

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
증상원인해결 방법
포트 연결 버튼이 비활성화Firefox/Safari 사용Chrome 또는 Edge 89+ 사용
"지원되지 않는 브라우저" 배너HTTP + 외부 IP 접속Docker와 같은 PC에서 localhost:3100으로 접속
포트 선택창에 ESP32가 안 보임드라이버 미설치 또는 케이블 불량데이터 전송 가능한 USB 케이블 사용, CP2102/CH340 드라이버 설치
플래시 후 부팅 안 됨Flash 크기 불일치Arduino IDE 보드 설정의 Flash Size가 실제 보드와 일치하는지 확인 후 재컴파일
업로드 실패 (파일 크기 초과)merged.bin이 32 MB 초과분리 파일 방식 사용 (앱만 ~1 MB)
플래시 중 연결 끊김USB 전원 불안정허브 대신 PC 직접 연결, 전원 공급이 충분한 포트 사용
BOOT 버튼 관련 오류ROM 부트로더 진입 실패BOOT 버튼을 누른 상태로 ESP32 연결 또는 RST 후 BOOT 누르기
+
+ + +
+

6 flash_args 플래그 설명

+ +

+ flash_args 파일에 기록된 플래그는 Arduino IDE가 컴파일 시 설정한 값입니다. + 웹 플래셔는 이 값을 바이너리에서 자동으로 읽으므로 별도 입력이 필요 없습니다. +

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
플래그값 (예시)의미웹 플래셔 입력 필요?
--flash-modedioSPI 플래시 통신 방식 (DIO = Dual I/O)불필요 (바이너리 내장)
--flash-freq80m플래시 클럭 주파수 (80 MHz)불필요 (바이너리 내장)
--flash-size16MB플래시 메모리 용량 (실제 보드와 일치해야 함)불필요 (바이너리 내장)
PSRAM 설정컴파일 옵션PSRAM 활성화 여부 (ESP32-S3 4MB/8MB PSRAM)불필요 (바이너리 내장)
CPU 주파수240 MHz프로세서 동작 클럭불필요 (바이너리 내장)
+ +
+ 💡 +
+ Arduino IDE에서 PSRAM, CPU 주파수, Flash 크기 등을 설정하면 모두 .bin 파일 안에 컴파일되어 저장됩니다. + 웹 플래셔는 이 .bin 파일을 그대로 ESP32에 써넣기만 하므로, 이 설정들을 다시 입력할 필요가 없습니다. +
+
+
+ + +
+

7 브라우저 및 환경 호환성

+ + + + + + + + + + + + + + +
환경지원비고
Chrome 89+✓ 지원권장
Edge 89+✓ 지원권장
Firefox✗ 미지원Web Serial API 없음
Safari✗ 미지원Web Serial API 없음
http://localhost✓ 동작보안 컨텍스트 예외
http://192.168.x.x (IP)✗ 미동작HTTPS 필요
https://도메인✓ 동작SSL 인증서 필요
+
+ +
+ +
+ ESP32 Web Flasher 사용 설명서 — 2025년 5월 +
+ + + diff --git a/frontend/index.html b/frontend/index.html index 32c81b4..bb365c6 100644 --- a/frontend/index.html +++ b/frontend/index.html @@ -110,14 +110,32 @@
ℹ
- Arduino IDE Sketch → Export Compiled Binary 로 생성한 .bin 파일을 업로드하세요. -
병합 바이너리(merged.bin)는 '펌웨어' 하나만 업로드해도 됩니다. + Arduino IDE Sketch → Export Compiled Binary 후 빌드 폴더에서 파일을 선택하세요.
- 분리 파일 사용 시: bootloader(0x0000) + partition-table(0x8000) + app(0x10000) + 병합 바이너리: *.merged.bin 하나만 업로드 (권장) | + 분리 파일: bootloader + partitions + boot_app0 + app
+ +
+ + +
+
@@ -161,40 +179,49 @@
-
- +
+
📦
-
- 펌웨어 .bin 파일을 드래그하거나 클릭하세요 -
(최대 8 MB)
+
+ *.merged.bin 파일을 드래그하거나 클릭하세요 +
(최대 32 MB)
- -
- - ▸ 분리 바이너리 파일 추가 (선택) - -
-
- -
- -
부트로더 .bin (선택사항)
-
-
-
- -
- -
파티션 테이블 .bin (선택사항)
-
+ +
+
+ +
+ +
*.partitions.bin 드래그 또는 클릭
+
+
+
+ +
+ +
boot_app0.bin 드래그 또는 클릭
+
+
+
+ +
+ +
*.ino.bin 드래그 또는 클릭
+
+
+