ESPHomeESP32OTA 升级彩灯特效自定义网页 UI米家床头灯

ESPHome 设备改造与自定义 UI(esphome-device-reflash-ui)

给已刷 ESPHome 的 ESP32 设备(如米家床头灯)做 OTA 升级、彩灯特效和网页控制页开发

一、这个 skill 是做什么的

ESPHome 是一个把 ESP32 这类小芯片变成智能设备的开源固件框架。这个 skill 专门帮你给"已经刷了 ESPHome 的成品设备"(比如米家床头灯 2 / MJCTD02YL)做三件事:远程升级固件、写彩色灯光特效、做一个由设备自己托管的网页控制页。

它的核心心法是:ESPHome 的验证是分层级的,某一层通过(比如配置能解析)不能推断另一层通过(比如编译能过、真机跑得动、网页渲染正常)。所以本说明会按"先查根因、分层验证"的思路教你,而不是让你无脑烧录试错。

很多坑只有在动手时才会暴露——例如彩色特效的 API 名字不对、OTA 烧录的 4 个文件布局、网页前端的三个必踩陷阱。本说明把它们都整理成"提前避坑清单",让你一次做对。

二、什么时候用它

三、前置条件 / 准备

四、具体用法(步骤)

① 先确认设备状态与可用引脚

查该设备的官方引脚表,确认哪些 GPIO 是"无功能 / 仅调试"——这些是加外设的首选。别碰 SPI flash 脚(GPIO6-11)和已占用的 PWM/I2C。改造成品灯加外设时,可复用调试串口(UART0 = GPIO1/GPIO3),但必须让出串口日志(logger: {level: WARN, baud_rate: 0}),并做可整体拔插的 4Pin 排针母座作为救砖后门。

② 写 YAML 配置

包含 light 组件、ota、web_server 等。注意 ESPHome 2026 起网页上传 OTA 是独立平台 web_server,需和 esphome 平台双并存才有网页升级入口。

③ 分层验证(别跳步)

先跑 esphome config x.yaml 检查 YAML 字段是否合法(它查不出 C++ 错误);再在本机原生 shell 跑 esphome compile x.yaml 编译;最后看真机日志和浏览器渲染。

④ 烧录与 OTA

首刷:接线后先用 esptool read_flash 备份原厂,再用 ESP-IDF 的 4 个 bin 文件布局(bootloader@0x1000 / partitions@0x8000 / ota_data_initial@0x9000 / firmware@0x10000)烧录;后续更新用 esphome upload x.yaml --device <设备IP> 走 OTA,不用再接线。

⑤ 自定义网页 UI

用 web_server 的 js_include / css_include 把 UI 烧进固件(同源、天然无跨域)。改 UI 必须重编 + OTA,并让用户 Ctrl+F5 清浏览器缓存。

进阶 / 可选:下面这些命令是真正编译和 OTA 时在本机原生 shell 跑的(沙箱内 compile 常被拦)。它们做的是"把配置编译成固件"和"通过 WiFi 把固件推送到设备"两件事。
# 1) 检查 YAML 配置是否合法(查不出 C++ 错误) esphome config x.yaml # 2) 在本机原生 shell 编译(沙箱里常被安全钩子拦截) esphome compile x.yaml # 3) 后续更新走 OTA,不用接线(设备已跑 ESPHome 时) esphome upload x.yaml --device 192.168.x.x

五、可直接照用的示例

你:我想给米家床头灯写个彩虹渐变特效,代码里用了 set_hue(h) 和 set_saturation(s),结果编译报 has no member named 'set_hue'。

AI大模型或AI智能体:这是 ESPHome 的头号坑——LightCall 根本没有 set_hue / set_saturation,它只有 set_red / set_green / set_blue / set_brightness 等。正确做法是手算 HSV→RGB 再调 RGB:在 lambda 里按色相 h 算出 r/g/b(0~1),然后 id(my_light).turn_on().set_red(r).set_green(g).set_blue(b).set_transition_length(0).perform()。这样编译就能过,彩虹特效就出来了。

你:灯已经跑着 ESPHome 了,我不想每次都拆壳接线升级,能不能远程更?

AI大模型或AI智能体:可以,后续更新走 OTA 就行:在本机原生 shell 跑 esphome upload x.yaml --device <灯的IP>(默认走 3232 端口的 TCP)。只有"设备现在跑的是原厂固件"时才必须线刷;已经跑 ESPHome 的都走 OTA。另外记得在 YAML 里把 ota 配成 esphome 和 web_server 双平台,网页里才有升级入口。

六、常见注意 / 避坑

七、相关 skill / 延伸

← 返回 SKILL 库