浏览器向导（esphome.cloud/app）
如果你不想要 AI 工具，完全不需要装。同一个 espctl 后端也驱动着 esphome.cloud/app 的网页向导，在那里你 可以完全在浏览器标签里配置、构建并烧录一台 ESP32 设备。
别和浏览器 MCP 搞混： esphome.cloud/mcp/esp-idf 是一个 网页控制台，里面有原始的 MCP 工具。这一页是引导向导 —— 更简单、 更手把手。
这适合谁
- ESPHome 用户 —— 已经习惯 YAML,想要点几下就行而不是打字。
- 第一次用的人 —— 想试试但不想装任何东西。
- 不想装 AI 工具的人。
- 工坊和演示 —— 目标是“点这些按钮,插上设备,看到它亮起来“。
它长什么样
向导有两种模式：组件模式（旧版，手动选组件）和方案模式（推荐，引导式流程）。方案模式是一个 7 步流程：
- 领域 —— 选择目标领域（载具控制系统、IoT 设备工具、网络安全、家庭数据中心、边缘 AI）。这会限定向导只展示相关的模组和方案。
- 设备 —— 选择芯片（ESP32、ESP32-S3、ESP32-C6 等）、开发板型号、设备名称和 Wi-Fi 配置。
- 模块 —— 选择与你开发板匹配的硬件模组。模组定义了可用的硬件能力（电机控制、摄像头、IMU、安全停车继电器等）。按领域和芯片过滤。
- 方案 —— 选择预优化的固件配置。每个方案包含固定的流水线步骤、必需组件和用户可配置的参数。对于载具领域，会显示三条逻辑链的优先级概要（控制上行链 / 视频下行链 / 遥测链）。
- 参数 —— 配置方案参数。参数以下拉框（枚举值如 IMU 芯片、控制协议、执行器类型）、开关（布尔值）或数字输入（数值）呈现。级联可见性：选“无 IMU“会隐藏芯片选择器。下方显示 GPIO 引脚分配表，根据你的选择动态更新。
- 复核 —— 核实模块、方案和参数。检测并警告引脚冲突。对于双 MCU 方案，会显示两个固件目标（控制板 + 摄像头板）。
- 构建 —— 远程编译固件，然后通过 USB 烧录。
你可以随时通过顶部的切换按钮切换到组件模式。
整个过程没有任何文件接触你本地硬盘，除非你选择下载。
安全提示: 你编译好的固件可能包含嵌入的敏感信息（Wi-Fi 密码、 API key）。把下载的
.bin文件当作敏感文件,不要公开分享。
架构(浏览器侧)
┌─────────────────────────────────────┐
│ 浏览器(ESPHome 向导) │
│ - 让构建服务器帮忙连接 │
│ - 打开 3 个通道: │
│ * espctl — 构建控制 + 事件 │
│ * pty — 实时终端流 │
│ * firmware — 二进制 chunk │
└──────┬──────────────────────────────┘
│ HTTPS(连接建立)
▼
┌─────────────────────────────────────┐
│ 构建服务器(esphome.cloud) │
│ - 颁发构建许可 │
│ - 挑最佳的构建机器 │
│ - 帮助两边找到对方 │
└──────┬──────────────────────────────┘
│ 任务分配
▼
┌─────────────────────────────────────┐
│ 构建机器 │
│ - 收到许可 │
│ - 直接和你的浏览器对话 │
│ - 在沙箱里跑构建 │
│ - 流式回传日志 + 固件 │
└─────────────────────────────────────┘
构建服务器从不接触构建本身 —— 它只帮两边找到对方。一旦通道打开, 所有构建流量在你浏览器和构建机器之间直接点对点流动。日志、 固件、甚至串口控制台的键盘输入,都是 P2P 的。
三个通道
| 通道 | 方向 | 承载 |
|---|---|---|
espctl | 浏览器 ↔ 构建机器 | 构建请求、状态事件、结构化进度,以及任何其他控制消息。 |
pty | 构建机器 → 浏览器 | 原始终端字节 —— 滚过去的 idf.py 输出。 |
firmware | 构建机器 → 浏览器 | 编译好的 .bin 文件,分 chunk 传输(最后还有一个校验和用于验证)。 |
通道在你连接时打开一次,在构建生命周期内保持打开。
你点“编译“时发生了什么
- 许可请求: 你的浏览器问构建服务器:“我想构建一些东西,用这些 通道,持续这么长时间。”
- 许可颁发: 构建服务器签发一个短命的 token,说明你被允许做什么, 然后挑一台构建机器。
- 连接建立: 你的浏览器和构建机器通过构建服务器交换几条消息来 在网络上找到对方。
- 直连: 你的浏览器和构建机器直接连上(如果你的网络不支持直连, 就通过中继)。
- 构建: 你的浏览器发送构建请求。构建机器验证许可,在沙箱里 跑构建,通过通道流式回传日志和编好的固件。
- 烧录: 你的浏览器把固件喂给内置烧录器,烧录器通过 USB 写到 你的设备。
浏览器的安全模型
- 许可短命。 构建服务器不会为通用使用颁发超过 30 秒的许可,而且 不会延长已有的许可 —— 你应该开新的。
- 通道允许列表。 许可精确列出你能打开哪些通道;构建机器强制执行。 你的浏览器无法打开未被授权的通道。
- 带宽和消息率限制。 每个许可有带宽上限和消息率上限,由构建机器 强制执行。
- 端到端加密。 所有通道流量在你的浏览器和构建机器之间加密。 构建服务器无法读取。
完整模型见 Grant 与安全。
网页向导不做的事
向导暴露了 espctl 最常用的那部分。一些高级功能是 AI 工具专有的:
- 超出
debug/release的自定义构建 profile。 - 手动
task_id管理(向导帮你管理任务生命周期)。 - 从你本地硬盘读任意
project://*资源(浏览器没有同样意义上的 本地硬盘)。 - 超过几分钟的长串口会话(许可 TTL 让这是有意的 —— 需要更长就 重启会话)。
如果需要其中任何一个,用 Claude Code 或 其他 AI 工具。
另见
- 系统总览 —— 同样的图,从更高视角看。
- 控制面与信令 —— 构建服务器到底做什么。
- WebRTC Agent 与数据通道 —— 构建机器 怎么执行许可规则。