@@ -0,0 +1,135 @@
+= Decoder-Spezifikationen (Stufe 2)
+:sectlinks:
+
+Der Empfang läuft in zwei Stufen, wie in link:../architecture/decisions/ADR-006-sensor-decoding-layer.adoc[ADR-006] beschrieben:
+
+. *Stufe 1* — `signalduino/parser` und `sd_protocols` machen aus Pulsen eine Bitfolge und daraus einen Hex-Payload.
+. *Stufe 2* — `signalduino/decoders` macht daraus Messwerte: Temperatur, Luftfeuchte, Batteriezustand, Sensor-ID, Kanal.
+
+Dieses Kapitel beschreibt, wie man Stufe 2 um ein Protokoll erweitert.
+
+== Der Regelfall: eine JSON-Datei
+
+Die meisten Protokolle lassen sich vollständig als Daten beschreiben. Eine Spezifikation liegt unter `signalduino/decoders/specs/` und wird beim Start gegen `spec_schema.json` validiert; ein Tippfehler fällt damit sofort beim Laden auf und nicht still bei jedem Telegramm.
+
+[source,json]
+----
+{
+  "protocol_id": "900",
+  "model": "TEST_900",
+  "sensor_type": "Beispielgerät",
+  "prematch": "^12",
+  "crc": {
+    "algorithm": "crc8",
+    "data":  { "from": 0, "to": 5 },
+    "check": { "from": 6, "to": 7 }
+  },
+  "fields": {
+    "id":          { "source": "hex",  "from": 0,  "to": 1,  "type": "str" },
+    "channel":     { "source": "bits", "from": 17, "to": 19, "offset": 1 },
+    "temperature": { "source": "bits", "from": 22, "to": 31,
+                     "type": "float", "offset": -400, "scale": 0.1, "unit": "°C" }
+  },
+  "limits": { "temperature": [-40, 60] }
+}
+----
+
+Die Namen unter `fields` sind bewusst die FHEM-Readingnamen (`temperature`, `humidity`, `batteryState`, `channel`, ...). Sie sind über rund 150 Protokolle hinweg etabliert, machen den Paritätstest gegen die FHEM-Testvektoren zu einem direkten Vergleich und werden von den Ausgabeadaptern auf deren jeweilige Namen abgebildet.
+
+== Indizes
+
+`from` und `to` sind **nullbasiert und einschließlich** — `from: 18, to: 27` ist ein Zehn-Bit-Feld. Das entspricht `SD_WS_binaryToNumber($bitData, 18, 27)` in FHEM, sodass sich die Bitpositionen aus den Kommentaren der Perl-Module direkt übernehmen lassen.
+
+`source` wählt die Datenquelle:
+
+* `bits` — die demodulierte Bitfolge aus `metadata["bits"]`. Fehlt sie, etwa bei MN-Telegrammen, wird sie aus dem Hex-Payload erzeugt.
+* `hex` — die Zeichen des Hex-Payloads, ohne Präambel.
+
+== Rechenschritte eines Feldes
+
+Die Reihenfolge liegt fest und ist so gewählt, dass eine Regel sich liest wie die FHEM-Zeile, die sie ersetzt:
+
+. Bereich ausschneiden
+. `bcd` — als binär codierte Dezimalzahl lesen
+. `sign_bit` mit `sign_style` anwenden
+. `offset` addieren
+. `scale` multiplizieren
+. `round` auf Nachkommastellen kürzen
+. `map` — Rohwert über eine Wertetabelle abbilden
+. `derive` — abgeleiteten Wert berechnen
+
+[cols="1,3", options="header"]
+|===
+| Schlüssel | Bedeutung
+
+| `type`
+| `int` (Vorgabe), `float`, `str`, `bool`. `str` liefert den Rohausschnitt, solange die Regel keine Rechenoperation enthält — typisch für Sensor-IDs.
+
+| `sign_style`
+| `offset` zieht `sign_offset` ab (das FHEM-Idiom `wert - 1024`), `negate` kehrt das Vorzeichen um, `twos_complement` liest den Bereich im Zweierkomplement.
+
+| `sign_value`
+| Welcher Wert des Vorzeichenbits negativ bedeutet, Vorgabe `"1"`.
+
+| `map`
+| Bildet den Rohwert ab, z. B. `{"0": "ok", "1": "low"}` für den Batteriezustand.
+
+| `derive`
+| Abgeleiteter Wert, derzeit `wind_dir_text`. Mit `derive_from` rechnet die Regel auf einem bereits dekodierten Feld statt auf einem eigenen Bereich.
+
+| `unit`
+| Einheit, die im `SensorEvent` neben dem Wert geführt wird.
+|===
+
+== Prüfsummen
+
+`crc` verweist auf einen Algorithmus aus `signalduino/decoders/crc.py` und auf zwei Bereiche des Hex-Payloads: `data` ist der geprüfte Bereich, `check` die im Telegramm mitgesendete Prüfsumme. Beide Bereiche sind Zeichenindizes und müssen ganze Bytes umfassen.
+
+Verfügbar sind `crc8`, `crc16`, `crc16lsb`, `sum8`, `xor8`, `lfsr_digest8` und `lfsr_digest8_reflect`. Abweichende Parameter stehen unter `params`, etwa `{"poly": 49, "init": 255}`.
+
+Schlägt die Prüfung fehl, wird das Telegramm verworfen — es entsteht kein `SensorEvent`. Genauso wirkt eine Verletzung von `limits`; das entspricht dem Verhalten der FHEM-Module, die bei unplausiblen Werten ebenfalls nichts liefern.
+
+== Varianten
+
+Trägt ein Protokoll je nach Telegrammtyp unterschiedliche Felder, wählt `variant_selector` den passenden Block aus `variants` aus. Die Felder unter `fields` gelten für alle Varianten, der Variantenblock ergänzt und überschreibt sie; `model` und `sensor_type` lassen sich pro Variante anpassen.
+
+[source,json]
+----
+{
+  "variant_selector": { "source": "hex", "from": 0, "to": 1, "type": "str" },
+  "fields":   { "id": { "source": "hex", "from": 2, "to": 3, "type": "str" } },
+  "variants": {
+    "30": { "model": "SD_WS_125_TH", "fields": { "temperature": { "…": "…" } } },
+    "52": { "model": "SD_WS_125_T",  "fields": { "…": "…" } }
+  }
+}
+----
+
+== Der Ausnahmefall: ein Python-Decoder
+
+Lässt sich ein Protokoll nicht als Daten beschreiben — etwa weil Felder voneinander abhängen, die Prüfsumme über einen umsortierten Payload läuft oder der Modellname selbst aus den Daten entsteht — gehört es nach `signalduino/decoders/custom/`:
+
+[source,python]
+----
+from ..registry import register_decoder
+
+@register_decoder("115")
+def decode_bresser_5in1(message):
+    ...
+    return SensorEvent(...)
+----
+
+Ein solcher Decoder hat Vorrang vor einer gleichnamigen Spezifikation. Damit lässt sich ein Protokoll später von der einen Form in die andere überführen, ohne etwas zu löschen.
+
+== Routing
+
+Gefunden wird ein Decoder über die `protocol_id`, die in `DecodedMessage` bereits vorliegt. Die Felder aus `protocols.json` dienen dabei nur der Vorbereitung: `preamble` trennt den Hex-Teil ab, `modulematch` ist der Vorgabewert für `prematch`, und `clientmodule` gruppiert die Protokolle für Topics und Berichte.
+
+== Neues Protokoll hinzufügen
+
+. Bitlayout und Prüfsumme im zugehörigen FHEM-Client-Modul nachlesen, etwa in `14_SD_WS.pm`.
+. Spezifikation unter `signalduino/decoders/specs/` anlegen.
+. Testvektoren vorhanden? `tests/data/fhem/` enthält die FHEM-Vektoren samt erwarteter Readings; ergänzt werden sie mit `tools/fhem_testdata_import.py`.
+. Tests ausführen (siehe `AGENTS.md`, Abschnitt zur Testausführung im Devcontainer).
+
+Stufe 2 kann Stufe 1 nicht beschädigen: Jeder Fehler im Decoder führt zu `sensor = None`, während der bisherige Nachrichtenfluss unverändert weiterläuft.
@@ -3,7 +3,7 @@
 
 Dieser Abschnitt beschreibt die Architektur, wie man zur Entwicklung beitragen kann (Contributing) und wie man Tests durchführt.
 
