DLMS 电表

dlms_meter 组件连接到使用 DLMS/COSEM 协议通过 UART 以 PUSH 模式运行的智能电表。这些智能电表在全球范围内广泛部署。

该组件不向电表传输数据。电表定期广播帧。ESPHome 监听、解码（必要时解密），并在数据到达时更新配置的传感器。

NOTE

硬件适配器： 需要一个适配器（如 M-Bus 到 UART 模块）来连接 ESP 板到智能电表。
ESP 板： 强烈建议使用 ESP32。ESP8266 板不适合大型或多帧 DLMS 报文，可能导致帧截断或损坏。
加密： 对于加密电表，必须从能源提供商处请求一个 32 字符的十六进制解密密钥。

Smart meter with M-Bus adapter board to ESP32

配置

该组件需要配置 UART 总线。

TIP

UART 配置取决于您的具体电表硬件。请务必查阅您的提供商或电表的规范。

dlms_meter:
  id: dlms_meter_hub
  uart_id: uart_dlms_bus

sensor:
  - platform: dlms_meter
    dlms_meter_id: dlms_meter_hub
    obis_code: "1.0.1.7.0.255"
    name: "从电网吸收的有功功率"

配置变量

id (可选, ID): dlms_meter 组件的 ID。
uart_id (可选, ID): 连接到智能电表的 UART 组件的 ID。
receive_timeout (可选, Time): 接收完整帧的超时时间。默认为 1000ms。
decryption_key (可选, string): 如果您的智能电表使用加密，请指定。您应向电力供应商请求此密钥（32 个十六进制字符，不区分大小写）。
auth_key (可选, string): 认证密钥。如果您的智能电表使用加密并带有认证，请指定。您应向电力供应商请求此密钥。用于 General-GLO-Ciphering 和 General-DED-Ciphering APDU。
skip_crc (可选, boolean): 跳过 CRC 检查。一些智能电表使用错误的多项式来计算 CRC。在这种情况下，可使用此标志作为变通方法。默认为 false。
custom_patterns (可选, list): 虽然 dlms_meter 原生支持大多数设备，但某些电表使用独特的有效载荷结构。如果电表的数据读取不正确，可使用此字段定义自定义 AXDR 描述符模式，以告知系统如何解析传入数据。

平台

传感器、文本传感器和二值传感器

所有平台（sensor、text_sensor、binary_sensor）均支持使用 obis_code 属性进行动态映射。这允许您解码电表发出的几乎任何属性。

dlms_meter_id (可选, ID): 如果您有多个中心，请手动指定 dlms_meter 中心的 ID。
obis_code (动态映射必选, string): 您想要读取的值的 OBIS 代码。该代码支持灵活格式如 1-0:32.7.0 或 1.0.32.7.0.255。

定义传感器时，建议包含标准 ESPHome 传感器属性，如 unit_of_measurement、accuracy_decimals、device_class 和 state_class。确切配置将根据您读取的具体值而有所不同（例如能源与功率与电压）。

以下是配置能源传感器以在 Home Assistant 能源仪表板中正确显示的示例：

sensor:
  - platform: dlms_meter
    dlms_meter_id: dlms_meter_hub
    obis_code: "1.0.1.8.0.255"
    name: "消耗能量"
    unit_of_measurement: "kWh"
    accuracy_decimals: 3
    device_class: energy
    state_class: total_increasing

查找电表的 OBIS 代码

使用此方法之前，强烈建议查阅电表手册或能源提供商的文档以获取受支持的 OBIS 代码列表。

TIP

如果您正在构建自定义模式或需要捕获原始十六进制有效载荷以进行故障排除，请将 dlms_meter 日志级别更改为 VERY_VERBOSE。这将输出完整的原始缓冲区和解密后的 AXDR 有效载荷。

如果是首次配置电表且不知道它广播哪些 OBIS 代码，可以临时将日志记录级别提高到 VERBOSE。组件会将所有成功解析的 OBIS 代码及其值打印到 ESPHome 日志中。

logger:
  level: VERBOSE
  initial_level: DEBUG
  logs:
    dlms_meter: VERBOSE

在此配置中，全局 level 设为 VERBOSE，因为否则 ESPHome 将在编译时排除较低严重性的日志消息（任何严重性较低的日志消息都不会显示）。

WARNING

提高日志记录详细程度，例如使用 VERBOSE 或 VERY_VERBOSE，可能会影响 ESP 应用程序的性能并增加内存大小。日常使用时务必恢复到默认日志级别。

为防止控制台被每个组件的详细消息淹没， initial_level 在运行时动态恢复标准默认值 DEBUG，同时 logs 映射手动将特定 dlms_meter 标签设置为保持 VERBOSE。

更多详细信息，请参阅日志记录器组件。

遗留密钥（已弃用）

WARNING

