Hello everyone,
I’m excited to share dsmr-custom, an enhanced ESPHome component for reading P1 port data from smart meters. It was born out of the need to reliably support Finnish meters (SESKO standard), but it has been built with flexibility in mind to support a wide range of DSMR-compatible meters, including experimental support for encrypted telegrams.
The key to this component is a diagnostics-first workflow. This guide will first show you the most stable way to discover every OBIS code your specific meter provides, and then how to build a powerful, custom configuration based on that data.
Getting Started: The 3-Step Guide
Follow these steps to get up and running reliably. This process is designed to prevent common issues like device crashes on platforms with limited memory like the ESP8266.
Step 1: Add the Component to ESPHome
You don’t need to copy any files. Simply add the following external_components block to your device’s YAML configuration. ESPHome will automatically download the component from GitHub.
external_components:
- source:
type: git
url: https://github.com/nikopaulanne/dsmr-custom
ref: v1.0.2 # Or the latest version tag
components: [ dsmr_custom ]
Step 2: Discover Your Meter’s OBIS Codes
Next, we’ll use a minimal configuration to safely listen to your meter and print its raw data to the ESPHome logs. This is the most important step.
-
Use the Diagnostic Configuration Below: Flash your device with this code. Its only job is to listen for one full data packet (a “telegram”) and print it to the logs.
# In your secrets.yaml, define your WiFi credentials, etc. # wifi_ssid: "YourNetwork" # ... esphome: name: dsmr-diagnostics esp8266: board: d1_mini # Add your wifi, api, ota... logger: level: INFO # Necessary to see the log output uart: id: uart_bus baud_rate: 115200 rx_pin: D7 # IMPORTANT: Change to your device's RX pin rx_buffer_size: 1700 external_components: - source: type: git url: https://github.com/nikopaulanne/dsmr-custom ref: v1.0.2 components: [ dsmr_custom ] dsmr_custom: id: dsmr_hub uart_id: uart_bus text_sensor: - platform: dsmr_custom dsmr_custom_hub_id: dsmr_hub # This confirms a connection, but the magic happens below. identification: name: "P1 Telegram Header" # This captures the full telegram internally and uses a lightweight # trigger to print it to the logs without crashing the device. telegram: internal: true on_value: - logger.log: level: INFO tag: "telegram_dump" format: "--- FULL TELEGRAM RECEIVED ---\n%s\n-----------------------------" args: [x.c_str()] -
View the Logs: In Home Assistant, go to Settings > Add-ons > ESPHome, select your device, and click LOGS.
-
Copy the Data: Wait for a telegram to arrive. You will see a block of text in the logs starting with
--- FULL TELEGRAM RECEIVED ---. Copy this entire block. You now have a complete list of every data point your meter provides!
Step 3: Build Your Final Configuration
Now, create your final YAML. Remove the diagnostic on_value trigger and use the OBIS codes you copied from the log to define your own sensors.
dsmr_custom:
id: dsmr_hub
uart_id: uart_bus
# ... other hub settings ...
custom_obis_sensors:
# Use the codes you discovered in Step 2!
- code: "1-0:1.8.0"
name: "Total Energy Import"
type: sensor
unit_of_measurement: "kWh"
device_class: energy
state_class: total_increasing
- code: "1-0:31.7.0"
name: "Phase Current L1"
type: sensor
unit_of_measurement: "A"
device_class: current
state_class: measurement
accuracy_decimals: 2
Component Features & Technical Details
-
User-Defined OBIS Sensors: The core feature. You can map any OBIS code from your meter to a sensor in Home Assistant, with full control over its name, unit, icon, and other properties.
-
Broad Protocol Support: The component’s parser is modified for lenient header validation, ensuring it works with standard DSMR, Dutch smart meters, and non-standard Finnish (SESKO) meters.
-
Encrypted Telegram Support (Experimental): The component includes the necessary architecture for decrypting AES-128-GCM encrypted P1 streams, such as those used in Luxembourg. To enable it, provide the 32-character decryption key.
dsmr_custom: decryption_key: "00112233445566778899AABBCCDDEEFF"Note: This feature is considered experimental and has not been tested on a live encrypted meter. Community feedback and testing are highly encouraged.
-
Buffer and Request Management:
- Large Buffer: The
rx_buffer_sizeis configurable to handle large telegrams from modern meters. - Request Pin: For meters that require a data request signal, you can define a
request_pinto actively poll for data.
- Large Buffer: The
Call for Community Testing
While this component has been validated on Finnish hardware, community assistance is needed to confirm its functionality in other environments. Help is especially welcome for:
- Encryption Functionality: Testing with meters from Luxembourg or other regions that use AES-128-GCM encryption.
- M-Bus Devices: Verifying OBIS codes and parsing for gas, water, or heat meters.
- Meter Variability: Testing with a wider range of smart meters from different manufacturers.
Please share your findings, OBIS mappings, or sanitized telegram samples via GitHub Issues.
Acknowledgments
This project would not be possible without the foundational work on DSMR parsing and integration from the ESPHome community, including contributions and inspiration from @glmnet, @matthijskooijman, @imars, and @zuidwijk.
A special thank you to the community members in the original HA thread for their testing and feedback.
GitHub Repository: nikopaulanne/dsmr-custom
Discussion: All feedback is welcome – I’m particularly interested in hearing from users with encrypted P1 streams or non-Finnish meters!