-include::architecture.adoc[] include::contribution.adoc[]
+include::architecture.adoc[] include::contribution.adoc[] include::decoder_specs.adoc[]
 
 == Weitere Ressourcen
 
 
@@ -127,4 +127,6 @@ include::02_developer_guide/architecture.adoc[]
 
 include::02_developer_guide/contribution.adoc[]
 
+include::02_developer_guide/decoder_specs.adoc[]
+
 include::03_protocol_reference/protocol_details.adoc[]
@@ -0,0 +1,25 @@
+"""Sensor value decoding, the second stage of the receive chain (ADR-006).
+
+Stage 1, in signalduino/parser and sd_protocols, turns pulses into a payload.
+This package turns that payload into measurements: temperature, humidity,
+battery state, sensor id, channel.
+
+Most protocols are described declaratively in specs/*.json and evaluated by
+dsl.py; the irregular ones register a Python decoder in custom/. Either way
+the result is a SensorEvent, which the output adapters render into the FHEM,
+rtl_433 and Home Assistant formats.
+"""
+
+from .pipeline import DecodeError, SensorDecoder, decode_with_spec
+from .registry import DecoderRegistry, register_decoder
+from .spec import DecoderSpec, SpecError
+
+__all__ = [
+    "DecodeError",
+    "DecoderRegistry",
+    "DecoderSpec",
+    "SensorDecoder",
+    "SpecError",
+    "decode_with_spec",
+    "register_decoder",
+]
@@ -0,0 +1,147 @@
+"""Checksum algorithms used by the decoder specifications (ADR-006).
+
+FHEM implements its checks inside each client module, so the same CRC-8 turns
+up several times in slightly different spellings. Here they live once, as pure
+functions over bytes, addressed by name from a specification.
+
+Adding an algorithm means adding a function and one ALGORITHMS entry. Anything
+irregular enough that it cannot be expressed as "digest over a byte range,
+compared against another byte range" belongs in a custom decoder instead.
+"""
+
+from __future__ import annotations
+
+from typing import Callable
+
+ChecksumFunc = Callable[..., int]
+
+
+def _reflect(value: int, width: int) -> int:
+    """Reverses the bit order of ``value`` within ``width`` bits."""
+    result = 0
+    for _ in range(width):
+        result = (result << 1) | (value & 1)
+        value >>= 1
+    return result
+
+
+def crc8(data: bytes, poly: int = 0x31, init: int = 0x00,
+         reflect_in: bool = False, reflect_out: bool = False,
+         xor_out: int = 0x00) -> int:
+    """CRC-8 with configurable parameters.
+
+    The default is polynomial 0x31 with initial value 0, neither input nor
+    output reflected, which is what the Fine Offset and EuroChron sensors use
+    and what Digest::CRC produces for ``width => 8, poly => 0x31`` in FHEM.
+    """
+    crc = init
+    for byte in data:
+        if reflect_in:
+            byte = _reflect(byte, 8)
+        crc ^= byte
+        for _ in range(8):
+            crc = ((crc << 1) ^ poly) & 0xFF if crc & 0x80 else (crc << 1) & 0xFF
+    if reflect_out:
+        crc = _reflect(crc, 8)
+    return crc ^ xor_out
+
+
+def crc16(data: bytes, poly: int = 0x8005, init: int = 0xFFFF,
+          reflect_in: bool = False, reflect_out: bool = False,
+          xor_out: int = 0x0000) -> int:
+    """CRC-16 with configurable parameters."""
+    crc = init
+    for byte in data:
+        if reflect_in:
+            byte = _reflect(byte, 8)
+        crc ^= byte << 8
+        for _ in range(8):
+            crc = ((crc << 1) ^ poly) & 0xFFFF if crc & 0x8000 else (crc << 1) & 0xFFFF
+    if reflect_out:
+        crc = _reflect(crc, 16)
+    return crc ^ xor_out
+
+
+def crc16lsb(data: bytes, poly: int = 0x8810, init: int = 0x0000) -> int:
+    """CRC-16 processed least significant bit first.
+
+    Mirrors SD_WS_crc16lsb from 14_SD_WS.pm, used by several weather sensors.
+    """
+    crc = init
+    for byte in data:
+        crc ^= byte
+        for _ in range(8):
+            crc = (crc >> 1) ^ poly if crc & 1 else crc >> 1
+    return crc & 0xFFFF
+
+
+def sum8(data: bytes, init: int = 0x00) -> int:
+    """Sum of all bytes, truncated to 8 bits."""
+    return (init + sum(data)) & 0xFF
+
+
+def xor8(data: bytes, init: int = 0x00) -> int:
+    """XOR over all bytes."""
+    result = init
+    for byte in data:
+        result ^= byte
+    return result & 0xFF
+
+
+def lfsr_digest8(data: bytes, gen: int = 0x31, key: int = 0xF4) -> int:
+    """Galois LFSR digest, bits processed most significant first.
+
+    Mirrors the digest used by Bresser style sensors: for every set bit the
+    current key is XORed into the sum, and the key advances through the LFSR
+    on each bit.
+    """
+    result = 0
+    current = key
+    for byte in data:
+        for bit in range(7, -1, -1):
+            if (byte >> bit) & 1:
+                result ^= current
+            current = (current >> 1) ^ gen if current & 1 else current >> 1
+    return result & 0xFF
+
+
+def lfsr_digest8_reflect(data: bytes, gen: int = 0x31, key: int = 0xF4) -> int:
+    """Galois LFSR digest over the bytes in reverse order, bits least first.
+
+    Mirrors SD_WS_LFSR_digest8_reflect from 14_SD_WS.pm.
+    """
+    result = 0
+    current = key
+    for byte in reversed(data):
+        for bit in range(8):
+            if (byte >> bit) & 1:
+                result ^= current
+            current = ((current << 1) ^ gen) & 0xFF if current & 0x80 else (current << 1) & 0xFF
+    return result & 0xFF
+
+
+ALGORITHMS: dict[str, ChecksumFunc] = {
+    "crc8": crc8,
+    "crc16": crc16,
+    "crc16lsb": crc16lsb,
+    "sum8": sum8,
+    "xor8": xor8,
+    "lfsr_digest8": lfsr_digest8,
+    "lfsr_digest8_reflect": lfsr_digest8_reflect,
+}
+
+
+def compute(algorithm: str, data: bytes, **params) -> int:
+    """Runs a named algorithm over ``data``.
+
+    Raises:
+        KeyError: if the algorithm is unknown. Specifications are validated
+            against the schema, so this only happens for custom decoders.
+    """
+    try:
+        func = ALGORITHMS[algorithm]
+    except KeyError:
+        raise KeyError(
+            f"Unknown checksum algorithm '{algorithm}'. Known: {', '.join(sorted(ALGORITHMS))}"
+        ) from None
+    return func(data, **params)
@@ -0,0 +1,18 @@
+"""Python decoders for protocols a specification cannot express (ADR-006).
+
+A protocol belongs here when its fields depend on each other, when the
+checksum runs over a reordered payload, or when the model name itself is
+derived from the data. Everything else belongs in specs/*.json.
+
+A module in this package registers itself:
+
+    from ..registry import register_decoder
+
+    @register_decoder("115")
+    def decode_bresser_5in1(message):
+        ...
+        return SensorEvent(...)
+
+and is imported here so the registry picks it up. A custom decoder takes
+precedence over a specification with the same protocol id.
+"""