.png)
1 month ago
1
A library for parsing Dutch Smart Meter Requirements (DSMR) telegram data.
DSMR is the standardized protocol used by smart energy meters in the Netherlands, Belgium, and Luxembourg. These smart meters are installed in homes and businesses to measure electricity and gas consumption in real-time.
Smart meters continuously broadcast "telegrams" - structured data packets containing:
- Current and cumulative electricity usage (delivered and returned to grid)
- Gas consumption readings
- Voltage and current measurements per phase
- Power failure logs and quality statistics
- Additional M-Bus connected devices (water, thermal, etc.)
This library parses these telegrams into Elixir structs, making it easy to build energy monitoring applications, home automation systems, or analytics dashboards.
Add dsmr to your list of dependencies in mix.exs:
By default, measurement values are returned as native floats. To use high-precision %Decimal{} structs instead, add the Decimal dependency and pass the floats: :decimals option to DSMR.parse/2.
This library supports DSMR 4.x and 5.x protocols:
- DSMR 4.x (version "42", "40") - Older Dutch meters
- DSMR 5.x (version "50") - Current standard in Netherlands, Belgium, Luxembourg
The parser automatically handles version differences. The version field in the telegram indicates which protocol version the meter uses.
DSMR.parse/2 accepts an optional keyword list of options:
| :checksum | true / false | true | When false, skips CRC16 checksum validation. Useful for testing or when processing telegrams from trusted sources. |
| :floats | :native / :decimals | :native | Controls numeric precision: • :native - Uses Erlang's native float conversion (faster, may have rounding) • :decimals - Returns Decimal structs for arbitrary precision (requires the decimal package) |
Examples:
The parsed %DSMR.Telegram{} struct contains the following fields:
Header & Metadata
- header - Meter manufacturer and model
- checksum - CRC16 checksum
- version - DSMR protocol version ("42", "50", etc.)
- measured_at - Timestamp of measurement
- equipment_id - Unique meter identifier
Electricity Measurements
- electricity_delivered_1 / electricity_delivered_2 - Cumulative consumption (tariff 1/2)
- electricity_returned_1 / electricity_returned_2 - Cumulative return to grid (tariff 1/2)
- electricity_tariff_indicator - Current active tariff
- electricity_currently_delivered / electricity_currently_returned - Instantaneous power
Per-Phase Measurements (3-phase connections)
- currently_delivered_l1/l2/l3 - Power delivered per phase
- currently_returned_l1/l2/l3 - Power returned per phase
- voltage_l1/l2/l3 - Voltage per phase
- phase_power_current_l1/l2/l3 - Current per phase
Power Quality
- power_failures_count / power_failures_long_count - Failure counters
- power_failures_log - Timestamped log of power failures
- voltage_sags_l1/l2/l3_count / voltage_swells_l1/l2/l3_count - Quality events
M-Bus Devices (gas, water, thermal meters)
- mbus_devices - List of %DSMR.MBusDevice{} structs with gas/water/heat readings
When the parser encounters OBIS codes that aren't in its mapping table, they're collected in unknown_fields as {obis_tuple, value} pairs instead of causing a crash. This allows the library to handle:
- Proprietary meter-specific codes
- Newer OBIS codes not yet supported
- Regional variations in smart meter implementations
See full documentation for detailed field descriptions and types.
You can convert a Telegram struct back to its string representation:
The parser returns {:error, reason} tuples for invalid data:
Common errors:
- :invalid_checksum - CRC16 validation failed
- {line, :dsmr_parser, message} - Syntax error at specific line
- {line, :dsmr_lexer, message} - Tokenization error
Troubleshooting:
- Ensure telegrams are complete (start with /, end with ! + checksum)
- Check for proper line endings (\r\n)
- Verify the telegram hasn't been corrupted during transmission
- Some meters send partial telegrams on connection - wait for the next complete one
Smart meters typically expose data via:
- Serial port (P1 port, usually RJ12 or RJ11 connector, 115200 baud)
- Network (some meters or P1-to-WiFi adapters expose TCP sockets)
This library only handles parsing - you'll need to handle data acquisition separately.
Example: Reading from a networked meter
See the included Livebook example for a complete GenServer implementation that:
- Connects to a meter via TCP (common with WiFi P1 adapters)
- Buffers incoming lines and assembles complete telegrams
- Parses telegrams and visualizes real-time usage
For serial port connections, use libraries like Circuits.UART.
This library uses a two-stage parsing architecture built on Erlang's leex (lexical analyzer) and yecc (parser generator):
The lexer (src/dsmr_lexer.xrl) tokenizes raw DSMR telegram data into structured tokens:
- OBIS codes: Pattern 1-0:1.8.1 → {obis, Line, {[1,0,1,8,1], Channel}}
- Timestamps: Pattern 161113205757W → {timestamp, Line, {[16,11,13,20,57,57], "W"}}
- Measurements: Float/int values like 001581.123 → {float, Line, "001581.123"}
- Headers/Footers: /KFM5KAIFA-METER and !6796 → {header, ...} / {checksum, ...}
The lexer also extracts the MBus channel number from OBIS codes (second position) for single-pass processing of multi-device telegrams.
The parser (src/dsmr_parser.yrl) uses grammar rules to transform tokens into the DSMR.Telegram struct:
OBIS code mapping is centralized in the DSMR.OBIS Elixir module (lib/dsmr/obis.ex), which serves as the single source of truth for all field mappings. The parser calls this module at runtime to map OBIS codes like [1,0,1,8,1] to field names like :electricity_delivered_1.
Special cases are handled directly in the parser:
- MBus devices: Fields with wildcards (e.g., 0-*:24.1.0) are grouped by channel
- Power failures log: Nested structure with variable-length event lists
- Unknown OBIS codes: Unrecognized codes are tagged and collected in unknown_fields rather than causing parse failures
The final DSMR.Parser module coordinates both stages and constructs the final struct with proper type conversions (Decimal, NaiveDateTime, etc.).
Please see CHANGELOG for more information on what has changed recently.
Everyone is encouraged to help improve this project. Here are a few ways you can help:
- Report bugs
- Fix bugs and submit pull requests
- Write, clarify, or fix documentation
- Suggest or add new features
Copyright (C) 2020 Robin van der Vleuten
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
