pywfrac 0.1.0__tar.gz

pywfrac-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,61 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  pytest:
+    name: Pytest (${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install
+        run: pip install -e ".[dev]"
+      - name: Run tests
+        run: pytest --cov=src/pywfrac --cov-report=term-missing
+
+  mypy:
+    name: Mypy
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - name: Install
+        run: pip install -e ".[dev]"
+      - name: Run mypy
+        run: mypy
+
+  ruff:
+    name: Ruff
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - name: Install
+        run: pip install -e ".[dev]"
+      - name: Run ruff
+        run: ruff check .
+
+  build:
+    name: Build package
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - name: Install build
+        run: pip install build
+      - name: Build sdist and wheel
+        run: python -m build

pywfrac-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,62 @@
+name: Release
+
+# Triggered by pushing a version tag (vX.Y.Z). Builds sdist+wheel and
+# publishes to PyPI via Trusted Publishing (OIDC) - no token stored in this
+# repo. The PyPI project must have this workflow registered as a trusted
+# publisher first (pypi.org project settings -> Publishing), which is a
+# one-time manual step done from the PyPI web UI.
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: read
+
+jobs:
+  check-version:
+    name: Check tag against pyproject.toml
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Compare tag to the package version
+        run: |
+          tag="${GITHUB_REF_NAME#v}"
+          version=$(python3 -c "import tomllib; print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
+          if [ "$tag" != "$version" ]; then
+            echo "::error::tag $GITHUB_REF_NAME does not match pyproject.toml version $version"
+            exit 1
+          fi
+
+  build:
+    name: Build distribution
+    needs: check-version
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - name: Install build
+        run: pip install build
+      - name: Build sdist and wheel
+        run: python -m build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # OIDC for Trusted Publishing
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

pywfrac-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.pyc
+.venv/
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+dist/
+build/
+*.egg-info/

pywfrac-0.1.0/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2022 jeatheak
+Copyright (c) 2026 blues-sechseck
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pywfrac-0.1.0/PKG-INFO

@@ -0,0 +1,101 @@
+Metadata-Version: 2.5
+Name: pywfrac
+Version: 0.1.0
+Summary: Async client library for Mitsubishi Heavy Industries WF-RAC WiFi module air conditioners
+Project-URL: Homepage, https://github.com/blues-sechseck/pywfrac
+Project-URL: Protocol reference, https://github.com/blues-sechseck/Mitsubishi-WF-RAC-Integration/blob/main/ha-integration/docs/wf-rac-module-reference.md
+Project-URL: Changelog, https://github.com/blues-sechseck/pywfrac/releases
+Author-email: Daniel <daosthofen@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: air-conditioner,hvac,mitsubishi,wf-rac
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Home Automation
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: aiohttp>=3.9
+Provides-Extra: dev
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pytest-asyncio; extra == 'dev'
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# pywfrac
+
+[![PyPI](https://img.shields.io/pypi/v/pywfrac)](https://pypi.org/project/pywfrac/)
+[![CI](https://github.com/blues-sechseck/pywfrac/actions/workflows/ci.yml/badge.svg)](https://github.com/blues-sechseck/pywfrac/actions/workflows/ci.yml)
+
+Async Python client library for **Mitsubishi Heavy Industries** air
+conditioners that use the **WF-RAC** WiFi module and the **Smart M-Air** app.
+Talks the module's local HTTP(S) API and decodes/encodes the `airconStat`
+protocol carried over it.
+
+> **Not for Mitsubishi Electric systems** (e.g. a MAC-577IF2-E interface) or
+> MELCloud — different manufacturer, different protocol.
+
+This library is the protocol layer extracted from the
+[`mitsubishi_wf_rac`](https://github.com/blues-sechseck/Mitsubishi-WF-RAC-Integration)
+Home Assistant integration, which stays the reference for field notes and
+supported devices. `pywfrac` has no dependency on Home Assistant — it only
+needs an `aiohttp.ClientSession`.
+
+## Install
+
+```
+pip install pywfrac
+```
+
+## Usage
+
+```python
+import aiohttp
+from pywfrac import Repository
+
+async def main() -> None:
+    async with aiohttp.ClientSession() as session:
+        repo = Repository(
+            session,
+            hostname="192.168.1.50",
+            port=51443,
+            operator_id="my-operator-id",
+            device_id="my-device-id",
+        )
+        airco_id = await repo.get_airco_id()
+        await repo.update_account_info(airco_id, time_zone="Europe/Berlin")
+        stats = await repo.get_aircon_stats(airco_id)
+```
+
+`Repository` discovers whether the module speaks plain HTTP or HTTPS on the
+first request and remembers the result; construct it with `method="http"` or
+`method="https"` to skip discovery if you already know. Pass `cert_path` to
+use a captured module certificate instead of the permissive fallback context
+— see `Repository._get_ssl_context` for how to capture one.
+
+`RacParser` turns a raw `getAirconStat` response into an `Aircon`/`AirconStat`
+object and back; see the protocol reference linked below for the field
+layout.
+
+## Protocol reference
+
+The `airconStat` wire format, error codes, and per-model capability tables
+are documented in the integration's
+[module reference](https://github.com/blues-sechseck/Mitsubishi-WF-RAC-Integration/blob/main/ha-integration/docs/wf-rac-module-reference.md).
+
+## Versioning
+
+This library follows [SemVer](https://semver.org/), independent of the
+integration's own CalVer release scheme — pin an exact version.
+
+## License
+
+MIT, see [LICENSE](LICENSE). Extracted from code originally by
+[@jeatheak](https://github.com/jeatheak), maintained since by
+[@blues-sechseck](https://github.com/blues-sechseck).

pywfrac-0.1.0/README.md

@@ -0,0 +1,71 @@
+# pywfrac
+
+[![PyPI](https://img.shields.io/pypi/v/pywfrac)](https://pypi.org/project/pywfrac/)
+[![CI](https://github.com/blues-sechseck/pywfrac/actions/workflows/ci.yml/badge.svg)](https://github.com/blues-sechseck/pywfrac/actions/workflows/ci.yml)
+
+Async Python client library for **Mitsubishi Heavy Industries** air
+conditioners that use the **WF-RAC** WiFi module and the **Smart M-Air** app.
+Talks the module's local HTTP(S) API and decodes/encodes the `airconStat`
+protocol carried over it.
+
+> **Not for Mitsubishi Electric systems** (e.g. a MAC-577IF2-E interface) or
+> MELCloud — different manufacturer, different protocol.
+
+This library is the protocol layer extracted from the
+[`mitsubishi_wf_rac`](https://github.com/blues-sechseck/Mitsubishi-WF-RAC-Integration)
+Home Assistant integration, which stays the reference for field notes and
+supported devices. `pywfrac` has no dependency on Home Assistant — it only
+needs an `aiohttp.ClientSession`.
+
+## Install
+
+```
+pip install pywfrac
+```
+
+## Usage
+
+```python
+import aiohttp
+from pywfrac import Repository
+
+async def main() -> None:
+    async with aiohttp.ClientSession() as session:
+        repo = Repository(
+            session,
+            hostname="192.168.1.50",
+            port=51443,
+            operator_id="my-operator-id",
+            device_id="my-device-id",
+        )
+        airco_id = await repo.get_airco_id()
+        await repo.update_account_info(airco_id, time_zone="Europe/Berlin")
+        stats = await repo.get_aircon_stats(airco_id)
+```
+
+`Repository` discovers whether the module speaks plain HTTP or HTTPS on the
+first request and remembers the result; construct it with `method="http"` or
+`method="https"` to skip discovery if you already know. Pass `cert_path` to
+use a captured module certificate instead of the permissive fallback context
+— see `Repository._get_ssl_context` for how to capture one.
+
+`RacParser` turns a raw `getAirconStat` response into an `Aircon`/`AirconStat`
+object and back; see the protocol reference linked below for the field
+layout.
+
+## Protocol reference
+
+The `airconStat` wire format, error codes, and per-model capability tables
+are documented in the integration's
+[module reference](https://github.com/blues-sechseck/Mitsubishi-WF-RAC-Integration/blob/main/ha-integration/docs/wf-rac-module-reference.md).
+
+## Versioning
+
+This library follows [SemVer](https://semver.org/), independent of the
+integration's own CalVer release scheme — pin an exact version.
+
+## License
+
+MIT, see [LICENSE](LICENSE). Extracted from code originally by
+[@jeatheak](https://github.com/jeatheak), maintained since by
+[@blues-sechseck](https://github.com/blues-sechseck).

pywfrac-0.1.0/pyproject.toml

@@ -0,0 +1,70 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "pywfrac"
+version = "0.1.0"
+description = "Async client library for Mitsubishi Heavy Industries WF-RAC WiFi module air conditioners"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.11"
+authors = [
+    { name = "Daniel", email = "daosthofen@gmail.com" },
+]
+keywords = ["mitsubishi", "wf-rac", "air-conditioner", "hvac"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Home Automation",
+    "Typing :: Typed",
+]
+dependencies = [
+    "aiohttp>=3.9",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest",
+    "pytest-asyncio",
+    "pytest-cov",
+    "mypy",
+    "ruff",
+]
+
+[project.urls]
+Homepage = "https://github.com/blues-sechseck/pywfrac"
+"Protocol reference" = "https://github.com/blues-sechseck/Mitsubishi-WF-RAC-Integration/blob/main/ha-integration/docs/wf-rac-module-reference.md"
+Changelog = "https://github.com/blues-sechseck/pywfrac/releases"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/pywfrac"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[tool.mypy]
+files = ["src/pywfrac"]
+strict = true
+
+[tool.ruff]
+target-version = "py311"
+# 100, not the default 88: the code this library was extracted from (and its
+# test suite, copied over unchanged) already runs comments/messages past 88
+# in places, and reflowing logic untouched from the integration isn't the
+# point of this migration.
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP"]
+
+[tool.ruff.lint.per-file-ignores]
+# Parametrize tables copied verbatim from the integration's test suite - not
+# reflowing data literals that aren't ours to redesign.
+"tests/test_rac_parser.py" = ["E501", "E731"]

pywfrac-0.1.0/src/pywfrac/__init__.py

@@ -0,0 +1,45 @@
+"""pywfrac - async client library for Mitsubishi Heavy Industries WF-RAC modules.
+
+Talks the local HTTP(S) API of the WF-RAC/WCBN4612L WiFi adapter that ships
+with several MHI split-system air conditioners, and decodes/encodes the
+airconStat protocol carried over it. Extracted from the
+`mitsubishi_wf_rac` Home Assistant integration
+(https://github.com/blues-sechseck/Mitsubishi-WF-RAC-Integration), which
+remains the reference for the protocol's field notes.
+"""
+
+from .capabilities import ModelCapabilities, get_capabilities
+from .error_codes import describe_error_code
+from .models.aircon import Aircon, AirconCommands, AirconStat, HomeLeaveModeSetting
+from .parser import RacParser
+from .repository import (
+    READ_RESULT_CODES,
+    RESULT_CODES,
+    Repository,
+    WfRacCommandError,
+    WfRacConnectionError,
+    WfRacError,
+    WfRacRegistrationError,
+    WfRacWriteRefusedError,
+    describe_result,
+)
+
+__all__ = [
+    "Repository",
+    "WfRacError",
+    "WfRacCommandError",
+    "WfRacRegistrationError",
+    "WfRacWriteRefusedError",
+    "WfRacConnectionError",
+    "RESULT_CODES",
+    "READ_RESULT_CODES",
+    "describe_result",
+    "RacParser",
+    "Aircon",
+    "AirconStat",
+    "AirconCommands",
+    "HomeLeaveModeSetting",
+    "ModelCapabilities",
+    "get_capabilities",
+    "describe_error_code",
+]

pywfrac-0.1.0/src/pywfrac/capabilities.py

@@ -0,0 +1,97 @@
+"""Per-model feature capability table, ported from the official app.
+
+Ground truth: the app's own `res/values/arrays.xml`
+(`model_no_type_function_*`, 5 tables x 17 flags) and `model/ModelNoType.java`
+(flag order, table selection).
+"""
+
+from dataclasses import dataclass
+from typing import Final
+
+
+@dataclass(frozen=True)
+class ModelCapabilities:
+    """Feature flags for one `model_no_type` table entry (17 booleans, in the
+    app's own field order - see ModelNoType.java's getters)."""
+
+    power_consumption: bool
+    vacant_property: bool
+    self_clean_operation: bool
+    wind_direction_lr: bool
+    entrust: bool
+    led_light: bool
+    auto_heating: bool
+    home_leave_mode: bool
+    temp_information: bool
+    indoor_and_outdoor_temp: bool
+    preset_temp_auto: bool
+    call_center_phone_number: bool
+    outdoor_temp_always_show: bool
+    outdoor_temp_outside_tokyo: bool
+    cool_hot_judge: bool
+    preset_temp_range_2: bool
+    operation_data: bool
+
+
+# Transcribed 1:1 from arrays.xml (item order == flag order above).
+_SEPARATE_2021: Final = ModelCapabilities(
+    power_consumption=True, vacant_property=False, self_clean_operation=False,
+    wind_direction_lr=True, entrust=True, led_light=True, auto_heating=True,
+    home_leave_mode=False, temp_information=True, indoor_and_outdoor_temp=True,
+    preset_temp_auto=False, call_center_phone_number=False,
+    outdoor_temp_always_show=False, outdoor_temp_outside_tokyo=True,
+    cool_hot_judge=True, preset_temp_range_2=False, operation_data=False,
+)
+_GLOBAL_2022: Final = ModelCapabilities(
+    power_consumption=True, vacant_property=True, self_clean_operation=True,
+    wind_direction_lr=True, entrust=True, led_light=False, auto_heating=True,
+    home_leave_mode=True, temp_information=True, indoor_and_outdoor_temp=True,
+    preset_temp_auto=False, call_center_phone_number=False,
+    outdoor_temp_always_show=True, outdoor_temp_outside_tokyo=False,
+    cool_hot_judge=True, preset_temp_range_2=False, operation_data=False,
+)
+_HIGH_END_FOR_JAPANESE_2023: Final = ModelCapabilities(
+    power_consumption=True, vacant_property=False, self_clean_operation=True,
+    wind_direction_lr=True, entrust=True, led_light=False, auto_heating=False,
+    home_leave_mode=False, temp_information=True, indoor_and_outdoor_temp=True,
+    preset_temp_auto=False, call_center_phone_number=True,
+    outdoor_temp_always_show=False, outdoor_temp_outside_tokyo=False,
+    cool_hot_judge=True, preset_temp_range_2=False, operation_data=False,
+)
+_ZT_2025: Final = ModelCapabilities(
+    power_consumption=False, vacant_property=True, self_clean_operation=True,
+    wind_direction_lr=True, entrust=True, led_light=False, auto_heating=True,
+    home_leave_mode=True, temp_information=True, indoor_and_outdoor_temp=True,
+    preset_temp_auto=False, call_center_phone_number=False,
+    outdoor_temp_always_show=True, outdoor_temp_outside_tokyo=False,
+    cool_hot_judge=True, preset_temp_range_2=True, operation_data=True,
+)
+_FDT_2023: Final = ModelCapabilities(
+    power_consumption=False, vacant_property=False, self_clean_operation=False,
+    wind_direction_lr=False, entrust=False, led_light=True, auto_heating=False,
+    home_leave_mode=False, temp_information=False, indoor_and_outdoor_temp=True,
+    preset_temp_auto=True, call_center_phone_number=False,
+    outdoor_temp_always_show=True, outdoor_temp_outside_tokyo=False,
+    cool_hot_judge=False, preset_temp_range_2=False, operation_data=False,
+)
+
+# Raw ModelNr byte -> table. Not a sequential scheme - hardcoded in
+# ModelNoType.java:getArrayPosition(): 1/2/3/64 map to their own table,
+# everything else (including 0) falls back to separate_2021.
+_TABLE_BY_RAW: Final = {
+    1: _GLOBAL_2022,
+    2: _HIGH_END_FOR_JAPANESE_2023,
+    3: _ZT_2025,
+    64: _FDT_2023,
+}
+
+
+# `wind_direction_lr` says what the model line supports, not what the unit
+# reports back: on the legacy bus protocol the module pins the left/right vane
+# and 3D-auto bits regardless of model (rac_parser.py, and section 6.7 of
+# docs/wf-rac-module-reference.md). Gate a horizontal-swing entity on the
+# observed state byte, not on this flag alone.
+def get_capabilities(model_nr_raw: int) -> ModelCapabilities:
+    """Return the capability table for a device's raw ModelNr byte
+    (`content[0] & 127`, see rac_parser.py's `ModelNrRaw`)."""
+    return _TABLE_BY_RAW.get(model_nr_raw, _SEPARATE_2021)

pywfrac-0.1.0/src/pywfrac/error_codes.py

@@ -0,0 +1,84 @@
+"""Plain-language descriptions for the self-diagnosis ErrorCode (rac_parser.py).
+
+Transcribed from the official MHI service/user manuals and the SRK
+databooks. Not hardware-verified against a real occurrence - only
+cross-checked between documents.
+
+The unit numbers errors and protective stops out of one shared space (the
+databooks' "Error code, stop code table"), which is why the same number is
+described once here and reused for both spellings: E<n> is the escalated,
+displayed fault, M<n> the protective stop that has not (yet) escalated - see
+describe_error_code().
+"""
+
+from typing import Final
+
+# High confidence: present with matching wording in the SRR service manual, the
+# SRK user's manual and the ZS-WF/ZSX-WF/ZR-WF databooks. The databook tables
+# are word-for-word identical across those three series, so these are not
+# specific to one model family.
+_HIGH_CONFIDENCE: Final[dict[str, str]] = {
+    "1": "Fehler Kabel-Fernbedienung",
+    "5": "Signalübertragungsfehler Indoor/Outdoor",
+    "35": "Kühl-Hochdruckschutz",
+    "36": "Verdichter-Übertemperatur (110 °C)",
+    "37": "Außenwärmetauscher-Sensor-Fehler",
+    "38": "Außenlufttemperatur-Sensor-Fehler",
+    "39": "Druckgasleitungs-Sensor-Fehler",
+    "40": "Absperrventil (Gasseite) geschlossen",
+    "42": "Current Cut (Startstrom-Abschaltung)",
+    "47": "Active-Filter-Spannungsfehler",
+    "48": "Außenlüfter-Fehler",
+    "51": "Leistungstransistor-Fehler",
+    "57": "Kältekreis-Schutzabschaltung",
+    "58": "Current-Safe-Abschaltung",
+    # Was "Störung Außeneinheit" until the databooks named the actual causes.
+    "59": "Verdichter-Verkabelung unterbrochen / Spannungseinbruch",
+    "61": "Verbindungsleitungen Innen-/Außeneinheit fehlerhaft",
+    "62": "Serielle Übertragungsstörung",
+    "80": "Innenlüfter-Motor gestört",
+    "82": "Innenwärmetauscher-Sensor-Fehler",
+    "84": "Kondensationsschutz aktiv",
+    "85": "Frostschutz aktiv",
+    "86": "Heiz-Hochdruckschutz aktiv",
+}
+
+# Medium confidence: the number is confirmed for a different indoor unit form
+# factor only (9: SRR series, explicitly marked "SRR series only" in the
+# service manual), or it appears in no databook table at all (16 is the SRR
+# indoor fan motor number - the SRK tables use 80 for that; 60 has no entry in
+# any of the three).
+_MEDIUM_CONFIDENCE: Final[dict[str, str]] = {
+    "9": "Drain-Störung (Service-Manual: nur SRR-Baureihe, für SRK unbestätigt)",
+    "16": "Innenlüfter-Fehler (SRR-Nummer; SRK meldet dafür 80)",
+    "60": "Rotor-Blockade (in keiner Databook-Tabelle belegt)",
+}
+
+
+def describe_error_code(code: str) -> str | None:
+    """Klartext description for an E<n> or M<n> code, or None if undocumented.
+
+    Both spellings resolve through the same table: the unit numbers protective
+    stops and displayed faults out of one space, so M35 and E35 are the same
+    condition at different escalation stages (the databooks' auto-recovery
+    column gives the count - e.g. cooling high pressure control after 5
+    occurrences, compressor overheat after 2). M codes are prefixed so the
+    distinction survives into the UI, since a protective stop that recovered on
+    its own is not the same news as a fault the unit is displaying.
+
+    Anything outside the tables gets no text rather than a guess.
+    """
+    if not code or code == "00":
+        return None
+    prefix, number = code[0], code[1:]
+    if prefix not in ("E", "M") or not number.isdigit():
+        return None
+    # rac_parser spells M codes zero-padded ("M01") and E codes bare ("E1"),
+    # so normalise before the lookup rather than keying both spellings.
+    number = str(int(number))
+    description = _HIGH_CONFIDENCE.get(number) or _MEDIUM_CONFIDENCE.get(number)
+    if description is None:
+        return None
+    if prefix == "M":
+        return f"Schutzabschaltung: {description}"
+    return description