使用预定义遗留密钥（如 voltage_l1、timestamp）的 dlms_meter 模式已弃用，将在 2026.11.0 版本中移除。请更新您的配置，以使用如上所示的带有 obis_code 变量的新模式。

此外，provider 配置选项已弃用，将在 2026.11.0 版本中完全移除：

对于大多数提供商，新的解析库动态处理电表特性，使得手动定义提供商变得不必要。该密钥将被安全忽略，应予以移除。
对于 provider: netznoe，本版本自动注入所需的 custom_patterns 以保持兼容性。然而，您必须在 2026.11.0 之前更新配置，通过移除 provider 密钥并显式替换为以下内容：

custom_patterns:
  - pattern: "L, TSTR"
    name: "MeterID"
    default_obis: "0.0.96.1.0.255"
  - pattern: "F, TDTM"
    name: "DateTime"
    default_obis: "0.0.1.0.0.255"

为了在弃用截止日之前保持向后兼容，早期版本中遗留的预定义密钥仍受支持，并自动映射到各自的 OBIS 代码。仅添加您需要的。所有密钥均支持其各自平台域的标准选项。

sensor:
  - platform: dlms_meter
    dlms_meter_id: dlms_meter_hub
    voltage_l1:
      name: "L1 电压"
    voltage_l2:
      name: "L2 电压"

text_sensor:
  - platform: dlms_meter
    dlms_meter_id: dlms_meter_hub
    meternumber:
      name: "电表编号"

传感器：

voltage_l1 (1.0.32.7.0.255): L1 电压。
voltage_l2 (1.0.52.7.0.255): L2 电压。
voltage_l3 (1.0.72.7.0.255): L3 电压。
current_l1 (1.0.31.7.0.255): L1 电流。
current_l2 (1.0.51.7.0.255): L2 电流。
current_l3 (1.0.71.7.0.255): L3 电流。
active_power_plus (1.0.1.7.0.255): 从电网吸收的有功功率。
active_power_minus (1.0.2.7.0.255): 输送到电网的有功功率。
active_energy_plus (1.0.1.8.0.255): 从电网吸收的累计有功能量。
active_energy_minus (1.0.2.8.0.255): 输送到电网的累计有功能量。
reactive_energy_plus (1.0.3.8.0.255): 从电网吸收的无功能量。
reactive_energy_minus (1.0.4.8.0.255): 输送到电网的无功能量。
power_factor (1.0.13.7.0.255): 功率因子。

文本传感器：

timestamp (0.0.1.0.0.255): 接收帧中包含的时间戳。
meternumber (0.0.96.1.0.255): 设备报告的电表编号。

高级配置

高级配置示例

此示例演示如何使用加密电表或需要自定义解析模式的电表的可选配置变量。

dlms_meter:
  id: dlms_meter_hub
  uart_id: uart_dlms_bus
  receive_timeout: 50ms
  decryption_key: "00112233445566778899AABBCCDDEEFF"
  auth_key: "00112233445566778899AABBCCDDEEFF"
  skip_crc: false
  custom_patterns:
    - pattern: "TO, TV"
      name: "扁平 OBIS + 值对"
      priority: 15
      default_obis: "1.0.96.1.0.255"

自定义模式

可以通过直接传递模式字符串，或定义带有附加属性的对象来定义自定义模式：

pattern (必选, string): 基于 DSL 的模式字符串（例如 "TO, TV"）。
name (可选, string): 模式的名称。
priority (可选, int): 模式的优先级（数字越小越先尝试）。默认为 0。
default_obis (可选, string): 如果模式未捕获 OBIS 代码，则使用的回退 OBIS 代码。要求设置 name。格式如 1-0:96.1.0 或 1.0.96.1.0.255。

内置模式

dlms_meter 组件默认加载几个内置模式。内置模式从优先级 10 开始。您的自定义模式将与这些模式一起根据其配置的 priority 进行评估。

名称	优先级	典型用途
`classId-taggedObis-scaler-value`	10	class ID、标记的 OBIS、scaler、value
`taggedObis-value-scalerUnit`	20	标记的 OBIS、value、scaler-unit 结构
`value-classId-scalerUnit-taggedObis`	30	value 优先、class ID、scaler-unit、OBIS
`zpaAidon-untaggedLayout`	40	未标记的 ZPA/Aidon 风格布局
`structuredObis-value-scalerUnit`	50	OBIS、value、scaler-unit 结构
`structuredObis-value`	60	OBIS 和 value 结构
`flatObis-valuePair`	70	扁平 OBIS + 值对
`firstElement-dateTime`	80	首元素日期时间结构
`swappedTagObis-value-scalerUnit`	90	交换标记的 OBIS、value、scaler-unit

常见自定义模式示例

以下是一些您可能在非标准电表上遇到的常见结构：

