MBusinoLibPy 0.10.0__py3-none-any.whl

MBusinoLibPy/vif_defs.py

@@ -0,0 +1,174 @@
+# -*- coding: utf-8 -*-
+"""vif_defs table - 1:1 port from MBusinoLib.h line 179-345.
+
+Struktur pro Eintrag wie im C++ (`typedef struct { uint8_t code; uint32_t base;
+uint8_t size; int8_t scalar; } vif_def_type`):
+
+    (code,   base, size, scalar)
+     |       |     |     |
+     |       |     |     +-- scaling exponent: value = raw * 10^scalar
+     |       |     +-------- number of consecutive valid values
+     |       +-------------- first byte/extension byte this definition belongs to
+     +---------------------- MBUS_CODE enum value delivered for this VIF combination
+
+The lookup `_findDefinition(vif)` checks `base <= vif < base + size` and returns the
+FIRST match - therefore the order here matters just as much as in C++.
+"""
+
+from .enums import MBUS_CODE
+
+# Number of entries, in C++: #define MBUS_VIF_DEF_NUM 132 (MBusinoLib.h line 177)
+MBUS_VIF_DEF_NUM = 132
+
+# Order and values taken over unchanged from MBusinoLib.h.
+VIF_DEFS = (
+    # C++-Kommentar: "0x7E is not used in direction Slave --> Master and
+    # therefore misused as library failure hint." -> UNKNOWN_VIF
+    (MBUS_CODE.UNKNOWN_VIF               , 0x7E    ,   1,    0),  # Fehlerhinweis-Eintrag
+
+    # --- without VIFE (direct codes) ---
+    (MBUS_CODE.ENERGY_WH                 , 0x0     ,   8,   -3),
+    (MBUS_CODE.ENERGY_J                  , 0x8     ,   8,    0),
+    (MBUS_CODE.VOLUME_M3                 , 0x10    ,   8,   -6),
+    (MBUS_CODE.MASS_KG                   , 0x18    ,   8,   -3),
+    (MBUS_CODE.ON_TIME_S                 , 0x20    ,   1,    0),
+    (MBUS_CODE.ON_TIME_MIN               , 0x21    ,   1,    0),
+    (MBUS_CODE.ON_TIME_H                 , 0x22    ,   1,    0),
+    (MBUS_CODE.ON_TIME_DAYS              , 0x23    ,   1,    0),
+    (MBUS_CODE.OPERATING_TIME_S          , 0x24    ,   1,    0),
+    (MBUS_CODE.OPERATING_TIME_MIN        , 0x25    ,   1,    0),
+    (MBUS_CODE.OPERATING_TIME_H          , 0x26    ,   1,    0),
+    (MBUS_CODE.OPERATING_TIME_DAYS       , 0x27    ,   1,    0),
+    (MBUS_CODE.POWER_W                   , 0x28    ,   8,   -3),
+    (MBUS_CODE.POWER_J_H                 , 0x30    ,   8,    0),
+    (MBUS_CODE.VOLUME_FLOW_M3_H          , 0x38    ,   8,   -6),
+    (MBUS_CODE.VOLUME_FLOW_M3_MIN        , 0x40    ,   8,   -7),
+    (MBUS_CODE.VOLUME_FLOW_M3_S          , 0x48    ,   8,   -9),
+    (MBUS_CODE.MASS_FLOW_KG_H            , 0x50    ,   8,   -3),
+    (MBUS_CODE.FLOW_TEMPERATURE_C        , 0x58    ,   4,   -3),
+    (MBUS_CODE.RETURN_TEMPERATURE_C      , 0x5C    ,   4,   -3),
+    (MBUS_CODE.TEMPERATURE_DIFF_K        , 0x60    ,   4,   -3),
+    (MBUS_CODE.EXTERNAL_TEMPERATURE_C    , 0x64    ,   4,   -3),
+    (MBUS_CODE.PRESSURE_BAR              , 0x68    ,   4,   -3),
+    (MBUS_CODE.TIME_POINT_DATE           , 0x6C    ,   1,    0),
+    (MBUS_CODE.TIME_POINT_DATETIME       , 0x6D    ,   1,    0),
+    (MBUS_CODE.AVG_DURATION_S            , 0x70    ,   1,    0),
+    (MBUS_CODE.AVG_DURATION_MIN          , 0x71    ,   1,    0),
+    (MBUS_CODE.AVG_DURATION_H            , 0x72    ,   1,    0),
+    (MBUS_CODE.AVG_DURATION_DAYS         , 0x73    ,   1,    0),
+    (MBUS_CODE.ACTUAL_DURATION_S         , 0x74    ,   1,    0),
+    (MBUS_CODE.ACTUAL_DURATION_MIN       , 0x75    ,   1,    0),
+    (MBUS_CODE.ACTUAL_DURATION_H         , 0x76    ,   1,    0),
+    (MBUS_CODE.ACTUAL_DURATION_DAYS      , 0x77    ,   1,    0),
+    (MBUS_CODE.FABRICATION_NUMBER        , 0x78    ,   1,    0),
+    (MBUS_CODE.BUS_ADDRESS               , 0x7A    ,   1,    0),
+    (MBUS_CODE.VOLUME_M3                 , 0x933A  ,   1,   -3),
+    (MBUS_CODE.VOLUME_M3                 , 0x943A  ,   1,   -2),
+
+    # --- VIFE 0xFD ---
+    (MBUS_CODE.CREDIT                    , 0xFD00  ,   4,   -3),
+    (MBUS_CODE.DEBIT                     , 0xFD04  ,   4,   -3),
+    (MBUS_CODE.ACCESS_NUMBER             , 0xFD08  ,   1,    0),
+    (MBUS_CODE.MANUFACTURER              , 0xFD0A  ,   1,    0),
+    (MBUS_CODE.PARAMETER_SET_ID          , 0xFD0B  ,   1,    0),
+    (MBUS_CODE.MODEL_VERSION             , 0xFD0C  ,   1,    0),
+    (MBUS_CODE.HARDWARE_VERSION          , 0xFD0D  ,   1,    0),
+    (MBUS_CODE.FIRMWARE_VERSION          , 0xFD0E  ,   1,    0),
+    (MBUS_CODE.SOFTWARE_VERSION          , 0xFD0F  ,   1,    0),  # C++: "//neu"
+    (MBUS_CODE.CUSTOMER_LOCATION         , 0xFD10  ,   1,    0),
+    (MBUS_CODE.CUSTOMER                  , 0xFD11  ,   1,    0),
+    (MBUS_CODE.ERROR_FLAGS               , 0xFD17  ,   1,    0),
+    (MBUS_CODE.ERROR_MASK                , 0xFD18  ,   1,    0),
+    (MBUS_CODE.DIGITAL_OUTPUT            , 0xFD1A  ,   1,    0),
+    (MBUS_CODE.DIGITAL_INPUT             , 0xFD1B  ,   1,    0),
+    (MBUS_CODE.BAUDRATE_BPS              , 0xFD1C  ,   1,    0),
+    (MBUS_CODE.RESPONSE_DELAY_TIME       , 0xFD1D  ,   1,    0),
+    (MBUS_CODE.RETRY                     , 0xFD1E  ,   1,    0),
+    (MBUS_CODE.SIZE_OF_STORAGE_BLOCK     , 0xFD22  ,   1,    0),
+    (MBUS_CODE.STORAGE_INTERVAL_MONTH    , 0xFD28  ,   1,    0),
+    (MBUS_CODE.GENERIC                   , 0xFD3A  ,   1,    0),
+    (MBUS_CODE.VOLTS                     , 0xFD40  ,  16,   -9),
+    (MBUS_CODE.AMPERES                   , 0xFD50  ,  16,  -12),
+    (MBUS_CODE.RESET_COUNTER             , 0xFD60  ,   1,    0),
+    (MBUS_CODE.CUMULATION_COUNTER        , 0xFD61  ,   1,    0),
+    (MBUS_CODE.SPECIAL_SUPPLIER_INFO     , 0xFD67  ,   1,    0),
+
+    # --- VIFE 0xFDFD ---
+    (MBUS_CODE.CURRENT_SELECTED_APL      , 0xFDFD00,   1,    0),
+    (MBUS_CODE.SUB_DEVICES               , 0xFDFD01,   1,    0),
+    (MBUS_CODE.REMAIN_BAT_LIFE_MONTH     , 0xFDFD02,   1,    0),
+    (MBUS_CODE.CARBON_DIOXIDE_PPM        , 0xFDFD10,   2,    0),
+    (MBUS_CODE.CARBON_MONOXIDE_PPM       , 0xFDFD12,   2,    0),
+    (MBUS_CODE.VOLATILE_ORG_COMP_ppb     , 0xFDFD14,   2,    0),
+    (MBUS_CODE.VOLATILE_ORG_COMP_UG_M3   , 0xFDFD16,   1,    0),
+    (MBUS_CODE.PARTICLES_UNSPEC_UG_M3    , 0xFDFD17,   1,    0),
+    (MBUS_CODE.PARTICLES_PM1_UG_M3       , 0xFDFD18,   1,    0),
+    (MBUS_CODE.PARTICLES_PM2_5_UG_M3     , 0xFDFD19,   1,    0),
+    (MBUS_CODE.PARTICLES_PM10_UG_M3      , 0xFDFD1A,   1,    0),
+    (MBUS_CODE.PARTICLES_UNSPEC_1M3      , 0xFDFD1B,   1,    5),
+    (MBUS_CODE.PARTICLES_PM1_1M3         , 0xFDFD1C,   1,    5),
+    (MBUS_CODE.PARTICLES_PM2_5_1M3       , 0xFDFD1D,   1,    5),
+    (MBUS_CODE.PARTICLES_PM10_1M3        , 0xFDFD1E,   1,    5),
+    (MBUS_CODE.ILLUMINANCE_LUX           , 0xFDFD1F,   1,    0),
+    (MBUS_CODE.LUMINOUS_INTENSITY_CD     , 0xFDFD20,   1,    0),
+    (MBUS_CODE.RADIANT_FLUX_DENS         , 0xFDFD21,   1,    0),
+    (MBUS_CODE.WIND_SPEED_M_S            , 0xFDFD22,   1,    0),
+    (MBUS_CODE.RAINFALL_L_MM             , 0xFDFD23,   1,    0),
+    (MBUS_CODE.FORMAZIN_NEPHELOMETER_U   , 0xFDFD25,   1,    0),
+    (MBUS_CODE.POTENTIAL_HYDROGEN_PH     , 0xFDFD27,   1,    0),
+    (MBUS_CODE.DISMOUNTS_COUNTER         , 0xFDFD2C,   1,    0),
+    (MBUS_CODE.TEST_BUTTON_COUNTER       , 0xFDFD2D,   1,    0),
+    (MBUS_CODE.ALARM_COUNTER             , 0xFDFD2E,   1,    0),
+    (MBUS_CODE.ALARM_MUTE_COUNTER        , 0xFDFD2F,   1,    0),
+    (MBUS_CODE.OBSTACLE_DETECT_COUNTER   , 0xFDFD30,   1,    0),
+    (MBUS_CODE.SMOKE_ENTRIES_COUNTER     , 0xFDFD31,   1,    0),
+    (MBUS_CODE.SMOKE_CHAMBER_DEFECTS     , 0xFDFD32,   1,    0),
+    (MBUS_CODE.SELF_TEST_COUNTER         , 0xFDFD33,   1,    0),
+    (MBUS_CODE.SOUNDER_DEFECT_COUNTER    , 0xFDFD34,   1,    0),
+    (MBUS_CODE.DECIBEL_A                 , 0xFDFD36,   1,    0),
+    (MBUS_CODE.BATTERY_PERCENTAGE        , 0xFDFD38,   1,    0),
+    (MBUS_CODE.CHAMBER_POLLUTION_LEVEL   , 0xFDFD39,   1,    0),
+    (MBUS_CODE.DISTANCE_MM               , 0xFDFD3A,   2,    0),
+    (MBUS_CODE.MOISTURE_LEVEL_PERCENT    , 0xFDFD3E,   1,    0),
+    (MBUS_CODE.PRESSURE_SENS_STATUS      , 0xFDFD40,   1,    0),
+    (MBUS_CODE.SMOKE_ALARM_STATUS        , 0xFDFD41,   1,    0),
+    (MBUS_CODE.CO_ALARM_STATUS           , 0xFDFD42,   1,    0),
+    (MBUS_CODE.HEAT_ALARM_STATUS         , 0xFDFD43,   1,    0),
+    (MBUS_CODE.DOOR_WINDOW_SENS_STATUS   , 0xFDFD44,   1,    0),
+
+    # --- VIFE 0xFB ---
+    (MBUS_CODE.ENERGY_WH                 , 0xFB00  ,   2,    5),
+    (MBUS_CODE.REACTIVE_ENERGY           , 0xFB02  ,   2,    0),
+    (MBUS_CODE.ENERGY_J                  , 0xFB08  ,   2,    8),
+    (MBUS_CODE.VOLUME_M3                 , 0xFB10  ,   2,    2),
+    (MBUS_CODE.REACTIVE_POWER            , 0xFB14  ,   4,   -3),
+    (MBUS_CODE.MASS_KG                   , 0xFB18  ,   2,    5),
+    (MBUS_CODE.RELATIVE_HUMIDITY         , 0xFB1A  ,   2,   -1),
+    (MBUS_CODE.VOLUME_FT3                , 0xFB21  ,   1,   -1),
+    (MBUS_CODE.VOLUME_GAL                , 0xFB22  ,   2,   -1),
+    (MBUS_CODE.VOLUME_FLOW_GAL_M         , 0xFB24  ,   1,   -3),
+    (MBUS_CODE.VOLUME_FLOW_GAL_M         , 0xFB25  ,   1,    0),
+    (MBUS_CODE.VOLUME_FLOW_GAL_H         , 0xFB26  ,   1,    0),
+    (MBUS_CODE.POWER_W                   , 0xFB28  ,   2,    5),
+    (MBUS_CODE.PHASE_VOLT_DEG            , 0xFB2A  ,   1,   -1),
+    (MBUS_CODE.PHASE_CURR_DEG            , 0xFB2B  ,   1,   -1),
+    (MBUS_CODE.FREQUENCY                 , 0xFB2C  ,   4,   -3),
+    (MBUS_CODE.POWER_J_H                 , 0xFB30  ,   2,    8),
+    (MBUS_CODE.APPARENT_POWER            , 0xFB34  ,   4,   -3),
+    (MBUS_CODE.FLOW_TEMPERATURE_F        , 0xFB58  ,   4,   -3),
+    (MBUS_CODE.RETURN_TEMPERATURE_F      , 0xFB5C  ,   4,   -3),
+    (MBUS_CODE.TEMPERATURE_DIFF_F        , 0xFB60  ,   4,   -3),
+    (MBUS_CODE.EXTERNAL_TEMPERATURE_F    , 0xFB64  ,   4,   -3),
+    (MBUS_CODE.TEMPERATURE_LIMIT_F       , 0xFB70  ,   4,   -3),
+    (MBUS_CODE.TEMPERATURE_LIMIT_C       , 0xFB74  ,   4,   -3),
+    (MBUS_CODE.MAX_POWER_W               , 0xFB78  ,   8,   -3),
+
+    # --- VIFE 0xFC ---
+    (MBUS_CODE.CUSTOMIZED_VIF            , 0xFC00  , 254,    0),
+
+    # --- VIFE 0xFF ---
+    (MBUS_CODE.MANUFACTURER_SPECIFIC     , 0xFF00  , 254,    0),
+)
+
+# Safety net: must match the C++ constant exactly.
+assert len(VIF_DEFS) == MBUS_VIF_DEF_NUM, len(VIF_DEFS)

