ESPHome 是一个把 ESP32 这类小芯片变成智能设备的开源固件框架。这个 skill 专门帮你给"已经刷了 ESPHome 的成品设备"(比如米家床头灯 2 / MJCTD02YL)做三件事:远程升级固件、写彩色灯光特效、做一个由设备自己托管的网页控制页。
它的核心心法是:ESPHome 的验证是分层级的,某一层通过(比如配置能解析)不能推断另一层通过(比如编译能过、真机跑得动、网页渲染正常)。所以本说明会按"先查根因、分层验证"的思路教你,而不是让你无脑烧录试错。
很多坑只有在动手时才会暴露——例如彩色特效的 API 名字不对、OTA 烧录的 4 个文件布局、网页前端的三个必踩陷阱。本说明把它们都整理成"提前避坑清单",让你一次做对。
has no member named set_hue。"esphome 命令行)。esphome config 能跑,但 esphome compile 常被安全钩子拦截——编译和烧录请在本机原生 shell 里执行。查该设备的官方引脚表,确认哪些 GPIO 是"无功能 / 仅调试"——这些是加外设的首选。别碰 SPI flash 脚(GPIO6-11)和已占用的 PWM/I2C。改造成品灯加外设时,可复用调试串口(UART0 = GPIO1/GPIO3),但必须让出串口日志(logger: {level: WARN, baud_rate: 0}),并做可整体拔插的 4Pin 排针母座作为救砖后门。
包含 light 组件、ota、web_server 等。注意 ESPHome 2026 起网页上传 OTA 是独立平台 web_server,需和 esphome 平台双并存才有网页升级入口。
先跑 esphome config x.yaml 检查 YAML 字段是否合法(它查不出 C++ 错误);再在本机原生 shell 跑 esphome compile x.yaml 编译;最后看真机日志和浏览器渲染。
首刷:接线后先用 esptool read_flash 备份原厂,再用 ESP-IDF 的 4 个 bin 文件布局(bootloader@0x1000 / partitions@0x8000 / ota_data_initial@0x9000 / firmware@0x10000)烧录;后续更新用 esphome upload x.yaml --device <设备IP> 走 OTA,不用再接线。
用 web_server 的 js_include / css_include 把 UI 烧进固件(同源、天然无跨域)。改 UI 必须重编 + OTA,并让用户 Ctrl+F5 清浏览器缓存。
你:我想给米家床头灯写个彩虹渐变特效,代码里用了 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 双平台,网页里才有升级入口。
flasher_args.json 拿权威偏移。r.json() 会报错(其实操作已成功),要按 content-type / content-length 判空;② 拖动不跟手 + 数值回弹,修法是拖动中乐观更新本地 + 发送节流 + 拖动期间暂停轮询;③ 用"色相接近"反推选中项会相邻色串联,要用点击索引记录事实,绝不推算。config_hash、产物大小、编译产物里的关键字(如 grep flash_running)。凭记忆 / 直觉下结论必错。throttle 已删除,改用各传感器 filters(如 delayed_off);24GHz 毫米波雷达安装口诀:单层、非金属、离天线 ≥6mm、正前方无遮挡。