WLED Battery Usermod 实战指南用 ESP8266/ESP32 实现电池电压监测、电量百分比、自动关机与低电量指示【免费下载链接】WLEDControl WS2812B and many more types of digital RGB LEDs with an ESP32 over WiFi!项目地址: https://gitcode.com/GitHub_Trending/wl/WLED本文是 WLED 项目中 Battery usermod 的完整技术指南。该模块让以电池供电的 ESP8266 / ESP32 LED 控制器能够实时监测电池电压、计算剩余电量百分比并具备可配置阈值的自动关机Auto-Off与低电量指示Low-Power Indicator能力同时深度集成 WLED 的 JSON API、MQTT 与 Home Assistant 自动发现。读完本文你将掌握 Battery usermod 的接线方案、编译配置、运行时参数调优与源码级工作原理可直接为你的便携 LED 项目灯带、灯笼、露营灯、可穿戴设备等部署一套可靠的电源监测方案。功能特性总览根据 Battery readme 与 Battery.cpp该 usermod 提供四项核心能力当前电池电压显示通过 ADC 采样计算电池电压显示在 WLED 信息界面与 JSON API 中电池电量百分比根据电池类型对应的电压-电量映射曲线mapVoltage计算 0–100% 电量自动关机Auto-Off电量跌至设定阈值时自动将 WLED 主亮度bri置 0保护电池避免过度放电低电量指示Low-Power Indicator电量低于阈值时自动播放预设Preset若干秒提示用户充电播完再切回之前的预设。此外自 2021-09-02 起该模块支持 MQTT 上报电压2024-08-19 版本又增加了电池百分比与电压两个 MQTT topic并支持 Home Assistant MQTT 自动发现详见文末变更日志。安装与启用WLED 采用 PlatformIO 构建usermod 有两种启用方式见 Battery readme 的 Installation 章节方式一platformio_override.ini推荐参见 官方示例截图在platformio_override.ini或platformio.ini中于custom_usermods 后追加Battery[platformio] default_envs esp32dev_custom [env:esp32dev_custom] extends env:esp32dev custom_usermods Battery build_flags ${env:esp32dev.build_flags} -D USERMOD_BATTERYcustom_usermods是 WLED 构建系统加载 usermod 库的入口见 platformio.ini构建脚本 pio-scripts/load_usermods.py 会解析该选项并把对应 usermod 目录如usermods/Battery/其下有 library.json 描述构建信息加入编译。你还可以在build_flags中直接传递配置宏例如设置测量引脚与采样间隔build_flags ${env:esp32dev.build_flags} -D USERMOD_BATTERY -D USERMOD_BATTERY_MEASUREMENT_PIN35 -D USERMOD_BATTERY_MEASUREMENT_INTERVAL3000方式二my_config.h将wled00/my_config_sample.h复制为wled00/my_config.h启用WLED_USE_MY_CONFIG后在文件中定义USERMOD_BATTERY即可将该 usermod 纳入编译源码注释中同样说明了这一点参见 Battery.cpp 对my_config.h的引用。配置示例见 my_config.h 配置截图。提示USERMOD_BATTERY只是编译开关真正把 usermod 实例挂入 WLED 运行循环的是源码末尾的static UsermodBattery battery; REGISTER_USERMOD(battery);见 Battery.cppREGISTER_USERMOD宏定义在 wled00/fcn_declare.h。典型接线方案Battery usermod 通过单片机的 ADC 读取电池电压。不同平台 ADC 特性不同接线方式也不同图示见 Battery readme 的 Example wiring 章节ESP8266单个 100kΩ 电阻ESP8266 只有唯一模拟输入引脚A0输入范围为 0–1V无衰减选项见 readVoltage() 源码注释。文档要求以 100kΩ 电阻将电池正极连接至A0即构成上拉式分压采样。默认电压倍率Voltage Multiplier为4.2定义于 battery_defaults.h用于将 A0 采样的低电压换算回真实电池电压。ESP32含 S2/S3/C3 等等值分压电阻对ESP32 系列建议使用两个阻值相等的电阻构成分压器将电池正极 → R1 → 分压节点 → R2 → GND分压节点接入 ADC1 通道GPIO32–GPIO39默认 GPIO35见 battery_defaults.h。默认电压倍率为2.0对应两个等值电阻将电压对半分压的场景。配置参数详解以下参数表格完整继承自 Battery readme 的 Define Your Options 章节默认值与取值范围结合 battery_defaults.h 与 Battery.cpp 源码补充基础测量参数名称单位说明默认值USERMOD_BATTERY—在my_config.h中定义以启用本 usermod—USERMOD_BATTERY_MEASUREMENT_PIN—测量引脚ESP8266 默认A0ESP32 默认GPIO35A0 / 35USERMOD_BATTERY_MEASUREMENT_INTERVALms电池检测间隔3000030 秒USERMOD_BATTERY_INITIAL_DELAYms首次读取前的延时等待电压稳定1000010 秒USERMOD_BATTERY_{TYPE}_MIN_VOLTAGEV电池最低电压2.618650 标准USERMOD_BATTERY_{TYPE}_MAX_VOLTAGEV电池最高电压4.218650 标准USERMOD_BATTERY_{TYPE}_TOTAL_CAPACITYmAh并联所有电芯的容量总和—USERMOD_BATTERY_{TYPE}_CALIBRATION—校准偏移量微调单片机测得的电压0USERMOD_BATTERY_VOLTAGE_MULTIPLIER—分压比倍率ESP32 默认 2.0ESP8266 默认 4.2见左Auto-Off自动关机名称单位说明默认值USERMOD_BATTERY_AUTO_OFF_ENABLEDtrue/false启用自动关机trueUSERMOD_BATTERY_AUTO_OFF_THRESHOLD%0–100达到该阈值时主电源亮度关闭10源码中当autoOffEnabled (autoOffThreshold bat-getLevel())时调用turnOff()即bri 0; stateUpdated(CALL_MODE_DIRECT_CHANGE);见 Battery.cpp 与 Battery.cpp。Low-Power Indicator低电量指示名称单位说明默认值USERMOD_BATTERY_LOW_POWER_INDICATOR_ENABLEDtrue/false启用低电量指示trueUSERMOD_BATTERY_LOW_POWER_INDICATOR_PRESET预设 ID检测到低电量时播放的预设0USERMOD_BATTERY_LOW_POWER_INDICATOR_THRESHOLD%0–100达到该阈值时触发低电量指示20USERMOD_BATTERY_LOW_POWER_INDICATOR_DURATION秒播放该预设的时长5lowPowerIndicator()的实现逻辑为电量低于阈值时记录当前预设、applyPreset()切换到指示预设持续duration*1000毫秒后切回原预设并带有防抖逻辑——只有当电量回升到threshold 10重新激活阈值见 Battery.cpp以上才允许再次触发见 Battery.cpp。阈值联动约束源码级细节setAutoOffThreshold()与setLowPowerIndicatorThreshold()之间存在相互钳制当低电量指示启用时自动关机阈值会被强制设为低电量阈值 - 1保证先提示后关机当自动关机启用时低电量指示阈值会被钳制为不小于自动关机阈值 1且下限为 5见 Battery.cpp 与 Battery.cpp。所有参数均可在运行时通过 Usermods 设置页面/settings/um动态调整无需重新编译编译期宏仅用于设定默认值。电池类型预配置每种电池类型可独立在my_config.h中预配置来自 Battery readme 的 Define Your Options 末尾表格名称别名my_config.h示例Lithium PolymerlipoLi-PoUSERMOD_BATTERY_lipo_MIN_VOLTAGELithium IonenlionLi-IonUSERMOD_BATTERY_lion_TOTAL_CAPACITY对应宏名规则为USERMOD_BATTERY_{小写类型}_{参数}例如USERMOD_BATTERY_lion_MIN_VOLTAGE。各类型默认电压区间定义于 battery_defaults.hUnkown通用3.3V – 4.2V保守默认LiPo3.2V – 4.2V注释特别提醒 1S LiPo 不应放电低于 3VLi-Ion2.6V – 4.2V18650 电芯标准。工厂模式与电压-电量映射自 2024-04-30 版本起模块采用工厂模式设计UMBattery为抽象基类定义于 UMBattery.hUnkownUMBattery、LipoUMBattery、LionUMBattery继承实现各自的mapVoltage()放电曲线Li-Ion / Unkown简单的线性映射(v - min) * 100 / (max - min)LiPo按三段曲线近似真实放电特性——0–40% 区间快速下降段、40–90% 近线性段、90–105% 缓降段见 LipoUMBattery.h。setup()中根据cfg.type实例化对应类型并注入配置见 Battery.cpp这就是 readme 提到的工厂模式便于扩展自定义电池类型。电压校准Calibration校准值是在最终计算电压经电压倍率Voltage Multiplier缩放之后再叠加的一个偏移量见 Battery readme 的 Calibration 章节最终电压 ADC 原始电压 ÷ ADC 精度 × 电压倍率 校准值ESP32 使用校准后的毫伏读数analogReadMilliVolts()ESP8266 使用analogRead()/1023见 Battery.cpp。校准值可以是正数或负数用于补偿分压电阻公差与 ESP ADC 固有测量误差。它既可在 Usermods 设置页面设置也可在编译期于my_config.h或platformio_override.ini中指定。读数平滑滤波由于 ESP32 的 ADC 单次读数波动较大loop()中对电压采用指数平滑EMA滤波平滑系数alpha默认0.1USERMOD_BATTERY_AVERAGING_ALPHAfloat filteredVoltage bat-getVoltage() alpha * (rawValue - bat-getVoltage());见 Battery.cpp。此外USERMOD_BATTERY_INITIAL_DELAY默认 10 秒保证上电电压稳定后才进行首次测量避免开机瞬间读数偏低loop()中的initialDelay处理见 Battery.cpp。重要务必核对电池规格所有电池都不相同在配置MIN_VOLTAGE/MAX_VOLTAGE前务必查阅你所用电芯的官方数据手册。以 readme 中引用的 Molicel INR18650-M35A3500mAh 10A 锂离子电池为例电池规格表数值对应配置项容量3500mAh 12.5Wh—最小容量3350mAh 11.9Wh—额定电压3.6V – 3.7V—充电截止电压4.2V ± 0.05USERMOD_BATTERY_MAX_VOLTAGE放电截止电压2.5VUSERMOD_BATTERY_MIN_VOLTAGE最大持续放电电流10A (10000mA)—最大充电电流1.7A (1700mA)—表格完整继承自 Battery readme 的 Important 章节。设置错误的电压区间会导致电量百分比严重失真甚至因过度放电损坏电池。另外注意 UMBattery.h 中setLevel()将电量钳制在 0–110% 之间setMaxVoltage()强制不低于minVoltage 0.5VLiPo 为 0.7VLi-Ion 为 1.0V这是基类对配置合法性的内置保护。系统集成JSON API、MQTT 与 Home AssistantJSON API 与信息界面模块通过addToJsonInfo()在/json/info的u对象中暴露Battery level含%、Battery voltage含V与Next update秒三个字段初始化完成前显示init引脚无效时显示n/a / invalid GPIO见 Battery.cpp。同时通过addToJsonState()/addToConfig()把min-voltage、max-voltage、calibration、voltage-multiplier、interval、auto-off、indicator等配置暴露到 JSON供 Usermods 设置页与外部客户端读写见 Battery.cpp。电压值经dot2round()保留两位小数显示。MQTT 上报启用 MQTT 后未定义WLED_DISABLE_MQTT每次测量会发布两个主题{mqttDeviceTopic}/battery—— 电池百分比整数{mqttDeviceTopic}/voltage—— 电池电压浮点。见 Battery.cpp。Home Assistant 自动发现当配置项HA-discovery开启后MQTT 连接建立时会通过onMqttConnect()为 Battery 与 Voltage 各注册一个 Home Assistant MQTT 传感器entity_category diagnostic过期时间 1800 秒见 Battery.cpp可在 Home Assistant 中直接以实体形式呈现电池状态。引脚管理与引脚复用检测在 ESP32 上setup()会通过PinManager::allocatePin(batteryPin, false, PinOwner::UM_Battery)申请 ADC 引脚申请失败被其他外设占用或非 ADC 引脚时batteryPin被置为-1并停止测量在设置页修改引脚后还会先deallocatePin再重新setup()见 Battery.cpp 与 Battery.cpp。PinOwner::UM_Battery对应 usermod ID 18定义于 const.h 与 pin_manager.h。变更日志2021 – 2024完整变更记录见 Battery readme 的 Change Log 章节要点如下2024-08-19改进 MQTT 支持新增电池百分比与电压 MQTT topic2024-05-11文档更新2024-04-30引入工厂模式便于扩展自定义电池类型首测延时以等待上电电压稳定2023-01-04支持 LiPo 可充电电池-D USERMOD_BATTERY_USE_LIPO改进 ESP32读取校准电压修复配置保存问题此前测量引脚与电压上下限会丢失2022-12-25新增 auto-off、low-power-indication、校准/偏移字段、供其他 usermod 交互的 getter/setter2021-09-02信息界面新增Battery voltage、新增电路图、MQTT 上报电压2021-08-15默认最低电压改为 2.6V18650 标准2021-08-10模块创建。排查建议信息界面显示n/a / invalid GPIO检查测量引脚是否配置为 ADC1 通道ESP32GPIO32–39或该引脚已被其他外设占用导致PinManager分配失败电量百分比长期异常核对电池数据手册中的充放电截止电压并在设置页调整min-voltage/max-voltage与calibration首次读数明显偏低这是上电瞬间电压未稳定所致USERMOD_BATTERY_INITIAL_DELAY默认 10 秒即为此设计请勿随意改小读数波动大增大USERMOD_BATTERY_AVERAGING_ALPHA默认 0.1以外的滤波相关参数需重新编译波动剧烈时优先检查分压电阻焊点与电池接触。相关接线参考资料来自 Battery readme 的 Useful Links 章节均为 ESP8266 A0 分压采样的实践文章lazyzero 的 WeMos D1 mini A0 采样指南、arduinodiy 的 LiPo 电压监测 ThingSpeak 教程。如需更深的 ADC 细节可参考 ESP-IDF 官方 ADC 文档中关于 ADC1 通道与衰减配置的说明。【免费下载链接】WLEDControl WS2812B and many more types of digital RGB LEDs with an ESP32 over WiFi!项目地址: https://gitcode.com/GitHub_Trending/wl/WLED创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 WLED Battery Usermod 实战指南：用 ESP8266/ESP32 实现电池电压监测、电量百分比、自动关机与低电量指示
WLED Battery Usermod 实战指南用 ESP8266/ESP32 实现电池电压监测、电量百分比、自动关机与低电量指示【免费下载链接】WLEDControl WS2812B and many more types of digital RGB LEDs with an ESP32 over WiFi!项目地址: https://gitcode.com/GitHub_Trending/wl/WLED本文是 WLED 项目中 Battery usermod 的完整技术指南。该模块让以电池供电的 ESP8266 / ESP32 LED 控制器能够实时监测电池电压、计算剩余电量百分比并具备可配置阈值的自动关机Auto-Off与低电量指示Low-Power Indicator能力同时深度集成 WLED 的 JSON API、MQTT 与 Home Assistant 自动发现。读完本文你将掌握 Battery usermod 的接线方案、编译配置、运行时参数调优与源码级工作原理可直接为你的便携 LED 项目灯带、灯笼、露营灯、可穿戴设备等部署一套可靠的电源监测方案。功能特性总览根据 Battery readme 与 Battery.cpp该 usermod 提供四项核心能力当前电池电压显示通过 ADC 采样计算电池电压显示在 WLED 信息界面与 JSON API 中电池电量百分比根据电池类型对应的电压-电量映射曲线mapVoltage计算 0–100% 电量自动关机Auto-Off电量跌至设定阈值时自动将 WLED 主亮度bri置 0保护电池避免过度放电低电量指示Low-Power Indicator电量低于阈值时自动播放预设Preset若干秒提示用户充电播完再切回之前的预设。此外自 2021-09-02 起该模块支持 MQTT 上报电压2024-08-19 版本又增加了电池百分比与电压两个 MQTT topic并支持 Home Assistant MQTT 自动发现详见文末变更日志。安装与启用WLED 采用 PlatformIO 构建usermod 有两种启用方式见 Battery readme 的 Installation 章节方式一platformio_override.ini推荐参见 官方示例截图在platformio_override.ini或platformio.ini中于custom_usermods 后追加Battery[platformio] default_envs esp32dev_custom [env:esp32dev_custom] extends env:esp32dev custom_usermods Battery build_flags ${env:esp32dev.build_flags} -D USERMOD_BATTERYcustom_usermods是 WLED 构建系统加载 usermod 库的入口见 platformio.ini构建脚本 pio-scripts/load_usermods.py 会解析该选项并把对应 usermod 目录如usermods/Battery/其下有 library.json 描述构建信息加入编译。你还可以在build_flags中直接传递配置宏例如设置测量引脚与采样间隔build_flags ${env:esp32dev.build_flags} -D USERMOD_BATTERY -D USERMOD_BATTERY_MEASUREMENT_PIN35 -D USERMOD_BATTERY_MEASUREMENT_INTERVAL3000方式二my_config.h将wled00/my_config_sample.h复制为wled00/my_config.h启用WLED_USE_MY_CONFIG后在文件中定义USERMOD_BATTERY即可将该 usermod 纳入编译源码注释中同样说明了这一点参见 Battery.cpp 对my_config.h的引用。配置示例见 my_config.h 配置截图。提示USERMOD_BATTERY只是编译开关真正把 usermod 实例挂入 WLED 运行循环的是源码末尾的static UsermodBattery battery; REGISTER_USERMOD(battery);见 Battery.cppREGISTER_USERMOD宏定义在 wled00/fcn_declare.h。典型接线方案Battery usermod 通过单片机的 ADC 读取电池电压。不同平台 ADC 特性不同接线方式也不同图示见 Battery readme 的 Example wiring 章节ESP8266单个 100kΩ 电阻ESP8266 只有唯一模拟输入引脚A0输入范围为 0–1V无衰减选项见 readVoltage() 源码注释。文档要求以 100kΩ 电阻将电池正极连接至A0即构成上拉式分压采样。默认电压倍率Voltage Multiplier为4.2定义于 battery_defaults.h用于将 A0 采样的低电压换算回真实电池电压。ESP32含 S2/S3/C3 等等值分压电阻对ESP32 系列建议使用两个阻值相等的电阻构成分压器将电池正极 → R1 → 分压节点 → R2 → GND分压节点接入 ADC1 通道GPIO32–GPIO39默认 GPIO35见 battery_defaults.h。默认电压倍率为2.0对应两个等值电阻将电压对半分压的场景。配置参数详解以下参数表格完整继承自 Battery readme 的 Define Your Options 章节默认值与取值范围结合 battery_defaults.h 与 Battery.cpp 源码补充基础测量参数名称单位说明默认值USERMOD_BATTERY—在my_config.h中定义以启用本 usermod—USERMOD_BATTERY_MEASUREMENT_PIN—测量引脚ESP8266 默认A0ESP32 默认GPIO35A0 / 35USERMOD_BATTERY_MEASUREMENT_INTERVALms电池检测间隔3000030 秒USERMOD_BATTERY_INITIAL_DELAYms首次读取前的延时等待电压稳定1000010 秒USERMOD_BATTERY_{TYPE}_MIN_VOLTAGEV电池最低电压2.618650 标准USERMOD_BATTERY_{TYPE}_MAX_VOLTAGEV电池最高电压4.218650 标准USERMOD_BATTERY_{TYPE}_TOTAL_CAPACITYmAh并联所有电芯的容量总和—USERMOD_BATTERY_{TYPE}_CALIBRATION—校准偏移量微调单片机测得的电压0USERMOD_BATTERY_VOLTAGE_MULTIPLIER—分压比倍率ESP32 默认 2.0ESP8266 默认 4.2见左Auto-Off自动关机名称单位说明默认值USERMOD_BATTERY_AUTO_OFF_ENABLEDtrue/false启用自动关机trueUSERMOD_BATTERY_AUTO_OFF_THRESHOLD%0–100达到该阈值时主电源亮度关闭10源码中当autoOffEnabled (autoOffThreshold bat-getLevel())时调用turnOff()即bri 0; stateUpdated(CALL_MODE_DIRECT_CHANGE);见 Battery.cpp 与 Battery.cpp。Low-Power Indicator低电量指示名称单位说明默认值USERMOD_BATTERY_LOW_POWER_INDICATOR_ENABLEDtrue/false启用低电量指示trueUSERMOD_BATTERY_LOW_POWER_INDICATOR_PRESET预设 ID检测到低电量时播放的预设0USERMOD_BATTERY_LOW_POWER_INDICATOR_THRESHOLD%0–100达到该阈值时触发低电量指示20USERMOD_BATTERY_LOW_POWER_INDICATOR_DURATION秒播放该预设的时长5lowPowerIndicator()的实现逻辑为电量低于阈值时记录当前预设、applyPreset()切换到指示预设持续duration*1000毫秒后切回原预设并带有防抖逻辑——只有当电量回升到threshold 10重新激活阈值见 Battery.cpp以上才允许再次触发见 Battery.cpp。阈值联动约束源码级细节setAutoOffThreshold()与setLowPowerIndicatorThreshold()之间存在相互钳制当低电量指示启用时自动关机阈值会被强制设为低电量阈值 - 1保证先提示后关机当自动关机启用时低电量指示阈值会被钳制为不小于自动关机阈值 1且下限为 5见 Battery.cpp 与 Battery.cpp。所有参数均可在运行时通过 Usermods 设置页面/settings/um动态调整无需重新编译编译期宏仅用于设定默认值。电池类型预配置每种电池类型可独立在my_config.h中预配置来自 Battery readme 的 Define Your Options 末尾表格名称别名my_config.h示例Lithium PolymerlipoLi-PoUSERMOD_BATTERY_lipo_MIN_VOLTAGELithium IonenlionLi-IonUSERMOD_BATTERY_lion_TOTAL_CAPACITY对应宏名规则为USERMOD_BATTERY_{小写类型}_{参数}例如USERMOD_BATTERY_lion_MIN_VOLTAGE。各类型默认电压区间定义于 battery_defaults.hUnkown通用3.3V – 4.2V保守默认LiPo3.2V – 4.2V注释特别提醒 1S LiPo 不应放电低于 3VLi-Ion2.6V – 4.2V18650 电芯标准。工厂模式与电压-电量映射自 2024-04-30 版本起模块采用工厂模式设计UMBattery为抽象基类定义于 UMBattery.hUnkownUMBattery、LipoUMBattery、LionUMBattery继承实现各自的mapVoltage()放电曲线Li-Ion / Unkown简单的线性映射(v - min) * 100 / (max - min)LiPo按三段曲线近似真实放电特性——0–40% 区间快速下降段、40–90% 近线性段、90–105% 缓降段见 LipoUMBattery.h。setup()中根据cfg.type实例化对应类型并注入配置见 Battery.cpp这就是 readme 提到的工厂模式便于扩展自定义电池类型。电压校准Calibration校准值是在最终计算电压经电压倍率Voltage Multiplier缩放之后再叠加的一个偏移量见 Battery readme 的 Calibration 章节最终电压 ADC 原始电压 ÷ ADC 精度 × 电压倍率 校准值ESP32 使用校准后的毫伏读数analogReadMilliVolts()ESP8266 使用analogRead()/1023见 Battery.cpp。校准值可以是正数或负数用于补偿分压电阻公差与 ESP ADC 固有测量误差。它既可在 Usermods 设置页面设置也可在编译期于my_config.h或platformio_override.ini中指定。读数平滑滤波由于 ESP32 的 ADC 单次读数波动较大loop()中对电压采用指数平滑EMA滤波平滑系数alpha默认0.1USERMOD_BATTERY_AVERAGING_ALPHAfloat filteredVoltage bat-getVoltage() alpha * (rawValue - bat-getVoltage());见 Battery.cpp。此外USERMOD_BATTERY_INITIAL_DELAY默认 10 秒保证上电电压稳定后才进行首次测量避免开机瞬间读数偏低loop()中的initialDelay处理见 Battery.cpp。重要务必核对电池规格所有电池都不相同在配置MIN_VOLTAGE/MAX_VOLTAGE前务必查阅你所用电芯的官方数据手册。以 readme 中引用的 Molicel INR18650-M35A3500mAh 10A 锂离子电池为例电池规格表数值对应配置项容量3500mAh 12.5Wh—最小容量3350mAh 11.9Wh—额定电压3.6V – 3.7V—充电截止电压4.2V ± 0.05USERMOD_BATTERY_MAX_VOLTAGE放电截止电压2.5VUSERMOD_BATTERY_MIN_VOLTAGE最大持续放电电流10A (10000mA)—最大充电电流1.7A (1700mA)—表格完整继承自 Battery readme 的 Important 章节。设置错误的电压区间会导致电量百分比严重失真甚至因过度放电损坏电池。另外注意 UMBattery.h 中setLevel()将电量钳制在 0–110% 之间setMaxVoltage()强制不低于minVoltage 0.5VLiPo 为 0.7VLi-Ion 为 1.0V这是基类对配置合法性的内置保护。系统集成JSON API、MQTT 与 Home AssistantJSON API 与信息界面模块通过addToJsonInfo()在/json/info的u对象中暴露Battery level含%、Battery voltage含V与Next update秒三个字段初始化完成前显示init引脚无效时显示n/a / invalid GPIO见 Battery.cpp。同时通过addToJsonState()/addToConfig()把min-voltage、max-voltage、calibration、voltage-multiplier、interval、auto-off、indicator等配置暴露到 JSON供 Usermods 设置页与外部客户端读写见 Battery.cpp。电压值经dot2round()保留两位小数显示。MQTT 上报启用 MQTT 后未定义WLED_DISABLE_MQTT每次测量会发布两个主题{mqttDeviceTopic}/battery—— 电池百分比整数{mqttDeviceTopic}/voltage—— 电池电压浮点。见 Battery.cpp。Home Assistant 自动发现当配置项HA-discovery开启后MQTT 连接建立时会通过onMqttConnect()为 Battery 与 Voltage 各注册一个 Home Assistant MQTT 传感器entity_category diagnostic过期时间 1800 秒见 Battery.cpp可在 Home Assistant 中直接以实体形式呈现电池状态。引脚管理与引脚复用检测在 ESP32 上setup()会通过PinManager::allocatePin(batteryPin, false, PinOwner::UM_Battery)申请 ADC 引脚申请失败被其他外设占用或非 ADC 引脚时batteryPin被置为-1并停止测量在设置页修改引脚后还会先deallocatePin再重新setup()见 Battery.cpp 与 Battery.cpp。PinOwner::UM_Battery对应 usermod ID 18定义于 const.h 与 pin_manager.h。变更日志2021 – 2024完整变更记录见 Battery readme 的 Change Log 章节要点如下2024-08-19改进 MQTT 支持新增电池百分比与电压 MQTT topic2024-05-11文档更新2024-04-30引入工厂模式便于扩展自定义电池类型首测延时以等待上电电压稳定2023-01-04支持 LiPo 可充电电池-D USERMOD_BATTERY_USE_LIPO改进 ESP32读取校准电压修复配置保存问题此前测量引脚与电压上下限会丢失2022-12-25新增 auto-off、low-power-indication、校准/偏移字段、供其他 usermod 交互的 getter/setter2021-09-02信息界面新增Battery voltage、新增电路图、MQTT 上报电压2021-08-15默认最低电压改为 2.6V18650 标准2021-08-10模块创建。排查建议信息界面显示n/a / invalid GPIO检查测量引脚是否配置为 ADC1 通道ESP32GPIO32–39或该引脚已被其他外设占用导致PinManager分配失败电量百分比长期异常核对电池数据手册中的充放电截止电压并在设置页调整min-voltage/max-voltage与calibration首次读数明显偏低这是上电瞬间电压未稳定所致USERMOD_BATTERY_INITIAL_DELAY默认 10 秒即为此设计请勿随意改小读数波动大增大USERMOD_BATTERY_AVERAGING_ALPHA默认 0.1以外的滤波相关参数需重新编译波动剧烈时优先检查分压电阻焊点与电池接触。相关接线参考资料来自 Battery readme 的 Useful Links 章节均为 ESP8266 A0 分压采样的实践文章lazyzero 的 WeMos D1 mini A0 采样指南、arduinodiy 的 LiPo 电压监测 ThingSpeak 教程。如需更深的 ADC 细节可参考 ESP-IDF 官方 ADC 文档中关于 ADC1 通道与衰减配置的说明。【免费下载链接】WLEDControl WS2812B and many more types of digital RGB LEDs with an ESP32 over WiFi!项目地址: https://gitcode.com/GitHub_Trending/wl/WLED创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考