8.0
热点
AI SCORE
编程提效2026-09-21 20:30
浏览器直接给 ESP32 烧录 Claude 写的宏，无需 IDE 或工具链
dev.to · AI#ESP32#Claude#AI编程
Editor brief · 编辑速览
通过 Synacl 云固件在浏览器中完成 ESP32 烧录，由 Claude 从一句话描述生成运行在开发板上的宏代码，全程无需本地工具链。
由 Synacl 团队撰写。首发于 synacl.com，该教程为交互式版本。
无需打开 IDE、编写 sketch 或编译任何代码，就可以让 ESP32 读取光照传感器并驱动继电器。开发板通过浏览器标签页进行烧录，通过同一根 USB 数据线接入 Wi-Fi，自动化逻辑由 Claude 根据你输入的一句话编写——以宏（macro）的形式直接在 ESP32 开发板上运行。你查看 Claude 编写的代码，再决定是否要执行。本教程完整走通整条链路，使用开发板自带的 LED 作为"继电器"，因此在尝试之前无需任何接线。
访问 synacl.com/flash — 选择"Synacl gateway firmware"，点击 Connect，选择 USB 端口，然后 Flash。以 460800 波特率烧录约需 25 秒；无需工具链，暂不需要账号。
进入 Gateways → Add gateway。跳过烧录步骤（第 1 步已完成），在第 2 步给网关起个名字并注册，然后在第 3 步输入你的 Wi-Fi 网络名称和密码并点击 Send Wi-Fi & Connect。应用通过 USB 发送凭证和网关的账号密钥——无需Captive Portal（ captive portal）。
约 90 秒内网关显示 online，固件版本也会显示在侧边。此时开发板上没有任何外接设备。
在 claude.ai 中添加自定义连接器，URL 填写：
https://api.synacl.com/mcp
这就是 Claude 端的全部配置。
Synacl 的授权页面列出了每一项权限。"Run macros"默认未勾选，并标注"默认关闭——可驱动设备"；其他所有权限均已预选，你也可以只授予其中一部分。本教程在此勾选它——但请记住第 8 步，这个权限本身并不足够。
"This gateway has a relay on GPIO 2. Set it up as a device, then write a macro called Blink that switches it on and off five times, half a second each."
Claude 创建了设备和宏，完成编译和推送，并告知需要你点击来重新发送配置使其生效。
Macros 页面显示网关上的 Blink 宏，包含五个步骤：一个 repeat five 次循环，内含继电器开、等待半秒、继电器关、再等待——以及 Claude 自己写的一行描述。在任何内容运行之前先阅读它。
让 Claude 运行 Blink 时，Claude 先读取宏的内容："Blink 上 agentRunnable: false。我的连接持有 macro:run 权限，但该权限仅适用于用户在网页应用中明确标记为 AI agent 可运行的宏。这个标记不是我自己能设置的。"它持有 Run macros 权限，却仍然无法启动——需要两把钥匙，而软件永远只持有一把。
编辑该宏，勾选"Let an AI agent run this macro"。所有宏默认关闭此选项，没有任何助手能自己设置它，即使是在它自己写的宏上也不行。
再次请求运行。网关确认运行已开始，状态从 requested → started → done，输出引脚切换了五次。Claude 报告的是网关确认的内容，而非它自己发送的内容。
一块 ESP32 开发板和一根 USB 数据线。任意经典 ESP32 都能使用 Synacl 固件；图片中使用的是普通的 ESP32-WROOM 模块，其 GPIO 2 上有一颗常见的蓝色 LED。
Chrome 或 Edge 桌面浏览器。浏览器烧录和 USB 配置使用 Web Serial API，Firefox 和 Safari 没有此功能。
一个免费的 Synacl 账号——前五个设备免费。在烧录后创建，烧录工具本身无需账号。
支持自定义连接器的 Claude。本连接是一个标准远程 MCP 服务器，因此任何支持 MCP 的助手都能以相同方式工作；本教程中的界面截图为 claude.ai。
最后一部分所需：BH1750 光照传感器——常见的 GY-302 breakout——连接到 I²C 引脚：3.3 V、GND、SDA 接 GPIO 21、SCL 接 GPIO 22，ADDR 悬空（低电平）地址为 0x23。任意有数据手册的 I²C 传感器都可同理使用。如果想驱动真实负载而非只看 LED 闪烁，则需要继电器模块。
整个过程约需 15 分钟，大部分时间在等待开发板重启。
打开 synacl.com/flash，插入开发板，选择 Synacl gateway firmware。页面获取当前稳定版本并显示版本号。点击 Connect，在浏览器弹出的选择器中选中开发板的串口，然后 Flash。在默认 460800 波特率下，四个镜像文件约需 25 秒；日志以"Flash complete"结束，开发板自动重启。保持"Leave Erase entire flash off"（不勾选擦除整个闪存）——新开发板不需要，已是 Synacl 网关的开发板如果勾选则会擦除已保存的 Wi-Fi 和账号设置。
选择器中没有端口通常是数据线仅支持充电；首次握手失败则需要按住 BOOT 再点击 Connect。烧录文章涵盖了其他情况。
现在你拥有的是一个等待两样东西的网关：Wi-Fi 网络和所属账号。
创建你的账号，然后打开 Gateways → Add gateway。该页面有三个步骤，第 1 步你已经完成，跳过烧录部分；在第 2 步给网关起个名字并注册，然后在第 3 步输入你的 Wi-Fi 网络名称和密码并点击 Send Wi-Fi & Connect。应用通过 USB 发送凭证和网关的账号密钥——无需 Captive Portal，无需找到热点（开发板也为无电脑情况提供了 Synacl-Gateway 备用 Portal 来完成配置）。
返回 Gateways 页面，新的网关约在 90 秒内显示 online，固件版本也会显示在旁边。此时开发板上没有任何外接设备；接下来的步骤通过软件添加设备，引脚在有内容运行之前不关心连接的是什么。
在 claude.ai 中添加自定义连接器，填入 Synacl MCP 端点：
https://api.synacl.com/mcp
Claude 首次使用该连接时，浏览器会打开 Synacl 的授权页面。仔细阅读：它列出了 Claude 在"It will be able to"下请求的每一项权限，你可以取消勾选任何你不想授予的项目。几乎所有权限都预选了——创建设备、编辑标签、编写宏——因为这些操作不会驱动任何实际设备。有一行不同。"Run macros"默认未勾选，并标注"默认关闭——可驱动设备"。勾选它——同时记住第 5 步中的内容，这个权限本身并不足够运行任何宏。确认授权后，Claude 已连接到你的账号且仅连接你的账号。你随时可以在 Settings → API & Agents 中撤销该连接。
Claude 在此之后的所有操作都经过该连接，仅使用你勾选的权限——AI 智能体文章有完整列表。
现在来写那句话。在新对话中，启用该连接器：
This gateway has a relay on GPIO 2. Set it up as a device, then write a macro called Blink that switches it on and off five times, half a second each, so I can see it work.
指定引脚位置：Claude 不会猜测引脚，因为这个操作无法删除设备，而免费账户只有五个设备槽位，猜错一次就会浪费一个——所以它会直接询问。有了引脚后，它会查找你的网关，创建设备——一个 GPIO 数字输出，位于 GPIO 2，高电平有效，默认关闭——然后写入宏。
那一下点击始终由你掌控。新设备只有当网关的配置被重新发送时才会连接到板卡，而重新发送会让网关重启，所以 Claude 会将其报告为待处理状态，而不是直接执行。从网关卡片（Info）打开网关，然后按 Resend config；大约三十秒后板卡恢复，此时已拥有了继电器引脚。Synacl 宏是由模块组成的短程序：切换输出、等待、循环、读取标签、条件判断等。对于 Blink，Claude 生成了一个循环五次、内部包含四个模块的宏：输出开启、等待 500 毫秒、输出关闭、等待 500 毫秒。如果出错，平台会准确告知是哪个模块未能编译，然后它会修复；除非你想看，否则这些细节你都不会看到。
在应用的 Macros 中打开查看：Blink · 你的网关 · 5 步，带有一个 Run 按钮。点击进入查看步骤——这是大多数"AI 帮你做硬件"演示略过的部分。一个从未见过你装置的助手能搞对基本结构，但具体细节大概率会有问题——引脚不对、时长不对——而"大致正确但细节有误"恰恰是你想在板卡什么都没做的时候就能发现的问题。
第 5 步——审核，然后让它运行
让 Claude 运行 Blink。它不会执行。在我们的运行中，它先读取了宏，发现 agentRunnable: false，然后如实告知而不是调用工具；如果它强行调用了，平台的回复值得引用，因为这就是整个设计的全部逻辑：
宏 "Blink" 未被标记为可由 AI 智能体运行，因此此连接不得启动它。这是一个刻意设计的每宏独立设置，与此 token 上的权限分开：必须有人阅读序列并允许 AI 智能体运行它，在 Synacl 应用中。如果用户想要运行，请让他们执行。不要寻找其他方式运行它。
运行宏需要两个独立的密钥，软件永远只能持有其中一个。第一个是 Claude 连接上的运行宏权限——那个默认未勾选、你在第 3 步勾选的权限。Claude 持有它，但仍然被拒绝。第二个位于宏本身：在编辑器中，触发器下方，有一个标注为"Let an AI agent run this macro"的勾选框。每个宏默认都是关闭的，包括助手创建的宏，而且没有任何助手可以勾选它——平台会将该字段从任何经过 AI 智能体连接传来的请求中删除。权限说明哪个软件可以执行操作；但它无法告诉你这个序列是否安全。所以平台会逐个向你确认序列。
你已经阅读了 Blink。勾选该框，保存，然后重新请求。
这次网关确认了运行，Claude 告知了你：不是"我已发送"而是"网关确认已启动"。Macros 中的卡片依次经过 requested → started → done，GPIO 2 上的蓝色 LED 闪烁五次。那是你的继电器。把引脚换成你继电器模块所在的引脚，同样的宏就能驱动线圈了。
两个坦诚的说明。Claude 会等待网关确认几秒钟，如果始终没有收到确认就会报告 unknown——永远不会完成。运行发生在 ESP32 上：板卡自己计时那些半秒，即使 Wi-Fi 断开也会完成——这也正是为什么 Abort 是一条网络消息，而不是紧急停止。
第 6 步——让它对光线做出反应
连接 BH1750——3.3 V、GND、SDA 到 GPIO 21、SCL 到 GPIO 22、ADDR 到 GND——然后告诉 Claude 并修改宏，而不是写第二个宏：
有一个 BH1750 光传感器在 I²C 上——SDA 在 GPIO 21，SCL 在 GPIO 22，地址 0x23。将其添加为设备，然后将 Blink 修改为：先读取光照强度，只有当低于 20 lux 时才触发继电器两秒。改名为 Dark relay。
传感器成为这些引脚上的 I²C 设备，在地址 0x23 处有一个通用标签——BH1750 没有内置驱动，所以 Claude 填入了数据手册上的参数：写入 0x10 一次以启动连续测量，读取两个字节，高位在前，除以 1.2 得到 lux。I²C 文章中列出了这些字段，如果你想核实的话。再重新发送一次配置，在一两次轮询后 lux 标签就上线了；用手遮住传感器，看着数字下降。然后 Claude 重写了同一个宏：一个 read_tag 模块将 lux 读数存入变量，一个基于该变量的 if 条件，以及内部的脉冲。再次阅读——修改后的宏是一个新的序列，你给 Blink 勾选的可由 AI 智能体运行仍然有效，所以这是你检查阈值和引脚的时刻，在任何操作执行之前。然后遮住传感器，让 Claude 运行它：LED 闪烁。移开遮盖物再运行：什么都不发生，而且运行仍然正常结束——宏读取了传感器、做出了判断、然后停止。
最后这次运行是很多人期望平台做得不同的地方，而平台有意没有这样做：宏每次触发只运行一次。Dark relay 读取传感器一次，做出判断，然后停止。它不会一直监测光线。要让它成为一个自动切换的夜灯，你需要给它设置一个调度——在宏编辑器中，每 30 秒——或者从 lux 标签上的告警规则触发它。任何一个在应用中一分钟就能完成。Claude 做不了这个。助手可以编写和编辑宏，但它不能将宏放入调度、将其连接到设备事件，或重新启用一个被禁用的宏；无人值守运行由人设置，不管助手持有何种权限。一个凌晨三点在房间里没人的时候触发的序列，始终是你的决定。
一旦调度好，整个循环——读取、比较、切换——每三十秒在板卡上运行一次，无论云端能否连接到达，而且每次运行都有网关自身十分钟的上限。
Claude 做不到的事，以及原因
这是一条规则，画在一处：助手可以创作，人必须授权。通过这个连接，助手不能：
删除任何东西——设备、网关、仪表盘、规则或宏。它可以创建副本；不能删除你的数据。
向引脚、线圈或寄存器发送原始命令。任何动作都通过你可以阅读的宏来执行。
启用宏：没有调度、没有设备事件触发、没有重新启用被禁用的宏。
将其自身的工作标记为可运行。可由 AI 智能体运行的勾选框由人设置，在应用中，每个宏独立设置。
持有超出你勾选范围的权限。每一次拒绝都会说明它缺少哪个权限，所以你来决定，而不是靠猜测。
你的计划的宏配额和宏的大小列在 plans 页面上；免费版足够涵盖本指南中的所有内容。
说得直白：这些都不是安全功能。这些边界是真实的——一个网关、一次运行一个、十分钟、一个中止按钮——但它们限制的是错误；不能让机器变得安全。Abort 是通过网络发送的消息，无法到达离线的网关。Synacl 不是安全认证的。如果继电器另一侧的东西能伤人或毁物，保护必须物理上独立于平台：在电源路径中有一个硬接线的急停开关，而不是通过 ESP32 路由；联锁装置；额定值正确的继电器；一个最坏情况也能存活执行器。只有在你愿意让同事从隔壁房间启动的情况下，才授予运行宏的权限。
同样的三个部分——浏览器刷写、通过 MCP 连接的助手、板卡上的宏——可以从闪烁的 LED 扩展到 Modbus 电表和泵。想要这个流程的工业版本——同一个网关上的 RS485 传感器、仪表盘上的读数、带告警——请阅读 ESP32 Modbus RTU to a cloud dashboard in 15 minutes。宏食谱展示了这些模块手工能做什么，Macros 文章将限制和安全说明集中在一处。