ESP32 Web Flasher

브라우저에서 ESP32 계열 마이컴에 펌웨어를 플래시하는 Docker 기반 웹 애플리케이션입니다.
별도 소프트웨어 설치 없이 Chrome/Edge 브라우저와 USB 케이블만으로 펌웨어를 구워 넣을 수 있습니다.

주요 특징

• Web Serial API — 드라이버·CLI 도구 없이 브라우저 직접 시리얼 통신
• esp-web-tools v10 (Espressif 공식) — 안정적인 웹 컴포넌트 기반 플래싱
• 다중 바이너리 지원 — bootloader / partition table / application 개별 또는 병합 바이너리
• 펌웨어 관리 — 업로드·목록·삭제, UUID 기반 REST API
• 실시간 로그 — 색상 구분 시리얼 모니터 내장
• Docker Compose — 단일 명령으로 백엔드(Node.js) + 프론트엔드(Nginx) 기동

지원 칩

칩 패밀리	지원 여부
ESP32-S3	✓ 권장 (내장 USB-OTG 지원)
ESP32-S2	✓
ESP32-C3	✓
ESP32	✓

브라우저 호환성

브라우저	지원
Chrome 89+	✓
Edge 89+	✓
Firefox	✗ (Web Serial 미지원)
Safari	✗ (Web Serial 미지원)

참고: HTTP(localhost 제외)에서는 Web Serial API가 동작하지 않습니다. 외부 배포 시 HTTPS가 필수입니다.

빠른 시작

사전 요구사항

• Docker Engine 20.10+
• Docker Compose v2+
• Chrome 89+ 또는 Edge 89+

실행

git clone https://gitea.byunc.com/byun/webflash.git
cd webflash
docker compose up -d --build

브라우저에서 http://localhost:3100 접속

중지

docker compose down

펌웨어 데이터까지 삭제하려면:

docker compose down -v

사용 방법

1단계 — 시리얼 연결 확인

1. ESP32를 USB 케이블로 PC에 연결
2. 포트 연결 버튼 클릭 → 브라우저 포트 선택 대화상자에서 포트 선택
3. VID/PID가 표시되고 Espressif(0x303A) 장치 여부 확인

2단계 — 펌웨어 업로드

펌웨어 업로드 탭에서:

• 이름, 버전, 칩 패밀리 입력
• .bin 파일 드래그&드롭 또는 클릭하여 선택
  • 병합 바이너리(merged.bin): 펌웨어 하나만 업로드
  • 분리 파일: bootloader(0x0000) + partitions(0x8000) + app(0x10000)
• 서버에 업로드 클릭

3단계 — 플래시

플래시 탭에서:

1. 목록에서 펌웨어 선택
2. ESP32S3 플래시 실행 버튼 클릭
3. esp-web-tools 대화상자에서 포트 선택 후 플래시 진행

플래시 파일 준비

Arduino IDE에서 내보내기

Sketch → Export Compiled Binary
→ 스케치 폴더에 .bin 파일 생성

병합 바이너리 생성 (권장)

esptool.py --chip esp32s3 merge_bin \
  -o merged.bin \
  0x0     bootloader.bin \
  0x8000  partitions.bin \
  0x10000 app.bin

PlatformIO 사용 시

pio run                      # 개별 바이너리 빌드
pio run --target mergebin    # 병합 바이너리 생성

프로젝트 구조

webflash/
├── backend/
│   ├── Dockerfile           # Node.js 20 Alpine 이미지
│   ├── package.json
│   └── server.js            # Express REST API 서버
├── frontend/
│   ├── Dockerfile           # Nginx Alpine 이미지
│   ├── nginx.conf           # 리버스 프록시 설정
│   ├── index.html           # 단일 페이지 앱 (한국어 UI)
│   ├── css/style.css        # 다크 테마 스타일
│   └── js/app.js            # Web Serial API 로직
└── docker-compose.yml

REST API

메서드	경로	설명
GET	/api/health	헬스 체크
GET	/api/firmware	펌웨어 목록 조회
POST	/api/firmware/upload	펌웨어 업로드
GET	/api/firmware/:id/manifest	esp-web-tools 매니페스트 생성
DELETE	/api/firmware/:id	펌웨어 삭제
GET	/firmware/files/:filename	바이너리 파일 서빙

업로드 요청 예시

curl -X POST http://localhost:3100/api/firmware/upload \
  -F "name=My Firmware" \
  -F "version=1.0.0" \
  -F "chipFamily=ESP32-S3" \
  -F "firmware=@app.bin" \
  -F "bootloader=@bootloader.bin" \
  -F "partitions=@partitions.bin"

매니페스트 응답 예시

{
  "name": "My Firmware",
  "version": "1.0.0",
  "new_install_prompt_erase": true,
  "builds": [{
    "chipFamily": "ESP32-S3",
    "parts": [
      { "path": "/firmware/files/xxxx-bootloader.bin", "offset": 0 },
      { "path": "/firmware/files/xxxx-partitions.bin", "offset": 32768 },
      { "path": "/firmware/files/xxxx-app.bin",        "offset": 65536 }
    ]
  }]
}

환경 변수

변수	기본값	설명
PORT	3000	백엔드 포트
NODE_ENV	production	실행 환경
ALLOWED_ORIGIN	*	CORS 허용 오리진

기술 스택

영역	기술
백엔드	Node.js 20, Express 4, Multer, UUID
프론트엔드	Vanilla JS, HTML5, CSS3
웹 서버	Nginx Alpine (리버스 프록시)
플래싱	esp-web-tools v10, Web Serial API
컨테이너	Docker, Docker Compose
저장소	파일 시스템 + JSON 메타데이터

보안 고려사항

• 파일 업로드는 .bin 확장자 및 8 MB 크기 제한
• XSS 방지를 위한 HTML 이스케이프 처리
• 외부 배포 시 HTTPS 적용 필수
• ESP32 Flash Encryption 활성화 권장 (펌웨어 덤프 방지)

라이선스

MIT