From 74ae767de592bec8a65d142ef91f6a4215b9e075 Mon Sep 17 00:00:00 2001 From: Tomer27cz <85194189+Tomer27cz@users.noreply.github.com> Date: Tue, 7 Apr 2026 16:57:42 +0200 Subject: [PATCH 01/11] update for dlms_parser lib --- .../docs/components/sensor/dlms_meter.mdx | 237 +++++++++--------- 1 file changed, 115 insertions(+), 122 deletions(-) diff --git a/src/content/docs/components/sensor/dlms_meter.mdx b/src/content/docs/components/sensor/dlms_meter.mdx index 3cf5ec1f1f..9f01b643e9 100644 --- a/src/content/docs/components/sensor/dlms_meter.mdx +++ b/src/content/docs/components/sensor/dlms_meter.mdx @@ -1,159 +1,152 @@ --- title: "DLMS Meter" -description: "Instructions for setting up DLMS (COSEM) smart meter integration using an M-Bus to UART adapter." +description: "Instructions for setting up DLMS (COSEM) smart meter integration" --- import APIClass from '@components/APIClass.astro'; import APIRef from '@components/APIRef.astro'; import { Image } from 'astro:assets'; -The `dlms_meter` component connects to smart meters which use the encrypted **DLMS/COSEM** protocol over UART. These -smart meters are (for example) widely deployed in Austria. +The `dlms_meter` component connects to smart meters which use the **DLMS/COSEM** protocol over UART. +These smart meters are widely deployed globally. -**An M-Bus to UART adapter is required.** You must also request the 32‑character hexadecimal decryption key from your -energy provider / grid operator. +By offloading the complex parsing logic to the dedicated [dlms_parser](https://github.com/esphome-libs/dlms_parser) +library, the component is robust and capable of supporting a vast array of meters. -This component is passive; it does not transmit data to the meter. The meter periodically broadcasts frames (often -about every 5 seconds). ESPHome listens, decrypts and updates the configured sensors as data arrives. +This component is passive; it does not transmit data to the meter. The meter periodically broadcasts frames. +ESPHome listens, decodes (and decrypts if necessary), and updates the configured sensors as data arrives. + +**An appropriate UART adapter (like an M-Bus to UART module) is required.** For encrypted meters, you must request +the 32‑character hexadecimal decryption key from your energy provider / grid operator. If your meter broadcasts +in plaintext, the decryption key is not needed. Smart meter with M-Bus adapter board to ESP32 -## Example (Generic Provider) +## Example Configuration ```yaml -# Example configuration entry for a generic grid operator uart: - rx_pin: GPIOXX # Adjust for where the M-Bus adapter RX is connected - baud_rate: 2400 + id: uart_bus + rx_pin: GPIOXX # Adjust for where the adapter RX is connected + baud_rate: 9600 # Adjust according to your meter's specification rx_buffer_size: 1024 # Needed for large frames dlms_meter: - decryption_key: "01234567890123456789012345678901" # Replace with your key + id: dlms_meter_hub + decryption_key: "01234567890123456789012345678901" # Optional: Replace with your key if encrypted + auth_key: "..." # Optional: Auth key if required + skip_crc: false # Optional: Skip CRC checks + custom_patterns: # Optional: For custom meter payloads + - pattern: "TO, TV" + name: "flat OBIS + value pairs" sensor: + # --- Dynamic Schema via OBIS Code (Recommended) --- - platform: dlms_meter - voltage_l1: - name: "Voltage L1" - voltage_l2: - name: "Voltage L2" - voltage_l3: - name: "Voltage L3" - current_l1: - name: "Current L1" - current_l2: - name: "Current L2" - current_l3: - name: "Current L3" - active_power_plus: - name: "Active power taken from grid" - active_power_minus: - name: "Active power put into grid" - active_energy_plus: - name: "Active energy taken from grid" - active_energy_minus: - name: "Active energy put into grid" - reactive_energy_plus: - name: "Reactive energy taken from grid" - reactive_energy_minus: - name: "Reactive energy put into grid" + dlms_meter_id: dlms_meter_hub + obis_code: "1-0:1.7.0" + name: "Active power taken from grid" -text_sensor: - - platform: dlms_meter - timestamp: - name: "Timestamp" -``` - -### Example (Netz Noe / EVN) - -```yaml -uart: - rx_pin: GPIOXX - baud_rate: 2400 - rx_buffer_size: 1024 - -dlms_meter: - decryption_key: "01234567890123456789012345678901" # Replace with your key - provider: netznoe - -sensor: + # --- Legacy Schema (Supported for backwards compatibility) --- - platform: dlms_meter voltage_l1: name: "Voltage L1" - voltage_l2: - name: "Voltage L2" - voltage_l3: - name: "Voltage L3" - current_l1: - name: "Current L1" - current_l2: - name: "Current L2" - current_l3: - name: "Current L3" - active_power_plus: - name: "Active power taken from grid" - active_power_minus: - name: "Active power put into grid" - active_energy_plus: - name: "Active energy taken from grid" - active_energy_minus: - name: "Active energy put into grid" - power_factor: # EVN specific - name: "Power Factor" text_sensor: - platform: dlms_meter - timestamp: - name: "Timestamp" - meternumber: # EVN specific - name: "Meter Number" + dlms_meter_id: dlms_meter_hub + obis_code: "0-0:96.1.0" + name: "Meter Number" + +binary_sensor: + - platform: dlms_meter + dlms_meter_id: dlms_meter_hub + obis_code: "0-1:2.3.4" + name: "Custom Binary Sensor" ``` ## Component Configuration -### Configuration Variables - -- **decryption_key** (**Required**, string, 32 hex chars, case-insensitive, templatable): Key used to decrypt DLMS telegrams. - Obtain this from your provider / grid operator. -- **provider** (*Optional*): Grid operator profile. Options: - - `generic` (default) – works for most operators. - - `netznoe` – Netz Noe / EVN specific mapping. - -## Sensor - -Not all sensors are available on all meters. Provider specific sensors are listed separately. - -### Configuration Variables - -Each of the following entries is *optional*; add only the ones you need. All support the standard [Sensor](/components/sensor) options. - -- **voltage_l1**: Voltage Phase 1. -- **voltage_l2**: Voltage Phase 2. -- **voltage_l3**: Voltage Phase 3. -- **current_l1**: Current Phase 1. -- **current_l2**: Current Phase 2. -- **current_l3**: Current Phase 3. -- **active_power_plus**: Active power taken from grid. -- **active_power_minus**: Active power put into grid. -- **active_energy_plus**: Cumulative active energy taken from grid. -- **active_energy_minus**: Cumulative active energy exported to grid. -- **reactive_energy_plus**: Reactive energy taken from grid. -- **reactive_energy_minus**: Reactive energy exported to grid. - -#### Netz Noe / EVN Additional Sensor - -- **power_factor**: Power factor. All options from [Sensor](/components/sensor). - -## Text Sensor - -### Configuration Variables - -All text sensor entries are *optional* and support standard [Text Sensor](/components/text_sensor#config-text_sensor) options. - -- **timestamp**: Timestamp included in the received frame. - -#### Netz Noe / EVN Additional Text Sensor +### Core Configuration Variables + +- **id** (*Optional*, [ID](/guides/configuration-types#config-id)): The ID of the `dlms_meter` component. +- **decryption_key** (*Optional*, string): Key used to decrypt DLMS telegrams (32 hex characters, case-insensitive). +Obtain this from your provider if your meter is encrypted. +- **auth_key** (*Optional*, string): Authentication key for `General-GLO-Ciphering` and `General-DED-Ciphering` +APDUs (32 hex characters). +- **skip_crc** (*Optional*, boolean): Skip CRC checks. Defaults to `false`. +- **custom_patterns** (*Optional*, list): Define custom AXDR descriptor patterns to match your meter's telegram +structure if the built-in patterns do not match. + +#### Custom Patterns +You can define a custom pattern simply by passing its pattern string, or by defining an object with +additional properties: +- **pattern** (**Required**, string): The DSL-based pattern string (e.g., `"TO, TV"`). +- **name** (*Optional*, string): A name for the pattern. +- **priority** (*Optional*, integer): The priority of the pattern (lower number is tried first). Built-in patterns +start at 10. Defaults to `0`. +- **default_obis** (*Optional*, string): The fallback OBIS code to use if the pattern captures no OBIS code. +Formatted like `1-0:96.1.0` or `1.0.96.1.0.255`. Requires **name** to be set. + +**Token Reference for Patterns:** + +| Token | Meaning | Hex example | +|----------------|--------------------------------------------|---------------------------------| +| `F` | first element guard | position check only | +| `L` | last element guard | position check only | +| `C` | class ID, 2-byte uint16 without tag | `00 03` | +| `TC` | tagged class ID | `12 00 03` | +| `O` | OBIS code, 6-byte octet string without tag | `01 00 01 08 00 FF` | +| `TO` | tagged OBIS code | `09 06 01 00 01 08 00 FF` | +| `TOW` | tagged OBIS with swapped tag bytes | `06 09 01 00 1F 07 00 FF` | +| `A` | attribute index, 1-byte uint8 without tag | `02` | +| `TA` | tagged attribute | `11 02` or `0F 02` | +| `V` / `TV` | generic value | `06 00 00 07 A4` | +| `TSTR` | tagged string-like value | `09 08 38 34 38 39 35 31 32 36` | +| `TDTM` | tagged 12-byte date-time value | `19 ...` or `09 0C ...` | +| `TS` | tagged scaler | `0F FF` | +| `TU` | tagged unit enum | `16 23` | +| `TSU` | tagged scaler-unit pair | `02 02 0F FF 16 23` | +| `S(x, y, ...)` | inline sub-structure | `02 03` | +| `DN` | descend into nested structure | control token | +| `UP` | return from nested structure | control token | +--- -- **meternumber**: Meter number reported by the device. +## Platforms + +### Sensor / Text Sensor / Binary Sensor + +All platforms (`sensor`, `text_sensor`, `binary_sensor`) support dynamic mapping using the `obis_code` property. +This allows you to decode nearly any property your meter emits. + +- **dlms_meter_id** (*Optional*, [ID](/guides/configuration-types#config-id)): Manually specify the ID of the +`dlms_meter` hub if you have multiple. +- **obis_code** (*Optional*, string): The OBIS code of the value you want to read. The code supports flexible +formats like `1-0:32.7.0` or `1.0.32.7.0.255`. + +### Legacy Keys +For backwards compatibility, the legacy predefined keys from earlier versions are still fully supported and mapped +automatically to their respective OBIS codes. Add only the ones you need. All support standard options from their +respective platform domains. + +**Sensors:** +- **voltage_l1** (`1-0:32.7.0`): Voltage Phase 1. +- **voltage_l2** (`1-0:52.7.0`): Voltage Phase 2. +- **voltage_l3** (`1-0:72.7.0`): Voltage Phase 3. +- **current_l1** (`1-0:31.7.0`): Current Phase 1. +- **current_l2** (`1-0:51.7.0`): Current Phase 2. +- **current_l3** (`1-0:71.7.0`): Current Phase 3. +- **active_power_plus** (`1-0:1.7.0`): Active power taken from grid. +- **active_power_minus** (`1-0:2.7.0`): Active power put into grid. +- **active_energy_plus** (`1-0:1.8.0`): Cumulative active energy taken from grid. +- **active_energy_minus** (`1-0:2.8.0`): Cumulative active energy exported to grid. +- **reactive_energy_plus** (`1-0:3.8.0`): Reactive energy taken from grid. +- **reactive_energy_minus** (`1-0:4.8.0`): Reactive energy exported to grid. +- **power_factor** (`1-0:13.7.0`): Power factor. + +**Text Sensors:** +- **timestamp** (`0-0:1.0.0`): Timestamp included in the received frame. +- **meternumber** (`0-0:96.1.0`): Meter number reported by the device. ## See Also From 2ea8b628982209fa154c33d199de01da7fcb754d Mon Sep 17 00:00:00 2001 From: PolarGoose <35307286+PolarGoose@users.noreply.github.com> Date: Tue, 7 Apr 2026 18:03:35 +0200 Subject: [PATCH 02/11] Start improving the documentation. Move all configuration specification into yaml code like it is done for DSMR component. --- .../docs/components/sensor/dlms_meter.mdx | 84 +++++++++---------- 1 file changed, 39 insertions(+), 45 deletions(-) diff --git a/src/content/docs/components/sensor/dlms_meter.mdx b/src/content/docs/components/sensor/dlms_meter.mdx index 9f01b643e9..f488d5969f 100644 --- a/src/content/docs/components/sensor/dlms_meter.mdx +++ b/src/content/docs/components/sensor/dlms_meter.mdx @@ -7,38 +7,55 @@ import APIClass from '@components/APIClass.astro'; import APIRef from '@components/APIRef.astro'; import { Image } from 'astro:assets'; -The `dlms_meter` component connects to smart meters which use the **DLMS/COSEM** protocol over UART. -These smart meters are widely deployed globally. +The `dlms_meter` component connects to smart meters which use the **DLMS/COSEM** protocol in PUSH mode over UART.
+These smart meters are widely deployed globally.
-By offloading the complex parsing logic to the dedicated [dlms_parser](https://github.com/esphome-libs/dlms_parser) -library, the component is robust and capable of supporting a vast array of meters. - -This component is passive; it does not transmit data to the meter. The meter periodically broadcasts frames. +The component does not transmit data to the meter. The meter periodically broadcasts frames. ESPHome listens, decodes (and decrypts if necessary), and updates the configured sensors as data arrives. -**An appropriate UART adapter (like an M-Bus to UART module) is required.** For encrypted meters, you must request -the 32‑character hexadecimal decryption key from your energy provider / grid operator. If your meter broadcasts -in plaintext, the decryption key is not needed. - Smart meter with M-Bus adapter board to ESP32 -## Example Configuration +## Prerequisites + +* You should have a special adater to connect EspHome board to the smart meter. For example `M-Bus to UART module`. +* If your meter uses encryption you should request the 32‑character hexadecimal decryption key. For some meter you also need an authentication key. + +## Configuration ```yaml uart: - id: uart_bus - rx_pin: GPIOXX # Adjust for where the adapter RX is connected - baud_rate: 9600 # Adjust according to your meter's specification - rx_buffer_size: 1024 # Needed for large frames + id: uart_dlms_bus + rx_pin: GPIOXX # pin that is connected to the RX pin of the adapter + baud_rate: 9600 # baud rate that the smart meter uses + rx_buffer_size: 1024 # recommended to avoid byte losses +# Configure dlms_meter component dlms_meter: id: dlms_meter_hub - decryption_key: "01234567890123456789012345678901" # Optional: Replace with your key if encrypted - auth_key: "..." # Optional: Auth key if required - skip_crc: false # Optional: Skip CRC checks - custom_patterns: # Optional: For custom meter payloads - - pattern: "TO, TV" - name: "flat OBIS + value pairs" + + # Optional. Decryption key. Specify if your smart meter uses encryption. + # You should request this key from your electricity provider. + decryption_key: "01234567890123456789012345678901" + + # Optional. Authentication key. Specify if your smart meter uses encryption with autentification. + # You should request this key from your electricity provider. + auth_key: "01234567890123456789012345678901" + + # Optional. Skip CRC check. Some smart meters use wrong polinom to calculate CRC. + # In such cases you can use this flag as a workaround. + skip_crc: false + + # Optional. The dlms_meter already configured to correctly parse the data from most of the meters. + # Some meters use a different way to package the data into the payload. + # In such cases you must specify custom patterns to tell the dlms_meter how to parse the payload. + custom_patterns: + - pattern: "TO, TV" # The DSL-based pattern string + name: "flat OBIS + value pairs" # Optional. A name for the pattern. + priority: 15 # Optional. The priority of the pattern (lower number is tried first). + # Default value is 0. + default_obis: "1-0:96.1.0" # Optional. The fallback OBIS code to use if the pattern + # captures no OBIS code. Requires 'name' to be set. + # Format is like "1-0:96.1.0" or "1.0.96.1.0.255" sensor: # --- Dynamic Schema via OBIS Code (Recommended) --- @@ -65,30 +82,7 @@ binary_sensor: name: "Custom Binary Sensor" ``` -## Component Configuration - -### Core Configuration Variables - -- **id** (*Optional*, [ID](/guides/configuration-types#config-id)): The ID of the `dlms_meter` component. -- **decryption_key** (*Optional*, string): Key used to decrypt DLMS telegrams (32 hex characters, case-insensitive). -Obtain this from your provider if your meter is encrypted. -- **auth_key** (*Optional*, string): Authentication key for `General-GLO-Ciphering` and `General-DED-Ciphering` -APDUs (32 hex characters). -- **skip_crc** (*Optional*, boolean): Skip CRC checks. Defaults to `false`. -- **custom_patterns** (*Optional*, list): Define custom AXDR descriptor patterns to match your meter's telegram -structure if the built-in patterns do not match. - -#### Custom Patterns -You can define a custom pattern simply by passing its pattern string, or by defining an object with -additional properties: -- **pattern** (**Required**, string): The DSL-based pattern string (e.g., `"TO, TV"`). -- **name** (*Optional*, string): A name for the pattern. -- **priority** (*Optional*, integer): The priority of the pattern (lower number is tried first). Built-in patterns -start at 10. Defaults to `0`. -- **default_obis** (*Optional*, string): The fallback OBIS code to use if the pattern captures no OBIS code. -Formatted like `1-0:96.1.0` or `1.0.96.1.0.255`. Requires **name** to be set. - -**Token Reference for Patterns:** +## Token Reference for Patterns | Token | Meaning | Hex example | |----------------|--------------------------------------------|---------------------------------| From 6a6aec238254823caa1572ec3c5ac9ef8311e313 Mon Sep 17 00:00:00 2001 From: PolarGoose <35307286+PolarGoose@users.noreply.github.com> Date: Tue, 7 Apr 2026 18:27:10 +0200 Subject: [PATCH 03/11] Move more to the yaml example --- .../docs/components/sensor/dlms_meter.mdx | 33 ++++++++----------- 1 file changed, 13 insertions(+), 20 deletions(-) diff --git a/src/content/docs/components/sensor/dlms_meter.mdx b/src/content/docs/components/sensor/dlms_meter.mdx index f488d5969f..51fbd9e1ea 100644 --- a/src/content/docs/components/sensor/dlms_meter.mdx +++ b/src/content/docs/components/sensor/dlms_meter.mdx @@ -33,13 +33,16 @@ uart: dlms_meter: id: dlms_meter_hub + # Name of the uart component that is connected to the smart meter + uart_id: uart_dlms_bus + # Optional. Decryption key. Specify if your smart meter uses encryption. # You should request this key from your electricity provider. - decryption_key: "01234567890123456789012345678901" + decryption_key: "00112233445566778899AABBCCDDEEFF" # Optional. Authentication key. Specify if your smart meter uses encryption with autentification. # You should request this key from your electricity provider. - auth_key: "01234567890123456789012345678901" + auth_key: "00112233445566778899AABBCCDDEEFF" # Optional. Skip CRC check. Some smart meters use wrong polinom to calculate CRC. # In such cases you can use this flag as a workaround. @@ -57,11 +60,11 @@ dlms_meter: # captures no OBIS code. Requires 'name' to be set. # Format is like "1-0:96.1.0" or "1.0.96.1.0.255" +# Specify sensors sensor: - # --- Dynamic Schema via OBIS Code (Recommended) --- - platform: dlms_meter - dlms_meter_id: dlms_meter_hub - obis_code: "1-0:1.7.0" + dlms_meter_id: dlms_meter_hub # Optional. + obis_code: "1-0:1.7.0" # OBIS code. Format is like "1-0:96.1.0" or "1.0.96.1.0.255" name: "Active power taken from grid" # --- Legacy Schema (Supported for backwards compatibility) --- @@ -69,16 +72,18 @@ sensor: voltage_l1: name: "Voltage L1" +# Specify text sensors text_sensor: - platform: dlms_meter - dlms_meter_id: dlms_meter_hub - obis_code: "0-0:96.1.0" + dlms_meter_id: dlms_meter_hub # Optional + obis_code: "0-0:96.1.0" # OBIS code. Format is like "1-0:96.1.0" or "1.0.96.1.0.255" name: "Meter Number" +# Specify binary sensors binary_sensor: - platform: dlms_meter dlms_meter_id: dlms_meter_hub - obis_code: "0-1:2.3.4" + obis_code: "0-1:2.3.4" # OBIS code. Format is like "1-0:96.1.0" or "1.0.96.1.0.255" name: "Custom Binary Sensor" ``` @@ -106,18 +111,6 @@ binary_sensor: | `UP` | return from nested structure | control token | --- -## Platforms - -### Sensor / Text Sensor / Binary Sensor - -All platforms (`sensor`, `text_sensor`, `binary_sensor`) support dynamic mapping using the `obis_code` property. -This allows you to decode nearly any property your meter emits. - -- **dlms_meter_id** (*Optional*, [ID](/guides/configuration-types#config-id)): Manually specify the ID of the -`dlms_meter` hub if you have multiple. -- **obis_code** (*Optional*, string): The OBIS code of the value you want to read. The code supports flexible -formats like `1-0:32.7.0` or `1.0.32.7.0.255`. - ### Legacy Keys For backwards compatibility, the legacy predefined keys from earlier versions are still fully supported and mapped automatically to their respective OBIS codes. Add only the ones you need. All support standard options from their From 787181559989efeb81a2a9c3d570696cfc0f3577 Mon Sep 17 00:00:00 2001 From: Tomer27cz <85194189+Tomer27cz@users.noreply.github.com> Date: Tue, 7 Apr 2026 21:38:59 +0200 Subject: [PATCH 04/11] guidelines --- .../docs/components/sensor/dlms_meter.mdx | 116 ++++++++++-------- 1 file changed, 65 insertions(+), 51 deletions(-) diff --git a/src/content/docs/components/sensor/dlms_meter.mdx b/src/content/docs/components/sensor/dlms_meter.mdx index 51fbd9e1ea..5900891647 100644 --- a/src/content/docs/components/sensor/dlms_meter.mdx +++ b/src/content/docs/components/sensor/dlms_meter.mdx @@ -7,87 +7,70 @@ import APIClass from '@components/APIClass.astro'; import APIRef from '@components/APIRef.astro'; import { Image } from 'astro:assets'; -The `dlms_meter` component connects to smart meters which use the **DLMS/COSEM** protocol in PUSH mode over UART.
-These smart meters are widely deployed globally.
+The `dlms_meter` component connects to smart meters which use the **DLMS/COSEM** protocol in PUSH mode over UART. +These smart meters are widely deployed globally. The component does not transmit data to the meter. The meter periodically broadcasts frames. ESPHome listens, decodes (and decrypts if necessary), and updates the configured sensors as data arrives. -Smart meter with M-Bus adapter board to ESP32 - -## Prerequisites +> [!NOTE] +> An adapter (like an `M-Bus to UART module`) is required to connect the EspHome board to the smart meter. +> +> For **encrypted meters**, you must request a 32-character hexadecimal **decryption key** from your energy provider. -* You should have a special adater to connect EspHome board to the smart meter. For example `M-Bus to UART module`. -* If your meter uses encryption you should request the 32‑character hexadecimal decryption key. For some meter you also need an authentication key. +Smart meter with M-Bus adapter board to ESP32 ## Configuration ```yaml uart: id: uart_dlms_bus - rx_pin: GPIOXX # pin that is connected to the RX pin of the adapter - baud_rate: 9600 # baud rate that the smart meter uses - rx_buffer_size: 1024 # recommended to avoid byte losses + rx_pin: GPIOXX + baud_rate: 9600 -# Configure dlms_meter component dlms_meter: id: dlms_meter_hub - - # Name of the uart component that is connected to the smart meter uart_id: uart_dlms_bus - # Optional. Decryption key. Specify if your smart meter uses encryption. - # You should request this key from your electricity provider. - decryption_key: "00112233445566778899AABBCCDDEEFF" - - # Optional. Authentication key. Specify if your smart meter uses encryption with autentification. - # You should request this key from your electricity provider. - auth_key: "00112233445566778899AABBCCDDEEFF" - - # Optional. Skip CRC check. Some smart meters use wrong polinom to calculate CRC. - # In such cases you can use this flag as a workaround. - skip_crc: false - - # Optional. The dlms_meter already configured to correctly parse the data from most of the meters. - # Some meters use a different way to package the data into the payload. - # In such cases you must specify custom patterns to tell the dlms_meter how to parse the payload. - custom_patterns: - - pattern: "TO, TV" # The DSL-based pattern string - name: "flat OBIS + value pairs" # Optional. A name for the pattern. - priority: 15 # Optional. The priority of the pattern (lower number is tried first). - # Default value is 0. - default_obis: "1-0:96.1.0" # Optional. The fallback OBIS code to use if the pattern - # captures no OBIS code. Requires 'name' to be set. - # Format is like "1-0:96.1.0" or "1.0.96.1.0.255" - -# Specify sensors sensor: - platform: dlms_meter - dlms_meter_id: dlms_meter_hub # Optional. - obis_code: "1-0:1.7.0" # OBIS code. Format is like "1-0:96.1.0" or "1.0.96.1.0.255" + dlms_meter_id: dlms_meter_hub + obis_code: "1-0:1.7.0" name: "Active power taken from grid" - # --- Legacy Schema (Supported for backwards compatibility) --- - - platform: dlms_meter - voltage_l1: - name: "Voltage L1" - -# Specify text sensors text_sensor: - platform: dlms_meter - dlms_meter_id: dlms_meter_hub # Optional - obis_code: "0-0:96.1.0" # OBIS code. Format is like "1-0:96.1.0" or "1.0.96.1.0.255" + dlms_meter_id: dlms_meter_hub + obis_code: "0-0:96.1.0" name: "Meter Number" -# Specify binary sensors binary_sensor: - platform: dlms_meter dlms_meter_id: dlms_meter_hub - obis_code: "0-1:2.3.4" # OBIS code. Format is like "1-0:96.1.0" or "1.0.96.1.0.255" + obis_code: "0-1:2.3.4" name: "Custom Binary Sensor" ``` -## Token Reference for Patterns +## Configuration variables + +- **id** (*Optional*, [ID](/guides/configuration-types#config-id)): The ID of the `dlms_meter` component. +- **uart_id** (*Optional*, [ID](/guides/configuration-types#config-id)): The ID of the UART bus to connect to. +- **decryption_key** (*Optional*, string): Key used to decrypt DLMS telegrams (32 hex characters, case-insensitive). +- **auth_key** (*Optional*, string): Authentication key for `General-GLO-Ciphering` and `General-DED-Ciphering` APDUs. +- **skip_crc** (*Optional*, boolean): Skip CRC checks. Defaults to `false`. +- **custom_patterns** (*Optional*, list): Define custom AXDR descriptor patterns to match the meter's telegram structure. + +### Custom Patterns + +You can define a custom pattern simply by passing its pattern string, or by defining an object with additional properties: + +- **pattern** (**Required**, string): The DSL-based pattern string (e.g., `"TO, TV"`). +- **name** (*Optional*, string): A name for the pattern. +- **priority** (*Optional*, int): The priority of the pattern (lower number is tried first). Defaults to `0`. +- **default_obis** (*Optional*, string): The fallback OBIS code to use if the pattern captures no OBIS code. Requires +**name** to be set. Formatted like `1-0:96.1.0` or `1.0.96.1.0.255`. + +### Token Reference for Patterns | Token | Meaning | Hex example | |----------------|--------------------------------------------|---------------------------------| @@ -111,12 +94,42 @@ binary_sensor: | `UP` | return from nested structure | control token | --- +## Platforms + +### Sensor / Text Sensor / Binary Sensor + +All platforms (`sensor`, `text_sensor`, `binary_sensor`) support dynamic mapping using the `obis_code` property. This +allows you to decode nearly any property your meter emits. + +- **dlms_meter_id** (*Optional*, [ID](/guides/configuration-types#config-id)): Manually specify the ID of the +`dlms_meter` hub if you have multiple. +- **obis_code** (**Required**, string): The OBIS code of the value you want to read. The code supports flexible formats +like `1-0:32.7.0` or `1.0.32.7.0.255`. + ### Legacy Keys + For backwards compatibility, the legacy predefined keys from earlier versions are still fully supported and mapped automatically to their respective OBIS codes. Add only the ones you need. All support standard options from their respective platform domains. +```yaml +sensor: + - platform: dlms_meter + dlms_meter_id: dlms_meter_hub + voltage_l1: + name: "Voltage Phase 1" + voltage_l2: + name: "Voltage Phase 2" + +text_sensor: + - platform: dlms_meter + dlms_meter_id: dlms_meter_hub + meternumber: + name: "Meter Number" +``` + **Sensors:** + - **voltage_l1** (`1-0:32.7.0`): Voltage Phase 1. - **voltage_l2** (`1-0:52.7.0`): Voltage Phase 2. - **voltage_l3** (`1-0:72.7.0`): Voltage Phase 3. @@ -132,6 +145,7 @@ respective platform domains. - **power_factor** (`1-0:13.7.0`): Power factor. **Text Sensors:** + - **timestamp** (`0-0:1.0.0`): Timestamp included in the received frame. - **meternumber** (`0-0:96.1.0`): Meter number reported by the device. From 4f763e7fb3709bca3bccb63c7669df1808551035 Mon Sep 17 00:00:00 2001 From: Tomer27cz <85194189+Tomer27cz@users.noreply.github.com> Date: Tue, 7 Apr 2026 22:09:58 +0200 Subject: [PATCH 05/11] add pattern examples add advanced config with all optional values add information from deleted comments in yaml to the configuration variables --- .../docs/components/sensor/dlms_meter.mdx | 74 +++++++++++++++++-- 1 file changed, 67 insertions(+), 7 deletions(-) diff --git a/src/content/docs/components/sensor/dlms_meter.mdx b/src/content/docs/components/sensor/dlms_meter.mdx index 5900891647..5113cd33e1 100644 --- a/src/content/docs/components/sensor/dlms_meter.mdx +++ b/src/content/docs/components/sensor/dlms_meter.mdx @@ -51,14 +51,40 @@ binary_sensor: name: "Custom Binary Sensor" ``` +### Advanced Configuration Example + +This example demonstrates how to use the optional configuration variables for encrypted meters or those requiring custom +parsing patterns. + +```yaml +dlms_meter: + id: dlms_meter_hub + uart_id: uart_dlms_bus + decryption_key: "00112233445566778899AABBCCDDEEFF" + auth_key: "00112233445566778899AABBCCDDEEFF" + skip_crc: false + custom_patterns: + - pattern: "TO, TV" + name: "flat OBIS + value pairs" + priority: 15 + default_obis: "1-0:96.1.0" +``` + ## Configuration variables - **id** (*Optional*, [ID](/guides/configuration-types#config-id)): The ID of the `dlms_meter` component. -- **uart_id** (*Optional*, [ID](/guides/configuration-types#config-id)): The ID of the UART bus to connect to. -- **decryption_key** (*Optional*, string): Key used to decrypt DLMS telegrams (32 hex characters, case-insensitive). -- **auth_key** (*Optional*, string): Authentication key for `General-GLO-Ciphering` and `General-DED-Ciphering` APDUs. -- **skip_crc** (*Optional*, boolean): Skip CRC checks. Defaults to `false`. -- **custom_patterns** (*Optional*, list): Define custom AXDR descriptor patterns to match the meter's telegram structure. +- **uart_id** (*Optional*, [ID](/guides/configuration-types#config-id)): The ID of the UART component that is +connected to the smart meter. +- **decryption_key** (*Optional*, string): Specify if your smart meter uses encryption. You should request this key +from your electricity provider (32 hex characters, case-insensitive). +- **auth_key** (*Optional*, string): Authentication key. Specify if your smart meter uses encryption with +authentication. You should request this key from your electricity provider. Used for `General-GLO-Ciphering` and +`General-DED-Ciphering` APDUs. +- **skip_crc** (*Optional*, boolean): Skip CRC check. Some smart meters use the wrong polynomial to calculate CRC. +In such cases, you can use this flag as a workaround. Defaults to `false`. +- **custom_patterns** (*Optional*, list): While the `dlms_meter` natively supports most devices, some meters use unique +payload structures. If your meter's data isn't being read correctly, use this field to define a **custom AXDR +descriptor pattern** that tells the system how to parse the incoming data. ### Custom Patterns @@ -70,6 +96,40 @@ You can define a custom pattern simply by passing its pattern string, or by defi - **default_obis** (*Optional*, string): The fallback OBIS code to use if the pattern captures no OBIS code. Requires **name** to be set. Formatted like `1-0:96.1.0` or `1.0.96.1.0.255`. +#### Built-in Patterns + +The `dlms_meter` component loads several built-in patterns by default. Your custom patterns will be evaluated alongside +these based on their configured `priority`. + +| Name | Priority | Typical use | +|---------|---------:|-------------------------------------------| +| `T1` | 10 | class ID, tagged OBIS, scaler, value | +| `T2` | 20 | tagged OBIS, value, scaler-unit structure | +| `T3` | 30 | value first, class ID, scaler-unit, OBIS | +| `U.ZPA` | 40 | untagged ZPA/Aidon-style layouts | + +#### Common Custom Pattern Examples + +Here are some common structures you might encounter on less standard meters: + +```yaml +dlms_meter: + # ... + custom_patterns: + - pattern: "TC, TO, TDTM" + name: "datetime value" + - pattern: "C, O, A, V, TS, TU" + name: "untagged flat" + - pattern: "TO, TV, S(TS, TU)" + name: "tagged with scaler-unit" + - pattern: "TO, TV" + name: "flat OBIS + value pairs (no scaler)" + - pattern: "L, TSTR" + name: "last element as string" + - pattern: "TOW, TV, TSU" + name: "Landis+Gyr swapped OBIS" +``` + ### Token Reference for Patterns | Token | Meaning | Hex example | @@ -98,8 +158,8 @@ You can define a custom pattern simply by passing its pattern string, or by defi ### Sensor / Text Sensor / Binary Sensor -All platforms (`sensor`, `text_sensor`, `binary_sensor`) support dynamic mapping using the `obis_code` property. This -allows you to decode nearly any property your meter emits. +All platforms (`sensor`, `text_sensor`, `binary_sensor`) support dynamic mapping using the `obis_code` property. +This allows you to decode nearly any property your meter emits. - **dlms_meter_id** (*Optional*, [ID](/guides/configuration-types#config-id)): Manually specify the ID of the `dlms_meter` hub if you have multiple. From 52da144b9445ad9055b1ee82ddd0e4f594eaf448 Mon Sep 17 00:00:00 2001 From: Tomer27cz <85194189+Tomer27cz@users.noreply.github.com> Date: Tue, 7 Apr 2026 22:34:24 +0200 Subject: [PATCH 06/11] reorganization --- .../docs/components/sensor/dlms_meter.mdx | 174 ++++++++---------- 1 file changed, 81 insertions(+), 93 deletions(-) diff --git a/src/content/docs/components/sensor/dlms_meter.mdx b/src/content/docs/components/sensor/dlms_meter.mdx index 5113cd33e1..544f8881e8 100644 --- a/src/content/docs/components/sensor/dlms_meter.mdx +++ b/src/content/docs/components/sensor/dlms_meter.mdx @@ -5,29 +5,28 @@ description: "Instructions for setting up DLMS (COSEM) smart meter integration" import APIClass from '@components/APIClass.astro'; import APIRef from '@components/APIRef.astro'; -import { Image } from 'astro:assets'; The `dlms_meter` component connects to smart meters which use the **DLMS/COSEM** protocol in PUSH mode over UART. These smart meters are widely deployed globally. -The component does not transmit data to the meter. The meter periodically broadcasts frames. -ESPHome listens, decodes (and decrypts if necessary), and updates the configured sensors as data arrives. +The component does not transmit data to the meter. The meter periodically broadcasts frames. ESPHome listens, decodes +(and decrypts if necessary), and updates the configured sensors as data arrives. > [!NOTE] > An adapter (like an `M-Bus to UART module`) is required to connect the EspHome board to the smart meter. > > For **encrypted meters**, you must request a 32-character hexadecimal **decryption key** from your energy provider. -Smart meter with M-Bus adapter board to ESP32 +![Smart meter with M-Bus adapter board to ESP32](/images/dlms_meter.jpg) ## Configuration -```yaml -uart: - id: uart_dlms_bus - rx_pin: GPIOXX - baud_rate: 9600 +This component requires a [UART bus](/components/uart/) to be configured. + +> [!TIP] +> The UART configuration depends on your specific meter hardware. Be sure to consult your meter's specifications. +```yaml dlms_meter: id: dlms_meter_hub uart_id: uart_dlms_bus @@ -37,21 +36,80 @@ sensor: dlms_meter_id: dlms_meter_hub obis_code: "1-0:1.7.0" name: "Active power taken from grid" +``` -text_sensor: +## Configuration variables + +- **id** (*Optional*, [ID](/guides/configuration-types#config-id)): The ID of the `dlms_meter` component. +- **uart_id** (*Optional*, [ID](/guides/configuration-types#config-id)): The ID of the UART component that is +connected to the smart meter. +- **decryption_key** (*Optional*, string): Specify if your smart meter uses encryption. You should request this key +from your electricity provider (32 hex characters, case-insensitive). +- **auth_key** (*Optional*, string): Authentication key. Specify if your smart meter uses encryption with +authentication. You should request this key from your electricity provider. Used for `General-GLO-Ciphering` and +`General-DED-Ciphering` APDUs. +- **skip_crc** (*Optional*, boolean): Skip CRC check. Some smart meters use the wrong polynomial to calculate CRC. +In such cases, you can use this flag as a workaround. Defaults to `false`. +- **custom_patterns** (*Optional*, list): While the `dlms_meter` natively supports most devices, some meters use +unique payload structures. If your meter's data isn't being read correctly, use this field to define a **custom AXDR +descriptor pattern** that tells the system how to parse the incoming data. + +## Platforms + +### Sensor, text sensor, and binary sensor + +All platforms (`sensor`, `text_sensor`, `binary_sensor`) support dynamic mapping using the `obis_code` property. +This allows you to decode nearly any property your meter emits. + +- **dlms_meter_id** (*Optional*, [ID](/guides/configuration-types#config-id)): Manually specify the ID of the +`dlms_meter` hub if you have multiple. +- **obis_code** (**Required**, string): The OBIS code of the value you want to read. The code supports flexible formats +like `1-0:32.7.0` or `1.0.32.7.0.255`. + +### Legacy keys + +For backwards compatibility, the legacy predefined keys from earlier versions are still fully supported and mapped +automatically to their respective OBIS codes. Add only the ones you need. All support standard options from their +respective platform domains. + +```yaml +sensor: - platform: dlms_meter dlms_meter_id: dlms_meter_hub - obis_code: "0-0:96.1.0" - name: "Meter Number" + voltage_l1: + name: "Voltage Phase 1" + voltage_l2: + name: "Voltage Phase 2" -binary_sensor: +text_sensor: - platform: dlms_meter dlms_meter_id: dlms_meter_hub - obis_code: "0-1:2.3.4" - name: "Custom Binary Sensor" + meternumber: + name: "Meter Number" ``` -### Advanced Configuration Example +**Sensors:** +- **voltage_l1** (`1-0:32.7.0`): Voltage Phase 1. +- **voltage_l2** (`1-0:52.7.0`): Voltage Phase 2. +- **voltage_l3** (`1-0:72.7.0`): Voltage Phase 3. +- **current_l1** (`1-0:31.7.0`): Current Phase 1. +- **current_l2** (`1-0:51.7.0`): Current Phase 2. +- **current_l3** (`1-0:71.7.0`): Current Phase 3. +- **active_power_plus** (`1-0:1.7.0`): Active power taken from grid. +- **active_power_minus** (`1-0:2.7.0`): Active power put into grid. +- **active_energy_plus** (`1-0:1.8.0`): Cumulative active energy taken from grid. +- **active_energy_minus** (`1-0:2.8.0`): Cumulative active energy exported to grid. +- **reactive_energy_plus** (`1-0:3.8.0`): Reactive energy taken from grid. +- **reactive_energy_minus** (`1-0:4.8.0`): Reactive energy exported to grid. +- **power_factor** (`1-0:13.7.0`): Power factor. + +**Text Sensors:** +- **timestamp** (`0-0:1.0.0`): Timestamp included in the received frame. +- **meternumber** (`0-0:96.1.0`): Meter number reported by the device. + +## Advanced configuration + +### Advanced configuration example This example demonstrates how to use the optional configuration variables for encrypted meters or those requiring custom parsing patterns. @@ -70,25 +128,10 @@ dlms_meter: default_obis: "1-0:96.1.0" ``` -## Configuration variables +### Custom patterns -- **id** (*Optional*, [ID](/guides/configuration-types#config-id)): The ID of the `dlms_meter` component. -- **uart_id** (*Optional*, [ID](/guides/configuration-types#config-id)): The ID of the UART component that is -connected to the smart meter. -- **decryption_key** (*Optional*, string): Specify if your smart meter uses encryption. You should request this key -from your electricity provider (32 hex characters, case-insensitive). -- **auth_key** (*Optional*, string): Authentication key. Specify if your smart meter uses encryption with -authentication. You should request this key from your electricity provider. Used for `General-GLO-Ciphering` and -`General-DED-Ciphering` APDUs. -- **skip_crc** (*Optional*, boolean): Skip CRC check. Some smart meters use the wrong polynomial to calculate CRC. -In such cases, you can use this flag as a workaround. Defaults to `false`. -- **custom_patterns** (*Optional*, list): While the `dlms_meter` natively supports most devices, some meters use unique -payload structures. If your meter's data isn't being read correctly, use this field to define a **custom AXDR -descriptor pattern** that tells the system how to parse the incoming data. - -### Custom Patterns - -You can define a custom pattern simply by passing its pattern string, or by defining an object with additional properties: +You can define a custom pattern simply by passing its pattern string, or by defining an object with additional +properties: - **pattern** (**Required**, string): The DSL-based pattern string (e.g., `"TO, TV"`). - **name** (*Optional*, string): A name for the pattern. @@ -96,7 +139,7 @@ You can define a custom pattern simply by passing its pattern string, or by defi - **default_obis** (*Optional*, string): The fallback OBIS code to use if the pattern captures no OBIS code. Requires **name** to be set. Formatted like `1-0:96.1.0` or `1.0.96.1.0.255`. -#### Built-in Patterns +#### Built-in patterns The `dlms_meter` component loads several built-in patterns by default. Your custom patterns will be evaluated alongside these based on their configured `priority`. @@ -108,7 +151,7 @@ these based on their configured `priority`. | `T3` | 30 | value first, class ID, scaler-unit, OBIS | | `U.ZPA` | 40 | untagged ZPA/Aidon-style layouts | -#### Common Custom Pattern Examples +#### Common custom pattern examples Here are some common structures you might encounter on less standard meters: @@ -130,7 +173,7 @@ dlms_meter: name: "Landis+Gyr swapped OBIS" ``` -### Token Reference for Patterns +### Token reference for patterns | Token | Meaning | Hex example | |----------------|--------------------------------------------|---------------------------------| @@ -154,62 +197,7 @@ dlms_meter: | `UP` | return from nested structure | control token | --- -## Platforms - -### Sensor / Text Sensor / Binary Sensor - -All platforms (`sensor`, `text_sensor`, `binary_sensor`) support dynamic mapping using the `obis_code` property. -This allows you to decode nearly any property your meter emits. - -- **dlms_meter_id** (*Optional*, [ID](/guides/configuration-types#config-id)): Manually specify the ID of the -`dlms_meter` hub if you have multiple. -- **obis_code** (**Required**, string): The OBIS code of the value you want to read. The code supports flexible formats -like `1-0:32.7.0` or `1.0.32.7.0.255`. - -### Legacy Keys - -For backwards compatibility, the legacy predefined keys from earlier versions are still fully supported and mapped -automatically to their respective OBIS codes. Add only the ones you need. All support standard options from their -respective platform domains. - -```yaml -sensor: - - platform: dlms_meter - dlms_meter_id: dlms_meter_hub - voltage_l1: - name: "Voltage Phase 1" - voltage_l2: - name: "Voltage Phase 2" - -text_sensor: - - platform: dlms_meter - dlms_meter_id: dlms_meter_hub - meternumber: - name: "Meter Number" -``` - -**Sensors:** - -- **voltage_l1** (`1-0:32.7.0`): Voltage Phase 1. -- **voltage_l2** (`1-0:52.7.0`): Voltage Phase 2. -- **voltage_l3** (`1-0:72.7.0`): Voltage Phase 3. -- **current_l1** (`1-0:31.7.0`): Current Phase 1. -- **current_l2** (`1-0:51.7.0`): Current Phase 2. -- **current_l3** (`1-0:71.7.0`): Current Phase 3. -- **active_power_plus** (`1-0:1.7.0`): Active power taken from grid. -- **active_power_minus** (`1-0:2.7.0`): Active power put into grid. -- **active_energy_plus** (`1-0:1.8.0`): Cumulative active energy taken from grid. -- **active_energy_minus** (`1-0:2.8.0`): Cumulative active energy exported to grid. -- **reactive_energy_plus** (`1-0:3.8.0`): Reactive energy taken from grid. -- **reactive_energy_minus** (`1-0:4.8.0`): Reactive energy exported to grid. -- **power_factor** (`1-0:13.7.0`): Power factor. - -**Text Sensors:** - -- **timestamp** (`0-0:1.0.0`): Timestamp included in the received frame. -- **meternumber** (`0-0:96.1.0`): Meter number reported by the device. - -## See Also +## See also - - From c204aecdef476d6e10381a96ae8c099bfdef0530 Mon Sep 17 00:00:00 2001 From: Tomer27cz <85194189+Tomer27cz@users.noreply.github.com> Date: Tue, 7 Apr 2026 23:19:52 +0200 Subject: [PATCH 07/11] add method to find obis codes --- .../docs/components/sensor/dlms_meter.mdx | 46 ++++++++++++++++++- 1 file changed, 44 insertions(+), 2 deletions(-) diff --git a/src/content/docs/components/sensor/dlms_meter.mdx b/src/content/docs/components/sensor/dlms_meter.mdx index 544f8881e8..94f4a40d43 100644 --- a/src/content/docs/components/sensor/dlms_meter.mdx +++ b/src/content/docs/components/sensor/dlms_meter.mdx @@ -24,7 +24,8 @@ The component does not transmit data to the meter. The meter periodically broadc This component requires a [UART bus](/components/uart/) to be configured. > [!TIP] -> The UART configuration depends on your specific meter hardware. Be sure to consult your meter's specifications. +> The UART configuration depends on your specific meter hardware. +> Be sure to consult your provider or meter's specifications. ```yaml dlms_meter: @@ -66,6 +67,40 @@ This allows you to decode nearly any property your meter emits. - **obis_code** (**Required**, string): The OBIS code of the value you want to read. The code supports flexible formats like `1-0:32.7.0` or `1.0.32.7.0.255`. +### Finding your meter's OBIS codes + +Before using this method, it is highly recommended to check your meter's manual or your energy provider's documentation +for a list of supported OBIS codes. + +If you are configuring your meter for the first time and do not know which OBIS codes it broadcasts, you can temporarily +increase the logging level to `VERBOSE`. The component will print all successfully parsed OBIS codes and their values to +the ESPHome log. + +```yaml +logger: + level: VERBOSE + initial_level: DEBUG + logs: + dlms_meter: VERBOSE +``` + +In this configuration, the global `level` is set to `VERBOSE` because ESPHome will otherwise exclude lower-severity log +messages at compile time (any log message with a lower severity will not be shown). + +To prevent your console from being flooded with verbose messages from every component, +`initial_level` restores the standard default of `DEBUG` dynamically at run time, +while the `logs` mapping manually sets the specific `dlms_meter` tag to remain at `VERBOSE`. + +> [!WARNING] +> Increasing the log level severity can impact the performance of your ESP application and increase memory size. +> Always **revert to default log levels** for daily use. + +> [!TIP] +> If you are building custom patterns or need to capture the raw hex payload for troubleshooting, change the `dlms_meter` +> log level to `VERY_VERBOSE`. This will output the full raw buffer and the decrypted AXDR payload. + +For more details, refer to the [Logger Component](/components/logger/). + ### Legacy keys For backwards compatibility, the legacy predefined keys from earlier versions are still fully supported and mapped @@ -89,6 +124,7 @@ text_sensor: ``` **Sensors:** + - **voltage_l1** (`1-0:32.7.0`): Voltage Phase 1. - **voltage_l2** (`1-0:52.7.0`): Voltage Phase 2. - **voltage_l3** (`1-0:72.7.0`): Voltage Phase 3. @@ -104,6 +140,7 @@ text_sensor: - **power_factor** (`1-0:13.7.0`): Power factor. **Text Sensors:** + - **timestamp** (`0-0:1.0.0`): Timestamp included in the received frame. - **meternumber** (`0-0:96.1.0`): Meter number reported by the device. @@ -195,7 +232,12 @@ dlms_meter: | `S(x, y, ...)` | inline sub-structure | `02 03` | | `DN` | descend into nested structure | control token | | `UP` | return from nested structure | control token | ---- + +## Specific meter configurations + +*(Additional instructions and specific `custom_patterns` for meters +from manufacturers like Landis+Gyr, Kaifa, Kamstrup, Iskra, etc., +can be added here as users report the specific setups required for their unique smart meter firmware.)* ## See also From 0072b9daa135bbee6466b36f63a6ed22a58fa166 Mon Sep 17 00:00:00 2001 From: Tomer27cz <85194189+Tomer27cz@users.noreply.github.com> Date: Wed, 8 Apr 2026 01:21:10 +0200 Subject: [PATCH 08/11] update --- src/content/docs/components/sensor/dlms_meter.mdx | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/src/content/docs/components/sensor/dlms_meter.mdx b/src/content/docs/components/sensor/dlms_meter.mdx index 94f4a40d43..2186830666 100644 --- a/src/content/docs/components/sensor/dlms_meter.mdx +++ b/src/content/docs/components/sensor/dlms_meter.mdx @@ -181,12 +181,12 @@ properties: The `dlms_meter` component loads several built-in patterns by default. Your custom patterns will be evaluated alongside these based on their configured `priority`. -| Name | Priority | Typical use | -|---------|---------:|-------------------------------------------| -| `T1` | 10 | class ID, tagged OBIS, scaler, value | -| `T2` | 20 | tagged OBIS, value, scaler-unit structure | -| `T3` | 30 | value first, class ID, scaler-unit, OBIS | -| `U.ZPA` | 40 | untagged ZPA/Aidon-style layouts | +| Name | Priority | Typical use | +|-------|---------:|-------------------------------------------| +| `T1` | 10 | class ID, tagged OBIS, scaler, value | +| `T2` | 20 | tagged OBIS, value, scaler-unit structure | +| `T3` | 30 | value first, class ID, scaler-unit, OBIS | +| `ADV` | 40 | untagged ZPA/Aidon-style layouts | #### Common custom pattern examples From 4e662e5f0a71e67292a504e57d9fbcb899f8fe04 Mon Sep 17 00:00:00 2001 From: Tomer27cz <85194189+Tomer27cz@users.noreply.github.com> Date: Wed, 8 Apr 2026 01:56:30 +0200 Subject: [PATCH 09/11] add unit config example --- .../docs/components/sensor/dlms_meter.mdx | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/src/content/docs/components/sensor/dlms_meter.mdx b/src/content/docs/components/sensor/dlms_meter.mdx index 2186830666..aa6c24e1fb 100644 --- a/src/content/docs/components/sensor/dlms_meter.mdx +++ b/src/content/docs/components/sensor/dlms_meter.mdx @@ -67,6 +67,24 @@ This allows you to decode nearly any property your meter emits. - **obis_code** (**Required**, string): The OBIS code of the value you want to read. The code supports flexible formats like `1-0:32.7.0` or `1.0.32.7.0.255`. +When defining your sensors, it is recommended to include standard ESPHome sensor properties such as +`unit_of_measurement`, `accuracy_decimals`, `device_class`, and `state_class`. +The exact configuration will vary depending on the specific value you are reading (e.g., energy vs. power vs. voltage). + +Here is an example of how to configure an energy sensor so it displays correctly with Home Assistant's Energy Dashboard: + +```yaml +sensor: + - platform: dlms_meter + dlms_meter_id: dlms_meter_hub + obis_code: "1.0.1.8.0.255" + name: "Energy Consumed" + unit_of_measurement: "kWh" + accuracy_decimals: 3 + device_class: energy + state_class: total_increasing +``` + ### Finding your meter's OBIS codes Before using this method, it is highly recommended to check your meter's manual or your energy provider's documentation From 20d87cc4e87bfb2dfea23cafcda278bb225c007e Mon Sep 17 00:00:00 2001 From: Tomer27cz <85194189+Tomer27cz@users.noreply.github.com> Date: Wed, 8 Apr 2026 11:31:01 +0200 Subject: [PATCH 10/11] add supported meters and custom configs --- .../docs/components/sensor/dlms_meter.mdx | 108 +++++++++++++++++- 1 file changed, 104 insertions(+), 4 deletions(-) diff --git a/src/content/docs/components/sensor/dlms_meter.mdx b/src/content/docs/components/sensor/dlms_meter.mdx index aa6c24e1fb..8dd7329fa0 100644 --- a/src/content/docs/components/sensor/dlms_meter.mdx +++ b/src/content/docs/components/sensor/dlms_meter.mdx @@ -251,11 +251,111 @@ dlms_meter: | `DN` | descend into nested structure | control token | | `UP` | return from nested structure | control token | -## Specific meter configurations +--- + +## Supported Meters + +> [!IMPORTANT] +> Always check if your meter reading already works natively with the default settings +> before adding any `custom_patterns`. The component's built-in parser handles many standard meters automatically. + +### Natively Supported (No Custom Configuration Required) +**The vast majority of standard-compliant smart meters are supported right out of the box.** +If your meter follows the official DLMS specifications, +you generally only need to provide the UART pins and your desired OBIS codes. + +We have explicitly tested and confirmed native support for standard meters including (but not limited to): + +**Sagemcom XT211**, **Energomera**, and **Kaifa MA304H3E**. + +### Specific meter configurations +Some manufacturers implement the DLMS standard using non-standard object structuring or framing. +Below are the tested configuration parameters required for these specific meters: + +**Salzburg Netz** +```yaml +dlms_meter: + # ... + custom_patterns: + - pattern: "TO, TDTM" + - pattern: "S(TO, TV)" +``` + +**Iskra 550** +```yaml +dlms_meter: + # ... + custom_patterns: + - pattern: "S(TO, TV)" +``` + +**Norway HAN (Aidon 1-phase and 3-phase)** +```yaml +dlms_meter: + # ... + custom_patterns: + - pattern: "F, S(TO, TDTM)" + name: "DateTime" + - pattern: "S(TO, TV, TSU)" + name: "Obis-Value-Scaler-Unit" + - pattern: "S(TO, TV)" +``` + +**Landis+Gyr ZMF100** +*: This specific meter sends invalid Frame Check Sequences (FCS) and requires skipping the CRC check.* +```yaml +dlms_meter: + # ... + skip_crc: true + custom_patterns: + - pattern: "S(TO, TDTM)" + - pattern: "S(TO, TV)" + - pattern: "TOW, TV, TSU" +``` + +**Landis+Gyr E450** +*: This meter uses encryption and requires a decryption key from your provider.* +```yaml +dlms_meter: + # ... + decryption_key: "YOUR_32_CHAR_HEX_KEY" + custom_patterns: + - pattern: "F, TDTM" + name: "DateTime" + - pattern: "TO, TV" + name: "Obis-Value Pair" +``` + +**Kamstrup Omnipower** +*: This meter uses encryption. Some regional variants also mandate an Authentication Key.* +```yaml +dlms_meter: + # ... + decryption_key: "YOUR_32_CHAR_HEX_KEY" + auth_key: "YOUR_32_CHAR_AUTH_KEY" # Add if required by your provider + custom_patterns: + - pattern: "F, TSTR" + name: "Obis List Ver" + - pattern: "TO, TV" + name: "Code-Value Pair" +``` + +**Netz NOE P1 (M-Bus)** +*: Requires encryption. The MeterID is untagged and requires a fallback default OBIS mapping.* +```yaml +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: "S(TO, TV, TSU)" + name: "Obis-Value-Scaler-Unit" +``` -*(Additional instructions and specific `custom_patterns` for meters -from manufacturers like Landis+Gyr, Kaifa, Kamstrup, Iskra, etc., -can be added here as users report the specific setups required for their unique smart meter firmware.)* +*(Additional instructions and specific `custom_patterns` for meters from manufacturers can be added here +as users report the specific setups required for their unique smart meter firmware.)* ## See also From ef045030802141a157e9f631d59e9ff79656e563 Mon Sep 17 00:00:00 2001 From: Tomer27cz <85194189+Tomer27cz@users.noreply.github.com> Date: Wed, 8 Apr 2026 11:54:07 +0200 Subject: [PATCH 11/11] update default obis format --- .../docs/components/sensor/dlms_meter.mdx | 34 +++++++++---------- 1 file changed, 17 insertions(+), 17 deletions(-) diff --git a/src/content/docs/components/sensor/dlms_meter.mdx b/src/content/docs/components/sensor/dlms_meter.mdx index 8dd7329fa0..5d4765ab89 100644 --- a/src/content/docs/components/sensor/dlms_meter.mdx +++ b/src/content/docs/components/sensor/dlms_meter.mdx @@ -35,7 +35,7 @@ dlms_meter: sensor: - platform: dlms_meter dlms_meter_id: dlms_meter_hub - obis_code: "1-0:1.7.0" + obis_code: "1.0.1.7.0.255" name: "Active power taken from grid" ``` @@ -143,24 +143,24 @@ text_sensor: **Sensors:** -- **voltage_l1** (`1-0:32.7.0`): Voltage Phase 1. -- **voltage_l2** (`1-0:52.7.0`): Voltage Phase 2. -- **voltage_l3** (`1-0:72.7.0`): Voltage Phase 3. -- **current_l1** (`1-0:31.7.0`): Current Phase 1. -- **current_l2** (`1-0:51.7.0`): Current Phase 2. -- **current_l3** (`1-0:71.7.0`): Current Phase 3. -- **active_power_plus** (`1-0:1.7.0`): Active power taken from grid. -- **active_power_minus** (`1-0:2.7.0`): Active power put into grid. -- **active_energy_plus** (`1-0:1.8.0`): Cumulative active energy taken from grid. -- **active_energy_minus** (`1-0:2.8.0`): Cumulative active energy exported to grid. -- **reactive_energy_plus** (`1-0:3.8.0`): Reactive energy taken from grid. -- **reactive_energy_minus** (`1-0:4.8.0`): Reactive energy exported to grid. -- **power_factor** (`1-0:13.7.0`): Power factor. +- **voltage_l1** (`1.0.32.7.0.255`): Voltage Phase 1. +- **voltage_l2** (`1.0.52.7.0.255`): Voltage Phase 2. +- **voltage_l3** (`1.0.72.7.0.255`): Voltage Phase 3. +- **current_l1** (`1.0.31.7.0.255`): Current Phase 1. +- **current_l2** (`1.0.51.7.0.255`): Current Phase 2. +- **current_l3** (`1.0.71.7.0.255`): Current Phase 3. +- **active_power_plus** (`1.0.1.7.0.255`): Active power taken from grid. +- **active_power_minus** (`1.0.2.7.0.255`): Active power put into grid. +- **active_energy_plus** (`1.0.1.8.0.255`): Cumulative active energy taken from grid. +- **active_energy_minus** (`1.0.2.8.0.255`): Cumulative active energy exported to grid. +- **reactive_energy_plus** (`1.0.3.8.0.255`): Reactive energy taken from grid. +- **reactive_energy_minus** (`1.0.4.8.0.255`): Reactive energy exported to grid. +- **power_factor** (`1.0.13.7.0.255`): Power factor. **Text Sensors:** -- **timestamp** (`0-0:1.0.0`): Timestamp included in the received frame. -- **meternumber** (`0-0:96.1.0`): Meter number reported by the device. +- **timestamp** (`0.0.1.0.0.255`): Timestamp included in the received frame. +- **meternumber** (`0.0.96.1.0.255`): Meter number reported by the device. ## Advanced configuration @@ -180,7 +180,7 @@ dlms_meter: - pattern: "TO, TV" name: "flat OBIS + value pairs" priority: 15 - default_obis: "1-0:96.1.0" + default_obis: "1.0.96.1.0.255" ``` ### Custom patterns