WLED 故障排除 错误 操作指南

WLED 错误代码:错误 7、8、9、12、19 和 91 的含义与修复方法

WLED 定义的每一个错误代码(1 到 101):网页界面提示的含义、固件中触发它的原因,以及修复方法。另附“issue loading your presets”的处理办法。

作者:

本文作者 Jamie Conde 在 MeowScript 开发 WLED Max。 WLED Max 是一款独立 App,与官方 WLED 项目无关,也未获其认可。

WLED 会在网页底部用一条红色的短横幅显示错误,例如 Error 8: Effect RAM depleted!。数字来自固件中的一个列表(wled00/const.h),旁边那句文字就是您能得到的全部解释。本页逐一讲解该列表定义的每个代码、真正触发它的原因,以及该怎么处理。

大家搜索最多的代码排在前面。完整表格在页面下方。

小知识

横幅只显示一次。WLED 会把错误交给第一个向灯请求状态的页面或 App,然后清除它。如果 Home Assistant 或某个手机 App 正在轮询这盏灯,它们可能先把错误取走,您的浏览器就永远看不到。想看到代码,请在问题发生后立刻刷新页面。

错误 7:No RAM for buffer(缓冲区内存不足)

仅 WLED 16。 灯尝试为某个分段的像素预留内存,但内存不够。WLED 随后会关闭该分段,所以很多人会把这个问题描述成“我的分段消失了”。

原因:

  • 对这块芯片来说 LED 太多,通常是 ESP8266,或者是大型 2D 矩阵。
  • 分段很多,每个分段都有自己的缓冲区。
  • 在支持播放图片的版本上,2D 矩阵上显示图片或 GIF。图片同样占内存。

修复方法:减少 LED 数量,合并用不上的分段,或者把大型装置换到 ESP32 上。带 PSRAM 的开发板(很多 ESP32-S3 开发板,以及 ESP32 WROVER 模块)空间大得多,因为 WLED 16 会尽可能把像素缓冲区放进 PSRAM。

错误 8:Effect RAM depleted(效果内存耗尽)

WLED 0.15 和 16。 某个效果申请工作内存(像 Fire 2012 或粒子效果使用的暂存空间)却没有拿到。WLED 对所有分段的效果内存总量设了上限(0.15 在所有开发板上都限制,16 只在没有 PSRAM 的开发板上限制),所以几个分段各跑一个重量级效果,就算灯看起来很闲,也可能碰到上限。

WLED 16 在另外两种情况下也用同一个代码,两种都值得了解:

  • 内存持续偏低 15 秒。 WLED 会把所有分段切换为 Solid 以释放内存,并显示错误 8。如果内存持续偏低 30 秒,它会删除除一个以外的所有分段;到 45 秒时,它会从头重建 LED 灯带并重新连接 Wi-Fi。
  • 某个 LED 输出需要的内存超过 WLED 允许的上限。 该输出会以占位符形式添加,所以接在上面的 LED 保持熄灭。保存 LED 设置后您会看到错误 8。

修复方法:使用更轻量的效果(Solid、Solid Pattern 和 Breathe 完全不需要效果内存),减少同时运行重量级效果的分段数量,或者减少每个输出上的 LED 数。如果您的分段总是自己变成 Solid,原因几乎都在这里。

错误 9:JSON parsing error(JSON 解析错误)

所有版本(横幅文字从 0.15 起出现)。有东西向灯发送了它无法读取的 JSON,请求被以 HTTP 400 拒绝。灯上什么都没有改变。

常见原因:

  • 弯引号。 您从备忘录 App 或聊天窗口复制了命令," 变成了 “ 和 ”。iPhone 的智能标点默认就会这样做。先粘贴到纯文本编辑器里,或者重新输入引号。
  • 末尾多了逗号、使用了单引号,或者带有注释。JSON 不允许这些。
  • 请求太大。JSON 缓冲区在 ESP8266 上约 10 KB,在 ESP32 上为 24 到 32 KB,一个带很多分段或很长单颗 LED 颜色列表的预设可能超出而解析失败。
  • 通过 WebSocket 连接时,一条消息被拆成多个数据包到达。WLED 不会把它们重新拼起来,而是回复错误 9。

如果您在网页界面手工输入预设,预设编辑器会在大多数此类问题到达灯之前拦住它们:您看到的是“Syntax error in custom JSON API command”,而不是错误 9。

错误 12:Preset not found(找不到预设)

所有版本。 有东西要求灯加载一个不存在的预设槽位。删除或重新编号预设之后这很常见,因为 WLED 里没有任何机制会去更新指向这些预设的地方:

  • Config›LED & Hardware(0.14 和 0.15 上是 LED Preferences)中的 Apply preset at boot。
  • Config > Time & Macros 中的定时器、按键动作和 Alexa 预设。
  • 播放列表里的条目。
  • 发送 {"ps":N} 的 Home Assistant 自动化、脚本或遥控器。