mbusinolibpy-0.10.0.dist-info/METADATA

@@ -0,0 +1,284 @@
+Metadata-Version: 2.4
+Name: MBusinoLibPy
+Version: 0.10.0
+Summary: Python port of MBusinoLib, the Arduino M-Bus (Meterbus) RSP_UD decoder library
+Author-email: Zeppelin500 <mbusinolib@gmail.com>
+License: GPL-3.0-or-later
+Project-URL: Homepage, https://github.com/Zeppelin500/MBusinoLibPy
+Project-URL: Source, https://github.com/Zeppelin500/MBusinoLibPy
+Project-URL: Original, https://github.com/Zeppelin500/MBusinoLib
+Keywords: m-bus,mbus,meterbus,mbusino,decoder,dif,vif,en13757,smart-meter,heat-meter
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Home Automation
+Classifier: Topic :: Software Development :: Embedded Systems
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# MBusinoLibPy - a Python M-Bus Decoder
+
+[![version](https://img.shields.io/badge/version-0.10.0-brightgreen.svg)](CHANGELOG.md)
+[![license](https://img.shields.io/badge/license-GPL--3.0-orange.svg)](LICENSE)
+[![python](https://img.shields.io/badge/python-%E2%89%A53.9-blue.svg)](https://www.python.org/)
+[![dependencies](https://img.shields.io/badge/runtime%20deps-0-brightgreen.svg)](pyproject.toml)
+
+**MBusinoLibPy** decodes M-Bus (Meterbus) **RSP_UD** telegrams - the answer a
+slave sends to the master - into plain Python dicts. It uses nothing but the
+Python standard library and is the Python port of the Arduino library
+[**MBusinoLib**](https://github.com/Zeppelin500/MBusinoLib) (v0.10.0,
+GPL-3.0).
+
+* **No runtime dependencies** - Python ≥ 3.9, standard library only.
+* Validates a *complete* frame (start/stop byte, declared length, checksum)
+  before decoding header and records.
+* Known record types come with readable names, units and Home Assistant
+  metadata.
+
+## Installation
+
+There is no PyPI package - install straight from GitHub:
+
+```bash
+pip install git+https://github.com/Zeppelin500/MBusinoLibPy.git
+```
+
+Working on the code itself? Use a development checkout:
+
+```bash
+git clone https://github.com/Zeppelin500/MBusinoLibPy.git
+cd MBusinoLibPy
+pip install -e .
+```
+
+## Quick start
+
+```python
+from MBusinoLibPy import MBusinoLib
+
+# A complete M-Bus long frame: 68 LL LL 68 C A CI ... CHK 16
+telegram = bytes.fromhex(
+    "68 C1 C1 68 08 00 72 09 34 75 73 C5 14 00 0D 43 00 00 00 04"
+    "78 41 63 65 04 04 06 AA 29 00 00 04 13 40 A1 75 00 04 2B 00"
+    "00 00 00 14 2B 3C F3 00 00 ... 75 16"          # shortened for readability
+)
+
+decode = MBusinoLib()
+result = decode.decode_telegram(telegram)
+
+print(result["frame"]["ok"], result["error_message"])   # True No error
+print(result["header"]["manufacturer"], result["header"]["id"])   # EFE 73753409
+print(result["header"]["medium"])                      # Heat (Mass)
+
+for record in result["records"]:
+    print(record["name"], record.get("value_scaled"), record.get("units"))
+# fab_number 73753409.0 None
+# volume 7708.992 m³
+# ...
+```
+
+A hex string works too (spaces, commas and `0x` prefixes are accepted):
+
+```python
+result = MBusinoLib().decode_telegram("68 1F 1F 68 08 00 72 78 56 34 ... CC 16")
+```
+
+More runnable examples: [examples/](examples/).
+
+## API reference
+
+All decoding entry points are methods of the `MBusinoLib` class.
+
+### `decode_telegram(raw)`
+
+```python
+def decode_telegram(raw: bytes) -> dict
+```
+
+Validates a complete frame and then decodes header and records.
+
+* `raw` - complete telegram as `bytes`/`bytearray`, a list of byte values, or
+  a hex string.
+* returns
+
+  ```python
+  {
+      "frame": {          # frame checks
+          "byte_count", "packet_size", "slave_address", "c_field", "ci_field",
+          "start_ok", "length_ok", "fits", "stop_ok",
+          "checksum", "checksum_received", "checksum_ok", "quartet_checksum_ok",
+          "ok", "error_message",
+      },
+      "header": {...},    # decode_header() output
+      "records": [...],   # decode_records() output
+      "error": 0,         # error code of the decoding step (see Error handling)
+      "error_message": "...",  # message for the first problem found
+  }
+  ```
+
+  `frame["ok"]` is `True` only when everything matched: start bytes, equal
+  length fields, declared length vs. actual size, stop byte and checksum.
+  The checksum is verified both as a plain byte sum and as an alternative
+  *quartet* (half-byte) sum - either match counts, and both results are
+  reported individually.
+
+### `decode_records(buffer, size=None)`
+
+```python
+def decode_records(buffer, size=None) -> list[dict]
+```
+
+* `buffer` - record bytes, normally `telegram[0x13:packet_size]`.
+* `size` - how many bytes to read. Default: `len(buffer)`.
+* returns the list of decoded records.
+
+Each record contains these keys (a key is only present when the telegram
+carries it):
+
+| key | content |
+|-----|---------|
+| `vif` | VIF/VIFE as lower-case hex string, e.g. `"0xfd1b"` |
+| `code` | `MBUS_CODE` value (the record type, *not* the VIF byte) |
+| `value_scaled` | numeric value, already scaled - absent for pure ASCII records |
+| `value_string` | formatted value (dates, ASCII) |
+| `units` | unit such as `"Wh"`, `"m³"`, `"°C"` - absent when none applies |
+| `name` | record name plus VIFE/function suffix, e.g. `"power_L1"` |
+| `subUnit` | > 0 only |
+| `storage` | > 0 only |
+| `tariff` | > 0 only |
+| `telegramFollow` | `1` when the frame ends with the `0x1F` marker |
+
+> **Error semantics:** when a record would run past the end of the buffer,
+> decoding stops, `BUFFER_OVERFLOW` is set, and the records decoded so far
+> are returned - so a partial result is always usable.
+
+### `decode_header(buffer, length=None)`
+
+```python
+def decode_header(buffer, length=None) -> dict
+```
+
+* `buffer` - the **complete** telegram including start/stop bytes.
+* `length` - usable length of the telegram. Default: `len(buffer)`.
+* returns the header fields; an empty/partial dict signals failure:
+
+| Python return | meaning |
+|---------------|---------|
+| `{}` | failed before writing (too short, wrong start byte, L1 ≠ L2) |
+| dict without `"id"` | failed after writing (CI is not `0x72`/`0x76`) |
+| dict with `"id"` | success |
+
+Possible header fields:
+
+* `len`, `c_field`, `address`, `ci_field` - basic frame header
+* `id` - meter identification number as HEX string (4 byte BCD, LSB first)
+* `manufacturer` - 3-letter manufacturer code
+* `version`, `medium_code`, `medium` - meter version and medium as text
+* `access_counter`, `status`
+* `status_details` - nested dict: `battery_low`, `permanent_error`,
+  `temporary_error`, `app_status`
+* `signature`
+
+### `get_code_name`, `get_code_units`, `get_device_class`, `get_state_class`
+
+```python
+get_code_name(code)                 -> str      # "" when unknown
+get_code_units(code)                -> str|None # None == no unit
+get_device_class(code, medium=0xFF) -> str      # "" when Home Assistant has no class
+get_state_class(code)               -> str      # "" when not applicable
+```
+
+Four lookup methods for `MBUS_CODE` values, implemented as complete lookup
+tables in `MBusinoLibPy/lookup_tables.py`. For the cumulative volume codes
+(`VOLUME_M3`/`FT3`/`GAL`) the `medium` argument selects the Home Assistant
+`device_class` (`water` / `gas` / `volume`).
+
+```python
+from MBusinoLibPy import MBUS_CODE, MBusinoLib
+
+decode = MBusinoLib()
+decode.get_code_name(MBUS_CODE.ENERGY_WH)            # 'energy'
+decode.get_code_units(MBUS_CODE.VOLUME_M3)           # 'm³'
+decode.get_device_class(MBUS_CODE.VOLUME_M3, 0x07)   # 'water' (medium = Water)
+decode.get_device_class(MBUS_CODE.VOLUME_M3, 0x03)   # 'gas'   (medium = Gas)
+decode.get_state_class(MBUS_CODE.ENERGY_WH)          # 'total_increasing'
+```
+
+### `get_error` / `get_error_message`
+
+```python
+decode.get_error()         -> int   # error code, then reset to NO_ERROR
+decode.get_error_message(code=None) -> str  # readable message, does NOT reset
+```
+
+`get_error()` returns the stored error code **and** clears it, so the next
+call starts fresh. `get_error_message()` only reads - with no argument it
+reports the currently stored error, with a code argument it translates that
+code. Call `get_error_message()` before `get_error()` if you need both.
+
+## Error handling
+
+Problems show up in two places:
+
+* **frame level** - `result["frame"]["ok"]` is `False` and
+  `result["frame"]["error_message"]` says what was wrong (start byte, length
+  fields, truncation, stop byte, checksum).
+* **decoding level** - `result["error"]` carries an error code and
+  `result["error_message"]` the matching text.
+
+The decoder itself can produce these codes:
+
+| value | name | meaning |
+|-------|------|---------|
+| 0 | `NO_ERROR` | no error |
+| 1 | `BUFFER_OVERFLOW` | declared length does not fit, or a record reaches past the buffer |
+| 4 | `UNSUPPORTED_VIF` | VIF is not known; the record falls back to `unknown_vif` |
+
+How to check errors:
+
+```python
+result = MBusinoLib().decode_telegram(telegram)
+
+if not result["frame"]["ok"]:
+    print(result["frame"]["error_message"])     # e.g. "Checksum mismatch: ..."
+if result["error"] != 0:
+    print(result["error_message"])              # e.g. "Unknown or unsupported VIF - ..."
+```
+
+When decoding records directly, use the instance methods (note that
+`get_error()` clears the value):
+
+```python
+decode = MBusinoLib()
+records = decode.decode_records(buf)
+code = decode.get_error()                       # int, reset to 0 afterwards
+if code != 0:
+    print(decode.get_error_message(code))
+```
+
+### Enums
+
+`MBUS_CODE` (123 members) and `MBUS_ERROR` (6 members) are `IntEnum`s.
+`VIF_DEFS` is the VIF definition table (132 entries: `(code, base, size,
+scalar)`).
+
+## License
+
+MBusinoLibPy is free software under the GNU General Public License v3 (or
+later) - see [LICENSE](LICENSE).
+
+## Development
+
+Run the test suite from the repository root: `python3 -m unittest`.
+
+Internal development notes and open points from the implementation live in
+[dev_issues/](dev_issues/README.md).

mbusinolibpy-0.10.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+MBusinoLibPy/__init__.py,sha256=WYwzWan95VgeRapuoyy6ytlMg3oOi3VTnE0IpfW4uPY,1955
+MBusinoLibPy/enums.py,sha256=QeqEhClnhEVVTvAlACvGm1IeqN9PirF6PwJOFnnZY58,5003
+MBusinoLibPy/lookup_tables.py,sha256=iL0SpECEbkVpQEljPZJTEib3Esbiq8-rvpfZDWm9Ip8,38058
+MBusinoLibPy/mbusino_lib.py,sha256=YCafJukdlYo6rpH1UwDOiOsjTv2zb689k9HxOdAJlnE,56168
+MBusinoLibPy/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+MBusinoLibPy/vif_defs.py,sha256=nBUXrSRf1ooj0hVjpvJXJCvKcLawN6bvk5udAcBnFuw,9985
+mbusinolibpy-0.10.0.dist-info/licenses/LICENSE,sha256=OXLcl0T2SZ8Pmy2_dmlvKuetivmyPd5m1q-Gyd-zaYY,35149
+mbusinolibpy-0.10.0.dist-info/METADATA,sha256=tgbSMFtLeJefZfNgiMAI5NzuDf_6kKggRmxXmE4hqt4,10291
+mbusinolibpy-0.10.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+mbusinolibpy-0.10.0.dist-info/top_level.txt,sha256=BYSSt2wqI6vm2kWEc_1kAuzPjkC-giji4vipsmcs_cc,13
+mbusinolibpy-0.10.0.dist-info/RECORD,,

mbusinolibpy-0.10.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+