NOTE

其中许多现在已由默认内置模式覆盖，但可进一步自定义

dlms_meter:
  # ...
  custom_patterns:
    - pattern: "TC, TO, TDTM"
      name: "日期时间值"
    - pattern: "C, O, A, V, TS, TU"
      name: "未标记扁平"
    - pattern: "TO, TV, S(TS, TU)"
      name: "带 scaler-unit 的标记"
    - pattern: "TO, TV"
      name: "扁平 OBIS + 值对（无 scaler）"
    - pattern: "L, TSTR"
      name: "最后元素为字符串"
    - pattern: "TOW, TV, TSU"
      name: "Landis+Gyr 交换的 OBIS"

模式的令牌参考

令牌	含义	十六进制示例
`F`	首元素守卫	仅位置检查
`L`	末元素守卫	仅位置检查
`C`	class ID，2 字节无标签 uint16	`00 03`
`TC`	带标签的 class ID	`12 00 03`
`O`	OBIS 代码，6 字节无标签八位字节串	`01 00 01 08 00 FF`
`TO`	带标签的 OBIS 代码	`09 06 01 00 01 08 00 FF`
`TOW`	带标签的 OBIS，标签字节交换	`06 09 01 00 1F 07 00 FF`
`A`	属性索引，1 字节无标签 uint8	`02`
`TA`	带标签的属性	`11 02` 或 `0F 02`
`V` / `TV`	通用值	`06 00 00 07 A4`
`TSTR`	带标签的类字符串值	`09 08 38 34 38 39 35 31 32 36`
`TDTM`	带标签的 12 字节日期时间值	`19 ...` 或 `09 0C ...`
`TS`	带标签的 scaler	`0F FF`
`TU`	带标签的 unit 枚举	`16 23`
`TSU`	带标签的 scaler-unit 对	`02 02 0F FF 16 23`
`S(x, y, ...)`	内联子结构	`02 03`
`DN`	进入嵌套结构	控制令牌
`UP`	从嵌套结构返回	控制令牌

支持的电表

IMPORTANT

在添加任何 custom_patterns 之前，请始终检查您的电表读数是否已在使用默认设置时原生工作。组件的内置解析器会自动处理许多标准电表。

原生支持（无需自定义配置）

绝大多数符合标准的智能电表开箱即用。 如果您的电表遵循官方 DLMS 规范，通常只需提供 UART 引脚和您需要的 OBIS 代码。

我们已明确测试并确认对以下标准电表的原生支持（包括但不限于）：

Sagemcom XT211、Energomera、Kaifa MA304H3E、Salzburg Netz、Iskra 550 和 Norway HAN (Aidon 单相和三相)。

特定电表配置

一些制造商使用非标准对象结构或帧化来实现 DLMS 标准。以下是这些特定电表所需的测试配置参数：

Landis+Gyr ZMF100 : 此特定电表发送无效的帧检查序列（FCS），需要跳过 CRC 检查。（自定义解析模式原生支持）

dlms_meter:
  # ...
  skip_crc: true

Landis+Gyr E450 : 此电表使用加密，需要来自您提供商的解密密钥。

dlms_meter:
  # ...
  decryption_key: "YOUR_32_CHAR_HEX_KEY"
  custom_patterns:
    - pattern: "F, TDTM"
      name: "DateTime"

Kamstrup Omnipower : 此电表使用加密。某些地区变体还强制要求认证密钥。

dlms_meter:
  # ...
  decryption_key: "YOUR_32_CHAR_HEX_KEY"
  auth_key: "YOUR_32_CHAR_AUTH_KEY" # 如提供商要求则添加
  custom_patterns:
    - pattern: "F, TSTR"
      name: "Obis List Ver"

Netz NOE P1 (M-Bus) : 需要加密。MeterID 未标记，需要回退默认 OBIS 映射。

dlms_meter:
  # ...
  decryption_key: "YOUR_32_CHAR_HEX_KEY"
  custom_patterns:
    - pattern: "L, TSTR"
      name: "MeterID"
      default_obis: "0.0.96.1.0.255"
    - pattern: "F, TDTM"
      name: "DateTime"
      default_obis: "0.0.1.0.0.255"

KAIFA MA309M : 需要以下自定义模式以正确解码电表 ID 和时间戳。注意：此电表不发送无功功率、功率因子或频率。

dlms_meter:
  # ...
  decryption_key: "YOUR_32_CHAR_HEX_KEY"
  custom_patterns:
    - pattern: "L, TSTR"
      name: "MeterID"
      default_obis: "0.0.96.1.0.255"
    - pattern: "F, TDTM"
      name: "DateTime"
      default_obis: "0.0.1.0.0.255"

（当用户报告其独特智能电表固件所需的特定设置时，可从制造商处添加额外的说明和特定 custom_patterns。）