2026/9/13 13:13:11
FEATURED · 精选文章 
WLED INA226 Usermod 实战通过 I2C 读取电压、电流、功率并发布到 MQTT【免费下载链接】WLEDControl WS2812B and many more types of digital RGB LEDs with an ESP32 over WiFi!项目地址: https://gitcode.com/GitHub_Trending/wl/WLED本文围绕 WLED 仓库中的 INA226 Usermodusermods/INA226_v2展开完整覆盖其全部运行时配置参数、采样次数与转换时间的组合选择方法、编译开关与编译期默认值并结合 INA226_v2.cpp 源码解析连续/触发两种测量模式、MQTT 发布阈值与 Home Assistant 自动发现等底层实现帮助你在 WLED 固件中为 ESP32 设备加上一路真实的电源监测通道。功能概述与工作原理该 Usermod 通过 I2C 总线读取 INA226 高精度电流监测芯片的数据在 WLED 的 Info 面板和 MQTT 中输出五类读数电流CurrentA电压VoltageV功率PowerW分流器压降Shunt VoltagemV溢出状态Overflow布尔值从源码看 INA226 通过测量分流电阻两端的差分电压得到电流芯片内部利用校准寄存器Calibration Register把该差分测量换算成电流值功率则由电流乘以总线电压算出。Usermod 在 INA226_v2.cpp 的initializeINA226()中通过setResistorRange(分流阻值(Ω), 量程(A))完成校准这两个值正是运行时参数ShuntResistor与CurrentRange的来源。芯片库依赖声明在 library.json 中使用wollewald/INA226_WE约 1.2.9 版本并设置了libArchive: false以强制直接链接到可执行文件这是 WLED 所有 usermod 的硬性要求构建脚本 load_usermods.py 会校验该字段缺失则构建报错退出。编译启用custom_usermods 与 platformio_override.ini启用方式是在platformio_override.ini的custom_usermods中加入INA226[env:ina226_example] extends env:esp32dev custom_usermods ${env:esp32dev.custom_usermods} INA226 build_flags ${env:esp32dev.build_flags} ; -D USERMOD_INA226_DEBUG ; -- add a debug status to the info modal这里写INA226而非目录名INA226_v2即可因为构建脚本 load_usermods.py 的find_usermod()会依次尝试名称、名称_v2、usermod_v2_名称三种目录命名最终命中usermods/INA226_v2/并生成symlink://依赖。仓库中同样内置了 platformio_override.sample.ini 和示例性的 platformio_override.usermods.ini 可作参考custom_usermods *则会自动展开usermods/下所有带library.json的模块。可选的-D USERMOD_INA226_DEBUG宏会在 Info 面板追加调试信息包括最近一次循环时间戳、I2C 状态码、实际生效的采样数、转换时间、预期单次读数耗时以及当前工作模式见下文“数据显示与排错”。运行时参数Usermod 设置页的 12 项配置以下参数均可在 WLED 网页的 Usermod 菜单中配置并保存到设备配置源码对应addToConfig()INA226_v2.cpp参数说明源码中的取值约束Enabled启用/禁用该 usermod。默认值由编译宏INA226_ENABLED_DEFAULT决定默认false—I2CAddressI2C 地址十进制。默认 64即 0x40对应编译宏INA226_ADDRESSCheckInterval两次读数之间的间隔单位秒。应大于“采样数 × 转换时间”所需的读数时长读入时校验必须在 1600 秒之间否则回落到编译默认值INA226_v2.cppINASamples每次测量使用的采样数11024。数值越大精度越高、耗时越长非合法值会被修正为最接近的合法档位getAverageEnum见下文INAConversionTime单次 ADC 转换时间μs。越大越精确、耗时越长同上由getConversionTimeEnum修正Decimals输出保留的小数位数05超出范围回落为默认 2 位_decimalFactor 100ShuntResistor分流电阻值单位毫欧。R100 标贴应写100R010 写10读入后 ×1000 转为微欧存储非正值回落编译默认值CurrentRange预期最大电流单位 mA如 5 A 填5000为 0 或超过 20000 mA 时回落编译默认值CurrentOffset电流偏移量单位 mA从原始读数中减去。用于补偿传感器固定偏差。默认 0配置缺失时使用编译宏INA226_CURRENT_OFFSET_MAMqttPublish开启/关闭 MQTT 发布—MqttPublishAlways无论数值是否变化都发布—MqttHomeAssistantDiscovery开启 Home Assistant 自动发现—从 readFromConfig() 的实现看任何一项解析失败都会把configComplete置为 false此时保留上一组有效值而当配置完整且已初始化过_initDone时会立即重新执行initializeINA226()并重建 MQTT 发现意味着保存设置页后参数立即生效无需重启。理解采样数与转换时间一张完整对照表INA226 内置可编程 ADC转换时间Conversion Time与平均采样数Average Samples共同决定单次读数的精度与耗时。INASamples与INAConversionTime两个参数就是在这两个维度上做选择。完整的组合耗时对照表单位 ms即 转换时间 × 采样数如下转换时间 (μs)1 样本4 样本16 样本64 样本128 样本256 样本512 样本1024 样本1400.281.124.4817.9235.8471.68143.36286.722040.4081.6326.52826.11252.224104.448208.896417.7923320.6642.65610.62442.49684.992169.984339.968679.9365881.1764.70418.81675.264150.528301.056602.1121204.22411002.28.835.2140.8281.6563.21126.42252.821164.23216.92867.712270.848541.6961083.3922166.7844333.56841568.31233.248132.992531.9681063.9362127.8724255.7448511.488824416.48865.952263.8081055.2322110.4644220.9288441.85616883.712选择原则是在CheckInterval之内保证读完一次测量同时取得精度与速度的平衡。文档给出的示例是若希望每 5 秒获得新读数CheckInterval5可选256 样本 4156 μs实际单次读数约需 2.1 秒留出足够余量。值得注意的是源码中 Debug 面板显示“预期读数时间”的公式是2 × 转换时间 × 采样数INA226_v2.cpp即上表数值再乘 2 —— 这与上节示例中 256 × 4156 μs ≈ 2.1 s 的结论一致说明表中 2127.872 ms 应理解为“保守估计”的读数周期预算。选型时请以 Debug 面板给出的 expected sample time 为准确保其小于CheckInterval。另外若输入的不是合法档位例如填了 2000 样本或 9000 μsgetAverageEnum() / getConversionTimeEnum() 会“向下吸附”到不超过该值的最高合法档位不会报错。功耗角度触发模式的 20 秒门槛当CheckInterval大于 20 秒时Usermod 会把 INA226 切换为triggered触发读数模式芯片只在实际测量期间耗电此时“转换时间 × 平均采样数”决定了每个周期内芯片保持上电的时长。源码中的判断点非常明确initializeINA226()if (_checkIntervalMs 20000) { _isTriggeredOperationMode true; _ina226-setMeasureMode(TRIGGERED); } else { _isTriggeredOperationMode false; _ina226-setMeasureMode(CONTINUOUS); }两种工作模式的底层流程loop()每轮根据模式分派到两条不同的代码路径INA226_v2.cpp且 LED 正在刷新strip.isUpdating()时会跳过本轮避免干扰渲染。连续模式CheckInterval 20 s芯片持续采样handleContinuousMode()只需在到达CheckInterval后直接调用fetchAndPushValues()读取寄存器即可无额外延迟。触发模式CheckInterval ≥ 20 shandleTriggeredMode()的流程是非阻塞的两段式到达_checkIntervalMs时调用startSingleMeasurementNoWait()发起单次测量置位_measurementTriggered之后每 400 ms 轮询一次isBusy()芯片忙则继续等不忙则执行fetchAndPushValues()并复位标志。这种设计避免了忙等把 I2C 读取均匀摊薄到主循环中。fetchAndPushValues()中还处理了两类边界I2C 错误码非零时直接返回面板会显示 An error occurred所有数值在发布前先经truncateDecimals()按Decimals截断电流则先减去CurrentOffsetINA226_v2.cpp。MQTT 发布与 Home Assistant 自动发现开启MqttPublish后每个读数周期都会通过mqttPublishIfChanged()检查是否需要发布。从源码看浮点型传感器并非只要变化就发而是有最小变化阈值INA226_v2.cpp主题设备主题/之后类型单位最小变化阈值current传感器A0.01voltage传感器V0.01power传感器W0.1shunt_voltage传感器V0.01overflow布尔true/false—状态翻转其中shunt_voltage以伏特发布内部以 mV 存储发布前除以 1000注释标明这是为了向后兼容。MqttPublishAlways打开后则跳过阈值判断无条件发布。开启MqttHomeAssistantDiscovery后MQTT 连接建立时会发布 5 个自动发现配置mqttCreateHassSensor()/mqttCreateHassBinarySensor()INA226_v2.cpphomeassistant/sensor/clientId/{Current,Voltage,Power,Shunt Voltage}/config与homeassistant/binary_sensor/clientId/Overflow/config。载荷中包含unique_idclientId 名称、device_classcurrent/voltage、unit_of_measurement、expire_after: 180030 分钟无消息判定离线以及 device 块厂商、型号、固件版本、identifierswled-sensor-clientIdHome Assistant 侧无需手工建卡即可接入。编译期默认值让设备首次上电即可用六个参数可以通过-D构建标志在编译期覆盖默认值适合做“出厂即正确”的板级定制免去了首次手动配置构建标志默认值单位说明INA226_ADDRESS0x40—INA226 的 I2C 地址INA226_SHUNT_MICRO_OHMS1000000μΩ分流电阻值1 000 000 μΩ 1 ΩINA226_DEFAULT_CURRENT_RANGE1000mA预期最大电流1000 mA 1 AINA226_CURRENT_OFFSET_MA0mA从读数中减去的电流偏移INA226_CHECK_INTERVAL_MS60000ms首次上电时的默认读数间隔INA226_ENABLED_DEFAULTfalse—首次上电是否启用该 usermod这些默认值在源码顶部以#ifndef保护的形式定义INA226_v2.cpp并在构造函数中作为初始值载入未定义时即上表默认值。以一块等效分流 2.888 mΩ、量程 10 A、偏移 -118 mA、1 秒轮询且默认启用的板子为例[env:my_board] extends env:esp32dev custom_usermods ${env:esp32dev.custom_usermods} INA226 build_flags ${env:esp32dev.build_flags} -D INA226_ENABLED_DEFAULTtrue -D INA226_SHUNT_MICRO_OHMS2888 -D INA226_DEFAULT_CURRENT_RANGE10000 -D INA226_CURRENT_OFFSET_MA-118 -D INA226_CHECK_INTERVAL_MS1000所有编译期默认值都可以在运行时通过 Usermod 设置页再次修改并持久化-D仅影响“无配置时的初始状态”。数据显示与排错要点Info 面板addToJsonInfo()在u节点下固定输出五项格式为数值 单位INA226_v2.cppCurrent … A、Voltage … V、Power … W、Shunt Voltage Drop … mV、Overflow … true/false从未读取过_lastLoopCheck 0例如 Enabled 未打开时五项均显示 Not read yetI2C 读取出错时五项显示 An error occurred排错时建议按以下顺序检查定义USERMOD_INA226_DEBUG重新编译Info 面板会多出INA226 last loop / last status / average samples / conversion time / expected sample time / mode / triggered等数组其中 last status 非 0 即 I2C 层错误常见原因是地址不对或接线问题核对INASamples × INAConversionTime对应的预期读数时间是否小于CheckInterval否则触发模式下会长期停留在 waiting for measurement若数值稳定偏大或偏小用CurrentOffset做线性补偿该值可以为负Overflow 为 true 表示测量超出量程检查ShuntResistor与CurrentRange是否与硬件实际一致——校准寄存器直接由这两者决定。小结INA226 Usermod 用一套简洁的参数体系打通了“硬件校准分流阻值 量程→ ADC 时序采样数 转换时间→ 读数节奏CheckInterval 与连续/触发模式→ 数据出口Info JSON MQTT HA 发现”的完整链路运行时 12 项参数全部可在设置页热更新6 个-D编译宏保证设备首启即正确USERMOD_INA226_DEBUG则提供了定位 I2C 与时序问题的调试抓手。更多注册背景可参考 const.h 中USERMOD_ID_INA226ID 50的定义更多 usermod 组织方式与构建约定见 usermods/readme.md。【免费下载链接】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 INA226 Usermod 实战：通过 I2C 读取电压、电流、功率并发布到 MQTT
WLED INA226 Usermod 实战通过 I2C 读取电压、电流、功率并发布到 MQTT【免费下载链接】WLEDControl WS2812B and many more types of digital RGB LEDs with an ESP32 over WiFi!项目地址: https://gitcode.com/GitHub_Trending/wl/WLED本文围绕 WLED 仓库中的 INA226 Usermodusermods/INA226_v2展开完整覆盖其全部运行时配置参数、采样次数与转换时间的组合选择方法、编译开关与编译期默认值并结合 INA226_v2.cpp 源码解析连续/触发两种测量模式、MQTT 发布阈值与 Home Assistant 自动发现等底层实现帮助你在 WLED 固件中为 ESP32 设备加上一路真实的电源监测通道。功能概述与工作原理该 Usermod 通过 I2C 总线读取 INA226 高精度电流监测芯片的数据在 WLED 的 Info 面板和 MQTT 中输出五类读数电流CurrentA电压VoltageV功率PowerW分流器压降Shunt VoltagemV溢出状态Overflow布尔值从源码看 INA226 通过测量分流电阻两端的差分电压得到电流芯片内部利用校准寄存器Calibration Register把该差分测量换算成电流值功率则由电流乘以总线电压算出。Usermod 在 INA226_v2.cpp 的initializeINA226()中通过setResistorRange(分流阻值(Ω), 量程(A))完成校准这两个值正是运行时参数ShuntResistor与CurrentRange的来源。芯片库依赖声明在 library.json 中使用wollewald/INA226_WE约 1.2.9 版本并设置了libArchive: false以强制直接链接到可执行文件这是 WLED 所有 usermod 的硬性要求构建脚本 load_usermods.py 会校验该字段缺失则构建报错退出。编译启用custom_usermods 与 platformio_override.ini启用方式是在platformio_override.ini的custom_usermods中加入INA226[env:ina226_example] extends env:esp32dev custom_usermods ${env:esp32dev.custom_usermods} INA226 build_flags ${env:esp32dev.build_flags} ; -D USERMOD_INA226_DEBUG ; -- add a debug status to the info modal这里写INA226而非目录名INA226_v2即可因为构建脚本 load_usermods.py 的find_usermod()会依次尝试名称、名称_v2、usermod_v2_名称三种目录命名最终命中usermods/INA226_v2/并生成symlink://依赖。仓库中同样内置了 platformio_override.sample.ini 和示例性的 platformio_override.usermods.ini 可作参考custom_usermods *则会自动展开usermods/下所有带library.json的模块。可选的-D USERMOD_INA226_DEBUG宏会在 Info 面板追加调试信息包括最近一次循环时间戳、I2C 状态码、实际生效的采样数、转换时间、预期单次读数耗时以及当前工作模式见下文“数据显示与排错”。运行时参数Usermod 设置页的 12 项配置以下参数均可在 WLED 网页的 Usermod 菜单中配置并保存到设备配置源码对应addToConfig()INA226_v2.cpp参数说明源码中的取值约束Enabled启用/禁用该 usermod。默认值由编译宏INA226_ENABLED_DEFAULT决定默认false—I2CAddressI2C 地址十进制。默认 64即 0x40对应编译宏INA226_ADDRESSCheckInterval两次读数之间的间隔单位秒。应大于“采样数 × 转换时间”所需的读数时长读入时校验必须在 1600 秒之间否则回落到编译默认值INA226_v2.cppINASamples每次测量使用的采样数11024。数值越大精度越高、耗时越长非合法值会被修正为最接近的合法档位getAverageEnum见下文INAConversionTime单次 ADC 转换时间μs。越大越精确、耗时越长同上由getConversionTimeEnum修正Decimals输出保留的小数位数05超出范围回落为默认 2 位_decimalFactor 100ShuntResistor分流电阻值单位毫欧。R100 标贴应写100R010 写10读入后 ×1000 转为微欧存储非正值回落编译默认值CurrentRange预期最大电流单位 mA如 5 A 填5000为 0 或超过 20000 mA 时回落编译默认值CurrentOffset电流偏移量单位 mA从原始读数中减去。用于补偿传感器固定偏差。默认 0配置缺失时使用编译宏INA226_CURRENT_OFFSET_MAMqttPublish开启/关闭 MQTT 发布—MqttPublishAlways无论数值是否变化都发布—MqttHomeAssistantDiscovery开启 Home Assistant 自动发现—从 readFromConfig() 的实现看任何一项解析失败都会把configComplete置为 false此时保留上一组有效值而当配置完整且已初始化过_initDone时会立即重新执行initializeINA226()并重建 MQTT 发现意味着保存设置页后参数立即生效无需重启。理解采样数与转换时间一张完整对照表INA226 内置可编程 ADC转换时间Conversion Time与平均采样数Average Samples共同决定单次读数的精度与耗时。INASamples与INAConversionTime两个参数就是在这两个维度上做选择。完整的组合耗时对照表单位 ms即 转换时间 × 采样数如下转换时间 (μs)1 样本4 样本16 样本64 样本128 样本256 样本512 样本1024 样本1400.281.124.4817.9235.8471.68143.36286.722040.4081.6326.52826.11252.224104.448208.896417.7923320.6642.65610.62442.49684.992169.984339.968679.9365881.1764.70418.81675.264150.528301.056602.1121204.22411002.28.835.2140.8281.6563.21126.42252.821164.23216.92867.712270.848541.6961083.3922166.7844333.56841568.31233.248132.992531.9681063.9362127.8724255.7448511.488824416.48865.952263.8081055.2322110.4644220.9288441.85616883.712选择原则是在CheckInterval之内保证读完一次测量同时取得精度与速度的平衡。文档给出的示例是若希望每 5 秒获得新读数CheckInterval5可选256 样本 4156 μs实际单次读数约需 2.1 秒留出足够余量。值得注意的是源码中 Debug 面板显示“预期读数时间”的公式是2 × 转换时间 × 采样数INA226_v2.cpp即上表数值再乘 2 —— 这与上节示例中 256 × 4156 μs ≈ 2.1 s 的结论一致说明表中 2127.872 ms 应理解为“保守估计”的读数周期预算。选型时请以 Debug 面板给出的 expected sample time 为准确保其小于CheckInterval。另外若输入的不是合法档位例如填了 2000 样本或 9000 μsgetAverageEnum() / getConversionTimeEnum() 会“向下吸附”到不超过该值的最高合法档位不会报错。功耗角度触发模式的 20 秒门槛当CheckInterval大于 20 秒时Usermod 会把 INA226 切换为triggered触发读数模式芯片只在实际测量期间耗电此时“转换时间 × 平均采样数”决定了每个周期内芯片保持上电的时长。源码中的判断点非常明确initializeINA226()if (_checkIntervalMs 20000) { _isTriggeredOperationMode true; _ina226-setMeasureMode(TRIGGERED); } else { _isTriggeredOperationMode false; _ina226-setMeasureMode(CONTINUOUS); }两种工作模式的底层流程loop()每轮根据模式分派到两条不同的代码路径INA226_v2.cpp且 LED 正在刷新strip.isUpdating()时会跳过本轮避免干扰渲染。连续模式CheckInterval 20 s芯片持续采样handleContinuousMode()只需在到达CheckInterval后直接调用fetchAndPushValues()读取寄存器即可无额外延迟。触发模式CheckInterval ≥ 20 shandleTriggeredMode()的流程是非阻塞的两段式到达_checkIntervalMs时调用startSingleMeasurementNoWait()发起单次测量置位_measurementTriggered之后每 400 ms 轮询一次isBusy()芯片忙则继续等不忙则执行fetchAndPushValues()并复位标志。这种设计避免了忙等把 I2C 读取均匀摊薄到主循环中。fetchAndPushValues()中还处理了两类边界I2C 错误码非零时直接返回面板会显示 An error occurred所有数值在发布前先经truncateDecimals()按Decimals截断电流则先减去CurrentOffsetINA226_v2.cpp。MQTT 发布与 Home Assistant 自动发现开启MqttPublish后每个读数周期都会通过mqttPublishIfChanged()检查是否需要发布。从源码看浮点型传感器并非只要变化就发而是有最小变化阈值INA226_v2.cpp主题设备主题/之后类型单位最小变化阈值current传感器A0.01voltage传感器V0.01power传感器W0.1shunt_voltage传感器V0.01overflow布尔true/false—状态翻转其中shunt_voltage以伏特发布内部以 mV 存储发布前除以 1000注释标明这是为了向后兼容。MqttPublishAlways打开后则跳过阈值判断无条件发布。开启MqttHomeAssistantDiscovery后MQTT 连接建立时会发布 5 个自动发现配置mqttCreateHassSensor()/mqttCreateHassBinarySensor()INA226_v2.cpphomeassistant/sensor/clientId/{Current,Voltage,Power,Shunt Voltage}/config与homeassistant/binary_sensor/clientId/Overflow/config。载荷中包含unique_idclientId 名称、device_classcurrent/voltage、unit_of_measurement、expire_after: 180030 分钟无消息判定离线以及 device 块厂商、型号、固件版本、identifierswled-sensor-clientIdHome Assistant 侧无需手工建卡即可接入。编译期默认值让设备首次上电即可用六个参数可以通过-D构建标志在编译期覆盖默认值适合做“出厂即正确”的板级定制免去了首次手动配置构建标志默认值单位说明INA226_ADDRESS0x40—INA226 的 I2C 地址INA226_SHUNT_MICRO_OHMS1000000μΩ分流电阻值1 000 000 μΩ 1 ΩINA226_DEFAULT_CURRENT_RANGE1000mA预期最大电流1000 mA 1 AINA226_CURRENT_OFFSET_MA0mA从读数中减去的电流偏移INA226_CHECK_INTERVAL_MS60000ms首次上电时的默认读数间隔INA226_ENABLED_DEFAULTfalse—首次上电是否启用该 usermod这些默认值在源码顶部以#ifndef保护的形式定义INA226_v2.cpp并在构造函数中作为初始值载入未定义时即上表默认值。以一块等效分流 2.888 mΩ、量程 10 A、偏移 -118 mA、1 秒轮询且默认启用的板子为例[env:my_board] extends env:esp32dev custom_usermods ${env:esp32dev.custom_usermods} INA226 build_flags ${env:esp32dev.build_flags} -D INA226_ENABLED_DEFAULTtrue -D INA226_SHUNT_MICRO_OHMS2888 -D INA226_DEFAULT_CURRENT_RANGE10000 -D INA226_CURRENT_OFFSET_MA-118 -D INA226_CHECK_INTERVAL_MS1000所有编译期默认值都可以在运行时通过 Usermod 设置页再次修改并持久化-D仅影响“无配置时的初始状态”。数据显示与排错要点Info 面板addToJsonInfo()在u节点下固定输出五项格式为数值 单位INA226_v2.cppCurrent … A、Voltage … V、Power … W、Shunt Voltage Drop … mV、Overflow … true/false从未读取过_lastLoopCheck 0例如 Enabled 未打开时五项均显示 Not read yetI2C 读取出错时五项显示 An error occurred排错时建议按以下顺序检查定义USERMOD_INA226_DEBUG重新编译Info 面板会多出INA226 last loop / last status / average samples / conversion time / expected sample time / mode / triggered等数组其中 last status 非 0 即 I2C 层错误常见原因是地址不对或接线问题核对INASamples × INAConversionTime对应的预期读数时间是否小于CheckInterval否则触发模式下会长期停留在 waiting for measurement若数值稳定偏大或偏小用CurrentOffset做线性补偿该值可以为负Overflow 为 true 表示测量超出量程检查ShuntResistor与CurrentRange是否与硬件实际一致——校准寄存器直接由这两者决定。小结INA226 Usermod 用一套简洁的参数体系打通了“硬件校准分流阻值 量程→ ADC 时序采样数 转换时间→ 读数节奏CheckInterval 与连续/触发模式→ 数据出口Info JSON MQTT HA 发现”的完整链路运行时 12 项参数全部可在设置页热更新6 个-D编译宏保证设备首启即正确USERMOD_INA226_DEBUG则提供了定位 I2C 与时序问题的调试抓手。更多注册背景可参考 const.h 中USERMOD_ID_INA226ID 50的定义更多 usermod 组织方式与构建约定见 usermods/readme.md。【免费下载链接】WLEDControl WS2812B and many more types of digital RGB LEDs with an ESP32 over WiFi!项目地址: https://gitcode.com/GitHub_Trending/wl/WLED创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
