## 1 Arduino IDE 빌드 파일 설명

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

파일명 | 크기 (예시) | 플래시 주소 | 용도 | 사용 여부
--- | --- | --- | --- | ---
`*.ino.merged.bin` | ~16 MB | `0x0000` | 전체 병합 바이너리 (모든 파일 합본) | ✓ 권장
`*.ino.bootloader.bin` | ~20 KB | `0x0000` | 부트로더 | 분리 방식 시
`*.ino.partitions.bin` | ~3 KB | `0x8000` | 파티션 테이블 | 분리 방식 시
`boot_app0.bin` | ~8 KB | `0xe000` | OTA 부트 선택자 | 분리 방식 시
`*.ino.bin` | ~1 MB | `0x10000` | 애플리케이션 (실제 코드) | 분리 방식 시
`*.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-mode` | dio | SPI 플래시 통신 방식 (DIO = Dual I/O) | 불필요 (바이너리 내장)
`--flash-freq` | 80m | 플래시 클럭 주파수 (80 MHz) | 불필요 (바이너리 내장)
`--flash-size` | 16MB | 플래시 메모리 용량 (실제 보드와 일치해야 함) | 불필요 (바이너리 내장)
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 인증서 필요