逐项检查这些地方里是否有错误提示的那个槽位号。如果槽位确实存在却仍然出现错误 12,预设文件本身可能已损坏,见下文的“issue loading your presets”。

关于开机预设和槽位的更多内容,见 WLED 预设与开机预设。

错误 19:A filesystem error has occurred(文件系统错误)

所有版本。 这是一个泛指的文件系统故障。在当前源码中它只来自一处:WLED 尝试创建一个空的 presets.json(在启动时,或在您保存预设而该文件已丢失时),但文件写不进去。在编译时带 EEPROM 支持的 0.14 和 0.15 版本上,当来自很早期 WLED(EEPROM 时代)的旧预设转换失败时,也会出现这个错误。

所以错误 19 的意思是闪存无法写入。通常是闪存满了,有时是写入过程中断电导致文件系统损坏。

按顺序尝试:

  1. 能备份的先备份:Config > Security & Updates > Backup configuration,如果可以的话再 Backup presets。
  2. 删除预设或您上传过的文件(ledmap、图片、自定义调色板)来释放空间。
  3. 如果反复出现,就做一次恢复出厂设置(同一页面,勾选 Factory reset 并保存,这会清除所有设置和预设),或者通过 install.wled.me 重新刷写固件,然后恢复您的备份。

错误 91:Brownout Restart(欠压重启)

仅 WLED 16,仅 ESP32 开发板。 芯片因为供电电压跌得太低而重启。WLED 在启动时读取重启原因,并在下一次加载页面时显示 91。在 ESP8266 上欠压和普通断电没有区别,所以您在那里永远不会看到 91,而 0.14 和 0.15 根本不报告它。

对于 LED 灯带,原因几乎总是供电:

  • 电源对您使用的亮度下的 LED 来说太小。全白是最坏情况。
  • 电源到控制器之间的线太细或太长,LED 变亮时电压就下垂。
  • 控制器由笔记本电脑的 USB 口或一个弱手机充电器供电。
  • 没有设置亮度上限。

修复方法:在 LED 设置页设置 Maximum PSU Current(0.14 上叫 Maximum Current),让 WLED 把亮度限制在电源能供应的范围内;在长灯带两端补电;并选用留有余量的电源(比计算值高约 20%)。具体数字和截图见 用手机设置 WLED。如果您的灯还时不时掉线,也请读一读 WLED 为什么会离线。

错误 90:Unexpected Restart(意外重启)

WLED 16。 灯崩溃了,或者被看门狗重置,重启后它会告诉您。偶尔出现一次 90 不值得追查。

如果它一再崩溃,WLED 16(以及 0.15.5)会自行介入。连续崩溃 5 次、每次间隔不到两分钟,它就当作启动循环处理,每循环一次尝试一步:先恢复最后一份正常的配置备份,然后重置配置,再然后(仅 ESP32)启动上次更新之前安装的固件。所以如果一连串重启之后您的设置看起来变了,原因就在这里。

常见诱因是对开发板来说太重的效果或用户模块、错误的 LED 设置(引脚、类型或数量),以及还不到欠压程度的供电问题。如果它是在固件更新之后才开始的,见 通过 OTA 更新 WLED。

“Sorry, there was an issue loading your presets!”

这一条没有编号。当网页界面读不出 presets.json 时,会在 Presets 标签页显示它,原因要么是灯没有应答,要么是文件已经不再是合法的 JSON(保存时断电就会造成这种情况)。

  1. 在浏览器中打开 http://<your-light-ip>/presets.json。如果能看到您的预设,说明文件没问题,只是连接短暂出了问题。刷新页面即可。
  2. 如果您常用的浏览器以前看过您的预设,这条提示还会显示“Here is a backup of the last known good state”,并带一个 Copy to clipboard 按钮(从 0.15 起还有 Restore 按钮)。这份备份存在浏览器里,不在灯上。先把它复制到安全的地方,再恢复。
  3. 否则,在 Config > Security & Updates > Restore presets 下恢复一份已保存的 presets.json。这会替换文件中的全部内容。

养成 备份配置和预设 的习惯,这件事就从一个糟糕的夜晚变成两分钟就能修好的小事。

WLED 的全部错误代码

