简介SMLReader是一款面向物联网开发者与智能家居爱好者的开源电表数据采集网关基于ESP8266兼容ESP32实现D0接口SML协议智能电表数据的实时解析与MQTT远程上报解决传统电表难以接入Home Assistant、Node-RED等现代家居平台的集成难题。资源包共29个文件含7张功能示意图png、5个核心头文件.h封装传感器、MQTT发布、调试与单位转换逻辑3份README与2份Markdown文档提供配置说明与使用指南另有YAML/INI环境配置、PlatformIO工程文件及Fritzing电路图.fzz整体839KB轻量易部署。已有267人学习下载读者可直接获取完整Arduino C工程含main.cpp、config.h、MqttPublisher.h等模块化源码、OBIS码映射表、SML帧解析关键逻辑及Wi-FiMQTT双模连接范例快速复现电表数据采集、结构化解析与云端同步全流程。1. 电表数据不再“黑匣子”SMLReader 把家用电表的实时功率、总电量、电压电流全吐到 MQTT连 ESP8266 都能扛住 D0 协议解析你有没有试过——半夜三点盯着智能插座的功耗曲线却完全不知道空调压缩机到底在哪个瞬间把电费刷高不是设备不支持是家里那台老式机械电子混合电表带 D0 接口的 SML 协议电表压根没联网能力。SMLReader 就是为这种“被遗忘的能源节点”而生它用一块不到 10 块钱的 ESP8266 模块接上电表背面那个不起眼的 D0 接口两根线GND DATA就能把每秒涌出的 SML 报文逐字节拆解提取 OBIS 标识符对应的真实物理量比如1-0:1.8.0*255是总正向有功电能1-0:21.7.0*255是A相实时功率再通过 MQTT 发到 Home Assistant、Node-RED 或任意自建平台。它不是“读数工具”而是把电表从一个被动显示设备变成可编程、可告警、可联动的 IoT 节点。适合想做家庭能源精细化管理、又不想换整块电表的 DIYer也适合嵌入式初学者练手——协议解析逻辑清晰Arduino C 实现无黑盒连串口调试时的原始 SML 字节流都给你留好了打印开关。2. 架构与技术选型为什么是 ESP8266 Arduino C D0 物理层而不是 ESP32 或 ModbusSMLReader 的轻量化不是妥协而是对 D0 协议特性和家庭部署场景的精准匹配。我们先看它拒绝什么不用 ESP32虽然 ESP32 性能更强但 D0 是异步串行协议非标准 UART 波特率典型 9600/300bps且电表发送 SML 报文是“脉冲式爆发”一帧报文含数十个 OBIS 条目持续 200~500ms之后静默数秒。ESP8266 的 UART RX 中断环形缓冲区足矣加 ESP32 反而增加功耗和固件体积对常年插在电表旁的网关无意义不用 Modbus国内主流单相/三相智能电表虽支持 RS485 Modbus但需额外电平转换、布线且厂家常锁死寄存器地址或要求认证密钥D0 接口是公开物理层IEC 62056-21只要电表有 D0 插座常见于威胜、科陆、林洋等型号接线即用坚持 Arduino C不引入 PlatformIO 复杂配置不依赖 RTOS所有核心逻辑SML 帧同步、OBIS 解析、MQTT 封包都在SMLParser.cpp和MQTTPublisher.cpp里函数粒度细到parseOBISValue()和extractHexBytes()新手改一个 OBIS 地址就能看到效果。2.1 硬件连接D0 接口的“两线制”真相与电平适配D0 接口本质是电流环Current Loop非 TTL 电平。电表侧输出的是约 20mA 电流脉冲通过外部上拉电阻转成电压信号给 ESP8266 识别。这是第一个必须亲手焊的环节电表 D0 接口引脚定义以威胜 DDS353 为例Pin1 GNDPin2 DATA开漏输出ESP8266 连接方式DATA → GPIO13RX2推荐因 GPIO3/RX0 常被 USB 转串口占用GND → ESP8266 GND关键元件在 DATA 与 ESP8266 VCC3.3V之间接一个4.7kΩ 上拉电阻非 10k太大会导致上升沿迟缓丢帧安全提示绝对禁止将电表 D0 直接连 ESP8266 TX/RX电表侧是电流源直接接会烧毁 ESP8266 UART 引脚。上拉电阻是必须的隔离器件。提示实物接线后用万用表测 GPIO13 对地电压静默时应为 3.3V电表发码时电压在 0~3.3V 间跳变。若始终为 0V检查上拉电阻是否虚焊若始终为 3.3V检查电表 D0 是否启用部分电表需进入设置菜单开启 D0 输出。2.2 软件栈分层从物理层到应用层的四层穿透SMLReader 的代码结构严格按数据流向分层每一层只解决一个问题层级模块文件核心职责关键设计点物理层HardwareSerial.h 自定义D0Receiver.cpp处理 UART 接收、环形缓冲区管理、帧起始检测/字符使用HardwareSerial::available()非阻塞轮询避免delay()导致丢帧缓冲区大小设为 512 字节SML 最大帧长 ≈ 380 字节协议层SMLParser.cppSML 帧校验CRC16-XMODEM、分段0x01/0x02/0x1E标记、OBIS 条目提取CRC 计算不调用库函数手写查表法crc16_table[]确保在 ESP8266 上 50μs 完成数据层OBISDatabase.cppOBIS 地址映射如1-0:1.8.0*255→total_energy_kwh、单位转换Wh→kWh、数值类型推导整数/浮点/字符串支持运行时动态注册新 OBIS无需改源码只需调用registerOBIS(1-0:32.7.0*255, voltage_l1_v, OBIS_TYPE_FLOAT)传输层MQTTPublisher.cppMQTT 连接管理自动重连、主题生成home/meter/energy_total、QoS1 发布、JSON 封包主题前缀可配置#define MQTT_TOPIC_PREFIX home/meterJSON 不用第三方库手写sprintf()拼接减少内存碎片这种分层让修改变得极简单想加一个新电表参数只动OBISDatabase.cpp想换 MQTT 服务器只改MQTTPublisher.cpp里的mqtt_server和mqtt_port想调试原始字节打开D0Receiver.cpp里的#define DEBUG_SML_RAW 1串口直接输出十六进制流。2.3 核心流程图一个 SML 帧从电表到 MQTT 的 7 步旅程整个数据链路没有魔法只有确定性的状态机。以下是真实代码中执行的步骤已简化异常分支物理接收D0Receiver::loop()检测到 GPIO13 电平下降沿 → 触发Serial2.read()读取字节 → 存入环形缓冲区rx_buffer[512]帧同步缓冲区扫描到字符/ASCII 0x2F→ 记录为帧起始位置帧捕获继续接收直到遇到结束标记0x01STX0x02SOH0x1ESUB组合 → 截取完整帧CRC 校验取帧末尾 2 字节作为 CRC → 用crc16_xmodem(frame_data, frame_len-2)计算 → 不匹配则丢弃整帧OBIS 提取遍历帧内所有0x72SML 类型标识段 → 解析后续 6 字节 OBIS 地址 → 查obis_map[]表获取字段名值解析根据 OBIS 后续0x09SCALAR或0x06OCTET_STRING类型 → 调用parseInteger()或parseFloat()→ 单位按数据库预设缩放如1.8.0除以 1000 得 kWhMQTT 发布拼接 JSON{value:12345.67,unit:kWh,timestamp:1717023456}→client.publish(topic, json_payload, true)retaintrue。这个流程在 ESP8266 上平均耗时 12~18ms实测远低于电表最小发码间隔通常 ≥2s因此不会成为瓶颈。3. 编译与烧录Arduino IDE 下零配置跑通但必须改这 3 个宏定义SMLReader 的platformio.ini和Arduino IDE项目均可用但 Arduino IDE 更适合新手——因为它的错误提示更直白。以下步骤基于Arduino IDE 2.3.2 ESP8266 Core 3.1.0必须用此版本低版本无Serial2支持高版本有 UART 中断兼容问题。3.1 环境准备SDK 版本与板级配置的硬性要求打开 Arduino IDE →文件 首选项→ 在“附加开发板管理器网址”填入https://arduino.esp8266.com/stable/package_esp8266com_index.json工具 开发板 开发板管理器→ 搜索esp8266→ 安装esp8266 by ESP8266 Community版本选3.1.0注意不是最新版3.2.0 会导致Serial2在某些板子上无法触发中断安装后工具 开发板 ESP8266 Boards→ 选择Generic ESP8266 Module关键参数设置必须与硬件匹配Flash Size:1MB (FS:512KB OTA:~1019KB)Upload Speed:921600高速上传避免超时CPU Frequency:80 MHz默认足够Debug Port:Disabled节省资源注意若使用 NodeMCU-12E 等带 USB 转串口芯片的开发板Upload Speed可设为115200但直接用 CH340 模块烧录时务必用921600否则上传失败率极高。3.2 配置文件修改3 个#define决定能否连上电表和 MQTT打开项目根目录下的config.h必须修改以下三项其他可保持默认// config.h 关键配置段 #define WIFI_SSID YourHomeWiFi // 你的 WiFi 名称2.4GHz onlyESP8266 不支持 5G #define WIFI_PASSWORD YourWiFiPass // WiFi 密码明文因 ESP8266 无安全存储 #define MQTT_SERVER 192.168.1.100 // MQTT Broker IP如 Mosquitto 在树莓派上 #define MQTT_PORT 1883 // 标准端口若用 TLS 则需改用 8883 并加证书本项目暂不支持 #define D0_RX_PIN 13 // 必须与硬件接线一致GPIO13 RX2为什么必须改这三项WIFI_SSID/PASSWORDESP8266 启动后首先进入 WiFi 连接状态若填错LED 会快闪 3 次后熄灭无任何串口提示这是血泪经验曾因 SSID 多一个空格调试 2 小时MQTT_SERVER不能填域名如mqtt.localESP8266 DNS 解析不稳定必须填 IPD0_RX_PIN默认是13但若你接在 GPIO4请同步改为4否则Serial2根本收不到数据。3.3 烧录与首次验证串口监视器里看到/才算成功接好硬件D0 线 上拉电阻 ESP8266 供电Arduino IDE 中选择正确端口工具 端口Windows 显示为COMxMac 为/dev/cu.usbserial-xxxx点击右上角√ 验证→ 确认无编译错误点击→ 上传→ 等待进度条完成打开工具 串口监视器设置波特率为115200换行符选Both NL CR关键观察点启动后应打印Connecting to WiFi...→WiFi connected! IP:192.168.1.xxx然后打印Connecting to MQTT...→MQTT connected!最重要几秒后若电表正在发码应看到类似[SML] Raw frame start: / [SML] Frame len: 342 bytes, CRC OK [OBIS] 1-0:1.8.0*255 12345678 Wh → publish to home/meter/energy_total [OBIS] 1-0:21.7.0*255 1245 W → publish to home/meter/power_l1_w若只看到 WiFi 连接成功但无[SML]日志 → 检查 D0 接线和上拉电阻若看到[SML] Raw frame start: /但无后续Frame len→ 说明收到/但没收到完整帧大概率是 CRC 校验失败电表型号不匹配或波特率不对但 D0 是固定 300/9600无需设波特率。4. 常见问题排查5 个真实翻车现场与救回操作SMLReader 的坑不在代码而在物理世界。以下是我在某高校实验室帮 12 个学生调试时高频出现的 5 类问题按现象→原因→解决三步给出答案。4.1 现象串口监视器一直打印WiFi connecting...IP 地址始终为空原因ESP8266 无法关联 WiFi常见于① WiFi 是 5GHz 频段ESP8266 仅支持 2.4GHz② WiFi 密码含特殊字符如、$、空格Arduino 字符串解析失败③ 路由器开启了“隐藏 SSID”或“WPA3 加密”ESP8266 Core 3.1.0 仅支持 WPA2。解决用手机热点2.4GHzWPA2-PSK密码纯字母数字测试在config.h中将密码用双引号包裹并转义反斜杠#define WIFI_PASSWORD MyPss123→ 改为MyP\\ss123路由器后台关闭“隐藏 SSID”加密方式选WPA2-PSK [AES]。4.2 现象WiFi 和 MQTT 都连上了但串口无[SML]日志电表 D0 接口实测有电压跳变原因D0 信号电平不匹配。电表 D0 输出是电流环但部分电表如早期林洋输出电压幅值偏低2.5V而 ESP8266 GPIO 输入高电平阈值为0.75×VCC ≈ 2.475V处于临界区导致误判。解决将上拉电阻从4.7kΩ换成2.2kΩ增强上拉能力抬高高电平或在 DATA 线上加一级 74HC14 施密特触发器整形成本 0.5 元彻底解决抖动快速验证用示波器看 GPIO13 波形若上升沿缓慢1μs或高电平 2.8V则必换电阻。4.3 现象串口偶尔打印[SML] Frame len: XX bytes, CRC OK但大部分帧显示CRC FAIL原因SML 帧在传输中被干扰最常见于电源噪声。ESP8266 对电源纹波敏感当电表与 ESP8266 共用同一开关电源时电表继电器动作产生的瞬态电流会耦合到 ESP8266 供电轨导致 UART 接收错位。解决必须分离供电电表 D0 接口取电通常为 5V仅用于上拉电阻ESP8266 用独立 3.3V LDO如 AMS1117-3.3供电输入端加100μF电解电容 100nF陶瓷电容在D0Receiver.cpp中降低接收灵敏度将if (Serial2.available())改为if (Serial2.available() 2)跳过单字节噪声。4.4 现象MQTT 收到数据但 Home Assistant 显示unknown或数值为0原因OBIS 地址映射错误。不同厂家电表对同一物理量使用的 OBIS 地址不同。例如威胜电表总电量用1-0:1.8.0*255科陆电表可能用1-0:1.8.1*255费率1或1-0:1.8.0*255总而 SMLReader 默认只注册了威胜常用地址。解决打开OBISDatabase.cpp找到void initOBISDatabase()函数在末尾添加你电表的实际地址registerOBIS(1-0:1.8.1*255, energy_total_kwh, OBIS_TYPE_UINT32); // 科陆总电量 registerOBIS(1-0:31.7.0*255, current_l1_a, OBIS_TYPE_FLOAT); // A相电流重新编译上传串口会打印新注册的日志。4.5 现象设备运行 2 小时后自动重启串口输出Fatal exception (28)原因堆内存溢出。SML 帧解析中String类型滥用如String sml_frame Serial2.readString()导致内存碎片ESP8266 仅 80KB RAM连续运行后malloc()失败。解决全局搜索项目中所有String声明替换为char buffer[512]Serial2.readBytes(buffer, len)在SMLParser.cpp中将parseOBISValue()的返回类型从String改为int32_t或float数值计算在栈上完成编译后查看 Arduino IDE 底部内存使用率确保Global variables≤ 35KB安全线。5. 核心模块代码详解SML 帧解析与 OBIS 提取的 3 个关键函数现在我们沉到代码最深处。SMLReader 的灵魂不在 MQTT而在SMLParser.cpp里那不到 200 行的解析逻辑。下面逐段拆解三个决定成败的函数每段都附真实注释和参数说明。5.1bool SMLParser::findSMLFrame(uint8_t *buffer, uint16_t len, uint16_t *frame_start, uint16_t *frame_end)这是帧同步的守门员负责从环形缓冲区中捞出完整的 SML 帧。bool SMLParser::findSMLFrame(uint8_t *buffer, uint16_t len, uint16_t *frame_start, uint16_t *frame_end) { // Step 1: 找帧头 / —— SML 标准规定每帧以 ASCII 0x2F 开始 for (uint16_t i 0; i len; i) { if (buffer[i] 0x2F) { // / 字符ASCII 码 47 *frame_start i; // Step 2: 从 / 向后找帧尾必须是 0x01 0x02 0x1E 组合STXSOHSUB // 注意SML 帧尾固定为这三个字节且中间不能有其他数据 for (uint16_t j i 1; j len - 2; j) { if (buffer[j] 0x01 buffer[j1] 0x02 buffer[j2] 0x1E) { *frame_end j 3; // 包含尾部 3 字节 return true; // 找到有效帧 } } } } return false; // 未找到完整帧 }逻辑说明该函数不解析内容只定位边界。buffer是从D0Receiver拿到的原始字节流len是当前缓冲区有效长度*frame_start和*frame_end是输出参数调用后得到帧在缓冲区中的索引范围为什么不用正则ESP8266 没有 regex 库且此逻辑 O(n) 时间复杂度实测 512 字节缓冲区平均 3μs 完成。5.2uint16_t SMLParser::calculateCRC16(const uint8_t *data, uint16_t len)CRC 校验是 SML 协议的生命线错一个字节整帧报废。// 预定义 CRC16-XMODEM 查表数组256 项占 512 字节 Flash const uint16_t crc16_table[256] PROGMEM { 0x0000,0x1021,0x2042,0x3063,0x4084,0x50a5,0x60c6,0x70e7, // ...完整表略实际代码中已展开 }; uint16_t SMLParser::calculateCRC16(const uint8_t *data, uint16_t len) { uint16_t crc 0x0000; for (uint16_t i 0; i len; i) { uint8_t idx (crc 8) ^ data[i]; // 高 8 位异或当前字节 crc (crc 8) ^ pgm_read_word_near(crc16_table[idx]); // 查表更新 } return crc; }参数说明data指向帧数据起始地址的指针不包含末尾 2 字节 CRClen数据长度SML 帧中CRC 前的数据长度 总长 - 2pgm_read_word_near()从 Flash 读取查表数据ESP8266 RAM 紧张查表必须放 Flash关键细节SML 的 CRC 是校验“从/到0x1E之前的所有字节”不包括帧头/和帧尾0x01 0x02 0x1E但包括中间所有0x01/0x02分隔符。5.3bool SMLParser::parseOBISValue(const uint8_t *obis_ptr, char *value_str, uint8_t max_len)这是 OBIS 值提取的核心把二进制编码转成可读数值。bool SMLParser::parseOBISValue(const uint8_t *obis_ptr, char *value_str, uint8_t max_len) { // OBIS 值结构[Length][Type][Value]其中 Type0x09 表示 SCALAR带缩放因子的整数 uint8_t len obis_ptr[0]; // 第 1 字节值长度不含类型字节 uint8_t type obis_ptr[1]; // 第 2 字节类型标识 if (type ! 0x09) { // 当前只处理 SCALAR 类型最常见 return false; } // Step 1: 提取缩放因子第 3 字节SML 中为 2 的幂次如 0xFF -1 → 10^-1 0.1 int8_t scaler (int8_t)obis_ptr[2]; int32_t raw_value 0; // Step 2: 解析后续字节为整数大端序最多 4 字节 for (uint8_t i 0; i len - 2 i 4; i) { raw_value (raw_value 8) | obis_ptr[3 i]; } // Step 3: 应用缩放因子转成浮点并格式化为字符串 float final_value (float)raw_value; for (int8_t i 0; i scaler; i) { final_value / 10.0; } for (int8_t i 0; i scaler; i--) { final_value * 10.0; } // Step 4: 格式化输出保留小数点后 3 位避免科学计数法 dtostrf(final_value, 10, 3, value_str); return true; }逻辑说明obis_ptr指向 OBIS 条目中0x09类型字节的地址即0x09及其后的所有字节scaler是缩放因子SML 协议中0xFF -1,0xFE -2,0x00 0,0x01 1表示10^scalerdtostrf()是 Arduino 标准库函数将浮点转字符串10是最小宽度3是小数位数为什么不用String此处value_str是调用方传入的栈数组如char val[16]避免堆分配。6. 二次开发实战如何添加「电压跌落告警」并推送 Telegram 消息现在你已跑通基础功能下一步是让它真正为你服务。我以「当 L1 相电压低于 210V 持续 5 秒自动发 Telegram 告警」为例展示从需求到落地的完整改造链。这不是理论是我在某导师家真实部署的方案。6.1 数据源确认先抓到电压 OBIS 地址第一步永远不是写代码而是确认电表真的在发这个数据。打开串口监视器开启DEBUG_SML_RAW宏在D0Receiver.cpp中取消注释#define DEBUG_SML_RAW 1重启设备。你会看到类似[SML] RAW: 2F 30 31 32 33 34 35 36 37 38 39 30 31 32 33 34...复制一段 RAW 数据粘贴到在线 SML 解析器如sml-parser.net找到电压相关 OBIS。常见地址1-0:32.7.0*255L1 相电压V1-0:52.7.0*255L2 相电压V1-0:72.7.0*255L3 相电压V确认地址后在OBISDatabase.cpp中注册registerOBIS(1-0:32.7.0*255, voltage_l1_v, OBIS_TYPE_FLOAT);6.2 告警逻辑实现状态机比定时器更可靠电压跌落是瞬态事件用millis()定时器容易漏判。我采用有限状态机FSM// 新增全局变量在 SMLReader.ino 顶部 enum VoltageAlertState { IDLE, DETECTING, ALERTED }; VoltageAlertState alert_state IDLE; unsigned long voltage_low_start 0; const unsigned long ALERT_DURATION_MS 5000; // 持续 5 秒才告警 // 在 loop() 中添加紧挨着 MQTT 发布之后 float current_voltage getOBISValue(voltage_l1_v); // 假设已有此函数 if (current_voltage 210.0) { if (alert_state IDLE) { voltage_low_start millis(); alert_state DETECTING; } else if (alert_state DETECTING (millis() - voltage_low_start) ALERT_DURATION_MS) { sendTelegramAlert(current_voltage); alert_state ALERTED; } } else { // 电压恢复正常重置状态 alert_state IDLE; }为什么用 FSMDETECTING状态确保只有持续低压才触发ALERTED状态防止重复发送避免 5 秒内发 10 条全部逻辑在loop()中无阻塞不影响 SML 接收。6.3 Telegram 推送用 HTTP POST 替代 MQTT轻量且免服务器SMLReader 本身不带 Telegram SDK但我们用 ESP8266 内置的HTTPClient库即可#include ESP8266HTTPClient.h void sendTelegramAlert(float voltage) { if (!WiFi.isConnected()) return; HTTPClient http; String url https://api.telegram.org/botYOUR_BOT_TOKEN/sendMessage; url ?chat_idYOUR_CHAT_IDtext; url ⚠️ 电压告警L1相电压 ; url String(voltage, 1); url V低于210V阈值; http.begin(url); int httpCode http.GET(); // 发送 GET 请求 if (httpCode 0) { Serial.printf([Telegram] Alert sent, code: %d\n, httpCode); } else { Serial.printf([Telegram] Alert failed, code: %d\n, httpCode); } http.end(); }关键配置YOUR_BOT_TOKEN在 Telegram 创建 Bot 后获得BotFatherYOUR_CHAT_ID发消息给 Bot它会回你自己的 ID或用getUpdatesAPI 获取安全提示Token 明文写在代码里有风险生产环境应存入 SPIFFS 文件系统但 DIY 场景够用。6.4 验证与上线三步闭环测试法改完代码别急着烧录按顺序验证单元验证在sendTelegramAlert()开头加Serial.println(Alert triggered!);串口看到日志即证明状态机逻辑正确集成验证用可调电源模拟电表电压输出接 D0 DATA 线调至 200V观察是否 5 秒后发 Telegram长期验证部署 72 小时用Serial.print(millis()/3600000)打印运行小时数确认无内存泄漏重启。从那以后我每次加新告警都强制走一遍这三步先串口打点再硬件模拟最后挂机 72 小时。少一次就可能在家用高峰时错过真正的故障本文还有配套的精品资源点击获取