Tasmota 通用 Modbus 电能表 JSON 配置完全指南寄存器映射、数据类型与三相扩展【免费下载链接】TasmotaAlternative firmware for ESP8266 and ESP32 based devices with easy configuration using webUI, OTA updates, automation using timers or rules, expandability and entirely local control over MQTT, HTTP, Serial or KNX. Full documentation at项目地址: https://gitcode.com/GitHub_Trending/ta/Tasmota导读本文基于 Tasmota 仓库中 energy_modbus_configs/configurations.md 与 value_pairs_description.md 两篇官方文档系统讲解通用 Modbus 电能表驱动xnrg_29_modbus源码见 xnrg_29_modbus.ino的 JSON 配置体系。读完本文你将掌握通过规则、脚本或文件系统三种方式加载 Modbus 配置、理解全部顶层参数与寄存器值对的含义、为 SDM230 / DDSU666 / PZEM014 / WE517 等常见电表套用开箱即用的官方配置并能为任意自定义 Modbus 电能设备编写寄存器映射实现本地化电能监测。一、通用 Modbus 电能驱动与配置数据的定位Tasmota 的通用 Modbus 电能驱动Generic Modbus energy meter支持单台三相设备或总线上三台同型号单相设备以三个相位呈现除浮点寄存器外还支持 Modbus 单/双整型寄存器通过一份 JSON 描述文件完成全部寄存器映射无需改动固件。驱动编译需要USE_ENERGY_SENSOR与USE_MODBUS_ENERGY两个宏参考 tasmota_configurations_ESP32.hESP32 默认启用与 tasmota_configurations.h其他平台可选约增加 5k 代码。这份 JSON 配置数据的官方参考即位于energy_modbus_configs/目录下的两个文档configurations.md现成设备配置清单默认配置 扩展配置value_pairs_description.mdJSON 键值对字段的完整语义说明。二、三种加载 Modbus JSON 的方式驱动在初始化时按固定优先级读取配置详见 xnrg_29_modbus.ino 的EnergyModbusReadRegisters()文件系统驱动优先级最高——若存在文件系统每个 ESP32 都有创建名为modbus.json的文件将所需 JSON 内容写入其中。源码中对应ENERGY_MODBUS_FILE宏定义/modbus.jsonxnrg_29_modbus.ino。规则驱动——将所需 JSON 内容复制到任意规则缓冲区前缀为rule3 on file#modbus do后缀为endon。脚本驱动——将 JSON 内容复制到脚本中前缀为y后缀为#。从源码的读取顺序看驱动依次尝试文件系统TfsLoadString(ENERGY_MODBUS_FILE)→ 规则RuleLoadFile(MODBUS)→ 脚本ScriptLoadSection(y)取第一个非空来源若 JSON 内容长度小于 7 个字符或解析失败则视为无效并放弃加载if (modbus.length() 7) { return false; }。注意事项长规则与串口缓冲通过串口控制台输入长规则时可能遇到Serial buffer overrun错误需要用命令serialbuffer 800增大串口输入缓冲区。配置生效时机配置的改动只有在执行restart命令重启后才会被激活。三、顶层配置参数顶层 JSON 键描述设备与通信层参数表如下来自 value_pairs_description.md参数说明默认值Name电能监测设备的名称无Baud设备 Modbus 接口的波特率可选9600Config串口配置如8N18 数据位、无校验、1 停止位由驱动内部宏决定Poll两次 Modbus 请求之间的间隔时间可选200毫秒AddressModbus 设备地址十进制1或十六进制0x01最多三个地址[1,2,3]可选1Function访问寄存器用的 Modbus 功能码可选4对应源码中的默认宏xnrg_29_modbus.ino默认波特率ENERGY_MODBUS_SPEED 9600、默认串口配置TS_SERIAL_8N1、默认地址ENERGY_MODBUS_ADDR 1、默认功能码ENERGY_MODBUS_FUNC 0x04、默认轮询间隔ENERGY_MODBUS_TICKER_POLL 200。几点实现细节值得注意Config在解析时会经过ParseSerialConfig()/ConvertSerialConfig()转换xnrg_29_modbus.inoPoll低于 100 ms 会被强制还原为默认值因为 9600 bps 下通信通常不可能更快xnrg_29_modbus.inoAddress传数组时驱动按数组元素数量设置设备数devices最多ENERGY_MODBUS_MAX_DEVICES即 3台设备xnrg_29_modbus.ino。四、Tasmota 内置寄存器名称内置寄存器即 Tasmota 电能框架中的标准字段每个寄存器可配置为以下三种形式之一单相单值十进制或十六进制寄存器地址如Voltage:0、Voltage:0x0000三相数组最多三个地址如Voltage:[0,2,4]值对对象带类型与因子的详细描述如Voltage:{R:0,T:0,F:0}。内置寄存器清单名称须与 Tasmota 默认嵌入名称一致不可被用户自定义名称占用键名含义典型地址示例Voltage电压单相或三相0x0000/[0x0000,0x0002,0x0004]Current电流0x0006/[0x0006,0x0008,0x000A]Power有功功率0x000C/[0x000C,0x000E,0x0010]ApparentPower视在功率0x000C起同 Power 布局ReactivePower无功功率0x0018起Factor功率因数0x001E起Frequency电网频率0x0046起Total总正向有功电能0x0156起ExportActive反向输出有功电能0x0160起源码中这些字段定义在kEnergyModbusValues字符串表与EnergyModbusRegisters枚举中xnrg_29_modbus.ino读取到的原始值经类型解析与因子换算后分别写入Energy-voltage[]、Energy-current[]、Energy-active_power[]等标准电能结构体xnrg_29_modbus.ino。寄存器值对Value Pair描述{R:0,T:0,F:0}三个字段RModbus register寄存器地址十进制或十六进制单相一个值0x0160三相最多三个值[0x0160,0x0162,0x0164]。TDatatype数据类型可选默认0float4 字节浮点值数据类型0float4 字节浮点12 字节有符号整型24 字节有符号整型32 字节无符号整型44 字节无符号整型5未使用64 字节有符号整型字序交换7未使用84 字节无符号整型字序交换源码中对应枚举EnergyModbusDataTypexnrg_29_modbus.ino并在EnergyModbusLoop()的 switch 中逐类型解码字节流。值得注意的是偶数为单寄存器类型2 字节奇数为双寄存器类型4 字节源码用2 - (datatype 1)计算需读取的寄存器个数xnrg_29_modbus.ino。字序交换类型6/8用于 Solax 等高低字颠倒的协议源码注释示例01 04 04 EB EC 00 0E 8E 51 977.9000。FRegister factor寄存器系数可选默认0表示不处理。正数表示乘负数表示除值运算-4除以 10000-3除以 1000-2除以 100-1除以 100不处理1乘以 102乘以 1003乘以 10004乘以 10000源码实现为按绝对值累乘 10 得到缩放因子再根据符号决定乘除xnrg_29_modbus.ino。五、用户自定义寄存器User当内置字段不够用时可用User数组补充任意数量的用户自定义寄存器。单个值对格式{R:0x0024,T:0,F:0,J:PhaseAngle,G:Phase Angle,U:Deg,D:2}字段说明R/T/F与内置寄存器值对完全相同的寄存器地址、数据类型与系数见上节表格。JJSON register nameJSON 输出中使用的名称建议无空格如PhaseAngle必填且必须与 Tasmota 默认内置寄存器名称不同否则该条用户寄存器会被驱动丢弃源码 xnrg_29_modbus.ino 用GetCommandCode(..., kEnergyModbusValues)检测重名后return false。GGUI register nameWeb 界面显示名称可选未定义则该寄存器不会显示在 GUI 中。UGUI unit nameWeb 界面显示的单位可选默认为空。DDecimals小数位浮点显示的位数0 到 20或对应 Tasmota 分辨率命令VoltRes/AmpRes/WattRes等设置代码D值含义0–20固定小数位数21VoltResV22AmpResA23WattResW、VA、var24EnergyReskWh、kVAh、kvarh25FreqResHz26TempRes°C、°F27HumRes%28PressReshPa、mmHg29WeightResKg源码中分辨率映射位于EnergyModbusResolution()xnrg_29_modbus.ino枚举定义见EnergyModbusResolutionsxnrg_29_modbus.ino。User可传对象单条或数组多条每条用户寄存器在 JSON 输出中以其J名称出现并在 Web 界面以GU呈现。六、默认配置清单开箱即用以下为官方文档提供的默认配置覆盖 DDSU666、PZEM014、SDM230、Solax X3MIC、WE517 五类常见设备DDSU6666 {Name:DDSU666,Baud:9600,Config:8N1,Address:1,Function:4,Voltage:0x2000,Current:0x2002,Power:0x2004,ReactivePower:0x2006,Factor:0x200A,Frequency:0x200E,Total:0x4000,ExportActive:0x400A} PZEM014 {Name:PZEM014,Baud:9600,Config:8N1,Address:1,Function:4,Voltage:{R:0,T:3,F:-1},Current:{R:1,T:8,F:-3},Power:{R:3,T:8,F:-1},Factor:{R:8,T:3,F:-2},Frequency:{R:7,T:3,F:-1},Total:{R:5,T:8,F:-3}} 3 x PZEM014 {Name:3 x PZEM014,Baud:9600,Config:8N1,Address:[1,2,3],Function:4,Voltage:{R:0,T:3,F:-1},Current:{R:1,T:8,F:-3},Power:{R:3,T:8,F:-1},Factor:{R:8,T:3,F:-2},Frequency:{R:7,T:3,F:-1},Total:{R:5,T:8,F:-3}} SDM230 {Name:SDM230,Baud:2400,Config:8N1,Address:1,Function:4,Voltage:0,Current:6,Power:12,ApparentPower:18,ReactivePower:24,Factor:30,Frequency:70,Total:342,ExportActive:0x004A} Solax X3MIC {Name:Solax X3MIC,Baud:9600,Config:8N1,Address:1,Function:4,Voltage:{R:0x0404,T:3,F:-1},Power:{R:0x040e,T:3,F:0},Total:{R:0x0423,T:8,F:-3}} WE517 {Name:WE517,Baud:9600,Config:8E1,Address:1,Function:3,Voltage:[0xE,0x10,0x12],Current:[0x16,0x18,0x1A],Power:[0x1E,0x20,0x22],ReactivePower:[0x26,0x28,0x2A],Factor:[0x36,0x38,0x3A],Frequency:0x14,Total:0x100}要点解读DDSU666单相直读型电表全部使用十六进制地址注意其Baud为 9600PZEM014寄存器内容为裸整型因此大量使用T2 字节无符号3/ 4 字节无符号交换字序8与F除以 10/100/1000组合还原真实物理量3 x PZEM014与单个 PZEM014 完全相同的寄存器映射仅把Address改为[1,2,3]即可将三台单相设备当作三相读取SDM230寄存器地址全部为十进制浮点型只有ExportActive用十六进制0x004A十进制 74 的对应值Solax X3MIC逆变器协议电压用 2 字节无符号除以 10总量用 4 字节无符号交换字序除以 1000WE517使用8E1偶校验与功能码3保持寄存器三相字段全部为数组。七、扩展配置清单含用户自定义寄存器示例扩展配置在默认配置基础上增加了User用户自定义寄存器官方提供如下示例SDM72 {Name:SDM72,Baud:9600,Config:8N1,Address:0x01,Function:0x04,Power:0x0034,Total:0x0156,ExportActive:0x004A,User:[{R:0x0502,J:ImportActive,G:Import Active,U:kWh,D:24},{R:0x0502,J:ExportPower,G:Export Power,U:W,D:23},{R:0x0500,J:ImportPower,G:Import Power,U:W,D:23}]} SDM72D_M {Name:SDM72D-M,Baud:9600,Config:8N1,Address:1,Function:4,Voltage:[0,2,4],Current:[6,8,10],Power:[12,14,16],ApparentPower:[18,20,22],ReactivePower:[24,26,28],Factor:[30,32,34],Frequency:70,ExportActive:74,Total:342,User:[{R:42,J:AverageVoltage,G:Average Voltage,U:V,D:21},{R:46,J:AverageCurrent,G:Average Current,U:A,D:22},{R:48,J:TotalCurrents,G:Total Currents,U:A,D:22},{R:52,J:TotalPower,G:Total Power,U:W,D:23},{R:56,J:TotalApparentPower,G:Total Apparent Power,U:W,D:23},{R:60,J:TotalReactivePower,G:Total Reactive Power,U:W,D:23},{R:62,J:TotalPowerFactor,G:Total Power Factor,U:W,D:2},{R:72,J:ImportActive,G:Import Active,U:kWh,D:24},{R:396,J:DiffPower,G:Diff Power,U:kWh,D:24},{R:1280,J:TotalImportActive,G:Total Import Active,U:W,D:23},{R:1282,J:TotalExportActive,G:Total Export Active,U:W,D:23}]} SDM120 {Name:SDM120,Baud:2400,Config:8N1,Address:1,Function:4,Voltage:0,Current:6,Power:12,ApparentPower:18,ReactivePower:24,Factor:30,Frequency:70,Total:342,ExportActive:0x004A,User:[{R:0x0048,J:ImportActive,G:Import Active,U:kWh,D:24},{R:0x004E,J:ExportReactive,G:Export Reactive,U:kVArh,D:24},{R:0x004C,J:ImportReactive,G:Import Reactive,U:kVArh,D:24},{R:0x0024,J:PhaseAngle,G:Phase Angle,U:Deg,D:2}]} SDM230 {Name:SDM230 with two user registers,Baud:2400,Config:8N1,Address:1,Function:4,Voltage:0,Current:6,Power:12,ApparentPower:18,ReactivePower:24,Factor:30,Frequency:70,Total:342,ExportActive:0x004A,User:[{R:0x004E,J:ExportReactive,G:Export Reactive,U:kVArh,D:3},{R:0x0024,J:PhaseAngle,G:Phase Angle,U:Deg,D:2}]} SDM630 {Name:SDM630,Baud:9600,Config:8N1,Address:1,Function:4,Voltage:[0,2,4],Current:[6,8,10],Power:[12,14,16],ApparentPower:[18,20,22],ReactivePower:[24,26,28],Factor:[30,32,34],Frequency:70,Total:342,ExportActive:[352,354,356],User:{R:[346,348,350],J:ImportActive,G:Import Active,U:kWh,D:24}} WE517 {Name:WE517,Baud:9600,Config:8E1,Address:1,Function:3,Voltage:[0xE,0x10,0x12],Current:[0x16,0x18,0x1A],Power:[0x1E,0x20,0x22],ReactivePower:[0x26,0x28,0x2A],Factor:[0x36,0x38,0x3A],Frequency:0x14,Total:0x100,ExportActive:0x110,User:[{J:ImportActive,G:Import Active,R:0x108,U:kWh,D:24},{J:TotalPower,G:Active Power Total,R:0x1C,U:W,D:23}]} Growatt 12KTL-3S (v3.x) {Name:Growatt,Baud:9600,Config:8N1,Function:4,Address:1,Poll:1000,Voltage:{R:[3,7],T:3,F:-1}, Power:{R:11,T:4,F:-1},Total:{R:28,T:4,F:-1}, User: [{J:IntTemp,R:32,T:3,F:-1, G:Internal temperature, U: C, D:26}]}这些示例展示了User的多种写法纯对象写法SDM630User:{R:[346,348,350],...}表示三相同一类型的用户寄存器多条数组写法SDM120 / SDM72D_M依次列出多条用户寄存器三相值对写法GrowattVoltage:{R:[3,7],T:3,F:-1}中R传两个地址两路输入电压并以Poll:1000放慢轮询间隔适配逆变器SDM72D-M的三相总量寄存器Total传十进制342并借助D:21/D:22等分辨率代码复用 Tasmota 的电压/电流/功率精度设置。八、接线与启用前提驱动由EnergyModbusDrvInit()在FUNC_PRE_INIT阶段注册xnrg_29_modbus.ino要求模板中同时配置GPIO_NRG_MBS_RX与GPIO_NRG_MBS_TX两个引脚可选配置GPIO_NRG_MBS_TX_ENA发送使能常用于 RS485 方向控制与GPIO_MBS_RX_ENA。引脚定义见 tasmota_template.hGPIO_NRG_MBS_TX, GPIO_NRG_MBS_RX并可通过 Berry 的gpio模块按名称NRG_MBS_RX访问be_gpio_defines.h。初始化成功后驱动通过Ticker以Poll默认 200 ms为周期调度EnergyModbusLoop()逐寄存器轮询当所有寄存器读取完成后调用EnergyUpdateTotal()更新总量xnrg_29_modbus.ino。此外配置了Total时驱动会自动启用SetOption72硬件电能总量作为参考见 xnrg_29_modbus.ino多设备Address数组情况下自动启用SetOption129显示相位信息并关闭共电压/共频率假设xnrg_29_modbus.ino。九、实操步骤接入一台自定义 Modbus 电表接线将电表 RS485 A/B 通过转换模块接到 ESP 的NRG_MBS_RX/NRG_MBS_TX引脚半双工设备可加NRG_MBS_TX_ENA方向控制在模板或配置中指定引脚。查阅电表寄存器表从设备手册取得电压、电流、功率等量的寄存器地址、数据类型float / int16 / uint32 等与缩放系数如 ×0.1、÷1000。编写 JSON按上文字段规则组织顶层参数 内置寄存器 User自定义寄存器。不确定数据类型时可用T:0float配合F系数调整并利用串口日志ENERGY_MODBUS_DEBUG宏见 xnrg_29_modbus.ino验证解析结果。加载配置三选一——写入modbus.json到文件系统、用rule3 on file#modbus do {...} endon、或用脚本段y {...} #。串口输入长规则时先执行serialbuffer 800。重启生效执行restart随后在 Web 界面 Energy 页面或 MQTTSTATUS/SENSOR中核对各量值是否与电表本地读数一致微调F系数与D小数位直至匹配。十、扩展阅读完整的 Modbus 电能 JSON 值对语义value_pairs_description.md官方配置与示例清单configurations.md驱动核心实现xnrg_29_modbus.ino编译开关与代码量说明tasmota_configurations.h、tasmota_configurations_ESP32.h引脚定义与模块支持tasmota_template.h其他 Modbus 电能驱动的配置方式可参考同目录下各xnrg_*驱动源码如 xnrg_08_sdm120.ino、xnrg_10_sdm630.ino【免费下载链接】TasmotaAlternative firmware for ESP8266 and ESP32 based devices with easy configuration using webUI, OTA updates, automation using timers or rules, expandability and entirely local control over MQTT, HTTP, Serial or KNX. Full documentation at项目地址: https://gitcode.com/GitHub_Trending/ta/Tasmota创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考