代码网页界面文字含义版本
1Denied!启用了设置 PIN 但没有输入,所以设置更改被拒绝全部(文字从 0.15 起)
2(无)0.14:旧的 EEPROM 代码,未使用。0.15 和 16:“concurrency”,已定义但从未触发实际不会出现
3Buffer locked!灯正忙于处理另一个 JSON 请求全部
4(空白)未实现:灯不认识的 /json/... 地址,或者在 16 上把仅限 2D 的效果用在 1D 灯带上、把 1D 粒子效果用在只有一颗 LED 的分段上,或者滚动文字的字体文件损坏0.15、16
7No RAM for buffer!分段像素的内存不足16
8Effect RAM depleted!效果内存不足,或者(16)内存偏低或某个 LED 输出太大0.15、16
9JSON parsing error!灯收到了无法读取的 JSON全部
10Could not mount filesystem!闪存文件系统没有启动全部
11Not enough space to save preset!文件系统已满全部
12Preset not found.请求了一个不存在的预设槽位全部
13Missing ir.json.设为 JSON 模式的红外遥控器发送了一个码,但灯上没有 ir.json全部
14(无)缺少 remote.json;该检查已被注释掉,所以永远不会触发实际不会出现
19A filesystem error has occured.泛指的文件系统故障,通常发生在创建 presets.json 时全部
30、31、32(无)过温、过流、欠压。源码中标记为“not implemented”实际不会出现
33 到 37(无)16 中定义的低内存代码,尚未触发(它们的网页界面文字被注释掉了)实际不会出现
90Unexpected Restart.灯在崩溃或看门狗重置后重启16
91Brownout Restart.灯因供电电压下跌而重启16,ESP32
100Note 100: Please reboot WLED to activate changed settings.某项硬件设置需要重启(在 16.0.1 上:ESP32-S3 上的 HUB75 面板更改)16
101Note 101: Please switch your device off and back on.某项硬件设置需要断电重启;已定义,16.0.1 中尚未使用16

0.14 的网页界面只有 10、11、12、13 和 19 的文字,所以其他代码都显示为“Error N:”,后面什么都没有。较新版本上的错误 4 也是如此。“occured”这个拼写错误来自固件本身。

其余代码简述

错误 1(Denied)。 您在 Config > Security & Updates 下设置了 PIN,而有东西试图在不输入 PIN 的情况下更改设置。在网页界面里输入 PIN,或者在正在写入的 App 或脚本里输入。

错误 3(Buffer locked)。 WLED 一次只处理一个 JSON 请求。在 0.15 上,期间到达的第二个请求会得到带错误 3 的 HTTP 503(在 0.14 上只有读取请求会这样,写入请求则得不到任何应答)。WLED 16 改为让 HTTP 请求排队等待,但 WebSocket 客户端仍可能收到错误 3。如果您经常看到它,说明有东西在高频轮询:Home Assistant 集成、几个打开的浏览器标签页加上一个 App 同时在跑。关掉不需要的。

错误 10(Could not mount filesystem)。 通常是刷固件时用了不适合该开发板的闪存布局,或者闪存芯片正在失效。用网页安装器重新刷写,并让它先擦除开发板。设置和预设会丢失,所以请从备份恢复。实际上挂载失败通常表现为错误 19,因为 WLED 会立刻尝试创建 presets.json,而那一步也会失败。

错误 11(Not enough space)。 只有在剩余空间足以容纳整个文件的一份完整副本再加约 9 KB 时,WLED 才会保存预设。一块存了很多带分段布局的预设的 ESP8266 会最先用光空间。删除不用的预设,或者移除不再需要的上传文件。

错误 13(Missing ir.json)。 在 Config > LED & Hardware(0.14 和 0.15 上是 LED Preferences)中红外接收器被设为“JSON remote”类型,却没有上传 ir.json。上传一个,或者在列表中选择您遥控器的型号。

来自 App 的提示

App 不显示 WLED 的编号,它们有自己的措辞。WLED Max(iOS 和 Android)中有两条提示直接对应固件状态:

  • “设备正忙,没有接受更改。”(Android 上是“设备正忙,没有接受这项更改。”)灯一直回复错误 3,App 重试几次后放弃了。等几秒再试,并查找是否有别的东西在轮询这盏灯。
  • “设备发来了意外的响应。它运行的固件版本可能不兼容。” 灯有应答,但返回的是 HTTP 错误或 App 无法使用的内容。可能是非常老的 WLED、完全不同的固件,或者灯在请求中途重启了。

App 在修改 presets.json 之前也会先检查它。如果文件已损坏,App 不会覆盖它,而是提议保存一份原始文件的副本(iOS:保存文件副本;Android:警告中的 备份原始文件,或“预设”标签页中的 保存文件副本)。

如果灯完全没有应答,那是网络问题而不是 WLED 错误,WLED App 找不到您的灯 会逐一讲解原因。

常见问题

WLED 错误代码列表在哪里? 在 WLED 源码的 wled00/const.h 中,紧挨着 ERR_ 名称。网页界面对每个代码的提示文字在 wled00/data/index.js 中。

出现错误是不是说明我的开发板坏了? 很少。大多数代码关于内存(7、8)、预设(12)或供电(91)。重新刷写后仍反复出现的错误 10 和 19 才是指向硬件的。

为什么刷新页面后错误就消失了? WLED 报告一次之后就清除错误。只有问题再次发生它才会再出现。

我们的 iOS 和 Android App WLED Max:一盏灯即可免费使用全部功能。