A Library for Parsing Dutch Smart Meter Requirements (DSMR)

DSMR 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. Installation Add dsmr to your list of dependencies in mix.exs : def deps do [ { :dsmr , "~> 1.0" } , { :decimal , "~> 2.0" } # Optional: Required only if you want to use floats: :decimals option for arbitrary precision ] end 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 . Supported DSMR Versions This library supports DSMR 4.x and 5.x protocols: DSMR 4.x (version "42", "40") - Older Dutch meters (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. Usage telegram = # String is formatted in separate lines for readability. Enum . join ( [ "/KFM5KAIFA-METER \r " , " \r " , "1-3:0.2.8(42) \r " , "0-0:1.0.0(161113205757W) \r " , "0-0:96.1.1(3960221976967177082151037881335713) \r " , "1-0:1.8.1(001581.123*kWh) \r " , "1-0:1.8.2(001435.706*kWh) \r " , "1-0:2.8.1(000000.000*kWh) \r " , "1-0:2.8.2(000000.000*kWh) \r " , "0-0:96.14.0(0002) \r " , "1-0:1.7.0(02.027*kW) \r " , "1-0:2.7.0(00.000*kW) \r " , "0-0:96.7.21(00015) \r " , "0-0:96.7.9(00007) \r " , "1-0:99.97.0(3)(0-0:96.7.19)(000104180320W)(0000237126*s)(000101000001W)" , "(2147583646*s)(000102000003W)(2317482647*s) \r " , "1-0:32.32.0(00000) \r " , "1-0:52.32.0(00000) \r " , "1-0:72.32.0(00000) \r " , "1-0:32.36.0(00000) \r " , "1-0:52.36.0(00000) \r " , "1-0:72.36.0(00000) \r " , "0-0:96.13.1() \r " , "0-0:96.13.0() \r " , "1-0:31.7.0(000*A) \r " , "1-0:51.7.0(006*A) \r " , "1-0:71.7.0(002*A) \r " , "1-0:21.7.0(00.170*kW) \r " , "1-0:22.7.0(00.000*kW) \r " , "1-0:41.7.0(01.247*kW) \r " , "1-0:42.7.0(00.000*kW) \r " , "1-0:61.7.0(00.209*kW) \r " , "1-0:62.7.0(00.000*kW) \r " , "0-1:24.1.0(003) \r " , "0-1:96.1.0(4819243993373755377509728609491464) \r " , "0-1:24.2.1(161129200000W)(00981.443*m3) \r " , "!6796 \r " ] ) DSMR . parse ( telegram ) #=> {:ok, %DSMR.Telegram{header: "KFM5KAIFA-METER", version: "42", electricity_delivered_1: %Measurement{unit: "kWh",value: Decimal.new("1581.123")}, ...]} Parser Options DSMR.parse/2 accepts an optional keyword list of options: Option Values Default Description :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: # Skip checksum validation DSMR . parse ( telegram , checksum: false ) # Use Decimal for precise calculations DSMR . parse ( telegram , floats: :decimals ) # Combine options DSMR . parse ( telegram , checksum: false , floats: :decimals ) Available Telegram Fields The parsed %DSMR.Telegram{} struct contains the following fields: Header & Metadata header - Meter manufacturer and model - Meter manufacturer and model checksum - CRC16 checksum - CRC16 checksum version - DSMR protocol version ("42", "50", etc.) - DSMR protocol version ("42", "50", etc.) measured_at - Timestamp of measurement - Timestamp of measurement equipment_id - Unique meter identifier Electricity Measurements electricity_delivered_1 / electricity_delivered_2 - Cumulative consumption (tariff 1/2) / - Cumulative consumption (tariff 1/2) electricity_returned_1 / electricity_returned_2 - Cumulative return to grid (tariff 1/2) / - Cumulative return to grid (tariff 1/2) electricity_tariff_indicator - Current active tariff - 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 - Power delivered per phase currently_returned_l1/l2/l3 - Power returned per phase - Power returned per phase voltage_l1/l2/l3 - Voltage per phase - Voltage per phase phase_power_current_l1/l2/l3 - Current per phase Power Quality power_failures_count / power_failures_long_count - Failure counters / - Failure counters power_failures_log - Timestamped log of power failures - 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. Serialization You can convert a Telegram struct back to its string representation: telegram = % DSMR.Telegram { header: "KFM5KAIFA-METER" , checksum: "6796" , version: "42" , measured_at: % DSMR.Timestamp { value: ~N [ 2016-11-13 20:57:57 ] , dst: "W" } , electricity_delivered_1: % DSMR.Measurement { value: Decimal . new ( "1581.123" ) , unit: "kWh" } } DSMR.Telegram . to_string ( telegram ) #=> "/KFM5KAIFA-METER\r \r 1-3:0.2.8(42)\r 0-0:1.0.0(161113205757W)\r 1-0:1.8.1(001581.123*kWh)\r !6796\r " Error Handling The parser returns {:error, reason} tuples for invalid data: DSMR . parse ( "invalid data" ) #=> {:error, {1, :dsmr_parser, ['syntax error before: ', []]}} DSMR . parse ( "/HEADER \r !FFFF \r " ) # Bad checksum #=> {:error, :invalid_checksum} Common errors: :invalid_checksum - CRC16 validation failed - CRC16 validation failed {line, :dsmr_parser, message} - Syntax error at specific line - Syntax error at specific line {line, :dsmr_lexer, message} - Tokenization error Troubleshooting: Ensure telegrams are complete (start with / , end with ! + checksum) , end with + checksum) Check for proper line endings ( \r ) ) Verify the telegram hasn't been corrupted during transmission Some meters send partial telegrams on connection - wait for the next complete one Getting Real Telegram Data Smart meters typically expose data via: Serial port (P1 port, usually RJ12 or RJ11 connector, 115200 baud) (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. Internals This library uses a two-stage parsing architecture built on Erlang's leex (lexical analyzer) and yecc (parser generator): Stage 1: Lexical Analysis (leex) 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}} : Pattern → Timestamps : Pattern 161113205757W → {timestamp, Line, {[16,11,13,20,57,57], "W"}} : Pattern → Measurements : Float/int values like 001581.123 → {float, Line, "001581.123"} : Float/int values like → 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. Stage 2: Parsing (yecc) The parser ( src/dsmr_parser.yrl ) uses grammar rules to transform tokens into the DSMR.Telegram struct: object -> obis attributes : map_obis_to_field ( '$1' , '$2' ). attribute -> '(' value ')' : '$2' . value -> float '*' string : extract_measurement ( '$1' , '$3' ). 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 : Fields with wildcards (e.g., ) are grouped by channel Power failures log : Nested structure with variable-length event lists : 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.). Changelog Please see CHANGELOG for more information on what has changed recently. Contributing 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 License 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.