一个服务搞定 ESP-IDF 项目的构建、烧录和串口监控 —— 可从浏览器或 Claude 使用。 One service that builds, flashes, and monitors your ESP-IDF project — from your browser or from Claude.
在 Windows 上构建 ESP-IDF 项目，远比想象中脆弱：
# export.bat silently exits -- MSYSTEM conflict with Git Bash
# activate.py can't find Python venv -- version mismatch
# cmd.exe /c broken in Git Bash -- interpreted as drive path
# idf.py not found -- environment never set up correctly
# Serial port contention -- flash needs the same COM as monitor每个新克隆、每次环境重置、每个新队友都会踩到这些坑。 Every new clone, every environment reset, every teammate hits these.
一个 HTTP+SSE 服务器，处理从环境准备到构建、烧录、串口监控的全部流程，在浏览器中实时可见，同时提供 REST API 供 AI 调用。
A single HTTP+SSE server that handles everything — environment setup, build, flash, and serial monitor — all visible in your browser and controllable via REST API.
- Web UI — 选择 COM 端口，实时查看串口输出，一键构建和烧录 / select COM port, see serial output live, build and flash with one click
- REST API — Claude 调用同一套接口，所有输出同时推送到浏览器和 API / Claude calls the same endpoints; all output streams to both browser and API
- Windows 兼容自动处理 — MSYSTEM、Python venv、export.bat、cmd.exe 等全部自动搞定 / Windows quirks handled automatically
- 无端口争用 — 服务器协调监控和烧录，烧录时自动释放 COM 口 / server coordinates monitor and flash; flash auto-releases COM
- 独立运行 — 不需要 Claude 也能用，在 UI 中配置 IDF 路径和项目目录即可 / works without Claude; configure IDF path and project dir from the UI
pip install pyserial
python serial_server.py
# 打开浏览器访问 http://localhost:8099
# Open http://localhost:8099- 设置 IDF 路径（留空则自动检测）/ Set IDF Path (leave empty to auto-detect)
- 设置 项目目录（例如 D:\Projects\hello_world）/ Set Project (e.g. D:\Projects\hello_world)
- 点击 Build — 实时查看编译日志 / Click Build — watch the compile log stream in real-time
- 选择 COM 端口，点击 Connect — 查看设备串口输出 / Select COM port and click Connect — see device serial output
- 点击 Flash — 烧录固件（监控器自动断开并重连）/ Click Flash — firmware uploads (monitor auto-disconnects, reconnects after)
- 点击 Reset — 通过 DTR 硬件复位 / Click Reset — hardware reset via DTR
服务器暴露 REST API，可供 AI 代理调用。AI 代理请阅读 SKILL.md 了解完整协议、错误分类和工作流程。
The server exposes a REST API that agents can call. AI agents: read SKILL.md for the full protocol, error classification, and agent workflow.
| 接口 Endpoint | 用途 Purpose |
|---|---|
| POST /api/check-config | 验证路径、版本、编译器 / Validate paths, versions, compiler |
| POST /api/build | 构建项目（同步或异步）/ Build project (sync or async) |
| POST /api/flash | 烧录固件（同步或异步）/ Flash firmware (sync or async) |
| POST /api/build-flash-monitor | 构建 + 烧录 + 监控串联 / Build + flash + monitor chain |
| POST /api/monitor/start | 打开串口 / Open serial port |
| POST /api/monitor/stop | 关闭串口 / Close serial port |
| POST /api/reset | DTR 硬件复位 / Hardware reset via DTR |
| POST /api/send | 向串口发送数据 / Send data to serial |
| POST /api/fullclean | 清理构建目录 / idf.py fullclean |
| POST /api/set-target | 切换 MCU 目标芯片 / Switch MCU target |
| POST /api/size | 固件体积分析 / Firmware size analysis |
| POST /api/menuconfig | 交互式配置（控制台执行）/ Interactive config (console) |
| POST /api/shutdown | 优雅关闭服务 / Graceful shutdown |
| GET /api/ports | 列出 COM 端口 / List COM ports |
| GET /api/status | 查询监控连接状态 / Monitor connection state |
| GET /api/task/<id> | 异步任务轮询 / Async task polling |
| GET /api/events | SSE 实时日志流 / SSE stream (live logs) |
# 指定 IDF 路径 / Override IDF path
python serial_server.py --idf-path D:\Programs\esp-idf\v5.5.3\esp-idf
# 自定义端口/主机 / Custom port/host
python serial_server.py --port 8080 --host 0.0.0.0- 浏览器串口监控（基于 pyserial 直接读取）/ Serial monitor in browser
- 浏览器一键构建 / One-click build from browser
- 一键烧录 + 自动 COM 口切换 / One-click flash with auto COM handover
- 异步任务 API（适合 AI 轮询）/ Async task API for agent-friendly polling
- 构建后自动显示固件体积 / Auto size after build
- DTR 硬件复位 / Hardware reset
- 可配置的 IDF 路径和项目目录 / Configurable IDF path and project dir
- Linux / macOS 支持 / Linux / macOS support
欢迎提交 PR！保持简洁 —— 这个项目的核心宗旨就是避免复杂性。
PRs welcome! Keep it simple — the whole point is avoiding complexity.